### Gherkin Example: Install ClusterExtension

Source: https://github.com/operator-framework/operator-controller/blob/main/test/e2e/README.md

An example Gherkin scenario demonstrating the installation of a ClusterExtension, including prerequisites and expected outcomes.

```gherkin
Feature: Install ClusterExtension

  Background:
    Given OLM is available
    And "test" catalog serves bundles
    And Service account "olm-sa" with needed permissions is available in test namespace

  Scenario: Install latest available version from the default channel
    When ClusterExtension is applied
      """
      apiVersion: olm.operatorframework.io/v1
      kind: ClusterExtension
      metadata:
        name: ${NAME}
      spec:
        namespace: ${TEST_NAMESPACE}
        serviceAccount:
          name: olm-sa
        source:
          sourceType: Catalog
          catalog:
            packageName: test
            selector:
              matchLabels:
                "olm.operatorframework.io/metadata.name": test-catalog
        ...
      """
    Then ClusterExtension is rolled out
    And ClusterExtension is available
```

--------------------------------

### Example Output of Successful Installation

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/tutorials/install-extension.md

This is an example of the output you can expect after successfully applying the ClusterExtension CR, indicating that the extension has been created.

```text
clusterextension.olm.operatorframework.io/argocd created
```

--------------------------------

### Verify Installed Tools Versions

Source: https://github.com/operator-framework/operator-controller/blob/main/dev/podman/setup-local-env-podman.md

Check the installed versions of Podman, Kind, and Tilt. Install them if they are not present.

```sh
$ podman --version
podman version 5.0.1
$ kind version
kind v0.26.0 go1.23.4 linux/amd64
$ tilt version
v0.33.15, built 2024-05-31
```

--------------------------------

### Go: Implementing a Gherkin Step Definition

Source: https://github.com/operator-framework/operator-controller/blob/main/test/e2e/README.md

An example Go function implementing the 'bundle is installed' step. It uses a waitFor function to poll for the bundle status.

```go
func BundleInstalled(ctx context.Context, name, version string) error {
    sc := scenarioCtx(ctx)
    waitFor(ctx, func() bool {
        v, err := kubectl("get", "clusterextension", sc.clusterExtensionName, "-o", "jsonpath={.status.install.bundle}")
        if err != nil {
          return false
        }
        var bundle map[string]interface{}
        json.Unmarshal([]byte(v), &bundle)
        return bundle["name"] == name && bundle["version"] == version
    })
    return nil
}
```

--------------------------------

### Claude Assistant - Local Dev Env Setup Prompt

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/contribute/developer.md

This is an example of a user prompt to an AI assistant (Claude) requesting help with setting up a local development environment for the OLM v1 project.

```text
> Can you help me set up a local dev environment?

● I'll help you set up the local development environment for this OLM v1 project. Since this project has a specialized sub-agent for
  local development setup, I'll use that to guide you through the complete process.
```

--------------------------------

### Start Rootless Podman Socket

Source: https://github.com/operator-framework/operator-controller/blob/main/dev/podman/setup-local-env-podman.md

Start the rootless Podman socket to enable Tilt to connect to it for image builds. Enable it to start automatically in your user session.

```sh
podman --user start podman.socket
systemctl --user enable --now podman.socket
```

--------------------------------

### Inspect Bundle Install Modes with opm

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/draft/howto/configure-bundles.md

Use `opm render` and `jq` to query a bundle image for its supported install modes. Ensure `opm` and `jq` are installed and replace `<bundle-image>` with your target image.

```bash
opm render <bundle-image> -o json | \
jq 'select(.schema == "olm.bundle") | .properties[] | select(.type == "olm.csv") | .value.spec.installModes'
```

--------------------------------

### Example Output of `kubectl get clustercatalog`

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/tutorials/add-catalog.md

This is an example of the output you might see when listing ClusterCatalogs, showing the catalog name, last unpacked time, serving status, and age.

```text
NAME            LASTUNPACKED   SERVING   AGE
operatorhubio   18s            True      27s
```

--------------------------------

### Generate Installation Manifests

Source: https://github.com/operator-framework/operator-controller/blob/main/hack/tools/catalogs/README.md

Generates fully rendered installation manifests for a specified bundle from a catalog. Use this when you need ready-to-apply manifests.

```terminal
./generate-manifests install argocd-operator 0.6.0 < operatorhubio-catalog.json
```

--------------------------------

### Claude Assistant - Operator Controller Dev Env Setup Prompt

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/contribute/developer.md

This is an example of a user prompt to an AI assistant (Claude) requesting help with setting up a local development environment specifically for the operator-controller project.

```text
> I need help setting up a local dev env

● I'll help you set up a local development environment for the operator-controller project. Since this involves setting up a complete
  development environment with multiple components, I'll use the specialized OLM development environment agent to guide you through the
  process.
```

--------------------------------

### Example Output After Deletion

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/tutorials/uninstall-extension.md

This is an example of the output you might see when verifying an extension's deletion, indicating no resources were found.

