diff --git a/.claude/commands/README.md b/.claude/commands/README.md new file mode 100644 index 0000000..7b36069 --- /dev/null +++ b/.claude/commands/README.md @@ -0,0 +1,125 @@ +# kubectl-operator Claude Code Slash Commands + +This directory contains slash commands that give Claude Code awareness of the kubectl-operator plugin. + +## Available Commands + +### `/operator` +**General help with kubectl operator plugin** + +Use this for general questions about kubectl operator commands, workflows, and best practices. + +**Example usage:** +``` +/operator +How do I install the prometheus operator? +``` + +``` +/operator +What's the difference between OLMv0 and OLMv1 commands? +``` + +### `/operator-install` +**Install a Kubernetes operator** + +Focused helper for installing operators using `kubectl operator olmv1 install extension`. + +**Example usage:** +``` +/operator-install +I want to install the prometheus operator +``` + +``` +/operator-install +Install cert-manager in the cert-manager namespace +``` + +### `/operator-catalog` +**Manage operator catalogs** + +Helper for creating, listing, updating, and deleting ClusterCatalogs. + +**Example usage:** +``` +/operator-catalog +Create a catalog from quay.io/operatorhubio/catalog:latest +``` + +``` +/operator-catalog +How do I check if my catalog is serving? +``` + +### `/operator-debug` +**Troubleshoot kubectl operator issues** + +Debug helper that matches error messages to documented scenarios and provides fixes. + +**Example usage:** +``` +/operator-debug +I got error: "no bundles found for package prometheus-operator" +``` + +``` +/operator-debug +My extension shows INSTALLED: False. How do I debug? +``` + +## How These Work + +Each slash command is a Markdown file that: +1. Loads context about kubectl-operator +2. References `olmv1.md` for accurate, up-to-date documentation +3. Follows documented workflows and error scenarios +4. Provides step-by-step guidance with verification + +## Knowledge Base + +All commands reference `olmv1.md` which contains: +- Complete command syntax and flags +- Prerequisites for each operation +- Success verification steps +- Common error scenarios and fixes +- Recommended workflows +- Example outputs (YAML, JSON, table formats) + +## Customization + +You can edit any of these `.md` files to customize the behavior. The format is: + +```markdown +--- +description: Short description for the command list +--- + +Instructions for Claude Code... +``` + +## Adding New Commands + +Create a new `.md` file in this directory with your command name: + +```bash +.claude/commands/my-command.md +``` + +Then use it in Claude Code: +``` +/my-command +``` + +## No MCP Server Required + +These slash commands work without an MCP server - they're just Markdown files that expand into prompts. This makes them: +- Easy to version control +- Simple to edit +- Fast to load +- No dependencies to manage + +## Documentation + +For more on Claude Code slash commands, see: +https://docs.claude.com/en/docs/claude-code/custom-commands diff --git a/.claude/commands/operator-catalog.md b/.claude/commands/operator-catalog.md new file mode 100644 index 0000000..aa7d3f7 --- /dev/null +++ b/.claude/commands/operator-catalog.md @@ -0,0 +1,40 @@ +--- +description: Manage operator catalogs using kubectl operator olmv1 +--- + +Help the user manage ClusterCatalogs using kubectl operator olmv1 catalog commands. + +## Instructions + +1. **Read the create catalog section from olmv1.md** (around line 61-258) +2. **Follow the catalog workflow** from "Recommended Workflows" (around line 1240-1258) +3. **Ask the user what they want to do**: + - Create a new catalog + - List existing catalogs + - Update a catalog + - Delete a catalog + - Search a catalog for packages + +4. **For catalog creation, provide the complete workflow**: + ```bash + # Step 1: Verify catalog doesn't exist + kubectl operator olmv1 get catalog + + # Step 2: Create catalog + kubectl operator olmv1 create catalog + + # Step 3: Poll for serving status + kubectl operator olmv1 get catalog + + # Step 4: Verify packages available + kubectl operator olmv1 search catalog --catalog + ``` + +5. **Include**: + - Prerequisites (image accessibility, valid FBC) + - Expected success message: `catalog "" created` + - Polling guidance (wait for SERVING: True) + - How to check conditions with yq if catalog fails to serve + - Common errors and fixes from the docs + +Now help the user with their catalog operation. diff --git a/.claude/commands/operator-debug.md b/.claude/commands/operator-debug.md new file mode 100644 index 0000000..90c61c1 --- /dev/null +++ b/.claude/commands/operator-debug.md @@ -0,0 +1,52 @@ +--- +description: Troubleshoot kubectl operator issues +--- + +Help the user debug and troubleshoot kubectl operator issues. + +## Instructions + +1. **Read olmv1.md** to understand all documented error scenarios +2. **Ask the user to provide**: + - The command they ran + - The error message they received + - Output of relevant `get` commands + +3. **Follow this diagnostic process**: + + **For extension installation failures**: + ```bash + # Check extension status + kubectl operator olmv1 get extension + + # Check detailed conditions + kubectl operator olmv1 get extension -o yaml | yq eval '.status.conditions' + + # Check catalogs are serving + kubectl operator olmv1 get catalog + + # Search for the package + kubectl operator olmv1 search catalog --package + ``` + + **For catalog creation failures**: + ```bash + # Check catalog status + kubectl operator olmv1 get catalog + + # Check detailed conditions + kubectl operator olmv1 get catalog -o yaml | yq eval '.status.conditions[] | select(.type=="Progressing")' + ``` + +4. **Match error messages to documented scenarios**: + - Read the "Common errors" sections in olmv1.md + - For install extension errors: see lines ~380-420 + - For create catalog errors: see lines ~237-255 + +5. **Provide**: + - Root cause analysis + - Specific fix from the documentation + - Verification commands + - Prevention tips + +Now help the user debug their issue. diff --git a/.claude/commands/operator-install.md b/.claude/commands/operator-install.md new file mode 100644 index 0000000..32e07b3 --- /dev/null +++ b/.claude/commands/operator-install.md @@ -0,0 +1,38 @@ +--- +description: Install a Kubernetes operator using kubectl operator olmv1 +--- + +Help the user install a Kubernetes operator using the kubectl operator olmv1 install extension command. + +## Instructions + +1. **Read the install extension section from olmv1.md** (around line 274-420) +2. **Follow the documented workflow** from the "Recommended Workflows" section (around line 1260-1287) +3. **Ask the user for required information if not provided**: + - Package name (use search if they don't know it) + - Namespace to install into + - ServiceAccount name (default: "default") + +4. **Provide the complete workflow**: + ```bash + # Step 1: Search for the package + kubectl operator olmv1 search catalog --package + + # Step 2: Verify catalogs are serving + kubectl operator olmv1 get catalog + + # Step 3: Install the extension + kubectl operator olmv1 install extension -n -p + + # Step 4: Verify installation + kubectl operator olmv1 get extension + ``` + +5. **Include**: + - Prerequisites from the docs + - Expected outputs at each step + - How to verify success (INSTALLED: True) + - Common errors and how to fix them + - Polling guidance (wait for INSTALLED: True) + +Now help the user install their operator. diff --git a/.claude/commands/operator.md b/.claude/commands/operator.md new file mode 100644 index 0000000..5ec7ed6 --- /dev/null +++ b/.claude/commands/operator.md @@ -0,0 +1,69 @@ +--- +description: Help with kubectl operator plugin commands and workflows +--- + +You are an expert assistant for the kubectl-operator plugin, which manages Kubernetes operators via OLM (Operator Lifecycle Manager). + +## Your Knowledge Base + +You have access to comprehensive documentation in `olmv1.md` which covers all olmv1 commands. When the user asks about kubectl operator commands: + +1. **Always read olmv1.md first** to get accurate, up-to-date command syntax and examples +2. **Use the documented workflows** in the "Recommended Workflows" section +3. **Reference specific error scenarios** from the documentation when troubleshooting + +## Initial setup +Before helping the user, ensure that the `kubectl-operator` plugin is installed and has the `olmv1` subcommand. This can be verified by running `kubectl operator olmv1`, which should not fail. +If this fails with an `unknown command` error, ensure that kubectl-operator is installed correctly following the steps in the `Installing from source` section on the `README.md` at the root level of the `kubectl-operator` repository. + +## Available Commands + +The kubectl operator plugin has two main command sets: + +### OLMv0 Commands (Legacy) +- `kubectl operator install ` - Install an operator (OLMv0) +- `kubectl operator uninstall ` - Uninstall an operator +- `kubectl operator list` - List installed operators +- `kubectl operator list-available` - List available operators +- `kubectl operator catalog add/remove/list` - Manage catalogs + +### OLMv1 Commands (Modern) +Read `olmv1.md` for complete documentation. Main commands: +- `kubectl operator olmv1 create catalog` - Create a ClusterCatalog +- `kubectl operator olmv1 install extension` - Install a ClusterExtension +- `kubectl operator olmv1 delete catalog|extension` - Delete resources +- `kubectl operator olmv1 update catalog|extension` - Update resources +- `kubectl operator olmv1 get catalog|extension` - View resources +- `kubectl operator olmv1 search catalog` - Search for packages + +## How to Help + +1. **For command help**: Read `olmv1.md` and provide the exact syntax with examples +2. **For workflows**: Use the "Recommended Workflows" section from `olmv1.md` +3. **For errors**: Match error messages to the "Common errors" sections and provide the documented fixes +4. **For installation**: Follow the complete workflow: search → verify catalogs → install → verify +5. **For catalog creation**: Include prerequisites, success verification, and polling guidance + +## Important Guidelines + +- **Always verify prerequisites** before suggesting commands +- **Provide expected outputs** so the user knows what success looks like +- **Include verification commands** after operations +- **Reference specific line numbers** from olmv1.md when citing documentation +- **Use the documented error scenarios** for troubleshooting +- **Follow the workflows** in olmv1.md for multi-step operations + +## Example Interaction Pattern + +User: "How do I install the prometheus operator?" + +Your response should: +1. Read `olmv1.md` to get current install extension syntax +2. Provide the complete workflow: + - Search for the package first + - Verify catalogs are serving + - Show the install command with all required flags + - Explain how to verify installation + - Include common errors and fixes + +Now, how can I help you with kubectl operator? diff --git a/README.md b/README.md index 902e023..c30367a 100644 --- a/README.md +++ b/README.md @@ -19,3 +19,49 @@ The `kubectl operator` plugin is distributed via [`krew`](https://krew.sigs.k8s. ```console kubectl krew install operator ``` + +# Installing from source + +Prerequisites: +- [go 1.23.4+](https://go.dev/dl/) +- `GOPATH` environment variable must be set. + +To build the latest version from the repository, run `make install`. This should install the kubectl-operator plugin to the `$GOPATH`/bin directory. + +To enable `kubectl` to discover the plugin, ensure that the '$GOPATH'/bin directory is either part of the '$PATH' environment variable, or that the newly installed `kubectl-operator` is moved to a directory in the `$PATH`. + +You should see that the plugin has successfully installed: +```bash +$ kubectl operator + +Manage operators in a cluster from the command line. + +kubectl operator helps you manage operator installations in your +cluster. It can install and uninstall operator catalogs, list +operators available for installation, and install and uninstall +operators from the installed catalogs. + +Usage: + operator [command] + +Available Commands: + catalog Manage operator catalogs + completion Generate the autocompletion script for the specified shell + describe Describe an operator + help Help about any command + install Install an operator + list List installed operators + list-available List operators available to be installed + list-operands List operands of an installed operator + olmv1 Manage OLMv1 extensions and catalogs + uninstall Uninstall an operator and operands + upgrade Upgrade an operator + version Print version information + +Flags: + -h, --help help for operator + -n, --namespace string If present, namespace scope for this CLI request + --timeout duration The amount of time to wait before giving up on an operation. (default 1m0s) + +Use "operator [command] --help" for more information about a command. +``` diff --git a/olmv1.md b/olmv1.md index 6b1422e..957a1b8 100644 --- a/olmv1.md +++ b/olmv1.md @@ -1,3 +1,15 @@ +# Quick Reference + - [create catalog](#olmv1-create-catalog) - Create a new ClusterCatalog + - [install extension](#olmv1-install-extension) - Install a ClusterExtension + - [delete catalog](#olmv1-delete-catalog) - Delete ClusterCatalog(s) + - [delete extension](#olmv1-delete-extension) - Delete ClusterExtension(s) + - [update catalog](#olmv1-update-catalog) - Update ClusterCatalog fields + - [update extension](#olmv1-update-extension) - Update ClusterExtension fields + - [get catalog](#olmv1-get-catalog) - List/view ClusterCatalogs + - [get extension](#olmv1-get-extension) - List/view ClusterExtensions + - [search catalog](#olmv1-search-catalog) - Search for packages + - [workflows](#recommended-workflows) - Recommended workflows for common tasks + # Kubectl Operator OLMv1 Commands Most of the kubectl operator plugin subcommands are aimed toward managing OLMv0 operators. @@ -70,6 +82,11 @@ Flags: The flags allow for setting most mutable fields: - `--available`: Sets whether the `ClusterCatalog` should be actively serving and make its contents available on cluster. Default: true. + Valid values: + - `--available=true` or `--available` (flag alone): Catalog will serve content + - `--available=false`: Catalog created but won't serve (useful for pre-staging) + Note: The flag defaults to true, so omitting it creates a serving catalog. + - `--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) - `--labels`: Additional labels to add to the newly created `ClusterCatalog` as `key=value` pairs. This flag may be specified multiple times. - `--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 @@ -78,10 +95,164 @@ The flags allow for setting most mutable fields: - `--output`: The format for displaying manifests if `--dry-run` is specified. The command requires at minimum a resource name and image reference. + +Minimal command example: ```bash $ kubectl operator olmv1 create catalog mycatalog myorg/mycatalogrepo:tag ``` +A full example with optional flags may look like: +```bash +$ kubectl operator olmv1 create catalog mycatalog myorg/mycatalogrepo:tag --labels foo=bar --available=false --priority 100 --source-poll-interval-minutes 5 --cleanup-timeout 5m +catalog "mycatalog" created +``` +The example creates a catalog without enabling it on the cluster. The successful creation can be verified as follows: +```bash +$ kubectl operator olmv1 get catalog mycatalog +NAME AVAILABILITY PRIORITY LASTUNPACKED SERVING AGE +mycatalog Unavailable 100 False 19s +``` +The catalog is present but Unavailable and not serving, as expected from the `--available=false` flag passed to the example. + +With `--dry-run`, the ClusterCatalog will be displayed but not applied. Without an accompanying `--output` flag, `--dry-run` only verifies whether the apply may succeed. + +A failed dry-run: +```bash +$ kubectl operator olmv1 create catalog mycatalog myorg/mycatalogrepo:tag --dry-run=All +failed to create catalog "mycatalog": clustercatalogs.olm.operatorframework.io "mycatalog" already exists +``` + +A successful dry-run: +```bash +$ kubectl operator olmv1 create catalog mycatalog1 myorg/mycatalogrepo:tag --dry-run=All +catalog "mycatalog1" created (dry run) +``` + +When passing the `--output` flag to a `--dry-run` command, the manifest to be applied is returned, which allows the object to be verified, or even piped through tools like `yq` or `jq` to make modifications to the manifest before applying it to the cluster. + +```bash +$ kubectl operator olmv1 create catalog mycatalog1 myorg/mycatalogrepo:tag --dry-run=All -o yaml +apiVersion: olm.operatorframework.io/v1 +kind: ClusterCatalog +metadata: + creationTimestamp: "2025-11-14T12:48:43Z" + generation: 1 + labels: + olm.operatorframework.io/metadata.name: mycatalog1 + managedFields: + - apiVersion: olm.operatorframework.io/v1 + fieldsType: FieldsV1 + fieldsV1: + f:spec: + .: {} + f:availabilityMode: {} + f:priority: {} + f:source: + .: {} + f:image: + .: {} + f:pollIntervalMinutes: {} + f:ref: {} + f:type: {} + manager: kubectl-operator + operation: Update + time: "2025-11-14T12:48:43Z" + name: mycatalog1 + uid: 31278405-b6d0-4555-b9b1-15aa23c649c8 +spec: + availabilityMode: Available + priority: 0 + source: + image: + pollIntervalMinutes: 10 + ref: myorg/mycatalogrepo:tag + type: Image +status: {} +``` + +```bash +$ kubectl operator olmv1 create catalog mycatalog1 myorg/mycatalogrepo:tag --dry-run=All -o json +{ + "kind": "ClusterCatalog", + "apiVersion": "olm.operatorframework.io/v1", + "metadata": { + "name": "mycatalog1", + "uid": "89919d7e-226f-43e2-88f9-91fff3936823", + "generation": 1, + "creationTimestamp": "2025-11-14T12:48:46Z", + "labels": { + "olm.operatorframework.io/metadata.name": "mycatalog1" + }, + "managedFields": [ + { + "manager": "kubectl-operator", + "operation": "Update", + "apiVersion": "olm.operatorframework.io/v1", + "time": "2025-11-14T12:48:46Z", + "fieldsType": "FieldsV1", + "fieldsV1": { + "f:spec": { + ".": {}, + "f:availabilityMode": {}, + "f:priority": {}, + "f:source": { + ".": {}, + "f:image": { + ".": {}, + "f:pollIntervalMinutes": {}, + "f:ref": {} + }, + "f:type": {} + } + } + } + } + ] + }, + "spec": { + "source": { + "type": "Image", + "image": { + "ref": "myorg/mycatalogrepo:tag", + "pollIntervalMinutes": 10 + } + }, + "priority": 0, + "availabilityMode": "Available" + }, + "status": {} +} +``` + +Prerequisites +Before creating a catalog, ensure: +1. Catalog image is accessible + - Image must be pullable from the cluster + - Verify: `docker pull ` or `podman pull ` works +2. Catalog image contains valid File-Based Catalog (FBC) + - Image must contain a valid FBC structure + - Invalid catalogs will be created but never become healthy/serving + - Verify: if `opm` is installed, the catalog may be verified by `opm render >/dev/null` + +Common errors: +- A ClusterCatalog with the given name already exists +```bash +$ kubectl operator olmv1 create catalog mycatalog myorg/mycatalogrepo:tag +failed to create catalog "mycatalog": clustercatalogs.olm.operatorframework.io "mycatalog" already exists +``` + Fix: If the existing catalog is meant to be updated, use the `kubectl operator olmv1 update catalog` command instead. If the catalog is not meant to replace the existing one, consider using a different catalog name. +- ClusterCatalog is set to serve(i.e, Available=true) but never becomes healthy + Possible causes: the provided catalog image does not exist, is unreachable or does not contain a catalog. Verify whether the image is reachable and valid. More information about the error can be acquired from the status conditions. +```bash +$ kubectl operator olmv1 get catalog mycatalog1 -o yaml | yq eval '.status.conditions[] | select(.type=="Progressing")' +lastTransitionTime: "2025-11-14T14:17:44Z" +message: 'source catalog content: terminal error: error parsing image reference "myorg/mycatalogrepo:tag": repository name must be canonical' +observedGeneration: 1 +reason: Blocked +status: "False" +type: Progressing + +```

