diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001127297210.png b/doc/best-practice/source/_static/images/en-us_image_0000001127297210.png new file mode 100644 index 0000000..9964a69 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001127297210.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001154597496.png b/doc/best-practice/source/_static/images/en-us_image_0000001154597496.png new file mode 100644 index 0000000..8550eb9 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001154597496.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001154645118.png b/doc/best-practice/source/_static/images/en-us_image_0000001154645118.png new file mode 100644 index 0000000..e852649 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001154645118.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001154760600.png b/doc/best-practice/source/_static/images/en-us_image_0000001154760600.png new file mode 100644 index 0000000..8d241be Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001154760600.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001154801774.png b/doc/best-practice/source/_static/images/en-us_image_0000001154801774.png new file mode 100644 index 0000000..edb0de0 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001154801774.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001154966988.png b/doc/best-practice/source/_static/images/en-us_image_0000001154966988.png new file mode 100644 index 0000000..e4d96f8 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001154966988.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001200534503.png b/doc/best-practice/source/_static/images/en-us_image_0000001200534503.png new file mode 100644 index 0000000..a1fca57 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001200534503.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001200577091.png b/doc/best-practice/source/_static/images/en-us_image_0000001200577091.png new file mode 100644 index 0000000..c1b1b10 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001200577091.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001200587685.png b/doc/best-practice/source/_static/images/en-us_image_0000001200587685.png new file mode 100644 index 0000000..38c4ad8 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001200587685.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001200681339.png b/doc/best-practice/source/_static/images/en-us_image_0000001200681339.png new file mode 100644 index 0000000..f4422f0 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001200681339.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001200802327.png b/doc/best-practice/source/_static/images/en-us_image_0000001200802327.png new file mode 100644 index 0000000..71e9c74 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001200802327.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001201043047.png b/doc/best-practice/source/_static/images/en-us_image_0000001201043047.png new file mode 100644 index 0000000..ed6ab27 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001201043047.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001361665969.png b/doc/best-practice/source/_static/images/en-us_image_0000001361665969.png new file mode 100644 index 0000000..cdea09f Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001361665969.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001400827629.png b/doc/best-practice/source/_static/images/en-us_image_0000001400827629.png new file mode 100644 index 0000000..b210b73 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001400827629.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001418569120.png b/doc/best-practice/source/_static/images/en-us_image_0000001418569120.png new file mode 100644 index 0000000..2dc55c4 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001418569120.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001418729104.png b/doc/best-practice/source/_static/images/en-us_image_0000001418729104.png new file mode 100644 index 0000000..a132dc5 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001418729104.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001468885853.png b/doc/best-practice/source/_static/images/en-us_image_0000001468885853.png new file mode 100644 index 0000000..d2ea735 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001468885853.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001469005545.png b/doc/best-practice/source/_static/images/en-us_image_0000001469005545.png new file mode 100644 index 0000000..d23cff7 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001469005545.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001507528236.png b/doc/best-practice/source/_static/images/en-us_image_0000001507528236.png new file mode 100644 index 0000000..8604d14 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001507528236.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001507688112.png b/doc/best-practice/source/_static/images/en-us_image_0000001507688112.png new file mode 100644 index 0000000..070e8b2 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001507688112.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001539405909.png b/doc/best-practice/source/_static/images/en-us_image_0000001539405909.png new file mode 100644 index 0000000..cff5507 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001539405909.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001539605245.png b/doc/best-practice/source/_static/images/en-us_image_0000001539605245.png new file mode 100644 index 0000000..8bbf3cc Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001539605245.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0000001558527697.png b/doc/best-practice/source/_static/images/en-us_image_0000001558527697.png new file mode 100644 index 0000000..2bc934f Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0000001558527697.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0143894038.png b/doc/best-practice/source/_static/images/en-us_image_0143894038.png new file mode 100644 index 0000000..603c946 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0143894038.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0165153802.png b/doc/best-practice/source/_static/images/en-us_image_0165153802.png new file mode 100644 index 0000000..e855272 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0165153802.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0165153805.png b/doc/best-practice/source/_static/images/en-us_image_0165153805.png new file mode 100644 index 0000000..a33c060 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0165153805.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0165729699.png b/doc/best-practice/source/_static/images/en-us_image_0165729699.png new file mode 100644 index 0000000..4378879 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0165729699.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0168961239.png b/doc/best-practice/source/_static/images/en-us_image_0168961239.png new file mode 100644 index 0000000..603c946 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0168961239.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0195122694.png b/doc/best-practice/source/_static/images/en-us_image_0195122694.png new file mode 100644 index 0000000..edb0de0 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0195122694.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0196304259.png b/doc/best-practice/source/_static/images/en-us_image_0196304259.png new file mode 100644 index 0000000..8b5e37b Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0196304259.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0282767856.png b/doc/best-practice/source/_static/images/en-us_image_0282767856.png new file mode 100644 index 0000000..069c98a Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0282767856.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0294353976.png b/doc/best-practice/source/_static/images/en-us_image_0294353976.png new file mode 100644 index 0000000..fee8364 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0294353976.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0294800819.png b/doc/best-practice/source/_static/images/en-us_image_0294800819.png new file mode 100644 index 0000000..a132dc5 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0294800819.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0294804326.png b/doc/best-practice/source/_static/images/en-us_image_0294804326.png new file mode 100644 index 0000000..d2ea735 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0294804326.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0294810557.png b/doc/best-practice/source/_static/images/en-us_image_0294810557.png new file mode 100644 index 0000000..d2ea735 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0294810557.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0294810558.png b/doc/best-practice/source/_static/images/en-us_image_0294810558.png new file mode 100644 index 0000000..f5da59a Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0294810558.png differ diff --git a/doc/best-practice/source/_static/images/en-us_image_0294810559.png b/doc/best-practice/source/_static/images/en-us_image_0294810559.png new file mode 100644 index 0000000..a132dc5 Binary files /dev/null and b/doc/best-practice/source/_static/images/en-us_image_0294810559.png differ diff --git a/doc/best-practice/source/basics_of_the_container_engine.rst b/doc/best-practice/source/basics_of_the_container_engine.rst new file mode 100644 index 0000000..a8e83e1 --- /dev/null +++ b/doc/best-practice/source/basics_of_the_container_engine.rst @@ -0,0 +1,134 @@ +:original_name: swr_01_0006.html + +.. _swr_01_0006: + +Basics of the Container Engine +============================== + +The container engine, namely, Docker, is an open-source engine which allows you to create a lightweight, portable, and self-sufficient container for any application. SWR is compatible with Docker, allowing you to use Docker CLI and APIs to manage your images. + +Installing Docker +----------------- + +Before installing Docker, get a basic understanding of what Docker is and how it works. For more information, see `Docker Documentation `__. + +Docker is compatible with almost all operating systems. Select a Docker version that best suits your needs. If you are not sure which Docker community edition to use, see https://docs.docker.com/engine/install/. + +.. note:: + + - Before using SWR to store container images, ensure that the Docker client used to push images to SWR is updated to 1.11.2 or later. + - Bind an elastic IP address first if your server runs in a private network as the installation requires Internet connection. + +On a device running Linux, run the following commands to quickly install Docker: + +.. code-block:: + + curl -fsSL get.docker.com -o get-docker.sh + sh get-docker.sh + sudo systemctl daemon-reload + sudo systemctl restart docker + +Building a Container Image +-------------------------- + +This section walks you through the steps of using a Dockerfile to build a container image for a simple web application. Dockerfile is a text file that contains all the instructions a user can call on the command line to build an image. A container image is a stack consisting of multiple layers. Each instruction creates a layer. + +When using a browser to access a containerized application built from a Nginx image, you will see the default Nginx welcome page. In this section, you will build a new image based on the Nginx image to change the welcome message to **Hello, SWR!** + +#. Log in to the device running Docker as a root user. + +#. Run the following commands to create an empty file named **Dockerfile**: + + **mkdir mynginx** + + **cd mynginx** + + **touch Dockerfile** + +#. Edit Dockerfile. + + **vim Dockerfile** + + Add the following instructions to the Dockerfile: + + .. code-block:: + + FROM nginx + RUN echo '

Hello,SWR!