```text
No resources found
```

--------------------------------

### Configure ClusterExtension for SingleNamespace Install Mode

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/draft/howto/single-ownnamespace-install.md

Example of configuring a ClusterExtension to use the SingleNamespace install mode. The `watchNamespace` is set to a different namespace than the install namespace.

```yaml
apiVersion: olm.operatorframework.io/v1
kind: ClusterExtension
metadata:
  name: argocd
spec:
  namespace: argocd
  serviceAccount:
    name: argocd-installer
  config:
    inline:
      watchNamespace: argocd-watch
  source:
    sourceType: Catalog
    catalog:
      packageName: argocd-operator
      version: 0.2.1 # Update to version 0.2.1
```

--------------------------------

### Complete ClusterExtension Example

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/draft/howto/customize-operator-deployments.md

This example demonstrates a wide range of configuration options for a ClusterExtension, including deployment settings, resource management, environment variables, volumes, and affinity rules. Use this as a template for complex operator deployments.

```yaml
apiVersion: olm.operatorframework.io/v1
kind: ClusterExtension
metadata:
  name: production-operator
spec:
  namespace: production-operators
  serviceAccount:
    name: production-operator-installer
  source:
    sourceType: Catalog
    catalog:
      packageName: production-operator
      version: 1.2.3
  config:
    inline:
      # Combined with deploymentConfig for operators that support namespace scoping
      watchNamespace: "production-workloads"

      deploymentConfig:
        # Schedule on dedicated operator nodes
        nodeSelector:
          node-role.kubernetes.io/operator: ""

        # Tolerate the operator node taint
        tolerations:
          - key: "node-role.kubernetes.io/operator"
            operator: "Exists"
            effect: "NoSchedule"

        # Set resource requirements
        resources:
          requests:
            memory: "512Mi"
            cpu: "250m"
          limits:
            memory: "1Gi"
            cpu: "500m"

        # Configure environment
        env:
          - name: LOG_LEVEL
            value: "info"
          - name: ENABLE_METRICS
            value: "true"
          - name: METRICS_PORT
            value: "8080"
        envFrom:
          - secretRef:
              name: operator-credentials

        # Add cache volume
        volumes:
          - name: operator-cache
            emptyDir:
              sizeLimit: 2Gi
        volumeMounts:
          - name: operator-cache
            mountPath: /var/cache/operator

        # Add monitoring annotations
        annotations:
          prometheus.io/scrape: "true"
          prometheus.io/port: "8080"
          prometheus.io/path: "/metrics"

        # Prefer spreading across zones
        affinity:
          podAntiAffinity:
            preferredDuringSchedulingIgnoredDuringExecution:
              - weight: 100
                podAffinityTerm:
                  labelSelector:
                    matchLabels:
                      olm.operatorframework.io/owner-kind: ClusterExtension
                      olm.operatorframework.io/owner-name: production-operator
                  topologyKey: topology.kubernetes.io/zone

```

--------------------------------

### Start Tilt with Podman

Source: https://github.com/operator-framework/operator-controller/blob/main/dev/podman/setup-local-env-podman.md

Run Tilt with Podman as the container engine. Set DOCKER_BUILDKIT=0 to ensure compatibility.

```sh
DOCKER_BUILDKIT=0 tilt up
```

--------------------------------

### Example Output of Cluster Extension Description

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/tutorials/install-extension.md

This is an example of the output you can expect when describing a cluster extension, showing its status and configuration.

```text
Name:         argocd
Namespace:
Labels:       <none>
Annotations:  <none>
API Version:  olm.operatorframework.io/v1
Kind:         ClusterExtension
Metadata:
  Creation Timestamp:  2024-11-11T13:41:23Z
  Finalizers:
    olm.operatorframework.io/cleanup-unpack-cache
    olm.operatorframework.io/cleanup-contentmanager-cache
  Generation:        1
  Resource Version:  5426
  UID:               bde55f03-abe2-48af-8c09-28d32df878ad
Spec:
  Namespace:  argocd
  Service Account:
    Name:  argocd-installer
  Source:
    Catalog:
      Package Name:               argocd-operator
      Upgrade Constraint Policy:  CatalogProvided
      Version:                    0.6.0
    Source Type:                  Catalog
Status:
  Conditions:
    Last Transition Time:  2024-11-11T13:41:23Z
    Message:
    Observed Generation:   1
    Reason:                Deprecated
    Status:                False
    Type:                  Deprecated
    Last Transition Time:  2024-11-11T13:41:23Z
    Message:
    Observed Generation:   1
    Reason:                Deprecated
    Status:                False
    Type:                  PackageDeprecated
    Last Transition Time:  2024-11-11T13:41:23Z
    Message:
    Observed Generation:   1
    Reason:                Deprecated
    Status:                False
    Type:                  ChannelDeprecated
    Last Transition Time:  2024-11-11T13:41:23Z
    Message:
    Observed Generation:   1
    Reason:                Deprecated
    Status:                False
    Type:                  BundleDeprecated
    Last Transition Time:  2024-11-11T13:41:31Z
    Message:               Installed bundle quay.io/operatorhubio/argocd-operator@sha256:d538c45a813b38ef0e44f40d279dc2653f97ca901fb660da5d7fe499d51ad3b3 successfully
    Observed Generation:   1
    Reason:                Succeeded
    Status:                True
    Type:                  Installed
    Last Transition Time:  2024-11-11T13:41:32Z
    Message:               desired state reached
    Observed Generation:   1
    Reason:                Succeeded
    Status:                True
    Type:                  Progressing
  Install:
    Bundle:
      Name:     argocd-operator.v0.6.0
      Version:  0.6.0
Events:         <none>
```

