|
| 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 `ClusterCatalogs`, 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 | + |
| 75 | +The command requires at minimum a resource name and image reference: |
| 76 | +```bash |
| 77 | +$ kubectl operator olmv1 create catalog mycatalog myorg/mycatalogrepo:tag |
| 78 | +``` |
| 79 | + |
| 80 | +<br/> |
| 81 | +<br/> |
| 82 | + |
| 83 | +--- |
| 84 | +## olmv1 install |
| 85 | +Install resources with olmv1, currently supports `ClusterExtensions`. |
| 86 | + |
| 87 | +```bash |
| 88 | +Install a resource |
| 89 | + |
| 90 | +Usage: |
| 91 | + operator olmv1 install [command] |
| 92 | + |
| 93 | +Available Commands: |
| 94 | + extension Install an extension |
| 95 | +``` |
| 96 | +<br/> |
| 97 | + |
| 98 | +### olmv1 install extension |
| 99 | + |
| 100 | +Install a new `ClusterExtension` with the provided name. |
| 101 | + |
| 102 | +```bash |
| 103 | +Install an extension |
| 104 | + |
| 105 | +Usage: |
| 106 | + operator olmv1 install extension <extension_name> [flags] |
| 107 | + |
| 108 | +Flags: |
| 109 | + -c, --channels strings channels which would be used for getting updates, e.g, --channels "stable,dev-preview,preview" |
| 110 | + -d, --cleanup-timeout duration the amount of time to wait before cancelling cleanup after a failed creation attempt (default 1m0s) |
| 111 | + -n, --namespace string namespace to install the operator in |
| 112 | + -p, --package-name string package name of the operator to install |
| 113 | + -s, --service-account string service account name to use for the extension installation (default "default") |
| 114 | + -v, --version string version (or version range) from which to resolve bundles |
| 115 | +``` |
| 116 | + |
| 117 | +The flags allow for setting most mutable fields: |
| 118 | +- **`-n`, `--namespace`**: The namespace to install any namespace-scoped resources created by the `ClusterExtension`. <span style="color:red">**Required**</span> |
| 119 | +- **`-p`, `--package-name`**: Name of the package to install. <span style="color:red">**Required**</span> |
| 120 | +- `-c`, `--channels`: An optional list of channels within a package to restrict searches for an installable version to. |
| 121 | +- `-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) |
| 122 | +- `-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`. |
| 123 | +- `-v`, `--version`: A version or version range to restrict search for an installable version to. |
| 124 | +<br/> |
| 125 | +<br/> |
| 126 | + |
| 127 | +The command requires at minimum a resource name, `--namespace` and `--package-name`: |
| 128 | +```bash |
| 129 | +$ kubectl operator olmv1 install extension myex --namespace myns --package-name prometheus-operator |
| 130 | +``` |
| 131 | +<br/> |
| 132 | +<br/> |
| 133 | + |
| 134 | +--- |
| 135 | + |
| 136 | +## olmv1 delete |
| 137 | + |
| 138 | +Delete `olmv1` resources. |
| 139 | + |
| 140 | +```bash |
| 141 | +Delete a resource |
| 142 | + |
| 143 | +Usage: |
| 144 | + operator olmv1 delete [command] |
| 145 | + |
| 146 | +Available Commands: |
| 147 | + catalog Delete either a single or all of the existing catalogs |
| 148 | + extension Delete an extension |
| 149 | +``` |
| 150 | +<br/> |
| 151 | + |
| 152 | +### olmv1 delete catalog |
| 153 | + |
| 154 | +Delete a `ClusterCatalog` by name. Specifying the `--all` flag deletes all existing `ClusterCatalogs`, and cannot be used when a resource name is passed as an argument. |
| 155 | + |
| 156 | + |
| 157 | +```bash |
| 158 | +Delete either a single or all of the existing catalogs |
| 159 | + |
| 160 | +Usage: |
| 161 | + operator olmv1 delete catalog [catalog_name] [flags] |
| 162 | + |
| 163 | +Aliases: |
| 164 | + catalog, catalogs [catalog_name] |
| 165 | + |
| 166 | +Flags: |
| 167 | + --all delete all catalogs |
| 168 | +``` |
| 169 | + |
| 170 | +The command requires exactly one of a resource name or the `--all` flag: |
| 171 | +```bash |
| 172 | +$ kubectl operator olmv1 delete catalog mycatalog |
| 173 | +$ kubectl operator olmv1 delete catalog --all |
| 174 | +``` |
| 175 | + |
| 176 | +<br/> |
| 177 | + |
| 178 | +### olmv1 delete extension |
| 179 | + |
| 180 | +Delete a `ClusterExtension` by name. Specifying the `--all` flag deletes all existing `ClusterExtensions`, and cannot be used when a resource name is passed as an argument. |
| 181 | + |
| 182 | +```bash |
| 183 | +Usage: |
| 184 | + operator olmv1 delete extension [extension_name] [flags] |
| 185 | + |
| 186 | +Aliases: |
| 187 | + extension, extensions [extension_name] |
| 188 | + |
| 189 | +Flags: |
| 190 | + -a, --all delete all extensions |
| 191 | +``` |
| 192 | + |
| 193 | +The command requires exactly one of a resource name or the `--all` flag: |
| 194 | +```bash |
| 195 | +$ kubectl operator olmv1 delete extension myex |
| 196 | +$ kubectl operator olmv1 delete extension --all |
| 197 | +``` |
| 198 | + |
| 199 | +<br/> |
| 200 | +<br/> |
| 201 | + |
| 202 | +--- |
| 203 | + |
| 204 | +## olmv1 update |
| 205 | + |
| 206 | +Update mutable fields on `olmv1` resources. |
| 207 | + |
| 208 | +```bash |
| 209 | +Update a resource |
| 210 | + |
| 211 | +Usage: |
| 212 | + operator olmv1 update [command] |
| 213 | + |
| 214 | +Available Commands: |
| 215 | + catalog Update a catalog |
| 216 | + extension Update an extension |
| 217 | +``` |
| 218 | +<br/> |
| 219 | + |
| 220 | +### olmv1 update catalog |
| 221 | + |
| 222 | +Update supported mutable fields on a `ClusterCatalog` specified by name. |
| 223 | + |
| 224 | +```bash |
| 225 | +Update a catalog |
| 226 | + |
| 227 | +Usage: |
| 228 | + operator olmv1 update catalog <catalog_name> [flags] |
| 229 | + |
| 230 | +Flags: |
| 231 | + --availability-mode string available means that the catalog should be active and serving data |
| 232 | + --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) |
| 233 | + --image string Image reference for the catalog source. Leave unset to retain the current image. |
| 234 | + --labels stringToString labels that will be added to the catalog (default []) |
| 235 | + --priority int32 priority determines the likelihood of a catalog being selected in conflict scenarios |
| 236 | + --source-poll-interval-minutes int catalog source polling interval [in minutes]. Set to 0 or -1 to remove the polling interval. (default 5) |
| 237 | +``` |
| 238 | + |
| 239 | +The flags allow for setting most mutable fields: |
| 240 | +- `--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. |
| 241 | +- `--availablity-mode`: Sets whether the `ClusterCatalog` should be actively serving and making its contents available on cluster. Valid values: `Available`|`Unavailable`. |
| 242 | +- `--image`: Update the image reference for the `ClusterCatalog`. |
| 243 | +- `--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. |
| 244 | +- `--priority`: Integer priority used for ordering `ClusterCatalogs` in case two extension packages have the same name across `ClusterCatalogs`, with a higher value indicating greater relative priority. |
| 245 | +- `--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. |
| 246 | +<br/> |
| 247 | + |
| 248 | +To update specific fields on a catalog, like adding a new label or setting availability, the required flag may be used on its own: |
| 249 | +```bash |
| 250 | +$ kubectl operator olmv1 update catalog mycatalog --label newlabel=newkey --label labeltoremove= |
| 251 | +$ kubectl operator olmv1 update catalog --availability-mode Available |
| 252 | +``` |
| 253 | + |
| 254 | +To reset a specific field on a catalog to its default, the value needs to be provided or all existing fields must be specified with `--ignore-unset`. |
| 255 | +```bash |
| 256 | +$ kubectl operator olmv1 update catalog mycatalog --availability-mode Available |
| 257 | +$ kubectl operator olmv1 update catalog mycatalog --ignore-unset=false --priority=10 --source-poll-interval-minutes=-1 --image=myorg/mycatalogrepo:tag --labels existing1=labelvalue1 --labels existing2=labelvalue2 |
| 258 | +``` |
| 259 | + |
| 260 | +### olmv1 update extension |
| 261 | + |
| 262 | +Update supported mutable fields on a `ClusterExtension` specified by name. |
| 263 | + |
| 264 | +```bash |
| 265 | +Update an extension |
| 266 | + |
| 267 | +Usage: |
| 268 | + operator olmv1 update extension <extension> [flags] |
| 269 | + |
| 270 | +Flags: |
| 271 | + --channels stringArray desired channels for extension versions. AND operation with version. If empty or not specified, all available channels will be taken into consideration |
| 272 | + --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) |
| 273 | + --labels stringToString labels that will be set on the extension (default []) |
| 274 | + --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 |
| 275 | + --upgrade-constraint-policy string controls whether the upgrade path(s) defined in the catalog are enforced. One of CatalogProvided|SelfCertified, Default: CatalogProvided |
| 276 | + --version string desired extension version (single or range) in semVer format. AND operation with channels |
| 277 | +``` |
| 278 | + |
| 279 | +The flags allow for setting most mutable fields: |
| 280 | +- `--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. |
| 281 | +- `-v`, `--version`: A version or version range to restrict search for a version upgrade. |
| 282 | +- `-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. |
| 283 | +- `--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`. |
| 284 | +- `--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. |
| 285 | + |
| 286 | +To update specific fields on an extension, like adding a new label or updating desired version range, the required flag may be used on its own: |
| 287 | +```bash |
| 288 | +$ kubectl operator olmv1 update extension myex --label newlabel=newkey --label labeltoremove= |
| 289 | +$ kubectl operator olmv1 update extension myex --version 1.2.x |
| 290 | +``` |
| 291 | + |
| 292 | +To reset a specific field to its default on an extension, the value needs to be provided or all existing fields must be specified with `--ignore-unset`. |
| 293 | +```bash |
| 294 | +$ kubectl operator olmv1 update catalog --upgrade-constraint-policy CatalogProvided |
| 295 | +$ kubectl operator olmv1 update catalog --ignore-unset=false --version=1.0.x --channels=stable,candidate --labels existing1=labelvalue1 --labels existing2=labelvalue2 |
| 296 | +``` |
| 297 | + |
| 298 | +<br/> |
| 299 | +<br/> |
| 300 | + |
| 301 | +--- |
| 302 | + |
| 303 | +## olmv1 get |
| 304 | +Display status information of `olmv1` resources. |
| 305 | + |
| 306 | +```bash |
| 307 | +Display one or many resource(s) |
| 308 | + |
| 309 | +Usage: |
| 310 | + operator olmv1 get [command] |
| 311 | + |
| 312 | +Available Commands: |
| 313 | + catalog Display one or many installed catalogs |
| 314 | + extension Display one or many installed extensions |
| 315 | +``` |
| 316 | +<br/> |
| 317 | + |
| 318 | +### olmv1 get catalog |
| 319 | +Display status information of all `ClusterCatalogs`. |
| 320 | + |
| 321 | +```bash |
| 322 | +Display one or many installed catalogs |
| 323 | + |
| 324 | +Usage: |
| 325 | + operator olmv1 get catalog [catalog_name] [flags] |
| 326 | + |
| 327 | +Aliases: |
| 328 | + catalog, catalogs |
| 329 | +``` |
| 330 | + |
| 331 | +```bash |
| 332 | +$ kubectl operator olmv1 get catalog |
| 333 | +NAME AVAILABILITY PRIORITY LASTUNPACKED SERVING AGE |
| 334 | +operatorhubio Available 0 44m True 44m |
| 335 | +``` |
| 336 | +<br/> |
| 337 | + |
| 338 | +### olmv1 get extension |
| 339 | +Display status information of installed `ClusterExtensions`. |
| 340 | + |
| 341 | +```bash |
| 342 | +Display one or many installed extensions |
| 343 | + |
| 344 | +Usage: |
| 345 | + operator olmv1 get extension [extension_name] [flags] |
| 346 | + |
| 347 | +Aliases: |
| 348 | + extension, extensions [extension_name] |
| 349 | +``` |
| 350 | + |
| 351 | +```bash |
| 352 | +$ kubectl operator olmv1 get extension |
| 353 | +NAME INSTALLED BUNDLE VERSION SOURCE TYPE INSTALLED PROGRESSING AGE |
| 354 | +test-operator prometheusoperator.0.47.0 0.47.0 Community Operators Index True False 44m |
| 355 | +``` |
0 commit comments