' > /usr/share/nginx/html/index.html + + In the preceding instructions: + + - **FROM**: creates a layer from the base image. A valid Dockerfile must start with a **FROM** instruction. In this example, the **Nginx** image is used as the base image. + - **RUN**: executes a command to create a new layer. One of its syntax forms is RUN . In this example, the **echo** command is executed to display **Hello, SWR!** + + Save the changes and exit. + +#. Run **docker build** [*option*] <*context path*> to build an image. + + **docker build -t nginx:v1 .** + + - **-t nginx:v1**: specifies the image name and tag. + - **.**: indicates the path where the Dockerfile is located. All contents in this path are packed and sent to the Docker to build an image. + +#. Run the following command to check the created image. The command output shows that the nginx image has been created with a tag of v1. + + **docker images** + +Creating an Image Package +------------------------- + +This section describes how to compress a container image into a .tar or .tar.gz package. + +#. Log in to the device running Docker as a root user. + +#. Run the following command to list images. + + **docker images** + + Check the name and tag of the image to be compressed. + +#. Run the following command to compress the image into a package. + + **docker save [OPTIONS] IMAGE [IMAGE...]** + + .. note:: + + **OPTIONS**: You can set this to **--output** or **-o**, indicating that the image is exported to a file. + + The file should be in either .tar or .tar.gz. + + Sample: + + .. code-block:: + + $ docker save nginx:latest > nginx.tar + $ ls -sh nginx.tar + 108M nginx.tar + + $ docker save php:5-apache > php.tar.gz + $ ls -sh php.tar.gz + 372M php.tar.gz + + $ docker save --output nginx.tar nginx + $ ls -sh nginx.tar + 108M nginx.tar + + $ docker save -o nginx-all.tar nginx + $ docker save -o nginx-latest.tar nginx:latest + +Importing an Image File +----------------------- + +This section describes how to import an image package as an image using the **docker load** command. + +There are two modes: + +**docker load <** **Path/File name.tar** + +**docker load --input** **Path/File name.tar** or **docker load -i** **Path/File name.tar** + +Sample: + +.. code-block:: + + $ docker load --input fedora.tar diff --git a/doc/best-practice/source/best_practices/index.rst b/doc/best-practice/source/best_practices/index.rst new file mode 100644 index 0000000..4557798 --- /dev/null +++ b/doc/best-practice/source/best_practices/index.rst @@ -0,0 +1,14 @@ +:original_name: swr_bp_index.html + +.. _swr_bp_index: + +Best Practices +============== + +- :ref:`Migrating Container Images ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + migrating_container_images/index diff --git a/doc/best-practice/source/best_practices/migrating_container_images/index.rst b/doc/best-practice/source/best_practices/migrating_container_images/index.rst new file mode 100644 index 0000000..e1aa65c --- /dev/null +++ b/doc/best-practice/source/best_practices/migrating_container_images/index.rst @@ -0,0 +1,18 @@ +:original_name: swr_bestpractice_0016.html + +.. _swr_bestpractice_0016: + +Migrating Container Images +========================== + +- :ref:`Migrating Images to SWR Using Docker Commands ` +- :ref:`Migrating Images to SWR Using image-syncer ` +- :ref:`Synchronizing Images Across Clouds from Harbor to SWR ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + migrating_images_to_swr_using_docker_commands + migrating_images_to_swr_using_image-syncer + synchronizing_images_across_clouds_from_harbor_to_swr diff --git a/doc/best-practice/source/best_practices/migrating_container_images/migrating_images_to_swr_using_docker_commands.rst b/doc/best-practice/source/best_practices/migrating_container_images/migrating_images_to_swr_using_docker_commands.rst new file mode 100644 index 0000000..2b34f76 --- /dev/null +++ b/doc/best-practice/source/best_practices/migrating_container_images/migrating_images_to_swr_using_docker_commands.rst @@ -0,0 +1,65 @@ +:original_name: swr_bestpractice_0012.html + +.. _swr_bestpractice_0012: + +Migrating Images to SWR Using Docker Commands +============================================= + +Scenarios +--------- + +SWR provides easy-to-use image hosting and efficient distribution services. If small quantity of images need to be migrated, enterprises can use the **docker pull/push** command to migrate images to SWR. + +Procedure +--------- + +#. .. _swr_bestpractice_0012__en-us_topic_0000001281347382_en-us_topic_0000001262401516_li13905204219362: + + Pull images from the source repository. + + Run the **docker pull** command to pull the images. + + Example: **docker pull nginx:latest** + + Run the **docker images** command to check whether the images are successfully pulled. + + .. code-block:: + + # docker images + REPOSITORY TAG IMAGE ID CREATED SIZE + nginx latest 22f2bf2e2b4f 5 hours ago 22.8MB + +#. Push the images pulled in :ref:`1 ` to SWR. + + a. Log in to the VM where the target container is located and log in to SWR. For details, see `Uploading an Image Through a Container Engine Client `__. + + b. Tag the images. + + **docker tag** **[Image name:Tag name] [Image repository address]/[Organization name]/[Image name:Tag name]** + + Example: + + **docker tag nginx:v1 swr.eu-de.otc.t-systems.com/cloud-develop/nginx:v1** + + c. Run the following command to push the images to the target image repository. + + **docker push** **[Image repository address]/[Organization name]/[Image name:Tag name]** + + Example: + + **docker push swr.eu-de.otc.t-systems.com/cloud-develop/nginx:v1** + + d. Check whether the following information is returned. If yes, the push is successful. + + .. code-block:: + + fbce26647e70: Pushed + fb04ab8effa8: Pushed + 8f736d52032f: Pushed + 009f1d338b57: Pushed + 678bbd796838: Pushed + d1279c519351: Pushed + f68ef921efae: Pushed + v1: digest: sha256:0cdfc7910db531bfa7726de4c19ec556bc9190aad9bd3de93787e8bce3385f8d size: 1780 + + To view the pushed image, refresh the **My Images** page. diff --git a/doc/best-practice/source/best_practices/migrating_container_images/migrating_images_to_swr_using_image-syncer.rst b/doc/best-practice/source/best_practices/migrating_container_images/migrating_images_to_swr_using_image-syncer.rst new file mode 100644 index 0000000..247bdd9 --- /dev/null +++ b/doc/best-practice/source/best_practices/migrating_container_images/migrating_images_to_swr_using_image-syncer.rst @@ -0,0 +1,100 @@ +:original_name: swr_bestpractice_0015.html + +.. _swr_bestpractice_0015: + +Migrating Images to SWR Using image-syncer +========================================== + +Scenarios +--------- + +If small quantity of images need to be migrated, you can use Docker commands. However, for thousands of images and several TBs of image repository data, it takes a long time and even data may be lost. In this case, you can use the open-source image migration tool `image-syncer `__. + +Procedure +--------- + +#. Download, decompress, and run image-syncer. + + The following uses image-syncer v1.3.1 as an example. + + **wget https://github.com/AliyunContainerService/image-syncer/releases/download/v1.3.1/image-syncer-v1.3.1-linux-amd64.tar.gz** + + **tar -zvxf image-syncer-v1.3.1-linux-amd64.tar.gz** + +#. Create **auth.json**, the authentication information file of the image repositories. + + image-syncer supports the Docker image repository based on Docker Registry V2. Enter the authentication information as required. In the following example, the image repository of eu-de is migrated to eu-nl. + + The following describes how to write the authentication information of the source and target repositories. + + .. code-block:: + + { + "swr.eu-de.otc.t-systems.com": { + "username": "eu-de_otc@F1I3Q......", + "password": "2fd4c969ea0......" + }, + "swr.eu-nl.otc.t-systems.com": { + "username": "eu-nl_otc@4N3FA......", + "password": "f1c82b57855f9d35......" + } + } + + In the preceding commands, **swr.eu-de.otc.t-systems.com** indicates the image repository address. You can obtain the username and password from the login command as follows: + + Log in to the SWR console, and click **Generate Login Command** in the upper right corner to obtain the login command in the dialog box displayed, as shown in the following figure. + + .. _swr_bestpractice_0015__en-us_topic_0000001262561396_fig27182115592: + + .. figure:: /_static/images/en-us_image_0000001400827629.png + :alt: **Figure 1** Generating a login command + + **Figure 1** Generating a login command + + In :ref:`the above figure `, **eu-de_otc@9LA......** is the username; + + **077be..............** is the password; + + **swr.eu-de.otc.t-systems.com** is the image repository address. + + .. caution:: + + For security, the example username and password are random. You should use the actual username and password obtained from the console. + +#. Create **images.json**, the image synchronization description file. + + In the following example, the source repository address is on the left, and the target repository address is on the right. image-syncer also supports other description modes. For details, see `README.md `__. + + .. code-block:: + + { + "swr.eu-de.otc.t-systems.com/org-ss/canary-consumer": "swr.eu-nl.otc.t-systems.com/dev-container/canary-consumer" + } + +#. Run the following command to migrate the images to SWR: + + **./image-syncer --auth=./auth.json --images=./images.json --namespace=dev-container --registry=swr.eu-de.otc.t-systems.com --retries=3 --log=./log** + + .. table:: **Table 1** Command parameter description + + +-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Parameter | Description | + +=============+=================================================================================================================================================================================================================================================================================+ + | --config | Sets the path of config file. This file needs to be created before starting synchronization. Default config file is at "current/working/directory/config.json". (This flag can be replaced with flag **--auth** and **--images** which for better organization.) | + +-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | --images | Sets the path of image rules file. This file needs to be created before starting synchronization. Default config file is at "current/working/directory/images.json". | + +-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | --auth | Sets the path of authentication file. This file needs to be created before starting synchronization. Default config file is at "current/working/directory/auth.json". | + +-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | --log | Sets the path of log file. Logs will be printed to Stderr by default. | + +-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | --namespace | Sets default-namespace. default-namespace can also be set by environment variable **DEFAULT_NAMESPACE**. If they are both set at the same time, **DEFAULT_NAMESPACE** will not work at this synchronization. default-namespace will work only if default-registry is not empty. | + +-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | --proc | Number of goroutines. Default value is 5. | + +-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | --retries | Number of retries. Default value is 2. The retries of failed sync tasks will start after all sync tasks are executed once. Reties of failed sync tasks will resolve most occasional network problems during synchronization. | + +-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | --registry | Sets default-registry. Default-registry can also be set by environment variable **DEFAULT_REGISTRY**. If they are both set at the same time, **DEFAULT_REGISTRY** will not work at this synchronization. default-registry will work only if default-namespace is not empty. | + +-------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + + After the migration command is executed, you can log in to the target image repository to view the migrated images. diff --git a/doc/best-practice/source/best_practices/migrating_container_images/synchronizing_images_across_clouds_from_harbor_to_swr.rst b/doc/best-practice/source/best_practices/migrating_container_images/synchronizing_images_across_clouds_from_harbor_to_swr.rst new file mode 100644 index 0000000..2506115 --- /dev/null +++ b/doc/best-practice/source/best_practices/migrating_container_images/synchronizing_images_across_clouds_from_harbor_to_swr.rst @@ -0,0 +1,88 @@ +:original_name: cce_bestpractice_0332.html + +.. _swr_bestpractice_0004: + +Synchronizing Images Across Clouds from Harbor to SWR +===================================================== + +Scenarios +--------- + +Harbor accesses SWR through a public network. For details, see :ref:`Accessing SWR Through a Public Network `. + +Background +---------- + +Harbor is an open-source enterprise-class Docker Registry server developed by VMware. It extends the Docker Distribution by adding the functionalities such as role-based access control (RBAC), image scanning, and image replication. Harbor has been widely used to store and distribute container images. + +.. _swr_bestpractice_0004__en-us_topic_0291248669_section176591736173817: + +Accessing SWR Through a Public Network +-------------------------------------- + +#. .. _swr_bestpractice_0004__en-us_topic_0291248669_li137017409395: + + Configure a registry endpoint on Harbor. + + .. note:: + + Open Telekom Cloud SWR has not yet integrated with Harbor. You need clone `this repo `__ and build it from branch **opentelekomcloud_adapter**. + + + .. TODO: version of Harbor which supports OTC adaptor + + .. .. note:: + + .. Open Telekom Cloud SWR has integrated with Harbor 1.10.5 and later versions. You only need to set **Provider** to **Open Telekom Cloud SWR** when configuring your endpoint. This document uses Harbor 2.4.1 as an example. + + a. Add an endpoint. + + |image1| + + b. Configure the following parameters. + + |image2| + + - **Provider**: Select **Open Telekom Cloud SWR**. + - **Name**: Enter a customized name. + - **Endpoint URL**: Enter the public network domain name of SWR in the format of **https://{SWR image repository address}**. To obtain the image repository address, log in to the SWR console, choose **My Images**, and click **Upload Through Client**. You can view the image repository address of the current region on the page that is displayed. + - **Access ID**: Enter an access ID in the format of **Regional project name@[AK]**. + - Access Secret: Enter an AK/SK. To obtain an AK/SK, see `Obtaining a Long-Term Valid Login Command `__. + - **Verify Remote Cert**: **Deselect** the option. + +#. Configure a replication rule. + + a. Create a replication rule. + + |image3| + + b. Configure the following parameters. + + - **Name**: Enter a customized name. + + - **Replication mode**: Select **Push-based**, indicating that images are pushed from the local Harbor to the remote repository. + + - **Source resource filter**: Filters images on Harbor based on the configured rules. + + - **Destination registry**: Select the endpoint created in :ref:`1 `. + + - **Destination** + + **Namespace**: Enter the organization name on SWR. + + **Flattening**: Select **Flatten All Levels**, indicating that the hierarchy of the registry is reduced when copying images. If the directory of Harbor registry is **library/nginx** and the directory of the endpoint namespace is **dev-container**, after you flatten all levels, the directory of the endpoint namespace is **library/nginx -> dev-container/nginx**. + + - **Trigger Mode**: Select **Manual**. + + - **Bandwidth**: Set the maximum network bandwidth when executing the replication rule. The value **-1** indicates no limitation. + +#. After creating the replication rule, select it and click **REPLICATE** to complete the replication. + + |image4| + + + +.. |image1| image:: /_static/images/en-us_image_0000001469005545.png +.. |image2| image:: /_static/images/en-us_image_0000001418569120.png +.. |image3| image:: /_static/images/en-us_image_0000001468885853.png +.. |image4| image:: /_static/images/en-us_image_0000001418729104.png \ No newline at end of file diff --git a/doc/best-practice/source/change_history.rst b/doc/best-practice/source/change_history.rst new file mode 100644 index 0000000..3d688b9 --- /dev/null +++ b/doc/best-practice/source/change_history.rst @@ -0,0 +1,25 @@ +:original_name: swr_change_index.html + +.. _swr_change_index: + +Change History +============== + ++-----------------------------------+-------------------------------------------------------------------------------------------------------+ +| Release Date | Description | ++===================================+=======================================================================================================+ +| 2022-06-09 | Permission description is added in :ref:`User Permissions `. | ++-----------------------------------+-------------------------------------------------------------------------------------------------------+ +| 2021-08-30 | :ref:`Service Overview `, :ref:`FAQs ` is added. | ++-----------------------------------+-------------------------------------------------------------------------------------------------------+ +| 2020-06-18 | - Prerequisites in :ref:`Uploading an Image Through the Client ` are updated. | +| | - Content related to organization deletion is added in :ref:`Organization Management `. | ++-----------------------------------+-------------------------------------------------------------------------------------------------------+ +| 2020-05-26 | Updated: | +| | | +| | - :ref:`Basics of the Container Engine ` | +| | - :ref:`Uploading an Image Through the Client ` | +| | - :ref:`User Permissions ` | ++-----------------------------------+-------------------------------------------------------------------------------------------------------+ +| 2020-04-21 | This issue is the first official release. | ++-----------------------------------+-------------------------------------------------------------------------------------------------------+ diff --git a/doc/best-practice/source/faqs/general_faqs/about_swr.rst b/doc/best-practice/source/faqs/general_faqs/about_swr.rst new file mode 100644 index 0000000..854c504 --- /dev/null +++ b/doc/best-practice/source/faqs/general_faqs/about_swr.rst @@ -0,0 +1,36 @@ +:original_name: swr_faq_0013.html + +.. _swr_faq_0013: + +About SWR +========= + +How Many Images Can Be Stored in SWR? +------------------------------------- + +SWR has no limit on the number of images. You can upload any number of images. + +What Is the Bandwidth of SWR? +----------------------------- + +The bandwidth of SWR dynamically changes based on actual usage. + +Is SWR Charged? +--------------- + +The billing items of SWR include storage space and traffic. Currently, it is free of charge. + +Does SWR Support Querying the CPU Architecture (x86 or Arm) of an Image? +------------------------------------------------------------------------ + +- For a public image, you can log in to the SWR console, go to the image center, search for the target image, and view its details, including the architectures supported by the image. + +- For a private image, you can Run **docker inspect** **[Image name:Version name]** to query the image architecture. + +*Example:* **docker inspect openjdk:7**\ *.* + + +.. figure:: /_static/images/en-us_image_0000001539405909.png + :alt: **Figure 1** Example + + **Figure 1** Example diff --git a/doc/best-practice/source/faqs/general_faqs/are_there_quotas_for_swr_resources.rst b/doc/best-practice/source/faqs/general_faqs/are_there_quotas_for_swr_resources.rst new file mode 100644 index 0000000..f7bebdb --- /dev/null +++ b/doc/best-practice/source/faqs/general_faqs/are_there_quotas_for_swr_resources.rst @@ -0,0 +1,20 @@ +:original_name: en-us_topic_0000001539549873.html + +.. _en-us_topic_0000001539549873: + +Are There Quotas for SWR Resources? +=================================== + +No quotas are imposed on SWR images. You can push as many images as you need. + +Quotas are imposed on the number of organizations a user can create, as shown in :ref:`Table 1 `. + +.. _en-us_topic_0000001539549873__table88365720443: + +.. table:: **Table 1** SWR resource quotas + + ============= ===== + Resource Type Quota + ============= ===== + Organization 5 + ============= ===== diff --git a/doc/best-practice/source/faqs/general_faqs/how_do_i_create_a_container_image.rst b/doc/best-practice/source/faqs/general_faqs/how_do_i_create_a_container_image.rst new file mode 100644 index 0000000..09dc348 --- /dev/null +++ b/doc/best-practice/source/faqs/general_faqs/how_do_i_create_a_container_image.rst @@ -0,0 +1,209 @@ +:original_name: swr_faq_0012.html + +.. _swr_faq_0012: + +How Do I Create a Container Image? +================================== + +The following two approaches are for you to consider. Approach 1 is for images that will only be updated occasionally whereas approach 2 is for images that will be frequently updated. + +- Approach 1: creating a snapshot. This approach involves three key steps: (1) Start a base container by running a base image (for example, Ubuntu image); (2) install the container engine software inside the base container; (3) create a snapshot of the container. +- Approach 2: creating a Dockerfile to build an image. This approach involves two key steps: (1) Write software installation instructions into a Dockerfile; (2) run the **docker build** command to build an image from the Dockerfile. + +.. _swr_faq_0012__section1017412550210: + +Approach 1: Creating a Snapshot +------------------------------- + +This approach is suitable for images that will only be updated occasionally. + + +.. figure:: /_static/images/en-us_image_0165153802.png + :alt: **Figure 1** Creating a snapshot + + **Figure 1** Creating a snapshot + +Procedure: + +#. Install the container engine software on a host. + +#. .. _swr_faq_0012__li118181720511: + + Start an empty base container in the interactive mode. + + For example, start a CentOS container in the interactive mode. + + **docker run -it centos** + +#. Run the following commands to install the target software: + + **yum install XXX** + + **git clone https://github.com/lh3/bwa.git** + + **cd bwa;make** + + .. note:: + + Install Git in advance and check whether an SSH key is set on the local host. + +#. Run the **exit** command to exit the container. + +5. Create a snapshot. + + **docker commit -m "xx" -a "test" container-id test/image:tag** + + - **-a**: indicates the author of the base image. + - **container-id**: indicates the ID of the container you have started in step :ref:`2 `. You can run the **docker ps -a** command to query the container ID. + - **-m**: indicates the commit message. + - **test/image:tag**: indicates the repository name/image name:tag name. + +6. Run the **docker images** command to list the built container image. + +.. _swr_faq_0012__section1690134131216: + +Approach 2: Creating a Dockerfile to Build an Image +--------------------------------------------------- + +This approach is suitable for images that will be frequently updated. In :ref:`Approach 1 `, you create a snapshot of the whole container. This could be demanding if you need to frequently update your images. In this case, :ref:`Approach 2 ` is put forward to automate the image build process. + +The idea behind :ref:`Approach 2 ` is to write the process of :ref:`Approach 1 ` into a Dockerfile and then run the **docker build -t test/image:tag.** command to automatically build an image from the Dockerfile. In the preceding command, **.** indicates the path to the Dockerfile. + + +.. figure:: /_static/images/en-us_image_0165153805.png + :alt: **Figure 2** Creating a Dockerfile to build an image + + **Figure 2** Creating a Dockerfile to build an image + +Example Dockerfile: + +.. note:: + + If an external network is required, ensure that network connectivity is available. + +.. code-block:: + + #Version 1.0.1 + FROM centos:latest + + # Setting the root user as the executor of subsequent commands + USER root + + # Performing operations + RUN yum update -y + RUN yum install -y java + + # Using && to concatenate commands + RUN touch test.txt && echo "abc" >>abc.txt + + # Setting an externally exposed port + EXPOSE 80 8080 1038 + + # Adding a network file + ADD https://www.baidu.com/img/bd_logo1.png /opt/ + + # Setting an environment variable + ENV WEBAPP_PORT=9090 + + # Setting a work directory + WORKDIR /opt/ + + # Setting a start command + ENTRYPOINT ["ls"] + + # Setting start parameters + CMD ["-a", "-l"] + + # Setting a volume + VOLUME ["/data", "/var/www"] + + # Setting the trigger operation for a sub-image + ONBUILD ADD . /app/src + ONBUILD RUN echo "on build excuted" >> onbuild.txt + +Basic Syntax of Dockerfile +-------------------------- + +- FROM: + + It is used to specify the parent image (base image) from which you are building a new image. Except annotations, a Dockerfile must start with a FROM instruction. Subsequent instructions run in this parent image environment until the next FROM instruction appears. You can create multiple images in the same Dockerfile by adding multiple FROM instructions. + +- MAINTAINER: + + It is used to specify the information about the author who creates an image, including the username and email address. This parameter is optional. + +- RUN: + + It is used to modify an image. Generally, RUN commands are executed to install libraries, and install and configure programs. After a RUN command is executed, an image layer will be created on the current image. The next command will be executed on the new image. The RUN statement can be in one of the following formats: + + - **RUN yum update**: Command that is executed in the **/bin/sh** directory. + - **RUN ["yum", "update"]**: Directly invoke **exec**. + - **RUN yum update && yum install nginx**: Use **&&** to connect multiple commands to a RUN statement. + +- EXPOSE: + + It is used to specify one or more network ports that will be exposed on a container. If there are multiple ports, separate them by spaces. + + When running a container, you can set **-P** (uppercase) to map the ports specified in EXPOSE to random ports on a host. Other containers or hosts can communicate with the container through the ports on the host. + + You can also use **-p** (lowercase) to expose the ports that are not listed in EXPOSE. + +- ADD: + + It is used to add a file to a new image. The file can be a host file, a network file, or a folder. + + - First parameter: source file (folder) + + - If a relative path is used, this path must correspond to the directory where the Dockerfile is located. + - If a URL is used, the file needs to be downloaded first and then added to the image. + + - Second parameter: target path + + - If the source file is in the .zip or .tar file, the container engine decompresses the file and then adds it to the specified location of the image. + - If the source file is a compressed network file specified by a URL, the file will not be decompressed. + +- VOLUME: + + It is used to create a mount point for a specified path (file or folder) in the image. Multiple containers can share data through the same mount point. Even if one of the containers is stopped, the mount point can still be accessed. + +- WORKDIR: + + It is used to specify a new work directory for the next command. The directory can be an absolute or a relative directory. WORKDIR can be specified multiple times as required. When a container is started, the directory specified by the last WORKDIR command is used as the current work directory of the container. + +- ENV: + + It is used to set an environment variable for running the container. When running the container, you can set **-e** to modify the environment variable or add other environment variables. + + Example: + + **docker run -e WEBAPP_PORT=8000 -e WEBAPP_HOST=www.example.com ...** + +- CMD: + + It is used to specify the default command for starting a container. + +- ENTRYPOINT: + + It is used to specify the default command for starting a container. Difference: For ENTRYPOINT, parameters added to the image during container running will be spliced. For CMD, these parameters will be overwritten. + + - If the Dockerfile specifies that the default command for starting a container is **ls -l**, the default command **ls -l** will be run accordingly. For example: + + - **ENTRYPOINT [ "ls", "-l"]**: The program and parameter for starting a container are set to be **ls** and **-l** respectively. + - **docker run centos**: The **docker run centos ls -l** command is run by default for starting a CentOS container. + - **docker run centos -a**: When the **-a** parameter is added for starting a CentOS container, the **docker run centos ls -l -a** command is run by default. + + - If the Dockerfile specifies that the default command for starting a container is **--entrypoint** but you need to replace the default command, you can add **--entrypoint** parameters to replace the configuration specified in Dockerfile. Example: + + **docker run gutianlangyu/test --entrypoint echo "hello world"** + +- USER: + + It is used to specify the user or UID for running the container, and running the RUN, CMD, or ENTRYPOINT command. + +- ONBUILD: + + Trigger command. During image build, the image builder of the container engine saves all commands specified by the ONBUILD command to the image metadata. These commands will not be executed in the process of building the current image. These commands will be executed only when a new image uses the FROM instruction to specify the parent image as the current image. + + Using the FROM instruction to build a child image based on the parent image created by the Dockerfile: + + **ONBUILD ADD. /app/src**: The **ADD. /app/src** command is automatically executed. diff --git a/doc/best-practice/source/faqs/general_faqs/how_do_i_create_an_image_package.rst b/doc/best-practice/source/faqs/general_faqs/how_do_i_create_an_image_package.rst new file mode 100644 index 0000000..d084462 --- /dev/null +++ b/doc/best-practice/source/faqs/general_faqs/how_do_i_create_an_image_package.rst @@ -0,0 +1,31 @@ +:original_name: swr_faq_0004.html + +.. _swr_faq_0004: + +How Do I Create an Image Package? +================================= + +Run the **docker save** command to compress the container image into a .tar or .tar.gz package. The command format is as follows: + +**docker save [OPTIONS] IMAGE [IMAGE...]** + +**[OPTIONS]** can be set to **--output** or **-o**, indicating that the image is exported to a file. + +Example: + +.. code-block:: + + $ docker save nginx:latest > nginx.tar + $ ls -sh nginx.tar + 108M nginx.tar + + $ docker save php:5-apache > php.tar.gz + $ ls -sh php.tar.gz + 372M php.tar.gz + + $ docker save --output nginx.tar nginx + $ ls -sh nginx.tar + 108M nginx.tar + + $ docker save -o nginx-all.tar nginx + $ docker save -o nginx-latest.tar nginx:latest diff --git a/doc/best-practice/source/faqs/general_faqs/index.rst b/doc/best-practice/source/faqs/general_faqs/index.rst new file mode 100644 index 0000000..b3cb291 --- /dev/null +++ b/doc/best-practice/source/faqs/general_faqs/index.rst @@ -0,0 +1,24 @@ +:original_name: swr_faq_1001.html + +.. _swr_faq_1001: + +General FAQs +============ + +- :ref:`What Is SWR? ` +- :ref:`About SWR ` +- :ref:`How Do I Create a Container Image? ` +- :ref:`How Do I Create an Image Package? ` +- :ref:`Are There Quotas for SWR Resources? ` +- :ref:`Why Does Organization Creation Fail? ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + what_is_swr + about_swr + how_do_i_create_a_container_image + how_do_i_create_an_image_package + are_there_quotas_for_swr_resources + why_does_organization_creation_fail diff --git a/doc/best-practice/source/faqs/general_faqs/what_is_swr.rst b/doc/best-practice/source/faqs/general_faqs/what_is_swr.rst new file mode 100644 index 0000000..1b75ea9 --- /dev/null +++ b/doc/best-practice/source/faqs/general_faqs/what_is_swr.rst @@ -0,0 +1,8 @@ +:original_name: swr_faq_1011.html + +.. _swr_faq_1011: + +What Is SWR? +============ + +SoftWare Repository for Container (SWR) allows users to easily manage the full lifecycle of container images and facilitates secure deployment of images for your applications. diff --git a/doc/best-practice/source/faqs/general_faqs/why_does_organization_creation_fail.rst b/doc/best-practice/source/faqs/general_faqs/why_does_organization_creation_fail.rst new file mode 100644 index 0000000..c4d5a47 --- /dev/null +++ b/doc/best-practice/source/faqs/general_faqs/why_does_organization_creation_fail.rst @@ -0,0 +1,12 @@ +:original_name: en-us_topic_0000001488470084.html + +.. _en-us_topic_0000001488470084: + +Why Does Organization Creation Fail? +==================================== + +Symptom: The creation of an organization fails, and a message is displayed indicating that the organization already exists. However, the organization is not found on the **Organizations** page. + +Solution: Change the organization name to one which is globally unique in the Region. + +If a message is displayed indicating that the organization already exists, the organization name may have been used by another user. Use another organization name. diff --git a/doc/best-practice/source/faqs/image_management_faqs/how_many_tenants_can_i_share_an_swr_private_image_with.rst b/doc/best-practice/source/faqs/image_management_faqs/how_many_tenants_can_i_share_an_swr_private_image_with.rst new file mode 100644 index 0000000..b4329b6 --- /dev/null +++ b/doc/best-practice/source/faqs/image_management_faqs/how_many_tenants_can_i_share_an_swr_private_image_with.rst @@ -0,0 +1,8 @@ +:original_name: swr_faq_1013.html + +.. _swr_faq_1013: + +How Many Tenants Can I Share an SWR Private Image with? +======================================================= + +500 diff --git a/doc/best-practice/source/faqs/image_management_faqs/image_push_and_pull.rst b/doc/best-practice/source/faqs/image_management_faqs/image_push_and_pull.rst new file mode 100644 index 0000000..bc2a259 --- /dev/null +++ b/doc/best-practice/source/faqs/image_management_faqs/image_push_and_pull.rst @@ -0,0 +1,48 @@ +:original_name: swr_faq_1012.html + +.. _swr_faq_1012: + +Image Push and Pull +=================== + +How Do I Push an Image to SWR by Calling APIs? +---------------------------------------------- + +Currently, SWR does not provide APIs for image push. You can push images using the **docker push** command on a client or using the SWR console. + +How Do I Pull an Image from SWR by Calling APIs? +------------------------------------------------ + +Currently, SWR does not provide APIs for image pull. You can pull images using the **docker pull** command on a client. + +Can I Push Arm-based Container Images to SWR? +--------------------------------------------- + +SWR has no restriction on the kernel architecture of images. There is no difference between pushing an Arm-based image and an x86-based image to SWR. + +What Protocol Is Used to Push Images to SWR When I Run the **docker push** Command? +----------------------------------------------------------------------------------- + +HTTPS is used. + +Will an Image Be Overwritten If I Push an Image That Have the Same Name and Tag with it? +---------------------------------------------------------------------------------------- + +Yes, the original image will be overwritten. + +Where Are the Images Pulled by Running the **docker pull** Command Stored? +-------------------------------------------------------------------------- + +Images pulled by running the **docker pull** command are stored on your local hosts. You can run the **docker save** command to save images into TAR archive files. + +What Is the Maximum Size of an SWR Layer? +----------------------------------------- + +If you use the container engine client to push images to SWR, each image layer cannot exceed 10 GB. + +Can SWR Be Accessed over Private Networks? Will I Be Charged for Pushing and Pulling Images over Private Networks? +------------------------------------------------------------------------------------------------------------------ + +If your machine and the image repository are in the same region, you can access the image repository through private networks. No additional fees are charged for private network access because you have paid for your servers and EIPs. + +If your machine and the image repository are in different regions, the node must have access to public networks to pull images from the image repository. diff --git a/doc/best-practice/source/faqs/image_management_faqs/index.rst b/doc/best-practice/source/faqs/image_management_faqs/index.rst new file mode 100644 index 0000000..b9eabe5 --- /dev/null +++ b/doc/best-practice/source/faqs/image_management_faqs/index.rst @@ -0,0 +1,18 @@ +:original_name: swr_faq_1002.html + +.. _swr_faq_1002: + +Image Management FAQs +===================== + +- :ref:`Image Push and Pull ` +- :ref:`How Many Tenants Can I Share an SWR Private Image with? ` +- :ref:`What Are the Differences Between Long-Term Valid Login Commands and Temporary Login Commands? ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + image_push_and_pull + how_many_tenants_can_i_share_an_swr_private_image_with + what_are_the_differences_between_long-term_valid_login_commands_and_temporary_login_commands diff --git a/doc/best-practice/source/faqs/image_management_faqs/what_are_the_differences_between_long-term_valid_login_commands_and_temporary_login_commands.rst b/doc/best-practice/source/faqs/image_management_faqs/what_are_the_differences_between_long-term_valid_login_commands_and_temporary_login_commands.rst new file mode 100644 index 0000000..bd32a14 --- /dev/null +++ b/doc/best-practice/source/faqs/image_management_faqs/what_are_the_differences_between_long-term_valid_login_commands_and_temporary_login_commands.rst @@ -0,0 +1,13 @@ +:original_name: swr_faq_0015.html + +.. _swr_faq_0015: + +What Are the Differences Between Long-Term Valid Login Commands and Temporary Login Commands? +============================================================================================= + +- Temporary login commands will expire after 24 hours. +- Long-term valid login commands are valid for a year. + +After you obtain a long-term valid login command, your temporary login commands will still be valid as long as they are in their validity periods. + +The long-term valid and temporary login commands can be used by multiple users to log in to the system at the same time. diff --git a/doc/best-practice/source/faqs/index.rst b/doc/best-practice/source/faqs/index.rst new file mode 100644 index 0000000..72b3e03 --- /dev/null +++ b/doc/best-practice/source/faqs/index.rst @@ -0,0 +1,20 @@ +:original_name: swr_faq_index.html + +.. _swr_faq_index: + +FAQs +==== + +- :ref:`General FAQs ` +- :ref:`Image Management FAQs ` +- :ref:`Troubleshooting ` +- :ref:`Other FAQs ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + general_faqs/index + image_management_faqs/index + troubleshooting/index + other_faqs/index diff --git a/doc/best-practice/source/faqs/other_faqs/index.rst b/doc/best-practice/source/faqs/other_faqs/index.rst new file mode 100644 index 0000000..cd1ed4a --- /dev/null +++ b/doc/best-practice/source/faqs/other_faqs/index.rst @@ -0,0 +1,14 @@ +:original_name: en-us_topic_0000001488475196.html + +.. _en-us_topic_0000001488475196: + +Other FAQs +========== + +- :ref:`Why Does a CCE Workload Cannot Pull an Image from SWR and the Message Indicating "Not Logged In" Is Displayed? ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + why_does_a_cce_workload_cannot_pull_an_image_from_swr_and_the_message_indicating_not_logged_in_is_displayed diff --git a/doc/best-practice/source/faqs/other_faqs/why_does_a_cce_workload_cannot_pull_an_image_from_swr_and_the_message_indicating_not_logged_in_is_displayed.rst b/doc/best-practice/source/faqs/other_faqs/why_does_a_cce_workload_cannot_pull_an_image_from_swr_and_the_message_indicating_not_logged_in_is_displayed.rst new file mode 100644 index 0000000..4ae7162 --- /dev/null +++ b/doc/best-practice/source/faqs/other_faqs/why_does_a_cce_workload_cannot_pull_an_image_from_swr_and_the_message_indicating_not_logged_in_is_displayed.rst @@ -0,0 +1,35 @@ +:original_name: en-us_topic_0000001539235197.html + +.. _en-us_topic_0000001539235197: + +Why Does a CCE Workload Cannot Pull an Image from SWR and the Message Indicating "Not Logged In" Is Displayed? +============================================================================================================== + +If a CCE workload cannot pull an SWR image and the message indicating "Not logged in" is displayed, check whether the YAML file of the workload contains the **imagePullSecrets** field and whether the value of **name** is fixed to **default-secret**. + +Example: + +.. code-block:: + + apiVersion: extensions/v1beta1 + kind: Deployment + metadata: + name: nginx + spec: + replicas: 1 + selector: + matchLabels: + app: nginx + strategy: + type: RollingUpdate + template: + metadata: + labels: + app: nginx + spec: + containers: + - image: nginx + imagePullPolicy: Always + name: nginx + imagePullSecrets: + - name: default-secret diff --git a/doc/best-practice/source/faqs/troubleshooting/index.rst b/doc/best-practice/source/faqs/troubleshooting/index.rst new file mode 100644 index 0000000..e8a87c2 --- /dev/null +++ b/doc/best-practice/source/faqs/troubleshooting/index.rst @@ -0,0 +1,18 @@ +:original_name: swr_faq_2000.html + +.. _swr_faq_2000: + +Troubleshooting +=============== + +- :ref:`Why Does the Login Command Fail to Be Executed? ` +- :ref:`Why Does an Image Fail to Be Uploaded Through a Container Engine Client? ` +- :ref:`Why Does the docker pull Command Fail to Be Executed? ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + why_does_the_login_command_fail_to_be_executed + why_does_an_image_fail_to_be_uploaded_through_a_container_engine_client + why_does_the_docker_pull_command_fail_to_be_executed diff --git a/doc/best-practice/source/faqs/troubleshooting/why_does_an_image_fail_to_be_uploaded_through_a_container_engine_client.rst b/doc/best-practice/source/faqs/troubleshooting/why_does_an_image_fail_to_be_uploaded_through_a_container_engine_client.rst new file mode 100644 index 0000000..26dad37 --- /dev/null +++ b/doc/best-practice/source/faqs/troubleshooting/why_does_an_image_fail_to_be_uploaded_through_a_container_engine_client.rst @@ -0,0 +1,56 @@ +:original_name: swr_faq_0006.html + +.. _swr_faq_0006: + +Why Does an Image Fail to Be Uploaded Through a Container Engine Client? +======================================================================== + +denied: you do not have the permission +-------------------------------------- + +**Problem**: When you push an image to SWR through your container engine client, the operation fails with the following information returned. + +**denied: you do not have the permission** + +**Possible Causes**: + +- The organization name you specified has already been used by another user or the maximum number of organizations that you are allowed to create has been reached. +- The **docker login** command you used to log in to SWR is generated using the AK and SK of an IAM user who does not have the permission of the target organization. + +**Solutions**: + +- If the organization name has been registered by another user, create an organization and then upload the image. +- If the number of SWR organizations reaches the quota (5 per user), upload the image to an existing organization. +- If the IAM user does not have the permission of the target organization, log in as the cloud account and grant corresponding permissions to the IAM user and try again. + +Message "tag does not exist: xxxxxx" or "An image does not exist locally with the tag: xxxxxx" Displayed +-------------------------------------------------------------------------------------------------------- + +**Problem**: When you push an image to SWR through your container engine client, the operation fails with the following information returned. + +**tag does not exist: xxxxxx** + +Or + +**An image does not exist locally with the tag: xxxxxx** + +**Possible cause**: The image or image tag to be pushed does not exist. + +**Solution**: Run the **docker images** command to view all the local images. Check the target image name and tag, and push the image again. + +name invalid: 'repository' is invalid +------------------------------------- + +**Problem**: When you push an image to SWR through your container engine client, the operation fails with the following information returned. + +**name invalid: 'repository' is invalid** + +**Possible cause**: The organization name or image name does not comply with the naming rules. + +**Solution**: The regular expressions of the organization (namespace) name and image (repository) name are as follows: + +namespace: The value contains a maximum of 64 characters and must meet regular expression **^([a-z]+(?:(?:(?:_|__|[-]*)[a-z0-9]+)+)?)$**. + +repository: The value contains a maximum of 128 characters and must meet regular expression **^([a-z0-9]+(?:(?:(?:_|__|[-]*)[a-z0-9]+)+)?)$**. + +Specify a valid organization name or image name, and push the image again. diff --git a/doc/best-practice/source/faqs/troubleshooting/why_does_the_docker_pull_command_fail_to_be_executed.rst b/doc/best-practice/source/faqs/troubleshooting/why_does_the_docker_pull_command_fail_to_be_executed.rst new file mode 100644 index 0000000..51ec423 --- /dev/null +++ b/doc/best-practice/source/faqs/troubleshooting/why_does_the_docker_pull_command_fail_to_be_executed.rst @@ -0,0 +1,47 @@ +:original_name: swr_faq_0033.html + +.. _swr_faq_0033: + +Why Does the **docker pull** Command Fail to Be Executed? +========================================================= + +x509: certificate sigined by unknown authority +---------------------------------------------- + +**Problem**: When you run the **docker pull** command to pull an image from SWR, error message "x509: certificate signed by unknown certificates" is displayed. + +**Possible Causes**: + +- A container engine client and SWR communicate with each other using HTTPS. When the client verifies the server certificate and finds that the root certificate installed on the client is incomplete, the error message "x509: certificate signed by unknown certificates" is displayed. +- A proxy is configured on the container engine client. + +**Solution**: + +- If you trust the server and skip certificate authentication, manually configure the startup parameters for the container engine using either of the following methods (use the actual image repository address): + + - Add the following configuration to the **/etc/docker/daemon.json** file. If the file does not exist, manually create it. Ensure that two-space indents are used in the configuration. + + .. code-block:: + + { + "insecure-registries":["Image repository address"] + } + + - /etc/sysconfig/docker: + + .. code-block:: + + INSECURE_REGISTRY='--insecure-registry=Image repository address' + + After configuration, run the **systemctl restart docker** or **service docker start** command to restart the container engine. + +- Run the **docker info** command to check whether the proxy is correctly configured. If not, modify the configuration. + +Error: remote trust data does not exist +--------------------------------------- + +**Problem**: When you run the **docker pull** command to pull an image from SWR, message "Error: remote trust data does not exist" is displayed. + +**Possible cause**: The image signature verification is enabled on the client. However, the image to be pulled does not contain a signature layer. + +**Solution**: Check whether the environment variable **DOCKER_CONTENT_TRUST** is set to **1**. If yes, delete **DOCKER_CONTENT_TRUST=1** from the **/etc/profile** file and run the **source /etc/profile** command to make the modification take effect. diff --git a/doc/best-practice/source/faqs/troubleshooting/why_does_the_login_command_fail_to_be_executed.rst b/doc/best-practice/source/faqs/troubleshooting/why_does_the_login_command_fail_to_be_executed.rst new file mode 100644 index 0000000..9af22fb --- /dev/null +++ b/doc/best-practice/source/faqs/troubleshooting/why_does_the_login_command_fail_to_be_executed.rst @@ -0,0 +1,91 @@ +:original_name: swr_faq_0016.html + +.. _swr_faq_0016: + +Why Does the Login Command Fail to Be Executed? +=============================================== + +Possible causes are as follows: + +#. The container engine is not properly installed, in which case the following error is reported: + + **docker: command not found** + + **Solution**: Reinstall the container engine. + + - It is advised to install container engine 1.11.2 or later because earlier versions do not support image push to SWR. + - If the container engine client is in a private network, bind an elastic IP address (EIP) to the client. This EIP will allow the client to download installation packages from the website. + +2. .. _swr_faq_0016__li1489599133814: + + The temporary login command has expired, or the regional project name, access key (AK), or login key in the command is incorrect, in which case the following error is reported: + + **unauthorized: authentication required** + + **Solution**: Log in to the SWR console. In the navigation pane on the left, choose **My Images**. On the page displayed, click **Upload Through Client**. Then you can find the information on how to obtain a login command. + + a. .. _swr_faq_0016__li48456813192: + + To obtain a temporary login command, click **Generate a temporary login command** and then click |image1| to copy the command. + + b. To obtain a long-term valid login command, click **learn how to obtain a login command that has long-term validity** and follow the instructions. + +3. The image repository address in the login command is incorrect, in which case the following error is reported: + + **Error llgging in to v2 endpoint, trying next endpoint: Get https://{{endpoint}}/v2/: dial tcp: lookup {{endpoint}} on xxx.xxx.xxx.xxx:53 : no such host** + + **Solutions**: + + a. Change the image repository address in the login command. + b. Generate a temporary login command. For detailed instructions, see :ref:`2 `. + +4. **x509: certificate has expired or is not yet valid** + + The preceding error is reported when the AK/SK in the login command with long-term validity is deleted. In this case, use a valid AK/SK to generate a login command. + +5. **x509: certificate signed by unknown authority** + + **Possible Causes**: + + The container engine client communicates with SWR through HTTPS. The client verifies the server certificate. If the server certificate is not issued by an authoritative organization, the following error message is displayed: "x509: certificate signed by unknown authority" + + **Solutions**: + + If you trust the server and skip certificate authentication, manually configure Docker startup parameters as follows: + + - CentOS: + + Modify the **/etc/docker/daemon.json** file. If the file does not exist, manually create it. Add the following content to the file: + + .. code-block:: + + { + "insecure-registries": ["{Image repository address}"] + } + + - Ubuntu: + + Modify the **/etc/default/docker** file and add the following content to **DOCKER_OPTS**: + + .. code-block:: + + DOCKER_OPTS="--insecure-registry {image repository address}" + + - EulerOS: + + Modify the **/etc/sysconfig/docker** file and add the following content to **INSECURE_REGISTRY**: + + .. code-block:: + + INSECURE_REGISTRY='--insecure-registry {image repository address}' + + .. note:: + + The image repository address can be a domain name or an IP address. + + - To obtain the image repository address in domain name format, obtain a temporary login command by referring to :ref:`2 `. The domain name at the end of the command is the image repository address. + - To obtain the image repository address in IP address format, ping the image repository address in the domain name format. + + After the configuration, run the **systemctl restart docker** command to restart the container engine. + +.. |image1| image:: /_static/images/en-us_image_0168961239.png diff --git a/doc/best-practice/source/image_management/index.rst b/doc/best-practice/source/image_management/index.rst new file mode 100644 index 0000000..83a3a42 --- /dev/null +++ b/doc/best-practice/source/image_management/index.rst @@ -0,0 +1,22 @@ +:original_name: swr_01_0028.html + +.. _swr_01_0028: + +Image Management +================ + +- :ref:`Uploading an Image Through the Client ` +- :ref:`Obtaining a Long-Term Valid Login Command ` +- :ref:`Pulling an Image ` +- :ref:`Setting Image Attributes ` +- :ref:`Sharing Private Images ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + uploading_an_image_through_the_client + obtaining_a_long-term_valid_login_command + pulling_an_image + setting_image_attributes + sharing_private_images diff --git a/doc/best-practice/source/image_management/obtaining_a_long-term_valid_login_command.rst b/doc/best-practice/source/image_management/obtaining_a_long-term_valid_login_command.rst new file mode 100644 index 0000000..9181492 --- /dev/null +++ b/doc/best-practice/source/image_management/obtaining_a_long-term_valid_login_command.rst @@ -0,0 +1,96 @@ +:original_name: swr_01_1000.html + +.. _swr_01_1000: + +Obtaining a Long-Term Valid Login Command +========================================= + +Scenario +-------- + +This section describes how to obtain a login command that is valid for a year. + +.. note:: + + For security purposes, it is advised to obtain the login command in the development environment. + +Process +------- + +You can obtain a long-term valid login command as the following process: + + +.. figure:: /_static/images/en-us_image_0000001539605245.png + :alt: **Figure 1** Process + + **Figure 1** Process + +Procedure +--------- + +#. **Obtain the programmatic access permission. (If the current user has the permission, skip this step.)** + + a. Log in to the management console as an administrator. + b. Click |image1| in the upper left corner and select a region and a project. + c. Click |image2| in the navigation pane on the left and choose **Management & Governance** > **Identity and Access Management**. + d. Enter the name of the user to whom you want to grant the programmatic access permission in the search box on the **Users** page. + e. Click the user to go to its details page. + f. Click |image3| next to **Access Type**. + g. Select **Programmatic access**. (You can select only programmatic access or both access types.) + +#. .. _swr_01_1000__li5768123671815: + + Obtain the region, project name, and image repository address. + + a. Log in to the management console, click your username in the upper right corner, and click **My Credentials**. + b. On the **Projects** tab page, search for the project corresponding to the current region. + c. Obtain the image repository address by referring to :ref:`1.b `. The domain name at the end of the login command is the image repository address. + +#. .. _swr_01_1000__li1863783911295: + + Obtain an AK/SK. + + .. note:: + + The access key ID (AK) and secret access key (SK) are a pair of access keys used together to authenticate users who wish to make API requests. The AK/AS pair provides functions similar to a password. If you already have an AK/SK, skip this step. + + a. Log in to the management console, click your username in the upper right corner, and click **My Credentials**. + b. On the **Access Keys** tab page, click **Add Access Key**. + c. Enter the login password and verification code sent to your mailbox or mobile phone. + d. Download the access key, which includes the AK and SK. + + .. note:: + + Keep the access key secure and do not disclose it to any unauthorized personnel. + +#. .. _swr_01_1000__li132430753010: + + Log in to a Linux PC and run the following command to obtain the login key: + + **printf "$AK" \| openssl dgst -binary -sha256 -hmac "$SK" \| od -An -vtx1 \| sed 's/[ \\n]//g' \| sed 'N;s/\\n//'** + + In the command, **$AK** and **$SK** indicate the AK and SK obtained in :ref:`3 ` respectively. + + + .. figure:: /_static/images/en-us_image_0165729699.png + :alt: **Figure 2** Sample command output + + **Figure 2** Sample command output + +#. Put the information you obtained in the following format to generate a long-term valid login command: + + **docker login -u** [*Regional project name*]\ **@**\ [*AK*] **-p** [*Login key*] [*Image repository address*] + + In the command, the regional project name and image repository address are obtained in :ref:`2 `, the AK in :ref:`3 `, and the login key in :ref:`4 `. + + .. note:: + + The login key is encrypted and cannot be decrypted. Therefore, other users cannot obtain the SK from -p. + + The login command can be used on other devices. + +#. Run the **history -c** command to clear the operation records. + +.. |image1| image:: /_static/images/en-us_image_0000001507688112.png +.. |image2| image:: /_static/images/en-us_image_0000001558527697.png +.. |image3| image:: /_static/images/en-us_image_0000001507528236.png diff --git a/doc/best-practice/source/image_management/pulling_an_image.rst b/doc/best-practice/source/image_management/pulling_an_image.rst new file mode 100644 index 0000000..8ef8b7d --- /dev/null +++ b/doc/best-practice/source/image_management/pulling_an_image.rst @@ -0,0 +1,48 @@ +:original_name: swr_01_0017.html + +.. _swr_01_0017: + +Pulling an Image +================ + +Scenario +-------- + +You can run the **docker pull** command to pull images from SWR. + +Procedure +--------- + +#. Log in to the VM running the container engine as the **root** user. + +#. Obtain a login command by referring to :ref:`1 ` and access SWR. + +#. Log in to the SWR console. + +#. In the navigation pane, choose **My Images** and click the target image. + +#. .. _swr_01_0017__en-us_topic_0084266454_li197783469319: + + On the **Image Tags** tab page, in the same row as the target image tag, click |image1| in the **Image Pull Command** column to copy the command. + + + .. figure:: /_static/images/en-us_image_0000001154597496.png + :alt: **Figure 1** Obtaining the image pull command + + **Figure 1** Obtaining the image pull command + +#. Run the **image pull** command obtained in :ref:`5 ` on the VM. + + Run the **docker images** command to check whether the images are successfully pulled. + + .. code-block:: + + # docker images + REPOSITORY TAG IMAGE ID CREATED SIZE + xxx/group/nginx v2.0.0 22f2bf2e2b4f 5 hours ago 22.8MB + +#. (Optional) Run the following command to save the image as an archive file: + + **docker save** [*Image name:tag name*] **>** [*Archive file name*] + +.. |image1| image:: /_static/images/en-us_image_0282767856.png diff --git a/doc/best-practice/source/image_management/setting_image_attributes.rst b/doc/best-practice/source/image_management/setting_image_attributes.rst new file mode 100644 index 0000000..c9554d4 --- /dev/null +++ b/doc/best-practice/source/image_management/setting_image_attributes.rst @@ -0,0 +1,63 @@ +:original_name: swr_01_0016.html + +.. _swr_01_0016: + +Setting Image Attributes +======================== + +Scenario +-------- + +After uploading an image, you can set image attributes, including its type (private by default), category and description. + +Public images can be pulled by all users; whereas the access to private images requires corresponding permissions. You can add permissions, namely, read, write, and manage, to allow users to access your private images. For details, see :ref:`Granting Permissions for a Specific Image `. + +Procedure +--------- + +#. Log in to the SWR console. + +#. In the navigation pane, choose **My Images** and click the desired image. + +#. On the details page, click **Edit** in the upper right corner. On the page displayed, set **Sharing Type** (**Public** or **Private**), **Category**, and **Description**, and click **OK**. + + + .. figure:: /_static/images/en-us_image_0000001154760600.png + :alt: **Figure 1** Setting Image Attributes + + **Figure 1** Setting Image Attributes + + .. table:: **Table 1** Editing an image + + +-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Parameter | Description | + +===================================+=================================================================================================================================================================+ + | Organization | The organization to which the image belongs | + +-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Image | Image name | + +-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Sharing Type | The following options are available: | + | | | + | | - Public | + | | - Private | + | | | + | | .. note:: | + | | | + | | Public images can be pulled and used by all users. | + | | | + | | - If your machine and the image repository are in the same region, you can access the image repository over private networks. | + | | - If your machine and the image repository are in different regions, the node must have access to public networks to pull images from the image repository. | + +-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Category | The following options are available: | + | | | + | | - Application server | + | | - Linux | + | | - Windows | + | | - Arm | + | | - Framework & Application | + | | - Database | + | | - Language | + | | - Others | + +-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Description | Image description. Enter a maximum of 30,000 characters. | + +-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/doc/best-practice/source/image_management/sharing_private_images.rst b/doc/best-practice/source/image_management/sharing_private_images.rst new file mode 100644 index 0000000..5ee025f --- /dev/null +++ b/doc/best-practice/source/image_management/sharing_private_images.rst @@ -0,0 +1,55 @@ +:original_name: swr_01_0026.html + +.. _swr_01_0026: + +Sharing Private Images +====================== + +Scenario +-------- + +You can share your **private images** with other users and grant the users access permissions. + +The user with whom you shared the image can then log in to SWR console to view the image by clicking **My Images > Shared Images**. On the tab page, the user can click the target image to check its detailed information, including the image tag and image pull command. + +Notes and Constraints +--------------------- + +- Only private images can be shared. Public images cannot be shared. +- Only users authorized to manage the private images can share images. The users with whom you share your images only have the read-only permission, which only allows them to pull the images. +- You can share images only with accounts in the same region. Cross-region image sharing is not supported. + +Procedure +--------- + +#. Log in to the SWR console. + +#. In the navigation pane, choose **My Images** and click the target image. + +#. On the details page, click the **Sharing** tab. + +#. Click **Share Image**. Set parameters based on :ref:`Table 1 `, and click **OK**. + + + .. figure:: /_static/images/en-us_image_0000001200681339.png + :alt: **Figure 1** Sharing an image + + **Figure 1** Sharing an image + + .. _swr_01_0026__table15531841319: + + .. table:: **Table 1** Sharing an image + + +-------------+-------------------------------------------------------------------------------------------------------------------------+ + | Parameter | Description | + +=============+=========================================================================================================================+ + | Share With | Enter an account name with which you want to share the image. | + +-------------+-------------------------------------------------------------------------------------------------------------------------+ + | Valid Until | Set a validity period. If you want the image to be permanently accessible to the account, select **Permanently valid**. | + +-------------+-------------------------------------------------------------------------------------------------------------------------+ + | Description | Enter a maximum of 1,000 characters. | + +-------------+-------------------------------------------------------------------------------------------------------------------------+ + | Permission | Only the **Pull** permission is supported currently. | + +-------------+-------------------------------------------------------------------------------------------------------------------------+ + +#. To view all the images that you have shared, choose **My Images** in the navigation pane, click the **Private Images** tab, and select **Display only shared images**. diff --git a/doc/best-practice/source/image_management/uploading_an_image_through_the_client.rst b/doc/best-practice/source/image_management/uploading_an_image_through_the_client.rst new file mode 100644 index 0000000..12ff003 --- /dev/null +++ b/doc/best-practice/source/image_management/uploading_an_image_through_the_client.rst @@ -0,0 +1,125 @@ +:original_name: swr_01_0011.html + +.. _swr_01_0011: + +Uploading an Image Through the Client +===================================== + +Scenario +-------- + +This section walks you through the steps of uploading an image to SWR through the client by taking the **nginx:v1** image built in :ref:`Basics of the Container Engine ` as an example. Uploading an image through the client is to run Docker commands on the client where Docker is installed to push the image to an image repository of SWR. + +Notes and Constraints +--------------------- + +- Each image layer uploaded through the client cannot exceed 10 GB. +- The Docker client version must be 1.11.2 or later. + +Prerequisites +------------- + +- You have created an organization in SWR. For details, see :ref:`Creating an Organization `. +- If you use an ECS that is not a CCE node to connect to SWR using a private network address, configure **insecure-registries** as follows: + + #. Modify the **/etc/docker/daemon.json** file. If the file does not exist, manually create it. Add the following content to the file: + + .. code-block:: + + { + "insecure-registries": [ + "{Intranet address}" + ] + } + + To obtain the value of {*Intranet address*}, log in to the SWR console. On the **Dashboard** page, click **Generate Login Command** and obtain the private network address in the private network command. + + + .. figure:: /_static/images/en-us_image_0000001201043047.png + :alt: **Figure 1** Obtaining the private network address + + **Figure 1** Obtaining the private network address + + .. note:: + + If **insecure-registry** has been configured in the **DOCKER_OPTS** configuration item in the **/etc/default/docker** file, you do not need to modify the **/etc/docker/daemon.json** file. + + Run the following command to add the private network IP address to the end of the **DOCKER_OPTS** configuration item: + + **vi /etc/default/docker** + + Example: + + .. code-block:: + + # Use DOCKER_OPTS to modify the daemon startup options. DOCKER_OPTS="--insecure-registry={existing configurations} --insecure-registry={Intranet address}" + + #. Restart Docker for the configuration to take effect. + + **sudo systemctl daemon-reload** + + **sudo systemctl restart docker** + +Procedure +--------- + +#. .. _swr_01_0011__en-us_topic_0112596104_en-us_topic_0075378957_li58001655123: + + Access SWR. + + a. Log in to the SWR console and the VM running the container engine as the **root** user. + + b. .. _swr_01_0011__en-us_topic_0112596104_li182568055016: + + In the navigation pane on the left, choose **My Images** and then click **Upload Through Client**. On the page displayed, click **Generate a temporary docker login command** and click |image1| to copy the command. + + + .. figure:: /_static/images/en-us_image_0000001200577091.png + :alt: **Figure 2** Obtaining a **docker login** command + + **Figure 2** Obtaining a **docker login** command + + .. note:: + + - A temporary login command is valid for 24 hours. For details about how to obtain a login command that will remain valid for a long term, see :ref:`Obtaining a Long-Term Valid Login Command `. After you obtain a long-term valid login command, your temporary login commands will still be valid as long as they are in their validity periods. + - The domain name at the end of the login command is the image repository address. Record the address for later use. + + c. Run the **docker login** command on your Docker client (a device that has Docker installed). + + The message "Login Succeeded" will be displayed upon a successful login. + +#. Run the following command on the device where Docker is installed to label the **nginx** image: + + **docker tag** *[Image name 1*:*tag 1]* *[Image repository address]*/*[Organization name]*/*[Image name 2*:*tag 2]* + + In the preceding command: + + - [Image name 1:tag 1]: Replace it with the actual name and tag of the image to upload. + - [Image repository address]: You can query the address on the SWR console, that is, the domain name at the end of the login command in :ref:`1.b `. + - [Organization name]: Replace it with the name of the organization created. + - [Image name 2: tag 2]: Replace it with the desired image name and tag. + + Example: + + **docker tag nginx:v1 swr.eu-de.otc.t-systems.com/group/nginx:v1** + +#. Push the image to the image repository by running the following command: + + **docker push** *[Image repository address]*/*[Organization name]*/*[Image name* 2:*tag 2]* + + Example: + + **docker push swr.eu-de.otc.t-systems.com/group/nginx:v1** + + The following information will be returned upon a successful push: + + .. code-block:: + + 6d6b9812c8ae: Pushed + 695da0025de6: Pushed + fe4c16cbf7a4: Pushed + v1: digest: sha256:eb7e3bbd8e3040efa71d9c2cacfa12a8e39c6b2ccd15eac12bdc49e0b66cee63 size: 948 + + To view the pushed image, refresh the **My Images** page. + +.. |image1| image:: /_static/images/en-us_image_0143894038.png diff --git a/doc/best-practice/source/index.rst b/doc/best-practice/source/index.rst index 6e49e3c..984eff5 100644 --- a/doc/best-practice/source/index.rst +++ b/doc/best-practice/source/index.rst @@ -2,3 +2,16 @@ Software Repository for Containers - Best Practice ================================================== +.. toctree:: + :maxdepth: 1 + + service_overview/index + overview + permissions_management/index + basics_of_the_container_engine + image_management/index + organization_management + user_permissions + best_practices/index + faqs/index + change_history diff --git a/doc/best-practice/source/organization_management.rst b/doc/best-practice/source/organization_management.rst new file mode 100644 index 0000000..091e20c --- /dev/null +++ b/doc/best-practice/source/organization_management.rst @@ -0,0 +1,72 @@ +:original_name: swr_01_0014.html + +.. _swr_01_0014: + +Organization Management +======================= + +Scenario +-------- + +Organizations enable efficient management of images. Organizations are used to isolate image repositories. With each organization being limited to one company or department, images can be managed in a centralized and efficient manner. An image name needs to be unique within an organization. The same user can access different organizations as long as the user has sufficient permissions, as shown in :ref:`Figure 1 `. + +You can grant different permissions, namely, read, write, and manage, to users created by the same account. For details, see :ref:`User Permissions `. + +.. _swr_01_0014__fig1924953913304: + +.. figure:: /_static/images/en-us_image_0000001154801774.png + :alt: **Figure 1** Organization + + **Figure 1** Organization + +.. _swr_01_0014__section12921632181415: + +Creating an Organization +------------------------ + +You can create organizations based on the organizational structure of your enterprise to facilitate image resource management. Create an organization before you push an image. + +#. Log in to the SWR console. + +#. In the navigation pane on the left, choose **Organization Management** and click **Create Organization**. On the page displayed, specify **Organization Name** and click **OK**. + + + .. figure:: /_static/images/en-us_image_0000001361665969.png + :alt: **Figure 2** Creating an organization + + **Figure 2** Creating an organization + + .. note:: + + - The organization name must be globally unique. If a message is displayed indicating that the organization already exists, the organization name may have been used by another user. Use another organization name. + - After a tenant is deleted, residual organization resources may exist. In this case, the message indicating that the organization already exists could also be displayed when you create an organization. Use another organization name. + +Viewing the Images of an Organization +------------------------------------- + +After you create an organization and push images to it, you can view the image list of the organization. + +#. Log in to the SWR console. + +#. In the navigation pane, choose **Organization Management**. On the page displayed, click the desired organization name in the list. + +#. To view the images of this organization, click the **Images** tab. + + + .. figure:: /_static/images/en-us_image_0000001154966988.png + :alt: **Figure 3** Viewing the images of an organization + + **Figure 3** Viewing the images of an organization + +Deleting an Organization +------------------------ + +Before deleting an organization, delete all the images in the organization. + +#. Log in to the SWR console. +#. In the navigation pane, choose **Organization Management**. On the page displayed, click the desired organization name in the list. +#. Click **Delete** in the upper right corner. In the displayed dialog box, enter DELETE as prompted and click **Yes**. + +.. important:: + + Before you delete a tenant, delete its organizations first; otherwise, residual organization resources may exist. When you create an organization that has the same name with the residual organization, a message is displayed indicating that the organization already exists. diff --git a/doc/best-practice/source/overview.rst b/doc/best-practice/source/overview.rst new file mode 100644 index 0000000..5dce156 --- /dev/null +++ b/doc/best-practice/source/overview.rst @@ -0,0 +1,16 @@ +:original_name: swr_01_0009.html + +.. _swr_01_0009: + +Overview +======== + +SoftWare Repository for Container (SWR) allows you to easily manage the full lifecycle of container images and facilitates secure deployment of images for your applications. + +SWR provides private image repositories and fine-grained permission management, allowing you to grant different access permissions, namely, read, write, and edit, to different users. + + +.. figure:: /_static/images/en-us_image_0000001200587685.png + :alt: **Figure 1** How SWR works + + **Figure 1** How SWR works diff --git a/doc/best-practice/source/permissions_management/creating_a_user_and_granting_swr_permissions.rst b/doc/best-practice/source/permissions_management/creating_a_user_and_granting_swr_permissions.rst new file mode 100644 index 0000000..c394a30 --- /dev/null +++ b/doc/best-practice/source/permissions_management/creating_a_user_and_granting_swr_permissions.rst @@ -0,0 +1,43 @@ +:original_name: swr_01_0072.html + +.. _swr_01_0072: + +Creating a User and Granting SWR Permissions +============================================ + +This section describes how to use `IAM `__ for fine-grained permission management on your SWR resources. With IAM, you can: + +- Create IAM users for employees based on your enterprise's organizational structure. Each IAM user will have their own security credentials for accessing SWR resources. +- Grant only the permissions required for users to perform a specific task. +- Entrust a cloud account or cloud service to perform efficient O&M on your SWR resources. + +If your account does not need individual IAM users, you may skip over this chapter. + +This section describes the procedure for granting permissions (see :ref:`Figure 1 `). + +Prerequisite +------------ + +Learn about the permissions supported by SWR and choose policies or roles according to your requirements. + +Process Flow +------------ + +.. _swr_01_0072__fig5293113815405: + +.. figure:: /_static/images/en-us_image_0000001127297210.png + :alt: **Figure 1** Process for granting SWR permissions + + **Figure 1** Process for granting SWR permissions + +#. .. _swr_01_0072__li8135822590: + + `Create a user group and assign permissions `__. + + Create a user group on the IAM console, and assign the **SWR Administrator** policy to the group. + +#. `Create an IAM user and add the user to a user group `__. + + Create a user on the IAM console and add the user to the group created in :ref:`1 `. + +#. `Log in `__ as the IAM user and verify permissions. diff --git a/doc/best-practice/source/permissions_management/index.rst b/doc/best-practice/source/permissions_management/index.rst new file mode 100644 index 0000000..911fda8 --- /dev/null +++ b/doc/best-practice/source/permissions_management/index.rst @@ -0,0 +1,14 @@ +:original_name: swr_01_0070.html + +.. _swr_01_0070: + +Permissions Management +====================== + +- :ref:`Creating a User and Granting SWR Permissions ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + creating_a_user_and_granting_swr_permissions diff --git a/doc/best-practice/source/service_overview/advantages.rst b/doc/best-practice/source/service_overview/advantages.rst new file mode 100644 index 0000000..9e992e1 --- /dev/null +++ b/doc/best-practice/source/service_overview/advantages.rst @@ -0,0 +1,23 @@ +:original_name: swr_03_0002.html + +.. _swr_03_0002: + +Advantages +========== + +Ease of Use +----------- + +- You can directly push and pull container images without platform build or O&M. +- SWR provides an easy-to-use management console for full lifecycle management over container images. + +Security and Reliability +------------------------ + +- SWR supports HTTPS to ensure secure image transmission, and provides multiple security isolation mechanisms between and inside accounts. +- Based on professional storage services, SWR provides highly reliable storage service for your container images. + +Image Acceleration +------------------ + +SWR uses the image pull acceleration technology to ensure faster image pull for CCE clusters in high concurrency scenarios. diff --git a/doc/best-practice/source/service_overview/application_scenarios.rst b/doc/best-practice/source/service_overview/application_scenarios.rst new file mode 100644 index 0000000..24d3239 --- /dev/null +++ b/doc/best-practice/source/service_overview/application_scenarios.rst @@ -0,0 +1,25 @@ +:original_name: swr_03_0004.html + +.. _swr_03_0004: + +Application Scenarios +===================== + +Image Lifecycle Management +-------------------------- + +You can use SWR to build, push, pull, synchronize, and delete container images. + +**Advantages** + +- Pull acceleration ensures faster image pull for CCE clusters. +- Up to 99.999999999% image storage reliability is achieved by working with Object Storage Service (OBS). +- Fine-grained authorization allows you to control access to specific images and images in specific organizations. + +**Related service: Cloud Container Engine (CCE)** + + +.. figure:: /_static/images/en-us_image_0294353976.png + :alt: **Figure 1** SWR working with CCE + + **Figure 1** SWR working with CCE diff --git a/doc/best-practice/source/service_overview/basic_concepts.rst b/doc/best-practice/source/service_overview/basic_concepts.rst new file mode 100644 index 0000000..f97dc7c --- /dev/null +++ b/doc/best-practice/source/service_overview/basic_concepts.rst @@ -0,0 +1,34 @@ +:original_name: swr_03_0003.html + +.. _swr_03_0003: + +Basic Concepts +============== + +Image +----- + +Images are like templates that include everything needed to run applications. When deploying containerized applications, you can use images from the Docker image center and your private image registries. For example, an image can contain a complete Ubuntu operating system, in which only the required programs and dependencies are installed. Docker images are used to create Docker containers. Docker provides an easy way to create and update your own images. You can also pull images created by other users. + +Container +--------- + +A container is a running instance of a Docker image. Multiple containers can run on one node. Containers are actually software processes. Unlike traditional software processes, containers have separate namespaces and do not run directly on a host. + +Images become containers at runtime, that is, containers are created from images. Containers can be created, started, stopped, deleted, and suspended. + +Repository +---------- + +Image repositories are used for storing Docker images. An image repository hosts different versions of a specific containerized application. + +Organization +------------ + +Organizations are used to isolate image repositories. With each organization being limited to one company or department, images can be managed in a centralized and efficient manner. A user can access different organizations as long as the user has corresponding permissions. Different permissions, namely read, write, and manage, can be assigned to different users in the same account. + + +.. figure:: /_static/images/en-us_image_0195122694.png + :alt: **Figure 1** Organization + + **Figure 1** Organization diff --git a/doc/best-practice/source/service_overview/index.rst b/doc/best-practice/source/service_overview/index.rst new file mode 100644 index 0000000..b81787c --- /dev/null +++ b/doc/best-practice/source/service_overview/index.rst @@ -0,0 +1,26 @@ +:original_name: swr_pd_index.html + +.. _swr_pd_index: + +Service Overview +================ + +- :ref:`Introduction ` +- :ref:`Advantages ` +- :ref:`Application Scenarios ` +- :ref:`Basic Concepts ` +- :ref:`Notes and Constraints ` +- :ref:`Permissions ` +- :ref:`Related Services ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + introduction + advantages + application_scenarios + basic_concepts + notes_and_constraints + permissions/index + related_services diff --git a/doc/best-practice/source/service_overview/introduction.rst b/doc/best-practice/source/service_overview/introduction.rst new file mode 100644 index 0000000..b24efa8 --- /dev/null +++ b/doc/best-practice/source/service_overview/introduction.rst @@ -0,0 +1,44 @@ +:original_name: swr_03_0001.html + +.. _swr_03_0001: + +Introduction +============ + +SoftWare Repository for Container (SWR) allows you to easily manage the full lifecycle of container images and facilitates secure deployment of images for your applications. + +SWR can either work with CCE or be used as an independent container image repository. + + +.. figure:: /_static/images/en-us_image_0000001200534503.png + :alt: **Figure 1** How SWR works + + **Figure 1** How SWR works + +Features +-------- + +- **Full lifecycle management of images** + + SWR manages the whole lifecycle of your container images, including push, pull, and deletion. + +- **Private image repository and access control** + + Private image repository and fine-grained permission management allow you to grant different access permissions, namely, read, write, and edit, to different users. + +- **Large scale image distribution acceleration** + + SWR uses the image pull acceleration technology to ensure faster image pull for CCE clusters in high concurrency scenarios. + +Accessing SWR +------------- + +The cloud platform provides a web-based management console and HTTPS-based APIs through which you can access the SWR service. + +- Using APIs + + If you want to integrate SWR into a third-party system for secondary development, use APIs to access SWR. For details, see *SWR API Reference*. + +- Using the management console + + Use this mode if you do not want to integrate SWR into a third-party system. diff --git a/doc/best-practice/source/service_overview/notes_and_constraints.rst b/doc/best-practice/source/service_overview/notes_and_constraints.rst new file mode 100644 index 0000000..7133bad --- /dev/null +++ b/doc/best-practice/source/service_overview/notes_and_constraints.rst @@ -0,0 +1,21 @@ +:original_name: swr_03_0007.html + +.. _swr_03_0007: + +Notes and Constraints +===================== + +Quotas +------ + +Quotas are imposed on the number of organizations a user can create. :ref:`Table 1 ` lists the quotas imposed by SWR. + +.. _swr_03_0007__table1038894018383: + +.. table:: **Table 1** SWR resource quotas + + ============= ===== + Resource Type Quota + ============= ===== + Organization 5 + ============= ===== diff --git a/doc/best-practice/source/service_overview/permissions/index.rst b/doc/best-practice/source/service_overview/permissions/index.rst new file mode 100644 index 0000000..0cd6c92 --- /dev/null +++ b/doc/best-practice/source/service_overview/permissions/index.rst @@ -0,0 +1,22 @@ +:original_name: en-us_topic_0000001488156484.html + +.. _en-us_topic_0000001488156484: + +Permissions +=========== + +If you need to assign different permissions to employees in your enterprise to access your SWR resources, Identity and Access Management (IAM) is a good choice for fine-grained permissions management. IAM provides identity authentication, permissions management, and access control, enabling secure access to your cloud resources. + +With IAM, you can use your account to create IAM users, and assign permissions to the users to control their access to specific cloud resources. For example, some software developers in your enterprise need to use SWR resources but should not be allowed to delete the resources or perform any other high-risk operations. In this scenario, you can create IAM users for the software developers and grant them only the permissions required for using SWR resources. + +If your account does not require individual IAM users for permissions management, skip this section. + +IAM can be used free of charge. You pay only for the resources in your account. For more information about IAM, see `IAM Service Overview `__. + +- :ref:`SWR Permissions ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + swr_permissions diff --git a/doc/best-practice/source/service_overview/permissions/swr_permissions.rst b/doc/best-practice/source/service_overview/permissions/swr_permissions.rst new file mode 100644 index 0000000..d83d4d7 --- /dev/null +++ b/doc/best-practice/source/service_overview/permissions/swr_permissions.rst @@ -0,0 +1,28 @@ +:original_name: en-us_topic_0000001488156664.html + +.. _en-us_topic_0000001488156664: + +SWR Permissions +=============== + +By default, new IAM users do not have any permissions granted. You need to add them to one or more groups and attach permissions policies or roles to these groups. In this way, the users can inherit permissions from the groups and perform operations on specific cloud resources. + +SWR is a project-level service deployed and accessed in specific physical regions. To assign AOM permissions to a user group, specify the scope as region-specific projects and select projects for the permissions to take effect. If **All projects** is selected, the permissions will take effect for the user group in all region-specific projects. When accessing SWR, the users need to switch to a Region where they have been authorized to use this service. + +.. table:: **Table 1** SWR permissions + + +------------------------+----------------------------------------------------------------------------------------------+---------------------+ + | Name | Description | Type | + +========================+==============================================================================================+=====================+ + | SWR Administrator | SWR administrator permissions, including all SWR permissions. | System-defined role | + +------------------------+----------------------------------------------------------------------------------------------+---------------------+ + | Tenant Administrator | Administrator permissions for all services except IAM, including all SWR permissions. | System-defined role | + +------------------------+----------------------------------------------------------------------------------------------+---------------------+ + | Tenant Guest | Read-only permissions for all services except IAM, including permissions such as image pull. | System-defined role | + +------------------------+----------------------------------------------------------------------------------------------+---------------------+ + | ServiceStage Developer | ServiceStage developer permissions, including permissions such as image pull. | System-defined role | + +------------------------+----------------------------------------------------------------------------------------------+---------------------+ + +.. note:: + + - `Granting user permissions `__ enables you to grant read, write, and management permissions to different users for them to access either a specific image or images of a specific organization. diff --git a/doc/best-practice/source/service_overview/related_services.rst b/doc/best-practice/source/service_overview/related_services.rst new file mode 100644 index 0000000..f2fbc5b --- /dev/null +++ b/doc/best-practice/source/service_overview/related_services.rst @@ -0,0 +1,27 @@ +:original_name: swr_03_0006.html + +.. _swr_03_0006: + +Related Services +================ + +SWR works with other cloud services and requires permissions to access them. For details, see :ref:`Figure 1 `. + +.. _swr_03_0006__fig1799743414113: + +.. figure:: /_static/images/en-us_image_0196304259.png + :alt: **Figure 1** Relationship between SWR and other services + + **Figure 1** Relationship between SWR and other services + +- Cloud Container Engine (CCE) + + CCE is a high-performance, high-reliability service through which enterprises can manage containerized applications. CCE supports native Kubernetes applications and tools, allowing you to easily set up a container runtime environment on the cloud. + + SWR works seamlessly with CCE to allow you to deploy your images held by SWR on CCE clusters. + +- Cloud Trace Service (CTS) + + CTS generates traces to enable you to get a history of operations performed on cloud service resources. The content of a trace includes operation requests sent using the management console or open APIs as well as the operation results. You can view all generated traces to query, audit, and backtrack performed operations. + + With CTS, you can record operations associated with SWR for future query, audit, and backtrack operations. diff --git a/doc/best-practice/source/user_permissions.rst b/doc/best-practice/source/user_permissions.rst new file mode 100644 index 0000000..c08934c --- /dev/null +++ b/doc/best-practice/source/user_permissions.rst @@ -0,0 +1,89 @@ +:original_name: swr_01_0015.html + +.. _swr_01_0015: + +User Permissions +================ + +Scenario +-------- + +To manage SWR permissions, you can use Identity and Access Management (IAM). If you have the SWR Administrator or Tenant Administrator permission, you become an admin user of SWR accounts. You can grant permissions to other IAM users in SWR. + +If you are not an SWR account admin user, you can request an SWR account admin user to grant you permissions to read, write, or manage a specific image or images in a specific organization. + +.. note:: + + - An SWR account admin user is granted image management permission of all organizations by default, even if the user is not in the authorized user list of the organizations. + - SWR is deployed and accessed in specific physical regions. To assign permissions to a user group, specify the scope as region-specific projects and select projects for the permissions to take effect. + +Authorization Method +-------------------- + +You can grant permissions to users in SWR by using either of the following methods: + +- :ref:`Grant permissions on an image details page ` to allow users to read, write, and manage a specific image. + +- :ref:`Grant permissions on an organization details page ` to allow users to read, write, and manage all the images in an organization. + + + .. figure:: /_static/images/en-us_image_0000001200802327.png + :alt: **Figure 1** User permissions + + **Figure 1** User permissions + +You can grant the following three types of permissions to users: + +- Read: Users can only pull images. +- Write: Users can pull and push images and edit image attributes. +- Manage: Users can pull and push images, delete images or tags, edit image attributes, grant permissions, and share images with other users. + +.. _swr_01_0015__section851514354541: + +Granting Permissions for a Specific Image +----------------------------------------- + +To allow users to read, write, and manage a specific image, grant corresponding permissions to them on the details page of this image. + +#. Log in to the SWR console. + +#. In the navigation pane, choose **My Images** and click the desired image. + +#. On the image details page, click the **Permissions** tab. + +#. Click **Add Permission**. On the page displayed, click **Read**, **Write**, or **Manage** in the row of the desired username. Click **OK** to confirm. + + + .. figure:: /_static/images/en-us_image_0000001154645118.png + :alt: **Figure 2** Granting permissions for a specific image + + **Figure 2** Granting permissions for a specific image + +Modifying or Deleting Permissions for a Specific Image +------------------------------------------------------ + +You can also modify or delete user permissions on the image details page. + +- To modify permissions, click **Modify** in the row of the desired username on the **Permissions** tab page. Select a permission in the **Permission** drop-down list, and click **Save** in the **Operation** column. +- To delete permissions, click **Delete** in the row of the desired username on the **Permissions** tab page, enter **DELETE** in the dialog box displayed, and then click **Yes**. + +.. _swr_01_0015__section950354645517: + +Granting Permissions for an Organization +---------------------------------------- + +To allow users to read, write, and manage all the images in an organization, grant corresponding permissions to them on the details page of this organization. + +Only users with the **Manage** permission can grant permissions for other users. + +#. Log in to the SWR console. +#. In the navigation pane, choose **Organization Management**. Then click **Details** in the row of the desired organization. +#. On the **Users** tab page, click **Add Permission**. In the dialog box displayed, select permissions for users and click **OK**. + +Modifying or Deleting Permissions for an Organization +----------------------------------------------------- + +You can also modify and delete user permissions of an organization. + +- To modify permissions, click **Modify** in the row of the desired username on the **Users** tab page. Select a permission in the **Permission** drop-down list, and click **Save** in the **Operation** column. +- To delete permissions, click **Delete** in the row of the desired username on the **Users** tab page. In the dialog box displayed, enter **DELETE** and click **Yes**.