### Quick Local Development Setup with Minikube

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/installation.md

Automated scripts for setting up Minikube, including cert-manager installation, and deploying the operator.

```bash
./scripts/setup-minikube.sh
```

```bash
./scripts/deploy-to-minikube.sh
```

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

### Lynq Development Setup Quick Start

Source: https://github.com/k8s-lynq/lynq/blob/main/CONTRIBUTING.md

Commands to quickly set up the Lynq development environment. This includes cloning the repository, downloading Go modules, creating a test cluster with kind, and installing/running the project.

```bash
# Clone and setup
git clone https://github.com/YOUR_USERNAME/lynq.git
cd lynq
go mod download

# Create test cluster
kind create cluster --name tenant-dev

# Install and run
make install
make run
```

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

### Install with Custom Resource Limits

Source: https://github.com/k8s-lynq/lynq/blob/main/chart/README.md

Install the lynq chart with specific CPU and memory resource limits. Ensure cert-manager is installed first. This example targets the 'lynq-system' namespace.

```bash
# Install cert-manager first (if not already installed)
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml

# Install with custom resource limits
helm install lynq k8s-lynq/lynq \
  --set resources.limits.cpu=1000m \
  --set resources.limits.memory=256Mi \
  --namespace lynq-system \
  --create-namespace
```

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

### PostgreSQL Adapter Implementation in Go

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/contributing-datasource.md

Provides a complete example of a PostgreSQL adapter, including connection setup, connection pooling, and querying nodes. Ensure the PostgreSQL driver is imported.

```go
package datasource

import (
    "context"
    "database/sql"
    "fmt"
    "time"

    _ "github.com/lib/pq" // PostgreSQL driver
)

type PostgreSQLAdapter struct {
    db *sql.DB
}

func NewPostgreSQLAdapter(config Config) (*PostgreSQLAdapter, error) {
    dsn := fmt.Sprintf("host=%s port=%d user=%s password=%s dbname=%s sslmode=disable",
        config.Host, config.Port, config.Username, config.Password, config.Database)

    db, err := sql.Open("postgres", dsn)
    if err != nil {
        return nil, fmt.Errorf("failed to open PostgreSQL connection: %w", err)
    }

    // Configure pool
    db.SetMaxOpenConns(25)
    db.SetMaxIdleConns(5)
    db.SetConnMaxLifetime(5 * time.Minute)

    // Test connection
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    if err := db.PingContext(ctx); err != nil {
        _ = db.Close()
        return nil, fmt.Errorf("failed to ping PostgreSQL: %w", err)
    }

    return &PostgreSQLAdapter{db: db}, nil
}

func (a *PostgreSQLAdapter) QueryNodes(ctx context.Context, config QueryConfig) ([]NodeRow, error) {
    // Build column list
    columns := []string{
        config.ValueMappings.UID,
        config.ValueMappings.HostOrURL,
        config.ValueMappings.Activate,
    }

    extraColumns := make([]string, 0, len(config.ExtraMappings))
    for _, col := range config.ExtraMappings {
        columns = append(columns, col)
        extraColumns = append(extraColumns, col)
    }

    // Build query (PostgreSQL uses $1, $2 for parameters if needed)
    query := fmt.Sprintf("SELECT %s FROM %s", joinColumnsPostgres(columns), config.Table)

    // Execute
    rows, err := a.db.QueryContext(ctx, query)
    if err != nil {
        return nil, fmt.Errorf("failed to query nodes: %w", err)
    }
    defer rows.Close()

    // Scan results
    var nodes []NodeRow
    for rows.Next() {
        row := NodeRow{Extra: make(map[string]string)}

        scanDest := []interface{}{&row.UID, &row.HostOrURL, &row.Activate}

        extraValues := make([]sql.NullString, len(extraColumns))
        for i := range extraValues {
            scanDest = append(scanDest, &extraValues[i])
        }

        if err := rows.Scan(scanDest...); err != nil {
            return nil, fmt.Errorf("failed to scan row: %w", err)
        }

        // Map extra values
        colIndex := make(map[string]int)
        for i, col := range extraColumns {
            colIndex[col] = i
        }

        for key, col := range config.ExtraMappings {
            if idx, ok := colIndex[col]; ok {
                if extraValues[idx].Valid {
                    row.Extra[key] = extraValues[idx].String
                }
            }
        }

        // Filter
        if isActive(row.Activate) && row.HostOrURL != "" {
            nodes = append(nodes, row)
        }
    }

    return nodes, rows.Err()
}

func (a *PostgreSQLAdapter) Close() error {
    if a.db != nil {
        return a.db.Close()
    }
    return nil
}

func joinColumnsPostgres(columns []string) string {
    result := ""
    for i, col := range columns {
        if i > 0 {
            result += ", "
        }
        result += `"` + col + `"` // PostgreSQL uses double quotes
    }
    return result
}

```

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

### Apply LynqHub Sample

Source: https://github.com/k8s-lynq/lynq/blob/main/chart/templates/NOTES.txt

Apply a sample LynqHub Custom Resource to your cluster. This is a basic example to get started.

```bash
kubectl apply -f https://raw.githubusercontent.com/k8s-lynq/lynq/main/config/samples/operator_v1_lynqhub.yaml
```

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

### Apply LynqForm Sample

Source: https://github.com/k8s-lynq/lynq/blob/main/chart/templates/NOTES.txt

Apply a sample LynqForm Custom Resource to your cluster. This is a basic example to get started.

