Merge pull request #29946 from neolit123/1.23-update-docs-about-image-repository

kubeadm: add more details about air-gapped and custom images

Author: k8s-ci-robot

content/en/docs/reference/setup-tools/kubeadm/kubeadm-init.md

@@ -142,6 +142,22 @@ For information about enabling IPVS mode with kubeadm see:
 For information about passing flags to control plane components see:
 - [control-plane-flags](/docs/setup/production-environment/tools/kubeadm/control-plane-flags/)
 
+### Running kubeadm without an Internet connection {#without-internet-connection}
+
+For running kubeadm without an Internet connection you have to pre-pull the required control-plane images.
+
+You can list and pull the images using the `kubeadm config images` sub-command:
+
+```shell
+kubeadm config images list
+kubeadm config images pull
+```
+
+You can pass `--config` to the above commands with a [kubeadm configuration file](#config-file)
+to control the `kubernetesVersion` and `imageRepository` fields.
+
+All default `k8s.gcr.io` images that kubeadm requires support multiple architectures.
+
 ### Using custom images {#custom-images}
 
 By default, kubeadm pulls images from `k8s.gcr.io`. If the
@@ -151,13 +167,24 @@ requested Kubernetes version is a CI label (such as `ci/latest`)
 You can override this behavior by using [kubeadm with a configuration file](#config-file).
 Allowed customization are:
 
+* To provide `kubernetesVersion` which affects the version of the images.
 * To provide an alternative `imageRepository` to be used instead of
   `k8s.gcr.io`.
-* To set `useHyperKubeImage` to `true` to use the HyperKube image.
-* To provide a specific `imageRepository` and `imageTag` for etcd or DNS add-on.
+* To provide a specific `imageRepository` and `imageTag` for etcd or CoreDNS.
+
+Image paths between the default `k8s.gcr.io` and a custom repository specified using
+`imageRepository` may differ for backwards compatibility reasons. For example,
+one image might have a subpath at `k8s.gcr.io/subpath/image`, but be defaulted
+to `my.customrepository.io/image` when using a custom repository.
 
-Please note that the configuration field `kubernetesVersion` or the command line flag
-`--kubernetes-version` affect the version of the images.
+To ensure you push the images to your custom repository in paths that kubeadm
+can consume, you must:
+
+* Pull images from the defaults paths at `k8s.gcr.io` using `kubeadm config images {list|pull}`.
+* Push images to the paths from `kubeadm config images list --config=config.yaml`,
+where `config.yaml` contains the custom `imageRepository`, and/or `imageTag`
+for etcd and CoreDNS.
+* Pass the same `config.yaml` to `kubeadm init`.
 
 ### Uploading control-plane certificates to the cluster
 
@@ -209,19 +236,6 @@ value to the kubelet.
 
 Be aware that overriding the hostname can [interfere with cloud providers](https://github.com/kubernetes/website/pull/8873).
 
-### Running kubeadm without an internet connection
-
-For running kubeadm without an internet connection you have to pre-pull the required control-plane images.
-
-You can list and pull the images using the `kubeadm config images` sub-command:
-
-```shell
-kubeadm config images list
-kubeadm config images pull
-```
-
-All images that kubeadm requires such as `k8s.gcr.io/kube-*`, `k8s.gcr.io/etcd` and `k8s.gcr.io/pause` support multiple architectures.
-
 ### Automating kubeadm
 
 Rather than copying the token you obtained from `kubeadm init` to each node, as

content/en/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md

@@ -83,6 +83,19 @@ kubeadm to tell it what to do. This crashloop is expected and normal.
 After you initialize your control-plane, the kubelet runs normally.
 {{< /note >}}
 
+### Preparing the required container images
+
+This step is optional and only applies in case you wish `kubeadm init` and `kubeadm join`
+to not download the default container images which are hosted at `k8s.gcr.io`.
+
+Kubeadm has commands that can help you pre-pull the required images
+when creating a cluster without an internet connection on its nodes.
+See [Running kubeadm without an internet connection](/docs/reference/setup-tools/kubeadm/kubeadm-init#without-internet-connection) for more details.
+
+Kubeadm allows you to use a custom image repository for the required images.
+See [Using custom images](docs/reference/setup-tools/kubeadm/kubeadm-init#custom-images)
+for more details.
+
 ### Initializing your control-plane node
 
 The control-plane node is the machine where the control plane components run, including
@@ -108,8 +121,6 @@ with the default gateway to set the advertise address for this particular contro
 To use a different network interface, specify the `--apiserver-advertise-address=<ip-address>` argument
 to `kubeadm init`. To deploy an IPv6 Kubernetes cluster using IPv6 addressing, you
 must specify an IPv6 address, for example `--apiserver-advertise-address=fd00::101`
-1. (Optional) Run `kubeadm config images pull` prior to `kubeadm init` to verify
-connectivity to the gcr.io container image registry.
 
 To initialize the control-plane node run: