1### registry.k8s.io/etcd docker image
2
3Provides docker images containing etcd and etcdctl binaries for multiple etcd
4version as well as a migration operator utility for upgrading and downgrading
5etcd--it's data directory in particular--to a target version.
6
7#### Versioning
8
9Each `registry.k8s.io/etcd` docker image is tagged with an version string of the form
10`<etcd-version>-<image-revision>`, e.g. `3.0.17-0`. The etcd version is the
11SemVer of latest etcd version available in the image. The image revision
12distinguishes between docker images with the same lastest etcd version but
13changes (bug fixes and backward compatible improvements) to the migration
14utility bundled with the image.
15
16In addition to the latest etcd version, each `registry.k8s.io/etcd` image contains
17etcd and etcdctl binaries for older versions of etcd. These are used by the
18migration operator utility when performing downgrades and multi-step upgrades,
19but can also be used as the etcd target version.
20
21#### Usage
22
23Always run `/usr/local/bin/migrate` (or the
24`/usr/local/bin/migrate-if-needed.sh` wrapper script) before starting the etcd
25server. On Windows, run `C:\bin\migrate.exe` (or the `C:\bin\migrate-if-needed.bat
26wrapper script`).
27
28`migrate` writes a `version.txt` file to track the "current" version
29of etcd that was used to persist data to disk. A "target" version may also be provided
30by the `TARGET_STORAGE` (e.g. "etcd3") and `TARGET_VERSION` (e.g. "3.4.13" )
31environment variables. If the persisted version differs from the target version,
32`migrate-if-needed.sh` will migrate the data from the current to the target
33version.
34
35Upgrades to any target version are supported. The data will be automatically upgraded
36in steps to each minor version until the target version is reached.
37
38Downgrades to the previous minor version of the 3.x series is supported.
39
40#### Permissions
41
42By default, `migrate` will write data directory files with default permissions
43according to the umask it is run with. When run in the published
44`registry.k8s.io/etcd` images the default umask is 0022 which will result in 0755
45directory permissions and 0644 file permissions.
46
47#### Cross building
48
49For `amd64`, official `etcd` and `etcdctl` binaries are downloaded from Github
50to maintain official support. For other architectures, `etcd` is cross-compiled
51from source. Arch-specific `debian` images serve as base images.
52
53Windows images can be built on Linux nodes due to `docker buildx`, but they will
54only be created and pushed when using the `all-push` make target.
55
56#### How to release
57
58First, update `ETCD_VERSION` and `REVSION` in the `Makefile`.
59
60Next, build and test the image:
61
62```console
63$ make build test
64```
65
66Last, build and push the docker images for all supported architectures.
67
68```console
69# Build images for all the architecture and push the manifest image as well
70$ make all-push
71
72# Build images for all the architecture
73$ make all-build
74
75# Build image for target architecture(default=amd64)
76$ make build ARCH=ppc64le
77```
78
79If you don't want to push the images, run `make` or `make build` instead
View as plain text