### One-time Setup for Docsgen Repo

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/generating-asciidoc-api.md

Clone the repository, install dependencies, and update your PATH to include the tool.

```bash
git clone https://github.com/jboxman-rh/openshift-apidocs-gen
```

```bash
cd openshift-apidocs-gen
```

```bash
npm install
```

```bash
PATH=<path_to_>/openshift-apidocs-gen:$PATH
```

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

### Deploy Subscription and Watch Installation

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-integration-lifecycle.md

Creates the namespace if it doesn't exist, applies the Subscription configuration, and then monitors the Cluster Service Version (CSV) status to track the installation progress.

```bash
oc create namespace openshift-lightspeed
oc apply -f subscription.yaml

# Watch installation
oc get csv -n openshift-lightspeed -w
```

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

### Check Subscription and Install Plan

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-bundle-management.md

Inspect the subscription and install plan resources in Kubernetes to troubleshoot OLM installation issues. This helps in diagnosing why OLM might not be able to install a bundle.

```bash
# Check subscription and install plan
oc get subscription lightspeed-operator -n openshift-lightspeed -o yaml
oc get installplan -n openshift-lightspeed
```

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

### Run Controller Locally

Source: https://github.com/openshift/lightspeed-operator/blob/main/CONTRIBUTING.md

Starts the controller locally with automatic setup for RBAC, CRDs, and the necessary namespace.

```bash
make run
```

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

### List Pending Install Plans (Manual Upgrades)

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-integration-lifecycle.md

View all InstallPlans that are awaiting manual approval for upgrades.

```bash
oc get installplan -n openshift-lightspeed
```

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

### Bundle Structure Example

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-bundle-management.md

Illustrates the typical directory structure of an OLM bundle, including manifests, metadata, tests, and the Dockerfile.

```tree
bundle/
├── manifests/
│   ├── lightspeed-operator.clusterserviceversion.yaml  # Main metadata and install strategy
│   ├── ols.openshift.io_olsconfigs.yaml                # CRD definition
│   └── *_rbac.authorization.k8s.io_*.yaml              # RBAC resources
├── metadata/
│   └── annotations.yaml                                # Bundle metadata (channels, OCP versions)
└── tests/scorecard/
    └── config.yaml                                     # Scorecard configuration

bundle.Dockerfile                                        # Bundle image build
```

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

### OLM Catalog Workflow

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-catalog-management.md

Illustrates the basic workflow for how an operator bundle is discovered and installed by OLM.

```text
Bundle (single version) → Add to Catalog(s) → OLM discovers operator → Users install
```

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

### Install Operator via OLM

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-testing-validation.md

Steps to perform a quick installation test of an operator using OLM. This involves applying catalog sources, subscriptions, and verifying the CSV and operator configuration.

```bash
# 1. Deploy catalog
oc apply -f hack/example_catalogsource.yaml

# 2. Create subscription (see olm-integration-lifecycle.md for full YAML)
oc apply -f subscription.yaml

# 3. Wait and verify
oc get csv -n openshift-lightspeed -w
oc apply -f config/samples/ols_v1alpha1_olsconfig.yaml
oc get olsconfig cluster -o yaml
```

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

### Manual Development Environment Setup and Teardown

Source: https://github.com/openshift/lightspeed-operator/blob/main/README.md

Provides commands for manually setting up or cleaning up the development environment, including namespace, CRDs, and RBAC resources.

```shell
make dev-setup
```

```shell
make dev-teardown
```

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

### Structured Logging

Source: https://github.com/openshift/lightspeed-operator/blob/main/CONTRIBUTING.md

Example of logging informational messages and errors with key-value pairs for context.

```go
r.GetLogger().Info("action", "key", value)
r.GetLogger().Error(err, "description", "key", value)
```

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

### Example Output for Snapshot to Catalog Update

Source: https://github.com/openshift/lightspeed-operator/blob/main/README.md

This output shows the details of updating the catalog, including the tools used, image references, and validation status.

