Version: 0.3

Create a YAML Catalog

Create YAML catalogs to deploy applications and platform tools consistently across clusters and environments.

Summary

This guide walks you through creating a YAML catalog that uses Helm templates and ArgoCD Applications to deploy Kubernetes resources.

Prerequisites

Catalog prerequisites completed
Organization GitOps repository cloned locally
Basic understanding of Helm charts

Step 1: Create Catalog Directory Structure

Navigate to your GitOps repository:
```
cd <your-org>-gitops
```
Create catalog directory structure:
```
mkdir -p catalog/<catalog-name>/templates
```
Replace <catalog-name> with your catalog's name (use kebab-case, e.g., datadog-agent).

Create required files:

touch catalog/<catalog-name>/Chart.yaml
touch catalog/<catalog-name>/values.yaml
touch catalog/<catalog-name>/templates/application.yaml

Step 2: Configure Chart.yaml

Open catalog/<catalog-name>/Chart.yaml in your text editor
Add Helm chart metadata:
```
apiVersion: v2
name: <catalog-name>
description: <Brief description of what this catalog deploys>
type: application
version: 0.1.0
appVersion: "1.0.0"
```
Field Descriptions:
- name: Must match your catalog directory name
- description: Brief summary shown to catalog users
- type: Always application for YAML catalogs
- version: Catalog template version (use semantic versioning)
- appVersion: Version of the application being deployed

Example:

apiVersion: v2
name: datadog-agent
description: Datadog Agent deployment for Kubernetes monitoring and observability
type: application
version: 0.1.0
appVersion: "3.57.3"

Step 3: Define Parameters with Annotations

Open catalog/<catalog-name>/values.yaml
Add configurable parameters with @input annotations:

# @input.type: string
# @input.description: Cluster name identifier
# @input.required: true
# @input.default: my-cluster
clusterName: my-cluster

# @input.type: string
# @input.description: Namespace for deployment
# @input.required: true
# @input.default: default
namespace: default

# @input.type: enum
# @input.description: Enable monitoring feature
# @input.options: true,false
# @input.required: true
# @input.default: true
monitoringEnabled: true

# @input.type: secret
# @input.description: API key for authentication
# @input.required: true
# @input.secretKey: api-key
# @input.secretEnv: API_KEY
# @input.secretBackend: vault
# @input.secretPath: /<catalog-name>
apiKey: ""

Important Notes:

All parameter names must use camelCase (e.g., clusterName, not cluster_name)
Include all required annotations: @input.type, @input.description, @input.required
For enum types, include @input.options
For secret types, include all secret-specific annotations
Leave secret values empty ("")

See the Catalog Annotations Reference for complete documentation.

Step 4: Create ArgoCD Application Template

Open catalog/<catalog-name>/templates/application.yaml
Add ArgoCD Application manifest:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: {{ .Values.clusterName }}-<app-name>
  namespace: argocd
  annotations:
    kubefirst.konstruct.io/application-name: <catalog-name>
    kubefirst.konstruct.io/source: catalog-templates
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  destination:
    namespace: {{ .Values.namespace }}
    name: {{ .Values.clusterDestination }}
  project: {{ .Values.project }}
  source:
    chart: <helm-chart-name>
    repoURL: <upstream-helm-repo>
    targetRevision: {{ .Values.chartVersion }}
    helm:
      releaseName: <release-name>
      values: |
        # Helm values using template variables
        key: {{ .Values.someValue }}
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Customize these fields:

<app-name>: Application name (e.g., datadog)
<catalog-name>: Your catalog name
<helm-chart-name>: Upstream Helm chart name (e.g., datadog)
<upstream-helm-repo>: Helm repository URL (e.g., https://helm.datadoghq.com)
<release-name>: Helm release name
Add your specific Helm values in the values: section

Step 5: Add Standard Values

Add these standard values to your values.yaml for ArgoCD integration:

# Standard ArgoCD values (add these to your values.yaml)

# @input.type: string
# @input.description: GitOps repository URL for ArgoCD sync
# @input.required: true
gitopsRepoUrl: https://github.com/example/gitops-repo

# @input.type: string
# @input.description: Registry path in GitOps repository
# @input.required: true
registryPath: registry/clusters/my-cluster

# @input.type: string
# @input.description: Target cluster destination for ArgoCD
# @input.required: true
# @input.default: in-cluster
clusterDestination: in-cluster

# @input.type: string
# @input.description: ArgoCD project name
# @input.required: true
# @input.default: default
project: default

Step 6: Commit and Push Catalog

Stage catalog files:
```
git add catalog/<catalog-name>/
```

Commit changes:

git commit -m "feat(catalog): add <catalog-name> YAML catalog"

Push to remote:
```
git push origin main
```

Step 7: Verify Catalog in Konstruct

Navigate to Catalogs in the Konstruct UI
Your new catalog should appear in the catalog list
Click the catalog name to view configurable parameters
Verify all parameters display correctly with descriptions

Complete Example: Datadog Agent Catalog

Here's a complete example of a Datadog monitoring agent catalog:

Chart.yaml:

apiVersion: v2
name: datadog-agent
description: Datadog Agent deployment for Kubernetes monitoring and observability
type: application
version: 0.1.0
appVersion: "3.57.3"

values.yaml:

# @input.type: string
# @input.description: Cluster name identifier
# @input.required: true
# @input.default: my-cluster
clusterName: my-cluster

# @input.type: string
# @input.description: Namespace for Datadog Agent deployment
# @input.required: true
# @input.default: datadog
namespace: datadog

# @input.type: string
# @input.description: Environment name for Datadog (DD_ENV)
# @input.required: true
# @input.default: production
environment: production

# @input.type: enum
# @input.description: Enable log collection from containers
# @input.options: true,false
# @input.required: true
# @input.default: true
logsEnabled: true

# @input.type: enum
# @input.description: Enable Datadog APM (Application Performance Monitoring)
# @input.options: true,false
# @input.required: false
# @input.default: false
apmEnabled: false

# @input.type: secret
# @input.description: Datadog API key for authentication
# @input.required: true
# @input.secretKey: api-key
# @input.secretEnv: DATADOG_API_KEY
# @input.secretBackend: vault
# @input.secretPath: /datadog-agent
datadogApiKey: ""

# Standard ArgoCD values
# @input.type: string
# @input.description: ArgoCD project name
# @input.required: true
# @input.default: default
project: default

# @input.type: string
# @input.description: Target cluster destination
# @input.required: true
# @input.default: in-cluster
clusterDestination: in-cluster

# @input.type: string
# @input.description: Datadog Helm chart version
# @input.required: true
# @input.default: 3.57.3
chartVersion: 3.57.3

templates/application.yaml:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: {{ .Values.clusterName }}-datadog
  namespace: argocd
  annotations:
    kubefirst.konstruct.io/application-name: datadog-agent
    kubefirst.konstruct.io/source: catalog-templates
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  destination:
    namespace: {{ .Values.namespace }}
    name: {{ .Values.clusterDestination }}
  project: {{ .Values.project }}
  source:
    chart: datadog
    repoURL: https://helm.datadoghq.com
    targetRevision: {{ .Values.chartVersion }}
    helm:
      releaseName: datadog
      values: |
        datadog:
          apiKeyExistingSecret: datadog-secret
          clusterName: "{{ .Values.clusterName }}"
          env:
          - name: DD_ENV
            value: "{{ .Values.environment }}"
          logs:
            enabled: {{ .Values.logsEnabled }}
            containerCollectAll: {{ .Values.logsEnabled }}
{{- if .Values.apmEnabled }}
          apm:
            enabled: true
{{- end }}
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Best Practices

Descriptive annotations: Provide clear, concise descriptions for all parameters
Sensible defaults: Include default values for non-critical parameters
Secrets handling: Always use @input.type: secret for sensitive data
Parameter organization: Group related parameters together with comments
Version pinning: Specify exact chart versions for stability
Validation: Test catalog deployment before committing to main branch
Documentation: Add a README.md in your catalog directory explaining usage

Troubleshooting

Catalog Not Appearing in UI

Verify the GitOps repository is properly registered in Konstruct
Check that the catalog/ directory exists in the repository root
Ensure Chart.yaml is valid YAML with required fields

Parameters Not Showing Correctly

Verify all required annotations are present (@input.type, @input.description, @input.required)
Check parameter names use camelCase (not snake_case or kebab-case)
Ensure no blank lines between annotations and parameters

Deployment Fails

Check ArgoCD Application syntax in templates/application.yaml
Verify Helm chart name and repository URL are correct
Ensure all referenced values exist in values.yaml

What's Next?

Deploy your YAML catalog to an environment
Learn about catalog annotations in detail
View more catalog examples
Create an IAC catalog for infrastructure
Create a Hybrid catalog combining YAML and IAC

Summary​

Prerequisites​

Step 1: Create Catalog Directory Structure​

Step 2: Configure Chart.yaml​

Step 3: Define Parameters with Annotations​

Step 4: Create ArgoCD Application Template​

Step 5: Add Standard Values​

Step 6: Commit and Push Catalog​

Step 7: Verify Catalog in Konstruct​

Complete Example: Datadog Agent Catalog​

Best Practices​

Troubleshooting​

Catalog Not Appearing in UI​

Parameters Not Showing Correctly​

Deployment Fails​

What's Next?​