Resource Providers

Resource providers automatically discover and sync your infrastructure into Ctrlplane’s resource inventory. This enables dynamic environment targeting based on resource metadata.

How It Works

Resource providers scan your infrastructure
Resources are created/updated in Ctrlplane’s inventory
Environments use selectors to dynamically match resources
When resources change, environments automatically update

Built-in Providers

Kubernetes

Sync Kubernetes clusters as resources:

type: ResourceProvider
name: kubernetes-clusters
provider: kubernetes
config:
  kubeconfig: /path/to/kubeconfig
  # Or use in-cluster config
  inCluster: true
resourceKind: KubernetesCluster
metadataMapping:
  region: metadata.labels.region
  environment: metadata.labels.environment
  provider: metadata.labels.cloud-provider

AWS

Sync AWS resources:

type: ResourceProvider
name: aws-resources
provider: aws
config:
  region: us-east-1
  accessKeyId: "{{.variables.aws_access_key}}"
  secretAccessKey: "{{.variables.aws_secret_key}}"
resources:
  - type: ec2:instance
    resourceKind: AWS/EC2
  - type: lambda:function
    resourceKind: AWS/Lambda
  - type: ecs:cluster
    resourceKind: AWS/ECS

Custom Resource Providers

Create custom providers using the Ctrlplane API or SDK.

Using the API

# Create or update a resource
curl -X PUT "https://your-ctrlplane-instance.com/api/v1/workspaces/{workspaceId}/resources" \
  -H "Authorization: Bearer $CTRLPLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "my-server-1",
    "name": "Production Server 1",
    "kind": "Server",
    "version": "1.0.0",
    "metadata": {
      "environment": "production",
      "region": "us-east-1",
      "team": "platform"
    },
    "config": {
      "host": "10.0.1.100",
      "port": 22
    }
  }'

Using the Node.js SDK

import { Ctrlplane } from "@ctrlplane/node-sdk";

const client = new Ctrlplane({ apiKey: process.env.CTRLPLANE_API_KEY });

// Sync resources from your infrastructure
async function syncResources() {
  const servers = await discoverServers(); // Your discovery logic

  for (const server of servers) {
    await client.resources.upsert({
      workspaceId: "your-workspace-id",
      identifier: server.id,
      name: server.hostname,
      kind: "Server",
      version: "1.0.0",
      metadata: {
        environment: server.environment,
        region: server.region,
        team: server.team,
      },
      config: {
        host: server.ip,
        port: 22,
      },
    });
  }
}

Using a Script

Run a script periodically to sync resources:

#!/bin/bash
# sync-resources.sh

# Discover resources (example: from cloud provider)
INSTANCES=$(aws ec2 describe-instances --query 'Reservations[].Instances[]')

# Sync each instance to Ctrlplane
echo "$INSTANCES" | jq -c '.[]' | while read instance; do
  INSTANCE_ID=$(echo "$instance" | jq -r '.InstanceId')
  NAME=$(echo "$instance" | jq -r '.Tags[] | select(.Key=="Name") | .Value')
  ENV=$(echo "$instance" | jq -r '.Tags[] | select(.Key=="Environment") | .Value')
  REGION=$(echo "$instance" | jq -r '.Placement.AvailabilityZone' | sed 's/.$//')

  curl -X PUT "https://your-ctrlplane-instance.com/api/v1/workspaces/${WORKSPACE_ID}/resources" \
    -H "Authorization: Bearer ${CTRLPLANE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d "{
      \"identifier\": \"${INSTANCE_ID}\",
      \"name\": \"${NAME}\",
      \"kind\": \"AWS/EC2\",
      \"version\": \"1.0.0\",
      \"metadata\": {
        \"environment\": \"${ENV}\",
        \"region\": \"${REGION}\"
      }
    }"
done

Resource Schema

Field	Required	Description
`identifier`	Yes	Unique identifier for the resource
`name`	Yes	Human-readable name
`kind`	Yes	Resource type (e.g., `KubernetesCluster`)
`version`	Yes	Resource version/schema version
`metadata`	No	Key-value pairs for filtering
`config`	No	Configuration data for job agents

Metadata vs Config

Metadata: Used for filtering and environment selectors
Config: Passed to job agents for deployment execution

# Good: metadata for filtering
metadata:
  environment: production
  region: us-east-1
  team: platform

# Good: config for deployment details
config:
  kubeconfig: "base64-encoded-config"
  namespace: my-app
  server: https://k8s.example.com

Environment Selectors

Environments use selectors to match resources:

type: Environment
name: Production US-East
resourceSelector: |
  resource.metadata["environment"] == "production" &&
  resource.metadata["region"] == "us-east-1"

When resources are added or updated, environments automatically re-evaluate their selectors.

Resource Lifecycle

Creating Resources

Resources are created via the API. Duplicate identifiers update the existing resource.

Updating Resources

When resource metadata or config changes, Ctrlplane:

Updates the resource in the inventory
Re-evaluates environment selectors
Updates release targets if needed

Deleting Resources

curl -X DELETE \
  "https://your-ctrlplane-instance.com/api/v1/resources/{resourceId}" \
  -H "Authorization: Bearer $CTRLPLANE_API_KEY"

When a resource is deleted:

It’s removed from all environments
Active releases are marked as orphaned
Jobs are not automatically canceled (handle gracefully)

Best Practices

Use Consistent Naming

# Good: consistent kind naming
kind: KubernetesCluster
kind: AWS/Lambda
kind: GCP/CloudRun

# Bad: inconsistent
kind: k8s
kind: aws-lambda
kind: cloud-run

Include Essential Metadata

metadata:
  environment: production # Required for environment selection
  region: us-east-1 # Useful for regional deployments
  team: platform # Useful for access control
  cost-center: eng-123 # Useful for tracking

Keep Config Minimal

Only include config needed for deployments:

# Good: minimal config
config:
  namespace: my-app
  cluster_url: https://k8s.example.com

# Bad: too much config
config:
  namespace: my-app
  cluster_url: https://k8s.example.com
  all_pods: [...]  # Don't include large datasets
  cluster_metrics: {...}  # Don't include monitoring data

Sync Frequently

Run resource sync on a schedule to keep inventory current:

# Kubernetes CronJob example
apiVersion: batch/v1
kind: CronJob
metadata:
  name: sync-resources
spec:
  schedule: "*/5 * * * *" # Every 5 minutes
  jobTemplate:
    spec:
      template:
        spec:
          containers:
            - name: sync
              image: your-sync-image
              command: ["/sync-resources.sh"]
          restartPolicy: OnFailure

​How It Works

​Built-in Providers

​Kubernetes

​AWS

​Custom Resource Providers

​Using the API

​Using the Node.js SDK

​Using a Script

​Resource Schema

​Metadata vs Config

​Environment Selectors

​Resource Lifecycle

​Creating Resources

​Updating Resources

​Deleting Resources

​Best Practices

​Use Consistent Naming

​Include Essential Metadata

​Keep Config Minimal

​Sync Frequently