PgBeam Docs

Crossplane

Manage PgBeam projects, databases, replicas, custom domains, cache rules, spend limits, agent credentials, policy profiles, and webhook endpoints 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, spend limits, agent credentials, policy profiles, and webhook endpoints.

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

Policy profiles are managed as code. The PolicyProfile resource defines the full policy (access mode, allow and deny lists, masking rules, budgets, write mode) in the same reviewed IaC flow. Resources that reference a policy (defaultPolicyProfileID on a project, policyProfileID on an agent credential) take the ID of a PolicyProfile you manage in the same manifest.

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:
      - cidr: 203.0.113.0/24
        label: Office
      - cidr: 198.51.100.42/32
        label: CI/CD
    defaultPolicyProfileID: pol_01h455vb4pex5vsknk084sn02q
    agentsDisabled: false
    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

AgentCredential

Manages a scoped agent credential (a PgBeam-issued Postgres login plus a hosted MCP token) for an AI agent. The connection string and MCP token are one-time secrets returned only at creation and exposed as sensitive computed outputs; they cannot be retrieved again. To rotate the secrets, taint/replace the resource (or use the rotate endpoint out of band).

apiVersion: pgbeam.io/v1alpha1
kind: AgentCredential
metadata:
  name: example
spec:
  forProvider:
    projectID: prj_01h455vb4pex5vsknk084sn02q
    policyProfileID: pol_01h455vb4pex5vsknk084sn02q
    name: Claude Code (analytics)
    status: active
    principalType: agent
    expiresAt: ...
  providerConfigRef:
    name: default

Status: pgUsername, authMethod, lastUsedAt, createdAt, updatedAt, connectionString, mcpURL, mcpToken

PolicyProfile

Manages a policy profile: a named bundle of agent-gateway enforcement rules (access mode, table allow/deny lists, statement-kind rules, PII masking rules, per-relation row filters, query/egress budgets, write mode, approvals, and migration safety) attached to agent credentials and enforced in the PG wire protocol. Nested-list fields (masking_rules, row_filters) and the nested statement_rules object are expressed as structured config.

apiVersion: pgbeam.io/v1alpha1
kind: PolicyProfile
metadata:
  name: example
spec:
  forProvider:
    projectID: prj_01h455vb4pex5vsknk084sn02q
    name: Read-only analytics
    accessMode: read_only
    statementRules:
      allow: ["..."]
      deny: ["..."]
    tableAllowlist: ["..."]
    tableDenylist: ["..."]
    maskingRules: ["..."]
    budgetQueriesPerHour: 0
    budgetQueriesPerDay: 0
    maxRows: 0
    statementTimeoutMs: 0
    rowFilters: ["..."]
    writeMode: normal
    approvalMode: off
    approvalAutoMaxRows: 0
    approvalTimeoutSeconds: 300
    migrationSafety: off
    egressBytesPerDay: 0
  providerConfigRef:
    name: default

Status: createdAt, updatedAt

WebhookEndpoint

Manages a webhook endpoint that receives project audit and anomaly event deliveries. The signing secret is write-only and never returned by the API.

apiVersion: pgbeam.io/v1alpha1
kind: WebhookEndpoint
metadata:
  name: example
spec:
  forProvider:
    projectID: ...
    url: https://example.com/hooks/pgbeam
    format: json
    eventTypes: ["..."]
    enabled: true
    description: ...
    secretSecretRef:
      name: credentials
      namespace: default
      key: secret
  providerConfigRef:
    name: default

Status: createdAt, updatedAt

Configuration

SettingSourceDescription
apiKeySecretRefProviderConfigSecret reference for the API key
baseURLProviderConfigAPI base URL (default: https://api.pgbeam.com)

Replacement vs update

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

ResourceRecreation triggers
ProjectorgId, cloud
DatabaseprojectId
ReplicaAny spec change (immutable)
CustomDomainAny spec change (immutable)
CacheRuleprojectId, databaseId, queryHash
SpendLimitorgId
AgentCredentialprojectId, policyProfileId, name, principalType, expiresAt
PolicyProfileprojectId
WebhookEndpointprojectId

Further reading

Terraform HCL

Manage PgBeam projects, databases, replicas, custom domains, cache rules, spend limits, agent credentials, policy profiles, and webhook endpoints as infrastructure using Terraform and the pgbeam provider.

Vercel Marketplace Soon

Deploy PgBeam as a Vercel Marketplace integration. Provision connection pooling and query caching directly from your Vercel dashboard.

On this page

SetupInstall the providerConfigure credentialsCreate a projectApplyResourcesProjectDatabaseReplicaCustomDomainCacheRuleSpendLimitAgentCredentialPolicyProfileWebhookEndpointConfigurationReplacement vs updateFurther reading