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
×

Operator SDK CLI reference

This guide documents the Operator SDK CLI commands and their syntax:

$ operator-sdk <command> [<subcommand>] [<argument>] [<flags>]

build

The operator-sdk build command compiles the code and builds the executables. After build completes, the image is built using a local container engine. It must then be pushed to a remote registry.

Table 1. build arguments
Argument Description

<image>

The container image to be built, for example quay.io/example/operator:v0.0.1.
Table 2. build flags
Flag Description

--enable-tests (bool)

Enable in-cluster testing by adding test binary to the image.

--namespaced-manifest (string)

Path of namespaced resources manifest for tests. Default: deploy/operator.yaml.

--test-location (string)

Location of tests. Default: ./test/e2e.

-h, --help

Usage help output.

If --enable-tests is set, the build command also builds the testing binary, adds it to the container image, and generates a deploy/test-pod.yaml file that allows a user to run the tests as a pod on a cluster.

For example:

$ operator-sdk build quay.io/example/operator:v0.0.1
Example output
building example-operator...

building container quay.io/example/operator:v0.0.1...
Sending build context to Docker daemon  163.9MB
Step 1/4 : FROM alpine:3.6
 ---> 77144d8c6bdc
Step 2/4 : ADD tmp/_output/bin/example-operator /usr/local/bin/example-operator
 ---> 2ada0d6ca93c
Step 3/4 : RUN adduser -D example-operator
 ---> Running in 34b4bb507c14
Removing intermediate container 34b4bb507c14
 ---> c671ec1cff03
Step 4/4 : USER example-operator
 ---> Running in bd336926317c
Removing intermediate container bd336926317c
 ---> d6b58a0fcb8c
Successfully built d6b58a0fcb8c
Successfully tagged quay.io/example/operator:v0.0.1

completion

The operator-sdk completion command generates shell completions to make issuing CLI commands quicker and easier.

Table 3. completion subcommands
Subcommand Description

bash

Generate bash completions.

zsh

Generate zsh completions.
Table 4. completion flags
Flag Description

-h, --help

Usage help output.

For example:

$ operator-sdk completion bash
Example output
# bash completion for operator-sdk                         -*- shell-script -*-
...
# ex: ts=4 sw=4 et filetype=sh

print-deps

The operator-sdk print-deps command prints the most recent Golang packages and versions required by Operators. It prints in columnar format by default.

Table 5. print-deps flags
Flag Description

--as-file

Print packages and versions in Gopkg.toml format.

For example:

$ operator-sdk print-deps --as-file
Example output
required = [
  "k8s.io/code-generator/cmd/defaulter-gen",
  "k8s.io/code-generator/cmd/deepcopy-gen",
  "k8s.io/code-generator/cmd/conversion-gen",
  "k8s.io/code-generator/cmd/client-gen",
  "k8s.io/code-generator/cmd/lister-gen",
  "k8s.io/code-generator/cmd/informer-gen",
  "k8s.io/code-generator/cmd/openapi-gen",
  "k8s.io/gengo/args",
]

[[override]]
  name = "k8s.io/code-generator"
  revision = "6702109cc68eb6fe6350b83e14407c8d7309fd1a"
...

generate

The operator-sdk generate command invokes a specific generator to generate code as needed.

crds

The generate crds subcommand generates custom resource definitions (CRDs) or updates them if they exist, under deploy/crds/__crd.yaml. OpenAPI V3 validation YAML is generated as a validation object.

Table 6. generate crds flags
Flag Description

--crd-version (string)

CRD version to generate. Default: v1beta1

-h, --help

Help for generate crds

For example:

$ operator-sdk generate crds
$ tree deploy/crds
Example output
├── deploy/crds/app.example.com_v1alpha1_appservice_cr.yaml
└── deploy/crds/app.example.com_appservices_crd.yaml

csv

The csv subcommand writes a cluster service version (CSV) manifest for use with Operator Lifecycle Manager (OLM). It also optionally writes CRD files to deploy/olm-catalog/<operator_name>/<csv_version>.

Table 7. generate csv flags
Flag Description

--csv-channel (string)

The channel the CSV should be registered under in the package manifest.

--csv-config (string)

The path to the CSV configuration file. Default: deploy/olm-catalog/csv-config.yaml.

--csv-version (string)

The semantic version of the CSV manifest. Required.

--default-channel

