github.imxd.top/operator-framework/operator-sdk@v0.8.2/doc/sdk-cli-reference.md (about) 1 # CLI Guide 2 3 ```bash 4 Usage: 5 operator-sdk [command] 6 ``` 7 8 ### Global Flags 9 10 * `--verbose` - enable debug logging 11 12 ## build 13 14 ### Args 15 16 * `image` - is the container image to be built, e.g. "quay.io/example/operator:v0.0.1". 17 18 ### Flags 19 20 * `--image-build-args` string - extra, optional image build arguments as one string such as `"--build-arg https_proxy=$https_proxy"` (default "") 21 * `--image-builder` string - tool to build OCI images. One of: `[docker, buildah]` (default "docker") 22 * `-h, --help` - help for build 23 24 ### Use 25 26 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. 27 28 ### Example 29 30 #### Build 31 32 ```console 33 $ operator-sdk build quay.io/example/operator:v0.0.1 34 building example-operator... 35 36 building container quay.io/example/operator:v0.0.1... 37 Sending build context to Docker daemon 163.9MB 38 Step 1/4 : FROM registry.access.redhat.com/ubi7/ubi-minimal:latest 39 ---> 77144d8c6bdc 40 Step 2/4 : ADD tmp/_output/bin/example-operator /usr/local/bin/example-operator 41 ---> 2ada0d6ca93c 42 Step 3/4 : RUN adduser -D example-operator 43 ---> Running in 34b4bb507c14 44 Removing intermediate container 34b4bb507c14 45 ---> c671ec1cff03 46 Step 4/4 : USER example-operator 47 ---> Running in bd336926317c 48 Removing intermediate container bd336926317c 49 ---> d6b58a0fcb8c 50 Successfully built d6b58a0fcb8c 51 Successfully tagged quay.io/example/operator:v0.0.1 52 ``` 53 54 ## completion 55 56 ### Available Commands 57 58 #### bash - Generate bash completions 59 60 ##### Flags 61 62 * `-h, --help` - help for bash 63 64 #### zsh - Generate zsh completions 65 66 ##### Flags 67 68 * `-h, --help` - help for zsh 69 70 ### Flags 71 72 * `-h, --help` - help for completion 73 74 ### Use 75 76 Generators for shell completions 77 78 Example: 79 80 ```console 81 $ operator-sdk completion bash 82 # bash completion for operator-sdk -*- shell-script -*- 83 ... 84 # ex: ts=4 sw=4 et filetype=sh 85 ``` 86 87 ## print-deps 88 89 Prints the most recent Golang packages and versions required by operators. Prints in columnar format by default. 90 91 ### Flags 92 93 * `--as-file` - Print packages and versions in go.mod or Gopkg.toml format, depending on the dependency manager chosen when initializing or migrating a project. 94 95 ### Example 96 97 With dependency manager `dep`: 98 99 ```console 100 $ operator-sdk print-deps --as-file 101 required = [ 102 "k8s.io/code-generator/cmd/deepcopy-gen", 103 "k8s.io/code-generator/cmd/conversion-gen", 104 "k8s.io/code-generator/cmd/client-gen", 105 "k8s.io/code-generator/cmd/lister-gen", 106 "k8s.io/code-generator/cmd/informer-gen", 107 "k8s.io/code-generator/cmd/openapi-gen", 108 "k8s.io/gengo/args", 109 ] 110 111 [[override]] 112 name = "k8s.io/code-generator" 113 revision = "6702109cc68eb6fe6350b83e14407c8d7309fd1a" 114 ... 115 ``` 116 117 With dependency manager `modules`, i.e. go mod: 118 119 ```console 120 $ operator-sdk print-deps --as-file 121 module github.com/example-inc/memcached-operator 122 123 require ( 124 contrib.go.opencensus.io/exporter/ocagent v0.4.9 // indirect 125 github.com/Azure/go-autorest v11.5.2+incompatible // indirect 126 github.com/appscode/jsonpatch v0.0.0-20190108182946-7c0e3b262f30 // indirect 127 github.com/coreos/prometheus-operator v0.26.0 // indirect 128 ``` 129 130 ## generate 131 132 ### k8s 133 134 Runs the Kubernetes [code-generators][k8s-code-generator] for all Custom Resource Definitions (CRD) apis under `pkg/apis/...`. 135 Currently only runs `deepcopy-gen` to generate the required `DeepCopy()` functions for all custom resource types. 136 137 **Note**: This command must be run every time the api (spec and status) for a custom resource type is updated. 138 139 ### Flags 140 141 * `--header-file` string - Path to file containing headers for generated files (optional). 142 143 #### Example 144 145 ```console 146 $ tree pkg/apis/app/v1alpha1/ 147 pkg/apis/app/v1alpha1/ 148 ├── appservice_types.go 149 ├── doc.go 150 ├── register.go 151 152 $ operator-sdk generate k8s 153 INFO[0000] Running deepcopy code-generation for Custom Resource group versions: [app:[v1alpha1], ] 154 INFO[0001] Code-generation complete. 155 156 $ tree pkg/apis/app/v1alpha1/ 157 pkg/apis/app/v1alpha1/ 158 ├── appservice_types.go 159 ├── doc.go 160 ├── register.go 161 └── zz_generated.deepcopy.go 162 ``` 163 164 ### openapi 165 166 Runs the [kube-openapi][openapi-code-generator] OpenAPIv3 code generator for all Custom Resource Definition (CRD) API tagged fields under `pkg/apis/...`. 167 168 **Note**: This command must be run every time a tagged API struct or struct field for a custom resource type is updated. 169 170 #### Example 171 172 ```console 173 $ tree pkg/apis/app/v1alpha1/ 174 pkg/apis/app/v1alpha1/ 175 ├── appservice_types.go 176 ├── doc.go 177 ├── register.go 178 179 $ operator-sdk generate openapi 180 INFO[0000] Running OpenAPI code-generation for Custom Resource group versions: [app:[v1alpha1], ] 181 INFO[0001] Created deploy/crds/app_v1alpha1_appservice_crd.yaml 182 INFO[0001] Code-generation complete. 183 184 $ tree pkg/apis/app/v1alpha1/ 185 pkg/apis/app/v1alpha1/ 186 ├── appservice_types.go 187 ├── doc.go 188 ├── register.go 189 └── zz_generated.openapi.go 190 ``` 191 192 ## olm-catalog 193 194 Parent command for all OLM Catalog related commands. 195 196 ### gen-csv 197 198 Writes a Cluster Service Version (CSV) manifest and optionally CRD files to `deploy/olm-catalog/{operator-name}/{csv-version}`. 199 200 #### Flags 201 202 * `--csv-version` string - (required) Semantic version of the CSV manifest. 203 * `--from-version` string - Semantic version of CSV manifest to use as a base for a new version. 204 * `--csv-config` string - Path to CSV config file. Defaults to deploy/olm-catalog/csv-config.yaml. 205 * `--update-crds` Update CRD manifests in deploy/{operator-name}/{csv-version} using the latest CRD manifests. 206 207 #### Example 208 209 ```console 210 $ operator-sdk olm-catalog gen-csv --csv-version 0.1.0 --update-crds 211 INFO[0000] Generating CSV manifest version 0.1.0 212 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: 213 spec.keywords 214 spec.maintainers 215 spec.provider 216 spec.labels 217 INFO[0000] Created deploy/olm-catalog/operator-name/0.1.0/operator-name.v0.1.0.clusterserviceversion.yaml 218 ``` 219 220 ## migrate 221 222 Adds a main.go source file and any associated source files for an operator that 223 is not of the "go" type. 224 225 **Note**: This command will look for playbook.yml in the project root, if you use the .yaml extension 226 you will need to rename it before running migrate or manually add it to your Dockerfile. 227 228 #### Flags 229 230 * `--dep-manager` string - Dependency manager the migrated project will use (choices: "dep", "modules") (default "modules") 231 232 ### Example 233 234 ```console 235 $ operator-sdk migrate 236 INFO[0000] No playbook was found, so not including it in the new Dockerfile 237 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 238 INFO[0000] Created go.mod 239 INFO[0000] Created cmd/manager/main.go 240 INFO[0000] Created build/Dockerfile 241 INFO[0000] Created bin/entrypoint 242 INFO[0000] Created bin/user_setup 243 INFO[0000] Created library/k8s_status.py 244 INFO[0000] Created bin/ao-logs 245 ``` 246 247 ## new 248 249 Scaffolds a new operator project. 250 251 ### Args 252 253 * `project-name` - name of the new project 254 255 ### Flags 256 257 * `--skip-git-init` - Do not init the directory as a git repository 258 * `--type` string - Type of operator to initialize: "ansible", "helm", or "go" (default "go"). Also requires the following flags if `--type=ansible` or `--type=helm` 259 * `--api-version` string - CRD APIVersion in the format `$GROUP_NAME/$VERSION` (e.g app.example.com/v1alpha1) 260 * `--kind` string - CRD Kind. (e.g AppService) 261 * `--generate-playbook` - Generate a playbook skeleton. (Only used for `--type ansible`) 262 * `--helm-chart` string - Initialize helm operator with existing helm chart (`<URL>`, `<repo>/<name>`, or local path) 263 * `--helm-chart-repo` string - Chart repository URL for the requested helm chart 264 * `--helm-chart-version` string - Specific version of the helm chart (default is latest version) 265 * `--dep-manager` string - Dependency manager the new project will use (choices: "dep", "modules") (default "modules") 266 * `-h, --help` - help for new 267 268 ### Example 269 270 #### Go project 271 272 ```console 273 $ mkdir $GOPATH/src/github.com/example.com/ 274 $ cd $GOPATH/src/github.com/example.com/ 275 $ operator-sdk new app-operator 276 ``` 277 278 #### Ansible project 279 280 ```console 281 $ operator-sdk new app-operator --type=ansible --api-version=app.example.com/v1alpha1 --kind=AppService 282 ``` 283 284 #### Helm project 285 286 For more details about creating new Helm operator projects, see the [Helm user guide][helm-user-guide-create-project]. 287 288 ```console 289 $ operator-sdk new app-operator --type=helm \ 290 --api-version=app.example.com/v1alpha1 \ 291 --kind=AppService 292 293 $ operator-sdk new app-operator --type=helm \ 294 --api-version=app.example.com/v1alpha1 \ 295 --kind=AppService \ 296 --helm-chart=myrepo/app 297 298 $ operator-sdk new app-operator --type=helm \ 299 --helm-chart=myrepo/app 300 301 $ operator-sdk new app-operator --type=helm \ 302 --helm-chart=myrepo/app \ 303 --helm-chart-version=1.2.3 304 305 $ operator-sdk new app-operator --type=helm \ 306 --helm-chart=app \ 307 --helm-chart-repo=https://charts.mycompany.com/ 308 309 $ operator-sdk new app-operator --type=helm \ 310 --helm-chart=app \ 311 --helm-chart-repo=https://charts.mycompany.com/ \ 312 --helm-chart-version=1.2.3 313 314 $ operator-sdk new app-operator --type=helm \ 315 --helm-chart=/path/to/local/chart-directories/app/ 316 317 $ operator-sdk new app-operator --type=helm \ 318 --helm-chart=/path/to/local/chart-archives/app-1.2.3.tgz 319 ``` 320 321 ## add 322 323 ### api 324 325 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. 326 327 #### Flags 328 329 * `--api-version` string - CRD APIVersion in the format `$GROUP_NAME/$VERSION` (e.g app.example.com/v1alpha1) 330 * `--kind` string - CRD Kind. (e.g AppService) 331 * `--header-file` string - Path to file containing headers for generated files (optional). 332 333 #### Example 334 335 ```console 336 $ operator-sdk add api --api-version app.example.com/v1alpha1 --kind AppService 337 INFO[0000] Generating api version app.example.com/v1alpha1 for kind AppService. 338 INFO[0000] Created pkg/apis/app/v1alpha1/appservice_types.go 339 INFO[0000] Created pkg/apis/addtoscheme_app_v1alpha1.go 340 INFO[0000] Created pkg/apis/app/v1alpha1/register.go 341 INFO[0000] Created pkg/apis/app/v1alpha1/doc.go 342 INFO[0000] Created deploy/crds/app_v1alpha1_appservice_cr.yaml 343 INFO[0000] Created deploy/crds/app_v1alpha1_appservice_crd.yaml 344 INFO[0001] Running deepcopy code-generation for Custom Resource group versions: [app:[v1alpha1], ] 345 INFO[0002] Code-generation complete. 346 INFO[0002] Running OpenAPI code-generation for Custom Resource group versions: [app:[v1alpha1], ] 347 INFO[0004] Created deploy/crds/app_v1alpha1_appservice_crd.yaml 348 INFO[0004] Code-generation complete. 349 INFO[0004] API generation complete. 350 ``` 351 352 ### controller 353 354 Adds a new controller under `pkg/controller/<kind>/...` that, by default, reconciles a custom resource for the specified apiversion and kind. 355 356 #### Flags 357 358 * `--api-version` string - CRD APIVersion in the format `$GROUP_NAME/$VERSION` (e.g app.example.com/v1alpha1) 359 * `--kind` string - CRD Kind. (e.g AppService) 360 * `--custom-api-import` string - External Kubernetes resource import path of the form "host.com/repo/path[=import_identifier]". import_identifier is optional 361 362 #### Example 363 364 ```console 365 $ operator-sdk add controller --api-version app.example.com/v1alpha1 --kind AppService 366 Created pkg/controller/appservice/appservice_controller.go 367 Created pkg/controller/add_appservice.go 368 ``` 369 370 ### crd 371 372 Generates the CRD and the CR files for the specified api-version and kind. 373 374 #### Flags 375 376 * `--api-version` string - CRD APIVersion in the format `$GROUP_NAME/$VERSION` (e.g app.example.com/v1alpha1) 377 * `--kind` string - CRD Kind. (e.g AppService) 378 379 #### Example 380 381 ```console 382 $ operator-sdk add crd --api-version app.example.com/v1alpha1 --kind AppService 383 Generating custom resource definition (CRD) files 384 Created deploy/crds/app_v1alpha1_appservice_crd.yaml 385 Created deploy/crds/app_v1alpha1_appservice_cr.yaml 386 ``` 387 388 ## run 389 390 ### ansible 391 392 Runs as an ansible operator process. This is intended to be used when running 393 in a Pod inside a cluster. Developers wanting to run their operator locally 394 should use `up local` instead. 395 396 #### Flags 397 398 * `--reconcile-period` string - Default reconcile period for controllers (default 1m0s) 399 * `--watches-file` string - Path to the watches file to use (default "./watches.yaml") 400 401 #### Example 402 403 ```console 404 $ operator-sdk run ansible --watches-file=/opt/ansible/watches.yaml --reconcile-period=30s 405 ``` 406 407 ### helm 408 409 Runs as a helm operator process. This is intended to be used when running 410 in a Pod inside a cluster. Developers wanting to run their operator locally 411 should use `up local` instead. 412 413 #### Flags 414 415 * `--reconcile-period` string - Default reconcile period for controllers (default 1m0s) 416 * `--watches-file` string - Path to the watches file to use (default "./watches.yaml") 417 418 #### Example 419 420 ```console 421 $ operator-sdk run helm --watches-file=/opt/helm/watches.yaml --reconcile-period=30s 422 ``` 423 424 ## scorecard 425 426 Run scorecard tests on an operator 427 428 ### Flags 429 430 * `basic-tests` - Enable basic operator checks (default true) 431 * `cr-manifest` string - (required) Path to manifest for Custom Resource 432 * `csv-path` string - (required if `olm-tests` is set) Path to CSV being tested 433 * `global-manifest` string - Path to manifest for Global resources (e.g. CRD manifests) 434 * `init-timeout` int - Timeout for status block on CR to be created, in seconds (default 10) 435 * `kubeconfig` string - Path to kubeconfig of custom resource created in cluster 436 * `namespace` string - Namespace of custom resource created in cluster 437 * `namespaced-manifest` string - Path to manifest for namespaced resources (e.g. RBAC and Operator manifest) 438 * `olm-deployed` - Only use the CSV at `csv-path` for manifest data, except for those provided to `cr-manifest` 439 * `olm-tests` - Enable OLM integration checks (default true) 440 * `proxy-image` string - Image name for scorecard proxy (default "quay.io/operator-framework/scorecard-proxy") 441 * `proxy-pull-policy` string - Pull policy for scorecard proxy image (default "Always") 442 * `verbose` - Enable verbose logging 443 * `-h, --help` - help for scorecard 444 445 ### Example 446 447 ```console 448 $ operator-sdk scorecard --cr-manifest deploy/crds/cache_v1alpha1_memcached_cr.yaml --csv-path deploy/olm-catalog/memcached-operator/0.0.2/memcached-operator.v0.0.2.clusterserviceversion.yaml 449 Checking for existence of spec and status blocks in CR 450 Checking that operator actions are reflected in status 451 Checking that writing into CRs has an effect 452 Checking for CRD resources 453 Checking for existence CR example 454 Checking spec descriptors 455 Checking status descriptors 456 Basic Operator: 457 Spec Block Exists: 1/1 points 458 Status Block Exist: 1/1 points 459 Operator actions are reflected in status: 1/1 points 460 Writing into CRs has an effect: 1/1 points 461 OLM Integration: 462 Owned CRDs have resources listed: 1/1 points 463 CRs have at least 1 example: 0/1 points 464 Spec fields with descriptors: 1/1 points 465 Status fields with descriptors: 0/1 points 466 467 Total Score: 6/8 points 468 SUGGESTION: Add an alm-examples annotation to your CSV to pass the CRs have at least 1 example test 469 SUGGESTION: Add a status descriptor for nodes 470 ``` 471 472 ## test 473 474 ### Available Commands 475 476 #### local 477 478 Runs the tests locally 479 480 ##### Args 481 482 * `test-location` - location of e2e test files (e.g. "./test/e2e/") 483 484 ##### Flags 485 486 * `--debug` - Enable debug-level logging 487 * `--kubeconfig` string - location of kubeconfig for Kubernetes cluster (default "~/.kube/config") 488 * `--global-manifest` string - path to manifest for global resources (default "deploy/crd.yaml) 489 * `--namespaced-manifest` string - path to manifest for per-test, namespaced resources (default: combines deploy/service_account.yaml, deploy/rbac.yaml, and deploy/operator.yaml) 490 * `--namespace` string - if non-empty, single namespace to run tests in (e.g. "operator-test") (default: "") 491 * `--go-test-flags` string - Additional flags to pass to go test 492 * `--molecule-test-flags` string - Additional flags to pass to molecule test 493 * `--up-local` - enable running operator locally with go run instead of as an image in the cluster 494 * `--no-setup` - disable test resource creation 495 * `--image` string - use a different operator image from the one specified in the namespaced manifest 496 * `-h, --help` - help for local 497 498 ##### Use 499 500 The operator-sdk test command runs go tests built using the Operator SDK's test framework. 501 502 ##### Example 503 504 ```console 505 $ operator-sdk test local ./test/e2e/ 506 ok github.com/operator-framework/operator-sdk-samples/memcached-operator/test/e2e 20.410s 507 ``` 508 509 ## up 510 511 ### Available Commands 512 513 #### local - Launches the operator locally 514 515 ##### Use 516 517 The `operator-sdk up local` command launches the operator on the local machine 518 with the ability to access a Kubernetes cluster using a kubeconfig file, and 519 setting any necessary environment variables that the operator would expect to 520 find when running in a cluster. For Go-based operators, this command will 521 compile and run the operator binary. In the case of non-Go operators, it runs 522 the operator-sdk binary itself as the operator. 523 524 ##### Flags 525 526 * `--go-ldflags` string - Set Go linker options 527 * `--kubeconfig` string - The file path to Kubernetes configuration file; defaults to $HOME/.kube/config 528 * `--namespace` string - The namespace where the operator watches for changes. (default "default") 529 * `--operator-flags` string - Flags that the local operator may need. 530 * `-h, --help` - help for local 531 532 ##### Example 533 534 ```console 535 $ operator-sdk up local --kubeconfig "mycluster.kubecfg" --namespace "default" --operator-flags "--flag1 value1 --flag2=value2" 536 ``` 537 538 The below example will use the default kubeconfig, the default namespace environment var, and pass in flags for the operator. 539 To use the operator flags, your operator must know how to handle the option. Below imagine an operator that understands the `resync-interval` flag. 540 541 ```console 542 $ operator-sdk up local --operator-flags "--resync-interval 10" 543 ``` 544 545 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. 546 For this to work your operator must handle the `WATCH_NAMESPACE` environment variable. To do that you can use the [utility function][utility_link] `k8sutil.GetWatchNamespace` in your operator. 547 548 ```console 549 $ operator-sdk up local --namespace "testing" 550 ``` 551 552 ### Flags 553 554 * `-h, --help` - help for up 555 556 [utility_link]: https://github.com/operator-framework/operator-sdk/blob/89bf021063d18b6769bdc551ed08fc37027939d5/pkg/util/k8sutil/k8sutil.go#L140 557 [k8s-code-generator]: https://github.com/kubernetes/code-generator 558 [openapi-code-generator]: https://github.com/kubernetes/kube-openapi 559 [helm-user-guide-create-project]: https://github.com/operator-framework/operator-sdk/blob/master/doc/helm/user-guide.md#create-a-new-project