Package com.cloudforge.core.annotation

Annotation Interface ConfigField

@Retention(RUNTIME) @Target(FIELD) public @interface ConfigField
Marks a field in DeploymentConfig as user-configurable with metadata for automatic prompt generation, validation, and JSON schema generation.

This annotation enables the Configuration Introspection system to automatically discover configuration fields, filter them by application capabilities, and generate interactive prompts without manual code changes.

Integration with Plugin Systems

ApplicationSpec Plugin Integration

The visibleWhen() condition references ApplicationSpec capabilities:


 @ConfigField(
     displayName = "Database Engine",
     visibleWhen = "supportsDatabase",  // ← Checks ApplicationSpec.supportsDatabase()
     category = "database"
 )
 public String databaseEngine;

FrameworkRules Plugin Integration

FrameworkRules plugins provide compliance-driven defaults and validation:


 // Annotation defines minimum
 @ConfigField(
     displayName = "Backup Retention Days",
     min = 7
 )
 public Integer databaseBackupRetentionDays;

 // FrameworkRules overrides for compliance
 // PCI-DSS: 90 days
 // HIPAA: 30 days
 // SOC2: 14 days

Usage Examples

Basic Field


 @ConfigField(
     displayName = "Stack Name",
     description = "CloudFormation stack name",
     category = "basic",
     required = true,
     pattern = "^[a-zA-Z][a-zA-Z0-9-]{0,127}$",
     example = "my-application"
 )
 public String stackName;

Conditional Field (Application-Specific)


 @ConfigField(
     displayName = "OIDC Provider",
     description = "OIDC identity provider",
     category = "security",
     visibleWhen = "supportsOidc",  // Only for OIDC-enabled apps
     allowedValues = {"cognito", "identity-center", "external-idp"}
 )
 public String oidcProvider;

Numeric Field with Constraints


 @ConfigField(
     displayName = "CPU Units",
     description = "Fargate CPU units",
     category = "resources",
     min = 256,
     max = 4096,
     example = "1024"
 )
 public int cpu;

Sensitive Field


 @ConfigField(
     displayName = "OIDC Client Secret",
     description = "OIDC client secret (stored in Secrets Manager)",
     category = "security",
     visibleWhen = "oidcProvider == external-idp",
     sensitive = true
 )
 public String oidcClientSecret;

Visibility Condition Language

The visibleWhen() attribute supports simple expressions:

  • "always" - Field always visible (default)
  • "supportsDatabase" - Checks ApplicationSpec.supportsDatabase()
  • "requiresDatabase" - Checks DatabaseSpec.databaseRequirement().type() == REQUIRED
  • "supportsOidc" - Checks ApplicationSpec.supportsOidcIntegration()
  • "applicationId == redis" - Checks specific application
  • "securityProfile == PRODUCTION" - Checks security profile
  • "provisionDatabase" - Checks boolean field value

Field Categories

Categories group related fields in interactive prompts:

  • basic - Stack name, environment, application ID
  • domain - Domain, subdomain, SSL configuration
  • resources - CPU, memory, instance type, scaling
  • database - RDS configuration (engine, instance class, storage)
  • network - VPC, WAF, CloudFront
  • security - OIDC, encryption, compliance
  • monitoring - CloudWatch, GuardDuty, logging
