Skip to content

sdk-cli-reference.md

Latest commit

 

History

History
621 lines (447 loc) · 22.6 KB

sdk-cli-reference.md

File metadata and controls

621 lines (447 loc) · 22.6 KB

Operator SDK Command Line Interface (CLI) Reference

Usage:
  operator-sdk [command]

Global Flags

  • --verbose - enable debug logging

build

Args

  • image - is the container image to be built, e.g. "quay.io/example/operator:v0.0.1".

Flags

  • --image-build-args string - extra, optional image build arguments as one string such as "--build-arg https_proxy=$https_proxy" (default "")
  • --image-builder string - tool to build OCI images. One of: [docker, podman, buildah] (default "docker")
  • --go-build-args string - extra Go build arguments as one string such as "-ldflags -X=main.xyz=abc"
  • -h, --help - help for build

Use

The operator-sdk build command compiles the code and builds the executables. After build completes, the image is built locally using the image builder specified by the --image-builder flag (default docker). Then it needs to be pushed to a remote registry.

Example

Build

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

building container quay.io/example/operator:v0.0.1...
Sending build context to Docker daemon  163.9MB
Step 1/4 : FROM registry.access.redhat.com/ubi8/ubi-minimal:latest
 ---> 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

Available Commands

bash - Generate bash completions

Flags
  • -h, --help - help for bash

zsh - Generate zsh completions

Flags
  • -h, --help - help for zsh

Flags

  • -h, --help - help for completion

Use

Generators for shell completions

Example:

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

print-deps

Prints the most recent Golang packages and versions required by operators. Prints in columnar format by default.

Example

$ operator-sdk print-deps
module github.com/example-inc/memcached-operator

