Skip to content

crossplane.mdx

Latest commit

 

History

History
432 lines (358 loc) · 11.6 KB

crossplane.mdx

File metadata and controls

432 lines (358 loc) · 11.6 KB
Raw
title Crossplane
icon Blocks
tag Kubernetes
description Manage PgBeam projects, databases, replicas, custom domains, cache rules, spend limits, agent credentials, policy profiles, webhook endpoints, and self host enrollments 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, webhook endpoints, and self host enrollments.

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

**Policy profiles are not yet managed as code.** Resources that reference a policy (`policy_profile_id` on an agent credential, `default_policy_profile_id` on a project) expect the ID of a profile created out of band with `pgbeam policies create` or the dashboard. There is no policy-profile resource in the providers yet, so the policy itself, the most security-sensitive primitive, lives outside your reviewed IaC flow and is invisible to drift detection. Track this before gating full adoption on policy-as-code.

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: "10.0.0.0/8", label: "VPC" },
        { cidr: "2001:db8::/32", label: "IPv6 range" },
      ]
    defaultPolicyProfileID: pol_01h455vb4pex5vsknk084sn02q
    residency: eu
    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, spendCapped, spendCappedAt, 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
    maxAffectedRows: 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

SelfHostEnrollment

Manages a self-host (BYOC) enrollment: a token a self-hosted proxy uses to authenticate to the control plane's config/audit stream. The token is a one-time secret returned only at creation and exposed as a sensitive computed output; it cannot be retrieved again. To rotate the token, replace the resource. Deletion revokes the enrollment.

SelfHostEnrollments are immutable; any spec change triggers recreation.

apiVersion: pgbeam.io/v1alpha1
kind: SelfHostEnrollment
metadata:
  name: example
spec:
  forProvider:
    orgID: org_abc123
    regionLabel: customer-vpc-us-east
    description: prod cluster
    expiresAt: ...
  providerConfigRef:
    name: default

Status: createdBy, createdAt, lastSeenAt, revokedAt, token

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, selfHosted
Database projectId
Replica Any spec change (immutable)
CustomDomain Any spec change (immutable)
CacheRule projectId, databaseId, queryHash
SpendLimit orgId
AgentCredential projectId, policyProfileId, name, principalType, expiresAt
PolicyProfile projectId
WebhookEndpoint projectId
SelfHostEnrollment Any spec change (immutable)

Further reading