```bash
kubectl apply -f https://raw.githubusercontent.com/k8s-lynq/lynq/main/config/samples/operator_v1_lynqform.yaml
```

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

### Install and Run Locally

Source: https://github.com/k8s-lynq/lynq/blob/main/CONTRIBUTING.md

Install Lynq locally and run it to test your changes in a development environment.

```bash
make install
make run
```

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

### Install Lynq with Kustomize

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/installation.md

Applies the Kustomize configuration to install Lynq. This method also requires cert-manager to be installed and ready.

```bash
# Step 1: Install cert-manager (if not already installed)
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml

# Step 2: Wait for cert-manager to be ready
kubectl wait --for=condition=Available --timeout=300s -n cert-manager deployment/cert-manager
kubectl wait --for=condition=Available --timeout=300s -n cert-manager deployment/cert-manager-webhook

# Step 3: Install Lynq
# cert-manager will automatically issue and manage webhook TLS certificates
kubectl apply -k https://github.com/k8s-lynq/lynq/config/default
```

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

### Add Lynq Helm repository and install

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/installation.md

Adds the Lynq Helm repository, updates it, and then installs Lynq into the 'lynq-system' namespace. This is the recommended installation method.

```bash
# Step 3: Add Helm repository
helm repo add lynq https://k8s-lynq.github.io/lynq
helm repo update

# Step 4: Install Lynq
helm install lynq lynq/lynq \
  --namespace lynq-system \
  --create-namespace
```

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

### Setup Kind Cluster

Source: https://github.com/k8s-lynq/lynq/blob/main/scripts/README_KIND.md

Creates and configures a kind cluster with customizable Kubernetes version, cert-manager installation, webhook configuration, and port mappings. Use environment variables to customize settings.

```bash
./scripts/setup-kind.sh
```

```bash
KIND_CLUSTER=my-test-cluster \
KIND_K8S_VERSION=v1.29.0 \
CERT_MANAGER_VERSION=v1.16.3 \
./scripts/setup-kind.sh
```

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

### Install Dependencies (Bash)

Source: https://github.com/k8s-lynq/lynq/blob/main/dashboard/README.md

Run this command to install all project dependencies for both the UI and BFF.

```bash
make install
```

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

### Create Example Directory for New Datasource

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/contributing-datasource.md

Create a dedicated directory within `config/samples/` for your new datasource's example manifests. This organizes sample configurations for easy access.

```bash
# Create example directory
mkdir -p config/samples/yourdatasource
```

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

### Build, Test, and Install Project

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/contributing-datasource.md

Commands to build the project, run tests and linters, install Custom Resource Definitions (CRDs), and run the application locally.

```bash
# 1. Build
make build

# 2. Run tests
make test

# 3. Run linter
make lint

# 4. Install CRDs
make install

# 5. Run locally
make run
```

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

### Template Examples for Deployment Image

Source: https://github.com/k8s-lynq/lynq/blob/main/AGENTS.md

Example of using a template to set the image for a Deployment, with a default value if the variable is not provided.

```yaml
image: "{{ default \"nginx:stable\" .deployImage }}"
```

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

### Template Examples for Deployment Image and Value

Source: https://github.com/k8s-lynq/lynq/blob/main/CLAUDE.md

Examples showing how to dynamically set the image and other values in a Deployment spec using template variables and functions.

```yaml
image: "{{ default \"nginx:stable\" .deployImage }}"
```

```yaml
value: "{{ .host }}"
```

```yaml
value: "{{ .uid }}"
```

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

### Start BFF Server (Bash)

Source: https://github.com/k8s-lynq/lynq/blob/main/dashboard/README.md

Execute this command in a separate terminal to start the Go backend-for-frontend development server.

```bash
make dev-bff
```

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

### Install Lynq for Production

Source: https://github.com/k8s-lynq/lynq/blob/main/chart/README.md

Install the Lynq Helm chart for production environments using production values. Ensure cert-manager is installed and ready before running this command.

```bash
helm install lynq k8s-lynq/lynq \
  -f https://raw.githubusercontent.com/k8s-lynq/lynq/main/chart/values-prod.yaml \
  --namespace lynq-system \
  --create-namespace
```

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

### Install Lynq from Source

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/installation.md

Installs Lynq from its source code. This involves cloning the repository, installing Custom Resource Definitions (CRDs), and ensuring cert-manager is installed.

```bash
# Clone repository
git clone https://github.com/k8s-lynq/lynq.git
cd lynq

# Install CRDs
make install

# Install cert-manager first if not already installed
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
```

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

### Complete Example with Type Conversions

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/templates.md

This example demonstrates the practical application of `toInt`, `toBool`, and `toFloat` within a Kubernetes `LynqForm` resource definition to correctly set various fields.

```yaml
apiVersion: lynq.sh/v1
kind: LynqForm
metadata:
  name: typed-app
spec:
  hubId: production-db
  deployments:
    - id: app
      nameTemplate: "{{ .uid }}-api"
      spec:
        apiVersion: apps/v1
        kind: Deployment
        spec:
          # Integer field - type conversion required
          replicas: "{{ .maxReplicas | default "2" | toInt }}"
          template:
            spec:
              # Boolean field - type conversion required
              automountServiceAccountToken: "{{ .mountToken | toBool }}"
              containers:
                - name: app
                  image: "{{ .image }}"
                  ports:
                    # Integer field - type conversion required
                    - containerPort: "{{ .appPort | toInt }}"
                      protocol: TCP
                  env:
                    # String fields - no conversion needed
                    - name: APP_ENV
                      value: "{{ .environment }}"
                    - name: TENANT_ID
                      value: "{{ .uid }}"
                    # Integer env var - stays as string (env values are always strings)
                    - name: MAX_CONNECTIONS
                      value: "{{ .maxConns }}"
                  resources:
                    limits:
                      # Float field - type conversion required
                      cpu: "{{ .cpuLimit | toFloat }}"
                      memory: "{{ .memoryLimit }}Mi"
                    requests:
                      cpu: "{{ .cpuRequest | toFloat }}"
                      memory: "{{ .memoryRequest }}Mi"
```

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

