mirror of https://github.com/k3s-io/k3s
157 lines
6.6 KiB
Markdown
157 lines
6.6 KiB
Markdown
# Images
|
|
Each container in a pod has its own image. Currently, the only type of image supported is a [Docker Image](https://docs.docker.com/userguide/dockerimages/).
|
|
|
|
You create your Docker image and push it to a registry before referring to it in a kubernetes pod.
|
|
|
|
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 Registry
|
|
- 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.
|
|
|
|
|
|
### Using Google Container Registry
|
|
|
|
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 pods in a cluster will have read access to images in this registry.
|
|
|
|
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.
|
|
|
|
All pods will have read access to any pre-pulled images.
|
|
|
|
### Specifying ImagePullKeys on a Pod
|
|
Kubernetes supports specifying registry keys on a pod.
|
|
|
|
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.
|
|
|
|
|
|
[]()
|