require (
	contrib.go.opencensus.io/exporter/ocagent v0.4.9 // indirect
	github.com/Azure/go-autorest v11.5.2+incompatible // indirect
	github.com/appscode/jsonpatch v0.0.0-20190108182946-7c0e3b262f30 // indirect
	github.com/coreos/prometheus-operator v0.26.0 // indirect

generate

k8s

Runs the Kubernetes code-generators for all Custom Resource Definitions (CRD) apis under pkg/apis/.... Currently only runs deepcopy-gen to generate the required DeepCopy() functions for all custom resource types.

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

Example

$ tree pkg/apis/app/v1alpha1/
pkg/apis/app/v1alpha1/
├── appservice_types.go
├── doc.go
├── register.go

$ operator-sdk generate k8s
INFO[0000] Running deepcopy code-generation for Custom Resource group versions: [app:[v1alpha1], ]
INFO[0001] Code-generation complete.

$ tree pkg/apis/app/v1alpha1/
pkg/apis/app/v1alpha1/
├── appservice_types.go
├── doc.go
├── register.go
└── zz_generated.deepcopy.go

openapi

DEPRECATED

The operator-sdk generate openapi command is deprecated

  • To generate CRDs, use 'operator-sdk generate crds'.

  • To generate Go OpenAPI code, use 'openapi-gen'. For example:

    # Build the latest openapi-gen from source
which ./bin/openapi-gen > /dev/null || go build -o ./bin/openapi-gen k8s.io/kube-openapi/cmd/openapi-gen

# Run openapi-gen for each of your API group/version packages
./bin/openapi-gen --logtostderr=true -o "" -i ./pkg/apis/<group>/<version> -O zz_generated.openapi -p ./pkg/apis/<group>/<version> -h ./hack/boilerplate.go.txt -r "-"

Runs the kube-openapi OpenAPIv3 code generator for all Custom Resource Definition (CRD) API tagged fields under pkg/apis/....

Note: This command must be run every time a tagged API struct or struct field for a custom resource type is updated.

Example

$ tree pkg/apis/app/v1alpha1/
pkg/apis/app/v1alpha1/
├── appservice_types.go
├── doc.go
└── register.go

$ operator-sdk generate openapi
INFO[0000] Running OpenAPI code-generation for Custom Resource group versions: [app:[v1alpha1], ]
INFO[0001] Created deploy/crds/app.example.com_appservices_crd.yaml
INFO[0001] Code-generation complete.

$ tree pkg/apis/app/v1alpha1/
pkg/apis/app/v1alpha1/
├── appservice_types.go
├── doc.go
├── register.go
└── zz_generated.openapi.go

crds

Runs CRD generation (based on controller-tools) for APIs under pkg/apis/....

Note: This command must be run every time a tagged API struct or struct field for a custom resource type is updated.

Example

$ tree pkg/apis/app/v1alpha1/
pkg/apis/app/v1alpha1/
├── appservice_types.go
├── doc.go
└── register.go

$ operator-sdk generate crds
INFO[0000] Running CRD generation for Custom Resource group versions: [app:[v1alpha1], ]
INFO[0001] Created deploy/crds/app.example.com_appservices_crd.yaml
INFO[0001] CRD generation complete.

$ tree deploy/crds/
deploy/crds
└── app.example.com_appservices_crd.yaml

olm-catalog

Parent command for all OLM Catalog related commands.

gen-csv

Writes a Cluster Service Version (CSV) manifest and optionally CRD files to deploy/olm-catalog/{operator-name}/{csv-version}.

Flags

  • --csv-version string - (required) Semantic version of the CSV manifest.
  • --from-version string - Semantic version of CSV manifest to use as a base for a new version.
  • --csv-config string - Path to CSV config file. Defaults to deploy/olm-catalog/csv-config.yaml.
  • --update-crds Update CRD manifests in deploy/{operator-name}/{csv-version} using the latest CRD manifests.
  • --csv-channel string - Channel the CSV should be registered under in the package manifest
  • --default-channel - Use the channel passed to --csv-channel as the package manifests' default channel. Only valid when --csv-channel is set.
  • --operator-name string - Operator name to use while generating this CSV.

Example

$ operator-sdk olm-catalog gen-csv --csv-version 0.1.0 --update-crds
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

migrate

Adds a main.go source file and any associated source files for an operator that is not of the "go" type.

Note: This command will look for playbook.yml in the project root, if you use the .yaml extension you will need to rename it before running migrate or manually add it to your Dockerfile.

Flags

  • --header-file string - Path to file containing headers for generated Go files. Copied to hack/boilerplate.go.txt
  • --repo string - Project repository path for Go operators. Used as the project's Go import path. This must be set if outside of $GOPATH/src (e.g. github.com/example-inc/my-operator)

Example

$ operator-sdk migrate
INFO[0000] No playbook was found, so not including it in the new Dockerfile
INFO[0000] Renamed Dockerfile to build/Dockerfile.sdkold and replaced with newer version. Compare the new Dockerfile to your old one and manually migrate any customizations
INFO[0000] Created go.mod
INFO[0000] Created cmd/manager/main.go
INFO[0000] Created build/Dockerfile
INFO[0000] Created bin/entrypoint
INFO[0000] Created bin/user_setup
INFO[0000] Created library/k8s_status.py
INFO[0000] Created bin/ao-logs

new

Scaffolds a new operator project.

Args

  • project-name - name of the new project

Flags

  • --type string - Type of operator to initialize: "ansible", "helm", or "go" (default "go"). Also requires the following flags if --type=ansible or --type=helm
  • --api-version string - CRD APIVersion in the format $GROUP_NAME/$VERSION (e.g app.example.com/v1alpha1)
  • --kind string - CRD Kind. (e.g AppService)
  • --generate-playbook - Generate a playbook skeleton. (Only used for --type ansible)
  • --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 is latest version)
  • --header-file string - Path to file containing headers for generated Go files. Copied to hack/boilerplate.go.txt
  • --repo string - Project repository path for Go operators. Used as the project's Go import path. This must be set if outside of $GOPATH/src (e.g. github.com/example-inc/my-operator)
  • --git-init - Initialize the project directory as a git repository (default false)
  • --vendor - Use a vendor directory for dependencies
  • --skip-validation - Do not validate the resulting project's structure and dependencies. (Only used for --type go)
  • -h, --help - help for new