```shell
Update catalog lightspeed-catalog-4.16/index.yaml from snapshot ols-bnxm2
using opm from /home/hasun/GitRepo/lightspeed-operator/bin/opm
using yq from /usr/bin/yq
Catalog will use the following images:
BUNDLE_IMAGE=registry.redhat.io/openshift-lightspeed-tech-preview/lightspeed-operator-bundle@sha256:b9387e5900e700db47d2b4d7f106b43d0958a3b0d3d4f4b68495141675b66a1c
OPERATOR_IMAGE=registry.redhat.io/openshift-lightspeed-tech-preview/lightspeed-rhel9-operator@sha256:4bb81dfec6cce853543c7c0e7f2898ece23105fe3a5c5b17d845b1ff58fdc92a
CONSOLE_IMAGE=registry.redhat.io/openshift-lightspeed-tech-preview/lightspeed-console-plugin-rhel9@sha256:4f45c9ba068cf92e592bb3a502764ce6bc93cd154d081fa49d05cb040885155b
SERVICE_IMAGE=registry.redhat.io/openshift-lightspeed-tech-preview/lightspeed-service-api-rhel9@sha256:794017379e28cfbbd17c8a8343f3326f2c99b8f9da5e593fa5afd52258d0c563
BUNDLE_IMAGE_ORIGIN=quay.io/redhat-user-workloads/crt-nshift-lightspeed-tenant/ols/bundle@sha256:b9387e5900e700db47d2b4d7f106b43d0958a3b0d3d4f4b68495141675b66a1c
Bundle version is 0.1.0
Validation passed for lightspeed-catalog-4.16/index.yaml
```

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

### Testing Commands

Source: https://github.com/openshift/lightspeed-operator/blob/main/AGENTS.md

Always use 'make test' for unit tests and 'make test-e2e' for end-to-end tests. The Makefile ensures proper environment setup.

```bash
make test       # Unit tests
```

```bash
make test-e2e   # E2E tests (requires cluster)
```

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

### Running the API Documentation Generator

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/generating-asciidoc-api.md

Ensure a Kubernetes cluster is running, generate the CRD documentation, install it, and then execute the script to generate AsciiDoc API references.

```bash
# If you haven't already, start any k8s cluster - kind, CRC
kind create cluster
```

```bash
# Make sure the CRD has all the desired doc within
make generate
```

```bash
make install
```

```bash
hack/asciidoc-gen.sh
```

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

### Check Install Plan Status

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-integration-lifecycle.md

Examine the InstallPlan YAML to understand its status and identify potential blocking issues.

```bash
oc get installplan -n openshift-lightspeed -o yaml
```

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

### Filter Events for CSV and InstallPlan

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-integration-lifecycle.md

Retrieve events specifically related to CSV and InstallPlan to troubleshoot installation problems.

```bash
oc get events -n openshift-lightspeed | grep -E 'CSV|InstallPlan'
```

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

### Check Subscription Status

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-integration-lifecycle.md

Inspect the subscription details to diagnose installation issues, such as a CSV not appearing.

```bash
oc get subscription lightspeed-operator -n openshift-lightspeed -o yaml
```

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

### Testing Commands

Source: https://github.com/openshift/lightspeed-operator/blob/main/CLAUDE.md

Always use 'make test' for unit tests and 'make test-e2e' for end-to-end tests. The Makefile handles essential setup like envtest and CRDs.

```bash
make test	    # Unit tests
```

```bash
make test-e2e	    # E2E tests (requires cluster)
```

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

### Update Bundle Images with Script

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-bundle-management.md

Use a script to update the bundle with new image references. This requires `yq` and `jq` to be installed and depends on a `related_images.json` file.

```bash
YQ=$(which yq) JQ=$(which jq) ./hack/update_bundle.sh -v 0.1.0 -i related_images.json
```

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

### Run E2E Tests with Verbose Output

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-testing-validation.md

Enable verbose output for E2E tests to get more detailed logs during execution.

```bash
make test-e2e GINKGO_V=true
```

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

### Delete Failed InstallPlan to Retry

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-integration-lifecycle.md

Remove a failed InstallPlan to allow OLM to create a new one and retry the installation or upgrade.

```bash
oc delete installplan <failed-plan> -n openshift-lightspeed
```

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

### Example FBC Structure for OLM Package

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-catalog-management.md

This YAML defines an OLM package, a bundle, and a channel, including skip ranges and replacement information for managing updates.

```yaml
---
schema: olm.package
name: lightspeed-operator
defaultChannel: alpha

---
schema: olm.bundle
name: lightspeed-operator.v0.1.0
package: lightspeed-operator
image: registry.redhat.io/.../bundle@sha256:...

---
schema: olm.channel
name: alpha
package: lightspeed-operator
entries:
  - name: lightspeed-operator.v0.1.0
  - name: lightspeed-operator.v0.2.0
    skipRange: ">=0.1.0 <0.2.0"
    replaces: lightspeed-operator.v0.1.0
```

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

### Check User Permissions for OLSConfig

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-rbac-security.md

Verify if a specific user has the necessary permissions to get OLSConfig resources. This is useful for troubleshooting user access issues.

```bash
# Check user permissions
oc auth can-i get olsconfig --as=<username>

# List role bindings
oc get rolebinding -n openshift-lightspeed -o yaml | grep <username>
```

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

