OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history bug_report picture_as_pdf
×

Updating Go-based Operator projects for newer Operator SDK versions

OpenShift Container Platform 4.17 supports Operator SDK 1.36.1. If you already have the 1.31.0 CLI installed on your workstation, you can update the CLI to 1.36.1 by installing the latest version.

The Red Hat-supported version of the Operator SDK CLI tool, including the related scaffolding and testing tools for Operator projects, is deprecated and is planned to be removed in a future release of OpenShift Container Platform. Red Hat will provide bug fixes and support for this feature during the current release lifecycle, but this feature will no longer receive enhancements and will be removed from future OpenShift Container Platform releases.

The Red Hat-supported version of the Operator SDK is not recommended for creating new Operator projects. Operator authors with existing Operator projects can use the version of the Operator SDK CLI tool released with OpenShift Container Platform 4.17 to maintain their projects and create Operator releases targeting newer versions of OpenShift Container Platform.

The following related base images for Operator projects are not deprecated. The runtime functionality and configuration APIs for these base images are still supported for bug fixes and for addressing CVEs.

  • The base image for Ansible-based Operator projects

  • The base image for Helm-based Operator projects

For the most recent list of major functionality that has been deprecated or removed within OpenShift Container Platform, refer to the Deprecated and removed features section of the OpenShift Container Platform release notes.

For information about the unsupported, community-maintained, version of the Operator SDK, see Operator SDK (Operator Framework).

However, to ensure your existing Operator projects maintain compatibility with Operator SDK 1.36.1, update steps are required for the associated breaking changes introduced since 1.31.0. You must perform the update steps manually in any of your Operator projects that were previously created or maintained with 1.31.0.

Updating Go-based Operator projects for Operator SDK 1.36.1

The following procedure updates an existing Go-based Operator project for compatibility with 1.36.1.

Prerequisites

  • Operator SDK 1.36.1 installed

  • An Operator project created or maintained with Operator SDK 1.31.0

Procedure

  1. Edit your Operator project’s Makefile to update the Operator SDK version to v1.36.1-ocp, as shown in the following example:

    Example Makefile
    # Set the Operator SDK version to use. By default, what is installed on the system is used.
# This is useful for CI or a project to utilize a specific version of the operator-sdk toolkit.
OPERATOR_SDK_VERSION ?= v1.36.1-ocp

  2. Update the kube-rbac-proxy container to use the Red Hat Enterprise Linux (RHEL) 9-based image:

    1. Find the entry for the kube-rbac-proxy container in the following files:

      • config/default/manager_auth_proxy_patch.yaml

      • bundle/manifests/<operator_name>.clusterserviceversion.yaml for your Operator project, for example memcached-operator.clusterserviceversion.yaml from the tutorials

    2. Update the image name in the pull spec from ose-kube-rbac-proxy to ose-kube-rbac-proxy-rhel9, and update the tag to v4.17:

      Example ose-kube-rbac-proxy-rhel9 pull spec with v4.17 image tag
      # ...
      containers:
      - name: kube-rbac-proxy
        image: registry.redhat.io/openshift4/ose-kube-rbac-proxy-rhel9:v4.17
# ...

  3. The go/v4 plugin is now stable and is the default version used when scaffolding a Go-based Operator. The transition from Golang v2 and v3 plugins to the new Golang v4 plugin introduces significant changes. This migration is designed to enhance your project’s functionality and compatibility, reflecting the evolving landscape of Golang development.

    For more information on the reasoning behind these changes, see go/v3 vs go/v4 in the Kubebuilder documentation.

    For a comprehensive understanding of the migration process to the v4 plugin format and detailed migration steps, see Migration from go/v3 to go/v4 by updating the files manually in the Kubebuilder documentation.

  4. The kustomize/v2 plugin is now stable and is the default version used in the plugin chain when using go/v4, ansible/v1, helm/v1, and hybrid/v1-alpha plugins. For more information on this default scaffold, see Kustomize v2 in the Kubebuilder documentation.

  5. If your Operator project uses a multi-platform, or multi-archicture, build, replace the existing docker-buildx target with following definition in your project Makefile:

    Example Makefile
    docker-buildx:
## Build and push the Docker image for the manager for multi-platform support
	- docker buildx create --name project-v3-builder
	docker buildx use project-v3-builder
	- docker buildx build --push --platform=$(PLATFORMS) --tag ${IMG} -f Dockerfile .
	- docker buildx rm project-v3-builder

  6. You must upgrade the Kubernetes versions in your Operator project to use 1.29. The following changes must be made in your project structure, Makefile, and go.mod files.

    The go/v3 plugin is being deprecated by Kubebuilder, therefore Operator SDK is also migrating to go/v4 in a future release.

    1. Update your go.mod file to upgrade your dependencies:

      k8s.io/api v0.29.2
k8s.io/apimachinery v0.29.2
k8s.io/client-go v0.29.2
sigs.k8s.io/controller-runtime v0.17.3

    2. Download the upgraded dependencies by running the following command:

      $ go mod tidy

    3. You can now generate a file that contains all the resources built with Kustomize, which are necessary to install this project without its dependencies. Update your Makefile by making the following changes:

      + .PHONY: build-installer
+   build-installer: manifests generate kustomize ## Generate a consolidated YAML with CRDs and deployment.
+   	mkdir -p dist
+   	cd config/manager && $(KUSTOMIZE) edit set image controller=${IMG}
+   	$(KUSTOMIZE) build config/default > dist/install.yaml

    4. Update the ENVTEST_K8S_VERSION variable in your Makefile by making the following changes:

      - ENVTEST_K8S_VERSION = 1.28.3
