Skip to content

Commit fd19a0c

Browse files
author
Tim Bannister
committed
Migrate good practice for container images into Containers section
1 parent e220769 commit fd19a0c

File tree

2 files changed

+73
-41
lines changed

2 files changed

+73
-41
lines changed

content/en/docs/concepts/configuration/overview.md

Lines changed: 0 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -73,32 +73,6 @@ A desired state of an object is described by a Deployment, and if changes to tha
7373

7474
- You can manipulate labels for debugging. Because Kubernetes controllers (such as ReplicaSet) and Services match to Pods using selector labels, removing the relevant labels from a Pod will stop it from being considered by a controller or from being served traffic by a Service. If you remove the labels of an existing Pod, its controller will create a new Pod to take its place. This is a useful way to debug a previously "live" Pod in a "quarantine" environment. To interactively remove or add labels, use [`kubectl label`](/docs/reference/generated/kubectl/kubectl-commands#label).
7575

76-
## Container Images
77-
78-
The [imagePullPolicy](/docs/concepts/containers/images/#updating-images) and the tag of the image affect when the [kubelet](/docs/reference/command-line-tools-reference/kubelet/) attempts to pull the specified image.
79-
80-
- `imagePullPolicy: IfNotPresent`: the image is pulled only if it is not already present locally.
81-
82-
- `imagePullPolicy: Always`: every time the kubelet launches a container, the kubelet queries the container image registry to resolve the name to an image digest. If the kubelet has a container image with that exact digest cached locally, the kubelet uses its cached image; otherwise, the kubelet downloads (pulls) the image with the resolved digest, and uses that image to launch the container.
83-
84-
- `imagePullPolicy` is omitted and either the image tag is `:latest` or it is omitted: `imagePullPolicy` is automatically set to `Always`. Note that this will _not_ be updated to `IfNotPresent` if the tag changes value.
85-
86-
- `imagePullPolicy` is omitted and the image tag is present but not `:latest`: `imagePullPolicy` is automatically set to `IfNotPresent`. Note that this will _not_ be updated to `Always` if the tag is later removed or changed to `:latest`.
87-
88-
- `imagePullPolicy: Never`: the image is assumed to exist locally. No attempt is made to pull the image.
89-
90-
{{< note >}}
91-
To make sure the container always uses the same version of the image, you can specify its [digest](https://docs.docker.com/engine/reference/commandline/pull/#pull-an-image-by-digest-immutable-identifier); replace `<image-name>:<tag>` with `<image-name>@<digest>` (for example, `image@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2`). The digest uniquely identifies a specific version of the image, so it is never updated by Kubernetes unless you change the digest value.
92-
{{< /note >}}
93-
94-
{{< note >}}
95-
You should avoid using the `:latest` tag when deploying containers in production as it is harder to track which version of the image is running and more difficult to roll back properly.
96-
{{< /note >}}
97-
98-
{{< note >}}
99-
The caching semantics of the underlying image provider make even `imagePullPolicy: Always` efficient, as long as the registry is reliably accessible. With Docker, for example, if the image already exists, the pull attempt is fast because all image layers are cached and no image download is needed.
100-
{{< /note >}}
101-
10276
## Using kubectl
10377

10478
- Use `kubectl apply -f <directory>`. This looks for Kubernetes configuration in all `.yaml`, `.yml`, and `.json` files in `<directory>` and passes it to `apply`.

content/en/docs/concepts/containers/images.md

Lines changed: 73 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -39,14 +39,6 @@ There are additional rules about where you can place the separator
3939
characters (`_`, `-`, and `.`) inside an image tag.
4040
If you don't specify a tag, Kubernetes assumes you mean the tag `latest`.
4141

42-
{{< caution >}}
43-
You should avoid using the `latest` tag when deploying containers in production,
44-
as it is harder to track which version of the image is running and more difficult
45-
to roll back to a working version.
46-
47-
Instead, specify a meaningful tag such as `v1.42.0`.
48-
{{< /caution >}}
49-
5042
## Updating images
5143

5244
When you first create a {{< glossary_tooltip text="Deployment" term_id="deployment" >}},
@@ -57,13 +49,68 @@ specified. This policy causes the
5749
{{< glossary_tooltip text="kubelet" term_id="kubelet" >}} to skip pulling an
5850
image if it already exists.
5951

60-
If you would like to always force a pull, you can do one of the following:
52+
### Image pull policy
53+
54+
The `imagePullPolicy` for a container and the tag of the image affect when the
55+
[kubelet](/docs/reference/command-line-tools-reference/kubelet/) attempts to pull (download) the specified image.
56+
57+
Here's a list of the values you can set for `imagePullPolicy` and the effects
58+
these values have:
59+
60+
`IfNotPresent`
61+
: the image is pulled only if it is not already present locally.
6162

62-
- set the `imagePullPolicy` of the container to `Always`.
63-
- omit the `imagePullPolicy` and use `:latest` as the tag for the image to use;
64-
Kubernetes will set the policy to `Always`.
65-
- omit the `imagePullPolicy` and the tag for the image to use.
66-
- enable the [AlwaysPullImages](/docs/reference/access-authn-authz/admission-controllers/#alwayspullimages) admission controller.
63+
`Always`
64+
: every time the kubelet launches a container, the kubelet queries the container
65+
image registry to resolve the name to an image
66+
[digest](https://docs.docker.com/engine/reference/commandline/pull/#pull-an-image-by-digest-immutable-identifier). If the kubelet has a
67+
container image with that exact digest cached locally, the kubelet uses its cached
68+
image; otherwise, the kubelet pulls the image with the resolved digest,
69+
and uses that image to launch the container.
70+
71+
`Never`
72+
: the kubelet does not try fetching the image. If the image is somehow already present
73+
locally, the kubelet attempts to start the container; otherwise, startup fails.
74+
See [pre-pulled images](#pre-pulled-images) for more details.
75+
76+
The caching semantics of the underlying image provider make even
77+
`imagePullPolicy: Always` efficient, as long as the registry is reliably accessible.
78+
Your container runtime can notice that the image layers already exist on the node
79+
so that they don't need to be downloaded again.
80+
81+
{{< note >}}
82+
You should avoid using the `:latest` tag when deploying containers in production as
83+
it is harder to track which version of the image is running and more difficult to
84+
roll back properly.
85+
86+
Instead, specify a meaningful tag such as `v1.42.0`.
87+
{{< /note >}}
88+
89+
To make sure the Pod always uses the same version of a container image, you can specify
90+
the image's digest;
91+
replace `<image-name>:<tag>` with `<image-name>@<digest>`
92+
(for example, `image@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2`).
93+
94+
When using image tags, if the image registry were to change the code that the tag on that image represents, you might end up with a mix of Pods running the old and new code. An image digest uniquely identifies a specific version of the image, so Kubernetes runs the same code every time it starts a container with that image name and digest specified. Specifying an image fixes the code that you run so that a change at the registry cannot lead to that mix of versions.
95+
96+
There are third-party [admission controllers](/docs/reference/access-authn-authz/admission-controllers/)
97+
that mutate Pods (and pod templates) when they are created, so that the
98+
running workload is defined based on an image digest rather than a tag.
99+
That might be useful if you want to make sure that all your workload is
100+
running the same code no matter what tag changes happen at the registry.
101+
102+
#### Default image pull policy {#imagepullpolicy-defaulting}
103+
104+
When you (or a controller) submit a new Pod to the API server, your cluster sets the
105+
`imagePullPolicy` field when specific conditions are met:
106+
107+
- if you omit the `imagePullPolicy` field, and the tag for the container image is
108+
`:latest`, `imagePullPolicy` is automatically set to `Always`;
109+
- if you omit the `imagePullPolicy` field, and you don't specify the tag for the
110+
container image, `imagePullPolicy` is automatically set to `Always`;
111+
- if you omit the `imagePullPolicy` field, and you don't specify the tag for the
112+
container image that isn't `:latest`, the `imagePullPolicy` is automatically set to
113+
`IfNotPresent`.
67114

68115
{{< note >}}
69116
The value of `imagePullPolicy` of the container is always set when the object is
@@ -75,7 +122,17 @@ For example, if you create a Deployment with an image whose tag is _not_
75122
the pull policy of any object after its initial creation.
76123
{{< /note >}}
77124

78-
When `imagePullPolicy` is defined without a specific value, it is also set to `Always`.
125+
#### Required image pull
126+
127+
If you would like to always force a pull, you can do one of the following:
128+
129+
- Set the `imagePullPolicy` of the container to `Always`.
130+
- Omit the `imagePullPolicy` and use `:latest` as the tag for the image to use;
131+
Kubernetes will set the policy to `Always` when you submit the Pod.
132+
- Omit the `imagePullPolicy` and the tag for the image to use;
133+
Kubernetes will set the policy to `Always` when you submit the Pod.
134+
- Enable the [AlwaysPullImages](/docs/reference/access-authn-authz/admission-controllers/#alwayspullimages) admission controller.
135+
79136

80137
### ImagePullBackOff
81138

@@ -328,6 +385,7 @@ common use cases and suggested solutions.
328385
If you need access to multiple registries, you can create one secret for each registry.
329386
Kubelet will merge any `imagePullSecrets` into a single virtual `.docker/config.json`
330387

388+
331389
## {{% heading "whatsnext" %}}
332390

333391
* Read the [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/master/manifest.md).

0 commit comments

Comments
 (0)