Skip to content

crossplane.mdx

Latest commit

 

History

History
306 lines (250 loc) · 6.77 KB

crossplane.mdx

File metadata and controls

306 lines (250 loc) · 6.77 KB
title Crossplane
icon Blocks
tag Kubernetes
description Manage PgBeam projects, databases, replicas, custom domains, cache rules, and spend limits as Kubernetes custom resources using the Crossplane provider.

Manage your PgBeam infrastructure as Kubernetes custom resources with Crossplane. The provider-pgbeam package provides managed resources for projects, databases, replicas, custom domains, cache rules, and spend limits.

Setup

Install the provider

The Crossplane provider is coming soon. Registry publishing is on the roadmap. 
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-pgbeam
spec:
  package: ghcr.io/pgbeam/provider-pgbeam:latest
kubectl apply -f provider.yaml

Configure credentials

Create a Secret with your PgBeam API key, then reference it in a ProviderConfig:

apiVersion: v1
kind: Secret
metadata:
  name: pgbeam-credentials
  namespace: crossplane-system
type: Opaque
stringData:
  api-key: pgb_your_api_key
apiVersion: pgbeam.io/v1alpha1
kind: ProviderConfig
metadata:
  name: default
spec:
  apiKeySecretRef:
    name: pgbeam-credentials
    namespace: crossplane-system
    key: api-key
  baseURL: https://api.pgbeam.com # optional
kubectl apply -f secret.yaml -f provider-config.yaml

Create a project

apiVersion: pgbeam.io/v1alpha1
kind: Project
metadata:
  name: my-app
spec:
  forProvider:
    orgId: org_abc123
    name: my-app
    database:
      host: my-rds.us-east-1.rds.amazonaws.com
      port: 5432
      name: mydb
      username: pgbeam
      passwordSecretRef:
        name: db-credentials
        namespace: default
        key: password
  providerConfigRef:
    name: default

Apply

kubectl apply -f project.yaml

Crossplane creates the PgBeam project and its primary database atomically. The proxy hostname is available in status.atProvider.proxyHost and published to the connection secret.

kubectl get project my-app -o jsonpath='{.status.atProvider.proxyHost}'

Resources

Project

Manages a PgBeam project with a primary database.

apiVersion: pgbeam.io/v1alpha1
kind: Project
metadata:
  name: example
spec:
  forProvider:
    orgID: org_abc123
    name: my-app
    description: Production database proxy
    tags: ["production", "us-east-1"]
    allowedCidrs: [[object Object], [object Object]]
    status: active
  providerConfigRef:
    name: default

Status: proxyHost, queriesPerSecond, burstSize, maxConnections, databaseCount, activeConnections, createdAt, updatedAt, primaryDatabaseID

Database

Manages an upstream database connection within a PgBeam project.

apiVersion: pgbeam.io/v1alpha1
kind: Database
metadata:
  name: example
spec:
  forProvider:
    projectID: prj_01h455vb4pex5vsknk084sn02q
    host: db.example.com
    port: 5432
    name: mydb
    username: pgbeam
    sslMode: require
    role: primary
    poolRegion: us-east-1
    queryTimeoutMs: 0
    autoReadRouting: false
    cacheConfig:
      enabled: true
      ttlSeconds: 60
      maxEntries: 10000
      swrSeconds: 30
    poolConfig:
      poolSize: 20
      minPoolSize: 5
      poolMode: transaction
      maxActive: 200
    passwordSecretRef:
      name: credentials
      namespace: default
      key: password
  providerConfigRef:
    name: default

Status: connectionString, createdAt, updatedAt

Replica

Manages a read replica for a PgBeam database.

Replicas are immutable — any spec change triggers recreation.

apiVersion: pgbeam.io/v1alpha1
kind: Replica
metadata:
  name: example
spec:
  forProvider:
    databaseID: db_01h455vb4pex5vsknk084sn02q
    host: replica.db.example.com
    port: 5432
    sslMode: require
  providerConfigRef:
    name: default

Status: createdAt, updatedAt

CustomDomain

Manages a custom domain for a PgBeam project.

CustomDomains are immutable — any spec change triggers recreation.

apiVersion: pgbeam.io/v1alpha1
kind: CustomDomain
metadata:
  name: example
spec:
  forProvider:
    projectID: prj_01h455vb4pex5vsknk084sn02q
    domain: db.example.com
  providerConfigRef:
    name: default

Status: verified, verifiedAt, tlsCertExpiry, dnsVerificationToken, dnsInstructions, createdAt, updatedAt

CacheRule

Manages a per-query cache rule. Deletion disables caching (soft-delete).

apiVersion: pgbeam.io/v1alpha1
kind: CacheRule
metadata:
  name: example
spec:
  forProvider:
    projectID: prj_01h455vb4pex5vsknk084sn02q
    databaseID: db_01h455vb4pex5vsknk084sn02q
    queryHash: a1b2c3d4e5f60718
    cacheEnabled: true
    cacheTTLSeconds: 300
    cacheSWRSeconds: 60
  providerConfigRef:
    name: default

Status: queryHash, normalizedSQL, queryType, callCount, avgLatencyMs, p95LatencyMs, avgResponseBytes, stabilityRate, recommendation, firstSeenAt, lastSeenAt

SpendLimit

Manages the monthly spend limit for an organization.

apiVersion: pgbeam.io/v1alpha1
kind: SpendLimit
metadata:
  name: example
spec:
  forProvider:
    orgID: org_abc123
    spendLimit: 500
  providerConfigRef:
    name: default

Status: orgID, plan, billingProvider, subscriptionStatus, currentPeriodEnd, enabled, customPricing, limits, createdAt, updatedAt

Configuration

Setting Source Description
apiKeySecretRef ProviderConfig Secret reference for the API key
baseURL ProviderConfig API base URL (default: https://api.pgbeam.com)

Replacement vs update

Some spec changes trigger resource recreation rather than in-place updates:

Resource Recreation triggers
Project orgId, cloud
Database projectId
Replica Any spec change (immutable)
CustomDomain Any spec change (immutable)
CacheRule projectId, databaseId, queryHash
SpendLimit orgId

Further reading