### Template Examples for Value Interpolation

Source: https://github.com/k8s-lynq/lynq/blob/main/AGENTS.md

Examples demonstrating how to interpolate variables like '.host' and '.uid' into resource values.

```yaml
value: "{{ .host }}"
```

```yaml
value: "{{ .uid }}"
```

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

### Prepare Minikube Cluster

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/quickstart.md

Bootstraps the base cluster with cert-manager and Lynq CRDs. Ensure kubectl get nodes shows Ready, kubectl get pods -n cert-manager, and kubectl get crds | grep lynq.

```bash
./scripts/setup-minikube.sh
```

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

### Install Go Dependencies

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/development.md

Download all the necessary Go modules for the project. This should be run after cloning the repository.

```bash
go mod download
```

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

### Install BFF Dependencies (Bash)

Source: https://github.com/k8s-lynq/lynq/blob/main/dashboard/README.md

Run this command to install only the Go dependencies for the BFF server.

```bash
# Install Go dependencies
make install-bff
```

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

### Setup Minikube for Feature A

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/local-development-minikube.md

Sets up a Minikube instance specifically for 'Feature A', allowing parallel development.

```bash
MINIKUBE_PROFILE=feature-a ./scripts/setup-minikube.sh
```

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

### Example Output for Verified Flux Resources

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/integration-flux.md

Example output showing a successfully fetched GitRepository, including its URL, readiness status, and the fetched revision.

```bash
# Example output:
# NAME                                              URL                                      READY   STATUS
# gitrepository.source.toolkit.fluxcd.io/acme-gitrepo   https://github.com/myorg/my-fleet   True    Fetched revision: main@sha1:abc123
```

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

### Install cert-manager for air-gapped environments

Source: https://github.com/k8s-lynq/lynq/blob/main/chart/CERT-MANAGER.md

In air-gapped environments, you must first load cert-manager images into your private registry. Then, install cert-manager using Helm, specifying your private registry for the images. Finally, install Lynq, also pointing to your private registry if necessary.

```bash
helm install cert-manager jetstack/cert-manager \
  --set image.repository=my-registry.com/cert-manager-controller \
  --set webhook.image.repository=my-registry.com/cert-manager-webhook \
  --set cainjector.image.repository=my-registry.com/cert-manager-cainjector

helm install lynq k8s-lynq/lynq \
  --set image.registry=my-registry.com
```

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

### Install UI Dependencies (Bash)

Source: https://github.com/k8s-lynq/lynq/blob/main/dashboard/README.md

Run this command to install only the Node.js dependencies for the UI.

```bash
# Install Node dependencies
make install-ui
```

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

### Install lynq Helm Chart

Source: https://github.com/k8s-lynq/lynq/blob/main/chart/README.md

Install the lynq Helm chart using a custom values file, specifying the namespace and creating it if it doesn't exist. Ensure cert-manager is installed if webhooks are enabled.

```bash
helm install lynq k8s-lynq/lynq \
  -f values-prod.yaml \
  --namespace lynq-system \
  --create-namespace
```

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

### Install Kind for E2E Tests

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/development.md

Installs the Kind (Kubernetes in Docker) tool, which is a prerequisite for running End-to-End tests.

```bash
# Install Kind (required for E2E tests)
# macOS
brew install kind

# Linux
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.25.0/kind-linux-amd64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind

# Verify installation
kind version
```

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

### Minimal Dependencies Example

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/dependencies.md

Illustrates specifying only the essential dependency for a resource. The 'Bad' example shows an unnecessary dependency being listed.

```yaml
- id: app
  dependIds: ["secret"]  # Only essential dependency
```

```yaml
- id: app
  dependIds: ["secret", "unrelated-resource"]  # Unnecessary wait
```

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

### Custom Lynq Installation

Source: https://github.com/k8s-lynq/lynq/blob/main/chart/README.md

Install the Lynq Helm chart with custom configurations for image tag, webhook enablement, and monitoring.

```bash
helm install lynq k8s-lynq/lynq \
  --set image.tag=v1.0.0 \
  --set webhook.enabled=true \
  --set monitoring.enabled=true \
  --namespace lynq-system \
  --create-namespace
```

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

### Install Lynq for Local Development

Source: https://github.com/k8s-lynq/lynq/blob/main/chart/README.md

Install the Lynq Helm chart using local development values. This configuration is suitable for minikube or kind and uses lower resource requirements.

```bash
helm install lynq k8s-lynq/lynq \
  -f https://raw.githubusercontent.com/k8s-lynq/lynq/main/chart/values-local.yaml \
  --namespace lynq-system \
  --create-namespace
```

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

### Install cert-manager and Lynq

Source: https://github.com/k8s-lynq/lynq/blob/main/chart/CERT-MANAGER.md

Standard installation steps for cert-manager and the Lynq operator. Ensures full validation, defaulting, and consistent behavior across all environments.