--------------------------------

### Example Output of `kubectl describe clustercatalog`

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/tutorials/add-catalog.md

This example output details the status of the 'operatorhubio' ClusterCatalog, including its conditions, last unpacked time, resolved source, and serving URL.

```text
Name:         operatorhubio
Namespace:
Labels:       olm.operatorframework.io/metadata.name=operatorhubio
Annotations:  <none>
API Version:  olm.operatorframework.io/v1
Kind:         ClusterCatalog
Metadata:
  Creation Timestamp:  2024-11-13T15:11:08Z
  Finalizers:
    olm.operatorframework.io/delete-server-cache
  Generation:        1
  Resource Version:  3069
  UID:               2c94ebf8-32ea-4a62-811a-c7098cd2d4db
Spec:
  Availability Mode:  Available
  Priority:           0
  Source:
    Image:
      Poll Interval Minutes:  10
      Ref:                    quay.io/operatorhubio/catalog:latest
    Type:                     Image
Status:
  Conditions:
    Last Transition Time:  2024-11-13T15:11:19Z
    Message:               Successfully unpacked and stored content from resolved source
    Observed Generation:   1
    Reason:                Succeeded
    Status:                True
    Type:                  Progressing
    Last Transition Time:  2024-11-13T15:11:19Z
    Message:               Serving desired content from resolved source
    Observed Generation:   1
    Reason:                Available
    Status:                True
    Type:                  Serving
  Last Unpacked:           2024-11-13T15:11:18Z
  Resolved Source:
    Image:
      Ref:  quay.io/operatorhubio/catalog@sha256:3cd8fde1dfd4269467451c4b2c77d4196b427004f2eb82686376f28265655c1c
    Type:   Image
  Urls:
    Base:  https://catalogd-service.olmv1-system.svc/catalogs/operatorhubio
Events:    <none>
```

--------------------------------

### Pagination Example

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/draft/howto/catalog-queries-graphql-endpoint.md

Demonstrates how to use `limit` and `offset` arguments for paginating results, shown here with `olmbundles`.

```APIDOC
## Pagination

### Description
All schema-based queries support pagination via `limit` and `offset` arguments.

### Method
POST

### Endpoint
`https://localhost:8443/catalogs/operatorhubio/api/v1/graphql`

### Request Body
```json
{
  "query": "{ olmbundles(limit: 10, offset: 20) { name } }"
}
```

### Response Example
```json
{
  "data": {
    "olmbundles": [
      {
        "name": "bundle-name-21"
      }
    ]
  }
}
```
```

--------------------------------

### Tilt Build Failure Example

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/contribute/developer.md

This is an example of an error message you might encounter when Tilt fails to build an image, particularly when using Podman without the necessary workaround.

```text
Build Failed: ImageBuild: stat /var/tmp/libpod_builder2384046170/build/Dockerfile: no such file or directory
```

--------------------------------

### List Packages Supporting AllNamespaces Install Mode Without Webhooks

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/draft/tutorials/explore-available-content-metas-endpoint.md

Filter extensions to find those supporting the 'AllNamespaces' install mode, do not use webhooks, and whose channel head version uses the 'olm.csv.metadata' format. This query helps identify suitable extensions for cluster-wide, non-webhook installations.

```bash
curl -k https://localhost:8443/catalogs/operatorhubio/api/v1/metas?schema=olm.bundle | jq -cs '[.[] | select(.properties[] | select(.type == "olm.csv.metadata").value.installModes[] | select(.type == "AllNamespaces" and .supported == true) and .spec.webhookdefinitions == null) | .package] | unique[]'
```

--------------------------------

### Example FBC Snippet

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/api-reference/catalogd-webserver.md

This example shows the structure of File-Based Catalog (FBC) objects that are part of the catalogd web server's response.

```json
{
    "schema": "olm.package",
    "name": "cockroachdb",
    "defaultChannel": "stable-v6.x",
}
{
    "schema": "olm.channel",
    "name": "stable-v6.x",
    "package": "cockroachdb",
    "entries": [
        {
            "name": "cockroachdb.v6.0.0",
            "skipRange": "<6.0.0"
        }
    ]
}
{
    "schema": "olm.bundle",
    "name": "cockroachdb.v6.0.0",
    "package": "cockroachdb",
    "image": "quay.io/openshift-community-operators/cockroachdb@sha256:d3016b1507515fc7712f9c47fd9082baf9ccb070aaab58ed0ef6e5abdedde8ba",
    "properties": [
        {
            "type": "olm.package",
            "value": {
                "packageName": "cockroachdb",
                "version": "6.0.0"
            }
        },
    ],
}
```

--------------------------------

### Install Podman Mac Helper

Source: https://github.com/operator-framework/operator-controller/blob/main/dev/podman/setup-local-env-podman.md

On MacOS, install the podman-mac-helper utility. This is often required for Podman to function correctly.

```sh
sudo podman-mac-helper install
podman machine stop/start
```

--------------------------------

### Example Extension Metadata Output

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/draft/tutorials/explore-available-content-metas-endpoint.md

This is an example of the JSON output when inspecting the metadata of an extension package like 'cockroachdb'. It shows the default channel, icon details, package name, and schema.

```json
{
  "defaultChannel": "stable-v6.x",
  "icon": {
    "base64data": "PHN2ZyB4bWxucz0ia...",
    "mediatype": "image/svg+xml"
  },
  "name": "cockroachdb",
  "schema": "olm.package"
}
```

--------------------------------

### Minimal ClusterCatalogSpec Example

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/api-reference/olmv1-api-reference.md

This example demonstrates a minimal ClusterCatalogSpec that sources a catalog from an image. It specifies the image reference for the catalog.

```yaml
source:
  type: Image
  image:
    ref: quay.io/operatorhubio/catalog:latest
