Skip to main content
Version: 0.3

Provision Environment from Catalog

Step-by-step guide to provision a complete environment using GitOps catalogs.

Prerequisites​

Step 1: Plan Your Environment​

Before creating, plan your environment architecture:

Choose Catalogs​

Determine which catalogs to deploy:

Infrastructure (IAC):

  • Database catalog (e.g., rds-postgres, azure-sql)
  • Storage catalog (e.g., s3-bucket, azure-storage)
  • Network catalog (e.g., vpc-network, security-groups)

Applications (YAML):

  • Monitoring catalog (e.g., datadog-agent, prometheus)
  • Security catalog (e.g., cert-manager, external-secrets)
  • Application catalog (e.g., your application Helm chart)

Hybrid:

  • Full-stack catalog combining infrastructure and applications

Gather Parameter Values​

Collect required values for each catalog:

  • Resource names and identifiers
  • Instance sizes and configurations
  • Network settings (VPC IDs, subnet IDs, CIDRs)
  • Secret values (API keys, passwords)
  • Environment-specific settings

Step 2: Create Environment​

1. Navigate to Environments​

  1. Log in to Konstruct UI

  2. Click Environments in the left sidebar

  3. Click Add Environment button

2. Enter Environment Details​

Fill in basic environment information:

Name: dev-my-feature

  • Use descriptive names including environment type and purpose
  • Examples: dev-feature-auth, staging-customer-a, prod-main

Namespace: dev-my-feature

  • Usually matches environment name
  • Will be created if it doesn't exist

Environment Type:

  • Pre-release: Development, staging, testing environments
  • Release: Production and production-like environments

Description (optional): Development environment for authentication feature

3. Enable Catalog Provisioning​

  1. Scroll to Dynamic Provisioning section

  2. Toggle Provision with catalogs to enabled

  3. The catalog selection interface appears

4. Select Catalogs​

Choose catalogs to deploy:

  1. Add IAC Catalog (if needed):

    • Click Add IAC Catalog
    • Select catalog from dropdown (e.g., rds-postgres)
    • Click Add

  2. Add YAML Catalog (if needed):

    • Click Add YAML Catalog
    • Select catalog from dropdown (e.g., datadog-agent)
    • Click Add

  3. Add Hybrid Catalog (if needed):

    • Click Add Hybrid Catalog
    • Select catalog from dropdown
    • Click Add

You can add multiple catalogs of each type.

5. Configure Catalog Parameters​

For each selected catalog:

  1. Click Configure next to the catalog name

  2. Fill in required parameters (marked with *):

    • String fields: Enter text values
    • Enum fields: Select from dropdown
    • Secret fields: Enter sensitive values (stored securely)

  3. Review optional parameters and provide values if needed

  4. Click Save Configuration

Example - RDS Postgres Catalog:

databaseName: my-feature-db
instanceClass: db.t3.micro
allocatedStorage: 20
vpcId: vpc-abc123
subnetIds: subnet-xyz789,subnet-def456
environment: development

Example - Datadog Agent Catalog:

clusterName: dev-cluster
namespace: dev-my-feature
environment: development
logsEnabled: true
apmEnabled: true
datadogApiKey: [secret value]

6. Review and Create​

  1. Review the environment configuration summary:

    • Environment details
    • Selected catalogs
    • Parameter values

  2. Verify all required parameters are filled

  3. Click Create Environment

Step 3: Monitor Provisioning​

View Provisioning Status​

The Environments page shows real-time status:

Status Indicators:

  • Creating: Environment definition being created
  • Provisioning Infrastructure: IAC catalogs deploying
  • Infrastructure Ready: All infrastructure provisioned
  • Deploying Applications: YAML catalogs deploying
  • Ready: Environment fully provisioned and operational
  • Failed: Error occurred during provisioning

Monitor Infrastructure Provisioning​

If you deployed IAC catalogs, monitor Crossplane:

  1. Check Workspace status:

    kubectl get workspace -n crossplane-system

  2. View detailed progress:

    kubectl describe workspace <catalog-name> -n crossplane-system

  3. Watch Terraform logs:

    kubectl logs -f -n crossplane-system -l crossplane.io/claim-name=<catalog-name>