```bash
# Step 1: Install cert-manager
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml

# Step 2: Wait for cert-manager to be ready
kubectl wait --for=condition=Available --timeout=300s -n cert-manager \
  deployment/cert-manager \
  deployment/cert-manager-webhook \
  deployment/cert-manager-cainjector

# Step 3: Verify
kubectl get pods -n cert-manager

# Step 4: Install lynq
helm install lynq k8s-lynq/lynq \
  --namespace lynq-system \
  --create-namespace
```

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

### Install for Local Development

Source: https://github.com/k8s-lynq/lynq/blob/main/chart/README.md

Install the lynq chart using a local development values file. This configuration is optimized for minikube, kind, or k3d, with webhooks and cert-manager enabled.

```bash
# Install cert-manager first (REQUIRED)
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
kubectl wait --for=condition=Available --timeout=300s -n cert-manager deployment/cert-manager-webhook

# Install lynq
helm install lynq k8s-lynq/lynq \
  -f values-local.yaml \
  --namespace lynq-system \
  --create-namespace
```

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

### Start UI Dev Server (Bash)

Source: https://github.com/k8s-lynq/lynq/blob/main/dashboard/README.md

Run this command in a separate terminal to start the React UI development server using Vite.

```bash
make dev-ui
```

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

### Local Development Installation with cert-manager

Source: https://github.com/k8s-lynq/lynq/blob/main/chart/CERT-MANAGER.md

Install cert-manager and Lynq using local development values for optimized resource settings. This ensures development mirrors production behavior.

```bash
# Install cert-manager (same as above)
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
kubectl wait --for=condition=Available --timeout=300s -n cert-manager deployment/cert-manager-webhook

# Install with local development values
helm install lynq k8s-lynq/lynq \
  -f https://raw.githubusercontent.com/k8s-lynq/lynq/main/chart/values-local.yaml \
  --namespace lynq-system \
  --create-namespace
```

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

### Install ExternalDNS with Helm

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/use-case-custom-domains.md

Installs ExternalDNS using Helm, configuring it for AWS, filtering domains to 'saas.example.com', setting the policy to 'sync', and using TXT records for ownership.

```bash
helm repo add external-dns https://kubernetes-sigs.github.io/external-dns/
helm install external-dns external-dns/external-dns \
  --set provider=aws \
  --set domainFilters[0]=saas.example.com \
  --set policy=sync \
  --set registry=txt \
  --set txtOwnerId=lynq-cluster
```

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

### Install Flux CLI and Bootstrap

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/integration-flux.md

Installs the Flux CLI and bootstraps a new GitOps repository structure for your cluster. Ensure you replace 'myorg' and 'fleet-infra' with your actual organization and repository names.

```bash
curl -s https://fluxcd.io/install.sh | sudo bash
```

```bash
flux bootstrap github \
  --owner=myorg \
  --repository=fleet-infra \
  --branch=main \
  --path=clusters/my-cluster \
  --personal
```

```bash
flux bootstrap gitlab \
  --owner=myorg \
  --repository=fleet-infra \
  --branch=main \
  --path=clusters/my-cluster \
  --personal
```

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

### Template Examples for Name Generation

Source: https://github.com/k8s-lynq/lynq/blob/main/AGENTS.md

Examples of using nameTemplate with different variable interpolations and function calls. Ensure names adhere to Kubernetes 63-character limits.

```yaml
nameTemplate: "{{ .uid }}-api"
```

```yaml
nameTemplate: "{{ .uid | trunc63 }}"
```

```yaml
nameTemplate: "{{ .uid }}-{{ .planId | default \"basic\" }}"
```

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

### Start with Docker Compose (Bash)

Source: https://github.com/k8s-lynq/lynq/blob/main/dashboard/README.md

Use this command to bring up the entire development environment, including the UI and BFF, using Docker Compose.

```bash
make docker-up
```

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

### Clone Repository and Install CRDs

Source: https://github.com/k8s-lynq/lynq/blob/main/README.md

Clone the Lynq repository, navigate to the directory, install the Custom Resource Definitions (CRDs), and then run the operator locally. This is the initial setup for development.

```bash
git clone https://github.com/k8s-lynq/lynq.git
cd lynq

# Install CRDs
make install

# Run locally
make run

# Run tests
make test
```

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

### Development Workflow for New Adapter

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/development.md

Step-by-step commands for developing a new datasource adapter, from creating the file to testing and running locally.

```bash
# 1. Create adapter file
touch internal/datasource/postgres.go

# 2. Implement interface
# (Copy mysql.go as template)

# 3. Register in factory
vim internal/datasource/interface.go

# 4. Add API types
vim api/v1/lynqhub_types.go

# 5. Generate manifests
make manifests

# 6. Write tests
touch internal/datasource/postgres_test.go

# 7. Test
make test

# 8. Lint
make lint

# 9. Build
make build

# 10. Test locally
make install
make run
kubectl apply -f config/samples/postgres/

```

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

### Example of a Complete Healthy Reconciliation Cycle

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/troubleshooting.md

Illustrates the log output during a successful reconciliation process, from start to status update. Useful for comparing against problematic logs.

