How to use the OpenShift integrated container registry

The OpenShift integrated registry of each APPUiO Cloud zone is exposed outside the cluster at registry.<zone>.appuio.cloud.

Prerequisites

In general, all users who have access to a namespace are allowed to

  • Pull images associated with the namespace from the registry.

  • Push images associated with the namespace to the registry.

Images associated with a namespace are stored in the registry under registry.<zone>.appuio.cloud/<namespace>.

If you need more fine-grained access control, see section Advanced user access configuration below.

Accessing the registry with your APPUiO Cloud user

You can access the registry with your APPUiO Cloud credentials with the following steps:

  1. Login to the desired zone and create docker credentials for the zone registry

    zone=ZONE-ID (1)
oc login https://api.${zone}.appuio.cloud:6443 (2)
oc whoami -t | docker login -u $(oc whoami) --password-stdin \
  registry.${zone}.appuio.cloud
    1 Replace ZONE-ID with the zone on which you want to access the registry. See the list of zones for available APPUiO Cloud zones.
    2 You may be asked to obtain an API token from oauth-openshift on the zone. If that’s the case, simply follow the link and copy the resulting login command from the browser before executing the next command.

  2. Push an image to the zone registry

    project=MYPROJECT (1)
docker pull busybox (2)
docker tag busybox registry.${zone}.appuio.cloud/${project}/busybox
docker push registry.${zone}.appuio.cloud/${project}/busybox
    1 Select the project to which you want to push the image.
    2 The example uses the latest busybox image to illustrate pushing an image to the registry. If you build your own images, just make sure you tag them as shown in the docker tag command.

  3. Check that the image has been pushed to the project

    $ oc -n ${project} get is
NAME      IMAGE REPOSITORY                                 TAGS     UPDATED
busybox   registry.<zone>.appuio.cloud/MYPROJECT/busybox   latest   25 seconds ago

Accessing the registry with a service account

To access the registry with a service account token, you need to grant the service account the registry-editor role. We recommend that you create a service account which you only use to access the registry per project. This way, you can be sure that your CI pipelines can only push images to the intended project.

  1. Create service account and add registry-editor to service account

    oc project MYPROJECT (1)
oc create serviceaccount image-pusher
oc policy add-role-to-user registry-editor -z image-pusher
oc apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
    name: image-pusher-secret
    annotations:
        kubernetes.io/service-account.name: image-pusher
type: kubernetes.io/service-account-token
EOF
    1 Select the project in which you want to create the service account.

  2. Extract the service account token

    token=$(oc get secret/image-pusher-secret -ogo-template='{{.data.token|base64decode}}')

  3. Use the extracted token to login to the registry

    echo "${token}" | docker login -u serviceaccount --password-stdin \
  registry.${zone}.appuio.cloud

You can use the extracted token and the command shown in the last step to push images to the zone’s registry from arbitrary CI pipelines.

Advanced user access configuration

If you want to implement more fine-grained control for registry access in your namespaces you can use the following:

  • To pull from the registry, accounts need the registry-viewer role.

  • To push to the registry, accounts need the registry-editor role.

Please be aware that users with role edit or admin for a namespace are granted both the registry-viewer and registry-editor roles. Additionally, users with role view for a namespace are granted the registry-viewer role.

See the OpenShift docs for details on how to configure those roles for users.