### Verify Lightspeed Operator Installation

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-integration-lifecycle.md

Checks the status of the Cluster Service Version (CSV) to ensure the operator is running successfully. It also verifies the operator pod and its logs.

```bash
# Check CSV status (should show "Succeeded")
oc get csv -n openshift-lightspeed

# Check operator pod
oc get pods -n openshift-lightspeed

# Check logs
oc logs -n openshift-lightspeed deployment/lightspeed-operator-controller-manager -f
```

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

### Upgrade Operator via OLM

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-testing-validation.md

Manual steps to test the upgrade process of an operator using OLM. This includes installing an old version, waiting for it, performing the upgrade by updating the catalog or subscription, and verifying the new version.

```bash
# 1. Install old version
oc apply -f old-subscription.yaml

# 2. Wait for installation
oc get csv -n openshift-lightspeed -w

# 3. Upgrade (update catalog or subscription)
oc apply -f new-subscription.yaml

# 4. Verify
oc get csv -n openshift-lightspeed -w
oc get olsconfig cluster -o yaml
oc get deployments -n openshift-lightspeed -o yaml | grep image
```

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

### Create New Component Package Structure

Source: https://github.com/openshift/lightspeed-operator/blob/main/CONTRIBUTING.md

Use this command to create the necessary directory structure and initial files for a new component.

```bash
mkdir -p internal/controller/mycomponent
cd internal/controller/mycomponent
touch reconciler.go assets.go suite_test.go reconciler_test.go assets_test.go
```

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

### Build and Push OLM Bundle

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-bundle-management.md

Build the bundle image locally and then push it to a registry. Ensure BUNDLE_IMG is set to your desired image repository and tag.

```bash
make bundle-build BUNDLE_IMG=quay.io/myorg/lightspeed-operator-bundle:v0.1.0
```

```bash
make bundle-push BUNDLE_IMG=quay.io/myorg/lightspeed-operator-bundle:v0.1.0
```

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

### Create Subscription for Lightspeed Operator

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-integration-lifecycle.md

Defines the intent to install the lightspeed-operator via OLM. This YAML configuration specifies the channel, source, and approval strategy.

```yaml
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: lightspeed-operator
  namespace: openshift-lightspeed
spec:
  channel: alpha
  name: lightspeed-operator
  source: lightspeed-catalog
  sourceNamespace: openshift-marketplace
  installPlanApproval: Automatic  # or Manual for controlled upgrades
```

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

### Create Catalog for New OCP Version

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-catalog-management.md

Steps to set up a new catalog directory for a future OpenShift Container Platform (OCP) version. This includes copying existing catalog files, updating the Dockerfile, and modifying the Makefile.

```bash
mkdir lightspeed-catalog-4.21
cp lightspeed-catalog-4.20/index.yaml lightspeed-catalog-4.21/
cp lightspeed-catalog-4.20.Dockerfile lightspeed-catalog-4.21.Dockerfile
# Edit Dockerfile to reference 4.21
vim Makefile  # Add 4.21 to catalog targets
```

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

### Configure System Resource Watcher

Source: https://github.com/openshift/lightspeed-operator/blob/main/CONTRIBUTING.md

Define system resources to be watched by the operator. Specify names, namespaces, descriptions, and affected deployments.

```go
watcherConfig := &utils.WatcherConfig{
    Secrets: utils.SecretWatcherConfig{
        SystemResources: []utils.SystemSecret{
            {
                Name:                "my-system-secret",
                Namespace:           namespace,
                Description:         "Description for debugging",
                AffectedDeployments: []string{"ACTIVE_BACKEND"},
            },
        },
    },
}
```

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

### Add Bundle to All Catalogs Workflow

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-catalog-management.md

Follow these steps to build, push, and add a bundle to all OLM catalogs, then build and push the catalog images for different OpenShift versions.

```bash
# 1. Build and push bundle first
make bundle BUNDLE_TAG=0.2.0
make bundle-build BUNDLE_IMG=quay.io/org/bundle:v0.2.0
make bundle-push BUNDLE_IMG=quay.io/org/bundle:v0.2.0

# 2. Add to catalogs using our script
./hack/bundle_to_catalog.sh quay.io/org/bundle:v0.2.0

# 3. Build and push catalog images
for v in 4.16 4.17 4.18 4.19 4.20; do
  make catalog-build VERSION=$v
  make catalog-push VERSION=$v
done
```

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

### File Naming Conventions

Source: https://github.com/openshift/lightspeed-operator/blob/main/CLAUDE.md

