Lynq

https://lynq.sh/
Admin
Lynq is a data-driven automation platform that transforms database records into Kubernetes resources...
Tokens:153,928
Snippets:1,980
Trust Score:7.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Lighter Resource Density Setup Example

Source: https://lynq.sh/resource-sizing

Calculates CPU usage for a setup with a lower number of resources per node.

```plaintext
total_managed = 500 × 3 = 1,500
CPU ≈ 1,500 × 0.55 = 825 m
```

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

### Heavier Resource Density Setup Example

Source: https://lynq.sh/resource-sizing

Calculates CPU usage for a setup with a higher number of resources per node.

```plaintext
total_managed = 2 × 100 × 15 = 3,000
CPU ≈ 3,000 × 0.55 = 1,650 m
```

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

### Fresh Start Setup for Minikube

Source: https://lynq.sh/local-development-minikube.html

Perform a complete reset by cleaning up the existing cluster, recreating it, and then deploying the operator.

```bash
# Complete reset
./scripts/cleanup-minikube.sh  # Delete everything
./scripts/setup-minikube.sh    # Recreate cluster
./scripts/deploy-to-minikube.sh  # Deploy operator
```

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

### PostgreSQL Adapter Implementation

Source: https://lynq.sh/contributing-datasource.html

A complete example of a PostgreSQL data source adapter, including connection setup, query execution, and result scanning. Use this as a reference for implementing your own adapters.

```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 Datasource Examples

Source: https://lynq.sh/contributing-datasource.html

Applies example configurations for a datasource using kubectl.

```bash
kubectl apply -f config/samples/yourdatasource/secret.yaml
kubectl apply -f config/samples/yourdatasource/hub.yaml
```

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

### Install Lynq from Source

Source: https://lynq.sh/installation.html

Installs Lynq by cloning the repository, installing CRDs, and deploying the operator. Ensure you are in the cloned lynq directory.

```bash
git clone https://github.com/k8s-lynq/lynq.git
cd lynq
make install                                    # install CRDs
make deploy IMG=ghcr.io/k8s-lynq/lynq:latest  # deploy operator
```

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

### Install Lynq using Kustomize

Source: https://lynq.sh/installation.html

Applies the Lynq installation configuration using Kustomize.

```bash
kubectl apply -k https://github.com/k8s-lynq/lynq/config/default
```

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

### Install Lynq using Helm

Source: https://lynq.sh/installation.html

Installs Lynq using Helm by adding the Lynq Helm repository and performing an upgrade. This is the recommended installation method.

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

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

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

### Get Deployment Apply Start Time

Source: https://lynq.sh/troubleshooting.html

Retrieve the annotation indicating when Lynq started applying changes to a deployment.

```bash
kubectl get deploy <name> -o jsonpath='{.metadata.annotations.lynq\.sh/apply-start-time}{"\n"}'
```

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

### Create Example Directory and Files for YourDatasource

Source: https://lynq.sh/contributing-datasource.html

Use these bash commands to set up the necessary directory structure and empty files for a new datasource example. This is a prerequisite for adding specific configuration details.

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

# Add example files
touch config/samples/yourdatasource/hub.yaml
touch config/samples/yourdatasource/secret.yaml
touch config/samples/yourdatasource/template.yaml
```

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

### Start UI Dev Server

Source: https://lynq.sh/dashboard.html

Starts the UI development server for the dashboard. Access it at http://localhost:5173.

```bash
cd dashboard
make dev-ui
```

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

### Datasource Configuration Example

Source: https://lynq.sh/contributing-datasource.html

Example of basic configuration for a new datasource in LynqHub. Ensure prerequisites like datasource version and network connectivity are met.

```yaml
apiVersion: operator.lynq.sh/v1
kind: LynqHub
metadata:
  name: my-hub
spec:
  source:
    type: yourdatasource
    yourdatasource:
      host: your-host.example.com
      port: 5432
      username: node_reader
      passwordRef:
        name: yourdatasource-credentials
        key: password
      database: nodes_db
      table: nodes
    syncInterval: 1m
  valueMappings:
    uid: node_id
    hostOrUrl: node_url
    activate: is_active

```

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

### Start kubectl Proxy for Local Dev (Exec-Plugin)

Source: https://lynq.sh/dashboard.html

