From f032efd0b00e4bf5764b5a0c09bf670bd555175d Mon Sep 17 00:00:00 2001 From: David C Wang Date: Wed, 3 Aug 2016 21:05:49 +0000 Subject: [PATCH] Add doc for configuring private docker registry Change-Id: I77ec5ced49236c81d5af1943632c4e5248a5fedd Partially-implements: blueprint documentation-initialization --- doc/source/index.rst | 1 + doc/source/private-registry.rst | 118 ++++++++++++++++++++++++++++++++ 2 files changed, 119 insertions(+) create mode 100644 doc/source/private-registry.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 140d96b61..06d8035e2 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -16,6 +16,7 @@ Contents: kubernetes-all-in-one quickstart multi-node + private-registry readme usage labels diff --git a/doc/source/private-registry.rst b/doc/source/private-registry.rst new file mode 100644 index 000000000..674561f32 --- /dev/null +++ b/doc/source/private-registry.rst @@ -0,0 +1,118 @@ +.. private-registry: + +============================================== +Kolla Kubernetes Private Docker Registry Guide +============================================== + +This guide documents how to configure the authentication and use of a +private registry within a Kubernetes cluster. The official Kubernetes +documentation may be found `here +`_. +Please note that several methods exist, and more than one may work for +your setup. + +`Specifying ImagePullSecrets on a Pod +`_ +is the one method which will work across all Kubernetes installations, +regardless of the cloud provider or mechanism for automatic node +replacement. This is the recommended configuration. + + +How It Works +============ + +There are two steps: + +- Create an ImagePullSecret. These instructions may differ based on + the docker registry provider. The two types of registry providers + currently covered by this guide include: + + - Standard Docker Registry with Username/Password Authentication + - GCR Google Container Registry + +- Patch the Kubernetes default service-account to add a reference to + the ImagePullSecret. By default and unless configured otherwise, + all Kubernetes pods are created under the default service-account. + Pods under the default service-account use the ImagePullSecret + credentials to authenticate and access the private docker registry. + + +Create the ImagePullSecret +========================== + +Based on the docker registry provider, follow the appropriate section +below to create the ImagePullSecret. + + +Standard Docker Registry with Username/Password Authentication +-------------------------------------------------------------- + +A typical docker registry only requires only username/password +authentication, without any other API keys or tokens (e.g. Docker +Hub). + +The Kubernetes official documentation for Creating a Secret with a +Docker Config may be found `here +`_. + +For the purposes of these instructions, create the ImagePullSecret to +be named ```private-docker-registry-secret```. + +:: + + # Create the ImagePullSecret named private-docker-registry-secret + # Be sure to replace the uppercase variables with your own. + kubectl create secret docker-registry private-docker-registry-secret \ + --docker-server=DOCKER_REGISTRY_SERVER \ + --docker-username=DOCKER_USER \ + --docker-password=DOCKER_PASSWORD \ + --docker-email=DOCKER_EMAIL + + +GCR Registry with Google Service Account Authentication +------------------------------------------------------- + +To allow any kubernetes cluster outside of Google Cloud to access the +GCR registry, the instuctions are a little more complex. These +instructions have been modified from `stackoverflow +`_. + +- Go to the Google Developer Console > Api Manager > Credentials, + click "Create credentials", and select "Service account key" +- Under "service account" select "new service account", name the new + key "gcr", and select JSON for the key type. +- Click on "Create" and the service-account key will be downloaded to your disk. +- You may want to save the key file, since there is no way to + re-download it from google. +- Rename the keyfile to be gcr-sa-key.json (GCR service account key), + for the purposes of these instructions. +- Using the keyfile, create the kubernetes secret named ```private-docker-registry-secret```:: + + # Create the docker-password from the file by stripping all + # newlines and squeezing whitespace. + DOCKER_PASSWORD=`cat gcr-sa-key.json | tr -s '[:space:]' | tr -d '\n'` + + # Create a Kubernetes secret named "private-docker-registry-secret" + kubectl create secret docker-registry private-docker-registry-secret \ + --docker-server "https://gcr.io" \ + --docker-username _json_key \ + --docker-email not@val.id \ + --docker-password="$DOCKER_PASSWORD" + + +Patch the Default Service-Account +================================= + +Patch the Kubernetes default service-account to add a reference to the +ImagePullSecret, after which pods under the default service-account +use the ImagePullSecret credentials to authenticate and access the +private docker registry. + +:: + + # Patch the default service account to include the new + # ImagePullSecret + kubectl patch serviceaccount default -p '{"imagePullSecrets":[{"name":"private-docker-registry-secret"}]}' + +Now, your kubernetes cluster should have access to the private docker registry. +