Catalog Types

Konstruct supports three types of GitOps catalogs, each designed for specific deployment scenarios.

Overview

Choose the catalog type based on what you need to deploy:

• YAML Catalogs: Deploy Kubernetes applications and platform tools
• IAC Catalogs: Provision cloud infrastructure resources
• Hybrid Catalogs: Deploy both infrastructure and applications together

YAML Catalogs

Deploy Kubernetes applications and platform tools using Helm charts and ArgoCD Applications.

Use Cases

• Monitoring agents (Datadog, Prometheus, Grafana)
• Security tools (Falco, Cert-Manager, External Secrets Operator)
• Developer tools (Argo Workflows, Tekton Pipelines)
• Application services with existing Helm charts
• Platform utilities (Ingress controllers, service meshes)

File Structure

catalog/
└── <catalog-name>/
    ├── Chart.yaml              # Helm chart metadata
    ├── values.yaml             # Configurable parameters with @input annotations
    └── templates/
        ├── application.yaml    # ArgoCD Application manifest
        ├── external-secret.yaml # Optional: External Secrets resources
        └── ingress.yaml         # Optional: Additional resources

How YAML Catalogs Work

1. Parameter Definition: Define configurable parameters in values.yaml with @input annotations
2. Value Collection: Users provide values when deploying the catalog
3. Helm Templating: Helm processes templates with provided values
4. ArgoCD App Creation: Generated ArgoCD Applications are committed to GitOps repository
5. Deployment: ArgoCD syncs applications to target clusters

Deployment Location

YAML catalogs deploy to environment-specific paths in the application GitOps repository:

<org>-gitops/
└── registry/
    └── environments/
        └── <environment>/
            └── <cluster-name>/
                ├── <catalog-name>.yaml          # ArgoCD Application
                └── <catalog-name>/              # Additional resources
                    └── ...

Key Features

• Parameters use camelCase naming convention
• Support for string, enum, bool, and secret types
• ArgoCD Applications automatically configured
• Environment and cluster-specific deployments

IAC Catalogs

Provision cloud infrastructure resources using Terraform via Crossplane's Terraform provider.

Use Cases

• Cloud storage (S3 buckets, Azure Storage, GCS buckets)
• Databases (RDS, Azure SQL Database, Cloud SQL)
• Networking (VPCs, subnets, security groups, load balancers)
• IAM roles and policies
• DNS records and SSL certificates
• Message queues (SQS, Service Bus, Pub/Sub)

File Structure

<catalog-name>/
├── provider              # Crossplane provider configuration (no extension)
├── main.tf               # Terraform resource definitions
├── variables.tf          # Input variables (snake_case)
└── outputs.tf            # Output values

Important: The provider file has no file extension.

How IAC Catalogs Work

1. Token Detokenization: Operator replaces <TOKEN> placeholders in provider file with actual values
2. Case Conversion: CatalogDeployment camelCase values converted to snake_case for Terraform
3. ProviderConfig Creation: Crossplane ProviderConfig CRD created with detokenized configuration
4. Workspace Creation: Crossplane Workspace CRD created with Terraform module reference
5. Terraform Execution: Crossplane runs Terraform plan and apply
6. State Management: Terraform state stored in configured S3 backend

Variable Naming Convention

Critical: Terraform variables must use snake_case naming.

• ✅ Correct: bucket_name, instance_class, enable_versioning
• ❌ Incorrect: bucketName, instanceClass, enableVersioning

The Konstruct operator automatically converts camelCase parameter names from the deployment interface to snake_case for Terraform.

Example:

• User provides: bucketName: "my-bucket"
• Operator converts to: bucket_name = "my-bucket" for Terraform

Deployment Location

IAC catalogs deploy to cluster-specific paths in the platform GitOps repository:

<org>-gitops/
└── registry/
    └── clusters/
        └── <project-cluster-name>/
            └── components/
                └── iac/
                    ├── <catalog-name>.yaml          # Workspace and ProviderConfig CRDs
                    └── iac.yaml                     # ArgoCD Application for IAC components

Provider File Tokens

The provider file uses <TOKEN> format for values that will be detokenized:

terraform {
  backend "s3" {
    bucket  = "<BUCKET_NAME>"
    key     = "registry/clusters/<NAME>/infrastructure/terraform.tfstate"
    region  = "<REGION>"
    encrypt = true
  }
}