Use the channel passed to --csv-channel as the default channel of the package manifests. Only valid when --csv-channel is set.

--from-version (string)

The semantic version of CSV manifest to use as a base for a new version.

--operator-name

The Operator name to use while generating the CSV.

--update-crds

Updates CRD manifests in deploy/<operator_name>/<csv_version> using the latest CRD manifests.

For example:

$ operator-sdk generate csv \
    --csv-version 0.1.0 \
		--update-crds
Example output
INFO[0000] Generating CSV manifest version 0.1.0
INFO[0000] Fill in the following required fields in file deploy/olm-catalog/operator-name/0.1.0/operator-name.v0.1.0.clusterserviceversion.yaml:
	spec.keywords
	spec.maintainers
	spec.provider
	spec.labels
INFO[0000] Created deploy/olm-catalog/operator-name/0.1.0/operator-name.v0.1.0.clusterserviceversion.yaml

k8s

The k8s subcommand runs the Kubernetes code-generators for all CRD APIs under pkg/apis/. Currently, k8s only runs deepcopy-gen to generate the required DeepCopy() functions for all custom resource (CR) types.

This command must be run every time the API (spec and status) for a custom resource type is updated.

For example:

$ tree pkg/apis/app/v1alpha1/
Example output
pkg/apis/app/v1alpha1/
├── appservice_types.go
├── doc.go
└── register.go
$ operator-sdk generate k8s
Example output
Running code-generation for Custom Resource (CR) group versions: [app:v1alpha1]
Generating deepcopy funcs
$ tree pkg/apis/app/v1alpha1/
Example output
pkg/apis/app/v1alpha1/
├── appservice_types.go
├── doc.go
├── register.go
└── zz_generated.deepcopy.go

new

The operator-sdk new command creates a new Operator application and generates (or scaffolds) a default project directory layout based on the input <project_name>.

Table 8. new arguments
Argument Description

<project_name>

Name of the new project.
Table 9. new flags
Flag Description

--api-version

CRD API version in the format <group_name>/<version>, for example app.example.com/v1alpha1. Used with ansible or helm types.

--generate-playbook

Generate an Ansible playbook skeleton. Used with ansible type.

--header-file <string>

Path to file containing headers for generated Go files. Copied to hack/boilerplate.go.txt.

--helm-chart <string>

Initialize Helm Operator with existing Helm chart: <url>, <repo>/<name>, or local path.

--helm-chart-repo <string>

Chart repository URL for the requested Helm chart.

--helm-chart-version <string>

Specific version of the Helm chart. Default: latest version.

--help, -h

Usage and help output.

--kind <string>

CRD kind, for example AppService. Used with ansible or helm types.

--skip-git-init

Do not initialize the directory as a Git repository.

--type

Type of Operator to initialize: go, ansible or helm. Default: go.

Starting with Operator SDK v0.12.0, the --dep-manager flag and support for dep-based projects have been removed. Go projects are now scaffolded to use Go modules.
Example usage for Go project
$ mkdir $GOPATH/src/github.com/example.com/
$ cd $GOPATH/src/github.com/example.com/
$ operator-sdk new app-operator
Example usage for Ansible project
$ operator-sdk new app-operator \
    --type=ansible \
    --api-version=app.example.com/v1alpha1 \
    --kind=AppService

add

The operator-sdk add command adds a controller or resource to the project. The command must be run from the Operator project root directory.

Table 10. add subcommands
Subcommand Description

api

Adds a new API definition for a new custom resource (CR) under pkg/apis and generates the custom resource definition (CRD) and CR files under deploy/crds/. If the API already exists at pkg/apis/<group>/<version>, then the command does not overwrite and returns an error.

controller

Adds a new controller under pkg/controller/<kind>/. The controller expects to use the CR type that should already be defined under pkg/apis/<group>/<version> via the operator-sdk add api --kind=<kind> --api-version=<group/version> command. If the controller package for that kind already exists at pkg/controller/<kind>, then the command does not overwrite and returns an error.

crd

Adds a CRD and the CR files. The <project_name>/deploy path must already exist. The --api-version and --kind flags are required to generate the new Operator application.

  • Generated CRD filename: <project_name>/deploy/crds/<group>_<version>_<kind>_crd.yaml

  • Generated CR filename: <project_name>/deploy/crds/<group>_<version>_<kind>_cr.yaml
Table 11. add api flags
Flag Description

--api-version (string)

