Merge pull request #205 from appuio/how-to/image-pull-secret

Add how-to for setting up an image pull secret

Author: simu

docs/modules/ROOT/nav.adoc

@@ -93,6 +93,7 @@
 
 .Registry
 * xref:how-to/use-integrated-registry.adoc[]
+* xref:how-to/setup-image-pull-secret.adoc[]
 
 .DevOps and CI/CD
 * xref:how-to/use-oc-cli.adoc[oc]

docs/modules/ROOT/pages/how-to/setup-image-pull-secret.adoc

@@ -0,0 +1,65 @@
+= Setting up an image pull secret for a namespace
+
+Some external container registries (for example DockerHub) have fairly strict rate limits for unauthenticated pulls.
+We strongly recommend setting up an image pull secret for such registries.
+This page will guide you through the process of setting up an image pull secret for all workloads in a namespace.
+
+TIP: Since DockerHub is the most prominent container registry that enforces strict pull rate limits for unauthenticated pulls, we'll illustrate the process with DockerHub.
+
+== Prerequisites
+
+* You have a token for authenticating with the registry
+** for example a https://docs.docker.com/security/for-developers/access-tokens/["Personal access token"] for DockerHub
+* You have `admin` access to the namespace in which you want to setup the image pull secret
+
+== Creating the image pull secret
+
+. Login to the desired zone 
++
+[source,bash]
+----
+zone=ZONE-ID <1>
+namespace=NAMESPACE <2>
+oc login --web https://api.${zone}.appuio.cloud:6443 <3>
+oc project $namespace <4>
+----
+<1> Replace `ZONE-ID` with the zone on which you want to access the registry.
+See the https://portal.appuio.cloud/zones[list of zones] for available {product} zones.
+<2> The namespace in which you want to create the image pull secret.
+<3> `oc login --web` may open a window or tab in your browser if you're not currently logged in on the zone.
+<4> Select the target namespace as the current project.
+This allows us to run commands targeting that namespace without `-n $namespace`.
+
+. Create the image pull secret from your token
++
+[source,bash]
+----
+REGISTRY='https://index.docker.io/v1/' <1>
+USERNAME=<username> <2>
+TOKEN=<token> <3>
+SECRET_NAME=image-pull-secret <4>
+oc create secret docker-registry "$SECRET_NAME" \
+  --docker-username="$USERNAME" --docker-password="$TOKEN"
+----
+<1> The URL of the registry.
+Change this if you're setting up a pull secret for a registry other than DockerHub.
+<2> The token for authenticating with the registry.
+For example a https://docs.docker.com/security/for-developers/access-tokens/["Personal access token"] for DockerHub.
+<3> Your user name on the registry.
+Check your registry's documentation for details on how to login using a token.
+For DockerHub, provide your Docker ID.
+<4> You can choose any name for the pull secret, but you must use the same name in the next section.
+
+== Link the image pull secret to the default service account in the namespace
+
+TIP: If you're using custom service accounts to run your workloads, repeat the instruction in this section for each service account that needs to pull images from the registry.
+
+. Add the image pull secret to the `default` service account
++
+[source,bash]
+----
+SERVICEACCOUNT=default <1>
+oc secrets link "$SERVICEACCOUNT" "$SECRET_NAME" --for=pull
+----
+<1> We link the pull secret to the `default` service account in the namespace.
+This is the service account that's used to run workloads when you don't specify a custom service account.