Adhere to these file naming conventions for different types of Go files within the project.

```go
reconciler.go
```

```go
assets.go
```

```go
suite_test.go
```

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

### Generate Bundle with Version and Related Images using Make

Source: https://github.com/openshift/lightspeed-operator/blob/main/hack/release_tools.md

Generate a bundle with a specific version and include images from a provided JSON file using 'make bundle'. This is useful for previewing the final bundle build.

```bash
RELATED_IMAGES_FILE=related_images.json make bundle
```

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

### Build, Push, and Deploy Operator Image

Source: https://github.com/openshift/lightspeed-operator/blob/main/README.md

Builds the Docker image for the operator, pushes it to a personal repository, and then deploys the operator into the cluster. Replace 'username/ols-operator:0.10' with your image details.

```shell
IMG="docker.io/username/ols-operator:0.10" make docker-build docker-push
IMG="docker.io/username/ols-operator:0.10" make deploy
```

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

### OpenAI API Keys Secret

Source: https://github.com/openshift/lightspeed-operator/blob/main/README.md

Example Kubernetes Secret definition for storing OpenAI API keys. The 'apitoken' field requires a base64 encoded API Key.

```yaml
apiVersion: v1
data:
  apitoken: <base64 encoded API Key>
kind: Secret
metadata:
  name: openai-api-keys
  namespace: openshift-lightspeed
type: Opaque
```

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

### Approve Manual Upgrade

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-integration-lifecycle.md

Approve a pending InstallPlan to proceed with the operator upgrade.

```bash
oc patch installplan <install-plan-name> -n openshift-lightspeed \
  --type merge -p '{"spec":{"approved":true}}'
```

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

### Watsonx API Keys Secret

Source: https://github.com/openshift/lightspeed-operator/blob/main/README.md

Example Kubernetes Secret definition for storing Watsonx API keys. The 'apitoken' field requires a base64 encoded API Key.

```yaml
apiVersion: v1
data:
  apitoken: <base64 encoded API Key>
kind: Secret
metadata:
  name: watsonx-api-keys
  namespace: openshift-lightspeed
type: Opaque
```

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

### Debug End-to-End Tests in VS Code

Source: https://github.com/openshift/lightspeed-operator/blob/main/README.md

Configure VS Code to launch and debug end-to-end tests. This setup requires KUBECONFIG and LLM_TOKEN environment variables to be defined.

```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch E2E test ",
            "type": "go",
            "request": "launch",
            "mode": "debug",
            "program": "${workspaceFolder}/test/e2e",
            "args": [
                // "--ginkgo.v", # verbose output from Ginkgo test framework
            ],
            "env": {
                "KUBECONFIG": "/path/to/kubeconfig",
                "LLM_TOKEN": "sk-xxxxxxxx"
            },
        },
    ]
}
```

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

### Add New Bundle to All Catalogs

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-catalog-management.md

Steps to create, push a new bundle, and then add it to all OLM catalogs. This involves building the bundle, pushing the image, and then distributing it across different catalog versions.

```bash
# 1. Create and push bundle
make bundle BUNDLE_TAG=0.3.0
make bundle-build BUNDLE_IMG=quay.io/org/bundle:v0.3.0
make bundle-push BUNDLE_IMG=quay.io/org/bundle:v0.3.0

# 2. Add to all catalogs
./hack/bundle_to_catalog.sh quay.io/org/bundle:v0.3.0

# 3. Build and push catalogs
for v in 4.16 4.17 4.18 4.19 4.20; do
  make catalog-build VERSION=$v
  make catalog-push VERSION=$v
done
```

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

### Run All Tests

Source: https://github.com/openshift/lightspeed-operator/blob/main/CONTRIBUTING.md

Always use 'make test' to run all tests. Never use 'go test' directly to ensure consistent testing environment and procedures.

```bash
make test  # ALWAYS use make test, NEVER go test directly
```

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

### Azure OpenAI API Keys Secret

Source: https://github.com/openshift/lightspeed-operator/blob/main/README.md

Example Kubernetes Secret definition for storing Azure OpenAI API keys. The 'apitoken' field requires a base64 encoded API Key.

```yaml
apiVersion: v1
data:
  apitoken: <base64 encoded API Key>
kind: Secret
metadata:
  name: azure-openai-api-keys
  namespace: openshift-lightspeed
type: Opaque
```

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

### Build Catalog Image with Podman

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-catalog-management.md

Command to build a catalog image using `podman` from a Dockerfile. This is used when catalog image build processes fail.

```bash
podman build -f lightspeed-catalog-4.18.Dockerfile -t test-catalog .
```

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

