copyright

lastupdated

keywords

subcollection

years
2014, 2021

2021-04-01

kubernetes, iks, registry, pull secret, secrets

containers

{:DomainName: data-hd-keyref="APPDomain"} {:DomainName: data-hd-keyref="DomainName"} {:android: data-hd-operatingsystem="android"} {:api: .ph data-hd-interface='api'} {:apikey: data-credential-placeholder='apikey'} {:app_key: data-hd-keyref="app_key"} {:app_name: data-hd-keyref="app_name"} {:app_secret: data-hd-keyref="app_secret"} {:app_url: data-hd-keyref="app_url"} {:authenticated-content: .authenticated-content} {:beta: .beta} {:c#: data-hd-programlang="c#"} {:cli: .ph data-hd-interface='cli'} {:codeblock: .codeblock} {:curl: .ph data-hd-programlang='curl'} {:deprecated: .deprecated} {:dotnet-standard: .ph data-hd-programlang='dotnet-standard'} {:download: .download} {:external: target="_blank" .external} {:faq: data-hd-content-type='faq'} {:fuzzybunny: .ph data-hd-programlang='fuzzybunny'} {:generic: data-hd-operatingsystem="generic"} {:generic: data-hd-programlang="generic"} {:gif: data-image-type='gif'} {:go: .ph data-hd-programlang='go'} {:help: data-hd-content-type='help'} {:hide-dashboard: .hide-dashboard} {:hide-in-docs: .hide-in-docs} {:important: .important} {:ios: data-hd-operatingsystem="ios"} {:java: .ph data-hd-programlang='java'} {:java: data-hd-programlang="java"} {:javascript: .ph data-hd-programlang='javascript'} {:javascript: data-hd-programlang="javascript"} {:new_window: target="_blank"} {:note .note} {:note: .note} {:objectc data-hd-programlang="objectc"} {:org_name: data-hd-keyref="org_name"} {:php: data-hd-programlang="php"} {:pre: .pre} {:preview: .preview} {:python: .ph data-hd-programlang='python'} {:python: data-hd-programlang="python"} {:route: data-hd-keyref="route"} {:row-headers: .row-headers} {:ruby: .ph data-hd-programlang='ruby'} {:ruby: data-hd-programlang="ruby"} {:runtime: architecture="runtime"} {:runtimeIcon: .runtimeIcon} {:runtimeIconList: .runtimeIconList} {:runtimeLink: .runtimeLink} {:runtimeTitle: .runtimeTitle} {:screen: .screen} {:script: data-hd-video='script'} {:service: architecture="service"} {:service_instance_name: data-hd-keyref="service_instance_name"} {:service_name: data-hd-keyref="service_name"} {:shortdesc: .shortdesc} {:space_name: data-hd-keyref="space_name"} {:step: data-tutorial-type='step'} {:subsection: outputclass="subsection"} {:support: data-reuse='support'} {:swift: .ph data-hd-programlang='swift'} {:swift: data-hd-programlang="swift"} {:table: .aria-labeledby="caption"} {:term: .term} {:tip: .tip} {:tooling-url: data-tooling-url-placeholder='tooling-url'} {:troubleshoot: data-hd-content-type='troubleshoot'} {:tsCauses: .tsCauses} {:tsResolve: .tsResolve} {:tsSymptoms: .tsSymptoms} {:tutorial: data-hd-content-type='tutorial'} {:ui: .ph data-hd-interface='ui'} {:unity: .ph data-hd-programlang='unity'} {:url: data-credential-placeholder='url'} {:user_ID: data-hd-keyref="user_ID"} {:vbnet: .ph data-hd-programlang='vb.net'} {:video: .video}

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.

Deploying containers from an {{site.data.keyword.registrylong_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 {{site.data.keyword.registrylong_notm}} namespace. For more information about how your cluster accesses registry images, see Understanding how your cluster is authorized to pull images from {{site.data.keyword.registrylong_notm}}. {: shortdesc}

Before you begin:

Set up a namespace in {{site.data.keyword.registrylong_notm}} and push images to this namespace.
Create a Kubernetes cluster.
Log in to your account. If applicable, target the appropriate resource group. Set the context for your cluster.

To deploy a container into the default namespace of your cluster:

Create a deployment configuration file that is named <deployment>.yaml.

Define the deployment and the image to use from your namespace in {{site.data.keyword.registrylong_notm}}.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: <deployment>
spec:
  replicas: <number_of_replicas>
  selector:
    matchLabels:
      app: <app_name>
  template:
    metadata:
      labels:
        app: <app_name>
    spec:
      containers:
      - name: <app_name>
        image: <region>.icr.io/<namespace>/<image>:<tag>

{: codeblock}

Understanding the YAML file components

Parameter	Description
`<deployment>`	Give your deployment a name.
`<number_of_replicas>`	Enter the number of replica pods that the deployment creates.
`app: <app_name>`	Use the name of your app as a label for the container.
`name: <app_name>`	Give your container a name, such as the name of your `app` label.
`image: <region>.icr.io/<namespace>/<image>:<tag>`	Replace the image URL variables with the information for your image: ``: The regional {{site.data.keyword.registrylong_notm}} API endpoint for the registry domain. To list the domain for the region that you are logged in to, run `ibmcloud cr api`. ``: The registry namespace. To get your namespace information, run `ibmcloud cr namespace-list`. `:`: The image and tag that you want to use for your container. To list the images that are available in your registry namespace, run `ibmcloud cr images`.

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

Referring to the image pull secret in your pod deployment

{: #pod_imagePullSecret}

If the cluster administrator did not store the image pull secret in the Kubernetes service account, all deployments that do not specify a service account cannot use the image pull secret to deploy containers. Instead, you can define an image pull secret in your pod deployment. When you refer to the image pull secret in a pod deployment, the image pull secret is valid for this pod only and cannot be shared across pods in the Kubernetes namespace. {: shortdesc}

Before you begin:

Create an image pull secret to access images in other registries or Kubernetes namespaces other than default.
Log in to your account. If applicable, target the appropriate resource group. Set the context for your cluster.

Steps:

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

Define the pod and the image pull secret to access images in {{site.data.keyword.registrylong_notm}}.

To access a private image:

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

{: codeblock}

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

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

{: codeblock}

Understanding the YAML file components

Parameter	Description
`<container_name>`	The name of the container to deploy to your cluster.
`<namespace_name>`	The registry namespace where the image is stored. To list available namespaces, run `ibmcloud cr namespace-list`.
`<image_name>`	The name of the image to use. To list available images in an {{site.data.keyword.cloud_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 image pull secret that you created earlier.

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

Pushing images to {{site.data.keyword.registrylong_notm}}

{: #push-images}

After the cluster administrator sets up an image registry with {{site.data.keyword.registrylong_notm}}, you can securely store and share Docker images with other users by adding images to your namespace. {: shortdesc}

For example, you might pull an image from any private or public registry source, and then tag it for later use in {{site.data.keyword.registrylong_notm}}. Or, you might push a Docker image that you work with to your namespace so that other users can access the image. To get started, see Adding images to your namespace.

Managing security of images in {{site.data.keyword.registrylong_notm}} with Vulnerability Advisor

{: #va-images}

Vulnerability Advisor checks the security status of container images that are provided by IBM, third parties, or added to your organization's {{site.data.keyword.registrylong_notm}} namespace. {: shortdesc}

When you add an image to a namespace, the image is automatically scanned by Vulnerability Advisor to detect security issues and potential vulnerabilities. If security issues are found, instructions are provided to help fix the reported vulnerability. To get started, see Managing image security with Vulnerability Advisor.

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.registrylong_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 so that only signed images can be used to build containers in your cluster, install the open source Portieris project.
Cluster users can deploy apps that are built from trusted images.
1. Deploy to the default Kubernetes namespace.
2. Deploy to a different Kubernetes namespace, or from a different {{site.data.keyword.cloud_notm}} region or account.

Enabling image security enforcement in your cluster

{: #portieris-image-sec}

When you enable image security enforcement in your cluster, you install the open-source Portieris Kubernetes project. Then, you can create image policies to prevent pods that do not meet the policies, such as unsigned images, from running in your cluster. {: shortdesc}

For more information, see the Portieris documentation{: external}.

Mutated images: By default, Portieris uses the MutatingAdmissionWebhook admission controller to mutate your image to refer to the image by a digest instead of a tag. However, you might have some deployment technology that rejects a mutated image. If so, you can use the image mutation option{: external} and policy{: external} to change the default behavior. {: note}

Enabling or disabling image security enforcement

{: #portieris-enable}

Kubernetes version 1.18 or later: You can enable or disable image security enforcement for your cluster from the CLI or console. For earlier versions, see the Portieris documentation{: external}. {: shortdesc}

CLI: See the following commands.

ibmcloud ks cluster image-security enable
ibmcloud ks cluster image-security disable

Console:

From the Kubernetes clusters console{: external}, select your cluster.
From the Overview tab, in the Summary pane, find the Image security enforcement field and click Enable or Disable.

Default image policies

{: #portieris-default-policies}

When you enable image security enforcement, {{site.data.keyword.containerlong_notm}} automatically creates certain image policies in your cluster. When you disable the feature, the underlying ClusterImagePolicy CRD is removed, which removes all of the default image policies and any custom images policies that you created. {: shortdesc}

Image policies with the name ibm-signed-image-enforcement restrict the images that are run in the namespace to {{site.data.keyword.containerlong_notm}} images only. Do not modify these image policies. Any changes that you make are overwritten within a few minutes.
Other image policies, such as default or default-allow-all, permit images that are not restricted by another image policy. You can modify these image policies and your changes are preserved, but do not rename the image policy. If you rename the policy, more policies with the default name and settings are created.

To review the image policies in your cluster:

Before you begin: Log in to your account. If applicable, target the appropriate resource group. Set the context for your cluster.

List the image policies that apply globally to the cluster. For an example configuration, see the Portieris policy documentation{: external}.
```
kubectl get ClusterImagePolicy
```
{: pre}
List the image policies that apply to particular namespaces within the cluster. For an example configuration, see the Portieris policy documentation{: external}.
```
kubectl get ImagePolicy --all-namespaces
```
{: pre}

Deprecated: Using a registry token to deploy containers from an {{site.data.keyword.registrylong_notm}} image

{: #namespace_token}

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.registrylong_notm}}. Existing clusters use a registry token{: external} that is stored in a cluster image pull secret to authorize access to pull images from the registry.bluemix.net domain names. {: shortdesc}

The image pull secrets are added to the default Kubernetes namespace, the kube-system namespace, and the list of secrets in the default service account for those namespaces. By using this initial setup, you can deploy containers from any image that is available in a namespace in your {{site.data.keyword.cloud_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.cloud_notm}} region or in another {{site.data.keyword.cloud_notm}} account, you must create your own image pull secret for your cluster.

This method of using a token to authorize cluster access to {{site.data.keyword.registrylong_notm}} for the registry.bluemix.net domain names is deprecated. Before tokens become unsupported, update your deployments to use the API key method to authorize cluster access to the new icr.io registry domain names. {: deprecated}

Depending on where the image is and where the container is, you must deploy containers by following different steps.

Deploy a container to the default Kubernetes namespace with an image that is in the same region as your cluster
Deploy a container to a different Kubernetes namespace than default
Deploy a container with an image that is in a different region or {{site.data.keyword.cloud_notm}} account than your cluster
Deploy a container with an image that is from a private, non-IBM registry

Deprecated: Deploying images to the `default` Kubernetes namespace with a registry token

{: #token_default_namespace}

With the registry token that is stored in the image pull secret, you can deploy a container from any image that is available in your regional {{site.data.keyword.registrylong_notm}} into the default namespace of your cluster. {: shortdesc}

Before you begin:

Set up a namespace in {{site.data.keyword.registrylong_notm}} and push images to this namespace.
Create a cluster.
Log in to your account. If applicable, target the appropriate resource group. Set the context for 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.registrylong_notm}}.

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

apiVersion: apps/v1
kind: Deployment
metadata:
  name: <app_name>-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: <app_name>
  template:
    metadata:
      labels:
        app: <app_name>
    spec:
      containers:
      - name: <app_name>
        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}

Deprecated: Copying the token-based image pull secret from the default namespace to other namespaces in your cluster

{: #token_copy_imagePullSecret}

You can copy the image pull secret with registry token credentials 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 image pull secrets from the default namespace to the namespace of your choice. The new image pull secrets 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 secrets are created successfully.
```
kubectl get secrets --namespace <namespace_name>
```
{: pre}
Deploy a container by using the image pull secret in your namespace.

Deprecated: Accessing token-authorized images in other {{site.data.keyword.cloud_notm}} regions and accounts

{: #token_other_regions_accounts}

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

Tokens that authorize access to registry.<region>.bluemix.net domains are deprecated. You can no longer create new tokens. Instead, create cluster image pull secrets that use API key credentials to pull images from the icr.io registry domains. {: deprecated}

List tokens in your {{site.data.keyword.cloud_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

Parameter	Description
`--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 image pull secret.
`--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`
`--docker-username <docker_username>`	Required. The username to log in to your private registry. For {{site.data.keyword.registrylong_notm}}, the username 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 image pull secret.
```
kubectl get secrets --namespace <kubernetes_namespace>
```
{: pre}
Deploy a container by using the image pull secret in your namespace.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

cs_images.md

cs_images.md

Building containers from images

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

Referring to the image pull secret in your pod deployment

Pushing images to {{site.data.keyword.registrylong_notm}}

Managing security of images in {{site.data.keyword.registrylong_notm}} with Vulnerability Advisor

Setting up trusted content for container images

Enabling image security enforcement in your cluster

Enabling or disabling image security enforcement

Default image policies

Deprecated: Using a registry token to deploy containers from an {{site.data.keyword.registrylong_notm}} image

Deprecated: Deploying images to the `default` Kubernetes namespace with a registry token

Deprecated: Copying the token-based image pull secret from the default namespace to other namespaces in your cluster

Deprecated: Accessing token-authorized images in other {{site.data.keyword.cloud_notm}} regions and accounts

Files

cs_images.md

Latest commit

History

cs_images.md

File metadata and controls

Building containers from images

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

Referring to the image pull secret in your pod deployment

Pushing images to {{site.data.keyword.registrylong_notm}}

Managing security of images in {{site.data.keyword.registrylong_notm}} with Vulnerability Advisor

Setting up trusted content for container images

Enabling image security enforcement in your cluster

Enabling or disabling image security enforcement

Default image policies

Deprecated: Using a registry token to deploy containers from an {{site.data.keyword.registrylong_notm}} image

Deprecated: Deploying images to the default Kubernetes namespace with a registry token

Deprecated: Copying the token-based image pull secret from the default namespace to other namespaces in your cluster

Deprecated: Accessing token-authorized images in other {{site.data.keyword.cloud_notm}} regions and accounts

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

Deprecated: Deploying images to the `default` Kubernetes namespace with a registry token