```log
$ kubectl logs -n lynq-system deployment/lynq-controller-manager --tail=50

# ✅ Phase 1: Start
2024-01-15T10:30:00.000Z INFO  controller.lynqnode  Reconciliation started  {"node": "acme-web", "namespace": "production"}

# ✅ Phase 2: Finalizer Check
2024-01-15T10:30:00.010Z DEBUG controller.lynqnode  Finalizer present  {"node": "acme-web"}

# ✅ Phase 3: Variable Resolution
2024-01-15T10:30:00.020Z DEBUG controller.lynqnode  Variables resolved  {"uid": "acme", "host": "acme.example.com", "planId": "enterprise"}

# ✅ Phase 4: Dependency Graph
2024-01-15T10:30:00.030Z DEBUG controller.lynqnode  Dependency graph built  {"nodes": 4, "edges": 3, "cycles": false}
2024-01-15T10:30:00.031Z DEBUG controller.lynqnode  Apply order determined  {"order": ["secret", "configmap", "deployment", "service"]}

# ✅ Phase 5: Orphan Cleanup
2024-01-15T10:30:00.040Z DEBUG controller.lynqnode  Checking for orphaned resources  {"previous": 4, "current": 4}
2024-01-15T10:30:00.041Z DEBUG controller.lynqnode  No orphaned resources found

# ✅ Phase 6: Resource Apply (each resource)
2024-01-15T10:30:00.100Z INFO  controller.lynqnode  Applying resource  {"kind": "Secret", "name": "acme-creds", "id": "creds"}
2024-01-15T10:30:00.150Z INFO  controller.lynqnode  Resource applied  {"kind": "Secret", "name": "acme-creds", "result": "configured"}

2024-01-15T10:30:00.200Z INFO  controller.lynqnode  Applying resource  {"kind": "ConfigMap", "name": "acme-config", "id": "config"}
2024-01-15T10:30:00.250Z INFO  controller.lynqnode  Resource applied  {"kind": "ConfigMap", "name": "acme-config", "result": "unchanged"}

2024-01-15T10:30:00.300Z INFO  controller.lynqnode  Applying resource  {"kind": "Deployment", "name": "acme-api", "id": "app"}
2024-01-15T10:30:00.400Z INFO  controller.lynqnode  Waiting for readiness  {"kind": "Deployment", "name": "acme-api", "timeout": "300s"}
2024-01-15T10:30:15.000Z INFO  controller.lynqnode  Resource ready  {"kind": "Deployment", "name": "acme-api", "waited": "14.6s"}

2024-01-15T10:30:15.100Z INFO  controller.lynqnode  Applying resource  {"kind": "Service", "name": "acme-api", "id": "svc"}
2024-01-15T10:30:15.150Z INFO  controller.lynqnode  Resource applied  {"kind": "Service", "name": "acme-api", "result": "configured"}

# ✅ Phase 7: Status Update
2024-01-15T10:30:15.200Z INFO  controller.lynqnode  Status updated  {"ready": 4, "desired": 4, "failed": 0, "skipped": 0}
```

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

### Seed MySQL Test Database

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/quickstart.md

Installs a MySQL 8.0 instance with sample node rows inside lynq-test. This step requires the Lynq operator to be running and the lynq-test namespace to exist. Confirm the mysql Deployment/Service is running and check the database and secrets with kubectl exec and kubectl get secret.

```bash
./scripts/deploy-mysql.sh
```

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

### MySQL Adapter Constructor and Connection Pooling

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/contributing-datasource.md

Illustrates how to establish a MySQL connection, configure connection pooling settings, and perform an initial connection test.

```go
func NewMySQLAdapter(config Config) (*MySQLAdapter, error) {
    // 1. Build connection string
    dsn := fmt.Sprintf("%s:%s@tcp(%s:%d)/%s?parseTime=true", ...) 

    // 2. Open connection
    db, err := sql.Open("mysql", dsn)

    // 3. Configure connection pool
    db.SetMaxOpenConns(25)
    db.SetMaxIdleConns(5)
    db.SetConnMaxLifetime(5 * time.Minute)

    // 4. Test connection
    if err := db.PingContext(ctx); err != nil {
        return nil, err
    }

    return &MySQLAdapter{db: db}, nil
}
```

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

### Create Datasource Sample Files

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/contributing-datasource.md

These commands create the necessary YAML files for a new datasource's configuration samples.

```bash
touch config/samples/yourdatasource/hub.yaml
touch config/samples/yourdatasource/secret.yaml
touch config/samples/yourdatasource/template.yaml
```

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

### Install Cert-Manager

Source: https://github.com/k8s-lynq/lynq/blob/main/chart/templates/NOTES.txt

Install cert-manager using its official manifest. This is required if you enable webhooks and do not have cert-manager installed.

```bash
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
```

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

### Dry-run lynq Helm Installation

Source: https://github.com/k8s-lynq/lynq/blob/main/chart/README.md

Perform a dry-run installation of the lynq Helm chart locally. This command checks if the chart can be rendered and installed without actually making changes to the cluster.

```bash
helm install lynq ./chart \
  --dry-run --debug \
  --namespace lynq-system
```

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

### Install Lynq with existing cert-manager

Source: https://github.com/k8s-lynq/lynq/blob/main/chart/CERT-MANAGER.md

If cert-manager is already installed in your cluster, simply install the Lynq chart using Helm. The chart will automatically detect and utilize the existing cert-manager instance.

```bash
helm install lynq k8s-lynq/lynq
```

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

### Install Lynq Dashboard using Helm Chart

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/dashboard.md

Install the Lynq Helm chart, enabling the dashboard component. This command adds the Helm repository, updates it, and installs the chart with the dashboard enabled.

```bash
# Add Helm repo
helm repo add lynq https://k8s-lynq.github.io/lynq
helm repo update

# Install with Dashboard
helm install lynq lynq/lynq \
  --namespace lynq-system \
  --create-namespace \
  --set dashboard.enabled=true
```

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