### Configure Postgres Secret Management in OLSConfig

Source: https://github.com/openshift/lightspeed-operator/blob/main/README.md

Example of how to specify a custom secret name for PostgreSQL credentials within the OLSConfig custom resource. This allows for explicit control over the secret used for database access.

```yaml
conversationCache:
  postgres:
    sharedBuffers: "256MB"
    maxConnections: 2000
    credentialsSecret: xyz
  type: postgres
```

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

### Database Deployment Settings

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olsconfig-ols-openshift-io-v1alpha1.adoc

Configure settings for the Database deployment.

```APIDOC
## .spec.ols.deployment.database

### Description
Database container settings.

### Type
`object`

### Properties
#### `nodeSelector`
- **Type**: `object (string)`
- **Description**: 

#### `resources`
- **Type**: `object`
- **Description**: ResourceRequirements describes the compute resource requirements.

#### `tolerations`
- **Type**: `array`
- **Description**: 
```

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

### Azure OpenAI User-Assigned Identity Secret

Source: https://github.com/openshift/lightspeed-operator/blob/main/README.md

Example Kubernetes Secret definition for Azure OpenAI using a user-assigned identity. Requires base64 encoded client ID, client secret, and tenant ID.

```yaml
apiVersion: v1
data:
  client_id: <base64 encoded client id>
  client_secret: <base64 encoded client secret>
  tenant_id: <base64 encoded tenant id>
kind: Secret
metadata:
  name: azure-api-keys
  namespace: openshift-lightspeed
type: Opaque
```

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

### Check Service Account and Role Bindings

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-rbac-security.md

Use these commands to verify the service account used by the operator and check its associated cluster role bindings. This helps in diagnosing permission denied errors.

```bash
# Check service account
oc get sa lightspeed-operator-controller-manager -n openshift-lightspeed

# Check role bindings
oc get clusterrolebinding | grep lightspeed-operator
```

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

### Run Unit Tests

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-testing-validation.md

Always use `make test` to run unit tests, as it correctly sets up the environment including envtest and CRDs.

```bash
make test
```

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

### Deploy CatalogSource

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-integration-lifecycle.md

Applies the CatalogSource configuration to make the operator catalog available to the cluster. Verify the deployment and check for the lightspeed-catalog pod.

```bash
oc apply -f hack/example_catalogsource.yaml

# Verify
oc get catalogsource -n openshift-marketplace
oc get pods -n openshift-marketplace | grep lightspeed-catalog
```

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

### Naming Patterns for Functions and Files

Source: https://github.com/openshift/lightspeed-operator/blob/main/AGENTS.md

Functions should follow a camelCase pattern, often indicating an action and resource. File names should be descriptive of their content.

```go
reconcile<ComponentName>()
```

```go
generate<ResourceType>()
```

```go
reconciler.go
```

```go
assets.go
```

```go
suite_test.go
```

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

### Naming Patterns for Constants and Functions

Source: https://github.com/openshift/lightspeed-operator/blob/main/CLAUDE.md

Follow these naming conventions for constants and functions to maintain code consistency.

```go
const OLSConfigCmName = "olsconfig"
```

```go
const ErrCreateAPIConfigmap = "failed to create API configmap"
```

```go
reconcile<ComponentName>()
```

```go
generate<ResourceType>()
```

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

### Review Pod Security Context Settings

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-rbac-security.md

Inspect the security context of pods and containers to ensure proper security configurations, such as running as non-root.

```bash
# View security context
oc get pod -n openshift-lightspeed <pod> -o jsonpath='{.spec.securityContext}'
oc get pod -n openshift-lightspeed <pod> -o jsonpath='{.spec.containers[0].securityContext}'

# Verify non-root
oc get pod -n openshift-lightspeed <pod> -o jsonpath='{.spec.containers[0].securityContext.runAsNonRoot}'
```

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

### Generate Bundle with Version using Make

Source: https://github.com/openshift/lightspeed-operator/blob/main/hack/release_tools.md

Generate a bundle with a specified version tag using the 'make bundle' command. This is an alternative to the update_bundle.sh script.

```bash
BUNDLE_TAG=0.2.1  make bundle
```

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

### Naming Patterns for Constants

Source: https://github.com/openshift/lightspeed-operator/blob/main/AGENTS.md

Use uppercase for constants. For error constants, include a descriptive error message.

```go
const OLSConfigCmName = "olsconfig"
```

```go
const ErrCreateAPIConfigmap = "failed to create API configmap"
```

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

### Render Bundle to File-Based Catalog (FBC)

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-catalog-management.md

Renders a bundle image into a File-Based Catalog (FBC) format. This is useful for integrating with systems that consume FBC.