Expected states:

  • Pending → Planning → Applying → Available

Monitor Application Deployment​

If you deployed YAML catalogs, monitor ArgoCD:

  1. List applications:

    kubectl get applications -n argocd | grep <env-name>

  2. View application details:

    kubectl describe application <env>-<app> -n argocd

  3. Check deployed pods:

    kubectl get pods -n <namespace>

Expected states:

  • Pending → Syncing → Healthy

Step 4: Verify Environment​

Once provisioning completes, verify the environment:

1. Check Infrastructure Resources​

For IAC catalogs, verify resources in cloud provider console:

AWS:

  • RDS: Check database instances
  • S3: Check buckets
  • VPC: Check networks and security groups

Azure:

  • SQL Database: Check servers
  • Storage: Check accounts
  • Virtual Network: Check VNets

2. Check Application Resources​

For YAML catalogs, verify Kubernetes resources:

# Check all resources in namespace
kubectl get all -n <namespace>

# Check specific resources
kubectl get deployments -n <namespace>
kubectl get services -n <namespace>
kubectl get ingress -n <namespace>

# Check pod logs
kubectl logs -n <namespace> <pod-name>

3. Test Connectivity​

Verify applications can connect to provisioned infrastructure:

# Test database connectivity
kubectl exec -n <namespace> <pod-name> -- psql -h <db-endpoint> -U postgres

# Check application logs for connections
kubectl logs -n <namespace> <app-pod-name>

Step 5: Use Your Environment​

Your environment is now ready for use:

  • Deploy applications: Use the namespace for application deployments
  • Run tests: Execute tests against the environment
  • Develop features: Use for feature development and testing
  • Access services: Connect to deployed applications via ingress or port-forward

Complete Example Walkthrough​

Here's a complete example provisioning a development environment:

Environment:

  • Name: dev-feature-payments
  • Type: Pre-release
  • Namespace: dev-feature-payments

Catalogs:

  1. rds-postgres (IAC)
  2. redis-cluster (IAC)
  3. datadog-agent (YAML)
  4. payment-service (YAML)

Configuration:

rds-postgres:

  • databaseName: payments-db
  • instanceClass: db.t3.micro
  • vpcId: vpc-12345
  • subnetIds: subnet-abc,subnet-def

redis-cluster:

  • clusterName: payments-cache
  • nodeType: cache.t3.micro
  • numNodes: 1

datadog-agent:

  • clusterName: dev-cluster
  • logsEnabled: true

payment-service:

  • replicas: 2
  • imageTag: v1.2.3

Provisioning Flow:

  1. Create environment (30 seconds)
  2. Deploy IAC catalogs - RDS and Redis (5-10 minutes)
  3. Wait for infrastructure Available state
  4. Deploy YAML catalogs - Datadog and Payment Service (2-3 minutes)
  5. Environment ready (total: ~15 minutes)

Troubleshooting​

Infrastructure Provisioning Stuck​

Symptoms: Workspace stays in Planning or Applying

Solutions:

  • Check Terraform logs for errors
  • Verify cloud provider permissions
  • Confirm resource quotas not exceeded
  • Check network connectivity from cluster

Application Deployment Failed​

Symptoms: ArgoCD application shows Degraded or OutOfSync

Solutions:

  • Check ArgoCD application events
  • Verify image exists and is accessible
  • Confirm secrets are created correctly
  • Check resource requests/limits

Environment Stuck in Creating​

Symptoms: Status shows Creating for extended time

Solutions:

  • Check Konstruct operator logs
  • Verify GitOps repository is accessible
  • Confirm no merge conflicts in GitOps repo

Best Practices​

  • Start small: Test with a simple catalog first
  • Validate parameters: Double-check all parameter values before creating
  • Monitor actively: Watch provisioning progress, don't walk away
  • Keep notes: Document parameter values for future reference
  • Clean up: Delete test environments when done
  • Use naming conventions: Consistent naming helps organization

What's Next?​