Starts a local kubectl proxy on port 8001, used for the local development server setup when dealing with EKS or exec-plugin clusters. This proxy handles authentication on the host side.

```bash
kubectl proxy --port=8001 --context=<your-context>
```

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

### Install Kind for E2E Tests

Source: https://lynq.sh/development.html

Provides instructions for installing the Kind tool on macOS and Linux, 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
```

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

### Install Crossplane using Helm

Source: https://lynq.sh/integration-crossplane.html

Installs Crossplane into the 'crossplane-system' namespace using Helm. Ensures the namespace is created and waits for the installation to complete.

```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

```

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

### Install Crossplane AWS Providers

Source: https://lynq.sh/integration-crossplane.html

Installs the 'provider-aws-rds' and 'provider-sql' Crossplane providers. It waits for all installed providers to become healthy.

```bash
cat <<EOF | kubectl apply -f -
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-sql
spec:
  package: xpkg.upbound.io/crossplane-contrib/provider-sql:v0.9.0
EOF

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

```

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

### Start Local Dev Server BFF with Proxy Kubeconfig

Source: https://lynq.sh/dashboard.html

Creates a temporary kubeconfig file pointing to a local kubectl proxy and then starts the BFF (Backend For Frontend) server for the Lynq dashboard. This is for development with exec-plugin clusters.

```bash
cat > /tmp/lynq-proxy.kubeconfig << 'EOF' \
apiVersion: v1 \
kind: Config \
clusters: \
- cluster: \
    server: http://localhost:8001 \
  name: proxy \
contexts: \
- context: \
    cluster: proxy \
    user: "" \
  name: proxy \
current-context: proxy \
users: [] \
EOF

cd dashboard
KUBECONFIG=/tmp/lynq-proxy.kubeconfig go run ./bff/cmd/server -mode local -addr :8080 -context proxy
```

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

### Install Go Dependencies

Source: https://lynq.sh/development.html

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

```bash
go mod download
```

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

### Configure and Setup Minikube Cluster

Source: https://lynq.sh/local-development-minikube.html

Set the number of CPUs and memory for Minikube before running the setup script. This is useful for creating a more powerful cluster for load testing.

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

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

### Lynq Resource Limits Configuration

Source: https://lynq.sh/installation.html

Example configuration for resource limits (CPU and memory) for the Lynq manager. These defaults are shipped with the installation.

```yaml
# config/manager/manager.yaml (shipped defaults)
resources:
  limits:
    cpu: 500m
    memory: 128Mi
  requests:
    cpu: 10m
    memory: 64Mi
```

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

### Basic LynqForm YAML Example

Source: https://lynq.sh/template-builder.html

This is a minimal example of a LynqForm resource, specifying the hub ID.

```yaml
apiVersion: operator.lynq.sh/v1
kind: LynqForm
metadata:
  name: my-form
spec:
  hubId: my-hub

```

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

### Install cert-manager

Source: https://lynq.sh/local-development-minikube.html

Installs cert-manager and waits for its webhook to become available. Ensure cert-manager is not already installed.

```bash
kubectl get pods -n cert-manager
kubectl get certificate -n lynq-system
kubectl describe certificate -n lynq-system
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
```

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

### Troubleshoot Operator Not Starting

Source: https://lynq.sh/quickstart

Check cert-manager status and Lynq controller logs if the operator is not starting. Ensure cert-manager is Ready.

```bash
kubectl get pods -n cert-manager
kubectl logs -n lynq-system -l control-plane=controller-manager
```

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

### Git Repository Structure Example

Source: https://lynq.sh/integration-flux.html

Example structure for a Git repository intended to hold node configurations for Flux.

```bash
my-fleet/
├── base/                    # Shared base configurations
│   ├── deployment.yaml
│   ├── service.yaml
│   └── kustomization.yaml
├── nodes/                   # Per-node overlays
│   ├── node-alpha/
│   │   ├── kustomization.yaml
│   │   └── patches.yaml
│   ├── node-beta/
│   │   ├── kustomization.yaml
│   │   └── patches.yaml
└── README.md
```

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

### Install Flux CLI and Bootstrap GitOps Repository

Source: https://lynq.sh/integration-flux.html

Installs the Flux CLI and bootstraps a GitOps repository for managing Kubernetes cluster configurations. Use the GitHub or GitLab bootstrap command based on your Git provider.

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

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

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

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

### Applied Resources Format Examples

Source: https://lynq.sh/api-lifecycle

Examples of the 'Kind/Namespace/Name@id' format used to track applied resources for orphan detection.

```text
Deployment/default/acme-app@deploy-main
Service/default/acme-svc@svc-main
Namespace/acme-ns@ns-main
```

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

### LynqHub Example Resource

Source: https://lynq.sh/api-lynqhub

A complete example of a LynqHub custom resource definition, including source configuration, value mappings, and extra value mappings.

```yaml
apiVersion: operator.lynq.sh/v1
kind: LynqHub
metadata:
  name: production-nodes
  namespace: lynq-system
