v1.0.0

Each project type has an appropriate migration guide, which we recommend following before reading this guide:

• Go
• Helm

The following subcommands were removed:

Library changes

Subpackages of the pkg/ directory have either been removed or moved from the operator-sdk repo to the operator-lib repo.

Removed packages:

• pkg/kube-metrics
• pkg/ready

Packages that have been moved can be used by making the following changes:

• The EnqueueRequestForAnnotation watch handler is now available in package github.com/operator-framework/operator-lib/handler

• The GenerationChangedPredicate was refactored and moved. Rewrite it as a composite predicate like the following:

• The leader-for-life leader election library at pkg/leader was moved to github.com/operator-framework/operator-lib/leader.

• The pkg/status library with status conditions helpers was moved to github.com/operator-framework/operator-lib/status.

See the following PRs for details:

• #3532

Upgrade your project from version “2” to “3-alpha”

The SDK’s default Go plugin no longer supports OLM- or scorecard-related project files nor writes a PROJECT field for projects scaffolded previously with operator-sdk init --project-version=2, Please migrate to project version “3-alpha” for support of these features by adding the following to your PROJECT file:

version: "3-alpha" # Updated from "2"
projectName: <output of "$(basename $(pwd))">
layout: go.kubebuilder.io/v2
plugins:
  go.sdk.operatorframework.io/v2-alpha: {}

See and #3697 for more details.

Add the samples scaffold marker to your config/samples/kustomization.yaml

Add the +kubebuilder:scaffold:manifestskustomizesamples to your config/samples/kustomization.yaml file like so (using an example sample file):

See #3645 for more details.

Update your Makefile’s bundle recipe to inject an operator image tag.

Make the following update to your Makefile’s bundle recipe, which will allow you to set make bundle IMG=<tag>:

bundle:
  ...
  operator-sdk generate kustomize manifests -q
  cd config/manager && $(KUSTOMIZE) edit set image controller=$(IMG) # Add this line
  ...

See #3634 for more details.

Update usage of operator-sdk cleanup

The operator-sdk cleanup packagemanifests command has been removed and replaced with a simpler operator-sdk cleanup command.

Update usages of operator-sdk cleanup packagemanifests to use operator-sdk cleanup <packageName>.

The value for <packageName> can be found in the *.package.yaml file in the root of your packagemanifests folder. It is typically your project name.

See #3644 for more details.

Remove olm-namespace flag from operator-sdk olm install command

The olm-namespace flag has been removed from operator-sdk olm install command, as the olm manifests published in github have a hardcoded namespace value. Hence, the olm operators can only be installed in olm namespace using this command.

See #3670 for more details.

Docker images for s390x are no longer created automatically

If you require an s390x image for a particular release, please open an issue in the operator-sdk GitHub project, and the maintainers will manually build and push an s390x image for supported versions

See #3710 for more details.

Default install mode for run packagemanifests changed from OwnNamespace to AllNamespaces

By default all operators are scaffolded to run at the cluster scope and watch all namespaces. However, if you are relying on the default behavior of the run packagemanifests command to use the default OwnNamespace install mode, you must now specify it explicitly with --install-mode=OwnNamespace.

See #3663 for more details.

Use new logging flags when running the Ansible and Helm operators

The Ansible and Helm operators now use controller-runtime’s zap package to define logging flags.

The --zap-sample and --zap-time-encoding flag have been removed since they are not present in controller-runtime’s flagset. These flags are no longer supported.

See #3596 for more details.

Core Ansible and Helm operator logic moved to <ansible-operator|helm-operator> run subcommand

If you are using the ansible-operator and helm-operator binaries directly, update your usage to call ansible-operator run and helm-operator run (e.g. in your Makefile’s make run target).

If you are using the base image and you are not overriding the operator entrypoint, no change is necessary because the base image has been updated to call the run subcommand by default.

See #3596 for more details.

This flag has been renamed to account for all objects that can be written to the package directory, ex. Roles.

See for more details.

Update scorecard API Go import paths

The scorecard v1alpha3 API has been moved to a separate repo. Update your Go import paths:

Old:

New:

import "github.com/operator-framework/api/pkg/apis/scorecard/v1alpha3"

See for more details.

Package version is no longer public