### Create Demo Namespace

Source: https://github.com/k8s-lynq/lynq/blob/main/killercoda/lynq-existing-resources/step1.md

Create a Kubernetes namespace named 'lynq-demo' to host the demonstration resources. This isolates the demo environment.

```bash
kubectl create namespace lynq-demo
```

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

### Setup Minikube with Custom Resource Allocations

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/local-development-minikube.md

Sets up a Minikube cluster with increased CPU and memory resources, suitable for load testing or demanding workloads.

```bash
MINIKUBE_CPUS=8 \
MINIKUBE_MEMORY=16384 \
./scripts/setup-minikube.sh
```

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

### Lynq Event Examples

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/monitoring.md

Examples of success, conflict, and deletion events generated by Lynq.

```bash
# Success
TemplateAppliedComplete: Applied 10 resources (10 ready, 0 failed, 2 changed)

# Conflict
ResourceConflict: Resource conflict detected for default/acme-app (Kind: Deployment, Policy: Stuck).
Another controller or user may be managing this resource.

# Deletion
LynqNodeDeleting: Deleting Node 'acme-prod-template' (template: prod-template, uid: acme) -
no longer in active dataset. This could be due to: row deletion, activate=false, or template change.
```

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

### Install Specific Alpha Version for Local Development

Source: https://github.com/k8s-lynq/lynq/blob/main/chart/README.md

Install a specific alpha version of the Lynq Helm chart for local development, including the --devel flag. Ensure cert-manager is installed first.

```bash
helm install lynq k8s-lynq/lynq \
  -f https://raw.githubusercontent.com/k8s-lynq/lynq/v1.1.0-alpha.2/chart/values-local.yaml \
  --version 1.1.0-alpha.2 \
  --devel \
  --namespace lynq-system \
  --create-namespace
```

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

### Build Binary

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/development.md

Use this make command to build the project's binary executable.

```bash
make build
```

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

### Basic Template Syntax Examples

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/templates.md

Demonstrates basic variable substitution, function usage, conditionals, and default values in Lynq templates.

```yaml
# Basic variable substitution
nameTemplate: "{{ .uid }}-app"
```

```yaml
# With function
nameTemplate: "{{ .uid | trunc63 }}"
```

```yaml
# Conditional
nameTemplate: "{{ if .region }}{{ .region }}-{{ end }}{{ .uid }}"
```

```yaml
# Default value
nameTemplate: "{{ .uid }}-{{ .planId | default \"basic\" }}"
```

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

### Verify Installed CRDs

Source: https://github.com/k8s-lynq/lynq/blob/main/killercoda/lynq-existing-resources/step4.md

Lists Custom Resource Definitions (CRDs) related to Lynq to confirm their installation.

```bash
kubectl get crds | grep lynq
```

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

### Create New Adapter File

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/contributing-datasource.md

Demonstrates the command to create a new Go file for a custom datasource adapter within the internal/datasource directory.

```bash
# Example: PostgreSQL
touch internal/datasource/postgres.go

# Example: MongoDB
touch internal/datasource/mongodb.go

# Example: REST API
touch internal/datasource/rest.go
```

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

### Setup Minikube for Feature B

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/local-development-minikube.md

Sets up a Minikube instance specifically for 'Feature B', enabling parallel development.

```bash
MINIKUBE_PROFILE=feature-b ./scripts/setup-minikube.sh
```

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

### Install cert-manager

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/use-case-custom-domains.md

Installs cert-manager using kubectl to manage SSL certificate provisioning. Ensure you are using a compatible version.

```bash
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.2/cert-manager.yaml
```

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

### Go Code Style - Good Example

Source: https://github.com/k8s-lynq/lynq/blob/main/CONTRIBUTING.md

Demonstrates correct Go error handling and structure within a Kubernetes controller's Reconcile function.

```go
// Good
func (r *LynqNodeReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    logger := log.FromContext(ctx)

    // Get LynqNode
    lynqnode := &lynqv1.LynqNode{}
    if err := r.Get(ctx, req.NamespacedName, lynqnode); err != nil {
        if errors.IsNotFound(err) {
            return ctrl.Result{}, nil
        }
        return ctrl.Result{}, err
    }

    // Business logic...

    return ctrl.Result{}, nil
}
```

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

### Install Crossplane via Helm

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/integration-crossplane.md

Installs Crossplane using the official Helm chart. Ensure you have Helm and kubectl configured.

```bash
helm repo add crossplane-stable https://charts.crossplane.io/stable
helm repo update
helm install crossplane crossplane-stable/crossplane \
  --namespace crossplane-system \
  --create-namespace \
  --wait
```

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

### Customize Minikube Setup with Environment Variables

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/quickstart.md

Configure Minikube resources like CPUs and memory when setting up the environment using environment variables.

```bash
# Example: Custom cluster configuration
MINIKUBE_CPUS=8 MINIKUBE_MEMORY=16384 ./scripts/setup-minikube.sh
```

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

### Check Lynq CRDs Installation

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/dashboard.md

Verify that the necessary Custom Resource Definitions (CRDs) for Lynq are installed in your Kubernetes cluster.

```bash
kubectl get crd | grep lynq
```

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

### Describe LynqNode for Readiness Issues

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/troubleshooting.md

Use `kubectl describe` on the LynqNode to get detailed information, including events and conditions, which can help pinpoint the cause of resources not being ready.

```bash
# Identify which resources are not ready
kubectl describe lynqnode <name>
```

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

### Run BFF with Specific Context (Bash)

