mirror of
https://github.com/k3s-io/kubernetes.git
synced 2025-07-31 23:37:01 +00:00
Document imagePullSecrets
This commit is contained in:
Eric Tune
parent
dafe79e5de
commit
7658071ef8
143
docs/images.md
143
docs/images.md
@ -5,31 +5,152 @@ You create your Docker image and push it to a registry before referring to it in
|
||||
|
||||
The `image` property of a container supports the same syntax as the `docker` command does, including private registries and tags.
|
||||
|
||||
## Updating Images
|
||||
|
||||
The default pull policy is `PullIfNotPresent` which causes the Kubelet to not
|
||||
pull an image if it already exists. If you would like to always force a pull
|
||||
you must set a pull image policy of `PullAlways` or specify a `:latest` tag on
|
||||
your image.
|
||||
|
||||
## Using a Private Registry
|
||||
Private registries may require keys to read images from them.
|
||||
Credentials can be provided in several ways:
|
||||
- Using Google Container Registy
|
||||
- Per-cluster
|
||||
- automatically configured on GCE/GKE
|
||||
- all pods can read the project's private registry
|
||||
- Configuring Nodes to Authenticate to a Private Registry
|
||||
- all pods can read any configured private registries
|
||||
- requires node configuration by cluster administrator
|
||||
- Pre-pulling Images
|
||||
- all pods can use any images cached on a node
|
||||
- requires root access to all nodes to setup
|
||||
- Specifying ImagePullKeys on a Pod
|
||||
- only pods which provide own keys can access the private registry
|
||||
Each option is described in more detail below.
|
||||
|
||||
|
||||
### Google Container Registry
|
||||
Kubernetes has native support for the [Google Container Registry](https://cloud.google.com/tools/container-registry/), when running on Google Compute Engine. If you are running your cluster on Google Compute Engine or Google Container Engine, simply use the full image name (e.g. gcr.io/my_project/image:tag) and the kubelet will automatically authenticate and pull down your private image.
|
||||
### Using Google Container Registry
|
||||
|
||||
### Other Private Registries
|
||||
Docker stores keys for private registries in a `.dockercfg` file. Create a config file by running `docker login <registry>.<domain>` and then copying the resulting `.dockercfg` file to the kubelet working dir.
|
||||
The kubelet working dir varies by cloud provider. It is `/` on GCE and `/home/core` on CoreOS. You can determine the working dir by running this command:
|
||||
`sudo ls -ld /proc/$(pidof kubelet)/cwd` on a kNode.
|
||||
Kubernetes has native support for the [Google Container
|
||||
Registry (GCR)](https://cloud.google.com/tools/container-registry/), when running on Google Compute
|
||||
Engine (GCE). If you are running your cluster on GCE or Google Container Engine (GKE), simply
|
||||
use the full image name (e.g. gcr.io/my_project/image:tag).
|
||||
|
||||
All users of the cluster will have access to any private registry in the `.dockercfg`.
|
||||
All pods in a cluster will have read access to images in this registry.
|
||||
|
||||
## Preloading Images
|
||||
The kubelet kubelet will authenticate to GCR using the instance's
|
||||
Google service account. The service account on the instance
|
||||
will have a `https://www.googleapis.com/auth/devstorage.read_only`,
|
||||
so it can pull from the project's GCR, but not push.
|
||||
|
||||
### Configuring Nodes to Authenticate to a Private Registry
|
||||
Docker stores keys for private registries in a `.dockercfg` file. Create a config file by running
|
||||
`docker login <registry>.<domain>` and then copy the resulting `.dockercfg` file to the root user's
|
||||
`$HOME` directory (e.g. `/root/.dockercfg`) on each node in the cluster.
|
||||
|
||||
You must ensure all nodes in the cluster have the same `.dockercfg`. Otherwise, pods will run on
|
||||
some nodes and fail to run on others. For example, if you use node autoscaling, then each instance
|
||||
template needs to include the `.dockercfg` or mount a drive that contains it.
|
||||
|
||||
All pods will have read access to images in any private registry with keys in the `.dockercfg`.
|
||||
|
||||
### Pre-pulling Images
|
||||
|
||||
Be default, the kubelet will try to pull each image from the specified registry.
|
||||
However, if the `imagePullPolicy` property of the container is set to `IfNotPresent` or `Never`,
|
||||
then a local image is used (preferentially or exclusively, respectively).
|
||||
|
||||
If you want to rely on pre-pulled images as a substitute for registry authentication,
|
||||
you must ensure all nodes in the cluster have the same pre-pulled images.
|
||||
|
||||
This can be used to preload certain images for speed or as an alternative to authenticating to a private registry.
|
||||
|
||||
Pull Policy is per-container, but any user of the cluster will have access to all local images.
|
||||
All pods will have read access to any pre-pulled images.
|
||||
|
||||
## Updating Images
|
||||
### Specifying ImagePullKeys on a Pod
|
||||
Kubernetes supports specifying registry keys on a pod.
|
||||
|
||||
The default pull policy is `PullIfNotPresent` which causes the Kubelet to not pull an image if it already exists. If you would like to always force a pull you must set a pull image policy of `PullAlways` or specify a `:latest` tag on your image.
|
||||
First, create a `.dockercfg`, such as running `docker login <registry.domain>`.
|
||||
Then put the resulting `.dockercfg` file into a [secret resource](../docs/secret.md). For example:
|
||||
```
|
||||
cat > dockercfg <<EOF
|
||||
{
|
||||
"https://docker.io/thisisfake": {
|
||||
"email": "bob@example.com",
|
||||
"auth": "secret"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
$ cat dockercfg | base64
|
||||
eyAKICAgImh0dHBzOi8vZG9ja2VyLmlvL3RoaXNpc2Zha2UiOiB7IAogICAgICJlbWFpbCI6ICJib2JAZXhhbXBsZS5jb20iLCAKICAgICAiYXV0aCI6ICJzZWNyZXQiIAogICB9Cn0K
|
||||
|
||||
cat > secret.json <<EOF
|
||||
{
|
||||
"apiVersion": "v1",
|
||||
"kind": "Secret",
|
||||
"metadata" : {
|
||||
"name": "myregistrykey",
|
||||
},
|
||||
"type": "kubernetes.io/dockercfg",
|
||||
"data": {
|
||||
".dockercfg":
|
||||
"eyAKICAgImh0dHBzOi8vZG9ja2VyLmlvL3RoaXNpc2Zha2UiOiB7IAogICAgICJlbWFpbCI6ICJib2JAZXhhbXBsZS5jb20iLCAKICAgICAiYXV0aCI6ICJzZWNyZXQiIAogICB9Cn0K",
|
||||
}
|
||||
}
|
||||
EOF
|
||||
This process only needs to be done one time (per namespace).
|
||||
|
||||
$ kubectl create -f secret.json
|
||||
secrets/myregistrykey
|
||||
```
|
||||
|
||||
Now, you can create pods which reference that secret by adding an `imagePullSecrets`
|
||||
section to a pod definition.
|
||||
```
|
||||
apiVersion: v1
|
||||
kind: Pod
|
||||
metadata:
|
||||
name: foo
|
||||
spec:
|
||||
containers:
|
||||
- name: foo
|
||||
image: registry.example.com/bar/fo
|
||||
imagePullSecrets:
|
||||
- name: myregistrykey
|
||||
```
|
||||
This needs to be done for each pod that is using a private registry.
|
||||
However, setting of this field can be automated by setting the imagePullSecrets
|
||||
in a [serviceAccount](../docs/service_accounts.md) resource.
|
||||
|
||||
Currently, all pods will potentially have read access to any images which were
|
||||
pulled using imagePullSecrets. That is, imagePullSecrets does *NOT* protect your
|
||||
images from being seen by other users in the cluster. Our intent
|
||||
is to fix that.
|
||||
|
||||
### Use Cases
|
||||
There are a number of solutions for configuring private registries. Here are some
|
||||
common use cases and suggested solutions.
|
||||
|
||||
1. Cluster running only non-proprietary (e.g open-source) images. No need to hide images.
|
||||
- Use public images on the Docker hub.
|
||||
- no configuration required
|
||||
- on GCE/GKE, a local mirror is automatically used for improved speed and availability
|
||||
1. Cluster running some proprietary images which should be hidden to those outside the company, but
|
||||
visible to all cluster users.
|
||||
- Use a hosted private [Docker registry](https://docs.docker.com/registry/)
|
||||
- may be hosted on the [Docker Hub](https://hub.docker.com/account/signup/), or elsewhere.
|
||||
- manually configure .dockercfg on each node as described above
|
||||
- Or, run an internal private registry behind your firewall with open read access.
|
||||
- no kubernetes configuration required
|
||||
- Or, when on GCE/GKE, use the project's Google Container Registry.
|
||||
- will work better with cluster autoscaling than manual node configuration
|
||||
- Or, on a cluster where changing the node configuration is inconvenient, use `imagePullSecrets`.
|
||||
1. Cluster with a proprietary images, a few of which require stricter access control
|
||||
- Move sensitive data into a "Secret" resource, instead of packaging it in an image.
|
||||
- DO NOT use imagePullSecrets for this use case yet.
|
||||
1. A multi-tenant cluster where each tenant needs own private registry
|
||||
- NOT supported yet.
|
||||
|
||||
|
||||
[]()
|
||||
|
||||
Loading…
Reference in New Issue
Block a user