Skip to content

Commit 207915d

Browse files
jab-rhjab-rh
authored
Merge pull request #52763 from michaelryanpeter/OSDOCS-4448-OSDK-1.25.1-Project-migration-docs
OSDOCS-4448: OSDK 1.25.1 Project migration docs
2 parents c8de750 + df2fbee commit 207915d

File tree

7 files changed

+368
-4
lines changed

7 files changed

+368
-4
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1577,6 +1577,8 @@ Topics:
15771577
File: osdk-java-tutorial
15781578
- Name: Project layout
15791579
File: osdk-java-project-layout
1580+
- Name: Updating Java-based projects
1581+
File: osdk-java-updating-projects
15801582
- Name: Defining cluster service versions (CSVs)
15811583
File: osdk-generating-csvs
15821584
- Name: Working with bundle images

‎modules/osdk-updating-v1220-to-v1251.adoc

Lines changed: 337 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,337 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operators/operator_sdk/golang/osdk-golang-updating-projects.adoc
4+
// * operators/operator_sdk/ansible/osdk-ansible-updating-projects.adoc
5+
// * operators/operator_sdk/helm/osdk-helm-updating-projects.adoc
6+
// * operators/operator_sdk/helm/osdk-hybrid-helm-updating-projects.adoc
7+
// * operators/operator_sdk/java/osdk-java-updating-projects.adoc
8+
9+
ifeval::["{context}" == "osdk-golang-updating-projects"]
10+
:golang:
11+
:type: Go
12+
endif::[]
13+
ifeval::["{context}" == "osdk-ansible-updating-projects"]
14+
:ansible:
15+
:type: Ansible
16+
endif::[]
17+
ifeval::["{context}" == "osdk-helm-updating-projects"]
18+
:helm:
19+
:type: Helm
20+
endif::[]
21+
ifeval::["{context}" == "osdk-hybrid-helm-updating-projects"]
22+
:hybrid:
23+
:type: Hybrid Helm
24+
endif::[]
25+
ifeval::["{context}" == "osdk-java-updating-projects"]
26+
:java:
27+
:type: Java
28+
endif::[]
29+
30+
:osdk_ver: v1.25.1
31+
:osdk_ver_n1: v1.22.0
32+
33+
:_content-type: PROCEDURE
34+
[id="osdk-upgrading-projects_{context}"]
35+
= Updating {type}-based Operator projects for Operator SDK {osdk_ver}
36+
37+
The following procedure updates an existing {type}-based Operator project for compatibility with {osdk_ver}.
38+
39+
.Prerequisites
40+
41+
* Operator SDK {osdk_ver} installed
42+
* An Operator project created or maintained with Operator SDK {osdk_ver_n1}
43+
44+
.Procedure
45+
46+
. Make the following changes to the `config/default/manager_auth_proxy_patch.yaml` file:
47+
+
48+
[source,yaml]
49+
----
50+
apiVersion: apps/v1
51+
kind: Deployment
52+
metadata:
53+
name: controller-manager
54+
namespace: system
55+
spec:
56+
template:
57+
spec:
58+
containers:
59+
- name: kube-rbac-proxy
60+
image: registry.redhat.io/openshift4/ose-kube-rbac-proxy:v4.12 <1>
61+
args:
62+
- "--secure-listen-address=0.0.0.0:8443"
63+
- "--upstream=http://127.0.0.1:8080/"
64+
- "--logtostderr=true"
65+
- "--v=0"
66+
...
67+
----
68+
<1> Update the tag version from `v4.11` to `v4.12`.
69+
70+
. Make the following changes to your `Makefile`:
71+
72+
.. To enable multi-architecture build support, add the `docker-buildx` target to your project `Makefile`:
73+
+
74+
.Example `Makefile`
75+
[source,make]
76+
----
77+
# PLATFORMS defines the target platforms for the manager image be build to provide support to multiple
78+
# architectures. (i.e. make docker-buildx IMG=myregistry/mypoperator:0.0.1). To use this option you need to:
79+
# - able to use docker buildx . More info: https://docs.docker.com/build/buildx/
80+
# - have enable BuildKit, More info: https://docs.docker.com/develop/develop-images/build_enhancements/
81+
# - be able to push the image for your registry (i.e. if you do not inform a valid value via IMG=<myregistry/image:<tag>> than the export will fail)
82+
# To properly provided solutions that supports more than one platform you should use this option.
83+
PLATFORMS ?= linux/arm64,linux/amd64,linux/s390x,linux/ppc64le
84+
.PHONY: docker-buildx
85+
docker-buildx: test ## Build and push docker image for the manager for cross-platform support
86+
# copy existing Dockerfile and insert --platform=${BUILDPLATFORM} into Dockerfile.cross, and preserve the original Dockerfile
87+
sed -e '1 s/\(^FROM\)/FROM --platform=\$$\{BUILDPLATFORM\}/; t' -e ' 1,// s//FROM --platform=\$$\{BUILDPLATFORM\}/' Dockerfile > Dockerfile.cross
88+
- docker buildx create --name project-v3-builder
89+
docker buildx use project-v3-builder
90+
- docker buildx build --push --platform=$(PLATFORMS) --tag ${IMG} -f Dockerfile.cross
91+
- docker buildx rm project-v3-builder
92+
rm Dockerfile.cross
93+
----
94+
ifdef::ansible,helm[]
95+
.. To enable support for `arm64` architectures in your Operator project, make the following changes to your `Makefile`:
96+
+
97+
.Old `Makefile`
98+
[source,make]
99+
----
100+
OS := $(shell uname -s | tr '[:upper:]' '[:lower:]')
101+
ARCH := $(shell uname -m | sed 's/x86_64/amd64/')
102+
----
103+
+
104+
.New `Makefile`
105+
[source,make]
106+
----
107+
OS := $(shell uname -s | tr '[:upper:]' '[:lower:]')
108+
ARCH := $(shell uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')
109+
----
110+
111+
.. Update the Kustomize version to `v4.5.5` as shown in the following example:
112+
+
113+
.Old `Makefile`
114+
[source,make]
115+
----
116+
.PHONY: kustomize
117+
KUSTOMIZE = $(shell pwd)/bin/kustomize
118+
kustomize: ## Download kustomize locally if necessary.
119+
ifeq (,$(wildcard $(KUSTOMIZE)))
120+
ifeq (,$(shell which kustomize 2>/dev/null))
121+
@{ \
122+
set -e ;\
123+
mkdir -p $(dir $(KUSTOMIZE)) ;\
124+
curl -sSLo - https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize/v3.8.7/kustomize_v3.8.7_$(OS)_$(ARCH).tar.gz | \
125+
tar xzf - -C bin/ ;\
126+
}
127+
else
128+
----
129+
+
130+
.New `Makefile`
131+
[source,make]
132+
----
133+
.PHONY: kustomize
134+
KUSTOMIZE = $(shell pwd)/bin/kustomize
135+
kustomize: ## Download kustomize locally if necessary.
136+
ifeq (,$(wildcard $(KUSTOMIZE)))
137+
ifeq (,$(shell which kustomize 2>/dev/null))
138+
@{ \
139+
set -e ;\
140+
mkdir -p $(dir $(KUSTOMIZE)) ;\
141+
curl -sSLo - https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize/v4.5.5/kustomize_v4.5.5_$(OS)_$(ARCH).tar.gz | \ <1>
142+
tar xzf - -C bin/ ;\
143+
}
144+
else
145+
----
146+
<1> Update version `v3.8.7` to `v4.5.5`.
147+
+
148+
[IMPORTANT]
149+
====
150+
Kustomize version `4.0.0` removed the `go-getter` plugin and introduced breaking changes that are not backwards compatible with earlier versions. Operator projects that rely on older versions of Kustomize might not work with newer releases.
151+
====
152+
endif::[]
153+
154+
ifdef::golang[]
155+
.. Update your project scaffolding to support changes in `kubebuilder` as shown in the following example:
156+
+
157+
.Old `Makefile`
158+
[source,make]
159+
----
160+
.PHONY: test
161+
test: manifests generate fmt vet envtest ## Run tests.
162+
KUBEBUILDER_ASSETS="$(shell $(ENVTEST) use $(ENVTEST_K8S_VERSION) -p path)" go test ./... -coverprofile cover.out
163+
----
164+
+
165+
.New `Makefile`
166+
[source,make]
167+
----
168+
.PHONY: test
169+
test: manifests generate fmt vet envtest ## Run tests.
170+
KUBEBUILDER_ASSETS="$(shell $(ENVTEST) use $(ENVTEST_K8S_VERSION) -p path)" go test $(go list ./... | grep -v /test/) -coverprofile cover.out
171+
----
172+
173+
.. To ensure `Makefile` targets do not download binaries already in your binary path, make the following changes to your `Makefile`:
174+
+
175+
.Old `Makefile`
176+
[source,make]
177+
----
178+
KUSTOMIZE_INSTALL_SCRIPT ?= "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh"
179+
.PHONY: kustomize
180+
kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary.
181+
$(KUSTOMIZE): $(LOCALBIN)
182+
{ curl -s $(KUSTOMIZE_INSTALL_SCRIPT) | bash -s -- $(subst v,,$(KUSTOMIZE_VERSION)) $(LOCALBIN); }
183+
184+
.PHONY: controller-gen
185+
controller-gen: $(CONTROLLER_GEN) ## Download controller-gen locally if necessary.
186+
$(CONTROLLER_GEN): $(LOCALBIN)
187+
test -s $(LOCALBIN)/controller-gen || GOBIN=$(LOCALBIN) go install sigs.k8s.io/controller-tools/cmd/controller-gen@$(CONTROLLER_TOOLS_VERSION
188+
GOBIN=$(LOCALBIN) go install sigs.k8s.io/controller-tools/cmd/controller-gen@$(CONTROLLER_TOOLS_VERSION)
189+
190+
.PHONY: envtest
191+
envtest: $(ENVTEST) ## Download envtest-setup locally if necessary.
192+
$(ENVTEST): $(LOCALBIN)
193+
GOBIN=$(LOCALBIN) go install sigs.k8s.io/controller-runtime/tools/setup-envtest@latest
194+
----
195+
+
196+
.New `Makefile`
197+
[source,make]
198+
----
199+
KUSTOMIZE_INSTALL_SCRIPT ?= "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh"
200+
.PHONY: kustomize
201+
kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary.
202+
$(KUSTOMIZE): $(LOCALBIN)
203+
test -s $(LOCALBIN)/kustomize || { curl -s $(KUSTOMIZE_INSTALL_SCRIPT) | bash -s -- $(subst v,,$(KUSTOMIZE_VERSION)) $(LOCALBIN); } <1>
204+
205+
.PHONY: controller-gen
206+
controller-gen: $(CONTROLLER_GEN) ## Download controller-gen locally if necessary.
207+
$(CONTROLLER_GEN): $(LOCALBIN)
208+
test -s $(LOCALBIN)/controller-gen || GOBIN=$(LOCALBIN) go install sigs.k8s.io/controller-tools/cmd/controller-gen@$(CONTROLLER_TOOLS_VERSION) <1>
209+
210+
.PHONY: envtest
211+
envtest: $(ENVTEST) ## Download envtest-setup locally if necessary.
212+
$(ENVTEST): $(LOCALBIN)
213+
test -s $(LOCALBIN)/setup-envtest || GOBIN=$(LOCALBIN) go install sigs.k8s.io/controller-runtime/tools/setup-envtest@latest <1>
214+
----
215+
<1> Add `test -s $(LOCALBIN)/<binary-name> ||` before the instruction to download a binary.
216+
217+
.. Update `controller-tools` to version `v0.9.2` as shown in the following example:
218+
+
219+
.Example `Makefile
220+
[source,make]
221+
----
222+
## Tool Versions
223+
KUSTOMIZE_VERSION ?= v3.8.7
224+
CONTROLLER_TOOLS_VERSION ?= v0.9.2 <1>
225+
----
226+
<1> Update version `v0.9.0` to `v0.9.2`.
227+
endif::[]
228+
229+
.. To apply the changes to your `Makefile` and rebuild your Operator, enter the following command:
230+
+
231+
[source,terminal]
232+
----
233+
$ make
234+
----
235+
236+
ifdef::ansible,helm[]
237+
. Update your `config/default/kustomizations.yaml` file as shown in the following examples:
238+
+
239+
.Example `kustomizations.yaml` file
240+
[source,yaml]
241+
----
242+
# Adds namespace to all resources.
243+
namespace: memcached-operator-system
244+
# Value of this field is prepended to the
245+
# names of all resources, e.g. a deployment named
246+
# "wordpress" becomes "alices-wordpress".
247+
# Note that it should also match with the prefix (text before '-') of the namespace
248+
# field above.
249+
namePrefix: memcached-operator-
250+
251+
# Labels to add to all resources and selectors.
252+
#labels: <1>
253+
#- includeSelectors: true <2>
254+
# pairs:
255+
# someName: someValue
256+
257+
resources: <3>
258+
- ../crd
259+
- ../rbac
260+
- ../manager
261+
----
262+
<1> Replace the `commonLabels` field with the `labels` field.
263+
<2> Add `includeSelectors: true`.
264+
<3> Replace the `bases` field with the `resources` field.
265+
endif::[]
266+
267+
ifdef::ansible[]
268+
. Update your `molecule/default/kustomize.yml` file with the following changes:
269+
+
270+
.Example `molecule/default/kustomize.yml` file
271+
[source,yaml]
272+
----
273+
---
274+
- name: Build kustomize testing overlay
275+
# load_restrictor must be set to none so we can load patch files from the default overlay
276+
command: '{{ kustomize }} build --load-restrictor LoadRestrictionsNone' <1>
277+
args:
278+
chdir: '{{ config_dir }}/testing'
279+
register: resources
280+
changed_when: false
281+
----
282+
<1> Replace `--load_restrictor none .` with `--load-restrictor LoadRestrictionNone`.
283+
endif::[]
284+
285+
ifdef::golang,hybrid[]
286+
. To update Go and its dependencies, make the following changes to your `go.mod` file:
287+
+
288+
[source,golang]
289+
----
290+
go 1.19 <1>
291+
292+
require (
293+
github.com/onsi/ginkgo/v2 v2.1.4 <2>
294+
github.com/onsi/gomega v1.19.0 <3>
295+
k8s.io/api v0.25.0 <4>
296+
k8s.io/apimachinery v0.25.0 <4>
297+
k8s.io/client-go v0.25.0 <4>
298+
sigs.k8s.io/controller-runtime v0.13.0 <5>
299+
)
300+
----
301+
<1> Update version `1.18` to `1.19`.
302+
<2> Update version `v1.16.5` to `v2.1.4`.
303+
<3> Update version `v1.18.1` to `v1.19.0`.
304+
<4> Update version `v0.24.0` to `v0.25.0`.
305+
<5> Update version `v0.12.1` to `v0.13.0`.
306+
307+
. To download the updated versions, clean up the dependencies, and apply the changes in your `go.mod` file, run the following command:
308+
+
309+
[source,terminal]
310+
----
311+
$ go mod tidy
312+
----
313+
endif::[]
314+
315+
:!osdk_ver:
316+
:!osdk_ver_n1:
317+
318+
ifeval::["{context}" == "osdk-golang-updating-projects"]
319+
:!golang:
320+
:!type:
321+
endif::[]
322+
ifeval::["{context}" == "osdk-ansible-updating-projects"]
323+
:!ansible:
324+
:!type:
325+
endif::[]
326+
ifeval::["{context}" == "osdk-helm-updating-projects"]
327+
:!helm:
328+
:!type:
329+
endif::[]
330+
ifeval::["{context}" == "osdk-hybrid-helm-updating-projects"]
331+
:!hybrid:
332+
:!type:
333+
endif::[]
334+
ifeval::["{context}" == "osdk-java-updating-projects"]
335+
:!java:
336+
:!type:
337+
endif::[]

‎operators/operator_sdk/ansible/osdk-ansible-updating-projects.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ toc::[]
1313

1414
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}.
1515

16-
include::modules/osdk-updating-projects.adoc[leveloffset=+1]
16+
include::modules/osdk-updating-v1220-to-v1251.adoc[leveloffset=+1]
1717

1818
[id="additional-resources_osdk-ansible-upgrading-projects"]
1919
[role="_additional-resources"]

‎operators/operator_sdk/golang/osdk-golang-updating-projects.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ toc::[]
1313

1414
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}.
1515

16-
include::modules/osdk-updating-projects.adoc[leveloffset=+1]
16+
include::modules/osdk-updating-v1220-to-v1251.adoc[leveloffset=+1]
1717

1818
[id="additional-resources_osdk-upgrading-projects-golang"]
1919
[role="_additional-resources"]

‎operators/operator_sdk/helm/osdk-helm-updating-projects.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ toc::[]
1313

1414
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}.
1515

16-
include::modules/osdk-updating-projects.adoc[leveloffset=+1]
16+
include::modules/osdk-updating-v1220-to-v1251.adoc[leveloffset=+1]
1717

1818
[id="additional-resources_osdk-helm-upgrading-projects"]
1919
[role="_additional-resources"]

‎operators/operator_sdk/helm/osdk-hybrid-helm-updating-projects.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ toc::[]
1313

1414
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}.
1515

16-
include::modules/osdk-updating-projects.adoc[leveloffset=+1]
16+
include::modules/osdk-updating-v1220-to-v1251.adoc[leveloffset=+1]
1717

1818
[id="additional-resources_osdk-hybrid-helm-upgrading-projects"]
1919
[role="_additional-resources"]

0 commit comments

Comments
 (0)