Container > NHN Container Registry (NCR) > User Guide

Prerequisites

Install Docker

The NHN Container Registry (NCR) service is a service for storing and deploying Docker container images. To work with container images, you must first have Docker installed in your environment.

Windows

Download and install Docker Desktop for Windows from Docker Hub.

macOS

Download and install Docker Desktop for Mac from Docker Hub.

Linux

Depending on your Linux distribution, the installation process is different. If you are using a distribution other than CentOS 7 or Ubuntu, check Install Docker Engine.

• CentOS 7

// Install packages required for Docker installation
$ sudo yum install -y yum-utils device-mapper-persistent-data lvm2

// Add the Docker repository
$ sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

// Install Docker
$ sudo yum install -y docker-ce docker-ce-cli containerd.io

// Start the Docker service
$ sudo systemctl start docker

• Ubuntu

// Update the APT index
$ sudo apt-get update

// Install packages to use repository over HTTPS
$ sudo apt-get install -y apt-transport-https ca-certificates curl gnupg-agent software-properties-common

// Add the GPG Key and verify
$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
$ sudo apt-key fingerprint 0EBFCD88

pub   rsa4096 2017-02-22 [SCEA]
      9DC8 5822 9FC7 DD38 854A  E2D8 8D81 803C 0EBF CD88
uid           [ unknown] Docker Release (CE deb) <docker@docker.com>
sub   rsa4096 2017-02-22 [S]

// Add the repository and update the APT index
$ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
$ sudo apt-get update

// Install Docker
$ sudo apt-get install docker-ce docker-ce-cli containerd.io

// Start the Docker service
$ sudo systemctl start docker

Check the User Access Key and Secret Key

You need User Access Key and Secret Key to log in to your user registry using the Docker command-line tool. User Access Key and Secret Key can be created in Account > API Security Setting page of the NHN Cloud Console.

• You can create up to 5 User Access Key IDs per NHN Cloud ID and 5 per IAM ID.

• If the User Secret Key is lost, it cannot be verified again and must be regenerated. For security, please keep the issued key in a safe place.

• It is recommended to change the User Access Key every 90 days.

Use a Container Registry

[Note] Users with member privileges cannot use the feature to store and delete container images.

Create a User Registry

To use the registry service for the first time, you must first create a registry in the NCR Console. Go to the Container > NHN Container Registry (NCR) > Management service page and click the Create Registry button. After entering the name of the registry you want to create, click the Confirm button to create the registry.

Check the User Registry Address

The address of the registry you created can be found in the registry list on the Container > NHN Container Registry (NCR) > Management service page.

Log in to the User Registry

You need to use the Docker command-line tool to store container images or import them into your environment of choice. You must be logged in to access the user registry using the Docker command-line tool. After using the docker login command, enter the User Access Key of your NHN Cloud user account in Username and the Secret Key in Password.

$ docker login {user registry address}
Username: {NHN Cloud user account User Access Key}
Password: {NHN Cloud user account User Secret Key}
Login Succeeded

[Note] The maximum validity period of a token obtained by the docker login command is 12 hours.

Store a Container Image (Push)

To store the container image to the user registry, the name of the image to be uploaded must be set in the form of image name and tag including the user registry address. This can be specified using the tag command of the Docker command-line tool.

docker tag {image name}:{tag} {user registry address}/{image name}:{tag}

• Example

docker tag ubuntu:18.04 example-kr1-registry.container.nhncloud.com/ubuntu:18.04

[Note] For container image names, only the combination of English lowercase letters, numbers, and some special characters (-, _, /, .) is allowed. Repository names are limited to a maximum of 255 characters including the registry address, and tag names are limited to a maximum of 128 characters. Long image names can be inconvenient to use. It is recommended to use a name of a suitable length.

You can now use the push command of the Docker command-line tool to store container images to your user registry.

docker push {user registry address}/{image name}:{tag name}

• Example

$ docker push example-kr1-registry.container.nhncloud.com/ubuntu:18.04
The push refers to repository [example-kr1-registry.container.nhncloud.com/ubuntu]
16542a8fc3be: Pushed
6597da2e2e52: Pushed
977183d4e999: Pushed
c8be1b8f4d60: Pushed
18.04: digest: sha256:e5dd9dbb37df5b731a6688fa49f4003359f6f126958c9c928f937bec69836320 size: 1152