It is no longer possible to import package version. To determine the version of operator-sdk, run operator-sdk version.

See for more details.

Remove --operator-name from scripts

The --operator-name flag has been removed from generate bundle and generate packagemanifests subcommands. Remove this flag from your scripts, and make sure the projectName key is set in your PROJECT file. If this key is not set, the current working directory’s base name will be used.

See for more details.

Create resources manually that were passed to run packagemanifests --include-paths

The run packagemanifests subcommand no longer has the --include-paths flag to create additional resources. Instead, use before invoking run packagemanifests.

See for more details.

Change the run packagemanifests flag --operator-version to --version

--operator-version is now --version.

See for more details.

Remove --olm-namespace from run packagemanifests invocations

OLM namespace is no longer required by this command.

See for more details.

Change the run packagemanifests flag --operator-namespace to --namespace

--operator-namespace is now --namespace.

See for more details.

pkg/log/zap is no longer a public API

Migrate to the upstream controller-runtime implementation in .

See #3525 for more details.

Default Ansible and Helm operator metrics port has changed

To continue using port 8383, specify --metrics-addr=:8383 when you start the operator.

See #3489 and for more details.

Update references to legacy operator-sdk domain strings

Update various usages of domains in plugin keys and annotations:

• In Kubebuilder-style projects, change the .operator-sdk.io suffix to .sdk.operatorframework.io in the PROJECT file.

• In live clusters containing CRs for Ansible and Helm-based operators:

  1. Patch all existing CRs that use a legacy annotation to ADD the new equivalent annotations alongside the legacy annotations.
  2. Upgrade the operator
  3. Patch all existing CRs that used a legacy annotation to REMOVE the legacy annotations.

See for more details.

There is no migration path that enables continued use of the Ansible-based or Helm-based operator Go libraries.

See #3560 and for more details.

Changes to Ansible and Helm configuration of max workers

• Flag max-workers was renamed to max-concurrent-reconciles in Ansible and Helm operators. Change all usage of --max-workers to --max-concurrent-reconciles. Functionality is identical; this is just a name change to align more with controller runtime terminology.

• The WORKERS_<Kind>_<Group> environment variable was deprecated. Change all usage of these environment variables to MAX_CONCURRENT_RECONCILES_<Kind>_<Group>.

See , #3452, and for more details.

Ansible Operator meta variable renamed to ansible_operator_meta

All existing references to the meta variable in your Ansible content will no longer work. Instead, your Ansible content should reference the ansible_operator_meta variable.

Alternatively, you can use the vars keyword in your watches.yaml in order to map the new ansible_operator_meta variable to meta. Below is a sample watches.yaml that has made this change:

See for more details.

Migrated Ansible and Helm operators to use new Kubebuilder-style metrics

• Replaced kube-state-metrics style metrics on port :8686 with a similar resource_created_at metric registered with the controller-runtime metrics registry

See and #3451 for more details.

Removed package pkg/k8sutil

With the transition to Kubebuilder-style projects, pkg/k8sutil is no longer used in the default scaffolding for Go operators. Migrate your project to the new Kubebuilder-style layout to remove the need for this package.

See #3475 for more details.

Removed packages pkg/kube-metrics and pkg/metrics

Remove the call to addMetrics in your main.go file and begin using the InstrumentedEnqueueRequestForObject handler when setting up controller-runtime watches for your primary CRs.

InstrumentedEnqueueRequestForObject can be imported from github.com/operator-framework/operator-lib/handler.

See #3484 for more details.

Removed package pkg/ready

Use controller-runtime‘s readyz server that supports custom http handlers. Add add a healthz.Checker (e.g. healthz.Ping) using .

See #3476 for more details.

Removed package pkg/tls

See the Kubebuilder docs on how to deploy and manage TLS certificates with cert-manager.

See for more details.

Update your scorecard config file to the new format

See the updated scorecard for details.

See #3434 and for more details.

Use scorecard instead of alpha scorecard

If you have been using operator-sdk alpha scorecard, update to use operator-sdk scorecard. If you have been using operator-sdk scorecard, migrate to the new scorecard. See the new .

See #3444 for more details.

Scorecard output formatting has changed

Update any scripts interpretting the scorecard output to understand the format.

See the json and format descriptions for details.