spec:
  source:
    type: mysql
    mysql:
      host: mysql.default.svc.cluster.local
      port: 3306
      username: node_reader
      passwordRef:
        name: mysql-credentials
        key: password
      database: saas_db
      table: node_configs
    syncInterval: 1m
  valueMappings:
    uid: node_id
    activate: is_active
  extraValueMappings:
    planId: subscription_plan
    region: deployment_region
```

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

### Start Local Dev Server UI

Source: https://lynq.sh/dashboard.html

Starts the UI development server for the Lynq dashboard using npm. This enables hot-reloading for UI development. Access the UI at http://localhost:5173 or the next available port.

```bash
cd dashboard
npm --prefix ui run dev
```

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

### Dependency Management Example

Source: https://lynq.sh/architecture.html

Defines a deployment and a service that depends on it. The service will only be applied after the deployment is ready.

```yaml
deployments:
  - id: app
    # ...
services:
  - id: svc
    dependIds: ["app"]   # applies only after app is ready
    waitForReady: true
```

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

### Template Variable Usage Example

Source: https://lynq.sh/template-builder.html

Demonstrates how to use template variables within resource configurations.

```go-template
{{ .uid }}-app
{{ .host }}

```

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

### Install Lynq Helm Chart with Dashboard

Source: https://lynq.sh/dashboard.html

Install the Lynq Helm chart, enabling the Dashboard component. This command adds the Helm repository and installs the chart into the 'lynq-system' namespace.

```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
```

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

### Dependency Example with dependIds

Source: https://lynq.sh/api-lynqform

Demonstrates how to define resource dependencies using `dependIds`. The 'deployment' resource will only be applied after the 'configmap' resource is ready.

```yaml
- id: configmap
  nameTemplate: "{{ .uid }}-config"
  spec: ...

- id: deployment
  dependIds: [configmap]    # applied only after configmap is ready
  nameTemplate: "{{ .uid }}-app"
  spec: ...
```

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

### Correct IgnoreFields Syntax Example

Source: https://lynq.sh/field-ignore.html

Demonstrates the correct syntax for ignoreFields, highlighting a common typo.

```yaml
# Wrong
ignoreFields: ["$.spec.template.spec.container[0].image"]
                                          # ^^^ missing 's'

# Correct
ignoreFields: ["$.spec.template.spec.containers[0].image"]
```

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

### nameTemplate Examples

Source: https://lynq.sh/api-lynqform

Examples of using Go templates for the nameTemplate field to generate Kubernetes metadata.name. Ensures names are valid and within length constraints.

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

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

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

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

### Install ExternalDNS for Cloudflare

Source: https://lynq.sh/integration-external-dns.html

Installs ExternalDNS using the Bitnami Helm chart for Cloudflare. Requires an API token and domain filter.

```bash
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

helm install external-dns bitnami/external-dns \
  --namespace kube-system \
  --set provider=cloudflare \
  --set cloudflare.apiToken=<your-api-token> \
  --set domainFilters[0]=example.com
```

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

### Benchmark Verification Calculation

Source: https://lynq.sh/resource-sizing

Example calculation to verify the resource usage formulas against observed metrics.

```plaintext
total_managed = (74 × 9) + (73 × 3) + (73 × 2) = 666 + 219 + 146 = 1,031