provider "aws" {
  region = "<REGION>"
  allowed_account_ids = ["<ACCOUNT_ID>"]
  assume_role_with_web_identity {
    role_arn = "<ROLE_ARN>"
  }
}

Common tokens:

• <BUCKET_NAME>: S3 bucket for Terraform state
• <NAME>: Cluster or resource name
• <REGION>: Cloud provider region
• <ACCOUNT_ID>: Cloud account identifier
• <ROLE_ARN>: IAM role ARN for authentication

Hybrid Catalogs

Combine infrastructure provisioning and application deployment in a single catalog.

Use Cases

• Database with management application (RDS + database admin UI)
• Monitoring infrastructure with collection agents (CloudWatch + Datadog agent)
• Complete application stacks (Load balancer + app + database)
• Multi-tier architectures (Network + compute + storage + applications)
• Platform services (S3 + upload service + file browser UI)

File Structure

<catalog-name>/
├── Chart.yaml              # YAML catalog metadata
├── values.yaml             # Combined parameters for YAML and IAC
├── templates/
│   ├── application.yaml    # Application ArgoCD manifests
│   └── ...                 # Additional Kubernetes resources
├── provider                # IAC provider configuration
├── main.tf                 # Infrastructure Terraform resources
├── variables.tf            # IAC variables (snake_case)
└── outputs.tf              # IAC outputs

How Hybrid Catalogs Work

Hybrid catalogs execute in two phases:

Phase 1: Infrastructure Provisioning (IAC)

1. Deploy IAC components to platform GitOps repository
2. Crossplane creates and applies Terraform configuration
3. Wait for infrastructure to reach Available state

Phase 2: Application Deployment (YAML) 4. Deploy YAML components to application GitOps repository 5. ArgoCD syncs applications to target clusters 6. Applications use provisioned infrastructure

Deployment Locations

Hybrid catalogs deploy to both repositories:

Platform GitOps (Infrastructure):

<org>-gitops/
└── registry/
    └── clusters/
        └── <cluster-name>/
            └── components/
                └── iac/
                    └── <catalog-name>.yaml

Application GitOps (Applications):

<org>-gitops/
└── registry/
    └── environments/
        └── <environment>/
            └── <cluster-name>/
                ├── <catalog-name>.yaml
                └── <catalog-name>/

Connecting Infrastructure to Applications

Use Terraform outputs to provide infrastructure details to applications:

outputs.tf:

output "database_endpoint" {
  value = aws_db_instance.main.endpoint
}

output "database_secret_arn" {
  value = aws_secretsmanager_secret.db_credentials.arn
}

Application values reference (via External Secrets):

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: database-connection
spec:
  secretStoreRef:
    name: aws-secrets-manager
  target:
    name: app-database-secret
  data:
    - secretKey: endpoint
      remoteRef:
        key: {{ .Values.databaseSecretArn }}
        property: endpoint

Choosing the Right Catalog Type

Use this decision matrix to choose the appropriate catalog type:

Requirement	Recommended Type
Deploy only Kubernetes resources	YAML
Provision only cloud infrastructure	IAC
Deploy application + provision infrastructure	Hybrid
Reusable monitoring agent	YAML
Database provisioning	IAC
Complete application stack with infrastructure	Hybrid
Platform tool (cert-manager, external-secrets)	YAML
Networking resources (VPC, subnets)	IAC
Multi-tier application with dedicated resources	Hybrid

Comparison Table

Feature	YAML	IAC	Hybrid
Technologies	Helm, ArgoCD	Terraform, Crossplane	Both
Variable Naming	camelCase	snake_case	Both (camelCase for YAML, snake_case for IAC)
Deploys To	Application GitOps	Platform GitOps	Both repositories
Deployment Path	registry/environments/	registry/clusters/	Both paths
Use ArgoCD	Yes	Yes (for IAC manifests)	Yes
Use Crossplane	No	Yes	Yes (for IAC components)
Complexity	Low	Medium	High
Best For	Applications, tools	Infrastructure	Complete stacks

What's Next?

• Review catalog prerequisites
• Create a YAML catalog for applications
• Create an IAC catalog for infrastructure
• Create a Hybrid catalog for combined deployments
• Learn about catalog annotations
• View catalog examples