```bash
# Render bundle to FBC
opm render <bundle-image>
```

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

### Correct Test Cleanup (Do)

Source: https://github.com/openshift/lightspeed-operator/blob/main/CONTRIBUTING.md

Shows the correct method for deleting a CR by using the `cleanupOLSConfig` helper, which properly handles finalizers.

```go
cleanupOLSConfig(ctx, cr)  // ✅ Removes finalizer, waits for deletion
```

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

### List All Bundles in Catalog Index

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-catalog-management.md

Uses `yq` to filter and list the names of all bundles defined in the catalog index, specifically those matching the `olm.bundle` schema.

```bash
yq '.[] | select(.schema == "olm.bundle") | .name' lightspeed-catalog-4.18/index.yaml
```

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

### View Unit Test Coverage

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-testing-validation.md

Generate an HTML report to visualize unit test coverage.

```bash
go tool cover -html=cover.out
```

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

### Build and Deploy Operator

Source: https://github.com/openshift/lightspeed-operator/blob/main/CONTRIBUTING.md

Builds the Docker image for the operator and deploys it to the cluster. Apply the sample CRD and tail logs for monitoring.

```bash
make docker-build
make deploy
oc apply -f config/samples/ols_v1alpha1_olsconfig.yaml
oc logs -n openshift-lightspeed deployment/lightspeed-operator-controller-manager -f
```

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

### Inspect Deployments in openshift-lightspeed Namespace

Source: https://github.com/openshift/lightspeed-operator/blob/main/README.md

Retrieves a list of all deployments within the 'openshift-lightspeed' namespace.

```shell
oc get deployments -n openshift-lightspeed
```

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

### Check Catalog Pod

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-integration-lifecycle.md

Verify the status and logs of the catalog pod to ensure it's running and healthy.

```bash
# Check catalog pod
oc get pods -n openshift-marketplace
oc logs -n openshift-marketplace <catalog-pod>
```

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

### Regenerate RBAC Manifests and Bundle

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-rbac-security.md

After updating RBAC markers, run these make targets to regenerate the manifests and create a bundle. Use `git diff` to review the changes.

```bash
make manifests              # Regenerate from markers
make bundle BUNDLE_TAG=0.1.0
git diff config/rbac/role.yaml
```

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

### Build OLM Catalog

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-catalog-management.md

Builds an OLM catalog using the provided version. This command is essential for creating new catalog versions.

```bash
# Build catalog
make catalog-build VERSION=4.18
```

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

### Copy Certificates and Nginx Config

Source: https://github.com/openshift/lightspeed-operator/blob/main/hack/rhelai/README.txt

Securely copy the generated certificates and Nginx configuration file to the RHELAI instance using scp. Replace 'your_aws_keys.pem' with your actual AWS key pair file.

```bash
$ scp -i your_aws_keys.pem -r certs nginx.conf cloud-user@18.191.144.20:~
```

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

### Inspect ConfigMaps in openshift-lightspeed Namespace

Source: https://github.com/openshift/lightspeed-operator/blob/main/README.md

Retrieves a list of all ConfigMaps within the 'openshift-lightspeed' namespace.

```shell
oc get configmaps -n openshift-lightspeed
```

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

### Run Linting

Source: https://github.com/openshift/lightspeed-operator/blob/main/CONTRIBUTING.md

Checks code for style and potential issues. Use `make lint-fix` to automatically resolve common linting problems.

```bash
make lint
```

```bash
make lint-fix
```

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

### Run End-to-End Tests with Make

Source: https://github.com/openshift/lightspeed-operator/blob/main/README.md

Execute end-to-end tests against a running OpenShift cluster. Requires the operator to be deployed and specific environment variables to be set.

```shell
make  test-e2e
```

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

### Create Rhelai CA ConfigMap

Source: https://github.com/openshift/lightspeed-operator/blob/main/hack/rhelai/README.txt

Create a Kubernetes ConfigMap named 'rhelai-ca' containing the RHELAI Nginx certificate. This ConfigMap will be referenced by the OLSConfig.

```bash
$ oc create configmap rhelai-ca --from-file=certs/rhelai.crt
```

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

### Add Bundle to Specific Catalog

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-catalog-management.md

Instructions for adding a bundle to a specific catalog version. This involves rendering the bundle, appending it to the catalog's index, validating, and rebuilding the catalog.

```bash
opm render quay.io/org/bundle:v0.3.0 > /tmp/bundle.yaml
cat /tmp/bundle.yaml >> lightspeed-catalog-4.18/index.yaml
vim lightspeed-catalog-4.18/index.yaml  # Add to channel entries
opm validate lightspeed-catalog-4.18
make catalog-build VERSION=4.18
```

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

