Skip to main content
Resources are the deployment targets in Ctrlplane - the actual infrastructure where your software runs. They represent any infrastructure component you want to deploy to, whether it’s a Kubernetes cluster, EC2 instance, database, or custom platform.

​
Key Characteristics

Each resource in Ctrlplane has:
  • Identifier: Unique identifier within a workspace (e.g., k8s-us-east-prod-cluster)
  • Name: Human-readable display name
  • Kind: Resource type (e.g., kubernetes-cluster, ec2-instance, database)
  • Version: Schema version for the resource kind
  • Config: Structured JSON data specific to the resource type
  • Metadata: Key-value pairs used for filtering and selection
  • Provider: Optional reference to the resource provider that manages this resource
  • Workspace: Every resource belongs to a specific workspace

​
Resource Metadata

Metadata is crucial for resource selection in environments and deployments. Common metadata includes:
  • environment: “production”, “staging”, “development”
  • region: “us-east-1”, “eu-west-1”
  • cluster: Kubernetes cluster name
  • tier: “web”, “database”, “cache”
  • Custom attributes specific to your infrastructure
Example resource with metadata: 
{
  "identifier": "k8s-prod-us-east",
  "name": "Production Cluster - US East",
  "kind": "kubernetes-cluster",
  "version": "1.0",
  "config": {
    "clusterEndpoint": "https://k8s-prod.example.com",
    "namespace": "default"
  },
  "metadata": {
    "environment": "production",
    "region": "us-east-1",
    "cloud": "aws"
  }
}

​
How Resources Work

​
Resource Discovery

Resources are added to Ctrlplane via:
  1. Resource Providers: Automated discovery from cloud providers (AWS, GCP, Azure, etc.)
  2. API: Manual creation via REST API
  3. Integrations: Kubernetes operators, Terraform, or custom scripts

​
Resource Providers

Resource providers automatically discover and sync resources from external systems:
  • AWS Provider: Discovers EC2 instances, ECS clusters, etc.
  • Kubernetes Provider: Discovers clusters and namespaces
  • GCP Provider: Discovers GCE instances, GKE clusters, etc.
  • Azure Provider: Discovers Azure VMs, AKS clusters, etc.
  • Custom Providers: Build your own using the Resource Provider SDK
Providers continuously sync to keep resources up-to-date.

​
Resource Selection

Environments and deployments use selectors to filter resources. Selectors query resource metadata: 
{
  "type": "comparison",
  "operator": "equals",
  "key": "environment",
  "value": "production"
}
Complex selectors support AND, OR, NOT operations for sophisticated filtering.

​
Resource Variables

Attach variables to resources for deployment-specific configuration:
  • Kubernetes namespace names
  • Database connection strings
  • API endpoints
  • Secrets references
  • Custom deployment parameters
Variables can reference workspace secrets for sensitive data.

​
Resource Relationships

Resources can have relationships to other resources:
  • associated_with: General association (e.g., a VM associated with a VPC)
  • depends_on: Dependency relationship (e.g., an app depends on a database)
Relationships help model complex infrastructure topologies and can be used in deployment policies.

​
Release Targets

When you create a deployment in a system, Ctrlplane creates release targets for each valid combination of:
  • The deployment
  • An environment in the system
  • A resource matching both the environment and deployment selectors
Release targets track what version should be deployed to each resource in each environment.

​
Creating Resources

​
Via API

curl -X POST https://api.ctrlplane.dev/v1/workspaces/{workspaceId}/resources \
  -H "Content-Type: application/json" \
  -d '{
    "resources": [{
      "identifier": "k8s-prod-us-east",
      "name": "Production Cluster - US East",
      "kind": "kubernetes-cluster",
      "version": "1.0",
      "config": {
        "endpoint": "https://k8s.example.com"
      },
      "metadata": {
        "environment": "production",
        "region": "us-east-1"
      }
    }]
  }'

​
Via Resource Provider

Resource providers automatically sync resources: 
import { CtrlplaneClient } from "@ctrlplane/node-sdk";

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

const provider = client.resourceProvider({
  workspaceId: "workspace-id",
  name: "my-k8s-provider",
});

await provider.set([
  {
    identifier: "k8s-prod-us-east",
    name: "Production Cluster - US East",
    kind: "kubernetes-cluster",
    version: "1.0",
    config: { endpoint: "https://k8s.example.com" },
    metadata: { environment: "production" },
  },
]);

​
Best Practices

  1. Consistent Metadata: Use standardized metadata keys across all resources for reliable filtering.
  2. Unique Identifiers: Ensure resource identifiers are unique and descriptive.
  3. Resource Providers: Use resource providers for automated discovery rather than manual creation.
  4. Metadata Organization: Structure metadata hierarchically (e.g., cloud.aws.region).
  5. Regular Sync: Keep resources in sync with actual infrastructure state.
  6. Resource Variables: Use resource variables for deployment-specific configuration instead of hardcoding in job configs.
Resources are the deployment targets in Ctrlplane’s orchestration system, providing flexible infrastructure representation for your deployment workflows.