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
-
Navigate to Catalogs in the left sidebar
-
Click Deploy next to your Application catalog item
-
Configure deployment:
- Environment: Select target environment (e.g., "dev", "staging", "production")
- Cluster: Choose specific clusters or "All clusters in environment"
-
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
-
Review deployment summary
-
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:
-
Argo CD UI: Navigate to Argo CD to view application sync status
-
Konstruct UI: View deployment status in Catalogs → Deployments
-
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
-
Navigate to Catalogs in the left sidebar
-
Click Deploy next to your IaC catalog item
-
Configure deployment:
- Cluster: Select target cluster for infrastructure provisioning
-
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
- Provider tokens (no
-
Review deployment summary
-
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:
-
Check Workspace status:
kubectl get workspace
kubectl describe workspace <instanceName> -
Check Argo CD apps:
kubectl get applications -n argocd | grep <instanceName> -
Check resource status in cloud provider console
Deploy a Hybrid Catalog Item
Hybrid catalog items deploy both infrastructure and applications.
Steps
-
Navigate to Catalogs in the left sidebar
-
Click Deploy next to your Hybrid catalog item
-
Configure deployment:
- Environment: Select target environment(s) for applications
- Cluster: Select target cluster(s)
-
Configure parameters:
- Provide both infrastructure variables (camelCase → snake_case)
- Provide application parameters (camelCase)
- Fill in secrets
-
Review dual deployment summary
-
Click Deploy Catalog Item
Deployment Sequence
Hybrid catalogs deploy in phases:
- Phase 1 - Infrastructure: IAC components deploy to platform GitOps
- Wait: Operator waits for infrastructure
Availablestate - Phase 2 - Applications: YAML components deploy to application GitOps
Monitor Hybrid Deployment
Monitor both phases:
-
Phase 1 - Infrastructure:
kubectl get workspace <catalog-name> -n crossplane-system -
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 Argo CD sync |
| Syncing | Argo CD syncing resources to cluster | Monitor Argo CD |
| Healthy | All resources deployed successfully | Deployment complete |
| Degraded | Some resources failed | Check Argo CD 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 Argo CD UI for sync errors
- Verify target namespace exists
- Confirm Argo CD 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 the Inputs of an IaC Deployment
Change the Terraform inputs of an IaC or hybrid deployment after it is provisioned, for example to add a consumer app to an existing database. Terraform applies the change to the existing resources.
Available from Konstruct 0.7.0-rc.192.
Only Terraform inputs (TF_ tokens) can be changed. Provider tokens such as region or account ID are fixed after provisioning, and YAML values can't be updated yet.
Update Inputs in the UI
-
Navigate to Catalogs → Deployed
-
Click Edit inputs next to the deployment
-
Change the inputs you need. Inputs you don't change are kept.
- Clear an optional input to reset it to the module default
- Leave a secret blank to keep its current value
-
Click Save changes
The deployment shows Provisioning until Terraform finishes, then Ready.
Update Inputs with the API
Send only the inputs you want to change:
curl -X PATCH "https://<konstruct-domain>/api/v1/catalog-deployment/<namespace>/<instance-name>" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"iac_values": {"TF_CONSUMER_APP_NAME": "[\"billing\",\"reports\"]"}}'
- Each key replaces that input. A list input is replaced whole, so send the complete list
- An empty value (
"") removes the input, so the module default applies - Inputs you don't send are kept
- The response returns
ready: falseuntil Terraform has applied the change. PollGET /api/v1/catalog-deployment/<namespace>/<instance-name>untilreadyistrue
The API returns 400 if a key isn't a TF_ input or the request has no inputs, and 404 if the deployment doesn't exist. Nothing is changed in either case.
What Happens After an Update
- The operator re-renders the deployment's Workspace into the platform GitOps repository
- Argo CD syncs the new Workspace
- Crossplane runs Terraform plan and apply with the new inputs
- The deployment reports ready once the Workspace has applied the new inputs
If Terraform fails, the deployment shows the error. Update the input again with a valid value to recover.
Some inputs can't change in place. Terraform replaces the resource instead: for example a bucket or database name. Inputs used in the provider file are the riskiest. A name that is also part of the Terraform state key (such as TF_S3_NAME) starts a new state, so Terraform creates a new resource and no longer manages the old one. Check the module before changing these inputs.
Delete Catalog Deployment
To remove a deployed catalog:
-
Navigate to Catalogs → Deployments
-
Click Delete next to the deployment
-
Confirm deletion
-
Operator performs cleanup:
- Removes files from GitOps repositories
- Argo CD 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