View a Container Image

Stored container images can be viewed on the NCR Console.

• Image list You can view the list of container images by clicking the View Image button of the uploaded registry in the registry list on the Container > NHN Container Registry (NCR) > Management service page.

• Artifact list You can view the list of artifacts of an image by clicking the View Artifact button of the image in the image list. You can select a specific artifact from the artifact list to see details and a tag list.

• Tag list You can view the list of tags assigned to an artifact by clicking the artifact in the artifact list. You can create a new tag or search for a tag and delete it.

Download a Container Image (Pull)

You can download an image using the pull command of the Docker command-line tool. Before that, you need to check the information of the image to download from the NCR Console.

docker pull {user registry address}/{image name}:{tag name}

• Example

$ docker pull example-en1-registry.container.nhncloud.com/ubuntu:18.04
18.04: Pulling from ubuntu
5bed26d33875: Pull complete
f11b29a9c730: Pull complete
930bda195c84: Pull complete
78bf9a5ad49e: Pull complete
Digest: sha256:e5dd9dbb37df5b731a6688fa49f4003359f6f126958c9c928f937bec69836320
Status: Downloaded newer image for example-kr1-registry.container.nhncloud.com/ubuntu:18.04
example-kr1-registry.container.nhncloud.com/ubuntu:18.04

$ docker images
REPOSITORY                                              TAG     IMAGE ID        CREATED         SIZE
example-kr1-registry.container.nhncloud.com/ubuntu   18.04   4e5021d210f6    12 days ago     64.2MB

Manage a Container Registry

Delete Container Images and Artifacts

If you no longer use an image stored in the registry, you can delete it from the NCR Console. To delete an image, select the image to delete on the image list view and click the Delete Image button. Likewise, to delete an artifact, select the artifact to delete in the artifact list view and click the Delete Artifact button.

Create a Container Image Tag

You can create tags in the NCR Console without using the Docker command-line tool. On the artifact list view, select an artifact to add a tag to, and then select the Tag tab on the detailed information view at the bottom. You will then see a list of tags assigned to the currently selected artifact. If you click the Create Tag button, the Create Tag dialog box appears, and you can create a new tag by entering the tag name of your choice.

Delete a Container Image Tag

Likewise, if you have tags that you no longer use, you can delete them in the NCR Console. Similar to creating a tag, go to the tag list view and select a tag to delete. If there are many tags and the tag does not appear in the tag list, you can use the tag search function to find the tags you want to delete. Select the tag to delete and click the Delete Tag button to delete the selected tag.

Registry Webhook Settings

To receive notifications on image changes, register your webhook settings in the NCR Console. Select the registry to configure the webhook on, and select the Webhook tab on the details pane at the bottom. Click the Create Webhook button. When the Create Webhook dialog box appears, set the properties and click the Confirm button. Currently, notification settings using HTTP(S) calls and Slack messenger are supported.

Container Image Cleanup

You can make settings to clean up (delete) the images and artifacts stored in a registry according to policies in the NCR Console. To use the image cleanup policy, select a repository to apply and click the Image Cleanup tab on the details pane at the bottom. Up to 15 image cleanup policies can be registered.

[Caution] If the same policy is set for image cleanup and image protection, the image protection policy takes priority and the image cleanup feature may not work properly.

Image Cleanup Policy Setting

If you click the Add Cleanup Policy button in the Policy Setting tab, the Add Cleanup Policy dialog box appears, and you can set a new cleanup policy by entering the desired image, tag, and policy. The image cleanup policy is enabled and created. If you want to temporarily disable the policy, you can use the Enable/Disable feature.

• If a cleanup policy is added or deleted during the image cleanup operation, it will be reflected from the next image cleanup execution.

Images, tags, and cleanup policies are treated as AND conditions.

• Example of deleting all artifacts: the entire image + unused tag names + the corresponding artifacts all excluded, and clean up

[Note] You cannot add duplicate cleanup policies with the same image, tag, and policy to the registry.

Except for artifacts with the pushed and pulled date of N, the cleanup policy deletes artifacts that have been pushed and pulled after the date of N.

Delete Image Cleanup Policy

You can delete a cleanup policy by selecting it at the bottom of the Policy Setting tab and clicking the Delete Cleanup Policy button.

Test Run

You can test the image cleanup policy you have set by clicking the Test Run button on the Policy Setting tab. You can check the test run results in the View History tab.

Run Immediately

On the Policy Setting tab, click the Run Immediately button to manually run the image cleanup policy you have set. Execution results can be found in the View History tab.

Cleanup Cycle Setting

You can set a image cleanup policy to run cleanup automatically on a periodic basis. Repeat cycle uses cron expression (* * * * *) and the meaning of each field is as follows.

Field name	Acceptable range of values	Allowed special characters
Minute	0-59	* / , -
Hour	0-59	* / , -
Date	1-31	* / , ?
Month	1-12 JAN-DEC	* / , -
Day	0-6 SUN-SAT	* / , ?

[Note] The time zone used with cron expressions is Coordinated Universal Time (UTC).

View History

You can view the image cleanup history in the View History tab. You can check the history details by clicking the queried information at the bottom.

Container Image Protection

You can set the image protection feature to protect the images and artifacts stored in a registry from deletion and change in the NCR Console. To use the image protection feature, select a registry to apply and click the Image Protection tab on the details pane at the bottom. Up to 15 image protection policies can be registered.

Add Image Protection Policy

If you click the Add Protection Policy, Add Protection Policy dialog box appears, and you can set a new protection policy by entering the desired protection policy. The image protection policy is enabled and created. If you want to temporarily disable the policy, you can use the Enable/Disable feature.

[Note] You cannot add duplicate protection policies with the same image and tag to the registry.

Delete Image Protection Policy

You can delete a image protection policy by selecting a protection policy to delete at the bottom of the Image Protection tab and clicking the Delete Protection Policy button.

Use Private URI

Private URI is an address for NCR that can be used within a VPC network of NHN Cloud. If you want to use the NCR service in an instance disconnected from the external network without having to connect to the internet gateway for enhanced security, you can use the Private URI feature.

[Note] You need to create NCR and Object Storage service gateway to use the Private URI in an instance unconnected with the internet gateway.

[Note] Instance, Service Gateway, Object Storage and NCR must all use the same region.

Create an NCR Service Gateway

Go to the Network > Service Gateway page and click Create Service Gateway. Enter Name, VPC, and Subnet of the service gateway to create, and select NCRin Service and click Confirm to create the NCR service gateway.

Create an Object Storage Service Gateway

To import images from NCR using Private URI, you need to create a service gateway for Object Storage. The service gateway is required because NCR uses Object Storage to store image layers. When downloading images, NCR is accessed to import the image manifest before accessing Object Storage to download the actual image layer.

Go to the Network > Service Gateway page and click Create Service Gateway. Enter Name, VPC, and Subnet of the service gateway to create, select Object Storage in Service and click Confirm to create the Object Storage service gateway.

Register Host

You must configure the domain and IP in the host file so that the NCR registry can be used through Private URI from an instance unconnected with the internet gateway. Enter the IP address of the NCR service gateway, NCR Private Endpoint, the IP address of Object storage service gateway, and the Object Storage domain in the host file so that the IP of Private Endpoint can be found from the instance.

The IP addresses of NCR and the Object Storage service gateway can be found on the Network > Service Gateway page.

The NCR Private URI can be found on the Basic Information tab under the Container > NHN Container Registry (NCR) > Management page by selecting the registry. The private endpoint is the private URI path excluding the registry name.

• Example

Private URI: private-example-kr1-registry.container.nhncloud.com/hello-world
Private Endpoint: private-example-kr1-registry.container.nhncloud.com

Windows Open C:\Windows\System32\drivers\etc\hosts and add the following content:

{NCR Services Gateway IP Address} {NCR Private Endpoint}
{Object Storage Services Gateway IP Address} {Object Storage Domain}

Linux Open /etc/hosts and add the following content.

