Skip to content

Commit 282cc69

Browse files
ahrtrahrtr
authored
Merge pull request #19717 from joshjms/update-etcd-steps
Summarize steps to update etcd version in Kubernetes
2 parents c5a5afd + 0cec47a commit 282cc69

File tree

1 file changed

+185
-0
lines changed

1 file changed

+185
-0
lines changed

‎Documentation/contributor-guide/bump_etcd_version_k8s.md

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# Bump etcd Version in Kubernetes
2+
3+
This guide will walk through the update of etcd in Kubernetes to a new version (`kubernetes/kubernetes` repository).
4+
5+
You can use this [issue](https://github.com/kubernetes/kubernetes/issues/131101) as a reference when updating the etcd version in Kubernetes.
6+
7+
Bumping the etcd version in Kubernetes consists of two steps.
8+
9+
* Bump etcd client SDK
10+
* Bump etcd image
11+
12+
> The commented lines in this document signifies the line to be changed
13+
14+
## Bump etcd client SDK
15+
16+
> Reference: [link](https://github.com/kubernetes/kubernetes/pull/131103)
17+
18+
You can refer to the guide [here](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/vendor.md) under the **Adding or updating a dependency** section.
19+
20+
1. Get all the etcd modules used in Kubernetes.
21+
22+
```bash
23+
$ grep 'go.etcd.io/etcd/' go.mod | awk '{print $1}'
24+
go.etcd.io/etcd/api/v3
25+
go.etcd.io/etcd/client/pkg/v3
26+
go.etcd.io/etcd/client/v3
27+
go.etcd.io/etcd/client/v2
28+
go.etcd.io/etcd/pkg/v3
29+
go.etcd.io/etcd/raft/v3
30+
go.etcd.io/etcd/server/v3
31+
```
32+
33+
2. For each module, in the root directory of the `kubernetes/kubernetes` repository, fetch the new version in `go.mod` using the following command (using `client/v3` as an example):
34+
35+
```bash
36+
hack/pin-dependency.sh go.etcd.io/etcd/client/v3 NEW_VERSION
37+
```
38+
39+
3. Rebuild the `vendor` directory and update the `go.mod` files for all staging repositories using the command below. This automatically updates the licenses.
40+
41+
```bash
42+
hack/update-vendor.sh
43+
```
44+
45+
4. Check if the new dependency requires newer versions of existing dependencies we have pinned. You can check this by:
46+
47+
* Running `hack/lint-dependencies.sh` against your branch and against `master` and comparing the results.
48+
* Checking if any new `replace` directives were added to `go.mod` files of components inside the staging directory.
49+
50+
## Bump etcd image
51+
52+
### Build etcd image
53+
54+
> Reference: [link 1](https://github.com/kubernetes/kubernetes/pull/131105) [link 2](https://github.com/kubernetes/kubernetes/pull/131126)
55+
56+
1. In `build/dependencies.yaml`, update the `version` of `etcd-image` and `golang: etcd release version` to the new version.
57+
58+
```yaml
59+
- name: "etcd-image"
60+
# version: 3.5.17
61+
version: 3.5.21
62+
refPaths:
63+
- path: cluster/images/etcd/Makefile
64+
match: BUNDLED_ETCD_VERSIONS\?|
65+
```
66+
67+
2. In `cluster/images/etcd/Makefile`, include the new version in `BUNDLED_ETCD_VERSIONS` and update the `LATEST_ETCD_VERSION` as well (the image tag will be generated from the `LATEST_ETCD_VERSION`). Update `GOLANG_VERSION` if necessary.
68+
69+
```Makefile
70+
# BUNDLED_ETCD_VERSIONS?=3.4.18 3.5.17
71+
BUNDLED_ETCD_VERSIONS?=3.4.18 3.5.21
72+
73+
# LATEST_ETCD_VERSION?=3.5.17
74+
LATEST_ETCD_VERSION?=3.5.21
75+
76+
# GOLANG_VERSION := 1.22.9
77+
GOLANG_VERSION := 1.23.7
78+
```
79+
80+
3. In `cluster/images/etcd/migrate/options.go`, include the new version in the `supportedEtcdVersions` slice.
81+
82+
```go
83+
var (
84+
// supportedEtcdVersions = []string{"3.4.18", "3.5.17"}
85+
supportedEtcdVersions = []string{"3.4.18", "3.5.21"}
86+
)
87+
```
88+
89+
### Publish etcd image
90+
91+
> Reference: [link](https://github.com/kubernetes/k8s.io/pull/7957)
92+
93+
1. When the previous step is merged, a post-commit job will run to build the image. You can find the newly built image in the [registry](https://gcr.io/k8s-staging-etcd/etcd).
94+
95+
2. Locate the newly built image and copy its SHA256 digest.
96+
97+
3. Inside the `kubernetes/k8s.io` repository, in `registry.k8s.io/images/k8s-staging-etcd/images.yaml`, create a new entry for the desired version and copy the SHA256 digest.
98+
99+
```yaml
100+
"sha256:b4a9e4a7e1cf08844c7c4db6a19cab380fbf0aad702b8c01e578e9543671b9f9": ["3.5.17-0"]
101+
# ADD:
102+
"sha256:d58c035df557080a27387d687092e3fc2b64c6d0e3162dc51453a115f847d121": ["3.5.21-0"]
103+
```
104+
105+
### Update to use the new etcd image
106+
107+
> Reference: [link](https://github.com/kubernetes/kubernetes/pull/131144)
108+
109+
1. In `build/dependencies.yaml`, change the `version` of `etcd` to the new version.
110+
111+
```yaml
112+
# etcd
113+
- name: "etcd"
114+
# version: 3.5.17
115+
version: 3.5.21
116+
refPaths:
117+
- path: cluster/gce/manifests/etcd.manifest
118+
match: etcd_docker_tag|etcd_version
119+
```
120+
121+
2. In `cluster/gce/manifests/etcd.manifest`, change the image tag to the new image tag and `TARGET_VERSION` to the new version.
122+
123+
```manifest
124+
// "image": "{{ pillar.get('etcd_docker_repository', 'registry.k8s.io/etcd') }}:{{ pillar.get('etcd_docker_tag', '3.5.17-0') }}",
125+
126+
"image": "{{ pillar.get('etcd_docker_repository', 'registry.k8s.io/etcd') }}:{{ pillar.get('etcd_docker_tag', '3.5.21-0') }}",
127+
128+
---
129+
130+
{ "name": "TARGET_VERSION",
131+
// "value": "{{ pillar.get('etcd_version', '3.5.17') }}"
132+
"value": "{{ pillar.get('etcd_version', '3.5.21') }}"
133+
},
134+
```
135+
136+
3. In `cluster/gce/upgrade-aliases.sh`, update the exports for `ETCD_IMAGE` to the new image tag and `ETCD_VERSION` to the new version.
137+
138+
```sh
139+
# export ETCD_IMAGE=3.5.17-0
140+
export ETCD_IMAGE=3.5.21-0
141+
# export ETCD_VERSION=3.5.17
142+
export ETCD_VERSION=3.5.21
143+
```
144+
145+
4. In `cmd/kubeadm/app/constants/constants.go`, change the `DefaultEtcdVersion` to the new version. In the same file, update `SupportedEtcdVersion` accordingly.
146+
147+
```go
148+
// DefaultEtcdVersion = "3.5.17-0"
149+
DefaultEtcdVersion = "3.5.21-0"
150+
151+
---
152+
153+
SupportedEtcdVersion = map[uint8]string{
154+
// 30: "3.5.17-0",
155+
// 31: "3.5.17-0",
156+
// 32: "3.5.17-0",
157+
// 33: "3.5.17-0",
158+
30: "3.5.21-0",
159+
31: "3.5.21-0",
160+
32: "3.5.21-0",
161+
33: "3.5.21-0",
162+
}
163+
```
164+
165+
5. In `hack/lib/etcd.sh`, update the `ETCD_VERSION`.
166+
167+
```sh
168+
# ETCD_VERSION=${ETCD_VERSION:-3.5.17}
169+
ETCD_VERSION=${ETCD_VERSION:-3.5.21}
170+
```
171+
172+
6. In `staging/src/k8s.io/sample-apiserver/artifacts/example/deployment.yaml`, update the etcd image used.
173+
174+
```yaml
175+
- name: etcd
176+
# image: gcr.io/etcd-development/etcd:v3.5.17
177+
image: gcr.io/etcd-development/etcd:v3.5.21
178+
```
179+
180+
7. In `test/utils/image/manifest.go`, update the etcd image tag.
181+
182+
```go
183+
// configs[Etcd] = Config{list.GcEtcdRegistry, "etcd", "3.5.17-0"}
184+
configs[Etcd] = Config{list.GcEtcdRegistry, "etcd", "3.5.21-0"}
185+
```

0 commit comments

Comments
 (0)