Example

Go project

$ mkdir $HOME/projects/example.com/
$ cd $HOME/projects/example.com/
$ operator-sdk new app-operator

Ansible project

$ operator-sdk new app-operator --type=ansible --api-version=app.example.com/v1alpha1 --kind=AppService

Helm project

For more details about creating new Helm operator projects, see the Helm user guide.

$ operator-sdk new app-operator --type=helm \
    --api-version=app.example.com/v1alpha1 \
    --kind=AppService

$ operator-sdk new app-operator --type=helm \
    --api-version=app.example.com/v1alpha1 \
    --kind=AppService \
    --helm-chart=myrepo/app

$ operator-sdk new app-operator --type=helm \
    --helm-chart=myrepo/app

$ operator-sdk new app-operator --type=helm \
    --helm-chart=myrepo/app \
    --helm-chart-version=1.2.3

$ operator-sdk new app-operator --type=helm \
    --helm-chart=app \
    --helm-chart-repo=https://charts.mycompany.com/

$ operator-sdk new app-operator --type=helm \
    --helm-chart=app \
    --helm-chart-repo=https://charts.mycompany.com/ \
    --helm-chart-version=1.2.3

$ operator-sdk new app-operator --type=helm \
    --helm-chart=/path/to/local/chart-directories/app/

$ operator-sdk new app-operator --type=helm \
    --helm-chart=/path/to/local/chart-archives/app-1.2.3.tgz

add

api

Adds the API definition for a new custom resource under pkg/apis and generates the CRD and CR files under depoy/crds/..., and generates Kubernetes deepcopy functions and OpenAPIv3 validation specs for the new API.

Flags

  • --api-version string - (required) CRD APIVersion in the format $GROUP_NAME/$VERSION (e.g app.example.com/v1alpha1)
  • --kind string - (required) CRD Kind. (e.g AppService)
  • --skip-generation - Skip generation of deepcopy and OpenAPI code and OpenAPI CRD specs.

Example

$ operator-sdk add api --api-version app.example.com/v1alpha1 --kind AppService
INFO[0000] Generating api version app.example.com/v1alpha1 for kind AppService.
INFO[0000] Created pkg/apis/app/v1alpha1/appservice_types.go
INFO[0000] Created pkg/apis/addtoscheme_app_v1alpha1.go
INFO[0000] Created pkg/apis/app/v1alpha1/register.go
INFO[0000] Created pkg/apis/app/v1alpha1/doc.go
INFO[0000] Created deploy/crds/app.example.com_v1alpha1_appservice_cr.yaml
INFO[0000] Created deploy/crds/app.example.com_appservices_crd.yaml
INFO[0001] Running deepcopy code-generation for Custom Resource group versions: [app:[v1alpha1], ]
INFO[0002] Code-generation complete.
INFO[0002] Running OpenAPI code-generation for Custom Resource group versions: [app:[v1alpha1], ]
INFO[0004] Created deploy/crds/app.example.com_appservices_crd.yaml
INFO[0004] Code-generation complete.
INFO[0004] API generation complete.

controller

Adds a new controller under pkg/controller/<kind>/... that, by default, reconciles a custom resource for the specified apiversion and kind.

Flags

  • --api-version string - CRD APIVersion in the format $GROUP_NAME/$VERSION (e.g app.example.com/v1alpha1)
  • --kind string - CRD Kind. (e.g AppService)
  • --custom-api-import string - External Kubernetes resource import path of the form "host.com/repo/path[=import_identifier]". import_identifier is optional

Example