```

--------------------------------

### Example Output of Deletion

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/tutorials/uninstall-extension.md

This is an example of the output you might see after successfully deleting an extension's CR.

```text
clusterextension.olm.operatorframework.io "argocd" deleted
```

--------------------------------

### Get First 10 Packages

Source: https://github.com/operator-framework/operator-controller/blob/main/internal/catalogd/graphql/sample-queries.txt

Fetch the first 10 packages from the catalog, including their name, default channel, icon, and description.

```graphql
{
  olmpackages(limit: 10) {
    name
    defaultChannel
    icon
    description
  }
}
```

--------------------------------

### Sample GraphQL Queries

Source: https://github.com/operator-framework/operator-controller/blob/main/internal/catalogd/graphql/README.md

Examples of common GraphQL queries that can be executed against the catalog data.

```APIDOC
## Sample Queries

### Get catalog summary
```graphql
{
  summary {
    totalSchemas
    schemas {
      name
      totalObjects
      totalFields
    }
  }
}
```

### Get bundles with pagination
```graphql
{
  olmbundles(limit: 5, offset: 0) {
    name
    package
    version
  }
}
```

### Get packages
```graphql
{
  olmpackages(limit: 10) {
    name
    description
  }
}
```

### Get channels
```graphql
{
  olmchannels(limit: 10) {
    name
    package
    entries
  }
}
```
```

--------------------------------

### Install Homebrew Tools on MacOS

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/contribute/developer.md

Installs essential command-line tools required for development on MacOS using Homebrew.

```shell
brew install bash gnu-tar gsed coreutils
```

--------------------------------

### Apply Custom Resource Definitions

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/contribute/developer.md

Applies the sample custom resources to your cluster as part of the manual installation process.

```sh
kubectl apply -f config/samples/
```

--------------------------------

### Generate Templated Installation Manifests

Source: https://github.com/operator-framework/operator-controller/blob/main/hack/tools/catalogs/README.md

Generates templated installation manifests for a specified bundle. Use the --template flag when you need to customize manifests before applying them to the cluster.

```terminal
generate-manifests install argocd-operator 0.6.0 --template < operatorhubio-catalog.json
```

--------------------------------

### Wait for Rollout to Complete

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/draft/howto/enable-webhook-support.md

After starting the controller, verify that the rollout of the operator-controller deployment has completed successfully in the olmv1-system namespace.

```bash
kubectl rollout status -n olmv1-system deployment/operator-controller-controller-manager
```

--------------------------------

### Install Cluster Extension

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/getting-started/olmv1_getting_started.md

Applies a sample ClusterExtension manifest to install the ArgoCD operator. The manifest includes necessary resources like namespace and service account.

```bash
kubectl apply -f https://raw.githubusercontent.com/operator-framework/operator-controller/main/config/samples/olm_v1_clusterextension.yaml
```

--------------------------------

### Describe Cluster Extensions

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/tutorials/install-extension.md

Use this command to describe the installed cluster extensions and view their details.

```bash
kubectl describe clusterextensions
```

--------------------------------

### Filter Packages by Install Mode and Webhooks

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/draft/howto/catalog-queries-metas-endpoint.md

Filter packages to find those supporting 'AllNamespaces' install mode and not using webhooks. This uses jq to process the output from a catalog query.

```jq
jq -cs '[.[] | select(.schema == "olm.bundle" and (.properties[] | select(.type == "olm.csv.metadata").value.installModes[] | select(.type == "AllNamespaces" and .supported == true)) and .spec.webhookdefinitions == null) | .package] | unique[]'
```

--------------------------------

### Get First 10 Packages

Source: https://github.com/operator-framework/operator-controller/blob/main/internal/catalogd/graphql/sample-queries.txt

Retrieves the first 10 packages from the catalog, including their name, default channel, icon, and description.

```APIDOC
## GraphQL Query: First 10 Packages

