diff --git a/modules/osdk-updating-v1101-to-v1160.adoc b/modules/osdk-updating-v1101-to-v1160.adoc new file mode 100644 index 0000000000..8784d780ec --- /dev/null +++ b/modules/osdk-updating-v1101-to-v1160.adoc @@ -0,0 +1,195 @@ +// Module included in the following assemblies: +// +// * operators/operator_sdk/osdk-upgrading-projects.adoc + +:osdk_ver: v1.16.0 +:osdk_ver_n1: v1.10.1 + +:_content-type: PROCEDURE +[id="osdk-upgrading-v1101-to-v1160_{context}"] += Updating projects for Operator SDK {osdk_ver} + +The following procedure updates an existing Operator project for compatibility with {osdk_ver}. + +[IMPORTANT] +==== +* Operator SDK v1.16.0 supports Kubernetes 1.22. + +* Many deprecated `v1beta1` APIs were removed in Kubernetes 1.22, including `sigs.k8s.io/controller-runtime v0.10.0` and `controller-gen v0.7`. + +* 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. + +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. +==== + +.Prerequisites + +* Operator SDK {osdk_ver} installed. +* An Operator project created or maintained with Operator SDK {osdk_ver_n1}. + +.Procedure + +. Add the `protocol` field in the `config/default/manager_auth_proxy_patch.yaml` and `config/rbac/auth_proxy_service.yaml` files: ++ +[source,diff] +---- +... + ports: + - containerPort: 8443 ++ protocol: TCP + name: https +---- + +. Make the following changes to the `config/manager/manager.yaml` file: + +.. Increase the CPU and memory resource limits: ++ +[source,diff] +---- +resources: + limits: +- cpu: 100m +- memory: 30Mi ++ cpu: 200m ++ memory: 100Mi +---- + +.. Add an annotation to specify the default container manager: ++ +[source,yaml] +---- +... +template: + metadata: + annotations: + kubectl.kubernetes.io/default-container: manager +... +---- + +. Add `PHONY` targets to all of the targets in your `Makefile` file. + +. For Go-based Operator projects, make the following changes: + +.. Install the `setup-envtest` binary. + +.. Change your `go.mod` file to update the dependencies: ++ +[source,golang] +---- +k8s.io/api v0.22.1 +k8s.io/apimachinery v0.22.1 +k8s.io/client-go v0.22.1 +sigs.k8s.io/controller-runtime v0.10.0 +---- + +.. Run the `go mod tidy` command to download the dependencies: ++ +[source,terminal] +---- +$ go mod tidy +---- + +.. Make the following changes to your `Makefile` file: ++ +[source,diff] +---- +... +- ENVTEST_K8S_VERSION = 1.21` ++ ENVTEST_K8S_VERSION = 1.22` + + test: manifests generate fmt vet envtest ## Run tests. +- go test ./... -coverprofile cover.out ++ KUBEBUILDER_ASSETS="$(shell $(ENVTEST) use $(ENVTEST_K8S_VERSION) -p path)" go test ./... -coverprofile cover.out +... + +- $(CONTROLLER_GEN) $(CRD_OPTIONS) rbac:roleName=manager-role webhook paths="./..." output:crd:artifacts:config=config/crd/bases ++ $(CONTROLLER_GEN) rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases +... + +# Produce CRDs that work back to Kubernetes 1.11 (no version conversion) +- CRD_OPTIONS ?= "crd:trivialVersions=true,preserveUnknownFields=false" +... +- admissionReviewVersions={v1,v1beta1} ++ admissionReviewVersions=v1 +... + ++ ifndef ignore-not-found ++ ignore-not-found = false ++ endif + +##@ Deployment +... +- sh kubectl delete -f - ++ sh kubectl delete --ignore-not-found=$(ignore-not-found) -f - +---- + +.. Run the `make manifest` command to generate your manifests with the updated version of Kubernetes: ++ +[source,terminal] +---- +$ make manifest +---- + +. For Ansible-based Operator projects, make the following changes: ++ +.. Change your `requirements.yml` file to include the following: + +... Replace the `community.kubernetes` collection with the `kubernetes.core` collection: ++ +[source,yaml] +---- +... +- name: kubernetes.core + version: "2.2.0" +... +---- + +... Update the `operator_sdk.util` utility from version `0.2.0` to `0.3.1`: ++ +[source,yaml] +---- +... +- name: operator_sdk.util + version: "0.3.1" +---- + +.. Verify the default resource limits in the `config/manager/manager.yaml` file: ++ +[source,yaml] +---- +... + # TODO(user): Configure the resources accordingly based on the project requirements. + # More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + +resources: + limits: + cpu: 500m + memory: 768Mi + requests: + cpu: 10m + memory: 256Mi +---- ++ +[IMPORTANT] +==== +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. +==== + +.. Optional: Make the following changes if you want to run your Ansible-based Operator locally by using the `make run` command: + +... Change the run target in the `Makefile` file: ++ +[source,terminal] +---- +ANSIBLE_ROLES_PATH="$(ANSIBLE_ROLES_PATH):$(shell pwd)/roles" $(ANSIBLE_OPERATOR) run +---- + +... Update the local version of `ansible-runner` to 2.0.2 or later. ++ +[IMPORTANT] +==== +As of version 2.0, the `ansible-runner` tool includes changes in the command signature that are not compatible with earlier versions. +==== + +:!osdk_ver: +:!osdk_ver_n1: diff --git a/operators/operator_sdk/osdk-upgrading-projects.adoc b/operators/operator_sdk/osdk-upgrading-projects.adoc index f77b13c7f7..4811eb0190 100644 --- a/operators/operator_sdk/osdk-upgrading-projects.adoc +++ b/operators/operator_sdk/osdk-upgrading-projects.adoc @@ -1,30 +1,26 @@ :_content-type: ASSEMBLY [id="osdk-upgrading-projects"] -= Upgrading projects for newer Operator SDK versions += Updating projects for newer Operator SDK versions include::modules/common-attributes.adoc[] :context: osdk-upgrading-projects -:osdk_ver: v1.10.1 -:osdk_ver_n1: v1.8.0 -:product-version-n1: 4.8 +:osdk_ver: v1.16.0 +:osdk_ver_n1: v1.10.1 +:product-version-n1: 4.9 toc::[] -{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]. +{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]. -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}. +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}. -include::modules/osdk-upgrading-v180-to-v1101.adoc[leveloffset=+1] - -[id="osdk-upgrading-projects-known-issues"] -== Known issues - -* 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. +include::modules/osdk-updating-v1101-to-v1160.adoc[leveloffset=+1] [id="additional-resources_osdk-upgrading-projects"] == Additional resources * xref:../../operators/operator_sdk/osdk-pkgman-to-bundle.adoc#osdk-pkgman-to-bundle[Migrating package manifest projects to bundle format] +* 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] * 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] //Consider updating this during the 4.10 to 4.11 version scrub.