Skip to content

Commit 631ed8d

Browse files
mohamed-rafrafmohamed-rafraf
authored
add kubeone mirror-images docs (kubermatic#1951)
1 parent 0ae8bbb commit 631ed8d

File tree

2 files changed

+86
-42
lines changed

2 files changed

+86
-42
lines changed

‎content/kubeone/main/guides/registry-configuration/_index.en.md‎

Lines changed: 43 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -37,36 +37,58 @@ This guide assumes that:
3737
If you don't have an image registry, you can check out the
3838
[Docker Registry][docker-reg-guide] as a possible solution.
3939

40-
## Preloading Images
40+
## Mirroring Images with `kubeone mirror-images`
4141

42-
Another prerequisites for this guide to work is that your image registry has
43-
all images needed for your cluster to work preloaded.
42+
KubeOne provides a built-in command `kubeone mirror-images` to simplify mirroring all required images (Kubernetes core components, CNI plugins, etc.) to your private registry. This command replaces the older `image-loader.sh` script and supports advanced filtering and multi-version mirroring.
4443

45-
To make this task easier, we provide the image loader script that:
44+
### Prerequisites
4645

47-
* pulls all images used by components deployed by KubeOne (CNI,
48-
metrics-server...) and Kubeadm (Kubernetes core components and CoreDNS)
49-
* re-tag those images so the image registry (e.g. `docker.io`) is replaced
50-
with the image registry provided by the user
51-
* push re-tagged images to your (mirror) image registry
46+
1. **Registry Setup**: Ensure your registry is accessible by all cluster nodes and supports TLS if using containerd.
47+
2. **Authentication**: The registry must allow unauthenticated access (support for credentials is planned for future releases).
48+
3. **KubeOne CLI**: Use KubeOne v1.5.0 or newer.
5249

53-
The image loader script (`image-loader.sh`) comes in the KubeOne release
54-
archive, under the `hack` directory. It can also be found on [GitHub in the
55-
`hack` directory][img-loader]. If you're downloading the script from GitHub,
56-
it's recommended to switch to the appropriate tag depending on which KubeOne
57-
version you're using.
50+
### Usage
5851

59-
Once you have downloaded the script, you can run it in the following way.
60-
Make sure to replace `KUBERNETES_VERSION` with the Kubernetes version you plan
61-
to use (without the `v` prefix), as well as, replace the `TARGET_REGISTRY` with
62-
the address to your image registry.
52+
The `kubeone mirror-images` command pulls, re-tags, and pushes images to your registry. Use the following syntax:
6353

54+
```bash
55+
kubeone mirror-images \
56+
[--filter base,optional,control-plane] \
57+
[--kubernetes-versions v1.29.4,v1.28.8] \
58+
[--insecure] # Allow pushing to insecure registries (HTTP) \
59+
--registry <your-registry>
6460
```
65-
KUBERNETES_VERSION=1.29.4 TARGET_REGISTRY=127.0.0.1:5000 ./image-loader.sh
61+
62+
#### Key Flags:
63+
- `--filter`: Select image groups (comma-separated):
64+
- `base`: Core images (OSM, DNS Cache, Calico, Machine-Controller).
65+
- `optional`: Add-ons like CCMs and CSI Drivers.
66+
- `control-plane`: Only Kubernetes core components (kube-apiserver, etcd, etc.).
67+
- `--kubernetes-versions`: Specify versions (comma-separated). If omitted, **all KubeOne-supported versions are mirrored**.
68+
- `--insecure`: Skip TLS verification for registries using HTTP (useful for local/insecure setups).
69+
70+
### Examples
71+
72+
#### 1. Mirror All Base Images for Specific Versions
73+
```bash
74+
kubeone mirror-images \
75+
--filter base \
76+
--kubernetes-versions v1.29.4,v1.28.8 \
77+
registry.example.com:5000
78+
```
79+
80+
#### 2. Mirror Only Control-Plane Images For All Supported Versions
81+
```bash
82+
kubeone mirror-images \
83+
--filter control-plane \
84+
registry.example.com:5000
6685
```
6786

68-
The preloading process can take a several minutes, depending on your
69-
connection speed.
87+
### Benefits of `kubeone mirror-images`
88+
- **Simpler Workflow**: No need to manually download or manage scripts.
89+
- **Multi-Version Support**: Mirror images for multiple Kubernetes versions in one command.
90+
- **Granular Control**: Use filters to mirror only the images you need.
91+
- **Automated Retagging**: Handles registry prefixes (e.g., `docker.io` → `registry.example.com`).
7092

7193
## Overriding Image Registries
7294

‎content/kubeone/v1.11/guides/registry-configuration/_index.en.md‎

Lines changed: 43 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -37,36 +37,58 @@ This guide assumes that:
3737
If you don't have an image registry, you can check out the
3838
[Docker Registry][docker-reg-guide] as a possible solution.
3939

40-
## Preloading Images
40+
## Mirroring Images with `kubeone mirror-images`
4141

42-
Another prerequisites for this guide to work is that your image registry has
43-
all images needed for your cluster to work preloaded.
42+
KubeOne provides a built-in command `kubeone mirror-images` to simplify mirroring all required images (Kubernetes core components, CNI plugins, etc.) to your private registry. This command replaces the older `image-loader.sh` script and supports advanced filtering and multi-version mirroring.
4443

45-
To make this task easier, we provide the image loader script that:
44+
### Prerequisites
4645

47-
* pulls all images used by components deployed by KubeOne (CNI,
48-
metrics-server...) and Kubeadm (Kubernetes core components and CoreDNS)
49-
* re-tag those images so the image registry (e.g. `docker.io`) is replaced
50-
with the image registry provided by the user
51-
* push re-tagged images to your (mirror) image registry
46+
1. **Registry Setup**: Ensure your registry is accessible by all cluster nodes and supports TLS if using containerd.
47+
2. **Authentication**: The registry must allow unauthenticated access (support for credentials is planned for future releases).
48+
3. **KubeOne CLI**: Use KubeOne v1.5.0 or newer.
5249

53-
The image loader script (`image-loader.sh`) comes in the KubeOne release
54-
archive, under the `hack` directory. It can also be found on [GitHub in the
55-
`hack` directory][img-loader]. If you're downloading the script from GitHub,
56-
it's recommended to switch to the appropriate tag depending on which KubeOne
57-
version you're using.
50+
### Usage
5851

59-
Once you have downloaded the script, you can run it in the following way.
60-
Make sure to replace `KUBERNETES_VERSION` with the Kubernetes version you plan
61-
to use (without the `v` prefix), as well as, replace the `TARGET_REGISTRY` with
62-
the address to your image registry.
52+
The `kubeone mirror-images` command pulls, re-tags, and pushes images to your registry. Use the following syntax:
6353

54+
```bash
55+
kubeone mirror-images \
56+
[--filter base,optional,control-plane] \
57+
[--kubernetes-versions v1.29.4,v1.28.8] \
58+
[--insecure] # Allow pushing to insecure registries (HTTP) \
59+
--registry <your-registry>
6460
```
65-
KUBERNETES_VERSION=1.29.4 TARGET_REGISTRY=127.0.0.1:5000 ./image-loader.sh
61+
62+
#### Key Flags:
63+
- `--filter`: Select image groups (comma-separated):
64+
- `base`: Core images (OSM, DNS Cache, Calico, Machine-Controller).
65+
- `optional`: Add-ons like CCMs and CSI Drivers.
66+
- `control-plane`: Only Kubernetes core components (kube-apiserver, etcd, etc.).
67+
- `--kubernetes-versions`: Specify versions (comma-separated). If omitted, **all KubeOne-supported versions are mirrored**.
68+
- `--insecure`: Skip TLS verification for registries using HTTP (useful for local/insecure setups).
69+
70+
### Examples
71+
72+
#### 1. Mirror All Base Images for Specific Versions
73+
```bash
74+
kubeone mirror-images \
75+
--filter base \
76+
--kubernetes-versions v1.29.4,v1.28.8 \
77+
registry.example.com:5000
78+
```
79+
80+
#### 2. Mirror Only Control-Plane Images For All Supported Versions
81+
```bash
82+
kubeone mirror-images \
83+
--filter control-plane \
84+
registry.example.com:5000
6685
```
6786

68-
The preloading process can take a several minutes, depending on your
69-
connection speed.
87+
### Benefits of `kubeone mirror-images`
88+
- **Simpler Workflow**: No need to manually download or manage scripts.
89+
- **Multi-Version Support**: Mirror images for multiple Kubernetes versions in one command.
90+
- **Granular Control**: Use filters to mirror only the images you need.
91+
- **Automated Retagging**: Handles registry prefixes (e.g., `docker.io` → `registry.example.com`).
7092

7193
## Overriding Image Registries
7294

0 commit comments

Comments
 (0)