Catalog Item Types

Konstruct supports three GitOps Catalog item types, each designed for specific deployment scenarios.

Overview

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

• Application Catalog Items: Deploy Kubernetes applications and platform tools
• IaC Catalog Items: Provision cloud infrastructure resources
• Hybrid Catalog Items: Deploy both infrastructure and applications together

Application Catalog Items

Deploy Kubernetes applications and platform tools using Helm charts and Argo CD 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 Application Catalog Items Work

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

Deployment Location

Application catalog items 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
• Argo CD Applications automatically configured
• Environment and cluster-specific deployments

IaC Catalog Items

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 Catalog Items Work

1. Clone template: Operator clones the IaC template from the catalog source repository
2. Push module: Commits the Terraform module to the platform GitOps repository
3. Split values: Separates deployment values by TF_ prefix — provider tokens for string replacement, workspace tokens for Terraform variables
4. Detokenize provider: Replaces <TOKEN> placeholders in the provider file
5. ProviderConfig creation: Crossplane ProviderConfig CRD created with detokenized configuration
6. Workspace creation: Crossplane Workspace CRD created with module reference and variables
7. Argo CD sync: Management cluster Argo CD syncs the new content
8. Terraform execution: Crossplane runs Terraform plan and apply

Value Types

IaC deployment values are split into two categories by the TF_ prefix:

Provider tokens (no TF_ prefix) — string-replaced in the provider file:

• <PROJECT_REGION> → replaced with us-west-2 in provider config
• <PROJECT_AWS_ACCOUNT_ID> → replaced with the AWS account ID

Workspace tokens (TF_ prefix) — passed as Terraform variables with prefix stripped and converted to snake_case:

• <TF_NAME> → name = "my-bucket"
• <TF_BUCKET_REGION> → bucket_region = "us-west-2"

Variable Naming Convention

Critical: Terraform variables must use snake_case naming to match the converted TF_ tokens.

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

Deployment Location

IaC catalog items deploy to the platform GitOps repository:

<platformOrg>/<projectName>-gitops/
|-- terraform/<catalogAppName>/                    # Cloned Terraform module
|-- registry/iac/<instanceName>/
|   |-- provider-config/provider-config.yaml       # Crossplane ProviderConfig
|   +-- infrastructure/workspace.yaml              # Crossplane Workspace
+-- registry/clusters/<clusterName>/
    |-- iac.yaml                                   # App-of-apps for all IaC
    +-- components/iac/
        |-- <instanceName>.yaml                    # ArgoCD app -> iac root
        |-- <instanceName>-provider.yaml           # ArgoCD app -> provider-config
        +-- <instanceName>-infra.yaml              # ArgoCD app -> infrastructure

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 Catalog Items

Combine infrastructure provisioning and application deployment in a single catalog item.

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              # Application catalog item 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 Catalog Items Work

Hybrid catalog items 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. Argo CD syncs applications to target clusters 6. Applications use provisioned infrastructure

Deployment Locations

Hybrid catalog items 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/v1
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 Item Type

Use this decision matrix to choose the appropriate catalog item 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, Argo CD	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 Argo CD	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 item prerequisites
• Create an Application catalog item for applications
• Create an IaC catalog item for infrastructure
• Create a Hybrid catalog item for combined deployments
• Learn about catalog item annotations
• View catalog item examples