Skip to content

Commit 0e20062

Browse files
adellapeadellape
authored
Merge pull request #12968 from adellape/osdk_cli
Add OSDK CLI ref guide
2 parents 6c945a0 + 4cc3280 commit 0e20062

10 files changed

+521
-0
lines changed

‎_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,8 @@ Distros: openshift-*
116116
Topics:
117117
- Name: Getting started with the Operator SDK
118118
File: osdk-getting-started
119+
- Name: Operator SDK CLI Reference
120+
File: osdk-cli-reference
119121
- Name: Migrating to Operator SDK v0.1.0
120122
File: migrating-to-osdk-v0-1-0
121123
---

‎modules/osdk-cli-reference-add.adoc

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
[id='osdk-cli-reference-add-{context}']
2+
= add
3+
4+
The `operator-sdk add` command adds a controller or resource to the project. The
5+
command must be run from the Operator project root directory.
6+
7+
.`add` subcommands
8+
[options="header",cols="1,3"]
9+
|===
10+
|Subcommand |Description
11+
12+
|`api`
13+
|Adds a new API definition for a new custom resource under `pkg/apis` and
14+
generates the customer resource definition (CRD) and custom resource (CR) files
15+
under `deploy/crds/`. If the API already exists at `pkg/apis/<group>/<version>`,
16+
then the command does not overwrite and returns an error.
17+
18+
|`controller`
19+
|Adds a new controller under `pkg/controller/<kind>/`. The controller expects to
20+
use the CR type that should already be defined under
21+
`pkg/apis/<group>/<version>` via the `operator-sdk add api --kind=<kind>
22+
--api-version=<group/version>` command. If the controller package for that
23+
`Kind` already exists at `pkg/controller/<kind>`, then the command does not
24+
overwrite and returns an error.
25+
26+
27+
|`crd`
28+
a|Adds a CRD and the CR files. The `<project-name>/deploy` path must already
29+
exist. The `--api-version` and `--kind` flags are required to generate the new
30+
Operator application.
31+
32+
* Generated CRD filename: `<project-name>/deploy/crds/<group>_<version>_<kind>_crd.yaml`
33+
* Generated CR filename: `<project-name>/deploy/crds/<group>_<version>_<kind>_cr.yaml`
34+
|===
35+
36+
.`add` flags
37+
[options="header",cols="1,3"]
38+
|===
39+
|Flag |Description
40+
41+
|`--api-version` (string)
42+
|CRD `APIVersion` in the format `$GROUP_NAME/$VERSION` (e.g.,
43+
`app.example.com/v1alpha1`).
44+
45+
|`--kind` (string)
46+
|CRD `Kind` (e.g., `AppService`).
47+
|===
48+
49+
.Example `add api` output
50+
----
51+
$ operator-sdk add api --api-version app.example.com/v1alpha1 --kind AppService
52+
Create pkg/apis/app/v1alpha1/appservice_types.go
53+
Create pkg/apis/addtoscheme_app_v1alpha1.go
54+
Create pkg/apis/app/v1alpha1/register.go
55+
Create pkg/apis/app/v1alpha1/doc.go
56+
Create deploy/crds/app_v1alpha1_appservice_cr.yaml
57+
Create deploy/crds/app_v1alpha1_appservice_crd.yaml
58+
Running code-generation for custom resource group versions: [app:v1alpha1]
59+
Generating deepcopy funcs
60+
61+
$ tree pkg/apis
62+
pkg/apis/
63+
├── addtoscheme_app_appservice.go
64+
├── apis.go
65+
└── app
66+
└── v1alpha1
67+
├── doc.go
68+
├── register.go
69+
├── types.go
70+
----
71+
72+
.Example `add controller` output
73+
----
74+
$ operator-sdk add controller --api-version app.example.com/v1alpha1 --kind AppService
75+
Create pkg/controller/appservice/appservice_controller.go
76+
Create pkg/controller/add_appservice.go
77+
78+
$ tree pkg/controller
79+
pkg/controller/
80+
├── add_appservice.go
81+
├── appservice
82+
│   └── appservice_controller.go
83+
└── controller.go
84+
----
85+
86+
.Example `add crd` output
87+
----
88+
$ operator-sdk add crd --api-version app.example.com/v1alpha1 --kind AppService
89+
Generating custom resource definition (CRD) files
90+
Create deploy/crds/app_v1alpha1_appservice_crd.yaml
91+
Create deploy/crds/app_v1alpha1_appservice_cr.yaml
92+
----