{NCR Services Gateway IP Address} {NCR Private Endpoint} 
Object Storage Services Gateway IP Address} {Object Storage Domain}

Registry Work via Private URI

Connect to the instance and log in to the registry by running the docker login command. Depending on the instance configuration, you may need to prefix the following commands with sudo :

$ docker login {user private registry address}
Username: {NHN Cloud user account User Access Key}
Password: {NHN Cloud user account User Secret Key}
Login Succeeded

• Example

$ docker login private-example-kr1-registry.container.nhncloud.com
Username: hello-world
Password:
Login Succeeded

Run registry works such as docker pull to download sample images from the registry. Check the information of the image to be imported from the NCR Console.

$ docker pull {User Private URI}/{Image Name}:{Tag Name}

• Example

$ docker pull private-example-kr1-registry.container.nhncloud.com/hello-world/ubuntu:18.04
18.04: Pulling from ubuntu
5bed26d33875: Pull complete
f11b29a9c730: Pull complete
930bda195c84: Pull complete
78bf9a5ad49e: Pull complete
Digest: sha256:e5dd9dbb37df5b731a6688fa49f4003359f6f126958c9c928f937bec69836320
Status: Downloaded newer image for private-example-kr1-registry.container.nhncloud.com/ubuntu:18.04
private-example-kr1-registry.container.nhncloud.com/ubuntu:18.04

$ docker images
REPOSITORY                                              TAG     IMAGE ID        CREATED         SIZE
example-kr1-registry.container.nhncloud.com/ubuntu   18.04   4e5021d210f6    12 days ago     64.2MB

Replicate a Container Image

The replication feature provided by NCR replicates images between regions. The specific characteristics of the replication feature are as follows.

• Replicate images from a region (A) to a target region (B).
• When an image is uploaded to a region (A), the image is automatically replicated to a target region (B).
• Users can start replication directly if they want.
• If the same image already exists in a target region (B), it will not be replicated.
• Even when the original image is deleted from a region (A), the replicated image is not deleted from a target region (B).

To use the image replication feature, click the Replication tab in the NCR Console.

Replication Configuration Settings

Click Create Replication and enter the required information to configure replication in the Create Replication dialog box.

[Note] The status can be displayed as Disabled immediately after creating replication. When replication is set ready, the status turns to Enabled. If the status doesn’t change after a few minutes, click Refresh.

Auto Replication

Once replication configuration is complete, when an image is uploaded to a region, it is automatically replicated to the target region.

[Caution] Only newly uploaded images are automatically replicated. If you want to replicate the uploaded image before configuring replication, use the Manual Replication feature.

Manual Replication

After clicking Run Replication , click Confirm in the Run Replication dialog box to start replication.

[Caution] If replication is executed before the Garbage Collection feature is run, the capacity of the image replicated in the target region (B) may be smaller than that of the original image. After a certain period of time, the capacity of the original image becomes smaller.

Replication History

You can check the replication progress and history in the replication history. To check the replication history, click the configured replication and click the Replication History tab on theView Details page at the bottom. You can find the history details by clicking the searched information at the bottom.

Service Permission

You can control the use of NCR for each user by using the service permissions.

Features for Permission

The service permissions of the NCR service are as follows.

Permission	Description
Project Admin Project Member Service Admin	Create, Read, Update, Delete the NHN Container Registry (NCR) service
Service Viewer	Read the NHN Container Registry (NCR) service

The features available by the NCR service permissions are as follows.

Action	Project Admin Project Member Service Admin	Service Viewer
View registries	✓	✓
Create/Delete registries	✓
View a registry replication list	✓	✓
Create/Modify/Delete/Run registry replications	✓
View a registry replication history	✓	✓
View images	✓	✓
Pull images	✓	✓
Push images	✓
Delete images	✓
View artifacts	✓	✓
Delete artifacts	✓
View artifact tags	✓	✓
Create/Delete artifact tags	✓
View webhook	✓	✓
Create/Modify/Delete webhooks	✓
View image cleanup policy	✓	✓
View image cleanup history	✓	✓
Create/Delete/Run image cleanup policy	✓
Enable/Disable image cleanup rule	✓
View image protection policy	✓	✓
Add/Delete image protection policy	✓