### Description
Fetches the first 10 available packages in the catalog, providing basic information for each.

### Query
```graphql
{
  olmpackages(limit: 10) {
    name
    defaultChannel
    icon
    description
  }
}
```

### Response Example (Success)
```json
{
  "data": {
    "olmpackages": [
      {
        "name": "prometheus",
        "defaultChannel": "stable",
        "icon": "https://example.com/icon.png",
        "description": "A monitoring system."
      }
    ]
  }
}
```
```

--------------------------------

### OLM v0 Subscription Configuration

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/draft/howto/customize-operator-deployments.md

Example of a Subscription configuration in OLM v0, including environment variables and resource requests.

```yaml
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: my-operator
  namespace: operators
spec:
  channel: stable
  name: my-operator
  source: operatorhubio-catalog
  sourceNamespace: olm
  config:
    env:
      - name: LOG_LEVEL
        value: "debug"
    resources:
      requests:
        memory: "256Mi"
        cpu: "100m"
```

--------------------------------

### Set up Persistent Experimental E2E Cluster

Source: https://github.com/operator-framework/operator-controller/blob/main/test/e2e/README.md

Builds images, creates a KIND cluster, deploys OLM, and waits for readiness for experimental features. This setup persists until explicitly torn down.

```bash
make experimental-e2e-setup
```

--------------------------------

### Configure ClusterExtension for OwnNamespace Install Mode

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/draft/howto/single-ownnamespace-install.md

Example of configuring a ClusterExtension to use the OwnNamespace install mode. The `watchNamespace` is set to the same namespace as the install namespace.

```yaml
apiVersion: olm.operatorframework.io/v1
kind: ClusterExtension
metadata:
  name: argocd
spec:
  namespace: argocd
  serviceAccount:
    name: argocd-installer
  config:
    inline:
      watchNamespace: argocd
  source:
    sourceType: Catalog
    catalog:
      packageName: argocd-operator
      version: 0.2.1 # Update to version 0.2.1
```

--------------------------------

### Set up Persistent Standard E2E Cluster

Source: https://github.com/operator-framework/operator-controller/blob/main/test/e2e/README.md

Builds images, creates a KIND cluster, deploys OLM, and waits for readiness for standard features. This setup persists until explicitly torn down.

```bash
make e2e-setup
```

--------------------------------

### E2E Test Isolation Workflow

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/designs/testing/2026-04-13-e2e-isolation/design.md

Illustrates the sequence of operations for setting up E2E test isolation, from scenario start to resource cleanup.

```text
Scenario starts
  -> Generate parameterized bundle manifests (CRD names, deployments, etc. include scenario ID)
  -> Build + push bundle OCI images to e2e registry via go-containerregistry
  -> Generate FBC catalog config referencing those bundle image refs
  -> Build + push catalog OCI image to e2e registry
  -> Create ClusterCatalog pointing at the catalog image
  -> Run scenario steps
  -> Cleanup all resources (including catalog)
```

--------------------------------

### Get ClusterExtension Status

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/tutorials/upgrade-extension.md

Use this command to retrieve the current installation status of a ClusterExtension, specifically showing the installed bundle and version.

```bash
kubectl get clusterextension argocd -o jsonpath-as-json="{.status.install}"
```

--------------------------------

### Basic ClusterExtension with Deployment Configuration

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/draft/howto/customize-operator-deployments.md

This example demonstrates how to specify basic deployment configurations like environment variables and resource requirements within a ClusterExtension resource.

```yaml
apiVersion: olm.operatorframework.io/v1
kind: ClusterExtension
metadata:
  name: my-operator
spec:
  namespace: my-namespace
  serviceAccount:
    name: my-operator-sa
  source:
    sourceType: Catalog
    catalog:
      packageName: my-operator
  config:
    inline:
      deploymentConfig:
        # Add environment variables
        env:
          - name: LOG_LEVEL
            value: "debug"
        # Set resource requirements
        resources:
          requests:
            memory: "256Mi"
            cpu: "100m"
          limits:
            memory: "512Mi"
            cpu: "200m"
```

--------------------------------

### Example ClusterExtension CR Manifest

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/tutorials/install-extension.md

Create a custom resource (CR) manifest for installing a Kubernetes extension. Ensure the ServiceAccount specified has the necessary RBAC permissions for installation and management.

```yaml
apiVersion: olm.operatorframework.io/v1
kind: ClusterExtension
metadata:
  name: <extension_name>
