Skip to main content
Version: 0.7 (Next)

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. Argo CD UI: Navigate to Argo CD 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 Argo CD 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​

StateDescriptionAction
PendingApplication manifest committed to GitOpsWait for Argo CD sync
SyncingArgo CD syncing resources to clusterMonitor Argo CD
HealthyAll resources deployed successfullyDeployment complete
DegradedSome resources failedCheck Argo CD logs

IaC Catalog Item States​

StateDescriptionAction
PendingWorkspace CRD createdWait for Terraform init
PlanningTerraform plan executingReview plan output
ApplyingTerraform apply in progressMonitor logs
AvailableInfrastructure provisionedDeployment complete
FailedTerraform execution failedCheck 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.

info

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​

  1. Navigate to Catalogs → Deployed

  2. Click Edit inputs next to the deployment

  3. 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
  4. 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: false until Terraform has applied the change. Poll GET /api/v1/catalog-deployment/<namespace>/<instance-name> until ready is true

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​

  1. The operator re-renders the deployment's Workspace into the platform GitOps repository
  2. Argo CD syncs the new Workspace
  3. Crossplane runs Terraform plan and apply with the new inputs
  4. 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.

Inputs that replace resources

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:

  1. Navigate to Catalogs → Deployments

  2. Click Delete next to the deployment

  3. Confirm deletion

  4. 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?​