@@ -132,19 +303,122 @@ The flags allow for setting most mutable fields: - `-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) - `-s`, `--service-account`: Name of the ServiceAccount present in the namespace specified by `--namespace` to use for creating and managing resources for the new `ClusterExtension`. If not specified, the command expects a ServiceAccount `default` to be present in the namespace provided by `--namespace` with the required permissions to create and manage all the resources the `ClusterExtension` may require. - `-v`, `--version`: A version or version range to restrict search for an installable version to. If specified along with `--channels`, only versions in the version range belonging to one or more of the channels specified will be allowed. + Valid version range format examples: + - Exact: `--version 1.2.3` + - Range: `--version ">=1.0.0 <2.0.0"` + - Wildcard: `--version 1.2.x` (any patch version of 1.2) + - Minimum: `--version ">=1.5.0"` + Example combinations: +```bash +# Latest from stable channel +--channels stable + +# Version 1.2.x from any channel +--version 1.2.x + +# Version 1.2.x from stable OR beta channels +--channels stable,beta --version 1.2.x +``` - `--dry-run`: Generate the manifest that would be applied with the command without actually applying it to the cluster. - `--output`: The format for displaying manifests if `--dry-run` is specified. - `--catalog-selector`: Limit the sources that the package specified by the ClusterExtension can be installed from to ClusterCatalogs matching the provided label selector. Only useful if the ClusterCatalogs on cluster have been labelled meaningfully, such as by maturity, provider etc. eg: +```bash +--catalog-selector foo=bar +# Multiple label constraints +--catalog-selector foo=bar,bar=baz +``` - `--labels`: Labels to be added to the new ClusterExtension. - `--upgrade-constraint-policy`:Controls how upgrade versions are picked for the ClusterExtension. If set to `SelfCertified`, upgrade to any version of the package (even earlier versions, i.e, downgrades) are allowed. If set to `CatalogProvided`, only upgrade paths mentioned in the ClusterCatalog are allowed for the package. Note that `SelfCertified` upgrades may be unsafe and lead to data loss. - `--crd-upgrade-safety-enforcement`: configures pre-flight CRD Upgrade safety checks. If set to `Strict`, an upgrade will be blocked if it has breaking changes to a CRD on cluster. If set to `None`, this pre-flight check is skipped, which may cause unsafe changes during installs and upgrades.