### Inspect Services in openshift-lightspeed Namespace

Source: https://github.com/openshift/lightspeed-operator/blob/main/README.md

Retrieves a list of all services within the 'openshift-lightspeed' namespace.

```shell
oc get services -n openshift-lightspeed
```

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

### Update Bundle with Version and Image List

Source: https://github.com/openshift/lightspeed-operator/blob/main/hack/release_tools.md

Update the bundle with a specific version and a JSON file containing related image information. If no image list is provided, the existing list in the CSV file is retained.

```bash
./hack/update_bundle.sh -v 0.2.1 -i related_images.json
```

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

### Formatted Error Handling

Source: https://github.com/openshift/lightspeed-operator/blob/main/CONTRIBUTING.md

Standard way to return errors, wrapping existing errors with a prefix for context.

```go
return fmt.Errorf("%s: %w", utils.ErrConstant, err)
```

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

### Generate OLM Bundle

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-bundle-management.md

Use this command to generate an OLM bundle. Specify the BUNDLE_TAG for versioning. Optionally, use RELATED_IMAGES_FILE to provide custom image references.

```bash
make bundle BUNDLE_TAG=0.1.0
```

```bash
# With custom images
make bundle BUNDLE_TAG=0.1.0 RELATED_IMAGES_FILE=related_images.json
```

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

### Preflight Checks for Operator Bundles and Images

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-testing-validation.md

Use preflight to check operator bundles or container images for compliance. Ensure your Docker configuration is accessible.

```bash
# Check bundle
preflight check operator bundle/ --docker-config=$HOME/.docker/config.json
```

```bash
# Check image
preflight check container quay.io/org/lightspeed-operator:v0.1.0
```

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

### Snapshot-Based Catalog Generation

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-catalog-management.md

This script is used for generating catalogs based on snapshots. Refer to the script for specific usage details.

```bash
# Snapshot-based catalog generation
./hack/snapshot_to_catalog.sh
```

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

### Data Collector Deployment Settings

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olsconfig-ols-openshift-io-v1alpha1.adoc

Configure settings for the Data Collector deployment.

```APIDOC
## .spec.ols.deployment.dataCollector

### Description
Data Collector container settings.

### Type
`object`

### Properties
#### `resources`
- **Type**: `object`
- **Description**: ResourceRequirements describes the compute resource requirements.
```

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

### Console Deployment Configuration

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olsconfig-ols-openshift-io-v1alpha1.adoc

Configuration for the console deployment within the OpenShift Lightspeed Operator.

```APIDOC
## spec.ols.deployment.console

### Description
Console container settings.

### Type
`object`

### Properties

#### `caCertificate`
- **Type**: `string`
- **Description**: Certificate Authority (CA) certificate used by the console proxy endpoint.

#### `nodeSelector`
- **Type**: `object (string)`
- **Description**: 

#### `replicas`
- **Type**: `integer`
- **Description**: Defines the number of desired Console pods. Default: "1"

#### `resources`
- **Type**: `object`
- **Description**: ResourceRequirements describes the compute resource requirements.

##### `resources.limits`
- **Type**: `integer-or-string`
- **Description**: Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

##### `resources.requests`
- **Type**: `integer-or-string`
- **Description**: Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

##### `resources.claims`
- **Type**: `array`
- **Description**: Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container.
This is an alpha field and requires enabling the DynamicResourceAllocation feature gate.
This field is immutable. It can only be set for containers.

###### `resources.claims[]`
- **Type**: `object`
- **Description**: ResourceClaim references one entry in PodSpec.ResourceClaims.

### Required
- `name`

#### `resources.claims[].name`
- **Type**: `string`
- **Description**: Name must match the name of one entry in pod.spec.resourceClaims of the Pod where this field is used. It makes that resource available inside a container.

#### `resources.claims[].request`
- **Type**: `string`
- **Description**: Request is the name chosen for a request in the referenced claim. If empty, everything from the claim is made available, otherwise only the result of this request.

#### `tolerations`
- **Type**: `array`
- **Description**: 

##### `tolerations[]`
- **Type**: `object`
- **Description**: The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>.

###### `tolerations[].effect`
- **Type**: `string`
- **Description**: Effect indicates the taint effect to match. Empty means match all taint effects. When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute.

###### `tolerations[].key`
- **Type**: `string`
- **Description**: Key is the taint key that the toleration applies to. Empty means match all taint keys. If the key is empty, operator must be Exists; this combination means to match all values and all keys.

###### `tolerations[].operator`
- **Type**: `string`
- **Description**: Operator represents a key's relationship to the value. Valid operators are Exists and Equal. Defaults to Equal. Exists is equivalent to wildcard for value, so that a pod can tolerate all taints of a particular category.

###### `tolerations[].tolerationSeconds`
- **Type**: `integer`
- **Description**: TolerationSeconds represents the period of time the toleration (which must be of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default, it is not set, which means tolerate the taint forever (do not evict). Zero and negative values will be treated as 0 (evict immediately) by the system.

###### `tolerations[].value`
- **Type**: `string`
- **Description**: Value is the taint value the toleration matches to. If the operator is Exists, the value should be empty, otherwise just a regular string.

```

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

