Merge pull request #60173 from jpbetz/migration-downgrade-docs

cluster/images/etcd/README.md

@@ -5,6 +5,24 @@ This is a small etcd image used in Kubernetes setups where `etcd` is deployed as
 For `amd64`, official `etcd` and `etcdctl` binaries are downloaded from Github to maintain official support.
 For other architectures, `etcd` is cross-compiled from source. Arch-specific `busybox` images serve as base images.
 
+### Upgrading and Downgrading
+
+To upgrade to a newer etcd version, or to downgrade to the previous minor
+version, always run `/usr/local/bin/migrate-if-needed.sh` before starting the
+etcd server.
+
+`migrate-if-needed.sh` writes a `version.txt` file to track the "current" version
+of etcd that was used to persist data to disk. A "target" version may also be provided
+by the `TARGET_STORAGE` (e.g. "etcd3") and `TARGET_VERSION` (e.g. "3.2.11" )
+environment variables. If the persisted version differs from the target version,
+`migrate-if-needed.sh` will migrate the data from the current to the target
+version.
+
+Upgrades to any target version are supported. The data will be automatically upgraded
+in steps to each minor version until the target version is reached.
+
+Downgrades to the previous minor version of the 3.x series and from 3.0 to 2.3.7 are supported.
+
 #### How to release
 
 First, run the migration and rollback tests.