copyright

lastupdated

years
2014, 2018

2018-11-13

{:new_window: target="_blank"} {:shortdesc: .shortdesc} {:screen: .screen} {:pre: .pre} {:table: .aria-labeledby="caption"} {:codeblock: .codeblock} {:tip: .tip} {:note: .note} {:important: .important} {:deprecated: .deprecated} {:download: .download}

Building containers from images

{: #images}

A Docker image is the basis for every container that you create with {{site.data.keyword.containerlong}}. {:shortdesc}

An image is created from a Dockerfile, which is a file that contains instructions to build the image. A Dockerfile might reference build artifacts in its instructions that are stored separately, such as an app, the app's configuration, and its dependencies.

Planning image registries

{: #planning}

Images are typically stored in a registry that can either be accessible by the public (public registry) or set up with limited access for a small group of users (private registry). {:shortdesc}

Public registries, such as Docker Hub, can be used to get started with Docker and Kubernetes to create your first containerized app in a cluster. But when it comes to enterprise applications, use a private registry, like the one provided in {{site.data.keyword.registryshort_notm}} to protect your images from being used and changed by unauthorized users. Private registries must be set up by the cluster admin to ensure that the credentials to access the private registry are available to the cluster users.

You can use multiple registries with {{site.data.keyword.containerlong_notm}} to deploy apps to your cluster.

Registry	Description	Benefit
{{site.data.keyword.registryshort_notm}}	With this option, you can set up your own secured Docker image repository in {{site.data.keyword.registryshort_notm}} where you can safely store and share images between cluster users.	Manage access to images in your account. Use {{site.data.keyword.IBM_notm}} provided images and sample apps, such as {{site.data.keyword.IBM_notm}} Liberty, as a parent image and add your own app code to it. Automatic scanning of images for potential vulnerabilities by Vulnerability Advisor, including OS specific recommendations to fix them.
Any other private registry	Connect any existing private registry to your cluster by creating an imagePullSecret . The secret is used to securely save your registry URL and credentials in a Kubernetes secret.	Use existing private registries independent of their source (Docker Hub, organization owned registries, or other private Cloud registries).
Public Docker Hub{: #dockerhub}	Use this option to directly use existing public images from Docker Hub in your Kubernetes deployment when no Dockerfile changes are needed. Note: Keep in mind that this option might not meet your organization's security requirements, like access management, vulnerability scanning, or app privacy.	No additional setup is needed for your cluster. Includes a variety of open-source applications.
{: caption="Public and private image registry options" caption-side="top"}

After you set up an image registry, cluster users can use the images for their app deployments to the cluster.

Learn more about securing your personal information when you work with container images.

Setting up trusted content for container images

{: #trusted_images}

You can build containers from trusted images that are signed and stored in {{site.data.keyword.registryshort_notm}}, and prevent deployments from unsigned or vulnerable images. {:shortdesc}

Sign images for trusted content. After you set up trust for your images, you can manage trusted content and signers that can push images to your registry.
To enforce a policy that only signed images can be used to build containers in your cluster, add Container Image Security Enforcement (beta).
Deploy your app.
1. Deploy to the default Kubernetes namespace.
2. Deploy to a different Kubernetes namespace, or from a different {{site.data.keyword.Bluemix_notm}} region or account.

Deploying containers from an {{site.data.keyword.registryshort_notm}} image to the `default` Kubernetes namespace

{: #namespace}

You can deploy containers to your cluster from an IBM-provided public image or a private image that is stored in your namespace in {{site.data.keyword.registryshort_notm}}. {:shortdesc}

When you create a cluster, non-expiring registry tokens and secrets are automatically created for both the nearest regional registry and the global registry. The global registry securely stores public, IBM-provided images that you can refer to across your deployments instead of having different references for images that are stored in each regional registry. The regional registry securely stores your own private Docker images, as well as the same public images that are stored in the global registry. The tokens are used to authorize read-only access to any of your namespaces that you set up in {{site.data.keyword.registryshort_notm}} so that you can work with these public (global registry) and private (regional registries) images.

Each token must be stored in a Kubernetes imagePullSecret so that it is accessible to a Kubernetes cluster when you deploy a containerized app. When your cluster is created, {{site.data.keyword.containerlong_notm}} automatically stores the tokens for the global (IBM-provided public images) and regional registries in Kubernetes image pull secrets. The image pull secrets are added to the default Kubernetes namespace, the default list of secrets in the ServiceAccount for that namespace, and the kube-system namespace.

By using this initial setup, you can deploy containers from any image that is available in a namespace in your {{site.data.keyword.Bluemix_notm}} account into the default namespace of your cluster. To deploy a container into other namespaces of your cluster, or to use an image that is stored in another {{site.data.keyword.Bluemix_notm}} region or in another {{site.data.keyword.Bluemix_notm}} account, you must create your own imagePullSecret for your cluster. {: note}

Want to make your registry credentials even more secured? Ask your cluster admin to enable {{site.data.keyword.keymanagementservicefull}} in your cluster to encrypt Kubernetes secrets in your cluster, such as the imagePullSecret that stores your registry credentials. {: tip}

Before you begin:

Set up a namespace in {{site.data.keyword.registryshort_notm}} on {{site.data.keyword.Bluemix_notm}} Public or {{site.data.keyword.Bluemix_dedicated_notm}} and push images to this namespace.
Create a cluster.
Target your CLI to your cluster.

To deploy a container into the default namespace of your cluster, create a configuration file.

Create a deployment configuration file that is named mydeployment.yaml.

Define the deployment and the image that you want to use from your namespace in {{site.data.keyword.registryshort_notm}}.

To use a private image from a namespace in {{site.data.keyword.registryshort_notm}}:

apiVersion: apps/v1beta1
kind: Deployment
metadata:
  name: ibmliberty-deployment
spec:
  replicas: 3
  template:
    metadata:
      labels:
        app: ibmliberty
    spec:
      containers:
      - name: ibmliberty
        image: registry.<region>.bluemix.net/<namespace>/<my_image>:<tag>

{: codeblock}

Tip: To retrieve your namespace information, run ibmcloud cr namespace-list.

Create the deployment in your cluster.
```
kubectl apply -f mydeployment.yaml
```
{: pre}

Tip: You can also deploy an existing configuration file, such as one of the IBM-provided public images. This example uses the ibmliberty image in the US-South region.
```
kubectl apply -f https://raw.githubusercontent.com/IBM-Cloud/kube-samples/master/deploy-apps-clusters/deploy-ibmliberty.yaml
```
{: pre}

Creating an `imagePullSecret` to access {{site.data.keyword.Bluemix_notm}} or external private registries in other Kubernetes namespaces, {{site.data.keyword.Bluemix_notm}} regions, and accounts

{: #other}

Create your own imagePullSecret to deploy containers to other Kubernetes namespaces, use images that are stored in other {{site.data.keyword.Bluemix_notm}} regions or accounts, use images that are stored in {{site.data.keyword.Bluemix_dedicated_notm}}, or use images that are stored in external private registries. {:shortdesc}

ImagePullSecrets are valid only for the Kubernetes namespaces that they were created for. Repeat these steps for every namespace where you want to deploy containers. Images from DockerHub do not require ImagePullSecrets. {: tip}

Before you begin:

Set up a namespace in {{site.data.keyword.registryshort_notm}} on {{site.data.keyword.Bluemix_notm}} Public or {{site.data.keyword.Bluemix_dedicated_notm}} and push images to this namespace.
Create a cluster.
Target your CLI to your cluster.

To create your own imagePullSecret you can choose among the following options: - [Copy the imagePullSecret from the default namespace to other namespaces in your cluster](#copy_imagePullSecret). - [Create an imagePullSecret to access images in other {{site.data.keyword.Bluemix_notm}} regions and accounts](#other_regions_accounts). - [Create an imagePullSecret to access images in external private registries](#private_images).
If you already created an imagePullSecret in your namespace that you want to use in your deployment, see [Deploying containers by using the created imagePullSecret](#use_imagePullSecret).

Copying the imagePullSecret from the default namespace to other namespaces in your cluster

{: #copy_imagePullSecret}

You can copy the imagePullSecret that is automatically created for the default Kubernetes namespace to other namespaces in your cluster. {: shortdesc}

List available namespaces in your cluster.

kubectl get namespaces

{: pre}

Example output:

default          Active    79d
ibm-cert-store   Active    79d
ibm-system       Active    79d
istio-system     Active    34d
kube-public      Active    79d
kube-system      Active    79d

{: screen}

Optional: Create a namespace in your cluster.
```
kubectl create namespace <namespace_name>
```
{: pre}

Copy the imagePullSecrets from the default namespace to the namespace of your choice. The new imagePullSecrets are named bluemix-<namespace_name>-secret-regional and bluemix-<namespace_name>-secret-international.

kubectl get secret bluemix-default-secret-regional -o yaml | sed 's/default/<namespace_name>/g' | kubectl -n <namespace_name> create -f -

{: pre}

kubectl get secret bluemix-default-secret-international -o yaml | sed 's/default/<namespace_name>/g' | kubectl -n <namespace_name> create -f -

{: pre}

Verify that the secret was created successfully.
```
kubectl get secrets --namespace <namespace_name>
```
{: pre}
Deploy a container by using the imagePullSecret in your namespace.

Creating an imagePullSecret to access images in other {{site.data.keyword.Bluemix_notm}} regions and accounts

{: #other_regions_accounts}

To access images in other {{site.data.keyword.Bluemix_notm}} regions or accounts, you must create a registry token and save your credentials in an imagePullSecret. {: shortdesc}

If you do not have a token, create a token for the registry that you want to access.
List tokens in your {{site.data.keyword.Bluemix_notm}} account.
```
ibmcloud cr token-list
```
{: pre}
Note the token ID that you want to use.
Retrieve the value for your token. Replace <token_ID> with the ID of the token that you retrieved in the previous step.
```
ibmcloud cr token-get <token_id>
```
{: pre}

Your token value is displayed in the Token field of your CLI output.

Create the Kubernetes secret to store your token information.

kubectl --namespace <kubernetes_namespace> create secret docker-registry <secret_name>  --docker-server=<registry_URL> --docker-username=token --docker-password=<token_value> --docker-email=<docker_email>

{: pre}

Understanding this command's components

Understanding this command's components
`--namespace <kubernetes_namespace>`	Required. The Kubernetes namespace of your cluster where you want to use the secret and deploy containers to. Run `kubectl get namespaces` to list all namespaces in your cluster.
`<secret_name>`	Required. The name that you want to use for your imagePullSecret.
`--docker-server <registry_URL>`	Required. The URL to the image registry where your namespace is set up. For namespaces that are set up in US-South and US-East registry.ng.bluemix.net For namespaces that are set up in UK-South registry.eu-gb.bluemix.net For namespaces that are set up in EU-Central (Frankfurt) registry.eu-de.bluemix.net For namespaces that are set up in Australia (Sydney) registry.au-syd.bluemix.net For namespaces that are set up in {{site.data.keyword.Bluemix_dedicated_notm}} registry.<dedicated_domain>
`--docker-username <docker_username>`	Required. The user name to log in to your private registry. For {{site.data.keyword.registryshort_notm}}, the user name is set to the value `token`.
`--docker-password <token_value>`	Required. The value of your registry token that you retrieved earlier.
`--docker-email <docker-email>`	Required. If you have one, enter your Docker email address. If you do not, enter a fictional email address, as for example a@b.c. This email is mandatory to create a Kubernetes secret, but is not used after creation.

Verify that the secret was created successfully. Replace <kubernetes_namespace> with the namespace where you created the imagePullSecret.
```
kubectl get secrets --namespace <kubernetes_namespace>
```
{: pre}
Deploy a container by using the imagePullSecret in your namespace.

Accessing images that are stored in other private registries

{: #private_images}

If you already have a private registry, you must store the registry credentials in a Kubernetes imagePullSecret and reference this secret from your configuration file. {:shortdesc}

Before you begin:

Create a cluster.
Target your CLI to your cluster.

To create an imagePullSecret:

Create the Kubernetes secret to store your private registry credentials.

kubectl --namespace <kubernetes_namespace> create secret docker-registry <secret_name>  --docker-server=<registry_URL> --docker-username=<docker_username> --docker-password=<docker_password> --docker-email=<docker_email>

{: pre}

Understanding this command's components

Understanding this command's components
`--namespace <kubernetes_namespace>`	Required. The Kubernetes namespace of your cluster where you want to use the secret and deploy containers to. Run `kubectl get namespaces` to list all namespaces in your cluster.
`<secret_name>`	Required. The name that you want to use for your imagePullSecret.
`--docker-server <registry_URL>`	Required. The URL to the registry where your private images are stored.
`--docker-username <docker_username>`	Required. The user name to log in to your private registry.
`--docker-password <token_value>`	Required. The value of your registry token that you retrieved earlier.
`--docker-email <docker-email>`	Required. If you have one, enter your Docker email address. If you do not have one, enter a fictional email address, as for example a@b.c. This email is mandatory to create a Kubernetes secret, but is not used after creation.

Verify that the secret was created successfully. Replace <kubernetes_namespace> with the name of the namespace where you created the imagePullSecret.
```
kubectl get secrets --namespace <kubernetes_namespace>
```
{: pre}
Create a pod that references the imagePullSecret.

Deploying containers by using the created imagePullSecret

{: #use_imagePullSecret}

You can define an imagePullSecret in your pod deployment or store the imagePullSecret in your Kubernetes service account so that it is available for all deployments that do not specify a service account. {: shortdesc}

Choose between the following options:

Referring to the imagePullSecret in your pod deployment: Use this option if you do not want to grant access to your registry for all pods in your namespace by default.
Storing the imagePullSecret in the Kubernetes service account: Use this option to grant access to images in your registry for deployments in the selected Kubernetes namespaces.

Before you begin:

Create an imagePullSecret to access images in other registries, Kubernetes namespaces, {{site.data.keyword.Bluemix_notm}} regions, or accounts.
Target your CLI to your cluster.

Referring to the `imagePullSecret` in your pod deployment

{: #pod_imagePullSecret}

When you refer to the imagePullSecret in a pod deployment, the imagePullSecret is valid for this pod only and cannot be shared across pods in the namespace. {:shortdesc}

Create a pod configuration file that is named mypod.yaml.

Define the pod and the imagePullSecret to access the private {{site.data.keyword.registrylong_notm}}.

To access a private image:

apiVersion: v1
kind: Pod
metadata:
  name: mypod
spec:
  containers:
    - name: <container_name>
      image: registry.<region>.bluemix.net/<namespace_name>/<image_name>:<tag>
  imagePullSecrets:
    - name: <secret_name>

{: codeblock}

To access an {{site.data.keyword.Bluemix_notm}} public image:

apiVersion: v1
kind: Pod
metadata:
  name: mypod
spec:
  containers:
    - name: <container_name>
      image: registry.bluemix.net/<image_name>:<tag>
  imagePullSecrets:
    - name: <secret_name>

{: codeblock}

Understanding the YAML file components

Understanding the YAML file components
`<container_name>`	The name of the container to deploy to your cluster.
`<namespace_name>`	The namespace where the image is stored. To list available namespaces, run `ibmcloud cr namespace-list`.
`<image_name>`	The name of the image that you want to use. To list available images in an {{site.data.keyword.Bluemix_notm}} account, run `ibmcloud cr image-list`.
`<tag>`	The version of the image that you want to use. If no tag is specified, the image that is tagged latest is used by default.
`<secret_name>`	The name of the imagePullSecret that you created earlier.

Save your changes.
Create the deployment in your cluster.
```
kubectl apply -f mypod.yaml
```
{: pre}

Storing the imagePullSecret in the Kubernetes service account for the selected namespace

{:#store_imagePullSecret}

Every namespace has a Kubernetes service account that is named default. You can add the imagePullSecret to this service account to grant access to images in your registry. Deployments that do not specify a service account automatically use the default service account for this namespace. {:shortdesc}

Check if an imagePullSecret already exists for your default service account.
```
kubectl describe serviceaccount default -n <namespace_name>
```
{: pre} When <none> is displayed in the Image pull secrets entry, no imagePullSecret exists.

Add the imagePullSecret to your default service account.

To add the imagePullSecret when no imagePullSecret is defined:

kubectl patch -n <namespace_name> serviceaccount/default -p '{"imagePullSecrets":[{"name": "bluemix-<namespace_name>-secret-regional"}]}'

{: pre}

To add the imagePullSecret when an imagePullSecret is already defined:

kubectl patch -n <namespace_name> serviceaccount/default --type='json' -p='[{"op":"add","path":"/imagePullSecrets/-","value":{"name":"bluemix-<namespace_name>-secret-regional"}}]'

{: pre}

Verify that your imagePullSecret was added to your default service account.

kubectl describe serviceaccount default -n <namespace_name>

{: pre}

Example output:

Name:                default
Namespace:           <namespace_name>
Labels:              <none>
Annotations:         <none>
Image pull secrets:  bluemix-namespace_name-secret-regional
Mountable secrets:   default-token-sh2dx
Tokens:              default-token-sh2dx
Events:              <none>

{: pre}

Deploy a container from an image in your registry.

apiVersion: v1
kind: Pod
metadata:
  name: mypod
spec:
  containers:
    - name: <container_name>
      image: registry.<region>.bluemix.net/<namespace_name>/<image_name>:<tag>

{: codeblock}

Create the deployment in the cluster.
```
kubectl apply -f mypod.yaml
```
{: pre}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

cs_images.md

cs_images.md

Building containers from images

Planning image registries

Setting up trusted content for container images

Deploying containers from an {{site.data.keyword.registryshort_notm}} image to the `default` Kubernetes namespace

Creating an `imagePullSecret` to access {{site.data.keyword.Bluemix_notm}} or external private registries in other Kubernetes namespaces, {{site.data.keyword.Bluemix_notm}} regions, and accounts

Copying the imagePullSecret from the default namespace to other namespaces in your cluster

Creating an imagePullSecret to access images in other {{site.data.keyword.Bluemix_notm}} regions and accounts

Accessing images that are stored in other private registries

Deploying containers by using the created imagePullSecret

Referring to the `imagePullSecret` in your pod deployment

Storing the imagePullSecret in the Kubernetes service account for the selected namespace

Files

cs_images.md

Latest commit

History

cs_images.md

File metadata and controls

Building containers from images

Planning image registries

Setting up trusted content for container images

Deploying containers from an {{site.data.keyword.registryshort_notm}} image to the default Kubernetes namespace

Creating an imagePullSecret to access {{site.data.keyword.Bluemix_notm}} or external private registries in other Kubernetes namespaces, {{site.data.keyword.Bluemix_notm}} regions, and accounts

Copying the imagePullSecret from the default namespace to other namespaces in your cluster

Creating an imagePullSecret to access images in other {{site.data.keyword.Bluemix_notm}} regions and accounts

Accessing images that are stored in other private registries

Deploying containers by using the created imagePullSecret

Referring to the imagePullSecret in your pod deployment

Storing the imagePullSecret in the Kubernetes service account for the selected namespace

Deploying containers from an {{site.data.keyword.registryshort_notm}} image to the `default` Kubernetes namespace

Creating an `imagePullSecret` to access {{site.data.keyword.Bluemix_notm}} or external private registries in other Kubernetes namespaces, {{site.data.keyword.Bluemix_notm}} regions, and accounts

Referring to the `imagePullSecret` in your pod deployment