spec:
  namespace: <namespace_name>
  serviceAccount:
    name: <serviceAccount_name>
  source:
    sourceType: Catalog
    catalog:
      packageName: <package_name>
      channels: [<channel1>, <channel2>]
      version: "<version>"
```

--------------------------------

### Start Tilt Development Environment

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/contribute/developer.md

Use this command to initiate the Tilt development server. Tilt will then manage the build, deployment, and update cycle for your containerized applications.

```shell
tilt up
```

--------------------------------

### ConfigMap Permissions for Installer Service Account

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/howto/derive-service-account.md

Grants the installer service account permissions to create, get, list, watch, update, patch, and delete ConfigMaps. This is necessary for managing the configuration for the extension controller.

```yaml
- apiGroups: [""]
  resources: [configmaps]
  verbs: [create]
- apiGroups: [""]
  resources: [configmaps]
  verbs: [get, list, watch, update, patch, delete]
  # scoped to the configmap name
  resourceNames: [argocd-operator-manager-config]
```

--------------------------------

### Service Permissions for Installer Service Account

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/howto/derive-service-account.md

Grants the installer service account permissions to create, get, list, watch, update, patch, and delete Services. This is needed for managing the metrics service for the extension controller.

```yaml
- apiGroups: [""]
  resources: [services]
  verbs: [create]
- apiGroups: [""]
  resources: [services]
  verbs: [get, list, watch, update, patch, delete]
  # scoped to the service name
  resourceNames: [argocd-operator-controller-manager-metrics-service]
```

--------------------------------

### ServiceAccount Permissions for Installer Service Account

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/howto/derive-service-account.md

Grants the installer service account permissions to create, list, watch, get, update, patch, and delete ServiceAccounts. This is required for managing the extension controller's ServiceAccounts.

```yaml
- apiGroups: [""]
  resources: [serviceaccounts]
  verbs: [create, list, watch]
- apiGroups: [""]
  resources: [serviceaccounts]
  verbs: [get, update, patch, delete]
  # scoped to the extension controller's deployment service account
  resourceNames: [argocd-operator-controller-manager]
```

--------------------------------

### Deployment Permissions for Installer Service Account

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/howto/derive-service-account.md

Grants the installer service account permissions to create, get, list, watch, update, patch, and delete Deployments. This is necessary for managing the extension controller's Deployments.

```yaml
- apiGroups: [apps]
  resources: [deployments]
  verbs: [create]
- apiGroups: [apps]
  resources: [deployments]
  verbs: [get, list, watch, update, patch, delete]
  # scoped to the extension controller deployment name
  resourceNames: [argocd-operator-controller-manager]
```

--------------------------------

### Get ClusterExtension Status

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/draft/howto/customize-operator-deployments.md

Retrieve the YAML output of a ClusterExtension to check its status, specifically looking for the 'Installed' condition to be 'True'.

```bash
kubectl get clusterextension my-operator -o yaml
```

--------------------------------

### Quick Start Profiling Workflow

Source: https://github.com/operator-framework/operator-controller/blob/main/hack/tools/test-profiling/README.md

Initiate profiling, run end-to-end tests, stop profiling, and view the analysis report. This sequence is useful for a rapid performance assessment.

```bash
# Start profiling
make start-profiling/baseline

# Run tests
make test-e2e

# Stop and analyze
make stop-profiling

# View report
cat test-profiles/baseline/analysis.md

# Compare runs
./bin/test-profile compare baseline optimized
cat test-profiles/comparisons/baseline-vs-optimized.md
```

--------------------------------

### Get ClusterRoles using kubectl

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/howto/derive-service-account.md

Example command to list ClusterRoles and filter by a specific name pattern. This is useful for identifying generated resource names.

```terminal
kubectl get clusterroles | grep argocd
```

--------------------------------

### Install Latest Operator Controller Release

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/contribute/developer.md

Installs the latest version of Operator Controller into your cluster. This command depends on cert-manager and may affect existing installations.

```bash
curl -L -s https://github.com/operator-framework/operator-controller/releases/latest/download/install.sh | bash -s
```

--------------------------------

### Local Development Commands

Source: https://github.com/operator-framework/operator-controller/blob/main/AGENTS.md

Commands for creating a kind cluster, deploying with standard or experimental manifests, or performing step-by-step setup, and cleaning up.

```bash
# Create kind cluster and deploy
make run                    # Standard manifest
make run-experimental       # Experimental manifest
```

```bash
# OR step by step:
make kind-cluster          # Create cluster
make docker-build          # Build images
make kind-load             # Load into kind
make kind-deploy           # Deploy manifests
make wait                  # Wait for ready
```

```bash
# Clean up
make kind-clean
```

--------------------------------

### Cleanup Installer Service Account Cluster Role Bindings

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/getting-started/olmv1_getting_started.md

Deletes the cluster role bindings associated with the installer service account. These grant the necessary permissions for installation.

```bash
kubectl delete clusterrolebinding argocd-installer-binding && kubectl delete clusterrolebinding argocd-installer-rbac-binding
```

--------------------------------

### Get First 10 Bundles with Basic Info

Source: https://github.com/operator-framework/operator-controller/blob/main/internal/catalogd/graphql/sample-queries.txt

Fetch the first 10 bundles with essential information like name, package, version, image, and skip range.

```graphql
{
  olmbundles(limit: 10) {
    name
    package
    version
    image
    skipRange
  }
}
```

--------------------------------

### Interactive Heap and CPU Profile Analysis

Source: https://github.com/operator-framework/operator-controller/blob/main/hack/tools/test-profiling/README.md

Use the Go pprof tool to analyze collected heap and CPU profiles. Commands include viewing top profiles, comparing profiles, and filtering output.

```bash
cd test-profiles/<name>/operator-controller
go tool pprof -top heap23.pprof
go tool pprof -base=heap0.pprof -top heap23.pprof
go tool pprof -text heap23.pprof | grep -i openapi
```

--------------------------------

### List Available E2E Steps

Source: https://github.com/operator-framework/operator-controller/blob/main/test/e2e/README.md

Run this command to get a list of all implemented end-to-end test steps, including their parameters and handler locations. This is useful for writing new feature files or debugging existing scenarios.

```shell
go test test/e2e/features_test.go -d
```

--------------------------------

### Go Step Definition Implementation

Source: https://github.com/operator-framework/operator-controller/blob/main/test/e2e/README.md

Shows how to register and implement custom step definitions in Go for Gherkin scenarios.

```go
func RegisterSteps(sc *godog.ScenarioContext) {
    // ... existing steps
    sc.Step(`^your step pattern "([^"]+)"$`, YourStepFunction)
}