-The command requires at minimum a resource name, `--namespace` and `--package-name`: +The command requires at minimum a resource name, `--namespace` and `--package-name`. +A minimal example: +```bash +$ kubectl operator olmv1 install extension myex --namespace myns --package-name prometheus-operator +``` + +A more complete example may look like: +```bash +$ kubectl operator olmv1 install extension testoperator --package-name prometheus --service-account olmv1-operators --namespace olmv1-system +extension "testoperator" created +``` + +This creates an extension for the `prometheus` package that installs the latest available version of that package. Success may be verified with: +```bash +$ kubectl operator olmv1 get extension +NAME INSTALLED BUNDLE VERSION SOURCE TYPE INSTALLED PROGRESSING AGE +testoperator prometheusoperator.v0.70.0 0.70.0 Catalog True True 21s +``` +A successful installation must eventually have `INSTALLED` be `True`. Poll until this condition is met or till the manifest shows error messages in its conditions. + +A failed install will have an error message on the `Progressing` condition on its `status.conditions` field in a detailed view of the resource through `kubectl operator olmv1 get extension -o yaml` +```bash +$ kubectl operator olmv1 get extension -o yaml testoperators | yq eval '.status.conditions.[] | select(.type=="Installed")' +lastTransitionTime: "2025-11-14T13:28:25Z" +message: 'service account "olmv1-operators" not found in namespace "olmv1-system": unable to authenticate with the Kubernetes cluster.' +observedGeneration: 1 +reason: Failed +status: Unknown +type: Installed +``` + +Prerequisites: + Before installing an extension, ensure: + 1. **At least one ClusterCatalog exists and is serving** + - Verify: `kubectl operator olmv1 get catalog` shows at least one catalog with `SERVING: True` + 2. **Target namespace exists** + - Verify: `kubectl get namespace ` + - Create if needed: `kubectl create namespace ` + 3. **ServiceAccount exists with required permissions** (if not using default) + - Verify: `kubectl get serviceaccount -n ` + 3. **ClusterExtension with the desired name does not already exist** + - Verify: `kubectl operator olmv1 get extension ` + - If it already exists, use a different name or update the existing ClusterExtension with `kubectl operator olmv1 update extension` + +Common errors: +- A ClusterExtension with the specified name already exists on the cluster ```bash $ kubectl operator olmv1 install extension myex --namespace myns --package-name prometheus-operator +failed to install extension "myex": clusterextensions.olm.operatorframework.io "myex" already exists +``` + Fix: If the extension is meant to be updated, use the `kubectl olmv1 update extension` command instead. If the ClusterExtension is not meant to replace the original ClusterExtension, use a different name for the new ClusterExtension. +- The package specified cannot be found +```bash +$ kubectl operator olmv1 install extension testoperator --package-name prometheusoperator +failed to install extension "testoperator": cluster extension "testoperator" did not finish installing: no bundles found for package "prometheusoperator" +``` + Cause: + - The catalog providing the package may not be serving or may be unhealthy. + Verify with `kubectl olmv1 get catalog -o yaml` that the required catalogs have healthy statuses and have `spec.availabilityMode` set to `Available`. + - The package name may be incorrect. + Verify with `kubectl olmv1 search catalog` to see if the package name is spelled correctly. + - The `--version` or `--channel` constraints may be too restrictive if present. + Verify with `kubectl olmv1 search catalog --package=` with and without `--list-versions` to see if either argument is incorrect. +- The ServiceAccount to use is missing +```bash +$ kubectl operator olmv1 install extension testoperator --package-name prometheus --service-account olmv1-operators --namespace olmv1-system +failed to install extension prometheus: cluster extension "testoperator" did not finish installing: installation cannot proceed due to missing ServiceAccount +``` + Fix: Create the ServiceAccount with the required permissions, or use an appropriate existing ServiceAccount. Note that this error may also occur if the namespace is incorrect, since the command only checks the provided namespace for the ServiceAccount. +- ServiceAccount provided is missing the expected permissions to complete the installation. +```bash +$ kubectl operator olmv1 install extension testoperator --package-name prometheus --namespace=olmv1-system +failed to install extension prometheus: cluster extension "testoperator" did not finish installing: error for resolved bundle "prometheusoperator.v0.70.0" with version "0.70.0": failed to get release state using server-side dry-run: Unable to continue with install: could not get information about the resource ServiceAccount "prometheus-operator" in namespace "olmv1-system": serviceaccounts "prometheus-operator" is forbidden: User "system:serviceaccount:olmv1-system:default" cannot get resource "serviceaccounts" in API group "" in the namespace "olmv1-system" +``` + Fix: Add the required permissions to the ServiceAccount through adding or updating the right RBAC resources. +- provided namespace does not exist +```bash +$ kubectl operator olmv1 install extension testoperators --package-name prometheus --service-account olmv1-operators --namespace randomns +failed to install extension prometheus: cluster extension "testoperators" did not finish installing: installation cannot proceed due to missing ServiceAccount ``` + Fix: Ensure the namespace exists. If it doesn't, either create it or use an existing namespace. +```bash +$ kubectl get ns randomns +Error from server (NotFound): namespaces "randomns" not found +``` +

