Docs › Container orchestration › Managing and hosting container images

Managing and hosting container images

Pelion Edge provides a full solution for your application management needs. This solution begins with the ability to deploy applications at the Edge in containers. With the container registry, you can efficiently manage and securely host the container images.

The container registry provides an interface for pushing, pulling or otherwise managing container images. This allows you to store your container application images in the cloud.

The registry service follows the Open Container Initiative (OCI) distribution specification, which defines an API protocol to facilitate and standardize the distribution of content.

The container registry is based on Docker Registry V2 API specification.

You can use standard tools, such as Docker, to add or retrieve application images to or from the container registry. For other actions, such as retrieving the list of available versions for an application image in a repository, you need to use the supported HTTPS APIs.

Note: Contact Pelion's service continuity team to request they enable pelion_container_registry features in your Pelion account. By default, managing container images with Pelion is not enabled.

Prerequisites

Before you can use the container registry to manage and host container images, you need to:

Complete all prerequisites and steps in deploying containerized applications using Pelion Edge.
Install Docker on your machine. Docker is a tool that makes it easier to create, deploy and run applications by using containers.

Using the container registry

The container registry provides a subset of standard application image registry features and edge extensions. A typical workflow to use the container registry is:

Log in to the container's domain.
Build and push an image to the container registry.
Pull the image directly on the gateway using Docker to run the image on the gateway device.
Use Pelion Edge and Kubernetes to deploy containerized applications to edge devices.
Fetch tags to discover image versions.

1. Logging in to the domain

The container registry is exposed on this subdomain:

containers.<region>.mbedcloud.com

The regions are:

Europe: eu-west-1.
Japan: ap-northeast-1.
United States: us-east-1.

docker login containers.<region>.mbedcloud.com -u KEY -p <access_key>

Note: The username should always be KEY. This identifies the type of authorization.

2. Pushing an image to a repository

Pushing an image to a repository involves:

Uploading the blobs that make up the image.
Uploading the image manifest.

We recommend using Docker command-line interface, which combines the steps, to manage the application images.

To do this:

Create an image, and name it with this name syntax:
```
<account_id>/<application_name> 
```
Note: You can find your Pelion account ID in the portal under Team configuration > Team profile.
Create a repository where you will push the image.
1. Format the repository name as a namespace, and include the account in the name.
  
  The repository name must follow this regex, so it can be structured as a valid namespace (for example, 0146e9b57080961e2c83536300000000/default/example-application):
```
[a-f0-9]{32}\/[a-z0-9]+([._-][a-z0-9]+)*(/[a-z0-9]+([._-][a-z0-9]+)*)*
```
  The first 32 characters structure the account ID, which must be a valid UUID.
  
  The request authentication checks that the access key or client certificate matches the account ID in the image namespace.
  
  The full image URL looks like this:
```
containers.<region>.mbedcloud.com/<account_id>/<application_name>
```
Build your application image to the repository namespace using docker build from a Dockerfile and a “context”. A build’s context is the set of files located in the specified path or URL.
Push the application image to the container registry using docker push:
```
docker build -t containers.<region>.mbedcloud.com/<account_id>/<application_name>:<tag> .
docker push containers.<region>.mbedcloud.com/<account_id>/<application_name>:<tag>
```
This pushes your application image to the container registry under the repository <account_id>/<application_name> with the tag <tag>.

3. Pulling an application image on the gateway

Gateway container management software can pull the images hosted by the container registry. The gateway connection to the container registry is authorized using device LwM2M certification.

Note: If the device from which you want to pull the container image is running Pelion Edge, you don't need to provide certificates because Pelion Edge can handle the authentication to the Pelion Device Management cloud. Use containers.local:8080 as the image server address. The host containers.local will be resolved as IP address 127.0.0.1, which Pelion Edge set up to forward traffic to the container's domain and add required authentication details.

Pulling an image involves:

Fetching the manifest using the tag or digest.
Retrieving one or more blobs.

Use Docker to fetch your application image using docker pull:

docker pull containers.local:8080/<account_id>/<application_name>:<tag>

This fetches the application Docker image on your gateway device.

4. Deploying applications using Kubernetes

You can deploy containerized applications to gateways with Pelion Edge.

To deploy application images stored in the container registry on the gateway, configure your Pod pod.yaml to fetch images from the container's domain.

For example:

apiVersion: v1
kind: Pod
metadata:
  name: test-pod
