diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index e768043..66bdef7 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -63,6 +63,11 @@ "name": "must-gather", "source": "./plugins/must-gather", "description": "A plugin to analyze and report on must-gather data" + }, + { + "name": "olmv1", + "source": "./plugins/olmv1", + "description": "A plugin for managing Kubernetes extensions using OLM v1 (operator-controller)" } ] } diff --git a/plugins/olmv1/.claude-plugin/plugin.json b/plugins/olmv1/.claude-plugin/plugin.json new file mode 100644 index 0000000..6bf607c --- /dev/null +++ b/plugins/olmv1/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "olmv1", + "description": "A plugin for managing Kubernetes extensions using OLM v1 (operator-controller)", + "version": "0.1.0", + "author": { + "name": "openshift-eng" + } +} diff --git a/plugins/olmv1/README.md b/plugins/olmv1/README.md new file mode 100644 index 0000000..0306313 --- /dev/null +++ b/plugins/olmv1/README.md @@ -0,0 +1,328 @@ +# OLM v1 Plugin + +Manage Kubernetes cluster extensions using Operator Lifecycle Manager v1 (operator-controller). + +## Overview + +OLM v1 provides a simpler, more flexible approach to managing Kubernetes extensions including Operators, Helm charts, and other cluster extensions. This plugin helps you discover, install, upgrade, and manage extensions in your cluster. + +## Prerequisites + +- `kubectl` or `oc` CLI configured with cluster access +- OLM v1 (operator-controller) installed in the cluster +- Appropriate RBAC permissions for managing ClusterExtensions and ClusterCatalogs + +## Key Concepts + +- **ClusterCatalog**: A catalog of available extensions +- **ClusterExtension**: An installed extension in the cluster +- **Channels**: Release channels for extensions (stable, candidate, etc.) +- **Version Constraints**: Semver-based version management +- **ServiceAccount & RBAC**: Each extension requires a ServiceAccount with sufficient permissions to install and operate + +## Important: RBAC Requirements in OLM v1 + +**CRITICAL DIFFERENCE FROM OLM v0**: In OLM v1, YOU (the cluster admin) must provide a ServiceAccount with all necessary RBAC permissions for each extension. OLM v1 does NOT have cluster-admin privileges like OLM v0. + +### ServiceAccount Requirements + +Every ClusterExtension installation requires: +1. A ServiceAccount in the target namespace +2. RBAC permissions (ClusterRole/Role) granting the ServiceAccount rights to: + - Create and manage the extension's resources (Deployments, Services, ConfigMaps, etc.) + - Create Custom Resource Definitions (CRDs) + - Create RBAC resources (if the extension creates its own Roles/RoleBindings) + - Any additional permissions the extension needs to operate + +### PreflightPermissions Feature Gate + +When the `PreflightPermissions` feature gate is enabled in operator-controller: +- OLM performs a **preflight check** before installation +- Missing RBAC permissions are identified and reported in the ClusterExtension status conditions +- Installation fails fast with clear error messages listing exactly which permissions are missing +- This helps you iteratively fix RBAC issues without trial and error + +The `/olmv1:install` command automatically creates baseline RBAC permissions and can iteratively fix missing permissions when preflight checks fail. + +### Webhook Feature Gates + +Many operators include admission webhooks (mutating or validating webhook configurations). OLM v1 requires a feature gate to be enabled for webhook support: + +**WebhookProviderCertManager** (recommended): +- Enables webhook support using cert-manager to provision certificates +- Requires cert-manager to be installed in the cluster +- Enable with: + ```bash + kubectl patch deployment operator-controller-controller-manager -n olmv1-system --type=json \ + -p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", + "value": "--feature-gates=WebhookProviderCertManager=true"}]' + ``` + +**WebhookProviderOpenshiftServiceCA**: +- Enables webhook support using OpenShift's service CA for certificate provisioning +- Only available on OpenShift clusters +- Enable similarly with `--feature-gates=WebhookProviderOpenshiftServiceCA=true` + +**What happens without webhook support:** +- Operators with webhooks will fail to install with error: "unsupported bundle: webhookDefinitions are not supported" +- The `/olmv1:install` and `/olmv1:status` commands will detect this and suggest enabling the appropriate feature gate +- If cert-manager is installed, the commands may automatically enable WebhookProviderCertManager + +**Additional RBAC for webhooks:** +When webhooks are enabled via cert-manager, your ServiceAccount also needs permissions for cert-manager resources: +```yaml +- apiGroups: ["cert-manager.io"] + resources: ["certificates", "issuers", "certificaterequests"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] +``` + +## Commands + +### Catalog Management + +#### `/olmv1:catalog-add [--poll-interval ]` +Add a new catalog source to the cluster. + +**Example:** +```bash +/olmv1:catalog-add operatorhubio quay.io/operatorhubio/catalog:latest +/olmv1:catalog-add my-catalog registry.example.com/catalog:v1 --poll-interval 1h +``` + +#### `/olmv1:catalog-list` +List all available catalogs and their status. + +**Example:** +```bash +/olmv1:catalog-list +``` + +### Extension Discovery + +#### `/olmv1:search [--catalog ]` +Search for available extensions across catalogs. + +**Example:** +```bash +/olmv1:search cert-manager +/olmv1:search prometheus --catalog operatorhubio +``` + +### Extension Installation + +#### `/olmv1:install [--version ] [--channel ] [--catalog ] [--namespace ]` +Install an extension with optional version or channel constraints. + +**Parameters:** +- `extension-name`: Name of the extension to install (required) +- `--version`: Specific version or version range (e.g., "1.14.5", ">=1.14.0 <1.15.0") +- `--channel`: Channel to track (e.g., "stable", "candidate") +- `--catalog`: Catalog source to use +- `--namespace`: Target namespace for namespaced extensions + +**Examples:** +```bash +# Install latest from stable channel +/olmv1:install cert-manager --channel stable + +# Install specific version +/olmv1:install argocd-operator --version 0.11.0 + +# Install with version range +/olmv1:install prometheus-operator --version ">=0.68.0 <0.69.0" + +# Install from specific catalog +/olmv1:install my-extension --catalog my-catalog +``` + +### Extension Management + +#### `/olmv1:list [--all-namespaces]` +List all installed extensions with their status. + +**Example:** +```bash +/olmv1:list +/olmv1:list --all-namespaces +``` + +#### `/olmv1:status ` +Get detailed status and health information for an installed extension. + +**Shows:** +- Installation status and conditions +- Resolved version and channel +- ServiceAccount and RBAC configuration +- Associated resources (CRDs, deployments, services) +- Recent events and issues +- **RBAC/preflight permission errors** (if present) + +**Example:** +```bash +/olmv1:status cert-manager +``` + +#### `/olmv1:fix-rbac ` +Analyze and fix RBAC permission issues for a ClusterExtension that failed preflight checks. + +**What it does:** +- Detects pre-authorization failures in the ClusterExtension status +- Parses the missing RBAC permissions from error messages +- Identifies the current ServiceAccount and ClusterRole +- Offers to automatically update the ClusterRole with missing permissions +- Or displays the required RBAC YAML for manual application + +**When to use:** +- Extension installation is stuck in "Progressing" state +- Status shows "pre-authorization failed" errors +- You see RBAC-related error messages + +**Example:** +```bash +/olmv1:fix-rbac postgres-operator +``` + +**Note:** Requires the `PreflightPermissions` feature gate to be enabled in operator-controller for detailed permission analysis. + +### Extension Upgrades + +#### `/olmv1:upgrade [--version ] [--channel ]` +Upgrade an extension using different strategies. + +**Strategies:** +- Channel-based: Track a specific channel for automatic updates +- Version pinning: Upgrade to a specific version +- Version range: Allow upgrades within a version range +- Z-stream: Stay within the same minor version + +**Examples:** +```bash +# Upgrade to latest in stable channel +/olmv1:upgrade cert-manager --channel stable + +# Upgrade to specific version +/olmv1:upgrade argocd-operator --version 0.12.0 + +# Upgrade within version range (z-stream) +/olmv1:upgrade prometheus-operator --version "~0.68.0" +``` + +### Extension Removal + +#### `/olmv1:uninstall ` +Safely uninstall an extension from the cluster. + +**Example:** +```bash +/olmv1:uninstall cert-manager +``` + +## Typical Workflows + +### Installing a New Extension +```bash +# 1. Search for the extension +/olmv1:search postgres-operator + +# 2. Install with desired version/channel +# This automatically creates: +# - Namespace +# - ServiceAccount +# - ClusterRole with baseline permissions +# - ClusterRoleBinding +# - ClusterExtension +/olmv1:install postgres-operator --channel stable --namespace postgres-operator + +# 3. If installation fails due to RBAC issues: +/olmv1:status postgres-operator +# Will show missing permissions + +# 4. Fix RBAC automatically +/olmv1:fix-rbac postgres-operator + +# 5. Verify installation succeeded +/olmv1:status postgres-operator + +# 6. List all installed extensions +/olmv1:list +``` + +### Managing Upgrades +```bash +# Check current status +/olmv1:status my-extension + +# Upgrade to latest in channel +/olmv1:upgrade my-extension --channel stable + +# Or pin to specific version +/olmv1:upgrade my-extension --version 2.0.0 + +# Verify upgrade +/olmv1:status my-extension +``` + +### Troubleshooting +```bash +# Check extension status and conditions (including RBAC issues) +/olmv1:status + +# Fix RBAC permission issues +/olmv1:fix-rbac + +# Check catalog availability +/olmv1:catalog-list + +# View all extensions and their health +/olmv1:list +``` + +## Differences from OLM v0 + +- **Simpler API**: Uses ClusterExtension and ClusterCatalog instead of Subscription/CSV/InstallPlan +- **Flexible versioning**: Supports semver ranges and version constraints +- **Broader scope**: Manages any Kubernetes extension, not just Operators +- **No automatic upgrades**: Explicit upgrade commands for better control +- **GitOps friendly**: Declarative extension management +- **⚠️ USER-MANAGED RBAC**: You must provide ServiceAccounts with proper RBAC permissions (OLM v0 had cluster-admin but best practices are to avoid this whenever possible) + +## Troubleshooting + +Common issues and solutions: + +1. **Extension stuck in progressing state with RBAC errors**: + - Run `/olmv1:status ` to see missing permissions + - Use `/olmv1:fix-rbac ` to automatically fix RBAC issues + - Requires `PreflightPermissions` feature gate enabled for detailed error messages + +2. **Pre-authorization failed errors**: + - These indicate the ServiceAccount lacks required RBAC permissions + - Error messages show exactly which permissions are missing in format: + ``` + Namespace:"" APIGroups:[apps] Resources:[deployments] Verbs:[create,update] + ``` + - Use `/olmv1:fix-rbac` to parse and apply missing permissions automatically + +3. **Catalog not available**: + - Verify catalog image and network connectivity + - Run `/olmv1:catalog-list` to check catalog status + +4. **Version conflicts**: + - Use `/olmv1:status` to see resolved dependencies + - Check for conflicting version constraints + +5. **ServiceAccount doesn't exist**: + - The `/olmv1:install` command creates ServiceAccounts automatically + - Ensure the namespace exists and you have permissions to create ServiceAccounts + +6. **PreflightPermissions feature gate not enabled**: + - Without this gate, RBAC errors won't be caught early + - Installation will fail with less helpful error messages + - Consider enabling it in operator-controller for better RBAC feedback + +## Resources + +- [OLM v1 Documentation](https://operator-framework.github.io/operator-controller/) +- [OLM v1 GitHub Repository](https://github.com/operator-framework/operator-controller) +- [Migration from OLM v0](https://operator-framework.github.io/operator-controller/concepts/olmv0-to-olmv1/) +- [RBAC Permissions Checking Guide](https://github.com/operator-framework/operator-controller/blob/main/docs/draft/howto/rbac-permissions-checking.md) diff --git a/plugins/olmv1/commands/catalog-add.md b/plugins/olmv1/commands/catalog-add.md new file mode 100644 index 0000000..21a1d5d --- /dev/null +++ b/plugins/olmv1/commands/catalog-add.md @@ -0,0 +1,62 @@ +# Add Catalog Command + +You are helping the user add a new catalog source to their OLM v1 enabled cluster. + +## Task + +Add a ClusterCatalog resource to make extensions available for installation. + +## Steps + +1. **Gather catalog information**: + - Catalog name (provided by user) + - Image reference (provided by user) + - Optional: Poll interval (default: 15m) + +2. **Create ClusterCatalog resource**: + ```yaml + apiVersion: olm.operatorframework.io/v1alpha1 + kind: ClusterCatalog + metadata: + name: + spec: + source: + type: Image + image: + ref: + pollInterval: + ``` + +3. **Apply the resource**: + ```bash + kubectl apply -f + ``` + +4. **Verify catalog availability**: + ```bash + kubectl get clustercatalog + kubectl wait --for=condition=Unpacked clustercatalog/ --timeout=5m + ``` + +5. **Report status**: + - Confirm catalog was added successfully + - Show catalog status and last update time + - Provide next steps (e.g., search for extensions) + +## Error Handling + +- If catalog image is unreachable, suggest checking image reference and network connectivity +- If catalog fails to unpack, check the ClusterCatalog status conditions for details +- If RBAC errors occur, suggest checking cluster permissions + +## Example Output + +``` +✓ Created ClusterCatalog: my-catalog +✓ Waiting for catalog to unpack... +✓ Catalog ready: my-catalog (Last updated: 2025-10-28T10:30:00Z) + +Next steps: +- Search for extensions: /olmv1:search --catalog my-catalog +- List all catalogs: /olmv1:catalog-list +``` diff --git a/plugins/olmv1/commands/catalog-list.md b/plugins/olmv1/commands/catalog-list.md new file mode 100644 index 0000000..0dc103e --- /dev/null +++ b/plugins/olmv1/commands/catalog-list.md @@ -0,0 +1,44 @@ +# List Catalogs Command + +You are helping the user list all available catalogs in their OLM v1 enabled cluster. + +## Task + +Display all ClusterCatalog resources and their status. + +## Steps + +1. **List all ClusterCatalogs**: + ```bash + kubectl get clustercatalogs + ``` + +2. **Get detailed status**: + ```bash + kubectl get clustercatalogs -o wide + ``` + +3. **Format output**: + Show for each catalog: + - Name + - Source image + - Status (Ready, Unpacking, Failed) + - Last updated timestamp + - Number of available packages (if available) + +4. **Check for issues**: + - Identify catalogs that are not ready + - Show any error conditions + +## Example Output + +``` +Available Catalogs: + +NAME IMAGE STATUS LAST UPDATED +operatorhubio quay.io/operatorhubio/catalog:latest Ready 2025-10-28T09:15:00Z +certified registry.redhat.io/certified:v4.15 Ready 2025-10-28T08:30:00Z +my-catalog registry.example.com/catalog:v1 Ready 2025-10-28T10:00:00Z + +Total: 3 catalogs (3 ready, 0 failed) +``` diff --git a/plugins/olmv1/commands/fix-rbac.md b/plugins/olmv1/commands/fix-rbac.md new file mode 100644 index 0000000..3bf19ee --- /dev/null +++ b/plugins/olmv1/commands/fix-rbac.md @@ -0,0 +1,250 @@ +# Fix RBAC Permissions Command + +You are helping the user diagnose and fix RBAC permission issues for a ClusterExtension that failed preflight checks. + +## Task + +Analyze a ClusterExtension's status conditions to identify missing RBAC permissions and either suggest or automatically apply the fixes. + +## Prerequisites + +- The ClusterExtension must exist in the cluster +- Ideally, the `PreflightPermissions` feature gate should be enabled for detailed permission analysis +- User must have permissions to update ClusterRoles and ClusterRoleBindings + +## Steps + +1. **Verify ClusterExtension exists**: + ```bash + kubectl get clusterextension + ``` + +2. **Get ClusterExtension full status**: + ```bash + kubectl get clusterextension -o yaml + ``` + +3. **Extract namespace and service account information**: + ```bash + # Get namespace + NAMESPACE=$(kubectl get clusterextension -o jsonpath='{.spec.namespace}') + + # Get service account name + SA_NAME=$(kubectl get clusterextension -o jsonpath='{.spec.serviceAccount.name}') + ``` + +4. **Check for pre-authorization failure in status conditions**: + ```bash + kubectl get clusterextension -o jsonpath='{.status.conditions}' | \ + jq -r '.[] | select(.message | contains("pre-authorization failed")) | .message' + ``` + +5. **Parse missing permissions from the error message**: + + The error message format looks like: + ``` + pre-authorization failed: service account requires the following permissions to manage cluster extension: + Namespace:"" APIGroups:[] Resources:[services] Verbs:[list,watch] + Namespace:"postgres-operator" APIGroups:[apps] Resources:[statefulsets] Verbs:[create,update,delete] + ``` + + Extract each permission line and parse into structured data: + - `Namespace:""` → cluster-scoped (empty namespace) + - `Namespace:""` → namespace-scoped + - `APIGroups:[]` → core API group (use `""` in YAML) + - `APIGroups:[group1,group2]` → specific API groups + - `Resources:[...]` → resource types + - `Verbs:[...]` → required verbs + +6. **Find existing ClusterRole or RoleBinding**: + ```bash + # Find ClusterRoleBindings for the service account + kubectl get clusterrolebindings -o json | \ + jq -r --arg sa "$SA_NAME" --arg ns "$NAMESPACE" \ + '.items[] | select(.subjects[]? | select(.kind=="ServiceAccount" and .name==$sa and .namespace==$ns)) | .metadata.name' + + # Get the ClusterRole name from the binding + CLUSTERROLE=$(kubectl get clusterrolebinding -o jsonpath='{.roleRef.name}') + ``` + +7. **Generate RBAC rules from parsed permissions**: + + For each missing permission, create a YAML rule: + + ```yaml + - apiGroups: [""] # or [""] for core + resources: ["", ""] + verbs: ["", ""] + # Add resourceNames: [] if specific resource names are mentioned + ``` + + Special cases: + - If namespace is empty (`Namespace:""`), this goes in a ClusterRole (cluster-scoped) + - If namespace is specified, this could go in a Role (namespace-scoped) OR ClusterRole + - Multiple resources with same APIGroup and Namespace can be combined into one rule + - Combine verbs when resources and APIGroups match + +8. **Present the missing permissions**: + + Show a clear summary: + ``` + Missing RBAC Permissions for : + + Cluster-scoped permissions (ClusterRole): + - APIGroups: [""], Resources: ["services"], Verbs: ["list", "watch"] + - APIGroups: ["apps"], Resources: ["statefulsets"], Verbs: ["create", "update", "delete"] + + Namespace-scoped permissions in '': + - APIGroups: [""], Resources: ["configmaps"], Verbs: ["get", "create"] + ``` + +9. **Offer to apply fixes automatically OR show manual instructions**: + + **Option A: Automatic (if user wants)** + - Fetch the existing ClusterRole + - Add the missing rules to the ClusterRole + - Apply the updated ClusterRole + - Wait for the ClusterExtension to reconcile and retry installation + + **Option B: Manual instructions** + - Display the complete YAML for the updated ClusterRole + - Provide `kubectl apply -f` command + - Explain that the operator-controller will automatically retry once RBAC is fixed + +10. **Verify the fix worked**: + After applying RBAC changes, monitor the ClusterExtension: + ```bash + kubectl get clusterextension -w + ``` + + Check if the pre-authorization error is cleared: + ```bash + kubectl get clusterextension -o jsonpath='{.status.conditions}' | \ + jq '.[] | select(.type=="Progressing" or .type=="Installed")' + ``` + +11. **Report results**: + - If automatic fix applied: Show the updated ClusterRole and confirm installation is proceeding + - If manual instructions: Provide the complete YAML and apply command + - Show the expected next state (installation should proceed automatically) + +## Error Handling + +- **ClusterExtension not found**: Suggest using `/olmv1:list` to see available extensions +- **No pre-authorization errors**: Check if extension is already installed or has other errors +- **PreflightPermissions feature gate disabled**: + - Explain that preflight checks are not enabled + - Suggest enabling the feature gate or reviewing operator-controller logs + - Provide general RBAC troubleshooting guidance +- **Cannot find existing ClusterRole**: + - Explain that RBAC may not have been set up + - Suggest using `/olmv1:install` which creates RBAC automatically +- **Permission denied updating ClusterRole**: + - User doesn't have cluster-admin or sufficient RBAC permissions + - Show the YAML they need to apply manually or ask their cluster admin + +## Parsing Pre-authorization Error Format + +The error message format from operator-controller is: +``` +pre-authorization failed: service account requires the following permissions to manage cluster extension: + Namespace:"" APIGroups:[] Resources:[] Verbs:[] +``` + +Parsing rules: +1. Look for lines starting with ` Namespace:"` +2. Extract namespace value (empty string means cluster-scoped) +3. Extract APIGroups (comma-separated list in brackets, empty `[]` means core group) +4. Extract Resources (comma-separated list in brackets) +5. Extract Verbs (comma-separated list in brackets) + +Example parsing: +``` +Input: Namespace:"" APIGroups:[] Resources:[services] Verbs:[list,watch] +Output: {namespace: "", apiGroups: [""], resources: ["services"], verbs: ["list", "watch"]} + +Input: Namespace:"myns" APIGroups:[apps,batch] Resources:[deployments,jobs] Verbs:[create] +Output: {namespace: "myns", apiGroups: ["apps", "batch"], resources: ["deployments", "jobs"], verbs: ["create"]} +``` + +## Example Output + +### When Pre-authorization Errors Found + +``` +Analyzing RBAC permissions for extension: postgres-operator + +Found pre-authorization failure in status conditions. + +Missing RBAC Permissions: +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Cluster-scoped permissions needed: +1. Core resources (APIGroup: "") + - Resources: persistentvolumeclaims + - Verbs: create, delete, get, list + +2. Apps API (APIGroup: apps) + - Resources: statefulsets + - Verbs: create, update, patch, delete + +Namespace-scoped permissions in "postgres-operator": +3. Core resources (APIGroup: "") + - Resources: secrets + - Verbs: get, list, watch + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Current ServiceAccount: postgres-operator-sa (namespace: postgres-operator) +Current ClusterRole: postgres-operator-installer + +Apply these fixes? (yes/no/show-yaml): yes + +Updating ClusterRole: postgres-operator-installer... +✓ ClusterRole updated successfully + +Waiting for operator-controller to retry installation... +✓ Pre-authorization check passed +✓ Installation is now progressing + +The ClusterExtension should install successfully now. +Monitor with: kubectl get clusterextension postgres-operator -w +``` + +### When No Errors Found + +``` +Analyzing RBAC permissions for extension: postgres-operator + +✓ No pre-authorization errors found + +Status: Installed +The ClusterExtension is successfully installed with proper RBAC permissions. + +Current RBAC configuration: +- ServiceAccount: postgres-operator-sa (namespace: postgres-operator) +- ClusterRole: postgres-operator-installer +- All required permissions are granted +``` + +### When Feature Gate Disabled + +``` +Analyzing RBAC permissions for extension: postgres-operator + +⚠ PreflightPermissions feature gate is not enabled + +Without the PreflightPermissions feature gate, the operator-controller does not +perform pre-authorization checks or report missing permissions in status conditions. + +Current status: Failed (or Progressing) +Error: + +To enable detailed RBAC checking: +1. Enable PreflightPermissions feature gate in operator-controller +2. Restart the operator-controller pod +3. The next reconciliation will perform preflight checks + +Alternative: Check operator-controller logs for RBAC errors: +kubectl logs -n olmv1-system -l app.kubernetes.io/name=operator-controller +``` diff --git a/plugins/olmv1/commands/install.md b/plugins/olmv1/commands/install.md new file mode 100644 index 0000000..13cd330 --- /dev/null +++ b/plugins/olmv1/commands/install.md @@ -0,0 +1,304 @@ +# Install Extension Command + +You are helping the user install a Kubernetes extension using OLM v1. + +## Task + +Install an extension with the specified version/channel constraints, including proper service account and RBAC setup. + +## Important: Service Account and RBAC Requirements + +**CRITICAL**: OLM v1 requires that YOU (the cluster admin) provide a ServiceAccount with sufficient RBAC permissions. Unlike OLM v0, OLM v1 does NOT have cluster-admin privileges. The ServiceAccount you provide must have all necessary permissions for the extension to install and operate. + +If the `PreflightPermissions` feature gate is enabled in the cluster, OLM will perform a preflight check and report missing permissions in the ClusterExtension status conditions before attempting installation. This helps you identify and fix RBAC issues up front. + +## Steps + +1. **Check operator-controller feature gates**: + + Before starting installation, check if necessary feature gates are enabled: + + ```bash + kubectl get deployment operator-controller-controller-manager -n olmv1-system \ + -o jsonpath='{.spec.template.spec.containers[0].args}' | jq -r '.[]' | grep feature-gates + ``` + + Important feature gates: + - **WebhookProviderCertManager** or **WebhookProviderOpenshiftServiceCA**: Required for operators with webhooks (mutating/validating webhook configurations) + - **PreflightPermissions**: Enables RBAC validation before installation, providing clear error messages about missing permissions + + If webhooks are needed but feature gate is not enabled: + - Check if cert-manager is installed: `kubectl get pods -n cert-manager` + - Enable the feature gate (this command is in the allow-list): + ```bash + kubectl patch deployment operator-controller-controller-manager -n olmv1-system --type=json \ + -p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", "value": "--feature-gates=WebhookProviderCertManager=true"}]' + ``` + - Wait for rollout: `kubectl rollout status deployment operator-controller-controller-manager -n olmv1-system` + +2. **Gather installation parameters**: + - Extension name (required) + - Version constraint (optional: specific version, range, or channel) + - Catalog source (optional: auto-detect if not specified) + - Target namespace (required for service account and resources) + - Service account name (default: `-sa`) + +3. **Validate extension exists**: + ```bash + kubectl get packages -A | grep + ``` + +4. **Determine installation strategy**: + - Channel-based: If --channel specified + - Version-specific: If --version with exact version + - Version range: If --version with range (e.g., ">=1.0.0 <2.0.0") + +5. **Create namespace if it doesn't exist**: + ```bash + kubectl create namespace --dry-run=client -o yaml | kubectl apply -f - + ``` + +6. **Create ServiceAccount**: + ```bash + kubectl create serviceaccount -sa -n --dry-run=client -o yaml | kubectl apply -f - + ``` + +7. **Create initial RBAC permissions**: + + Start with a baseline ClusterRole that grants common permissions needed by most extensions: + + ```yaml + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: -installer + rules: + # Common core resources + - apiGroups: [""] + resources: ["services", "serviceaccounts", "configmaps", "secrets"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] + - apiGroups: [""] + resources: ["namespaces"] + verbs: ["get", "list", "watch"] + # Apps resources + - apiGroups: ["apps"] + resources: ["deployments", "statefulsets", "daemonsets"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] + # RBAC (needed to create operator's own roles) + - apiGroups: ["rbac.authorization.k8s.io"] + resources: ["roles", "rolebindings", "clusterroles", "clusterrolebindings"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete", "bind", "escalate"] + # CRDs + - apiGroups: ["apiextensions.k8s.io"] + resources: ["customresourcedefinitions"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] + # Admission webhooks (if needed) + - apiGroups: ["admissionregistration.k8s.io"] + resources: ["validatingwebhookconfigurations", "mutatingwebhookconfigurations"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] + ``` + + Bind the ClusterRole to the ServiceAccount: + + ```yaml + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRoleBinding + metadata: + name: -installer + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: -installer + subjects: + - kind: ServiceAccount + name: -sa + namespace: + ``` + +8. **Create ClusterExtension resource**: + ```yaml + apiVersion: olm.operatorframework.io/v1alpha1 + kind: ClusterExtension + metadata: + name: + spec: + namespace: + serviceAccount: + name: -sa + source: + sourceType: Catalog + catalog: + packageName: + version: "" # or omit for channel + channel: "" # or omit for version + ``` + +9. **Apply the resources**: + ```bash + kubectl apply -f + kubectl apply -f + kubectl apply -f + kubectl apply -f + kubectl apply -f + ``` + +10. **Monitor installation**: + ```bash + kubectl wait --for=condition=Installed clusterextension/ --timeout=5m + kubectl get clusterextension -o yaml + ``` + +11. **Check for webhook-related errors**: + + If you see errors like "unsupported bundle: webhookDefinitions are not supported": + - This means the operator bundle includes webhooks but the feature gate is not enabled + - Check if cert-manager is available: `kubectl get pods -n cert-manager` + - Enable the WebhookProviderCertManager feature gate (see step 1) + - Trigger reconciliation: `kubectl annotate clusterextension reconcile="$(date +%s)" --overwrite` + + If webhooks are enabled but you see cert-manager permission errors: + - Add cert-manager permissions to the ClusterRole: + ```yaml + - apiGroups: ["cert-manager.io"] + resources: ["certificates", "issuers", "certificaterequests"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] + ``` + +12. **Check for RBAC/preflight errors**: + If installation fails or hangs, check the ClusterExtension status conditions: + + ```bash + kubectl get clusterextension -o jsonpath='{.status.conditions}' | jq '.[] | select(.type=="Progressing" or .type=="Installing")' + ``` + + Look for messages starting with "pre-authorization failed:" which will list missing RBAC permissions in this format: + ``` + Namespace:"" APIGroups:[] Resources:[services] Verbs:[list,watch] + Namespace:"" APIGroups:[apps] Resources:[deployments] Verbs:[create] + ``` + + - `Namespace:""` means cluster-scoped permissions needed + - `APIGroups:[]` means core API group (no group) + - Add the missing permissions to the ClusterRole and reapply + +13. **Iteratively fix RBAC if needed**: + If preflight checks fail: + - Parse the error message to extract missing permissions + - Update the ClusterRole with additional rules + - Reapply the ClusterRole + - The controller will automatically retry installation + +14. **Verify installation**: + - Check ClusterExtension status shows "Installed" + - Verify CRDs were created + - Check associated deployments/pods + - Validate extension is functioning + +15. **Report results**: + - Installation success with version installed + - List created resources (CRDs, namespaces, service accounts, RBAC) + - Provide next steps or usage examples + - If RBAC issues encountered, show the final working RBAC configuration + +## Error Handling + +- Extension not found: Suggest running `/olmv1:search ` first +- Version/channel doesn't exist: Show available versions/channels using search +- Namespace doesn't exist: Create it automatically +- ServiceAccount doesn't exist: Create it automatically +- **Webhook-related errors**: + - "unsupported bundle: webhookDefinitions are not supported": Enable WebhookProviderCertManager feature gate + - Check if cert-manager is installed before enabling webhook support + - Automatically enable the feature gate if cert-manager is available (kubectl patch command is in allow-list) + - After enabling, trigger reconciliation with annotation + - Add cert-manager.io permissions to ClusterRole if needed +- **RBAC/Pre-authorization errors**: + - Parse the "pre-authorization failed" message from status conditions + - Extract the missing permissions (Namespace, APIGroups, Resources, Verbs) + - Suggest specific RBAC rules to add to the ClusterRole + - Remind user to reapply after fixing RBAC + - Suggest using `/olmv1:fix-rbac ` to automatically generate missing permissions +- Installation failed (other): Parse status conditions and provide specific error +- Resource conflicts: Identify conflicting resources + +## Example Output + +### Successful Installation + +``` +Installing postgres-operator... + +✓ Created namespace: postgres-operator +✓ Created ServiceAccount: postgres-operator-sa +✓ Created ClusterRole: postgres-operator-installer +✓ Created ClusterRoleBinding: postgres-operator-installer +✓ Validated extension exists in catalog: operatorhubio +✓ Created ClusterExtension resource +✓ Waiting for installation to complete... +✓ Extension installed successfully + +Installed: postgres-operator +Version: 1.2.0 +Channel: stable +Namespace: postgres-operator + +Created Resources: +- Namespace: postgres-operator +- ServiceAccount: postgres-operator-sa (with ClusterRole permissions) +- CRDs: postgresqls.acid.zalan.do, operatorconfigurations.acid.zalan.do +- Deployment: postgres-operator (1/1 ready) + +Next steps: +- Check status: /olmv1:status postgres-operator +- View all extensions: /olmv1:list +``` + +### Installation with RBAC Fixes + +``` +Installing postgres-operator... + +✓ Created namespace: postgres-operator +✓ Created ServiceAccount: postgres-operator-sa +✓ Created ClusterRole: postgres-operator-installer (baseline permissions) +✓ Created ClusterRoleBinding: postgres-operator-installer +✓ Validated extension exists in catalog: operatorhubio +✓ Created ClusterExtension resource +⚠ Preflight check failed - missing RBAC permissions + +Missing permissions detected: + Namespace:"" APIGroups:[] Resources:[persistentvolumeclaims] Verbs:[create,delete] + Namespace:"" APIGroups:[apps] Resources:[statefulsets] Verbs:[create,update] + +Updating ClusterRole with missing permissions... +✓ Updated ClusterRole: postgres-operator-installer +✓ Waiting for installation to retry... +✓ Extension installed successfully + +Installed: postgres-operator +Version: 1.2.0 +Channel: stable +Namespace: postgres-operator + +Final RBAC Configuration: +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: postgres-operator-installer +rules: +# (baseline permissions) +# ... +# Additional permissions required: +- apiGroups: [""] + resources: ["persistentvolumeclaims"] + verbs: ["create", "delete"] +- apiGroups: ["apps"] + resources: ["statefulsets"] + verbs: ["create", "update"] + +Next steps: +- Check status: /olmv1:status postgres-operator +- View all extensions: /olmv1:list +- Save RBAC config for future reference +``` diff --git a/plugins/olmv1/commands/list.md b/plugins/olmv1/commands/list.md new file mode 100644 index 0000000..f2bf660 --- /dev/null +++ b/plugins/olmv1/commands/list.md @@ -0,0 +1,52 @@ +# List Extensions Command + +You are helping the user list all installed extensions in their cluster. + +## Task + +Display all ClusterExtension resources with their status and health. + +## Steps + +1. **List all ClusterExtensions**: + ```bash + kubectl get clusterextensions + ``` + +2. **Get detailed information**: + For each extension, gather: + - Name + - Package name + - Installed version + - Channel (if applicable) + - Status (Installed, Progressing, Failed) + - Namespace + +3. **Check health indicators**: + - Installation status condition + - Associated pod health + - Recent events or errors + +4. **Format output**: + Display in tabular format with key information. + +5. **Highlight issues**: + - Mark failed or degraded extensions + - Show extensions with pending updates (if tracking channel) + +## Example Output + +``` +Installed Extensions: + +NAME PACKAGE VERSION CHANNEL STATUS NAMESPACE +cert-manager-operator cert-manager 1.14.5 stable ✓ Healthy cert-manager +argocd-operator argocd-operator 0.11.0 alpha ✓ Healthy argocd +prometheus-operator prometheus 0.68.0 beta ⚠ Degraded monitoring +strimzi-kafka-operator strimzi-kafka-operator 0.40.0 stable ✓ Healthy kafka + +Total: 4 extensions (3 healthy, 1 degraded) + +Issues detected: +- prometheus-operator: CRD validation warnings (use /olmv1:status for details) +``` diff --git a/plugins/olmv1/commands/search.md b/plugins/olmv1/commands/search.md new file mode 100644 index 0000000..ea70d6c --- /dev/null +++ b/plugins/olmv1/commands/search.md @@ -0,0 +1,127 @@ +# Search Extensions Command + +You are helping the user discover available extensions across catalogs. + +## Task + +Search for extensions matching the provided keyword across available catalogs using the catalogd service API. + +## Prerequisites + +- Verify `jq` is installed (required for JSON parsing) +- Port-forwarding access to the catalogd-service in olmv1-system namespace + +## Steps + +1. **Verify catalogs are available**: + ```bash + kubectl get clustercatalogs + ``` + +2. **Determine which catalogs to search**: + - If `--catalog` flag provided: Search only that catalog + - Otherwise: Search all available catalogs + +3. **Set up port forwarding to catalogd service**: + ```bash + kubectl -n olmv1-system port-forward svc/catalogd-service 8443:443 & + PORT_FORWARD_PID=$! + sleep 2 # Give port-forward time to establish + ``` + +4. **Query catalog(s) for matching packages**: + For each catalog to search: + ```bash + # Fetch all catalog data and filter for matching packages + curl -sk https://localhost:8443/catalogs//api/v1/all | \ + jq -s --arg keyword "" '.[] | + select(.schema == "olm.package") | + select(.name | test($keyword; "i"))' + ``` + +5. **Get package details**: + For each matching package, gather: + - Package name + - Description + - Default channel + - Available channels (query olm.channel schema) + - Latest version from default channel + + ```bash + # Get channels for a package + curl -sk https://localhost:8443/catalogs//api/v1/all | \ + jq -s --arg pkg "" '.[] | + select(.schema == "olm.channel") | + select(.package == $pkg) | + {name: .name, entries: .entries}' + + # Get bundles for a package + curl -sk https://localhost:8443/catalogs//api/v1/all | \ + jq -s --arg pkg "" '.[] | + select(.schema == "olm.bundle") | + select(.package == $pkg)' + ``` + +6. **Clean up port forwarding**: + ```bash + kill $PORT_FORWARD_PID + ``` + +7. **Format results**: + For each matching extension show: + - Name + - Description (from package metadata) + - Default channel (from package metadata) + - Available channels (from channel query) + - Source catalog + - Latest version (from default channel entries) + +8. **Provide installation hints**: + Show example install command for found extensions. + +## Error Handling + +- If no catalogs exist, suggest adding one first with `/olmv1:catalog-add` +- If keyword matches nothing, suggest broader search terms +- If catalog specified doesn't exist, list available catalogs +- If `jq` is not installed, provide installation instructions +- If port-forwarding fails, check olmv1-system namespace and catalogd-service existence +- If catalog is not ready/unpacked, show catalog status and suggest waiting + +## Implementation Notes + +- Use `-k` flag with curl to skip TLS verification (catalogd uses self-signed cert) +- The catalog API endpoint format is: `https://localhost:8443/catalogs//api/v1/all` +- Three main schemas to query: + - `olm.package`: Package metadata and default channel + - `olm.channel`: Channel information and version entries + - `olm.bundle`: Bundle/version details +- Port forwarding runs in background; ensure cleanup even on errors + +## Example Output + +``` +Found 3 extensions matching "cert-manager": + +1. cert-manager-operator + Description: Certificate management for Kubernetes + Catalog: operatorhubio + Default Channel: stable + Available Channels: stable, candidate + Latest Version: 1.14.5 + +2. openshift-cert-manager-operator + Description: OpenShift certificate management + Catalog: certified + Default Channel: stable-v1 + Latest Version: 1.13.0 + +3. cert-manager-community + Description: Community cert-manager operator + Catalog: community-operators + Default Channel: alpha + Latest Version: 1.15.0-alpha.1 + +Install example: +/olmv1:install cert-manager-operator --channel stable +``` diff --git a/plugins/olmv1/commands/status.md b/plugins/olmv1/commands/status.md new file mode 100644 index 0000000..fd5cb54 --- /dev/null +++ b/plugins/olmv1/commands/status.md @@ -0,0 +1,251 @@ +# Extension Status Command + +You are helping the user get detailed status information for an installed extension. + +## Task + +Provide comprehensive health and status information for a specific extension. + +## Steps + +1. **Check operator-controller feature gates**: + + Check current feature gates to understand enabled capabilities: + + ```bash + kubectl get deployment operator-controller-controller-manager -n olmv1-system \ + -o jsonpath='{.spec.template.spec.containers[0].args}' | jq -r '.[]' | grep feature-gates + ``` + + Report on feature gate status: + - **WebhookProviderCertManager**: Webhook support via cert-manager + - **WebhookProviderOpenshiftServiceCA**: Webhook support via OpenShift service CA + - **PreflightPermissions**: RBAC preflight validation (provides detailed permission errors) + +2. **Verify extension exists**: + ```bash + kubectl get clusterextension + ``` + +3. **Get detailed status**: + ```bash + kubectl get clusterextension -o yaml + ``` + +4. **Parse status information**: + - Installation phase (Installed, Progressing, Failed) + - Resolved version and channel + - Status conditions and messages + - Installation timestamp + - **Check for webhook errors**: Look for "webhookDefinitions are not supported" in condition messages + - **Check for RBAC/preflight permission errors**: Look for "pre-authorization failed" in condition messages + +5. **Check associated resources**: + ```bash + # Get CRDs created by this extension + kubectl get crds -l olm.operatorframework.io/owner-name= + + # Get extension namespace and resources + kubectl get all -n + + # Get deployment status + kubectl get deployments -n + ``` + +6. **Check for recent events**: + ```bash + kubectl get events -n --sort-by='.lastTimestamp' + ``` + +7. **Analyze health**: + - All pods running and ready + - No crash loops or errors + - CRDs properly installed + - Service endpoints available + - Webhooks configured if needed + +8. **Identify webhook issues if present**: + + Check for webhook-related errors: + ```bash + kubectl get clusterextension -o jsonpath='{.status.conditions}' | \ + jq -r '.[] | select(.message | contains("webhookDefinitions")) | .message' + ``` + + If found: + - Check current feature gates (see step 1) + - Verify cert-manager is installed + - Suggest enabling WebhookProviderCertManager feature gate + - May automatically enable if cert-manager is available + +9. **Identify RBAC/permission issues if present**: + + Check specifically for pre-authorization failures: + ```bash + kubectl get clusterextension -o jsonpath='{.status.conditions}' | \ + jq -r '.[] | select(.message | contains("pre-authorization failed")) | .message' + ``` + + If found: + - Extract and display the missing permissions in a readable format + - Identify the ServiceAccount and current RBAC configuration + - Suggest using `/olmv1:fix-rbac ` to automatically fix the issues + +10. **Report comprehensive status**: + - Overall health summary + - Feature gate status (webhook support, preflight permissions) + - Version and channel information + - ServiceAccount and RBAC status + - Resource details + - Any warnings or errors (especially webhook and RBAC-related) + - Suggested actions if unhealthy + +## Error Handling + +- Extension not found: List available extensions +- Namespace not accessible: Check RBAC permissions +- Incomplete installation: Suggest troubleshooting steps +- **Webhook errors detected**: + - Check if WebhookProviderCertManager or WebhookProviderOpenshiftServiceCA is enabled + - Verify cert-manager installation status + - Suggest enabling feature gate via kubectl patch + - May automatically enable if cert-manager is present (command is in allow-list) +- **RBAC/Pre-authorization errors detected**: + - Display the missing permissions clearly + - Show current ServiceAccount configuration + - Suggest running `/olmv1:fix-rbac ` to resolve + - Explain that PreflightPermissions feature gate must be enabled for detailed checks + - Note: Without PreflightPermissions, RBAC errors may only appear as generic installation failures + +## Example Output + +``` +Status: cert-manager-operator + +Overall Health: ✓ Healthy +Installation Status: Installed +Installed Version: 1.14.5 +Channel: stable +Catalog Source: operatorhubio +Namespace: cert-manager +Installed At: 2025-10-28T09:30:00Z + +Conditions: +✓ Installed: True (Last transition: 2025-10-28T09:32:15Z) +✓ Resolved: True (Resolved to version 1.14.5) + +Custom Resource Definitions (3): +✓ certificates.cert-manager.io +✓ issuers.cert-manager.io +✓ clusterissuers.cert-manager.io + +Workload Status: +Deployment: cert-manager-controller + ✓ 1/1 pods ready + ✓ Last updated: 2025-10-28T09:31:30Z + +Deployment: cert-manager-webhook + ✓ 1/1 pods ready + +Deployment: cert-manager-cainjector + ✓ 1/1 pods ready + +Recent Events: +- Successfully reconciled ClusterExtension (2 minutes ago) +- All deployments scaled to desired replicas (3 minutes ago) + +No issues detected. Extension is operating normally. +``` + +### With RBAC/Permission Issues + +``` +Status: postgres-operator + +Overall Health: ⚠ Installation Blocked +Installation Status: Progressing (Retrying) +Channel: stable +Catalog Source: operatorhubio +Namespace: postgres-operator +ServiceAccount: postgres-operator-sa + +Conditions: +⚠ Progressing: True (Reason: Retrying) + Message: pre-authorization failed: service account requires the following permissions to manage cluster extension: + Namespace:"" APIGroups:[] Resources:[persistentvolumeclaims] Verbs:[create,delete] + Namespace:"" APIGroups:[apps] Resources:[statefulsets] Verbs:[create,update] + +✗ Installed: False + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +⚠ RBAC Permission Issues Detected + +Missing permissions for ServiceAccount "postgres-operator-sa": + +Cluster-scoped: +1. Core API: persistentvolumeclaims [create, delete] +2. apps API: statefulsets [create, update] + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Current RBAC Configuration: +- ServiceAccount: postgres-operator-sa (namespace: postgres-operator) +- ClusterRole: postgres-operator-installer (missing required permissions) + +Recommended Action: +Run the following command to automatically fix RBAC permissions: + /olmv1:fix-rbac postgres-operator + +Or manually update the ClusterRole to include the missing permissions. +Once fixed, the operator-controller will automatically retry installation. +``` + +### With Webhook Issues + +``` +Status: cloudnative-pg + +Overall Health: ⚠ Installation Blocked - Webhook Support Required +Installation Status: Progressing (Retrying) +Channel: stable +Catalog Source: operatorhubio +Namespace: cloudnative-pg +ServiceAccount: cloudnative-pg-sa + +OLM v1 Feature Gates: +⚠ WebhookProviderCertManager: Not Enabled +✓ cert-manager: Installed and ready + +Conditions: +⚠ Progressing: True (Reason: Retrying) + Message: error for resolved bundle "cloudnative-pg.v1.27.1" with version "1.27.1": + unsupported bundle: webhookDefinitions are not supported + +✗ Installed: False + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +⚠ Webhook Support Required + +This operator requires webhook support, but the WebhookProviderCertManager +feature gate is not enabled on operator-controller. + +cert-manager is installed and available, so webhook support can be enabled. + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Recommended Action: +Enable the WebhookProviderCertManager feature gate with: + + kubectl patch deployment operator-controller-controller-manager -n olmv1-system --type=json \ + -p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", + "value": "--feature-gates=WebhookProviderCertManager=true"}]' + +Then wait for rollout: + kubectl rollout status deployment operator-controller-controller-manager -n olmv1-system + +After enabling, trigger reconciliation: + kubectl annotate clusterextension cloudnative-pg reconcile="$(date +%s)" --overwrite +``` + diff --git a/plugins/olmv1/commands/uninstall.md b/plugins/olmv1/commands/uninstall.md new file mode 100644 index 0000000..f8920a9 --- /dev/null +++ b/plugins/olmv1/commands/uninstall.md @@ -0,0 +1,109 @@ +# Uninstall Extension Command + +You are helping the user safely remove an installed extension from their cluster. + +## Task + +Uninstall an extension and clean up associated resources. + +## Steps + +1. **Verify extension exists**: + ```bash + kubectl get clusterextension + ``` + +2. **Check for dependent resources**: + - List custom resources created by this extension + - Warn about data loss if CRs exist + - Get user confirmation before proceeding + +3. **Show what will be removed**: + ```bash + # Show CRDs + kubectl get crds -l olm.operatorframework.io/owner-name= + + # Show namespace resources + kubectl get all -n + ``` + +4. **Request confirmation**: + Ask user to confirm uninstallation with awareness of: + - CRDs that will be removed + - Custom resources that will be deleted + - Namespaces that may be cleaned up + +5. **Delete custom resources** (if requested): + ```bash + # Delete all CRs for each CRD + kubectl delete --all --all-namespaces + ``` + +6. **Delete ClusterExtension**: + ```bash + kubectl delete clusterextension + ``` + +7. **Verify removal**: + ```bash + kubectl get clusterextension # Should not exist + kubectl get crds -l olm.operatorframework.io/owner-name= # Should be empty + ``` + +8. **Clean up namespace** (if empty and created by extension): + ```bash + kubectl delete namespace + ``` + +9. **Report results**: + - Confirmation of deletion + - List of removed resources + - Any manual cleanup steps required + +## Safety Checks + +- WARNING: Uninstalling will remove CRDs and all custom resources +- Dependency Check: Look for resources in other namespaces using this extension +- Confirmation Required: Always require explicit user confirmation +- Backup Suggestion: Suggest backing up custom resources before deletion + +## Error Handling + +- Extension not found: List available extensions +- Deletion blocked: Check for finalizers or dependent resources +- RBAC errors: Suggest required permissions +- Partial deletion: Report what was deleted and what remains + +## Example Output + +``` +Preparing to uninstall: cert-manager-operator + +The following resources will be removed: + +Custom Resource Definitions (3): +- certificates.cert-manager.io (15 instances found) +- issuers.cert-manager.io (8 instances found) +- clusterissuers.cert-manager.io (2 instances found) + +Namespace: cert-manager +Deployments: 3 +Pods: 3 +Services: 2 + +WARNING: This will delete all Certificate, Issuer, and ClusterIssuer resources! + +Do you want to proceed with uninstallation? (y/N): y + +Uninstalling... +✓ Deleted 15 Certificates +✓ Deleted 8 Issuers +✓ Deleted 2 ClusterIssuers +✓ Deleted ClusterExtension: cert-manager-operator +✓ Removed CRDs +✓ Deleted namespace: cert-manager + +Uninstallation complete. + +cert-manager-operator has been successfully removed from the cluster. +``` diff --git a/plugins/olmv1/commands/upgrade.md b/plugins/olmv1/commands/upgrade.md new file mode 100644 index 0000000..e3d7ca0 --- /dev/null +++ b/plugins/olmv1/commands/upgrade.md @@ -0,0 +1,132 @@ +# Upgrade Extension Command + +You are helping the user upgrade an installed extension using OLM v1. + +## Task + +Upgrade an extension to a new version or channel using various upgrade strategies. + +## Steps + +1. **Verify extension is installed**: + ```bash + kubectl get clusterextension + ``` + +2. **Get current version/channel**: + ```bash + kubectl get clusterextension -o jsonpath='{.status.resolution}' + ``` + +3. **Determine upgrade strategy**: + - **Channel-based**: Switch or update to latest in channel + - **Version-specific**: Upgrade to exact version + - **Version range**: Update version constraint range + - **Z-stream**: Stay within minor version (e.g., ~1.14.0) + +4. **Validate upgrade path**: + - Check if target version/channel exists + - Verify upgrade is supported (no major version skips if restricted) + - Check for breaking changes + +5. **Update ClusterExtension**: + ```bash + kubectl patch clusterextension --type=merge -p ' + spec: + source: + catalog: + version: "" + channel: "" + ' + ``` + +6. **Monitor upgrade process**: + ```bash + kubectl get clusterextension -w + ``` + +7. **Verify upgrade completion**: + - Check new version is installed + - Verify all pods are ready + - Check for any errors or warnings + +8. **Report results**: + - Old version → New version + - Upgrade status + - Any required manual steps + - Rollback instructions if needed + +## Upgrade Strategies + +### Channel-Based Upgrade +```yaml +spec: + source: + catalog: + channel: "stable-v2" # Switch to new channel +``` + +### Version Pinning +```yaml +spec: + source: + catalog: + version: "2.0.0" # Exact version +``` + +### Version Range +```yaml +spec: + source: + catalog: + version: ">=2.0.0 <3.0.0" # Allow minor updates +``` + +### Z-Stream Upgrade +```yaml +spec: + source: + catalog: + version: "~1.14.0" # Stay in 1.14.x +``` + +## Error Handling + +- Extension not found: Confirm extension name +- Version doesn't exist: Show available versions +- Upgrade forbidden: Check upgrade constraints +- Upgrade failed: Parse error and suggest rollback +- Breaking changes: Warn user and require confirmation + +## Example Output + +``` +Upgrading cert-manager-operator... + +Current State: + Version: 1.14.5 + Channel: stable + +Target State: + Version: 1.15.0 + Channel: stable + +✓ Validated upgrade path +✓ Updated ClusterExtension resource +✓ Waiting for upgrade to complete... +✓ Upgrade completed successfully + +Upgraded: cert-manager-operator +Previous Version: 1.14.5 +New Version: 1.15.0 +Upgraded At: 2025-10-28T10:45:00Z + +Changes: +- Updated CRD: certificates.cert-manager.io (v1beta1 → v1) +- New feature: Enhanced ACME support +- All pods restarted and healthy + +Next steps: +- Verify functionality: /olmv1:status cert-manager-operator +- Rollback if needed: /olmv1:upgrade cert-manager-operator --version 1.14.5 +```