func YourStepFunction(ctx context.Context, param string) error {
    sc := scenarioCtx(ctx)
    // Implementation
    return nil
}
```

--------------------------------

### Build Commands

Source: https://github.com/operator-framework/operator-controller/blob/main/AGENTS.md

Commands to build the project for the local platform, Linux, Docker images, and a full release.

```bash
# Build for local platform
make build
```

```bash
# Build for Linux (required for docker)
make build-linux
```

```bash
# Build docker images
make docker-build
```

```bash
# Full release build
make release
```

--------------------------------

### List Packages with Metadata

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/draft/howto/catalog-queries-graphql-endpoint.md

Retrieve a list of packages, including their name, description, and default channel. Pagination is supported.

```curl
curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ olmpackages(limit: 10) { name description defaultChannel } }"
  }' | jq
```

--------------------------------

### JSON Lines Response Example

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/api-reference/catalogd-webserver.md

This example demonstrates the corresponding JSON Lines format for the FBC snippet, where each object is delimited by a newline.

```jsonlines
{"schema":"olm.package","name":"cockroachdb","defaultChannel":"stable-v6.x"}
{"schema":"olm.channel","name":"stable-v6.x","package":"cockroachdb","entries":[{"name":"cockroachdb.v6.0.0","skipRange":"<6.0.0"}]}
{"schema":"olm.bundle","name":"cockroachdb.v6.0.0","package":"cockroachdb","image":"quay.io/openshift-community-operators/cockroachdb@sha256:d3016b1507515fc7712f9c47fd9082baf9ccb070aaab58ed0ef6e5abdedde8ba","properties":[{"type":"olm.package","value":{"packageName":"cockroachdb","version":"6.0.0"}}]}
```

--------------------------------

### Cleanup Installer Service Account Cluster Roles

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/getting-started/olmv1_getting_started.md

Deletes the cluster roles created for the installer service account. These are typically named with an 'argocd-installer' prefix.

```bash
kubectl delete clusterrole argocd-installer-clusterrole && kubectl delete clusterrole argocd-installer-rbac-clusterrole
```

--------------------------------

### Verify ClusterExtension Installation Status

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/concepts/controlling-catalog-selection.md

Check the status of the ClusterExtension using kubectl to confirm that the operator was installed from the intended catalog based on labels and priority.

```shell
kubectl get clusterextension install-my-operator -o yaml
```

--------------------------------

### CRD Permissions for Installer Service Account

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/howto/derive-service-account.md

Defines permissions for the installer service account to manage CustomResourceDefinitions. Scopes permissions to specific CRDs within a bundle.

```yaml
- apiGroups: [apiextensions.k8s.io]
  resources: [customresourcedefinitions]
  verbs: [create, list, watch]
- apiGroups: [apiextensions.k8s.io]
  resources: [customresourcedefinitions]
  verbs: [get, update, patch, delete]
  # Scoped to the CRDs in the bundle
  resourceNames: [applications.argoproj.io, appprojects.argoproj.io, argocds.argoproj.io, argocdexports.argoproj.io, applicationsets.argoproj.io]
