k8s.io/kubernetes@v1.31.0-alpha.0.0.20240520171757-56147500dadc/cluster/images/etcd/README.md (about)

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