Source: https://github.com/k8s-lynq/lynq/blob/main/dashboard/README.md

Example of running the BFF development server with a specified Kubernetes context.

```bash
cd bff && go run ./cmd/server -mode local -context my-cluster
```

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

### LynqForm Template Example

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/blog/maxskew-implementation-lessons.md

Example of a LynqForm template that applies to multiple LynqNodes. Changes to this template can trigger widespread updates.

```yaml
apiVersion: lynq.sh/v1
kind: LynqForm
spec:
  deployments:
    - id: app
      spec:
        template:
          spec:
            containers:
              - image: app:v2  # Changed from v1 to v2
```

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

### Install cert-manager

Source: https://github.com/k8s-lynq/lynq/blob/main/chart/README.md

Apply the cert-manager manifest and wait for the webhook deployment to become available. This is a prerequisite for installing lynq with webhooks enabled.

```bash
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
kubectl wait --for=condition=Available --timeout=300s -n cert-manager deployment/cert-manager-webhook
```

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

### Typical Development Cycle Commands

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/local-development-minikube.md

Execute these commands sequentially to make code changes, run tests, lint, build, deploy, and verify the operator on Minikube.

```bash
# 1. Make code changes
vim internal/controller/lynqnode_controller.go

# 2. Run unit tests
make test

# 3. Run linter
make lint

# 4. Build and deploy to Minikube
./scripts/deploy-to-minikube.sh

# 5. View operator logs
kubectl logs -n lynq-system -l control-plane=controller-manager -f

# 6. Test changes
kubectl apply -f config/samples/

# 7. Verify results
kubectl get lynqnodes
kubectl get all -n node-<uid>

# 8. Repeat steps 1-7 as needed
```

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

### Conventional Commits Examples

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/development.md

Examples of conventional commit messages for various types of changes, including features, fixes, documentation, and tests.

```text
feat: add new feature
fix: fix bug
docs: update documentation
test: add tests
refactor: refactor code
chore: maintenance tasks
```

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

### Verify Lynq Setup

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/quickstart.md

Commands to check the status of LynqNodes, associated resources, and operator logs.

```bash
# Check LynqNode CRs
kubectl get lynqnodes
```

```bash
# Check node resources
kubectl get deployments,services -l lynq.sh/node
```

```bash
# View operator logs
kubectl logs -n lynq-system -l control-plane=controller-manager -f
```

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

### Install Crossplane Providers

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/integration-crossplane.md

Installs necessary Crossplane providers for AWS S3, RDS, CloudFront, and a SQL provider. Waits for them to become healthy.

```yaml
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-aws-s3
spec:
  package: xpkg.upbound.io/upbound/provider-aws-s3:v1.1.0
---
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-aws-rds
spec:
  package: xpkg.upbound.io/upbound/provider-aws-rds:v1.1.0
---
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-aws-cloudfront
spec:
  package: xpkg.upbound.io/upbound/provider-aws-cloudfront:v1.1.0
---
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-sql
spec:
  package: xpkg.upbound.io/crossplane-contrib/provider-sql:v0.9.0
```

```bash
kubectl wait --for=condition=Healthy provider.pkg.crossplane.io --all --timeout=5m
```

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

### Check Prometheus Operator Installation

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/monitoring.md

Confirm that the Prometheus Operator is installed in the cluster by checking for the existence of the `ServiceMonitor` Custom Resource Definition (CRD).

```bash
kubectl get crd servicemonitors.monitoring.coreos.com
```

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

### Run UI Dev Server (Bash)

Source: https://github.com/k8s-lynq/lynq/blob/main/dashboard/README.md

Starts the Vite development server for the React UI. It proxies API requests to the BFF.

```bash
# Run Vite dev server (http://localhost:5173)
make dev-ui
```

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

### Install ExternalDNS with upsert-only Policy

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/integration-external-dns.md

Install ExternalDNS using Helm with the 'upsert-only' policy to prevent accidental deletion of existing DNS records.

```bash
helm install external-dns bitnami/external-dns \
  --set policy=upsert-only
```

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

### Install cert-manager

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/troubleshooting.md

Install cert-manager, which is required for webhook TLS certificates. This command applies the cert-manager manifest and waits for its core components to become available.

```bash
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
```

```bash
kubectl wait --for=condition=Available --timeout=300s -n cert-manager \
  deployment/cert-manager \
  deployment/cert-manager-webhook \
  deployment/cert-manager-cainjector
```

```bash
kubectl get pods -n cert-manager
```

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

### Install Lynq Operator via Helm

Source: https://context7.com/k8s-lynq/lynq/llms.txt

Installs the Lynq Operator using Helm into a dedicated namespace. Ensure the namespace is created if it doesn't exist.

```bash
helm install lynq lynq/lynq \
  --namespace lynq-system \
  --create-namespace
```

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

### Manual Build and Load into Minikube

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/local-development-minikube.md

If needed, manually build the operator binary locally, build the Docker image, and then load it into Minikube's registry.

```bash
# Build binary locally
make build

# Build Docker image
make docker-build IMG=lynq:dev

# Load into Minikube
minikube -p lynq image load lynq:dev
```

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

### Deploy MySQL with Initial Data

Source: https://github.com/k8s-lynq/lynq/blob/main/killercoda/lynq-quickstart/step3.md

Applies Kubernetes resources to set up a MySQL database, including credentials, initialization scripts with sample tenant data, the deployment, and a service.

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: mysql-credentials
  namespace: lynq-demo