Since:
3.0.0
See Also:

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    description
    Detailed description shown to users explaining the purpose and behavior.
    String
    displayName
    Display name shown to users in interactive prompts.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String[]
    allowedValues
    Allowed values for enum-like fields with constrained choices.
    String
    category
    Field category for grouping related configuration options.
    String
    defaultFrom
    Method name or expression for resolving default value from ApplicationSpec.
    String
    dependsOn
    Name of parent field that this field depends on.
    String
    example
    Example value shown to users as guidance.
    double
    max
    Maximum value for numeric fields (int, double, float).
    double
    min
    Minimum value for numeric fields (int, double, float).
    int
    order
    Order hint for field display within a category.
    String
    pattern
    Regular expression pattern for string validation.
    boolean
    required
    Whether this field is required to have a non-null value.
    boolean
    sensitive
    Whether this field contains sensitive data (passwords, secrets, API keys).
    String
    sourceConfig
    Configuration for sensitive field source strategy.
    FieldTag[]
    tags
    Impact and characteristic tags for change analysis.
    String[]
    validators
    Custom validators for cross-field validation.
    String
    visibleWhen
    Visibility condition expression determining when this field should be shown.

  • Element Details

    • displayName

      String displayName
      Display name shown to users in interactive prompts.

      Should be human-readable and concise (e.g., "Database Engine", "Stack Name").

      Returns:
      display name for this field

    • description

      String description
      Detailed description shown to users explaining the purpose and behavior.

      Should provide enough context for users to make informed decisions.

      Returns:
      description of this field

    • category

      String category
      Field category for grouping related configuration options.

      Categories are used to organize prompts in the interactive deployer and group related fields in generated documentation.

      Common categories:

      • basic - Essential configuration (stack name, app ID)
      • domain - Domain and SSL configuration
      • resources - CPU, memory, instance sizing
      • database - RDS database configuration
      • network - VPC, WAF, CloudFront
      • security - OIDC, encryption, compliance
      • monitoring - CloudWatch, GuardDuty, logging
      Returns:
      field category
      Default:
      "basic"

    • visibleWhen

      String visibleWhen
      Visibility condition expression determining when this field should be shown.

      Expressions reference ApplicationSpec capabilities and DeploymentConfig field values. This enables application-aware configuration where fields are only shown when relevant.

      Supported expressions:

      • "always" - Always visible (default)
      • "supportsDatabase" - Visible when ApplicationSpec supports database
      • "requiresDatabase" - Visible when database is required
      • "supportsOidc" - Visible when OIDC is supported
      • "provisionDatabase" - Visible when provisionDatabase flag is true
      • "applicationId == redis" - Visible only for specific applications

      For complex conditions, use logical operators (future enhancement):

      • "supportsDatabase && provisionDatabase"
      • "securityProfile == PRODUCTION || complianceMode == PCI_DSS"
      Returns:
      visibility condition expression
      Default:
      "always"

    • required

      boolean required
      Whether this field is required to have a non-null value.

      Required fields must be provided by the user or have a default value. The configuration introspector will validate required fields before deployment.

      Returns:
      true if field is required
      Default:
      false

    • example

      String example
      Example value shown to users as guidance.

      Should demonstrate the expected format and a typical use case.

      Returns:
      example value
      Default:
      ""

    • allowedValues

      String[] allowedValues
      Allowed values for enum-like fields with constrained choices.

      When specified, only these values are accepted. Interactive prompts will present these as a selection menu.

      Example:

      
 allowedValues = {"postgres", "mysql", "mariadb"}
      Returns:
      array of allowed values, or empty for unconstrained fields
      Default:
      {}

    • min

      double min
      Minimum value for numeric fields (int, double, float).

      Validation will reject values below this minimum.

      Returns:
      minimum allowed value
      Default:
      -1.0/0.0

    • max

      double max
      Maximum value for numeric fields (int, double, float).

      Validation will reject values above this maximum.

      Returns:
      maximum allowed value
      Default:
      1.0/0.0

    • pattern

      String pattern
      Regular expression pattern for string validation.

      String values must match this pattern to be considered valid.

      Example:

      
 pattern = "^[a-zA-Z][a-zA-Z0-9-]{0,127}$"  // Stack name validation
      Returns:
      regex pattern, or empty string for no pattern validation
      Default:
      ""

    • sensitive

      boolean sensitive
      Whether this field contains sensitive data (passwords, secrets, API keys).

      Sensitive fields are:

      • Masked in interactive prompts
      • Excluded from logs and error messages
      • Marked as sensitive in JSON schemas
      • Should be stored in AWS Secrets Manager, not deployment-context.json
      Returns:
      true if field contains sensitive data
      Default:
      false

    • tags

      FieldTag[] tags
      Impact and characteristic tags for change analysis.

      Tags drive warnings and approval workflows:

      • DESTRUCTIVE - Resource replacement (data loss risk)
      • REQUIRES_RESTART - Service restart needed (~1-2 min downtime)
      • BILLING_IMPACT - AWS cost impact
      • IMMUTABLE - Cannot change after creation
      • REQUIRES_APPROVAL - Manual approval for production
      • EXPERIMENTAL - Not production-ready
      Returns:
      array of field tags
      Default:
      {}

    • order

      int order
      Order hint for field display within a category.

      Fields with lower order values are shown first. Fields with the same order are sorted alphabetically by display name.

      Default order is 1000, allowing insertion before and after.

      Returns:
      display order hint
      Default:
      1000

    • dependsOn

      String dependsOn
      Name of parent field that this field depends on.

      Used to establish explicit dependencies between fields, making it clear when one field's visibility or value depends on another.

      Example:

      
 @ConfigField(
     displayName = "Database Version",
     dependsOn = "provisionDatabase",
     visibleWhen = "provisionDatabase == true"
 )
 public String databaseVersion;
      Returns:
      parent field name, or empty if no dependency
      Default:
      ""

    • defaultFrom

      String defaultFrom
      Method name or expression for resolving default value from ApplicationSpec.

      Supports convention-based lookup via reflection:

      • "defaultCpu" - Calls appSpec.defaultCpu()
      • "databaseRequirement().engine" - Chained method calls

      This enables layered defaults:

       User Override (highest priority)
     ↓
 FrameworkRules (compliance)
     ↓
 ApplicationSpec (defaultFrom)
     ↓
 ConfigField default (system)
      Returns:
      method name or expression, or empty for no ApplicationSpec default
      Default:
      ""

    • sourceConfig

      String sourceConfig
      Configuration for sensitive field source strategy.

      References another field containing the source location (e.g., Secrets Manager ARN).

      Example:

      
 @ConfigField(
     displayName = "Database Password ARN",
     sensitive = false
 )
 public String databasePasswordArn;

 @ConfigField(
     displayName = "Database Password",
     sensitive = true,
     sourceConfig = "databasePasswordArn"
 )
 public String databasePassword;  // Value comes from Secrets Manager
      Returns:
      field name containing source configuration
      Default:
      ""

    • validators

      String[] validators
      Custom validators for cross-field validation.

      Validators are executed after basic field-level validation (required, min, max, etc.) and enable complex validation logic that depends on multiple fields or external state.

      Validators are specified by their simple class name and must implement the FieldValidator interface.

      Built-in validators:

      • CapacityValidator - Validates maxCapacity >= minCapacity
      • FargateCpuMemoryValidator - Validates AWS Fargate CPU/memory combinations

      Example:

      
 @ConfigField(
     displayName = "Maximum Capacity",
     validators = {"CapacityValidator"}
 )
 public int maxCapacity = 10;

 @ConfigField(
     displayName = "Fargate Memory (MB)",
     validators = {"FargateCpuMemoryValidator"}
 )
 public int fargateMemory = 2048;
      Returns:
      array of validator class names
      Default:
      {}