Skip to content

Commit 6dbacf0

Browse files
michaelryanpetermichaelryanpeter
authored
Merge pull request #41029 from michaelryanpeter/osdk-template-updating-and-migrating-projects
OSDOCS-2935 & 2858: Consolidate migration steps for upgrading OSDK version and k8s 1.22
2 parents 240fc27 + ddc0b16 commit 6dbacf0

File tree

2 files changed

+203
-12
lines changed

2 files changed

+203
-12
lines changed

‎modules/osdk-updating-v1101-to-v1160.adoc

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operators/operator_sdk/osdk-upgrading-projects.adoc
4+
5+
:osdk_ver: v1.16.0
6+
:osdk_ver_n1: v1.10.1
7+
8+
:_content-type: PROCEDURE
9+
[id="osdk-upgrading-v1101-to-v1160_{context}"]
10+
= Updating projects for Operator SDK {osdk_ver}
11+
12+
The following procedure updates an existing Operator project for compatibility with {osdk_ver}.
13+
14+
[IMPORTANT]
15+
====
16+
* Operator SDK v1.16.0 supports Kubernetes 1.22.
17+
18+
* Many deprecated `v1beta1` APIs were removed in Kubernetes 1.22, including `sigs.k8s.io/controller-runtime v0.10.0` and `controller-gen v0.7`.
19+
20+
* Updating projects to Kubernetes 1.22 is a breaking change if you need to scaffold `v1beta1` APIs for custom resource definitions (CRDs) or webhooks to publish your project into older cluster versions.
21+
22+
See link:https://docs.openshift.com/container-platform/4.9/release_notes/ocp-4-9-release-notes.html#ocp-4-9-osdk-k8s-api-bundle-validate[Validating bundle manifests for APIs removed from Kubernetes 1.22] and link:https://docs.openshift.com/container-platform/4.9/release_notes/ocp-4-9-release-notes.html#ocp-4-9-removed-kube-1-22-apis[Beta APIs removed from Kubernetes 1.22] for more information about changes introduced in Kubernetes 1.22.
23+
====
24+
25+
.Prerequisites
26+
27+
* Operator SDK {osdk_ver} installed.
28+
* An Operator project created or maintained with Operator SDK {osdk_ver_n1}.
29+
30+
.Procedure
31+
32+
. Add the `protocol` field in the `config/default/manager_auth_proxy_patch.yaml` and `config/rbac/auth_proxy_service.yaml` files:
33+
+
34+
[source,diff]
35+
----
36+
...
37+
ports:
38+
- containerPort: 8443
39+
+ protocol: TCP
40+
name: https
41+
----
42+
43+
. Make the following changes to the `config/manager/manager.yaml` file:
44+
45+
.. Increase the CPU and memory resource limits:
46+
+
47+
[source,diff]
48+
----
49+
resources:
50+
limits:
51+
- cpu: 100m
52+
- memory: 30Mi
53+
+ cpu: 200m
54+
+ memory: 100Mi
55+
----
56+
57+
.. Add an annotation to specify the default container manager:
58+
+
59+
[source,yaml]
60+
----
61+
...
62+
template:
63+
metadata:
64+
annotations:
65+
kubectl.kubernetes.io/default-container: manager
66+
...
67+
----
68+
69+
. Add `PHONY` targets to all of the targets in your `Makefile` file.
70+
71+
. For Go-based Operator projects, make the following changes:
72+
73+
.. Install the `setup-envtest` binary.
74+
75+
.. Change your `go.mod` file to update the dependencies:
76+
+
77+
[source,golang]
78+
----
79+
k8s.io/api v0.22.1
80+
k8s.io/apimachinery v0.22.1
81+
k8s.io/client-go v0.22.1
82+
sigs.k8s.io/controller-runtime v0.10.0
83+
----
84+
85+
.. Run the `go mod tidy` command to download the dependencies:
86+
+
87+
[source,terminal]
88+
----
89+
$ go mod tidy
90+
----
91+
92+
.. Make the following changes to your `Makefile` file:
93+
+
94+
[source,diff]
95+
----
96+
...
97+
- ENVTEST_K8S_VERSION = 1.21`
98+
+ ENVTEST_K8S_VERSION = 1.22`
99+
100+
test: manifests generate fmt vet envtest ## Run tests.
101+
- go test ./... -coverprofile cover.out
102+
+ KUBEBUILDER_ASSETS="$(shell $(ENVTEST) use $(ENVTEST_K8S_VERSION) -p path)" go test ./... -coverprofile cover.out
103+
...
104+
105+
- $(CONTROLLER_GEN) $(CRD_OPTIONS) rbac:roleName=manager-role webhook paths="./..." output:crd:artifacts:config=config/crd/bases
106+
+ $(CONTROLLER_GEN) rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
107+
...
108+
109+
# Produce CRDs that work back to Kubernetes 1.11 (no version conversion)
110+
- CRD_OPTIONS ?= "crd:trivialVersions=true,preserveUnknownFields=false"
111+
...
112+
- admissionReviewVersions={v1,v1beta1}
113+
+ admissionReviewVersions=v1
114+
...
115+
116+
+ ifndef ignore-not-found
117+
+ ignore-not-found = false
118+
+ endif
119+
120+
##@ Deployment
121+
...
122+
- sh kubectl delete -f -
123+
+ sh kubectl delete --ignore-not-found=$(ignore-not-found) -f -
124+
----
125+
126+
.. Run the `make manifest` command to generate your manifests with the updated version of Kubernetes:
127+
+
128+
[source,terminal]
129+
----
130+
$ make manifest
131+
----
132+
133+
. For Ansible-based Operator projects, make the following changes:
134+
+
135+
.. Change your `requirements.yml` file to include the following:
136+
137+
... Replace the `community.kubernetes` collection with the `kubernetes.core` collection:
138+
+
139+
[source,yaml]
140+
----
141+
...
142+
- name: kubernetes.core
143+
version: "2.2.0"
144+
...
145+
----
146+
147+
... Update the `operator_sdk.util` utility from version `0.2.0` to `0.3.1`:
148+
+
149+
[source,yaml]
150+
----
151+
...
152+
- name: operator_sdk.util
153+
version: "0.3.1"
154+
----
155+
156+
.. Verify the default resource limits in the `config/manager/manager.yaml` file:
157+
+
158+
[source,yaml]
159+
----
160+
...
161+
# TODO(user): Configure the resources accordingly based on the project requirements.
162+
# More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
163+
164+
resources:
165+
limits:
166+
cpu: 500m
167+
memory: 768Mi
168+
requests:
169+
cpu: 10m
170+
memory: 256Mi
171+
----
172+
+
173+
[IMPORTANT]
174+
====
175+
Operator SDK scaffolds these values as a reasonable default setting. Operator authors should set and optimize resource limits based on the requirements of their project.
176+
====
177+
178+
.. Optional: Make the following changes if you want to run your Ansible-based Operator locally by using the `make run` command:
179+
180+
... Change the run target in the `Makefile` file:
181+
+
182+
[source,terminal]
183+
----
184+
ANSIBLE_ROLES_PATH="$(ANSIBLE_ROLES_PATH):$(shell pwd)/roles" $(ANSIBLE_OPERATOR) run
185+
----
186+
187+
... Update the local version of `ansible-runner` to 2.0.2 or later.
188+
+
189+
[IMPORTANT]
190+
====
191+
As of version 2.0, the `ansible-runner` tool includes changes in the command signature that are not compatible with earlier versions.
192+
====
193+
194+
:!osdk_ver:
195+
:!osdk_ver_n1:

‎operators/operator_sdk/osdk-upgrading-projects.adoc

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,27 @@
11
:_content-type: ASSEMBLY
22
[id="osdk-upgrading-projects"]
3-
= Upgrading projects for newer Operator SDK versions
3+
= Updating projects for newer Operator SDK versions
44
include::modules/common-attributes.adoc[]
55
:context: osdk-upgrading-projects
66

7-
:osdk_ver: v1.10.1
8-
:osdk_ver_n1: v1.8.0
9-
:product-version-n1: 4.8
7+
:osdk_ver: v1.16.0
8+
:osdk_ver_n1: v1.10.1
9+
:product-version-n1: 4.9
1010

1111
toc::[]
1212

13-
{product-title} {product-version} supports Operator SDK {osdk_ver}. If you already have the {osdk_ver_n1} CLI installed on your workstation, you can upgrade the CLI to {osdk_ver} by xref:../../operators/operator_sdk/osdk-installing-cli.adoc#osdk-installing-cli[installing the latest version].
13+
{product-title} {product-version} supports Operator SDK {osdk_ver}. If you already have the {osdk_ver_n1} CLI installed on your workstation, you can update the CLI to {osdk_ver} by xref:../../operators/operator_sdk/osdk-installing-cli.adoc#osdk-installing-cli[installing the latest version].
1414

15-
However, to ensure your existing Operator projects maintain compatibility with Operator SDK {osdk_ver}, upgrade steps are required for the associated breaking changes introduced since {osdk_ver_n1}. You must perform the upgrade steps manually in any of your Operator projects that were previously created or maintained with {osdk_ver_n1}.
15+
However, to ensure your existing Operator projects maintain compatibility with Operator SDK {osdk_ver}, update steps are required for the associated breaking changes introduced since {osdk_ver_n1}. You must perform the update steps manually in any of your Operator projects that were previously created or maintained with {osdk_ver_n1}.
1616

17-
include::modules/osdk-upgrading-v180-to-v1101.adoc[leveloffset=+1]
18-
19-
[id="osdk-upgrading-projects-known-issues"]
20-
== Known issues
21-
22-
* The `ansible-operator` binary rejects the `kubeconfig` file if the server URL contains a path. There is currently no workaround other than running the Operator as a pod in the cluster, in which case it uses the internal endpoint. The fix for this issue is currently blocked waiting on a fix to the `apimachinery` package. See link:https://github.com/operator-framework/operator-sdk/issues/4925[operator-framework/operator-sdk#4925] for more details.
17+
include::modules/osdk-updating-v1101-to-v1160.adoc[leveloffset=+1]
2318

2419
[id="additional-resources_osdk-upgrading-projects"]
2520
[role="_additional-resources"]
2621
== Additional resources
2722

2823
* xref:../../operators/operator_sdk/osdk-pkgman-to-bundle.adoc#osdk-pkgman-to-bundle[Migrating package manifest projects to bundle format]
24+
* link:https://docs.openshift.com/container-platform/4.9/operators/operator_sdk/osdk-upgrading-projects.html#osdk-upgrading-v180-to-v1101_osdk-upgrading-projects[Upgrading projects for Operator SDK v1.10.1]
2925
* link:https://docs.openshift.com/container-platform/4.8/operators/operator_sdk/osdk-upgrading-projects.html#osdk-upgrading-v130-to-v180_osdk-upgrading-projects[Upgrading projects for Operator SDK v1.8.0]
3026
//Consider updating this during the 4.10 to 4.11 version scrub.
3127

0 commit comments

Comments
 (0)