### Update Bundle from Snapshot using Shell Commands

Source: https://github.com/openshift/lightspeed-operator/blob/main/README.md

This script backs up the current bundle image, updates the related images list from a snapshot, restores the bundle image, and then generates a new bundle. Ensure `SNAPSHOT_NAME` is set before execution.

```shell
# back up the bundle image from the related images list
jq '.[] | select(.name == "lightspeed-operator-bundle")' related_images.json > bundle.json
./hack/snapshot_to_image_list.sh -s "${SNAPSHOT_NAME}" -r stable -o related_images.json
# restore the bundle image to the related images list
jq 'map(select(.name != "lightspeed-operator-bundle"))' related_images.json > tmp.json && mv tmp.json related_images.json
jq -s '.[0] + [.[1]]' related_images.json bundle.json > tmp.json && mv tmp.json related_images.json
# generate new bundle
PATH=./bin:$PATH make bundle
```

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

### View Logs for lightspeed-app-server Pod

Source: https://github.com/openshift/lightspeed-operator/blob/main/README.md

Fetches the logs for the 'lightspeed-app-server' pod in the 'openshift-lightspeed' namespace. This log indicates that the Gradio UI is disabled by default.

```shell
oc logs lightspeed-app-server-f7fd6cf6-k7s7p -n openshift-lightspeed
```

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

### Generate Signing Key and Certificate

Source: https://github.com/openshift/lightspeed-operator/blob/main/hack/rhelai/README.txt

Use this command to generate a self-signed certificate and private key for TLS. Ensure openssl.cnf is configured correctly for your environment.

```bash
$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout certs/rhelai.key -out certs/rhelai.crt -config openssl.cnf
```

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

### Error Handling Pattern

Source: https://github.com/openshift/lightspeed-operator/blob/main/CLAUDE.md

Wrap errors using fmt.Errorf with the error constant and the original error for better context and traceability.

```go
fmt.Errorf("%s: %w", ErrConstant, err)
```

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

### Check Operator and User Permissions

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-rbac-security.md

Verify permissions for the operator's service account and individual users using `oc auth can-i`. Review all operator permissions with `oc describe clusterrole`.

```bash
# Check operator permissions
oc auth can-i create deployments \
  --as=system:serviceaccount:openshift-lightspeed:lightspeed-operator-controller-manager

# Check user permissions
oc auth can-i create olsconfig --as=alice

# View all operator permissions
oc describe clusterrole lightspeed-operator-manager-role
```

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

### Deploy the Operator

Source: https://github.com/openshift/lightspeed-operator/blob/main/README.md

Deploys the controller to the OpenShift cluster using the make command. Ensure your kubeconfig is set to the correct cluster context.

```shell
make deploy
```

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

### Run Nginx Container

Source: https://github.com/openshift/lightspeed-operator/blob/main/hack/rhelai/README.txt

Run an Nginx container on the RHELAI instance to act as a TLS reverse proxy. This command maps the host's ports and mounts the Nginx configuration and certificates.

```bash
$ podman run -it --rm --network=host \
  --name my-nginx \
  -p 8443:8443 \
  -v $PWD/nginx.conf:/etc/nginx/nginx.conf:ro,Z \
  -v $PWD/certs:/etc/nginx/certs:ro,Z \
  docker.io/library/nginx:stable
```

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

### Inspect Pods in openshift-lightspeed Namespace

Source: https://github.com/openshift/lightspeed-operator/blob/main/README.md

Retrieves a list of all pods within the 'openshift-lightspeed' namespace.

```shell
oc get pods -n openshift-lightspeed
```

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

### Run E2E Tests

Source: https://github.com/openshift/lightspeed-operator/blob/main/docs/olm-testing-validation.md

Execute end-to-end tests for the operator. Ensure KUBECONFIG and LLM_TOKEN are set.

```bash
export KUBECONFIG=/path/to/kubeconfig
export LLM_TOKEN=your-token
make test-e2e
```