+ ENVTEST_K8S_VERSION = 1.29.0

    5. Remove the following section from your Makefile:

      - GOLANGCI_LINT = $(shell pwd)/bin/golangci-lint
- GOLANGCI_LINT_VERSION ?= v1.54.2
- golangci-lint:
- 	@[ -f $(GOLANGCI_LINT) ] || { \
- 	set -e ;\
- 	curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(shell dirname $(GOLANGCI_LINT)) $(GOLANGCI_LINT_VERSION) ;\
- 	}

    6. Update your Makefile by making the following changes:

      Makefile changes 
      - ## Tool Binaries
- KUBECTL ?= kubectl
- KUSTOMIZE ?= $(LOCALBIN)/kustomize
- CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen
- ENVTEST ?= $(LOCALBIN)/setup-envtest
-
- ## Tool Versions
- KUSTOMIZE_VERSION ?= v5.2.1
- CONTROLLER_TOOLS_VERSION ?= v0.13.0
-
- .PHONY: kustomize
- kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary. If wrong version is installed, it will be removed before downloading.
- $(KUSTOMIZE): $(LOCALBIN)
-   @if test -x $(LOCALBIN)/kustomize && ! $(LOCALBIN)/kustomize version | grep -q $(KUSTOMIZE_VERSION); then \
-   echo "$(LOCALBIN)/kustomize version is not expected $(KUSTOMIZE_VERSION). Removing it before installing."; \
-   rm -rf $(LOCALBIN)/kustomize; \
-   fi
-   test -s $(LOCALBIN)/kustomize || GOBIN=$(LOCALBIN) GO111MODULE=on go install sigs.k8s.io/kustomize/kustomize/v5@$(KUSTOMIZE_VERSION)
-
- .PHONY: controller-gen
- controller-gen: $(CONTROLLER_GEN) ## Download controller-gen locally if necessary. If wrong version is installed, it will be overwritten.
- $(CONTROLLER_GEN): $(LOCALBIN)
-   test -s $(LOCALBIN)/controller-gen && $(LOCALBIN)/controller-gen --version | grep -q $(CONTROLLER_TOOLS_VERSION) || \
-   GOBIN=$(LOCALBIN) go install sigs.k8s.io/controller-tools/cmd/controller-gen@$(CONTROLLER_TOOLS_VERSION)
-
- .PHONY: envtest
- envtest: $(ENVTEST) ## Download envtest-setup locally if necessary.
- $(ENVTEST): $(LOCALBIN)
-   test -s $(LOCALBIN)/setup-envtest || GOBIN=$(LOCALBIN) go install sigs.k8s.io/controller-runtime/tools/setup-envtest@latest
+ ## Tool Binaries
+ KUBECTL ?= kubectl
+ KUSTOMIZE ?= $(LOCALBIN)/kustomize-$(KUSTOMIZE_VERSION)
+ CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen-$(CONTROLLER_TOOLS_VERSION)
+ ENVTEST ?= $(LOCALBIN)/setup-envtest-$(ENVTEST_VERSION)
+ GOLANGCI_LINT = $(LOCALBIN)/golangci-lint-$(GOLANGCI_LINT_VERSION)
+
+ ## Tool Versions
+ KUSTOMIZE_VERSION ?= v5.3.0
+ CONTROLLER_TOOLS_VERSION ?= v0.14.0
+ ENVTEST_VERSION ?= release-0.17
+ GOLANGCI_LINT_VERSION ?= v1.57.2
+
+ .PHONY: kustomize
+ kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary.
+ $(KUSTOMIZE): $(LOCALBIN)
+ 	$(call go-install-tool,$(KUSTOMIZE),sigs.k8s.io/kustomize/kustomize/v5,$(KUSTOMIZE_VERSION))
+
+ .PHONY: controller-gen
+ controller-gen: $(CONTROLLER_GEN) ## Download controller-gen locally if necessary.
+ $(CONTROLLER_GEN): $(LOCALBIN)
+ 	$(call go-install-tool,$(CONTROLLER_GEN),sigs.k8s.io/controller-tools/cmd/controller-gen,$(CONTROLLER_TOOLS_VERSION))
+
+ .PHONY: envtest
+ envtest: $(ENVTEST) ## Download setup-envtest locally if necessary.
+ $(ENVTEST): $(LOCALBIN)
+ 	$(call go-install-tool,$(ENVTEST),sigs.k8s.io/controller-runtime/tools/setup-envtest,$(ENVTEST_VERSION))
+
+ .PHONY: golangci-lint
+ golangci-lint: $(GOLANGCI_LINT) ## Download golangci-lint locally if necessary.
+ $(GOLANGCI_LINT): $(LOCALBIN)
+ 	$(call go-install-tool,$(GOLANGCI_LINT),github.com/golangci/golangci-lint/cmd/golangci-lint,${GOLANGCI_LINT_VERSION})
+
+ # go-install-tool will 'go install' any package with custom target and name of binary, if it doesn't exist
+ # $1 - target path with name of binary (ideally with version)
+ # $2 - package url which can be installed
+ # $3 - specific version of package
+ define go-install-tool
+ @[ -f $(1) ] || { \
+ set -e; \
+ package=$(2)@$(3) ;\
+ echo "Downloading $${package}" ;\
+ GOBIN=$(LOCALBIN) go install $${package} ;\
+ mv "$$(echo "$(1)" | sed "s/-$(3)$$//")" $(1) ;\
+ }
+ endef

Additional resources