spec:
  automountServiceAccountToken: false
  hostname: test-pod
  nodeName: **YOUR-NODE-ID-HERE**
  containers:
  - name: client
    image: containers.local:8080/<account_id>/<application_name>:<tag>
    command: ["/bin/sh"]
    args: ["-c","echo 'hello'; sleep 6000000"]

Note: The host containers.local is resolved as IP address 127.0.0.1, which Pelion Edge set up to forward traffic to the container's domain.

5. Fetching tags

When images are pushed, they are tagged with versions. The tag list API gives the list of available tags or versions of an image.

To fetch the list of tags available for an image repository:

Perform a GET request to the tags endpoint.
The service responds with a list of tags.

If the repository has no tags, the service provides an empty list.

If the respository has tags, the service provides a list in a JSON body in this format:
```
{
  "name": "<name>",
  "tags": [
    "<tag1>",
    "<tag2>",
    "<tag3>"
  ]
}
```

For authentication, you can use the bearer token header authorization to authorize requests to the container's domain. You need to use the access key tied to your Pelion account to manage images pertaining to that account.

Authorization: Bearer <access_key>

Example request:

$ curl https://containers.<region>.mbedcloud.com/v2/<account_id>/<application_name>/tags/list \
 -H "Authorization: Bearer <access_key>"

 {"name":"<account_id>/<application_name>","tags":["<tag_1>","<tag_2>",..]}

Known issue

The OCI-specified DELETE APIs aren't supported.

Managing Helm charts

With the container registry, you can manage Open Container Initiative (OCI) artifacts in your repositories.

Pushing a Helm chart

To push a Helm chart to the Pelion container registry:

Set up the Helm client. For more information, see Helm installation.

Note: The container registry supports Helm client version 3.0.x and later for storing and retrieving Helm charts. To deploy Helm charts using the Edge container orchestration service, you must use Helm client version 3.0.x.
Enable OCI support in the Helm 3 client because it is an experimental feature:
```
export HELM_EXPERIMENTAL_OCI=1
```
Authenticate to the cloud registry. The container registry is exposed on this subdomain: containers.<region>.mbedcloud.com

The regions are:
- Europe: eu-west-1.
- Japan: ap-northeast-1.
- United States: us-east-1.
Log in to the container registry server domain using the access key:
```
helm registry login containers.<region>.mbedcloud.com -u KEY -p <access_key>
```
Note: The username should always be KEY. This identifies the type of authorization.

Create the Helm chart:

Create a directory named test-helm to work in:
```
mkdir test-helm
cd test-helm
```
Create a Helm chart named newchart, and clear the contents of the templates directory:
```
helm create newchart
rm -rf ./newchart/templates/*
```

Create a ConfigMap in the templates folder:

cd newchart/templates
cat <<EOF > configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: newchart-configmap
data:
  myvalue: "Hello World"
EOF

Save the chart with the helm chart save command. Use the correct alias pointing to the registry, and name it with this name syntax: <account_id>/<chart_name>.

Note: You can find your Pelion account ID in the portal under Team configuration > Team profile.

Format the chart name as a namespace, and include the account ID in the name.

The name must follow this regex, so it can be structured as a valid namespace (for example, 0146e9b57080961e2c83536300000000/test-chart): [a-f0-9]{32}\/[a-z0-9]+([._-][a-z0-9]+)*(/[a-z0-9]+([._-][a-z0-9]+)*)*

The first 32 characters structure the account ID, which must be a valid UUID.

The request authentication checks that the access key matches the account ID in the image namespace.
```
cd ..
helm chart save . containers.<region>.mbedcloud.com/<account_id>/<chart_name>:<tag>
```
For example:
```
helm chart save . containers.us-east-1.mbedcloud.com/0146e9b57080961e2c83536300000000/test-chart:mychart
ref:     containers.us-east-1.mbedcloud.com/0146e9b57080961e2c83536300000000/test-chart:mychart
digest:  0ac8b3acdaa7266e442e5b28e1fc9a7b1945276a6f7e57b49f9bac4299c9cb2e
size:    1.4 KiB
name:    newchart
version: 0.1.0
mychart: saved
```

Identify the Helm chart to push:

Run the helm chart list command to list the Helm charts on your system.

helm chart list
REF                                                         	        NAME    	VERSION	DIGEST 	SIZE   	CREATED  
containers.us-east-1.mbedcloud.com/0146e9b57080961e2c835363...	newchart	0.1.0  	0ac8b3a	1.4 KiB	5 minutes

To push, you must see the recently saved helm charts in the results.

Push the Helm chart using the helm chart push command:

helm chart push containers.<region>.mbedcloud.com/<account_id>/<chart_name>:<tag>