$ operator-sdk add controller --api-version app.example.com/v1alpha1 --kind AppService
Created pkg/controller/appservice/appservice_controller.go
Created pkg/controller/add_appservice.go

crd

Generates the CRD and the CR files for the specified api-version and kind.

Flags

  • --api-version string - CRD APIVersion in the format $GROUP_NAME/$VERSION (e.g app.example.com/v1alpha1)
  • --kind string - CRD Kind. (e.g AppService)

Example

$ operator-sdk add crd --api-version app.example.com/v1alpha1 --kind AppService
Generating custom resource definition (CRD) files
Created deploy/crds/app.example.com_appservices_crd.yaml
Created deploy/crds/app.example.com_v1alpha1_appservice_cr.yaml

run

ansible

Runs as an ansible operator process. This is intended to be used when running in a Pod inside a cluster. Developers wanting to run their operator locally should use up local instead.

Flags

  • --reconcile-period string - Default reconcile period for controllers (default 1m0s)
  • --watches-file string - Path to the watches file to use (default "./watches.yaml")

Example

$ operator-sdk run ansible --watches-file=/opt/ansible/watches.yaml --reconcile-period=30s

helm

Runs as a helm operator process. This is intended to be used when running in a Pod inside a cluster. Developers wanting to run their operator locally should use up local instead.

Flags

  • --reconcile-period string - Default reconcile period for controllers (default 1m0s)
  • --watches-file string - Path to the watches file to use (default "./watches.yaml")

Example

$ operator-sdk run helm --watches-file=/opt/helm/watches.yaml --reconcile-period=30s

scorecard

Run scorecard tests on an operator