CPU  ≈ 1,031 × 0.55 = 567 m  → observed 500–600 m ✓
Mem  ≈ 30 + 1,031 × 0.1 = 133 MB → observed 100–140 MB ✓
```

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

### LynqForm Complete Example with Type Conversion

Source: https://lynq.sh/templates-typed-values

This example demonstrates the use of type conversion for integers, booleans, and floats within a LynqForm definition. It shows how to apply default values and convert input variables to the appropriate types for fields like replicas, container ports, service account token mounting, and resource limits/requests.

```yaml
apiVersion: operator.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:
          replicas: "{{ .maxReplicas | default \"2\" | int }}"
          template:
            spec:
              automountServiceAccountToken: "{{ .mountToken | bool }}"
              containers:
                - name: app
                  image: "{{ .image }}"
                  ports:
                    - containerPort: "{{ .appPort | int }}"
                      protocol: TCP
                  env:
                    # String fields — no conversion needed
                    - name: APP_ENV
                      value: "{{ .environment }}"
                    - name: NODE_ID
                      value: "{{ .uid }}"
                    # Integer env var — keep as string (env values are always strings)
                    - name: MAX_CONNECTIONS
                      value: "{{ .maxConns }}"
                  resources:
                    limits:
                      cpu: "{{ .cpuLimit | float }}"
                      memory: "{{ .memoryLimit }}Mi"
                    requests:
                      cpu: "{{ .cpuRequest | float }}"
                      memory: "{{ .memoryRequest }}Mi"

```

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

### Unnecessary Dependencies Example (Bad Practice)

Source: https://lynq.sh/dependencies.html

Illustrates a bad practice of including unnecessary dependencies, which can lead to longer deployment times.

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

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

### Define Database Table and Sample Data

Source: https://lynq.sh/how-it-works.html

Sets up the 'customers' table with essential fields and populates it with sample data for demonstration.

```sql
-- Your existing customers table
CREATE TABLE customers (
  id VARCHAR(36) PRIMARY KEY,
  name VARCHAR(255),
  domain VARCHAR(255),
  plan VARCHAR(50),
  active BOOLEAN DEFAULT true,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Sample data
INSERT INTO customers VALUES
  ('acme-corp', 'Acme Corporation', 'acme.example.com', 'enterprise', true, NOW()),
  ('startup-io', 'Startup IO', 'startup.example.com', 'starter', true, NOW()),
  ('inactive-co', 'Inactive Co', 'inactive.example.com', 'basic', false, NOW());

```

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

### Create Namespace

Source: https://lynq.sh/dashboard.html

Creates the 'lynq-system' namespace if it doesn't already exist. This is optional if the Lynq Operator is already installed.

```bash
kubectl create namespace lynq-system --dry-run=client -o yaml | kubectl apply -f -
```

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

### Kubernetes Job Definition

Source: https://lynq.sh/blog/managing-resource-lifecycle

A basic Kubernetes Job definition for database initialization. This example demonstrates a common setup that can lead to unintended repeated executions.

```yaml
jobs:
  - id: db-init
    nameTemplate: "{{ .uid }}-db-init"
    spec:
      apiVersion: batch/v1
      kind: Job
      spec:
        template:
          spec:
            containers:
            - name: init
              image: postgres:15
              command: ["psql", "-c", "CREATE DATABASE app;"]
            restartPolicy: Never
```

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

### Clone Lynq Repository

Source: https://lynq.sh/development.html

Clone the Lynq repository and navigate into the project directory. This is the first step before installing dependencies or building the project.

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

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

### Check Provider Status

Source: https://lynq.sh/integration-crossplane.html

Use `kubectl get providers` to check the installation status of Crossplane providers. If a provider is unhealthy, use `kubectl describe provider` and `kubectl logs` for detailed diagnostics.

```bash
kubectl get providers
kubectl describe provider provider-aws-rds
kubectl logs -n crossplane-system -l pkg.crossplane.io/provider=provider-aws-rds
```

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

### Extra Value Mappings Example

Source: https://lynq.sh/api-lynqhub

Illustrates how to map additional database columns to template variables for use in LynqNode configurations.

```yaml
extraValueMappings:
  planId: subscription_plan   # → {{ .planId }}
  region: aws_region          # → {{ .region }}
  nodeUrl: node_url           # → {{ .nodeUrl | toHost }} for hostname extraction

```

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

### Example Timeline: Failed Dependency

Source: https://lynq.sh/dependencies.html

Shows the timeline when a dependency fails. Dependent resources are skipped, and `DependencySkipped` events are emitted.

```text
T=0s:  Deployment created with invalid image
T=20s: Deployment fails (ImagePullBackOff, timeout exceeded)
       DependencySkipped event emitted for ConfigMap
       skippedResources: 1
```

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

### Build Project

Source: https://lynq.sh/contributing-datasource.html

Builds the project using the make command.

```bash
make build
```

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

### Install ExternalDNS using Helm

Source: https://lynq.sh/integration-external-dns.html

Recommended method for installing ExternalDNS on a Kubernetes cluster using Helm. Ensure Helm is installed and configured for your cluster.

```bash
helm install external-dns external-dns/external-dns --namespace kube-system
```

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

### Install CRDs

Source: https://lynq.sh/development.html

Installs the Custom Resource Definitions required for the operator.

```bash
make install
```

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

### Readiness Gates: Wait for Resource Readiness

Source: https://lynq.sh/dependencies.html

This example demonstrates using `waitForReady: true` to ensure a dependent resource is not only created but also ready before proceeding.

```yaml
deployments:
  - id: db
    waitForReady: true
    timeoutSeconds: 300

deployments:
  - id: app
    dependIds: ["db"]  # Wait for db to exist AND be ready
    waitForReady: true
```

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

### Setup and Cleanup E2E Test Environment

Source: https://lynq.sh/development.html

Sets up the Kind cluster and necessary components for E2E tests, and cleans them up afterward. This is useful for running specific tests or for development workflows.

```bash
make setup-test-e2e
```

```bash
make cleanup-test-e2e
```

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

### List MySQL Databases

Source: https://lynq.sh/quickstart

Connect to the MySQL instance and list all available databases to confirm its operational status.

```bash
kubectl exec -it deployment/mysql -n lynq-test -- mysql -e "SHOW DATABASES;"
```

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

### Install and Deploy Operator on Minikube

Source: https://lynq.sh/local-development-minikube.html

Commands to install CRDs, rebuild, and deploy the operator to Minikube.

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

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

### Install Delve Debugger

Source: https://lynq.sh/local-development-minikube.html

Installs the Delve debugger, a necessary tool for debugging Go applications.

```bash
go install github.com/go-delve/delve/cmd/dlv@latest
```

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

### MySQL Adapter Implementation

Source: https://lynq.sh/contributing-datasource.html

Illustrates the structure and methods of a MySQL datasource adapter, including connection establishment, query execution, and resource management.

```go
// Adapter struct - holds connection
type MySQLAdapter struct {
    db *sql.DB
}

// Constructor - establishes connection
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
}

