Skip to content

Commit bcbb0a3

Browse files
ankitathomasankitathomas
committed
olmv1 readme
Signed-off-by: Ankita Thomas <ankithom@redhat.com>
1 parent 75ba494 commit bcbb0a3

File tree

1 file changed

+302
-0
lines changed

1 file changed

+302
-0
lines changed

‎olmv1.md‎

Lines changed: 302 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,302 @@
1+
# Kubectl Operator OLMv1 Commands
2+
3+
Most of the kubectl operator plugin subcommands are aimed toward managing OLMv0 operators.
4+
5+
[OLMv1](https://github.com/operator-framework/operator-controller/) has two main on-cluster CRDs, both of which can be managed by the kubectl operator `olmv1` subcommand. These are:
6+
- [`ClusterCatalogs`](https://github.com/operator-framework/operator-controller/blob/main/api/v1/clustercatalog_types.go): A CR used to provide a curated collection of packages for users to install and upgrade from, backed by an image reference to a File Based Catalog (FBC)
7+
- [`ClusterExtensions`](https://github.com/operator-framework/operator-controller/blob/main/api/v1/clusterextension_types.go): A CR expressing the current status and desired state of a package on cluster. It must provide the package name to be installed from available `ClusterCatalogs`, but may also specify restrictions on install and upgrade discovery.
8+
9+
Within the repository, these are defined in `internal/cmd/olmv1.go`, which in turn references `internal/cmd/internal/olmv1` and `internal/pkg/v1`.
10+
11+
```bash
12+
$ kubectl operator olmv1 --help
13+
14+
Manage extensions via `olmv1` in a cluster from the command line.
15+
16+
Usage:
17+
operator olmv1 [command]
18+
19+
Available Commands:
20+
create Create a resource
21+
delete Delete a resource
22+
get Display one or many resource(s)
23+
install Install a resource
24+
update Update a resource
25+
```
26+
27+
Of the global flags, only `--help` is relevant to `olmv1` and its subcommands. The `olmv1` subcommands are detailed as follows.
28+
29+
<br/>
30+
<br/>
31+
32+
---
33+
34+
## `olmv1 create`
35+
Create `olmv1` resources, currently supports only `ClusterCatalogs`.
36+
37+
```bash
38+
Create a resource
39+
40+
Usage:
41+
operator olmv1 create [command]
42+
43+
Available Commands:
44+
catalog Create a new catalog
45+
```
46+
<br/>
47+
48+
### `olmv1 create catalog`
49+
Create a new `ClusterCatalog` with the provided name and catalog image reference.
50+
51+
```bash
52+
Create a new catalog
53+
54+
Usage:
55+
operator olmv1 create catalog <catalog_name> <image_source_ref> [flags]
56+
57+
Aliases:
58+
catalog, catalogs <catalog_name> <image_source_ref>
59+
60+
Flags:
61+
--available true means that the catalog should be active and serving data (default true)
62+
--cleanup-timeout duration the amount of time to wait before cancelling cleanup after a failed creation attempt (default 1m0s)
63+
--labels stringToString labels that will be added to the catalog (default [])
64+
--priority int32 priority determines the likelihood of a catalog being selected in conflict scenarios
65+
--source-poll-interval-minutes int catalog source polling interval [in minutes] (default 10)
66+
```
67+
68+
The flags allow for setting most mutable fields:
69+
- `--available`: Sets whether the `ClusterCatalog` should be actively serving and make its contents available on cluster. Default: true.
70+
- `--cleanup-timeout`: If a `ClusterCatalog` creation attempt fails due to the resource never becoming healthy, `olmv1` cleans up by deleting the failed resource, with a timeout specified by `--cleanup-timeout`. Default: 1 minute (1m)
71+
- `--labels`: Additional labels to add to the newly created `ClusterCatalog` as `key=value` pairs. This flag may be specified multiple times.
72+
- `--priority`: Integer priority used for ordering `ClusterCatalogs` in case two extension packages have the same name across catalogs, with a higher value indicating greater relative priority. Default: 0
73+
- `--source-poll-interval-minutes`: The polling interval to check for changes if the `ClusterCatalog` source image provided is not a digest based image, i.e, if it is referenced by tag. Set to 0 to disable polling. Default: 10
74+
<br/>
75+
<br/>
76+
---
77+
## olmv1 install
78+
Install resources with olmv1, currently supports `ClusterExtensions`.
79+
80+
```bash
81+
Install a resource
82+
83+
Usage:
84+
operator olmv1 install [command]
85+
86+
Available Commands:
87+
extension Install an extension
88+
```
89+
<br/>
90+
91+
### olmv1 install extension
92+
93+
Install a new `ClusterExtension` with the provided namez.
94+
95+
```bash
96+
Install an extension
97+
98+
Usage:
99+
operator olmv1 install extension <extension_name> [flags]
100+
101+
Flags:
102+
-c, --channels strings channels which would be used for getting updates, e.g, --channels "stable,dev-preview,preview"
103+
-d, --cleanup-timeout duration the amount of time to wait before cancelling cleanup after a failed creation attempt (default 1m0s)
104+
-n, --namespace string namespace to install the operator in
105+
-p, --package-name string package name of the operator to install
106+
-s, --service-account string service account name to use for the extension installation (default "default")
107+
-v, --version string version (or version range) from which to resolve bundles
108+
```
109+
110+
The flags allow for setting most mutable fields:
111+
- `-c`, `--channels`: An optional list of channels within a package to restrict searches for an installable version to.
112+
- `-d`, `--cleanup-timeout`: If a `ClusterExtension` creation attempt fails due to the resource never becoming healthy, `olmv1` cleans up by deleting the failed resource, with a timeout specified by `--cleanup-timeout`. Default: 1 minute (1m)
113+
- `-n`, `--namespace`: The namespace to install any namespace-scoped resources created by the `ClusterExtension`. *Required*
114+
- `-p`, `--package-name`: Name of the package to install. *Required*
115+
- `-s`, `--service-account`: Name of the service account present in the namespace specified by `--namespace` to use for creating and managing resources for the new `ClusterExtension`.
116+
- `-v`, `--version`: A version or version range to restrict search for an installable version to.
117+
<br/>
118+
<br/>
119+
---
120+
121+
## olmv1 delete
122+
123+
Delete `olmv1` resources.
124+
125+
```bash
126+
Delete a resource
127+
128+
Usage:
129+
operator olmv1 delete [command]
130+
131+
Available Commands:
132+
catalog Delete either a single or all of the existing catalogs
133+
extension Delete an extension
134+
```
135+
<br/>
136+
137+
### olmv1 delete catalog
138+
139+
Delete a `ClusterCatalog` by name. Specifying `--all` flag allows for cleaning up all existing `ClusterCatalogs`, and cannot be used when a resource name is passed as an argument.
140+
141+
142+
```bash
143+
Delete either a single or all of the existing catalogs
144+
145+
Usage:
146+
operator olmv1 delete catalog [catalog_name] [flags]
147+
148+
Aliases:
149+
catalog, catalogs [catalog_name]
150+
151+
Flags:
152+
--all delete all catalogs
153+
```
154+
<br/>
155+
156+
### olmv1 delete extension
157+
158+
Delete a `ClusterExtension` by name. Specifying `--all` flag allows for cleaning up all existing `ClusterExtensions`, and cannot be used when a resource name is passed as an argument.
159+
160+
```bash
161+
Usage:
162+
operator olmv1 delete extension [extension_name] [flags]
163+
164+
Aliases:
165+
extension, extensions [extension_name]
166+
167+
Flags:
168+
-a, --all delete all extensions
169+
```
170+
<br/>
171+
<br/>
172+
173+
---
174+
175+
## olmv1 update
176+
177+
Update mutable fields on `olmv1` resources.
178+
179+
```bash
180+
Update a resource
181+
182+
Usage:
183+
operator olmv1 update [command]
184+
185+
Available Commands:
186+
catalog Update a catalog
187+
extension Update an extension
188+
```
189+
<br/>
190+
191+
### olmv1 update catalog
192+
193+
Update supported mutable fields on a `ClusterCatalog` specified by name.
194+
195+
```bash
196+
Update a catalog
197+
198+
Usage:
199+
operator olmv1 update catalog <catalog_name> [flags]
200+
201+
Flags:
202+
--availability-mode string available means that the catalog should be active and serving data
203+
--ignore-unset when enabled, any unset flag value will not be changed. Disabling this flag replaces all other unset or empty values with a default value, overwriting any values on the existing CR (default true)
204+
--image string Image reference for the catalog source. Leave unset to retain the current image.
205+
--labels stringToString labels that will be added to the catalog (default [])
206+
--priority int32 priority determines the likelihood of a catalog being selected in conflict scenarios
207+
--source-poll-interval-minutes int catalog source polling interval [in minutes]. Set to 0 or -1 to remove the polling interval. (default 5)
208+
```
209+
210+
The flags allow for setting most mutable fields:
211+
- `--ignore-unset`: Sets the behavior of unspecified or empty flags, whether they should be ignored, preserving the current value on the resource, or treated as valid and used to set the field values to their default value.
212+
- `--availablity-mode`: Sets whether the `ClusterCatalog` should be actively serving and make its contents available on cluster. Valid values: `Available`|`Unavailable`.
213+
- `--image`: Update the image reference for the `ClusterCatalog`.
214+
- `--labels`: Additional labels to add to the `ClusterCatalog` as `key=value` pairs. This flag may be specified multiple times. Setting the value of a label to an empty string deletes the label from the resource.
215+
- `--priority`: Integer priority used for ordering `ClusterCatalogs` in case two extension packages have the same name across catalogs, with a higher value indicating greater relative priority.
216+
- `--source-poll-interval-minutes`: The polling interval to check for changes if the `ClusterCatalog` source image provided is not a digest based image, i.e, if it is referenced by tag. Set to 0 or -1 to disable polling.
217+
<br/>
218+
219+
### olmv1 update extension
220+
221+
Update supported mutable fields on a `ClusterExtension` specified by name.
222+
223+
```bash
224+
Update an extension
225+
226+
Usage:
227+
operator olmv1 update extension <extension> [flags]
228+
229+
Flags:
230+
--channels stringArray desired channels for extension versions. AND operation with version. If empty or not specified, all available channels will be taken into consideration
231+
--ignore-unset when enabled, any unset flag value will not be changed. Disabling this flag replaces all other unset or empty values with a default value, overwriting any values on the existing CR (default true)
232+
--labels stringToString labels that will be set on the extension (default [])
233+
--selector string filters the set of catalogs used in the bundle selection process. Empty means that all catalogs will be used in the bundle selection process
234+
--upgrade-constraint-policy string controls whether the upgrade path(s) defined in the catalog are enforced. One of CatalogProvided|SelfCertified, Default: CatalogProvided
235+
--version string desired extension version (single or range) in semVer format. AND operation with channels
236+
```
237+
238+
The flags allow for setting most mutable fields:
239+
- `--ignore-unset`: Sets the behavior of unspecified or empty flags, whether they should be ignored, preserving the current value on the resource, or treated as valid and used to set the field values to their default value.
240+
- `-v`, `--version`: A version or version range to restrict search for a version upgrade.
241+
- `-c`, `--channels`: An optional list of channels within a package to restrict searches for updates. If empty or unspecified, no channel restrictions apply while searching for valid package versions for extension updates.
242+
- `--upgrade-constraint-policy`: Specifies upgrade selection behavior. Valid values: `CatalogProvided|SelfCertified`. `SelfCertified` can be used to override upgrade graphs within a catalog and upgrade to any version at the risk of using non-standard upgrade paths. `CatalogProvided` restricts upgrades to standard paths between versions explicitly allowed within the `ClusterCatalog`.
243+
- `--labels`: Additional labels to add to the `ClusterExtension` as `key=value` pairs. This flag may be specified multiple times. Setting the value of a label to an empty string deletes the label from the resource.
244+
245+
<br/>
246+
<br/>
247+
248+
---
249+
250+
## olmv1 get
251+
Display status information of `olmv1` resources.
252+
253+
```bash
254+
Display one or many resource(s)
255+
256+
Usage:
257+
operator olmv1 get [command]
258+
259+
Available Commands:
260+
catalog Display one or many installed catalogs
261+
extension Display one or many installed extensions
262+
```
263+
<br/>
264+
265+
### olmv1 get catalog
266+
Display status information of all `ClusterCatalogs`.
267+
268+
```bash
269+
Display one or many installed catalogs
270+
271+
Usage:
272+
operator olmv1 get catalog [catalog_name] [flags]
273+
274+
Aliases:
275+
catalog, catalogs
276+
```
277+
278+
```bash
279+
$ kubectl operator olmv1 get catalog
280+
NAME AVAILABILITY PRIORITY LASTUNPACKED SERVING AGE
281+
operatorhubio Available 0 44m True 44m
282+
```
283+
<br/>
284+
285+
### olmv1 get extension
286+
Display status information of installed `ClusterExtensions`.
287+
288+
```bash
289+
Display one or many installed extensions
290+
291+
Usage:
292+
operator olmv1 get extension [extension_name] [flags]
293+
294+
Aliases:
295+
extension, extensions [extension_name]
296+
```
297+
298+
```bash
299+
$ kubectl operator olmv1 get extension
300+
NAME INSTALLED BUNDLE VERSION SOURCE TYPE INSTALLED PROGRESSING AGE
301+
test-operator prometheusoperator.0.47.0 0.47.0 Community Operators Index True False 44m
302+
```

0 commit comments

Comments
 (0)