Using image pull secrets
If you are using the OKD internal registry and are pulling from image streams located in the same project, then your pod service account should already have the correct permissions and no additional action should be required.
However, for other scenarios, such as referencing images across OKD projects or from secured registries, then additional configuration steps are required.
You can obtain the image pull secret from the Red Hat OpenShift Cluster Manager. This pull secret is called pullSecret
.
You use this pull secret to authenticate with the services that are provided by the included authorities, Quay.io and registry.redhat.io, which serve the container images for OKD components.
Allowing pods to reference images across projects
When using the internal registry, to allow pods in project-a
to reference images in project-b
, a service account in project-a
must be bound to the system:image-puller
role in project-b
.
When you create a pod service account or a namespace, wait until the service account is provisioned with a docker pull secret; if you create a pod before its service account is fully provisioned, the pod fails to access the OKD internal registry. |
Procedure
To allow pods in
project-a
to reference images inproject-b
, bind a service account inproject-a
to thesystem:image-puller
role inproject-b
:$ oc policy add-role-to-user \
system:image-puller system:serviceaccount:project-a:default \
--namespace=project-b
After adding that role, the pods in
project-a
that reference the default service account are able to pull images fromproject-b
.To allow access for any service account in
project-a
, use the group:$ oc policy add-role-to-group \
system:image-puller system:serviceaccounts:project-a \
--namespace=project-b
Allowing pods to reference images from other secured registries
The .dockercfg
$HOME/.docker/config.json
file for Docker clients is a Docker credentials file that stores your authentication information if you have previously logged into a secured or insecure registry.
To pull a secured container image that is not from OKD’s internal registry, you must create a pull secret from your Docker credentials and add it to your service account.
The Docker credentials file and the associated pull secret can contain multiple references to the same registry, each with its own set of credentials.
Example config.json
file
{
"auths":{
"cloud.openshift.com":{
"auth":"b3Blb=",
"email":"you@example.com"
},
"quay.io":{
"auth":"b3Blb=",
"email":"you@example.com"
},
"quay.io/repository-main":{
"auth":"b3Blb=",
"email":"you@example.com"
}
}
}
Example pull secret
apiVersion: v1
data:
.dockerconfigjson: ewogICAiYXV0aHMiOnsKICAgICAgIm0iOnsKICAgICAgIsKICAgICAgICAgImF1dGgiOiJiM0JsYj0iLAogICAgICAgICAiZW1haWwiOiJ5b3VAZXhhbXBsZS5jb20iCiAgICAgIH0KICAgfQp9Cg==
kind: Secret
metadata:
creationTimestamp: "2021-09-09T19:10:11Z"
name: pull-secret
namespace: default
resourceVersion: "37676"
uid: e2851531-01bc-48ba-878c-de96cfe31020
type: Opaque
Procedure
If you already have a
.dockercfg
file for the secured registry, you can create a secret from that file by running:$ oc create secret generic <pull_secret_name> \
--from-file=.dockercfg=<path/to/.dockercfg> \
--type=kubernetes.io/dockercfg
Or if you have a
$HOME/.docker/config.json
file:$ oc create secret generic <pull_secret_name> \
--from-file=.dockerconfigjson=<path/to/.docker/config.json> \
--type=kubernetes.io/dockerconfigjson
If you do not already have a Docker credentials file for the secured registry, you can create a secret by running:
$ oc create secret docker-registry <pull_secret_name> \
--docker-server=<registry_server> \
--docker-username=<user_name> \
--docker-password=<password> \
--docker-email=<email>
To use a secret for pulling images for pods, you must add the secret to your service account. The name of the service account in this example should match the name of the service account the pod uses. The default service account is
default
:$ oc secrets link default <pull_secret_name> --for=pull
Pulling from private registries with delegated authentication
A private registry can delegate authentication to a separate service. In these cases, image pull secrets must be defined for both the authentication and registry endpoints.
Procedure
Create a secret for the delegated authentication server:
$ oc create secret docker-registry \
--docker-server=sso.redhat.com \
--docker-username=developer@example.com \
--docker-password=******** \
--docker-email=unused \
redhat-connect-sso
secret/redhat-connect-sso
Create a secret for the private registry:
$ oc create secret docker-registry \
--docker-server=privateregistry.example.com \
--docker-username=developer@example.com \
--docker-password=******** \
--docker-email=unused \
private-registry
secret/private-registry
Updating the global cluster pull secret
You can update the global pull secret for your cluster by either replacing the current pull secret or appending a new pull secret.
To transfer your cluster to another owner, you must first initiate the transfer in OpenShift Cluster Manager, and then update the pull secret on the cluster. Updating a cluster’s pull secret without initiating the transfer in OpenShift Cluster Manager causes the cluster to stop reporting Telemetry metrics in OpenShift Cluster Manager. For more information about transferring cluster ownership, see “Transferring cluster ownership” in the Red Hat OpenShift Cluster Manager documentation. |
Cluster resources must adjust to the new pull secret, which can temporarily limit the usability of the cluster. |
Prerequisites
- You have access to the cluster as a user with the
cluster-admin
role.
Procedure
Optional: To append a new pull secret to the existing pull secret, complete the following steps:
Enter the following command to download the pull secret:
$ oc get secret/pull-secret -n openshift-config --template='{{index .data ".dockerconfigjson" | base64decode}}' ><pull_secret_location> (1)
1 Provide the path to the pull secret file. Enter the following command to add the new pull secret:
$ oc registry login --registry="<registry>" \ (1)
--auth-basic="<username>:<password>" \ (2)
--to=<pull_secret_location> (3)
1 Provide the new registry. You can include multiple repositories within the same registry, for example: —registry=”<registry/my-namespace/my-repository>”
.2 Provide the credentials of the new registry. 3 Provide the path to the pull secret file. Alternatively, you can perform a manual update to the pull secret file.
Enter the following command to update the global pull secret for your cluster:
$ oc set data secret/pull-secret -n openshift-config --from-file=.dockerconfigjson=<pull_secret_location> (1)
1 Provide the path to the new pull secret file. This update is rolled out to all nodes, which can take some time depending on the size of your cluster.
As of OKD 4.7.4, changes to the global pull secret no longer trigger a node drain or reboot.