// QueryNodes - query and map data
func (a *MySQLAdapter) QueryNodes(ctx context.Context, config QueryConfig) ([]NodeRow, error) {
    // 1. Build query
    query := fmt.Sprintf("SELECT %s FROM %s", columns, table)

    // 2. Execute query
    rows, err := a.db.QueryContext(ctx, query)

    // 3. Scan results
    var nodes []NodeRow
    for rows.Next() {
        // Map columns to NodeRow
        // Filter active nodes
    }

    return nodes, nil
}

// Close - cleanup
func (a *MySQLAdapter) Close() error {
    if a.db != nil {
        return a.db.Close()
    }
    return nil
}
```

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

### Install Flux GitHub Receiver

Source: https://lynq.sh/integration-flux.html

Installs a Flux receiver for GitHub events. Requires a webhook secret.

```bash
flux create receiver github-receiver \
  --type github \
  --event ping \
  --event push \
  --secret-ref webhook-token \
  --resource GitRepository/my-gitrepo
```

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

### Troubleshooting Operator Startup Issues

Source: https://lynq.sh/local-development-minikube.html

Commands to check pod status, logs, and common issues like cert-manager readiness, webhook certificates, image loading, and CRD installation.

```bash
# Check pod status
kubectl get pods -n lynq-system

# Check logs
kubectl logs -n lynq-system -l control-plane=controller-manager

# Common issues:

# 1. cert-manager not ready
kubectl get pods -n cert-manager
# If pods are not running, wait or check:
kubectl describe pods -n cert-manager

# 2. Webhook certificates not ready
kubectl get certificate -n lynq-system
# Should show "Ready=True"

# 3. Image not loaded
minikube -p lynq image ls | grep lynq

