ConfigHub Usage Guide

Goals

This rulebook helps you:

• Adopt ConfigHub's Configuration as Data approach for managing Kubernetes deployments
• Manage configuration variants across multiple environments (dev, staging, prod)
• Implement safe change workflows with review, approval, and rollback capabilities
• Eliminate configuration drift between desired and live state
• Automate configuration validation, transformation, and deployment

---

Key Concepts

Configuration as Data vs Infrastructure as Code

ConfigHub stores fully rendered, literal configuration (WET - Write Every Time) instead of templates with variables. This means:

• No Helm templates, no variable interpolation, no conditionals
• Every environment's config is stored independently in standard YAML
• Changes are made via API/CLI, not git commits and CI/CD pipelines
• Configuration can be queried, validated, and transformed using composable tools

Core Entities

• Unit: A collection of related Kubernetes resources (e.g., Deployment + Service + Ingress)
• Space: Logical grouping for units, typically representing an environment or team
• Revision: Immutable snapshot of a unit's configuration at a point in time
• Worker: Process running in your infrastructure that executes apply/destroy/refresh operations
• Target: Represents a deployment destination (Kubernetes cluster)
• Function: Code that reads/writes configuration data (readonly, mutating, or validating)
• Trigger: Automated function execution on configuration changes (validation, policy enforcement)
• Link: Dependency relationship between units for value propagation and apply ordering

---

Workflow

Step 1: Install the CLI

Install the cub CLI tool:

curl -fsSL https://hub.confighub.com/cub/install.sh | bash

Add to your PATH:

# Choose one method:
sudo ln -sf ~/.confighub/bin/cub /usr/local/bin/cub
# OR
export PATH=~/.confighub/bin:$PATH

Reasoning: The CLI is your primary interface for ConfigHub operations. It provides both interactive and scriptable access to all ConfigHub features.

Step 2: Authenticate and Set Context

Login and configure your default space:

# Authenticate via browser
cub auth login

# Set default space (replace with your space slug)
cub context set --space <SPACE_SLUG>

# Verify context
cub context get

Reasoning: Context configuration reduces repetitive flags in subsequent commands.

Step 3: Create Space Hierarchy for Environments

Organize your environments using spaces with labels:

# Create a home space for shared entities
cub space create home

# Create environment-specific spaces
cub space create app-dev --label Environment=dev --label Application=myapp
cub space create app-staging --label Environment=staging --label Application=myapp
cub space create app-prod --label Environment=prod --label Application=myapp

# Create platform spaces for shared infrastructure
cub space create platform-dev --label Environment=dev
cub space create platform-prod --label Environment=prod

Reasoning: Spaces provide isolation boundaries. Labels enable bulk operations across related spaces using where filters.

Step 4: Set Up Validation Triggers

Install essential validation triggers in your home space:

# Schema validation (always recommended)
cub trigger create --space home valid-k8s Mutation Kubernetes/YAML vet-schemas

# Placeholder validation (prevents applying incomplete config)
cub trigger create --space home complete-k8s Mutation Kubernetes/YAML vet-placeholders

# Context enforcement (adds metadata to resources)
cub trigger create --space home context-k8s Mutation Kubernetes/YAML ensure-context true

Apply triggers to other spaces:

homeSpaceID="$(cub space get home --jq '.Space.SpaceID')"
cub space create app-dev --label Environment=dev --where-trigger "SpaceID = '$homeSpaceID'"

Reasoning: Triggers enforce policies automatically. Installing them early prevents invalid configurations from being created or applied.

Step 5: Deploy and Configure Workers

Create and deploy a worker to enable apply/destroy/refresh operations:

# Create worker entity
cub worker create --space platform-dev cluster-worker

# Install worker in your cluster
cub worker install cluster-worker \
  --space platform-dev \
  --env IN_CLUSTER_TARGET_NAME=dev-cluster \
  --export --include-secret | kubectl apply -f -

# Verify worker is connected
cub worker list --space "*"

Reasoning: Workers execute operations in your infrastructure with your credentials. They never send credentials to ConfigHub, maintaining security boundaries.

Step 6: Import or Create Initial Configuration

Option A: Import from existing cluster

# Import specific resources
cub unit import --space app-dev frontend \
  --namespace myapp \
  --resource-type apps/v1/Deployment \
  --resource-name frontend

# Import entire namespace
cub unit import --space app-dev myapp-all \
  --namespace myapp

Option B: Create from Helm chart

# Add Helm repo
helm repo add bitnami https://charts.bitnami.com/bitnami --force-update

# Install chart as ConfigHub unit
cub helm install myapp bitnami/nginx \
  --space app-dev \
  --namespace myapp \
  --values values.yaml

Option C: Create from YAML files

# Validate locally first
cub function local vet-schemas deployment.yaml

