From b833fb3ffd8353ff99d50a63c5d64da27a681374 Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Mon, 1 Jul 2019 11:25:33 -0700 Subject: [PATCH] Add detail on using private registry with kubectl --- .../en/k8s-in-rancher/registries/_index.md | 87 +++++++++++++++---- 1 file changed, 70 insertions(+), 17 deletions(-) diff --git a/content/rancher/v2.x/en/k8s-in-rancher/registries/_index.md b/content/rancher/v2.x/en/k8s-in-rancher/registries/_index.md index 7cdc97f89ac..44a31d3a61d 100644 --- a/content/rancher/v2.x/en/k8s-in-rancher/registries/_index.md +++ b/content/rancher/v2.x/en/k8s-in-rancher/registries/_index.md @@ -6,14 +6,14 @@ aliases: --- Registries are Kubernetes secrets containing credentials used to authenticate with [private Docker registries](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/). -The word "registry" can refer to two things: +The word "registry" can mean two things, depending on whether it is used to refer to a Docker or Kubernetes registry: -- A ** Docker registry** contains Docker images that you can pull in order to use them in your deployment. The registry is a stateless, scalable server side application that stores and lets you distribute Docker images. -- The Kubernetes secret that your deployment uses to authenticate with a Docker registry +- A **Docker registry** contains Docker images that you can pull in order to use them in your deployment. The registry is a stateless, scalable server side application that stores and lets you distribute Docker images. +- The **Kubernetes registry** is a secret that your deployment uses to authenticate with a Docker registry. -Deployments use the secrets in the Kubernetes registry to authenticate with a private Docker registry and then pull a Docker image hosted on it. +Deployments use the Kubernetes registry secret to authenticate with a private Docker registry and then pull a Docker image hosted on it. -Currently, credentials are pulled automatically only if the workload is created in the Rancher UI and not when it is created via kubectl. +Currently, deployments pull the private registry credentials automatically only if the workload is created in the Rancher UI and not when it is created via kubectl. >**Prerequisites:** You must have a [private registry](https://docs.docker.com/registry/deploying/) available to use. @@ -27,30 +27,83 @@ Currently, credentials are pulled automatically only if the workload is created 1. Select a **Scope** for the registry. You can either make the registry available for the entire project or a single [namespace]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#namespaces). -1. Select the website that hosts your private registry. Then enter credentials that authenticate with the registry. +1. Select the website that hosts your private registry. Then enter credentials that authenticate with the registry. For example, if you use DockerHub, provide your DockerHub username and password. 1. Click **Save**. -**Result:** Your secret is added to the project or namespace, depending on the scope you chose. You can view the secret in the Rancher UI from the **Resources > Registries** view. Any workload that you create in the Rancher UI will be able to access your registry if it is within the registry's scope. +**Result:** -## How to Deploy Workloads with an Image from a Private Registry +- Your secret is added to the project or namespace, depending on the scope you chose. +- You can view the secret in the Rancher UI from the **Resources > Registries** view. +- Any workload that you create in the Rancher UI will have the credentials to access the registry if the workload is within the registry's scope. + +## Using a Private Registry You can deploy a workload with an image from a private registry through the Rancher UI, or with `kubectl`. -### Deploying the Workload with the Rancher UI +### Using the Private Registry with the Rancher UI -When you create the workload, in the **Docker Image** field, you need to enter the URL of the path to the Docker image in your private registry. +To deploy a workload with an image from your private registry, -You don't need to enter your private registry credentials because the pod automatically has access to the Kubernetes registry secret if the workload is in the scope of a registry that you added. +1. Go to the project view, +1. Go to the **Workloads** tab. +1. Click **Deploy.** +1. Enter a unique name for the workload and choose a namespace. +1. In the **Docker Image** field, enter the URL of the path to the Docker image in your private registry. For example, if your private registry is on Quay.io, you could use `quay.io//`. +1. Click **Launch.** -### Deploying the Workload with kubectl +**Result:** Your deployment should launch, authenticate using the private registry credentials you added in the Rancher UI, and pull the Docker image that you specified. -When you create the workload using `kubectl`, you need to configure the pod so that its YAML has: +### Using the Private Registry with kubectl -- The path to the container image in the private registry, for example `quay.io/$(registry owner's name)/$(name of registry)` -- The name of the Kubernetes secret that has the private registry credentials +When you create the workload using `kubectl`, you need to configure the pod so that its YAML has the path to the private registry. You also have to specify the registry secret because the pod only automatically gets access to the private registry credentials if it is created in the Rancher UI. -To reference this secret in the Pod yaml, you will add the field `imagePullSecrets` with the name of the secret. For more information, refer to the Kubernetes documentation on [creating a pod that uses your secret.](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#create-a-pod-that-uses-your-secret) +Below is an example `pod.yml` for a workload that uses an image from a private registry. In this example, the pod uses an image from Quay.io, and the .yml specifies the path to the image. The pod authenticates with the registry using credentials stored in a Kubernetes secret called `testquay`, which is specified in `spec.imagePullSecrets.name`: -The reason you have to add the Kubernetes secret manually is that the pod only automatically gets the private registry credentials if you create it in the Rancher UI. +``` +apiVersion: v1 +kind: Pod +metadata: + name: private-reg +spec: + containers: + - name: private-reg-container + image: quay.io// + imagePullSecrets: + - name: testquay +``` +You can use `kubectl` to create the secret with the private registry credentials. In this example, the secret is named `testquay`: + +``` +kubectl create secret docker-registry testquay \ + --docker-server=quay.io \ + --docker-username= \ + --docker-password= +``` + +To see how the secret is stored in Kubernetes, you can use this command: + +``` +kubectl get secret testquay --output="jsonpath={.data.\.dockerconfigjson}" | base64 --decode +``` + +The result looks like this: + +``` +{"auths":{"quay.io":{"username":"","password":"","auth":"c291bXlhbGo6dGVzdGFiYzEyMw=="}}} +``` + +After the workload is deployed, you can check if the image was pulled successfully: + +``` +kubectl get events +``` +The result should look like this: +``` +14s Normal Scheduled Pod Successfully assigned default/private-reg2 to minikube +11s Normal Pulling Pod pulling image "quay.io//" +10s Normal Pulled Pod Successfully pulled image "quay.io//" +``` + +For more information, refer to the Kubernetes documentation on [creating a pod that uses your secret.](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#create-a-pod-that-uses-your-secret) \ No newline at end of file