# 4. CRDs not installed
kubectl get crd | grep lynq
```

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

### Minimal Dependencies Best Practice

Source: https://lynq.sh/dependencies.html

Shows the recommended practice of specifying only essential dependencies to avoid unnecessary waiting times.

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

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

### Install cert-manager

Source: https://lynq.sh/installation.html

Installs cert-manager, which is required for managing webhook TLS certificates. Waits for all cert-manager components to be ready.

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

# Wait for all three cert-manager components to be ready
kubectl wait --for=condition=Available --timeout=300s -n cert-manager \
  deployment/cert-manager \
  deployment/cert-manager-webhook \
  deployment/cert-manager-cainjector
```

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

### Structured JSON Log Example

Source: https://lynq.sh/monitoring.html

All logs are structured in JSON format. This example shows a typical info-level log message.

```json
{"level":"info","ts":"2025-01-15T10:30:00Z","msg":"Reconciliation completed","lynqnode":"acme-web","ready":10,"failed":0}
```

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

### Example Timeline: Successful Dependency

Source: https://lynq.sh/dependencies.html

Illustrates the timeline when a dependency is progressing but not yet ready. Dependent resources are blocked, not skipped, and no skip events are emitted.

```text
T=0s:  Deployment created, status: Progressing
       ConfigMap blocked (dependency not ready yet)
       NO DependencySkipped event

T=30s: Reconcile runs, Deployment still Progressing
       ConfigMap still blocked
       NO DependencySkipped event

T=45s: Deployment becomes Ready
       Reconcile runs, ConfigMap created
       SUCCESS - no skip events emitted
```

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

### Build Local Dev Server BFF with Make

Source: https://lynq.sh/dashboard.html

Builds and starts the BFF (Backend For Frontend) server for the Lynq dashboard using the Make utility. This command is suitable for standard clusters using certificate-based authentication in the kubeconfig.

```bash
cd dashboard
make dev-bff
```

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

### Install cert-manager

Source: https://lynq.sh/troubleshooting.html

Install cert-manager if it's not already present. This command applies the cert-manager manifest and waits for its deployments to become available.

```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 \
  deployment/cert-manager-webhook \
  deployment/cert-manager-cainjector
```

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

### Register New Controller in Main

Source: https://lynq.sh/development.html

Register the newly created controller with the manager in the main application entry point. Ensure proper error handling during setup.

```go
if err = (&controller.MyResourceReconciler{
    Client: mgr.GetClient(),
    Scheme: mgr.GetScheme(),
}).SetupWithManager(mgr); err != nil {
    // Handle error
}
```

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

### Typical Development Cycle

Source: https://lynq.sh/local-development-minikube.html

This bash script outlines the typical development cycle for making changes to Lynq and testing them locally on Minikube.

```bash
make install
make deploy
make docker-build docker-push
make deploy-operator
make test
```

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

### Verify Lynq Installation

Source: https://lynq.sh/installation.html

Verifies the Lynq installation by checking the deployment status of the controller manager and listing custom resource definitions (CRDs).

```bash
kubectl get deployment -n lynq-system lynq-controller-manager
kubectl get crd | grep operator.lynq.sh
```

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

### Manual Build and Load Docker Image to Minikube

Source: https://lynq.sh/local-development-minikube.html

Manually build the operator binary, build the Docker image with a specified tag, and then load the image into Minikube's internal registry if needed.

```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
```

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

### Healthy Lynq Hub Status Example

Source: https://lynq.sh/troubleshooting.html

Example of a healthy Lynq hub status, indicating successful synchronization and a desired number of nodes.

```yaml
status:
  conditions:
  - type: Ready
    status: "True"
    reason: SyncSuccess
    message: "Successfully synced 5 nodes from database"
  desired: 10          # activeRows × referencingForms
  ready: 10
  referencingTemplates: 2
  lastSyncTime: "2024-01-15T10:30:00Z"
```

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

### Build Kustomization Manifests

Source: https://lynq.sh/integration-flux.html

Builds Kustomization manifests from a specified path.

```bash
kustomize build ./path/to/manifests
```

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

### Install ExternalDNS for AWS Route53

Source: https://lynq.sh/integration-external-dns.html

Installs ExternalDNS using the Bitnami Helm chart for AWS Route53. Configure with your domain filter and cluster ID.

