Crossplane

Manage PgBeam projects, databases, replicas, domains, and cache rules 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

The top-level resource. Each project gets a unique proxy hostname and is created with its primary upstream database.

apiVersion: pgbeam.io/v1alpha1
kind: Project
metadata:
  name: prod
spec:
  forProvider:
    orgId: org_abc123
    name: production
    cloud: aws
    queriesPerSecond: 1000
    burstSize: 200
    maxConnections: 500
    database:
      host: primary.us-east-1.rds.amazonaws.com
      port: 5432
      name: mydb
      username: pgbeam
      passwordSecretRef:
        name: db-credentials
        namespace: default
        key: password
      sslMode: require
      poolConfig:
        poolSize: 20
        minPoolSize: 5
        poolMode: transaction
      cacheConfig:
        enabled: true
        ttlSeconds: 60
        maxEntries: 10000
        swrSeconds: 30
  providerConfigRef:
    name: default

Status: proxyHost, status, databaseCount, activeConnections, primaryDatabaseId, createdAt, updatedAt

Database

Add additional upstream databases to a project. Useful for read replicas or multi-database setups.

apiVersion: pgbeam.io/v1alpha1
kind: Database
metadata:
  name: read-replica
spec:
  forProvider:
    projectId: proj_abc123
    host: replica.us-east-1.rds.amazonaws.com
    port: 5432
    name: mydb
    username: pgbeam
    passwordSecretRef:
      name: db-credentials
      namespace: default
      key: password
    role: replica
    poolConfig:
      poolSize: 20
      minPoolSize: 5
      poolMode: transaction
  providerConfigRef:
    name: default

Status: connectionString, role, sslMode, cacheConfig, poolConfig

Replica

Register a read replica endpoint under a database. PgBeam routes read queries to replicas automatically based on proximity.

Replicas are immutable — any spec change triggers recreation.

apiVersion: pgbeam.io/v1alpha1
kind: Replica
metadata:
  name: us-west
spec:
  forProvider:
    databaseId: db_abc123
    host: replica.us-west-2.rds.amazonaws.com
    port: 5432
    sslMode: require
  providerConfigRef:
    name: default

CustomDomain

Attach a custom domain to a project. Requires the Scale or Enterprise plan.

apiVersion: pgbeam.io/v1alpha1
kind: CustomDomain
metadata:
  name: prod-domain
spec:
  forProvider:
    projectId: proj_abc123
    domain: db.example.com
  providerConfigRef:
    name: default

After creation, configure DNS records from status.atProvider.dnsInstructions, then verify via the dashboard:

kubectl get customdomain prod-domain -o jsonpath='{.status.atProvider.dnsInstructions}'

CacheRule

Override per-query cache settings for a specific query shape.

apiVersion: pgbeam.io/v1alpha1
kind: CacheRule
metadata:
  name: hot-query
spec:
  forProvider:
    projectId: proj_abc123
    databaseId: db_abc123
    queryHash: a1b2c3d4e5f67890
    cacheEnabled: true
    cacheTtlSeconds: 300
    cacheSwrSeconds: 60
  providerConfigRef:
    name: default

Status: normalizedSql, queryType, callCount, avgLatencyMs, recommendation

Find query hashes in the PgBeam dashboard under the Cache Rules tab, or via the API's listCacheRules endpoint.

SpendLimit

Set a monthly spending cap for an organization.

apiVersion: pgbeam.io/v1alpha1
kind: SpendLimit
metadata:
  name: prod-limit
spec:
  forProvider:
    orgId: org_abc123
    spendLimit: 500
  providerConfigRef:
    name: default

When the limit is reached, the organization's projects are suspended until the next billing period. Deleting this resource resets the limit (no cap).

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`