Updating Go-based Operator projects for newer Operator SDK versions

OKD 4.11 supports Operator SDK 1.22.0. If you already have the 1.16.0 CLI installed on your workstation, you can update the CLI to 1.22.0 by installing the latest version.

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

Updating Go-based Operator projects for Operator SDK 1.22.0

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

Prerequisites

  • Operator SDK 1.22.0 installed.

  • An Operator project created or maintained with Operator SDK 1.16.0.

Procedure

  1. Make the following changes to the config/default/manager_auth_proxy_patch.yaml file:

    1. ...
    2. spec:
    3.   template:
    4.     spec:
    5.       containers:
    6.       - name: kube-rbac-proxy
    7.         image: registry.redhat.io/openshift4/ose-kube-rbac-proxy:v4.11 (1)
    8.         args:
    9.         - "--secure-listen-address=0.0.0.0:8443"
    10.         - "--upstream=http://127.0.0.1:8080/"
    11.         - "--logtostderr=true"
    12.         - "--v=0" (2)
    13. ...
    14. resources:
    15.   limits:
    16.     cpu: 500m
    17.     memory: 128Mi
    18.   requests:
    19.     cpu: 5m
    20.     memory: 64Mi (3)
    1Update the tag version from v4.10 to v4.11.
    2Reduce the debugging log level from —v=10 to —v=0.
    3Add resource requests and limits.

  2. Make the following changes to your Makefile:

    1. Enable support for image digests by adding the following environment variables to your Makefile:

      Old Makefile

      1. BUNDLE_IMG ?= $(IMAGE_TAG_BASE)-bundle:v$(VERSION)
      2. ...

      New Makefile

      1. BUNDLE_IMG ?= $(IMAGE_TAG_BASE)-bundle:v$(VERSION)
      3. # BUNDLE_GEN_FLAGS are the flags passed to the operator-sdk generate bundle command
      4. BUNDLE_GEN_FLAGS ?= -q --overwrite --version $(VERSION) $(BUNDLE_METADATA_OPTS)
      6. # USE_IMAGE_DIGESTS defines if images are resolved via tags or digests
      7. # You can enable this value if you would like to use SHA Based Digests
      8. # To enable set flag to true
      9. USE_IMAGE_DIGESTS ?= false
      10. ifeq ($(USE_IMAGE_DIGESTS), true)
      11.     BUNDLE_GEN_FLAGS += --use-image-digests
      12. endif

    2. Edit your Makefile to replace the bundle target with the BUNDLE_GEN_FLAGS environment variable:

      Old Makefile

      1. $(KUSTOMIZE) build config/manifests | operator-sdk generate bundle -q --overwrite --version $(VERSION) $(BUNDLE_METADATA_OPTS)

      New Makefile

      1. $(KUSTOMIZE) build config/manifests | operator-sdk generate bundle $(BUNDLE_GEN_FLAGS)

    3. Edit your Makefile to update opm to version 1.23.0:

      1. .PHONY: opm
      2. OPM = ./bin/opm
      3. opm: ## Download opm locally if necessary.
      4. ifeq (,$(wildcard $(OPM)))
      5. ifeq (,$(shell which opm 2>/dev/null))
      6.     @{ \
      7.     set -e ;\
      8.     mkdir -p $(dir $(OPM)) ;\
      9.     OS=$(shell go env GOOS) && ARCH=$(shell go env GOARCH) && \
      10.     curl -sSLo $(OPM) https://github.com/operator-framework/operator-registry/releases/download/v1.23.0/$${OS}-$${ARCH}-opm ;\ (1)
      11.     chmod +x $(OPM) ;\
      12.     }
      13. else
      14. OPM = $(shell which opm)
      15. endif
      16. endif
      1Replace v1.19.1 with v1.23.0.

    4. Edit your Makefile to replace the go get targets with go install targets:

      Old Makefile

      1. CONTROLLER_GEN = $(shell pwd)/bin/controller-gen
      2. .PHONY: controller-gen
      3. controller-gen: ## Download controller-gen locally if necessary.
      4.     $(call go-get-tool,$(CONTROLLER_GEN),sigs.k8s.io/controller-tools/cmd/controller-gen@v0.8.0)
      6. KUSTOMIZE = $(shell pwd)/bin/kustomize
      7. .PHONY: kustomize
      8. kustomize: ## Download kustomize locally if necessary.
      9.     $(call go-get-tool,$(KUSTOMIZE),sigs.k8s.io/kustomize/kustomize/v3@v3.8.7)
      11. ENVTEST = $(shell pwd)/bin/setup-envtest
      12. .PHONY: envtest
      13. envtest: ## Download envtest-setup locally if necessary.
      14.     $(call go-get-tool,$(ENVTEST),sigs.k8s.io/controller-runtime/tools/setup-envtest@latest)
      16. # go-get-tool will 'go get' any package $2 and install it to $1.
      17. PROJECT_DIR := $(shell dirname $(abspath $(lastword $(MAKEFILE_LIST))))
      18. define go-get-tool
      19. @[ -f $(1) ] || { \
      20. set -e ;\
      21. TMP_DIR=$$(mktemp -d) ;\
      22. cd $$TMP_DIR ;\
      23. go mod init tmp ;\
      24. echo "Downloading $(2)" ;\
      25. GOBIN=$(PROJECT_DIR)/bin go get $(2) ;\
      26. rm -rf $$TMP_DIR ;\
      27. }
      28. endef

      New Makefile

      1. ##@ Build Dependencies
      3. ## Location to install dependencies to
      4. LOCALBIN ?= $(shell pwd)/bin
      5. $(LOCALBIN):
      6.     mkdir -p $(LOCALBIN)
      8. ## Tool Binaries
      9. KUSTOMIZE ?= $(LOCALBIN)/kustomize
      10. CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen
      11. ENVTEST ?= $(LOCALBIN)/setup-envtest
      13. ## Tool Versions
      14. KUSTOMIZE_VERSION ?= v3.8.7
      15. CONTROLLER_TOOLS_VERSION ?= v0.8.0
      17. KUSTOMIZE_INSTALL_SCRIPT ?= "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh"
      18. .PHONY: kustomize
      19. kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary.
      20. $(KUSTOMIZE): $(LOCALBIN)
      21.     curl -s $(KUSTOMIZE_INSTALL_SCRIPT) | bash -s -- $(subst v,,$(KUSTOMIZE_VERSION)) $(LOCALBIN)
      23. .PHONY: controller-gen
      24. controller-gen: $(CONTROLLER_GEN) ## Download controller-gen locally if necessary.
      25. $(CONTROLLER_GEN): $(LOCALBIN)
      26.     GOBIN=$(LOCALBIN) go install sigs.k8s.io/controller-tools/cmd/controller-gen@$(CONTROLLER_TOOLS_VERSION)
      28. .PHONY: envtest
      29. envtest: $(ENVTEST) ## Download envtest-setup locally if necessary.
      30. $(ENVTEST): $(LOCALBIN)
      31.     GOBIN=$(LOCALBIN) go install sigs.k8s.io/controller-runtime/tools/setup-envtest@latest

    5. Update ENVTEST_K8S_VERSION and controller-gen fields in your Makefile to support Kubernetes 1.24:

      1. ...
      2. ENVTEST_K8S_VERSION = 1.24 (1)
      3. ...
      4. sigs.k8s.io/controller-tools/cmd/controller-gen@v0.9.0 (2)
      1Update version 1.22 to 1.24.
      2Update version 0.7.0 to 0.9.0.

    6. Apply the changes to your Makefile and rebuild your Operator by entering the following command:

      1. $ make

  3. Make the following changes to the go.mod file to update Go and its dependencies:

    1. go 1.18 (1)
    3. require (
    4.   github.com/onsi/ginkgo v1.16.5 (2)
    5.   github.com/onsi/gomega v1.18.1 (3)
    6.   k8s.io/api v0.24.0 (4)
    7.   k8s.io/apimachinery v0.24.0 (4)
    8.   k8s.io/client-go v0.24.0 (4)
    9.   sigs.k8s.io/controller-runtime v0.12.1 (5)
    10. )
    1Update version 1.16 to 1.18.
    2Update version v1.16.4 to v1.16.5.
    3Update version v1.15.0 to v1.18.1.
    4Update version v0.22.1 to v0.24.0.
    5Update version v0.10.0 to v0.12.1.

  4. Download and clean up the dependencies by entering the following command:

    1. $ go mod tidy

  5. If you use the api/webhook_suitetest.go and controllers/suite_test.go suite test files, make the following changes:

    Old suite test file

    1. cfg, err := testEnv.Start()

    New suite test file

    1. var err error
    2. // cfg is defined in this file globally.
    3. cfg, err = testEnv.Start()

  6. If you use the Kubernetes declarative plug-in, update your Dockerfile with the following changes:

    1. Add the following changes below the line that begins COPY controllers/ controllers/:

      1. # https://github.com/kubernetes-sigs/kubebuilder-declarative-pattern/blob/master/docs/addon/walkthrough/README.md#adding-a-manifest
      2. # Stage channels and make readable
      3. COPY channels/ /channels/
      4. RUN chmod -R a+rx /channels/

    2. Add the following changes below the line that begins COPY --from=builder /workspace/manager .:

      1. # copy channels
      2. COPY --from=builder /channels /channels

Additional resources