```bash
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

helm install external-dns bitnami/external-dns \
  --namespace kube-system \
  --set provider=aws \
  --set aws.zoneType=public \
  --set domainFilters[0]=example.com \
  --set policy=upsert-only \
  --set txtOwnerId=my-cluster-id
```

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

### Failing Lynq Hub Status Example

Source: https://lynq.sh/troubleshooting.html

Example of a failing Lynq hub status, showing a connection error to the database and zero desired nodes.

```yaml
status:
  conditions:
  - type: Ready
    status: "False"
    reason: DatabaseConnectionFailed
    message: "Failed to connect to database: connection refused"
  desired: 0
  lastSyncTime: "2024-01-15T10:25:00Z"  # stale
```

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

### Good Dependency Graph Example

Source: https://lynq.sh/performance.html

Demonstrates a shallow dependency tree where resources can be created in parallel groups, leading to faster creation times. This is achieved by minimizing inter-resource dependencies.

```yaml
resources:
  - id: namespace      # No dependencies
  - id: deployment     # Depends on: namespace
  - id: service        # Depends on: deployment
# Depth: 3 - Resources can be created in parallel groups
```

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

### Create Simple Node Configuration Table

Source: https://lynq.sh/datasource.html

SQL schema for a basic node configuration table, including node ID, activation status, subscription plan, and deployment region.

```sql
CREATE TABLE node_configs (
    node_id         VARCHAR(255) PRIMARY KEY,
    is_active       TINYINT(1)  DEFAULT 0,
    subscription_plan VARCHAR(50),
    deployment_region VARCHAR(50)
);
```

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

### Shallow Dependency Tree Example

Source: https://lynq.sh/dependencies.html

Illustrates a good practice of maintaining shallow dependency trees for better manageability. This example shows a depth of 2.

```yaml
secret
  ├─ app
  │   └─ svc
  └─ db
      └─ db-svc
```

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

### Custom Resource Definition Example

Source: https://lynq.sh/blog/maxskew-implementation-lessons

Example of a Custom Resource (CR) definition for LynqForm, specifying manifests with nested Kubernetes resources like InnoDBCluster.

```yaml
apiVersion: operator.lynq.sh/v1
kind: LynqForm
spec:
  manifests:
    - id: mysql-cluster
      spec:
        apiVersion: mysql.oracle.com/v2
        kind: InnoDBCluster
        # ...

```

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

### Conventional Commit Message Examples

Source: https://lynq.sh/development.html

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

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

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

### BFF Server Architecture

Source: https://lynq.sh/blog/introducing-lynq-dashboard

Illustrates the communication flow between the browser, BFF server (Go), and Kubernetes API Server.

```text
[Browser] <-> [BFF Server (Go)] <-> [Kubernetes API Server]
```

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

### Check Lynq CRDs Installation

Source: https://lynq.sh/dashboard.html

Verify that the Lynq Operator Custom Resource Definitions (CRDs) are installed in the cluster. This command lists all CRDs and filters for those containing 'lynq'.

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

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

### Circular Dependency Example

Source: https://lynq.sh/dependencies.html

This example shows a circular dependency between a deployment and a config map, which will cause an error. The 'db' deployment depends on 'app-config', and 'app-config' depends on 'db'.

```yaml
deployments:
  - id: db
    dependIds: ["app-config"]
    spec:
      containers:
        - name: postgres
          env:
            - name: MAX_CONNECTIONS
              valueFrom:
                configMapKeyRef:
                  name: "{{ .uid }}-app-config"
                  key: max_connections

configMaps:
  - id: app-config
    dependIds: ["db"]  # Config needs DB host info (circular!)
    spec:
      data:
        database_host: "{{ .uid }}-db-svc"
        max_connections: "100"
```

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

### Install Flux Controllers via Manifests

Source: https://lynq.sh/integration-flux.html

Applies the Flux controllers directly to your Kubernetes cluster using the latest release manifest. This method is an alternative to using the Flux CLI for installation.

```bash
kubectl apply -f https://github.com/fluxcd/flux2/releases/latest/download/install.yaml
```

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

### Run Tests

Source: https://lynq.sh/contributing-datasource.html

Executes the project's test suite using the make command.

```bash
make test
```

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

### Install ExternalDNS with Upsert-Only Policy

Source: https://lynq.sh/integration-external-dns.html

