Catalog Item Annotations Reference

Catalog annotations define configurable parameters for Application catalog items using special @input comments in values.yaml files.

Annotation Syntax

All annotations use comment-based syntax above the parameter definition:

# @input.<property>: <value>
parameterName: default-value

Annotations must appear directly above the parameter they describe, with no blank lines between the annotations and the parameter.

Required Annotations

Every parameter in an Application catalog item's values.yaml must include these three required annotations:

@input.type

Defines the parameter's data type.

Syntax:

# @input.type: <type>

Valid Types:

Type	Description	UI Component
string	Text input	Text field
enum	Select from predefined options	Dropdown list
bool	Boolean value (use enum with true,false options)	Checkbox or dropdown
secret	Sensitive data (passwords, API keys, tokens)	Password field

Examples:

# String type
# @input.type: string
clusterName: my-cluster

# Enum type
# @input.type: enum
environment: production

# Secret type
# @input.type: secret
apiKey: ""

@input.description

Human-readable description displayed in the Konstruct UI.

Syntax:

# @input.description: <description text>

Guidelines:

• Keep descriptions concise (1-2 sentences)
• Explain what the parameter controls
• Include units if applicable (e.g., "in days", "in MB")
• Mention any special formatting requirements

Examples:

# @input.type: string
# @input.description: Cluster name for resource identification
clusterName: my-cluster

# @input.type: string
# @input.description: Data retention period in days (e.g., 15d, 30d)
retentionPeriod: 15d

# @input.type: enum
# @input.description: Enable debug logging for troubleshooting
debugEnabled: false

@input.required

Specifies whether the parameter must be provided during deployment.

Syntax:

# @input.required: true|false

Examples:

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

# Optional parameter
# @input.type: string
# @input.description: Custom resource tag
# @input.required: false
customTag: ""

Optional Annotations

@input.default

Specifies the default value if the user does not provide one.

Syntax:

# @input.default: <default-value>

Guidelines:

• Include sensible defaults for optional parameters
• Default values should work in most scenarios
• Match the default value format to the parameter type

Examples:

# @input.type: string
# @input.description: Environment name
# @input.required: false
# @input.default: production
environment: production

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

@input.options

Defines available options for enum type parameters.

Syntax:

# @input.options: <option1>,<option2>,<option3>

Guidelines:

• Required for enum type parameters
• Separate options with commas (no spaces)
• For boolean values, use: true,false
• Options are case-sensitive

Examples:

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

# Multiple options
# @input.type: enum
# @input.description: Deployment environment
# @input.options: development,staging,production
# @input.required: true
# @input.default: development
environment: development

# Instance sizes
# @input.type: enum
# @input.description: Instance size
# @input.options: small,medium,large
# @input.required: true
# @input.default: medium
instanceSize: medium

Secret-Specific Annotations

When using @input.type: secret, these additional annotations are required. They define how and where secret values are stored so that the workload cluster's ExternalSecret can retrieve them.

@input.secretKey

The key name under which the secret is stored in the secret backend.

Syntax:

# @input.secretKey: <key-name>

@input.secretEnv

The environment variable name that will contain the secret value.

Syntax:

# @input.secretEnv: <ENV_VAR_NAME>

@input.secretBackend

The secret storage backend where the secret is stored. This determines which ClusterSecretStore is used to retrieve the secret.

Syntax:

# @input.secretBackend: <backend-name>

Supported backends:

• aws-secrets-store - AWS SSM Parameter Store
• vault - HashiCorp Vault
• azure-key-vault - Azure Key Vault
• gcp-secret-manager - GCP Secret Manager

@input.secretPath

The path in the secret backend where the secret is stored. This path is used by the ExternalSecret in your catalog template to read the secret.

Syntax:

# @input.secretPath: <path>

Examples:

# Database password
# @input.type: secret
# @input.description: Database password for application
# @input.required: true
# @input.secretKey: db-password
# @input.secretEnv: DATABASE_PASSWORD
# @input.secretBackend: aws-secrets-store
# @input.secretPath: /myapp/database
databasePassword: ""

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

Complete Examples

String Parameter

# @input.type: string
# @input.description: Name identifier for the cluster
# @input.required: true
# @input.default: default-cluster
clusterName: default-cluster

Enum Parameter (Boolean)

# @input.type: enum
# @input.description: Enable debug logging
# @input.options: true,false
# @input.required: false
# @input.default: false
debugEnabled: false

Enum Parameter (Multiple Options)

# @input.type: enum
# @input.description: Deployment environment type
# @input.options: development,staging,production
# @input.required: true
# @input.default: development
environment: development

Secret Parameter

# @input.type: secret
# @input.description: Database password for application
# @input.required: true
# @input.secretKey: db-password
# @input.secretEnv: DATABASE_PASSWORD
# @input.secretBackend: aws-secrets-store
# @input.secretPath: /myapp/database
databasePassword: ""

Multiple Parameters in values.yaml

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

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

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

# @input.type: enum
# @input.description: Enable application performance monitoring
# @input.options: true,false
# @input.required: false
# @input.default: false
apmEnabled: false

# Secrets
# @input.type: secret
# @input.description: API key for service authentication
# @input.required: true
# @input.secretKey: api-key
# @input.secretEnv: SERVICE_API_KEY
# @input.secretBackend: aws-secrets-store
# @input.secretPath: /my-service
serviceApiKey: ""

Naming Conventions

Critical: All parameter names in values.yaml must use camelCase.

Correct (camelCase)

• ✅ clusterName
• ✅ apiKey
• ✅ enableMonitoring
• ✅ databasePassword
• ✅ instanceSize

Incorrect

• ❌ cluster_name (snake_case)
• ❌ api-key (kebab-case)
• ❌ ClusterName (PascalCase)
• ❌ cluster name (spaces)

Validation Rules

The Konstruct platform validates annotations according to these rules:

1. Required Annotations: All parameters must have @input.type, @input.description, and @input.required
2. Enum Options: Parameters with @input.type: enum must include @input.options
3. Secret Annotations: Parameters with @input.type: secret must include all four secret-specific annotations
4. Default Types: Default values must match the declared type
5. Naming: Parameter names must use camelCase
6. No Blank Lines: Annotations must directly precede their parameters

Common Patterns

Optional Feature Toggle

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

Required Configuration with Sensible Default

# @input.type: string
# @input.description: Log level for application
# @input.required: true
# @input.default: info
logLevel: info

Environment-Specific Settings

# @input.type: enum
# @input.description: Deployment environment
# @input.options: dev,staging,prod
# @input.required: true
environment: dev

# @input.type: string
# @input.description: Resource size based on environment
# @input.required: true
# @input.default: small
resourceSize: small

What's Next?

• Create an Application catalog item using these annotations
• View catalog item examples with complete annotation usage
• Deploy catalog items to see how parameters appear in the UI
• Learn about catalog item types