@@ -468,6 +742,7 @@ The flags allow for limiting or formatting output: - `--package`: If non-empty, limit the listed packages and bundles to only those with the package name specified by this flag. - `--output`: This flag allows the output to be provided in a specific format. Currently support yaml, json. If empty, provides a simplified table of packages instead. +Minimal example: ```bash $ kubectl operator olmv1 search catalog @@ -477,3 +752,348 @@ ack-acm-controller operatorhubio alpha ack-acmpca-controller operatorhubio alpha ... ``` + +Full examples: +Restricting to a specific package: +```bash +$ kubectl operator olmv1 search catalog --package etcd + +PACKAGE CATALOG PROVIDER CHANNELS +etcd operatorhubio alpha,clusterwide-alpha,singlenamespace-alpha +``` + +Listing versions from a package: +```bash +$ kubectl operator olmv1 search catalog --package etcd --list-versions + +PACKAGE CATALOG PROVIDER VERSION +etcd operatorhubio CoreOS, Inc 0.9.4 +etcd operatorhubio CoreOS, Inc 0.9.4-clusterwide +etcd operatorhubio CoreOS, Inc 0.9.2 +etcd operatorhubio CoreOS, Inc 0.9.2-clusterwide +etcd operatorhubio CoreOS, Inc 0.9.0 +etcd operatorhubio CoreOS, Inc 0.6.1 +``` + +#### Specific output formats: +##### YAML output format: +```bash +$kubectl operator olmv1 search catalog --package vault-helm -o yaml +--- +defaultChannel: alpha +icon: + base64data: PHN2ZyBp= + mediatype: image/svg+xml +name: vault-helm +schema: olm.package +--- +entries: +- name: vault-helm.v0.0.1 +- name: vault-helm.v0.0.2 + replaces: vault-helm.v0.0.1 +name: alpha +package: vault-helm +schema: olm.channel +--- +image: quay.io/brejohns/vault-helm:0.0.2 +name: vault-helm.v0.0.1 +package: vault-helm +properties: +- type: olm.gvk + value: + group: vault.sdbrett.com + kind: Vault + version: v1alpha1 +- type: olm.package + value: + packageName: vault-helm + version: 0.0.1 +relatedImages: +- image: gcr.io/kubebuilder/kube-rbac-proxy:v0.5.0 + name: "" +- image: quay.io/brejohns/vault-helm:0.0.1 + name: "" +schema: olm.bundle +--- +image: quay.io/brejohns/vault-helm:0.0.2 +name: vault-helm.v0.0.2 +package: vault-helm +properties: +- type: olm.gvk + value: + group: vault.sdbrett.com + kind: Vault + version: v1alpha1 +- type: olm.package + value: + packageName: vault-helm + version: 0.0.2 +- type: olm.csv.metadata + value: + annotations: + alm-examples: |- + [ + { + "apiVersion": "vault.sdbrett.com/v1alpha1", + "kind": "Vault", + } + ] + capabilities: Basic Install + categories: Security + containerImage: quay.io/brejohns/vault-helm:0.0.2 + createdAt: "2021-01-27 09:00:00" + description: Use Helm to Deploy and manage Hashicorp Vault + operatorhub.io/ui-metadata-max-k8s-version: "1.21" + operators.operatorframework.io/builder: operator-sdk-v1.2.0 + operators.operatorframework.io/project_layout: helm.sdk.operatorframework.io/v1 + repository: https://github.com/SDBrett/vault-helm + apiServiceDefinitions: {} + crdDescriptions: + owned: + - description: Provides Vault-Helm operators with values for the Vault Helm + chart + displayName: Vault Helm + kind: Vault + name: vaults.vault.sdbrett.com + version: v1alpha1 + description: Operator for deployment and management of Hashicorp Vault instances + based on the Helm chart + displayName: Vault Helm + installModes: + - supported: true + type: OwnNamespace + - supported: false + type: SingleNamespace + - supported: false + type: MultiNamespace + - supported: true + type: AllNamespaces + keywords: + - Helm + - Vault + - Hashicorp + maintainers: + - email: brett@sdbrett.com + name: Brett Johnson + maturity: alpha + provider: + name: SDBrett + url: sdbrett.com +relatedImages: +- image: gcr.io/kubebuilder/kube-rbac-proxy:v0.5.0 + name: "" +- image: quay.io/brejohns/vault-helm:0.0.2 + name: "" +schema: olm.bundle +--- +``` + +##### JSON output format: +```json +$ kubectl operator olmv1 search catalog --package vault-helm -o json +{ + "schema": "olm.package", + "name": "vault-helm", + "defaultChannel": "alpha", + "icon": { + "base64data": "PHN2ZyBpZD0i=", + "mediatype": "image/svg+xml" + } +} +{ + "schema": "olm.channel", + "name": "alpha", + "package": "vault-helm", + "entries": [ + { + "name": "vault-helm.v0.0.1" + }, + { + "name": "vault-helm.v0.0.2", + "replaces": "vault-helm.v0.0.1" + } + ] +} +{ + "schema": "olm.bundle", + "name": "vault-helm.v0.0.1", + "package": "vault-helm", + "image": "quay.io/brejohns/vault-helm:0.0.1", + "properties": [ + { + "type": "olm.gvk", + "value": { + "group": "vault.sdbrett.com", + "kind": "Vault", + "version": "v1alpha1" + } + }, + { + "type": "olm.package", + "value": { + "packageName": "vault-helm", + "version": "0.0.1" + } + } + ], + "relatedImages": [ + { + "name": "", + "image": "gcr.io/kubebuilder/kube-rbac-proxy:v0.5.0" + }, + { + "name": "", + "image": "quay.io/brejohns/vault-helm:0.0.1" + }, + ] +} +{ + "schema": "olm.bundle", + "name": "vault-helm.v0.0.2", + "package": "vault-helm", + "image": "quay.io/brejohns/vault-helm:0.0.2", + "properties": [ + { + "type": "olm.gvk", + "value": { + "group": "vault.sdbrett.com", + "kind": "Vault", + "version": "v1alpha1" + } + }, + { + "type": "olm.package", + "value": { + "packageName": "vault-helm", + "version": "0.0.2" + } + }, + { + "type": "olm.csv.metadata", + "value": { + "annotations": { + "alm-examples": "[\n{\n\"apiVersion\": \"vault.sdbrett.com/v1alpha1\",\n\"kind\" \"Vault\"}\n]", + "capabilities": "Basic Install", + "categories": "Security", + "containerImage": "quay.io/brejohns/vault-helm:0.0.2", + "createdAt": "2021-01-27 09:00:00", + "description": "Use Helm to Deploy and manage Hashicorp Vault", + "operatorhub.io/ui-metadata-max-k8s-version": "1.21", + "operators.operatorframework.io/builder": "operator-sdk-v1.2.0", + "operators.operatorframework.io/project_layout": "helm.sdk.operatorframework.io/v1", + "repository": "https://github.com/SDBrett/vault-helm" + }, + "apiServiceDefinitions": {}, + "crdDescriptions": { + "owned": [ + { + "description": "Provides Vault-Helm operators with values for the Vault Helm chart", + "displayName": "Vault Helm", + "kind": "Vault", + "name": "vaults.vault.sdbrett.com", + "version": "v1alpha1" + } + ] + }, + "description": "Operator for deployment and management of Hashicorp Vault instances based on the Helm chart", + "displayName": "Vault Helm", + "installModes": [ + { + "supported": true, + "type": "OwnNamespace" + }, + { + "supported": false, + "type": "SingleNamespace" + }, + { + "supported": false, + "type": "MultiNamespace" + }, + { + "supported": true, + "type": "AllNamespaces" + } + ], + "keywords": [ + "Helm", + "Vault", + "Hashicorp" + ], + "maintainers": [ + { + "email": "brett@sdbrett.com", + "name": "Brett Johnson" + } + ], + "maturity": "alpha", + "provider": { + "name": "SDBrett", + "url": "sdbrett.com" + } + } + } + ], + "relatedImages": [ + { + "name": "", + "image": "gcr.io/kubebuilder/kube-rbac-proxy:v0.5.0" + }, + { + "name": "", + "image": "quay.io/brejohns/vault-helm:0.0.2" + }, + ] +} +``` + +## Recommended Workflows + +### Adding a catalog: + 1. **Validate inputs**: + - Verify catalog name doesn't already exist: `kubectl operator olmv1 get catalog ` + - Should return: not found (error is expected) + 2. **Create catalog**: +```bash +kubectl operator olmv1 create catalog +``` + - Expected output: catalog "" created + - If no output or different message: creation failed + 3. Poll for serving status (if --available=true or default): + kubectl operator olmv1 get catalog + - Poll every 15-30 seconds + - Wait until SERVING: True or timeout after 5 minutes. This may be slightly greater for very large catalogs. + - If SERVING stays False, check kubectl operator olmv1 get catalog -o yaml for error conditions + 4. Verify packages available (optional): + kubectl operator olmv1 search catalog --catalog + - Should show packages from the catalog + - If no packages, catalog may be empty or invalid + +### Installing a package: + For reliable installation, follow this sequence: + 1. **Search for the package**: +```bash +$ kubectl operator olmv1 search catalog --package +``` +```bash +$ kubectl operator olmv1 search catalog --package --list-versions +``` + Verify the package exists and note available channels/versions. + If package-name is not known, search the catalog for a potential match: +```bash +$ kubectl operator olmv1 search catalog +``` + 2. Check catalogs are serving: + kubectl operator olmv1 get catalog + 2. Ensure at least one catalog shows SERVING: True. + 3. Ensure a ServiceAccount with the required permissions for installing the operator. May provide blanket permissions on dry-runs. + 4. Install the extension: +```bash +$ kubectl operator olmv1 install extension --namespace --package-name --service-account +``` + 5. Verify installation: +```bash +$ kubectl operator olmv1 get extension +``` + Wait for INSTALLED: True. +