‎modules/osdk-cli-reference-build.adoc

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
[id='osdk-cli-reference-build-{context}']
2+
= build
3+
4+
The `operator-sdk build` command compiles the code and builds the executables.
5+
After `build` completes, the image is built locally in `docker`. It must then be
6+
pushed to a remote registry.
7+
8+
.`build` arguments
9+
[options="header",cols="1,3"]
10+
|===
11+
|Argument |Description
12+
13+
|`<image>`
14+
|The container image to be built, e.g., `quay.io/example/operator:v0.0.1`.
15+
|===
16+
17+
.`build` flags
18+
[options="header",cols="1,3"]
19+
|===
20+
|Flag |Description
21+
22+
|`--enable-tests` (bool)
23+
|Enable in-cluster testing by adding test binary to the image.
24+
25+
|`--namespaced-manifest` (string)
26+
|Path of namespaced resources manifest for tests. Default: `deploy/operator.yaml`.
27+
28+
|`--test-location` (string)
29+
|Location of tests. Default: `./test/e2e`
30+
31+
|`-h, --help`
32+
|Usage help output.
33+
|===
34+
35+
If `--enable-tests` is set, the `build` command also builds the testing binary,
36+
adds it to the container image, and generates a `deploy/test-pod.yaml` file that
37+
allows a user to run the tests as a Pod on a cluster.
38+
39+
.Example output
40+
----
41+
$ operator-sdk build quay.io/example/operator:v0.0.1
42+
43+
building example-operator...
44+
45+
building container quay.io/example/operator:v0.0.1...
46+
Sending build context to Docker daemon 163.9MB
47+
Step 1/4 : FROM alpine:3.6
48+
---> 77144d8c6bdc
49+
Step 2/4 : ADD tmp/_output/bin/example-operator /usr/local/bin/example-operator
50+
---> 2ada0d6ca93c
51+
Step 3/4 : RUN adduser -D example-operator
52+
---> Running in 34b4bb507c14
53+
Removing intermediate container 34b4bb507c14
54+
---> c671ec1cff03
55+
Step 4/4 : USER example-operator
56+
---> Running in bd336926317c
57+
Removing intermediate container bd336926317c
58+
---> d6b58a0fcb8c
59+
Successfully built d6b58a0fcb8c
60+
Successfully tagged quay.io/example/operator:v0.0.1
61+
----

‎modules/osdk-cli-reference-completion.adoc

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
[id='osdk-cli-reference-completion-{context}']
2+
= completion
3+
4+
The `operator-sdk completion` command generates shell completions to make
5+
issuing CLI commands quicker and easier.
6+
7+
.`completion` subcommands
8+
[options="header",cols="1,3"]
9+
|===
10+
|Subcommand |Description
11+
12+
|`bash`
13+
|Generate bash completions.
14+
15+
|`zsh`
16+
|Generate zsh completions.
17+
|===
18+
19+
.`completion` flags
20+
[options="header",cols="1,3"]
21+
|===
22+
|Flag |Description
23+
24+
|`-h, --help`
25+
|Usage help output.
26+
|===
27+
28+
.Example output
29+
----
30+
$ operator-sdk completion bash
31+
32+
# bash completion for operator-sdk -*- shell-script -*-
33+
...
34+
# ex: ts=4 sw=4 et filetype=sh
35+
----