CRD API version in the format <group_name>/<version>, for example app.example.com/v1alpha1.

--kind (string)

CRD Kind (e.g., AppService).

For example:

$ operator-sdk add api \
    --api-version app.example.com/v1alpha1 \
    --kind AppService
Example output
Create pkg/apis/app/v1alpha1/appservice_types.go
Create pkg/apis/addtoscheme_app_v1alpha1.go
Create pkg/apis/app/v1alpha1/register.go
Create pkg/apis/app/v1alpha1/doc.go
Create deploy/crds/app_v1alpha1_appservice_cr.yaml
Create deploy/crds/app_v1alpha1_appservice_crd.yaml
Running code-generation for Custom Resource (CR) group versions: [app:v1alpha1]
Generating deepcopy funcs
$ tree pkg/apis
Example output
pkg/apis/
├── addtoscheme_app_appservice.go
├── apis.go
└── app
    └── v1alpha1
        ├── doc.go
        ├── register.go
        └── types.go
$ operator-sdk add controller \
    --api-version app.example.com/v1alpha1 \
    --kind AppService
Example output
Create pkg/controller/appservice/appservice_controller.go
Create pkg/controller/add_appservice.go
$ tree pkg/controller
Example output
pkg/controller/
├── add_appservice.go
├── appservice
│   └── appservice_controller.go
└── controller.go
$ operator-sdk add crd \
    --api-version app.example.com/v1alpha1 \
    --kind AppService
Example output
Generating Custom Resource Definition (CRD) files
Create deploy/crds/app_v1alpha1_appservice_crd.yaml
Create deploy/crds/app_v1alpha1_appservice_cr.yaml

test

The operator-sdk test command can test the Operator locally.

local

The local subcommand runs Go tests built using the test framework of the Operator SDK locally.

Table 12. test local arguments
Arguments Description

<test_location> (string)

Location of end-to-end (e2e) test files, for example ./test/e2e/.
Table 13. test local flags
Flags Description

--kubeconfig (string)

Location of kubeconfig for a cluster. Default: ~/.kube/config.

--global-manifest (string)

Path to manifest for global resources. Default: deploy/crd.yaml.

--namespaced-manifest (string)

Path to manifest for per-test, namespaced resources. Default: combines deploy/service_account.yaml, deploy/rbac.yaml, and deploy/operator.yaml.

--namespace (string)

If non-empty, a single namespace to run tests in, for example operator-test. Default: "".

--go-test-flags (string)

Extra arguments to pass to go test, for example -f "-v -parallel=2".

--up-local

Enable running the Operator locally with go run instead of as an image in the cluster.

--no-setup

Disable test resource creation.

--image (string)

Use a different Operator image from the one specified in the namespaced manifest.

-h, --help

Usage help output.

For example:

$ operator-sdk test local ./test/e2e/
Example output
ok  	github.com/operator-framework/operator-sdk-samples/memcached-operator/test/e2e	20.410s

run

The operator-sdk run command provides options that can launch the Operator in various environments.

Table 14. run arguments
Arguments Description

--kubeconfig (string)

The file path to a Kubernetes configuration file. Default: $HOME/.kube/config

--local

The Operator is run locally by building the Operator binary with the ability to access a Kubernetes cluster using a kubeconfig file.

--namespace (string)

The namespace where the Operator watches for changes. Default: default

--operator-flags

Flags that the local Operator might require. Example: --flag1 value1 --flag2=value2. For use with the --local flag only.

-h, --help

Usage help output.

--local

The --local flag launches the Operator on the local machine by building the Operator binary with the ability to access a Kubernetes cluster using a kubeconfig file.

For example:

$ operator-sdk run --local \
  --kubeconfig "mycluster.kubecfg" \
  --namespace "default" \
  --operator-flags "--flag1 value1 --flag2=value2"

The following example uses the default kubeconfig, the default namespace environment variable, and passes in flags for the Operator. To use the Operator flags, your Operator must know how to handle the option. For example, for an Operator that understands the resync-interval flag:

$ operator-sdk run --local --operator-flags "--resync-interval 10"

If you are planning on using a different namespace than the default, use the --namespace flag to change where the Operator is watching for custom resources (CRs) to be created:

$ operator-sdk run --local --namespace "testing"

For this to work, your Operator must handle the WATCH_NAMESPACE environment variable. This can be accomplished using the utility function k8sutil.GetWatchNamespace in your Operator.