Crossplane

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.

provider.yaml

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:

secret.yaml

apiVersion: v1
kind: Secret
metadata:
  name: pgbeam-credentials
  namespace: crossplane-system
type: Opaque
stringData:
  api-key: pgb_your_api_key

provider-config.yaml

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

project.yaml

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`