Install ExternalDNS using Helm with the 'upsert-only' policy to prevent accidental deletion of existing DNS records. This enhances safety by only allowing record creation or updates.

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

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

### Manage Multiple Minikube Profiles

Source: https://lynq.sh/local-development-minikube.html

Sets up and deploys to separate Minikube profiles for different features, allowing simultaneous work. Includes commands to switch between contexts.

```bash
MINIKUBE_PROFILE=feature-a ./scripts/setup-minikube.sh
MINIKUBE_PROFILE=feature-a ./scripts/deploy-to-minikube.sh
MINIKUBE_PROFILE=feature-b ./scripts/setup-minikube.sh
MINIKUBE_PROFILE=feature-b ./scripts/deploy-to-minikube.sh
kubectl config use-context feature-a
kubectl config use-context feature-b
```

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

### Verify Active Preview Environments with kubectl

Source: https://lynq.sh/use-case-preview-environments

List all active preview environments in the 'lynq-system' namespace. This command helps in monitoring the status of your preview environments.

```bash
# List all active preview environments
kubectl get lynqnodes -n lynq-system -l lynq.sh/hub=preview-hub
# NAME                    READY   DESIRED   AGE
# pr-1234-preview-stack   True    3/3       2m
# pr-1235-preview-stack   True    3/3       5m
```

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

### Watch for New Preview Environments

Source: https://lynq.sh/use-case-preview-environments

Continuously monitor the 'lynq-system' namespace for new 'lynqnodes' to appear. This command is useful for observing the provisioning of new environments in real-time.

```bash
# Watch a new environment appear after CI inserts a row
kubectl get lynqnodes -n lynq-system -w
```

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

### Run Operator

Source: https://lynq.sh/development.html

Starts the Lynq operator.

```bash
make run
```

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

### Configure Deployment with CreationPolicy Once

Source: https://lynq.sh/blog/managing-resource-lifecycle

Define a deployment with `creationPolicy: Once` to set the initial replica count but then let other controllers manage it.

```yaml
deployments:
  - id: app
    creationPolicy: Once  # Set initial state, then hands-off
    nameTemplate: "{{ .uid }}-app"
    spec:
      apiVersion: apps/v1
      kind: Deployment
      spec:
        replicas: 3  # Initial value only
        # ...
```

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

### Describe Pod

Source: https://lynq.sh/troubleshooting.html

Get detailed information about a specific pod.

```bash
kubectl describe pod <pod-name>
```

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

### Troubleshoot Node Readiness

Source: https://lynq.sh/integration-crossplane.html

To diagnose why a node is not becoming Ready, use `kubectl describe lynqnode` to inspect its status and events.

```bash
kubectl describe lynqnode <name>
```

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

### Terraform Plan and Apply Workflow

Source: https://lynq.sh/blog/why-i-built-lynq

Illustrates the repetitive and time-consuming workflow of using Terraform for provisioning, highlighting the need for automation.

```bash
# This flow repeated every time
terraform plan -out=tfplan  # ... wait 10 minutes
# (go do something else, come back)
terraform apply tfplan      # ... wait again
```

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

### Get Deployment Logs

Source: https://lynq.sh/troubleshooting.html

Retrieve recent logs for a deployment.

```bash
kubectl logs deployment/<name> --tail=30
```

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

### Check Flux Version

Source: https://lynq.sh/integration-flux.html

Verify the installed version of the Flux CLI.

```bash
flux --version
```

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

### LynqHub Minimal Setup

Source: https://lynq.sh/use-case-database-per-tenant.html

Configures a LynqHub to read node data from a MySQL database and map specific fields to Lynq's internal structure.

```yaml
apiVersion: operator.lynq.sh/v1
kind: LynqHub
metadata:
  name: database-per-node
  namespace: lynq-system
spec:
  source:
    type: mysql
    syncInterval: 1m
    mysql:
      host: mysql.internal.svc.cluster.local
      port: 3306
      database: nodes_db
      table: nodes
      username: lynq_reader
      passwordRef:
        name: mysql-credentials
        key: password
  valueMappings:
    uid: node_id
    activate: is_active
  extraValueMappings:
    dbInstanceClass: db_instance_class
    dbStorageGb: db_storage_gb
    dbMultiAz: db_multi_az
    planType: plan_type
```
Tokens:
Raw