diff --git a/umn/source/_static/images/en-us_image_0000001137013964.png b/umn/source/_static/images/en-us_image_0000001137013964.png new file mode 100644 index 0000000..8e7f594 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0000001137013964.png differ diff --git a/umn/source/_static/images/en-us_image_0000001154534788.png b/umn/source/_static/images/en-us_image_0000001154534788.png new file mode 100644 index 0000000..8043ab4 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0000001154534788.png differ diff --git a/umn/source/_static/images/en-us_image_0000001154597496.png b/umn/source/_static/images/en-us_image_0000001154597496.png new file mode 100644 index 0000000..8550eb9 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0000001154597496.png differ diff --git a/umn/source/_static/images/en-us_image_0000001154645118.png b/umn/source/_static/images/en-us_image_0000001154645118.png new file mode 100644 index 0000000..e852649 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0000001154645118.png differ diff --git a/umn/source/_static/images/en-us_image_0000001154760600.png b/umn/source/_static/images/en-us_image_0000001154760600.png new file mode 100644 index 0000000..8d241be Binary files /dev/null and b/umn/source/_static/images/en-us_image_0000001154760600.png differ diff --git a/umn/source/_static/images/en-us_image_0000001154801774.png b/umn/source/_static/images/en-us_image_0000001154801774.png new file mode 100644 index 0000000..edb0de0 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0000001154801774.png differ diff --git a/umn/source/_static/images/en-us_image_0000001154966988.png b/umn/source/_static/images/en-us_image_0000001154966988.png new file mode 100644 index 0000000..e4d96f8 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0000001154966988.png differ diff --git a/umn/source/_static/images/en-us_image_0000001200534503.png b/umn/source/_static/images/en-us_image_0000001200534503.png new file mode 100644 index 0000000..a1fca57 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0000001200534503.png differ diff --git a/umn/source/_static/images/en-us_image_0000001200577091.png b/umn/source/_static/images/en-us_image_0000001200577091.png new file mode 100644 index 0000000..c1b1b10 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0000001200577091.png differ diff --git a/umn/source/_static/images/en-us_image_0000001200587685.png b/umn/source/_static/images/en-us_image_0000001200587685.png new file mode 100644 index 0000000..38c4ad8 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0000001200587685.png differ diff --git a/umn/source/_static/images/en-us_image_0000001200681339.png b/umn/source/_static/images/en-us_image_0000001200681339.png new file mode 100644 index 0000000..f4422f0 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0000001200681339.png differ diff --git a/umn/source/_static/images/en-us_image_0000001200800369.png b/umn/source/_static/images/en-us_image_0000001200800369.png new file mode 100644 index 0000000..c5dc977 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0000001200800369.png differ diff --git a/umn/source/_static/images/en-us_image_0000001200802327.png b/umn/source/_static/images/en-us_image_0000001200802327.png new file mode 100644 index 0000000..71e9c74 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0000001200802327.png differ diff --git a/umn/source/_static/images/en-us_image_0000001201043047.png b/umn/source/_static/images/en-us_image_0000001201043047.png new file mode 100644 index 0000000..ed6ab27 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0000001201043047.png differ diff --git a/umn/source/_static/images/en-us_image_0143894038.png b/umn/source/_static/images/en-us_image_0143894038.png new file mode 100644 index 0000000..603c946 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0143894038.png differ diff --git a/umn/source/_static/images/en-us_image_0165153802.png b/umn/source/_static/images/en-us_image_0165153802.png new file mode 100644 index 0000000..e855272 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0165153802.png differ diff --git a/umn/source/_static/images/en-us_image_0165153805.png b/umn/source/_static/images/en-us_image_0165153805.png new file mode 100644 index 0000000..a33c060 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0165153805.png differ diff --git a/umn/source/_static/images/en-us_image_0165729699.png b/umn/source/_static/images/en-us_image_0165729699.png new file mode 100644 index 0000000..4378879 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0165729699.png differ diff --git a/umn/source/_static/images/en-us_image_0168961239.png b/umn/source/_static/images/en-us_image_0168961239.png new file mode 100644 index 0000000..603c946 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0168961239.png differ diff --git a/umn/source/_static/images/en-us_image_0195122694.png b/umn/source/_static/images/en-us_image_0195122694.png new file mode 100644 index 0000000..edb0de0 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0195122694.png differ diff --git a/umn/source/_static/images/en-us_image_0196304259.png b/umn/source/_static/images/en-us_image_0196304259.png new file mode 100644 index 0000000..8b5e37b Binary files /dev/null and b/umn/source/_static/images/en-us_image_0196304259.png differ diff --git a/umn/source/_static/images/en-us_image_0282767856.png b/umn/source/_static/images/en-us_image_0282767856.png new file mode 100644 index 0000000..069c98a Binary files /dev/null and b/umn/source/_static/images/en-us_image_0282767856.png differ diff --git a/umn/source/_static/images/en-us_image_0294353976.png b/umn/source/_static/images/en-us_image_0294353976.png new file mode 100644 index 0000000..fee8364 Binary files /dev/null and b/umn/source/_static/images/en-us_image_0294353976.png differ diff --git a/umn/source/basics_of_the_container_engine.rst b/umn/source/basics_of_the_container_engine.rst new file mode 100644 index 0000000..fdb4024 --- /dev/null +++ b/umn/source/basics_of_the_container_engine.rst @@ -0,0 +1,117 @@ +: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 diff --git a/umn/source/change_history.rst b/umn/source/change_history.rst new file mode 100644 index 0000000..3d688b9 --- /dev/null +++ b/umn/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/umn/source/conf.py b/umn/source/conf.py index 6d80bb9..6ea0a6d 100644 --- a/umn/source/conf.py +++ b/umn/source/conf.py @@ -26,9 +26,6 @@ otcdocs_auto_version = False project = 'Software Repository for Containers' otcdocs_repo_name = 'docs/software-repository-container' -# Those variables are required for edit/bug links -otcdocs_git_fqdn = 'gitea.eco.tsi-dev.otc-service.com' -otcdocs_git_type = 'gitea' # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -75,12 +72,11 @@ show_authors = False html_theme = 'otcdocs' # Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the +# further. For a list of options available for each theme, see the # documentation. html_theme_options = { - "disable_search": True, - "site_name": "Internal Documentation Portal", - "logo_url": "https://docs-int.otc-service.com", + 'disable_search': True, + 'site_name': 'Internal Documentation Portal' } # The name for this set of Sphinx documents. If None, it defaults to @@ -96,8 +92,8 @@ html_static_path = ['_static'] # -- Options for PDF output -------------------------------------------------- latex_documents = [ - ('index', +('index', 'swr-umn.tex', u'Software Repository for Containers - User Guide', u'OpenTelekomCloud', 'manual'), -] +] \ No newline at end of file diff --git a/umn/source/faqs/general_faqs/how_do_i_create_a_container_image.rst b/umn/source/faqs/general_faqs/how_do_i_create_a_container_image.rst new file mode 100644 index 0000000..9737f2d --- /dev/null +++ b/umn/source/faqs/general_faqs/how_do_i_create_a_container_image.rst @@ -0,0 +1,204 @@ +: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. + +|image1| + +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. + +|image2| + +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. + +.. |image1| image:: /_static/images/en-us_image_0165153802.png +.. |image2| image:: /_static/images/en-us_image_0165153805.png diff --git a/umn/source/faqs/general_faqs/how_do_i_create_an_image_package.rst b/umn/source/faqs/general_faqs/how_do_i_create_an_image_package.rst new file mode 100644 index 0000000..d084462 --- /dev/null +++ b/umn/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/umn/source/faqs/general_faqs/index.rst b/umn/source/faqs/general_faqs/index.rst new file mode 100644 index 0000000..c34f082 --- /dev/null +++ b/umn/source/faqs/general_faqs/index.rst @@ -0,0 +1,18 @@ +:original_name: swr_faq_1001.html + +.. _swr_faq_1001: + +General FAQs +============ + +- :ref:`SWR Overview ` +- :ref:`How Do I Create a Container Image? ` +- :ref:`How Do I Create an Image Package? ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + swr_overview + how_do_i_create_a_container_image + how_do_i_create_an_image_package diff --git a/umn/source/faqs/general_faqs/swr_overview.rst b/umn/source/faqs/general_faqs/swr_overview.rst new file mode 100644 index 0000000..9f82356 --- /dev/null +++ b/umn/source/faqs/general_faqs/swr_overview.rst @@ -0,0 +1,26 @@ +:original_name: swr_faq_0013.html + +.. _swr_faq_0013: + +SWR Overview +============ + +How Many Images Can Be Stored in SWR? +------------------------------------- + +SWR has no limit on the number of images. You can upload any number of images. + +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. diff --git a/umn/source/faqs/image_management_faqs/can_i_pull_container_images_on_the_swr_console_to_a_local_pc.rst b/umn/source/faqs/image_management_faqs/can_i_pull_container_images_on_the_swr_console_to_a_local_pc.rst new file mode 100644 index 0000000..17efd2a --- /dev/null +++ b/umn/source/faqs/image_management_faqs/can_i_pull_container_images_on_the_swr_console_to_a_local_pc.rst @@ -0,0 +1,24 @@ +:original_name: swr_faq_0035.html + +.. _swr_faq_0035: + +Can I Pull Container Images on the SWR Console to a Local PC? +============================================================= + +Container images stored in SWR cannot be directly downloaded through the console. You can perform the following operations to pull the images: + +#. Obtain the image pull command on the image details page. + +#. Run the obtained command on the device where the Docker client is installed. + + Example: + + **docker pull swr.eu-de.otc.t-systems.com/group/nginx:v1** + +#. Save the image as a TAR or TAR.GZ file. + + Example: + + **docker save** **nginx:v1** **>** **nginx.tar** + +#. Download the file to the local host. diff --git a/umn/source/faqs/image_management_faqs/index.rst b/umn/source/faqs/image_management_faqs/index.rst new file mode 100644 index 0000000..24404fa --- /dev/null +++ b/umn/source/faqs/image_management_faqs/index.rst @@ -0,0 +1,18 @@ +:original_name: swr_faq_1002.html + +.. _swr_faq_1002: + +Image Management FAQs +===================== + +- :ref:`What Are the Differences Between Long-Term Valid Login Commands and Temporary Login Commands? ` +- :ref:`Why Is an Image Uploaded Through the Client to SWR Different in Size From One Uploaded Through the SWR Console? ` +- :ref:`Can I Pull Container Images on the SWR Console to a Local PC? ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + what_are_the_differences_between_long-term_valid_login_commands_and_temporary_login_commands + why_is_an_image_uploaded_through_the_client_to_swr_different_in_size_from_one_uploaded_through_the_swr_console + can_i_pull_container_images_on_the_swr_console_to_a_local_pc diff --git a/umn/source/faqs/image_management_faqs/what_are_the_differences_between_long-term_valid_login_commands_and_temporary_login_commands.rst b/umn/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/umn/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/umn/source/faqs/image_management_faqs/why_is_an_image_uploaded_through_the_client_to_swr_different_in_size_from_one_uploaded_through_the_swr_console.rst b/umn/source/faqs/image_management_faqs/why_is_an_image_uploaded_through_the_client_to_swr_different_in_size_from_one_uploaded_through_the_swr_console.rst new file mode 100644 index 0000000..0de2bf7 --- /dev/null +++ b/umn/source/faqs/image_management_faqs/why_is_an_image_uploaded_through_the_client_to_swr_different_in_size_from_one_uploaded_through_the_swr_console.rst @@ -0,0 +1,27 @@ +:original_name: swr_faq_0005.html + +.. _swr_faq_0005: + +Why Is an Image Uploaded Through the Client to SWR Different in Size From One Uploaded Through the SWR Console? +=============================================================================================================== + +Symptom +------- + +Assume that a nginx image of v2.0.0 is created on the local Docker client. The **docker images** command is run to query **SIZE** of the image. The size is **22.8 MB**. + +.. code-block:: + + $ docker images + REPOSITORY TAG IMAGE ID CREATED SIZE + nginx v2.0.0 22f2bf2e2b4f 9 days ago 22.8MB + +#. Run the **docker push** command to upload the image to SWR. The size of the image is **9.5 MB**. +#. On the local Docker client, pack the image into a **.tar** package. Download the **nginx.tar** package to the local host, and upload the package to SWR. The size of the package is **23.2 MB**. + +The size of the image uploaded through the client is different from that of the image uploaded through the SWR console. + +Cause Analysis +-------------- + +Image layers are compressed into **.tgz** packages when images are uploaded to SWR through the client, whereas when they are uploaded through the SWR console, they are only packed without being compressed. Therefore, the same image will be of different sizes when it is uploaded in these two different ways. diff --git a/umn/source/faqs/index.rst b/umn/source/faqs/index.rst new file mode 100644 index 0000000..93eff97 --- /dev/null +++ b/umn/source/faqs/index.rst @@ -0,0 +1,18 @@ +:original_name: swr_faq_index.html + +.. _swr_faq_index: + +FAQs +==== + +- :ref:`General FAQs ` +- :ref:`Image Management FAQs ` +- :ref:`Troubleshooting ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + general_faqs/index + image_management_faqs/index + troubleshooting/index diff --git a/umn/source/faqs/troubleshooting/index.rst b/umn/source/faqs/troubleshooting/index.rst new file mode 100644 index 0000000..e8a87c2 --- /dev/null +++ b/umn/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/umn/source/faqs/troubleshooting/why_does_an_image_fail_to_be_uploaded_through_a_container_engine_client.rst b/umn/source/faqs/troubleshooting/why_does_an_image_fail_to_be_uploaded_through_a_container_engine_client.rst new file mode 100644 index 0000000..05a7fc2 --- /dev/null +++ b/umn/source/faqs/troubleshooting/why_does_an_image_fail_to_be_uploaded_through_a_container_engine_client.rst @@ -0,0 +1,63 @@ +: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: + +Organization name: The value contains a maximum of 64 characters and must meet regular expression **^([a-z]+(?:(?:(?:_|__|[-]*)[a-z0-9]+)+)?)$**. + +Image name: 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. + +Image Push Occasionally Times Out +--------------------------------- + +**Problem**: Image push occasionally times out. + +**Solution**: When you push an image from a server in Chinese mainland to a server outside Chinese mainland, the network may be unstable. diff --git a/umn/source/faqs/troubleshooting/why_does_the_docker_pull_command_fail_to_be_executed.rst b/umn/source/faqs/troubleshooting/why_does_the_docker_pull_command_fail_to_be_executed.rst new file mode 100644 index 0000000..ef12a0e --- /dev/null +++ b/umn/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, skip certificate authentication. Specifically, manually configure the container engine startup parameters using either of the following two methods. Replace *Image repository address* with the actual SWR 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 restart docker** 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/umn/source/faqs/troubleshooting/why_does_the_login_command_fail_to_be_executed.rst b/umn/source/faqs/troubleshooting/why_does_the_login_command_fail_to_be_executed.rst new file mode 100644 index 0000000..cbccbc1 --- /dev/null +++ b/umn/source/faqs/troubleshooting/why_does_the_login_command_fail_to_be_executed.rst @@ -0,0 +1,94 @@ +: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: certficate 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: certficate 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: certficate signed by unknown authority". + + |image2| + + **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 +.. |image2| image:: /_static/images/en-us_image_0000001137013964.png diff --git a/umn/source/image_management/index.rst b/umn/source/image_management/index.rst new file mode 100644 index 0000000..83a3a42 --- /dev/null +++ b/umn/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/umn/source/image_management/obtaining_a_long-term_valid_login_command.rst b/umn/source/image_management/obtaining_a_long-term_valid_login_command.rst new file mode 100644 index 0000000..ab92b08 --- /dev/null +++ b/umn/source/image_management/obtaining_a_long-term_valid_login_command.rst @@ -0,0 +1,77 @@ +: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. + +Procedure +--------- + +#. .. _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 **Project List** 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:`Step 2 ` respectively. + + + .. figure:: /_static/images/en-us_image_0165729699.png + :alt: **Figure 1** Sample command output + + **Figure 1** 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:`Step 1 `, the AK in :ref:`Step 2 `, and the login key in :ref:`Step 3 `. + + + .. figure:: /_static/images/en-us_image_0000001154534788.png + :alt: **Figure 2** Long-term login command + + **Figure 2** Long-term login command + + .. 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. diff --git a/umn/source/image_management/pulling_an_image.rst b/umn/source/image_management/pulling_an_image.rst new file mode 100644 index 0000000..b570b67 --- /dev/null +++ b/umn/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:`Step 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:`Step 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/umn/source/image_management/setting_image_attributes.rst b/umn/source/image_management/setting_image_attributes.rst new file mode 100644 index 0000000..c9554d4 --- /dev/null +++ b/umn/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/umn/source/image_management/sharing_private_images.rst b/umn/source/image_management/sharing_private_images.rst new file mode 100644 index 0000000..5ee025f --- /dev/null +++ b/umn/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/umn/source/image_management/uploading_an_image_through_the_client.rst b/umn/source/image_management/uploading_an_image_through_the_client.rst new file mode 100644 index 0000000..4bc2415 --- /dev/null +++ b/umn/source/image_management/uploading_an_image_through_the_client.rst @@ -0,0 +1,129 @@ +: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. + +.. note:: + + Each image layer uploaded through the client cannot exceed 10 GB. + +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 (IP:20202) 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/umn/source/index.rst b/umn/source/index.rst index f41dac8..4d2b116 100644 --- a/umn/source/index.rst +++ b/umn/source/index.rst @@ -2,3 +2,14 @@ Software Repository for Containers - User Guide =============================================== +.. toctree:: + :maxdepth: 1 + + service_overview/index + introduction + basics_of_the_container_engine + image_management/index + organization_management + user_permissions + faqs/index + change_history diff --git a/umn/source/introduction.rst b/umn/source/introduction.rst new file mode 100644 index 0000000..f0b477e --- /dev/null +++ b/umn/source/introduction.rst @@ -0,0 +1,16 @@ +:original_name: swr_01_0009.html + +.. _swr_01_0009: + +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 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/umn/source/organization_management.rst b/umn/source/organization_management.rst new file mode 100644 index 0000000..b53e687 --- /dev/null +++ b/umn/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_0000001200800369.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 **Image** 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/umn/source/service_overview/advantages.rst b/umn/source/service_overview/advantages.rst new file mode 100644 index 0000000..c7c84ba --- /dev/null +++ b/umn/source/service_overview/advantages.rst @@ -0,0 +1,24 @@ +: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 P2P image download acceleration technology to ensure faster image pull for CCE clusters in high concurrency scenarios. +- Intelligent node scheduling around the globe ensures that your image build tasks can be automatically assigned to the idle nodes nearest to the image repository. diff --git a/umn/source/service_overview/application_scenarios.rst b/umn/source/service_overview/application_scenarios.rst new file mode 100644 index 0000000..558a99a --- /dev/null +++ b/umn/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** + +- P2P download 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 Services** + +You can use SWR together with CCE in this scenario. + +|image1| + +.. |image1| image:: /_static/images/en-us_image_0294353976.png diff --git a/umn/source/service_overview/basic_concepts.rst b/umn/source/service_overview/basic_concepts.rst new file mode 100644 index 0000000..f97dc7c --- /dev/null +++ b/umn/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/umn/source/service_overview/index.rst b/umn/source/service_overview/index.rst new file mode 100644 index 0000000..1200f96 --- /dev/null +++ b/umn/source/service_overview/index.rst @@ -0,0 +1,24 @@ +: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:`Related Services ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + introduction + advantages + application_scenarios + basic_concepts + notes_and_constraints + related_services diff --git a/umn/source/service_overview/introduction.rst b/umn/source/service_overview/introduction.rst new file mode 100644 index 0000000..23b72ed --- /dev/null +++ b/umn/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. + +- **P2P acceleration of large scale image distribution** + + SWR uses the image download 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/umn/source/service_overview/notes_and_constraints.rst b/umn/source/service_overview/notes_and_constraints.rst new file mode 100644 index 0000000..7133bad --- /dev/null +++ b/umn/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/umn/source/service_overview/related_services.rst b/umn/source/service_overview/related_services.rst new file mode 100644 index 0000000..f2fbc5b --- /dev/null +++ b/umn/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/umn/source/user_permissions.rst b/umn/source/user_permissions.rst new file mode 100644 index 0000000..9ba403b --- /dev/null +++ b/umn/source/user_permissions.rst @@ -0,0 +1,89 @@ +:original_name: swr_01_0015.html + +.. _swr_01_0015: + +User Permissions +================ + +Scenarios +--------- + +To manage SWR permissions, you can use Identity and Access Management (IAM). If you have the SWR Admin or Tenant Administrator permission, you become an admin user of SWR. You can grant permissions to other IAM users in SWR. + +If you are not an SWR admin user, you can request an SWR admin user to grant you permissions to read, write, or manage a specific image or images in a specific organization. + +.. note:: + + - An 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. In the dialog box displayed, enter **DELETE** and 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**.