# Create unit
cub unit create --space app-dev frontend deployment.yaml

Reasoning: ConfigHub works with existing infrastructure. Import captures current state, while Helm integration leverages the ecosystem. Direct YAML creation works for custom configurations.

Step 7: Create Configuration Variants

Clone units to create environment variants:

# Clone single unit to another space
cub unit create --space app-staging \
  --upstream-space app-dev \
  --upstream-unit frontend

# Clone all units from dev to multiple prod spaces
cub unit create --space app-dev \
  --where-space "Labels.Environment = 'prod'"

Reasoning: Cloning maintains upstream/downstream relationships, enabling controlled propagation of changes while preserving environment-specific overrides.

Step 8: Manage Dependencies with Links

Create links to propagate values and control apply order:

# Link backend to namespace (propagates namespace value)
cub link create --space app-dev - backend app-namespace

# Link backend to database (establishes apply order)
cub link create --space app-dev - backend database

# Bulk link all units to namespace
cub link create --space "*" \
  --where-space "Slug = 'app-dev'" \
  --where-from "Slug != 'app-namespace'" \
  --where-to "Slug = 'app-namespace'"

Reasoning: Links automate value substitution (replacing placeholders) and ensure correct apply/destroy ordering based on dependencies.

Step 9: Attach Targets to Units

Attach deployment targets to enable apply operations:

# Attach target to specific unit
cub unit set-target --space app-dev frontend platform-dev/dev-cluster

# Bulk attach to all units in environment
cub unit set-target --space "*" \
  --where "Space.Labels.Environment = 'dev'" \
  platform-dev/dev-cluster

Reasoning: Targets specify where configuration should be applied. Units without targets cannot be applied.

Step 10: Make Configuration Changes

Use functions to modify configuration:

# Update container image
cub function do --space app-dev --unit frontend \
  --change-desc "Update to v1.2.3" \
  set-image-reference main ":v1.2.3"

# Set resource limits
cub function do --space app-dev --unit frontend \
  set-container-resources main all 500m 512Mi 2

# Set environment variable
cub function do --space app-dev --unit frontend \
  set-env-var main DATABASE_URL "postgres://db:5432/myapp"

# Bulk update across environments
cub function do --space "*" \
  --where "Labels.Application = 'myapp' AND Space.Labels.Environment = 'prod'" \
  --change-desc "Production image update" \
  set-image-reference main ":v1.2.3"

Reasoning: Functions provide type-safe, validated configuration changes. They're more reliable than manual YAML editing and support bulk operations.

Step 11: Implement Change Management with ChangeSets

Group related changes using ChangeSets:

# Create ChangeSet
cub changeset create --space home release-v123 \
  --description "Release v1.2.3: Bug fixes and new features"

# Open ChangeSet (add units to it)
cub unit update --patch --space app-prod \
  --filter home/prod-app-filter \
  --changeset home/release-v123 \
  --change-desc "Starting release v1.2.3 rollout"

# Make changes (they'll be part of the ChangeSet)
cub function do --space app-prod \
  --changeset home/release-v123 \
  --filter home/prod-app-filter \
  --change-desc "Update image to v1.2.3" \
  set-image-reference main ":v1.2.3"

# Close ChangeSet
cub unit update --patch --space app-prod \
  --filter home/prod-app-filter \
  --changeset -

Reasoning: ChangeSets provide atomic, trackable change groups. They enable coordinated rollouts and rollbacks across multiple units.

Step 12: Review and Approve Changes

If approval triggers are configured:

# Approve specific revision
cub unit approve --space app-prod frontend --revision 5

# Bulk approve ChangeSet
cub unit approve --space app-prod \
  --filter home/prod-app-filter \
  --changeset home/release-v123

Step 13: Apply Configuration

Apply changes to clusters:

# Apply single unit
cub unit apply --space app-dev frontend

# Apply all units in environment
cub unit apply --space "*" \
  --where "Space.Labels.Environment = 'dev'"

# Apply with dry-run first
cub unit apply --space app-prod frontend --dry-run

Step 14: Monitor and Refresh State

Keep ConfigHub in sync with live state:

# Refresh single unit
cub unit refresh --space app-dev frontend

# Bulk refresh
cub unit refresh --space "*" \
  --where "Space.Labels.Environment = 'dev'"

# Check drift
cub unit get --space app-dev frontend --jq '.Unit.DriftStatus'

Step 15: Rollback When Needed

Revert to previous configurations:

# View revision history
cub unit get --space app-dev frontend --jq '.Unit.Revisions'

# Rollback to specific revision
cub unit rollback --space app-dev frontend --revision 3

# Rollback entire ChangeSet
cub unit rollback --space app-prod \
  --filter home/prod-app-filter \
  --changeset home/release-v123

---

References

• ConfigHub Documentation
• Configuration as Data Principles
• CLI Reference