type: Opaque
stringData:
  root-password: "rootpass123"
  password: "lynqpass123"
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: mysql-init
  namespace: lynq-demo
data:
  init.sql: |
    CREATE DATABASE IF NOT EXISTS tenants;
    USE tenants;

    CREATE TABLE IF NOT EXISTS tenant_configs (
      id INT AUTO_INCREMENT PRIMARY KEY,
      tenant_id VARCHAR(63) NOT NULL UNIQUE,
      tenant_url VARCHAR(255),
      is_active BOOLEAN DEFAULT true,
      plan VARCHAR(50) DEFAULT 'basic',
      created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
    );

    -- Insert sample tenants
    INSERT INTO tenant_configs (tenant_id, tenant_url, is_active, plan) VALUES
    ('acme-corp', 'https://acme.example.com', true, 'enterprise'),
    ('beta-inc', 'https://beta.example.com', true, 'basic'),
    ('gamma-ltd', 'https://gamma.example.com', false, 'basic');

    -- Create read-only user for Lynq
    CREATE USER IF NOT EXISTS 'lynq_reader'@'%' IDENTIFIED BY 'lynqpass123';
    GRANT SELECT ON tenants.* TO 'lynq_reader'@'%';
    FLUSH PRIVILEGES;
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mysql
  namespace: lynq-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mysql
  template:
    metadata:
      labels:
        app: mysql
    spec:
      containers:
      - name: mysql
        image: mysql:8.0
        env:
        - name: MYSQL_ROOT_PASSWORD
          valueFrom:
            secretKeyRef:
              name: mysql-credentials
              key: root-password
        ports:
        - containerPort: 3306
        readinessProbe:
          exec:
            command:
            - mysqladmin
            - ping
            - -h
            - "127.0.0.1"
            - -uroot
            - -prootpass123
          initialDelaySeconds: 10
          periodSeconds: 5
          timeoutSeconds: 5
        volumeMounts:
        - name: init-script
          mountPath: /docker-entrypoint-initdb.d
      volumes:
      - name: init-script
        configMap:
          name: mysql-init
---
apiVersion: v1
kind: Service
metadata:
  name: mysql
  namespace: lynq-demo
spec:
  selector:
    app: mysql
  ports:
  - port: 3306
    targetPort: 3306
```

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

### LynqForm Example for Dependency Visualizer

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/dependencies.md

This YAML defines a LynqForm with several resources and their dependencies. It's used as an example input for the dependency visualizer tool.

```yaml
apiVersion: lynq.sh/v1
kind: LynqForm
metadata:
  name: my-app
spec:
  hubId: customer-hub
  secrets:
    - id: db-creds
  deployments:
    - id: db
      dependIds: ["db-creds"]
    - id: app
      dependIds: ["db"]
  services:
    - id: app-svc
      dependIds: ["app"]
```

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

### Verify Flux Installation

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/integration-flux.md

Commands to verify that Flux controllers are installed correctly, check Flux CRDs, display the Flux version, and confirm the cluster status.

```bash
kubectl get pods -n flux-system
```

```bash
kubectl get crd | grep fluxcd
```

```bash
flux --version
```

```bash
flux check
```

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

### Verify Initial State (Bash)

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/use-case-blue-green.md

Check the current active color, deployed versions, Kubernetes deployments, service selector, and production traffic to establish the baseline before deployment.

```bash
# 1. Check current active color in database
mysql -e "SELECT node_id, active_color, blue_version, green_version FROM nodes WHERE node_id='acme-corp'"
# Expected output:
# +-----------+--------------+--------------+---------------+ 
# | node_id   | active_color | blue_version | green_version | 
# +-----------+--------------+--------------+---------------+ 
# | acme-corp | blue         | v1.0.0       | v1.0.0        | 
# +-----------+--------------+--------------+---------------+ 

# 2. Check deployments in Kubernetes
kubectl get deployment -l app=acme-corp

# Expected output:
# NAME              READY   UP-TO-DATE   AVAILABLE   REPLICAS   AGE
# acme-corp-blue    3/3     3            3           3          5h
# acme-corp-green   1/1     1            1           1          5h

# 3. Verify service selector
kubectl get svc acme-corp-app -o jsonpath='{.spec.selector}' | jq
# Expected: {"app":"acme-corp","color":"blue"}

# 4. Verify traffic is going to blue
curl -s https://acme.example.com/version
# Expected: v1.0.0 (blue version)
```

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

### Apply LynqForm

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/quickstart.md

Defines the blueprint for each active node. Ensure the LynqHub is ready and you have necessary permissions.

```bash
./scripts/deploy-lynqform.sh
```

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

### Install AWS Provider and Configure Credentials

Source: https://github.com/k8s-lynq/lynq/blob/main/docs/use-case-database-per-tenant.md

Installs the AWS provider for Crossplane and configures AWS credentials and a ProviderConfig. Ensure your AWS credentials file is correctly set up.

```bash
kubectl apply -f - <<EOF
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-aws
spec:
  package: xpkg.upbound.io/upbound/provider-aws:v0.40.0
EOF

# Configure AWS credentials
kubectl create secret generic aws-creds -n crossplane-system \
  --from-file=credentials=$HOME/.aws/credentials

# Create ProviderConfig
kubectl apply -f - <<EOF
apiVersion: aws.upbound.io/v1beta1
kind: ProviderConfig
metadata:
  name: default
spec:
  credentials:
    source: Secret
    secretRef:
      namespace: crossplane-system
      name: aws-creds
      key: credentials
EOF
```