‎modules/osdk-cli-reference-generate.adoc

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
[id='osdk-cli-reference-generate-{context}']
2+
= generate
3+
4+
The `operator-sdk generate` command invokes a specific generator to generate
5+
code as needed.
6+
7+
.`generate` subcommands
8+
[options="header",cols="1,3"]
9+
|===
10+
|Subcommand |Description
11+
12+
|`k8s`
13+
|Runs the Kubernetes
14+
link:https://github.com/kubernetes/code-generator[code-generators] for all CRD
15+
APIs under `pkg/apis/`. Currently, `k8s` only runs `deepcopy-gen` to generate
16+
the required `DeepCopy()` functions for all custom resource types.
17+
|===
18+
19+
[NOTE]
20+
====
21+
This command must be run every time the API (`spec` and `status`) for a custom
22+
resource type is updated.
23+
====
24+
25+
.Example output
26+
----
27+
$ tree pkg/apis/app/v1alpha1/
28+
pkg/apis/app/v1alpha1/
29+
├── appservice_types.go
30+
├── doc.go
31+
├── register.go
32+
33+
$ operator-sdk generate k8s
34+
Running code-generation for custom resource group versions: [app:v1alpha1]
35+
Generating deepcopy funcs
36+
37+
$ tree pkg/apis/app/v1alpha1/
38+
pkg/apis/app/v1alpha1/
39+
├── appservice_types.go
40+
├── doc.go
41+
├── register.go
42+
└── zz_generated.deepcopy.go
43+
----

‎modules/osdk-cli-reference-new.adoc

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
[id='osdk-cli-reference-new-{context}']
2+
= new
3+
4+
The `operator-sdk new` command creates a new Operator application and generates
5+
(or _scaffolds_) a default project directory layout based on the input
6+
`<project_name>`.
7+
8+
.`new` arguments
9+
[options="header",cols="1,3"]
10+
|===
11+
|Argument |Description
12+
13+
|`<project_name>`
14+
|Name of the new project.
15+
|===
16+
17+
.`new` flags
18+
[options="header",cols="1,3"]
19+
|===
20+
|Flag |Description
21+
22+
| `--skip-git-init`
23+
|Do not initialize the directory as a Git repository.
24+
25+
|`--type`
26+
a|Type of Operator to initialize: `ansible` or `go` (default: `go`). Also requires the following flags if `--type=ansible`:
27+
28+
* `--api-version`: CRD `APIVersion` in the format `$GROUP_NAME/$VERSION` (e.g., `app.example.com/v1alpha1`)
29+
* `--kind`: CRD `Kind` (e.g., `AppService`).
30+
31+
|`--cluster-scoped`
32+
|Initialize the Operator to be cluster-scoped instead of namespace-scoped.
33+
34+
|`-h, --help`
35+
|Usage help output.
36+
|===
37+
38+
.Example usage for Go project
39+
----
40+
$ mkdir $GOPATH/src/github.com/example.com/
41+
$ cd $GOPATH/src/github.com/example.com/
42+
$ operator-sdk new app-operator
43+
----
44+
45+
.Example usage for Ansible project
46+
----
47+
$ operator-sdk new app-operator \
48+
--type=ansible \
49+
--api-version=app.example.com/v1alpha1 \
50+
--kind=AppService
51+
----

‎modules/osdk-cli-reference-print-deps.adoc

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
[id='osdk-cli-reference-print-deps-{context}']
2+
= print-deps
3+
4+
The `operator-sdk print-deps` command prints the most recent Golang packages and
5+
versions required by Operators. It prints in columnar format by default.
6+
7+
.`print-deps` flags
8+
[options="header",cols="1,3"]
9+
|===
10+
|Flag |Description
11+
12+
|`--as-file`
13+
|Print packages and versions in `Gopkg.toml` format.
14+
|===
15+
16+
.Example output
17+
----
18+
$ operator-sdk print-deps --as-file
19+
required = [
20+
"k8s.io/code-generator/cmd/defaulter-gen",
21+
"k8s.io/code-generator/cmd/deepcopy-gen",
22+
"k8s.io/code-generator/cmd/conversion-gen",
23+
"k8s.io/code-generator/cmd/client-gen",
24+
"k8s.io/code-generator/cmd/lister-gen",
25+
"k8s.io/code-generator/cmd/informer-gen",
26+
"k8s.io/code-generator/cmd/openapi-gen",
27+
"k8s.io/gengo/args",
28+
]
29+
30+
[[override]]
31+
name = "k8s.io/code-generator"
32+
revision = "6702109cc68eb6fe6350b83e14407c8d7309fd1a"
33+
...
34+
----

0 commit comments

Comments
 (0)