```

--------------------------------

### List Packages Supporting AllNamespaces and No Webhooks

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/tutorials/explore-available-content.md

Filter packages to find those supporting the 'AllNamespaces' install mode and not utilizing webhooks. The output includes the package name and version.

```curl
curl -k https://localhost:8443/catalogs/operatorhubio/api/v1/all | jq -cs '[.[] | select(.schema == "olm.bundle" and (.properties[] | select(.type == "olm.csv.metadata").value.installModes[] | select(.type == "AllNamespaces" and .supported == true)) and .spec.webhookdefinitions == null) | .package] | unique[]'
```

--------------------------------

### Download ENVTEST Kubernetes Binaries

Source: https://github.com/operator-framework/operator-controller/blob/main/CONTRIBUTING.md

Use this command to download the necessary Kubernetes binaries for ENVTEST to run controller tests. The binaries are stored in the bin/envtest-binaries directory.

```sh
make envtest-k8s-bins
```

--------------------------------

### Configuring Components for Profiling

Source: https://github.com/operator-framework/operator-controller/blob/main/hack/tools/test-profiling/README.md

Set environment variables to define which components to profile, their namespaces, deployments, and pprof ports. This allows customization of the profiling scope.

```bash
# Define components to profile (optional - defaults to operator-controller and catalogd)
# Format: "name:namespace:deployment:port;name2:namespace2:deployment2:port2"
export TEST_PROFILE_COMPONENTS="operator-controller:olmv1-system:operator-controller-controller-manager:6060;catalogd:olmv1-system:catalogd-controller-manager:6060"

# Profile custom applications
export TEST_PROFILE_COMPONENTS="my-app:my-ns:my-deployment:8080;api-server:api-ns:api-deployment:9090"

# Other settings
export TEST_PROFILE_INTERVAL=10                # seconds between collections
export TEST_PROFILE_CPU_DURATION=10            # CPU profiling duration in seconds
export TEST_PROFILE_MODE=both                  # both|heap|cpu
export TEST_PROFILE_DIR=./test-profiles        # output directory
export TEST_PROFILE_TEST_TARGET=test-e2e       # make target to run
```

--------------------------------

### SourceConfig

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/api-reference/olmv1-api-reference.md

A discriminated union which selects the installation source.

```APIDOC
## SourceConfig

### Description
SourceConfig is a discriminated union which selects the installation source.

### Fields
- `sourceType` (string) - sourceType is required and specifies the type of install source. The only allowed value is "Catalog". When set to "Catalog", information for determining the appropriate bundle of content to install is fetched from ClusterCatalog resources on the cluster. When using the Catalog sourceType, the catalog field must also be set.
- `catalog` ([CatalogFilter](#catalogfilter)) - catalog configures how information is sourced from a catalog. It is required when sourceType is "Catalog", and forbidden otherwise.
```

--------------------------------

### Run All Scenarios in a Feature File

Source: https://github.com/operator-framework/operator-controller/blob/main/test/e2e/README.md

Execute all scenarios defined within a specific feature file using the persistent cluster setup.

```bash
make e2e/install
```

--------------------------------

### Accessing Full FBC Metadata via v1 API

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/draft/api-reference/catalogd-webserver-metas-endpoint.md

This example shows how to construct the URL to access the entire FBC metadata using the 'api/v1/all' endpoint. It assumes a base URL is provided by the ClusterCatalog resource.

```yaml
urls:
    base: https://catalogd-service.olmv1-system.svc/catalogs/operatorhubio

https://catalogd-service.olmv1-system.svc/catalogs/operatorhubio/api/v1/all
```

--------------------------------

### ServiceAccountReference

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/api-reference/olmv1-api-reference.md

Identifies the serviceAccount used to install a ClusterExtension.

```APIDOC
## ServiceAccountReference

### Description
ServiceAccountReference identifies the serviceAccount used for install a ClusterExtension.

### Fields
- `name` (string) - name is a required, immutable reference to the name of the ServiceAccount used for installation and management of the content for the package specified in the packageName field. This ServiceAccount must exist in the installNamespace. The name field follows the DNS subdomain standard as defined in [RFC 1123]. It must contain only lowercase alphanumeric characters, hyphens (-) or periods (.), start and end with an alphanumeric character, and be no longer than 253 characters.
```

--------------------------------

### Paginate Bundle Queries

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/draft/howto/catalog-queries-graphql-endpoint.md

Demonstrates how to use `limit` and `offset` arguments to paginate through query results, such as bundles. This is applicable to all schema-based queries.

```curl
curl -k -X POST 'https://localhost:8443/catalogs/operatorhubio/api/v1/graphql' \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ olmbundles(limit: 10, offset: 20) { name } }"
  }' | jq
```

--------------------------------

### ClusterExtensionInstallStatus

Source: https://github.com/operator-framework/operator-controller/blob/main/docs/api-reference/olmv1-api-reference.md

Represents the installation status of a Cluster Extension's bundle.

```APIDOC
## ClusterExtensionInstallStatus

### Description
ClusterExtensionInstallStatus is a representation of the status of the identified bundle for a Cluster Extension installation.

### Fields
- `bundle` (BundleMetadata) - Required. Represents the identifying attributes of a bundle, which is a versioned set of content applied to a cluster to install a package.
```