Deploy a Catalog Item

Deploy catalog items to provision infrastructure or applications across your clusters and environments.

Summary

Once you've created a catalog, deploy instances with custom configurations through the Konstruct UI.

Prerequisites

• Catalog item prerequisites completed
• At least one catalog created in your GitOps repository
• Target cluster or environment configured

Deploy an Application Catalog Item

Application catalog items deploy applications to specific environments.

Steps

1. Navigate to Catalogs in the left sidebar

2. Click Deploy next to your Application catalog item

3. Configure deployment:

   • Environment: Select target environment (e.g., "dev", "staging", "production")
   • Cluster: Choose specific clusters or "All clusters in environment"

4. Configure parameters:

   • Fill in all required fields (marked with *)
   • Provide optional parameters as needed
   • For secret fields, values are stored in your configured secret backend

5. Review deployment summary

6. Click Deploy Catalog Item

Deployment Path

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

Monitor Deployment

Check deployment status:

1. ArgoCD UI: Navigate to ArgoCD to view application sync status

2. Konstruct UI: View deployment status in Catalogs → Deployments

3. Kubectl: Check application resources

   kubectl get applications -n argocd
   kubectl get pods -n <namespace>

Deploy an IaC Catalog Item

IaC catalog items provision infrastructure resources on specific clusters.

Steps

1. Navigate to Catalogs in the left sidebar

2. Click Deploy next to your IaC catalog item

3. Configure deployment:

   • Cluster: Select target cluster for infrastructure provisioning

4. Configure deployment values:

   • Provider tokens (no TF_ prefix): String-replaced in the provider file (e.g., region, account ID, IAM role)
   • Workspace tokens (TF_ prefix): Passed as Terraform variables with prefix stripped and converted to snake_case
   • Fill in all required values

5. Review deployment summary

6. Click Deploy Catalog Item

Deployment Path

IaC catalog items deploy to the platform GitOps repository (not the application 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

Monitor Provisioning

Check infrastructure provisioning on the management cluster:

1. Check Workspace status:

   kubectl get workspace
   kubectl describe workspace <instanceName>

2. Check ArgoCD apps:

   kubectl get applications -n argocd | grep <instanceName>

3. Check resource status in cloud provider console

Deploy a Hybrid Catalog Item

Hybrid catalog items deploy both infrastructure and applications.

Steps

1. Navigate to Catalogs in the left sidebar

2. Click Deploy next to your Hybrid catalog item

3. Configure deployment:

   • Environment: Select target environment(s) for applications
   • Cluster: Select target cluster(s)

4. Configure parameters:

   • Provide both infrastructure variables (camelCase → snake_case)
   • Provide application parameters (camelCase)
   • Fill in secrets

5. Review dual deployment summary

6. Click Deploy Catalog Item

Deployment Sequence

Hybrid catalogs deploy in phases:

1. Phase 1 - Infrastructure: IAC components deploy to platform GitOps
2. Wait: Operator waits for infrastructure Available state
3. Phase 2 - Applications: YAML components deploy to application GitOps

Monitor Hybrid Deployment

Monitor both phases:

1. Phase 1 - Infrastructure:

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

2. Phase 2 - Applications:

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

Deployment States

Application Catalog Item States

State	Description	Action
Pending	Application manifest committed to GitOps	Wait for ArgoCD sync
Syncing	ArgoCD syncing resources to cluster	Monitor ArgoCD
Healthy	All resources deployed successfully	Deployment complete
Degraded	Some resources failed	Check ArgoCD logs

IaC Catalog Item States

State	Description	Action
Pending	Workspace CRD created	Wait for Terraform init
Planning	Terraform plan executing	Review plan output
Applying	Terraform apply in progress	Monitor logs
Available	Infrastructure provisioned	Deployment complete
Failed	Terraform execution failed	Check logs and fix

Troubleshooting

Application Catalog Item Issues

Application Not Syncing:

• Check ArgoCD UI for sync errors
• Verify target namespace exists
• Confirm ArgoCD project permissions

Parameters Not Applied:

• Check values.yaml syntax
• Verify parameter naming (camelCase)
• Confirm all required annotations present

IaC Catalog Item Issues

Workspace Stuck in Pending:

• Check Crossplane provider status: kubectl get provider
• Verify ProviderConfig credentials
• Review S3 backend access permissions

Terraform Apply Failures:

• View Workspace logs for detailed errors
• Check cloud provider permissions
• Verify variable values match expected types
• Confirm resource quotas not exceeded

Token Detokenization Errors:

• Verify all <TOKENS> in provider file have corresponding values
• Check token naming matches exactly (case-sensitive)

Update Deployed Catalog

To update a deployed catalog:

1. Navigate to Catalogs → Deployments

2. Click Edit next to the deployment

3. Modify parameters as needed

4. Click Update Deployment

5. Monitor sync/apply process

Changes trigger:

• YAML: ArgoCD resync with new values
• IAC: New Terraform plan and apply
• Hybrid: Both phases re-execute if needed

Delete Catalog Deployment

To remove a deployed catalog:

1. Navigate to Catalogs → Deployments

2. Click Delete next to the deployment

3. Confirm deletion

4. Operator performs cleanup:

   • Removes files from GitOps repositories
   • ArgoCD prunes application resources
   • Crossplane runs Terraform destroy (for IAC)

Warning: IaC catalog item deletion runs terraform destroy. Ensure you have backups of important data.

Best Practices

• Test in dev first: Deploy to development environment before production
• Review changes: Check GitOps repository commits after deployment
• Monitor actively: Watch deployments until they reach healthy/available state
• Use descriptive names: Name deployments clearly for easy identification
• Document parameters: Keep track of parameter values for each deployment
• Regular cleanup: Remove unused catalog deployments to reduce clutter

What's Next?

• View catalog item examples for common patterns
• Learn about dynamic environment provisioning
• Create additional catalog items for your needs