propose-swr_best-practice-923

Reviewed-by: Akriotis, Kyriakos <kyriakos.akriotis@t-systems.com>
Co-authored-by: Zamani Pozveh, Mohammadjavad <a200273771@noreply.gitea.eco.tsi-dev.otc-service.com>
Co-committed-by: Zamani Pozveh, Mohammadjavad <a200273771@noreply.gitea.eco.tsi-dev.otc-service.com>

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 <swr_bestpractice_0016>`
+
+.. toctree::
+   :maxdepth: 1
+   :hidden: 
+
+   migrating_container_images/index

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 <swr_bestpractice_0012>`
+-  :ref:`Migrating Images to SWR Using image-syncer <swr_bestpractice_0015>`
+-  :ref:`Synchronizing Images Across Clouds from Harbor to SWR <swr_bestpractice_0004>`
+
+.. 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

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 <swr_bestpractice_0012__en-us_topic_0000001281347382_en-us_topic_0000001262401516_li13905204219362>` 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 <https://docs.otc.t-systems.com/software-repository-container/umn/image_management/uploading_an_image_through_the_client.html>`__.
+
+   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.

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 <swr_bestpractice_0004__en-us_topic_0291248669_section176591736173817>`.
+
+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 <https://github.com/akyriako/harbor/tree/opentelekomcloud_adapter>`__ 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 <https://docs.otc.t-systems.com/software-repository-container/umn/image_management/obtaining_a_long-term_valid_login_command.html>`__.
+      -  **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 <swr_bestpractice_0004__en-us_topic_0291248669_li137017409395>`.
+
+      -  **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

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 <swr_01_0015>`.                             |
++-----------------------------------+-------------------------------------------------------------------------------------------------------+
+| 2021-08-30                        | :ref:`Service Overview <swr_pd_index>`, :ref:`FAQs <swr_faq_index>` is added.                         |
++-----------------------------------+-------------------------------------------------------------------------------------------------------+
+| 2020-06-18                        | -  Prerequisites in :ref:`Uploading an Image Through the Client <swr_01_0011>` are updated.           |
+|                                   | -  Content related to organization deletion is added in :ref:`Organization Management <swr_01_0014>`. |
++-----------------------------------+-------------------------------------------------------------------------------------------------------+
+| 2020-05-26                        | Updated:                                                                                              |
+|                                   |                                                                                                       |
+|                                   | -  :ref:`Basics of the Container Engine <swr_01_0006>`                                                |
+|                                   | -  :ref:`Uploading an Image Through the Client <swr_01_0011>`                                         |
+|                                   | -  :ref:`User Permissions <swr_01_0015>`                                                              |
++-----------------------------------+-------------------------------------------------------------------------------------------------------+
+| 2020-04-21                        | This issue is the first official release.                                                             |
++-----------------------------------+-------------------------------------------------------------------------------------------------------+

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

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>`.
+
+.. _en-us_topic_0000001539549873__table88365720443:
+
+.. table:: **Table 1** SWR resource quotas
+
+   ============= =====
+   Resource Type Quota
+   ============= =====
+   Organization  5
+   ============= =====

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

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? <swr_faq_1011>`
+-  :ref:`About SWR <swr_faq_0013>`
+-  :ref:`How Do I Create a Container Image? <swr_faq_0012>`
+-  :ref:`How Do I Create an Image Package? <swr_faq_0004>`
+-  :ref:`Are There Quotas for SWR Resources? <en-us_topic_0000001539549873>`
+-  :ref:`Why Does Organization Creation Fail? <en-us_topic_0000001488470084>`
+
+.. 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

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.