Flags

  • basic-tests - Enable basic operator checks (default true)
  • config string - config file (default is '<project_dir>/.osdk-scorecard'; the config file's extension and format can be .yaml, .json, or .toml)
  • cr-manifest string - (required) Path to manifest for Custom Resource
  • crds-dir string - Directory containing CRD manifests (default "deploy/crds")
  • csv-path string - (required if olm-tests is set) Path to CSV being tested
  • global-manifest string - Path to manifest for Global resources (e.g. CRD manifests)
  • init-timeout int - Timeout for status block on CR to be created, in seconds (default 10)
  • kubeconfig string - Path to kubeconfig of custom resource created in cluster
  • namespace string - Namespace of custom resource created in cluster
  • namespaced-manifest string - Path to manifest for namespaced resources (e.g. RBAC and Operator manifest)
  • olm-deployed - Only use the CSV at csv-path for manifest data, except for those provided to cr-manifest
  • olm-tests - Enable OLM integration checks (default true)
  • -o, --output string - Output format for results. Valid values: human-readable or json (default human-readable)
  • proxy-image string - Image name for scorecard proxy (default "quay.io/operator-framework/scorecard-proxy")
  • proxy-pull-policy string - Pull policy for scorecard proxy image (default "Always")
  • selector string - Selector (label query) to filter tests on (only valid when version is v1alpha2)
  • -h, --help - help for scorecard
  • version string - The scorecard version to run (default v1alpha1), the tech preview version is v1alpha2.

Example

$ operator-sdk scorecard --cr-manifest deploy/crds/cache.example.com_v1alpha1_memcached_cr.yaml --csv-path deploy/olm-catalog/memcached-operator/0.0.2/memcached-operator.v0.0.2.clusterserviceversion.yaml -o text
basic:
	Writing into CRs has an effect     : pass
	Spec Block Exists                  : pass
	Status Block Exists                : pass
olm:
	Spec fields with descriptors       : pass
	Status fields with descriptors     : pass
	Provided APIs have validation      : fail
	Owned CRDs have resources listed   : pass
	CRs have at least 1 example        : pass
SUGGESTION: Add CRD validation for Memcached/v1alpha1
SUGGESTION: If it would be helpful to an end-user to understand or troubleshoot your CR, consider adding resources [deployments/v1 services/v1 configmaps/v1 memcacheds/v1alpha1 replicasets/v1] to the resources section for owned CRD Memcached

test

Available Commands

local

Runs the tests locally

Args
  • test-location - location of e2e test files (e.g. "./test/e2e/")
Flags
  • --debug - Enable debug-level logging
  • --kubeconfig string - location of kubeconfig for Kubernetes 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, single namespace to run tests in (e.g. "operator-test") (default: "")
  • --go-test-flags string - Additional flags to pass to go test
  • --molecule-test-flags string - Additional flags to pass to molecule test
  • --up-local - enable running operator locally with go run instead of as an image in the cluster
  • --local-operator-flags string - flags that the operator needs, while using --up-local (e.g. "--flag1 value1 --flag2=value2")
  • --no-setup - disable test resource creation
  • --image string - use a different operator image from the one specified in the namespaced manifest
  • -h, --help - help for local
Use

The operator-sdk test command runs go tests built using the Operator SDK's test framework.

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

up

Available Commands

local - Launches the operator locally

Use

The operator-sdk up local command launches the operator on the local machine with the ability to access a Kubernetes cluster using a kubeconfig file, and setting any necessary environment variables that the operator would expect to find when running in a cluster. For Go-based operators, this command will compile and run the operator binary. In the case of non-Go operators, it runs the operator-sdk binary itself as the operator.

Flags
  • --enable-delve bool - starts the operator locally and enables the delve debugger listening on port 2345
  • --go-ldflags string - Set Go linker options
  • --kubeconfig string - The file path to Kubernetes configuration file; defaults to $HOME/.kube/config
  • --namespace string - The namespace where the operator watches for changes. (default "default")
  • --operator-flags string - Flags that the local operator may need.
  • -h, --help - help for local
Example
$ operator-sdk up local --kubeconfig "mycluster.kubecfg" --namespace "default" --operator-flags "--flag1 value1 --flag2=value2"

The below example will use the default kubeconfig, the default namespace environment var, and pass in flags for the operator. To use the operator flags, your operator must know how to handle the option. Below imagine an operator that understands the resync-interval flag.

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

If you are planning on using a different namespace than the default, then you should use the --namespace flag to change where the operator is watching for custom resources to be created. For this to work your operator must handle the WATCH_NAMESPACE environment variable. To do that you can use the utility function k8sutil.GetWatchNamespace in your operator.

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

Flags

  • -h, --help - help for up

alpha olm

Flags

  • --timeout duration - time to wait for the command to complete before failing (default: "2m")

Available commands

install - Installs Operator Lifecycle Manager

Use

The operator-sdk alpha olm install command installs OLM in a Kubernetes cluster based on the configured kubeconfig. It works by downloading OLM's release manifests at a specific version (default: latest), checking to see if any of those resources already exist in the cluster (and aborting if they do), and then creating all of the necessary resources and waiting for them to become healthy. When the installation is complete, olm install outputs a status summary of all of the resources that were installed.

Flags
  • --version string - version of OLM resources to install, uninstall, or get status about (default: "latest")

uninstall - Uninstalls Operator Lifecycle Manager

Use

The operator-sdk alpha olm uninstall command uninstalls OLM from a Kubernetes cluster based on the configured kubeconfig. It works by downloading OLM's release manifests at the version installed in the cluster, checking to see if any of those resources exist (if none exist, it aborts with an error since OLM is not installed), and then deletes each resource that is listed in the downloaded release manifests. It waits until all resources have been fully cleaned up before returning.

status - Get status of the Operator Lifecycle Manager installation

Use

The operator-sdk alpha olm status command gets the status of the OLM installation in a Kubernetes cluster based on the configured kubeconfig. It works by downloading OLM's release manifests at the version installed in the cluster, checking to see if any of those resources exist (if none exist, it aborts with an error since OLM is not installed), and printing a summary of the status of each of those resources as they exist in the cluster.