YAML Format Guide

This guide provides a detailed description of the YAML formats and syntax rules supported by ConfigMaps, helping you efficiently import and export configuration data.

Supported YAML Formats

The system supports two YAML formats. You can choose the appropriate format based on your use case:

1. Simplified Format (Recommended)

The simplified format is designed specifically for ConfigMaps and supports full feature capabilities, including variable descriptions and sensitive information flags.

Basic Structure:

name: "ConfigMap name"
description: "ConfigMap description"
variables:
  VARIABLE_NAME:
    value: "variable value"
    description: "variable description"
    isSecret: false

Full Example:

name: "auth-service"
description: "Authentication service configuration"
variables:
  JWT_SECRET_KEY:
    value: "your-very-secret-jwt-key-here"
    description: "JWT signing key"
    isSecret: true
  TOKEN_EXPIRATION:
    value: "24h"
    description: "Token expiration time"
    isSecret: false
  OAUTH_CLIENT_ID:
    value: "oauth-client-12345"
    description: "OAuth client ID"
  OAUTH_CLIENT_SECRET:
    value: "oauth-secret-67890"
    description: "OAuth client secret"
    isSecret: true
  ENABLE_2FA:
    value: "true"
    description: "Whether to enable two-factor authentication"

2. Kubernetes ConfigMap Format

The standard Kubernetes ConfigMap format, suitable for integration with K8s environments.

Basic Structure:

apiVersion: v1
kind: ConfigMap
metadata:
  name: "ConfigMap name"
data:
  VARIABLE_NAME: "variable value"

Full Example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: "database-config"
  labels:
    app: "my-application"
    environment: "production"
data:
  DATABASE_HOST: "prod-db.example.com"
  DATABASE_PORT: "5432"
  DATABASE_NAME: "myapp_production"
  DATABASE_USER: "app_user"
  REDIS_URL: "redis://redis.example.com:6379"
  MAX_CONNECTIONS: "100"

Format Comparison

Feature	Simplified Format	Kubernetes Format
Variable Description	✅ Supported	❌ Not Supported
Sensitive Info Flag	✅ Supported	❌ Not Supported
ConfigMap Description	✅ Supported	❌ Not Supported
K8s Compatibility	❌ Not Compatible	✅ Fully Compatible
File Size	Larger	Smaller
Readability	Better	Average

YAML Syntax Rules

Basic Syntax

1. Indentation: Use 2 spaces for indentation; do not use tabs
2. Key-Value Pairs: Separate with a colon and space key: value
3. Strings: Recommend wrapping string values in double quotes
4. Booleans: Use true or false
5. Comments: Start comment lines with #

String Handling

Plain Strings:

SIMPLE_VALUE: "hello world"

Multi-line Strings:

MULTI_LINE_VALUE: |
  This is a multi-line string
  Second line content
  Third line content

Strings Containing Special Characters:

SPECIAL_CHARS: "String with \"quotes\" and \n newlines"
DATABASE_URL: "postgresql://user:pass@host:5432/db?sslmode=require"

JSON-formatted Strings:

JSON_CONFIG: '{"timeout": 30, "retries": 3, "endpoints": ["api1", "api2"]}'

Data Type Examples

name: "data-types-example"
description: "Examples of various data types"
variables:
  # String type
  STRING_VALUE:
    value: "This is a string"
    description: "String example"
  
  # Number type
  NUMBER_VALUE:
    value: "12345"
    description: "Number example"
  
  # Boolean type
  BOOLEAN_VALUE:
    value: "true"
    description: "Boolean example"
  
  # URL type
  URL_VALUE:
    value: "https://api.example.com/v1"
    description: "URL example"
  
  # Password type
  PASSWORD_VALUE:
    value: "super-secret-password"
    description: "Password example"
    isSecret: true
  
  # JSON configuration
  JSON_VALUE:
    value: '{"host": "localhost", "port": 3000}'
    description: "JSON configuration example"

Practical Examples

Example 1: Microservice Configuration

name: "microservice-config"
description: "Microservice common configuration"
variables:
  # Service configuration
  SERVICE_NAME:
    value: "user-service"
    description: "Service name"
  
  SERVICE_PORT:
    value: "8080"
    description: "Service port"
  
  SERVICE_VERSION:
    value: "1.2.3"
    description: "Service version"
  
  # Database configuration
  DATABASE_URL:
    value: "postgresql://localhost:5432/userdb"
    description: "Database connection URL"
    isSecret: true
  
  DATABASE_POOL_SIZE:
    value: "20"
    description: "Database connection pool size"
  
  # Cache configuration
  REDIS_URL:
    value: "redis://localhost:6379"
    description: "Redis connection URL"
  
  CACHE_TTL:
    value: "3600"
    description: "Cache expiration time (seconds)"
  
  # Logging configuration
  LOG_LEVEL:
    value: "info"
    description: "Log level"
  
  LOG_FORMAT:
    value: "json"
    description: "Log format"

Example 2: Third-Party Service Integration

name: "external-services"
description: "Third-party service configuration"
variables:
  # Email service
  SMTP_HOST:
    value: "smtp.gmail.com"
    description: "SMTP server address"
  
  SMTP_PORT:
    value: "587"
    description: "SMTP server port"
  
  SMTP_USER:
    value: "noreply@example.com"
    description: "SMTP username"
  
  SMTP_PASSWORD:
    value: "smtp-app-password"
    description: "SMTP password"
    isSecret: true
  
  # Object storage
  S3_BUCKET_NAME:
    value: "my-app-storage"
    description: "S3 bucket name"
  
  S3_ACCESS_KEY:
    value: "AKIAIOSFODNN7EXAMPLE"
    description: "S3 access key ID"
    isSecret: true
  
  S3_SECRET_KEY:
    value: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    description: "S3 secret access key"
    isSecret: true
  
  S3_REGION:
    value: "us-west-2"
    description: "S3 region"
  
  # Payment service
  STRIPE_PUBLIC_KEY:
    value: "pk_test_51234567890"
    description: "Stripe public key"
  
  STRIPE_SECRET_KEY:
    value: "sk_test_51234567890"
    description: "Stripe secret key"
    isSecret: true
  
  STRIPE_WEBHOOK_SECRET:
    value: "whsec_1234567890"
    description: "Stripe webhook secret"
    isSecret: true

Example 3: Feature Toggle Configuration

name: "feature-toggles"
description: "Feature toggle configuration"
variables:
  # New feature toggles
  ENABLE_NEW_DASHBOARD:
    value: "true"
    description: "Enable new dashboard"
  
  ENABLE_DARK_MODE:
    value: "true"
    description: "Enable dark theme"
  
  ENABLE_NOTIFICATIONS:
    value: "false"
    description: "Enable push notifications"
  
  # Performance-related
  MAX_UPLOAD_SIZE_MB:
    value: "100"
    description: "Maximum upload file size (MB)"
  
  REQUEST_TIMEOUT_SECONDS:
    value: "30"
    description: "Request timeout (seconds)"
  
  MAX_CONCURRENT_REQUESTS:
    value: "1000"
    description: "Maximum concurrent requests"
  
  # Maintenance mode
  MAINTENANCE_MODE:
    value: "false"
    description: "Maintenance mode toggle"
  
  MAINTENANCE_MESSAGE:
    value: "The system is under maintenance and is expected to be restored in 30 minutes"
    description: "Maintenance mode message"
  
  # A/B testing
  AB_TEST_NEW_CHECKOUT:
    value: "50"
    description: "New checkout flow A/B test ratio (%)"
  
  AB_TEST_RECOMMENDATION_ENGINE:
    value: "25"
    description: "Recommendation engine A/B test ratio (%)"

Import/Export Operations

Export Configuration

1. Click the "Export YAML" button in the configuration variable management interface
2. Select the export format:
   • Simplified Format: Includes complete variable information and descriptions
   • Kubernetes Format: Standard K8s ConfigMap format
3. The system automatically downloads the YAML file

Import Configuration

1. Click the "Import YAML" button to open the import dialog
2. Select the YAML format and import options
3. Three ways to upload a file:
   • Drag and Drop: Drag a .yaml or .yml file directly into the upload area
   • Click to Select: Click the "Choose File" button to browse files
   • Manual Input: Directly edit YAML content in the text box
4. The system automatically detects the format and pre-fills the content
5. Click "Import Configuration" to complete the import

Import Option Details

• Overwrite Existing Variables:
  • ✅ Checked: Existing variables with the same name will be overwritten during import
  • ❌ Unchecked: Same-named variables are skipped; only new variables are imported

Common Errors and Solutions

1. Indentation Error

Incorrect Example:

variables:
WRONG_INDENT:  # Missing indentation
  value: "incorrect"

Correct Example:

variables:
  CORRECT_INDENT:  # Correct 2-space indentation
    value: "correct"

2. Incorrect Quote Usage

Incorrect Example:

MIXED_QUOTES:
  value: "String with 'single quotes'"  # May cause parsing errors

Correct Example:

PROPER_QUOTES:
  value: "String with \"double quotes\""  # Properly escaped

3. Special Character Handling

Incorrect Example:

DATABASE_URL:
  value: postgresql://user:p@ssw0rd@host:5432/db  # @ symbol not escaped

Correct Example:

DATABASE_URL:
  value: "postgresql://user:p@ssw0rd@host:5432/db"  # Wrapped in quotes

4. Boolean Value Format

Incorrect Example:

ENABLE_FEATURE:
  value: True  # Uppercase T

Correct Example:

ENABLE_FEATURE:
  value: "true"  # Lowercase, recommended to use quotes

Best Practices

1. Format Selection Recommendations

• Use Simplified Format: When you need detailed variable descriptions and sensitive information flags
• Use K8s Format: When you need to integrate with Kubernetes environments
• Mixed Use: Choose different formats for different ConfigMaps based on their purpose

2. Naming Conventions

# Recommended variable naming
variables:
  DATABASE_URL:          # All uppercase, underscore separated
    value: "..."
  
  SMTP_HOST:             # Use prefixes to distinguish services
    value: "..."
  
  ENABLE_NEW_FEATURE:    # Use ENABLE_ prefix for booleans
    value: "true"
  
  MAX_UPLOAD_SIZE_MB:    # Include unit information
    value: "100"

3. Sensitive Information Handling

variables:
  # Clearly mark sensitive information
  DATABASE_PASSWORD:
    value: "super-secret-password"
    description: "Database password"
    isSecret: true
  
  API_KEY:
    value: "sk-1234567890abcdef"
    description: "Third-party API key"
    isSecret: true
  
  # Non-sensitive information does not need marking
  DATABASE_HOST:
    value: "localhost"
    description: "Database host address"
    isSecret: false  # Can be omitted, defaults to false

4. Documentation Recommendations

name: "well-documented-config"
description: "Example of a well-documented ConfigMap"
variables:
  # Provide clear descriptions for each variable
  JWT_SECRET_KEY:
    value: "your-secret-key"
    description: "Key for JWT token signing, at least 32 characters"
    isSecret: true
  
  TOKEN_EXPIRATION:
    value: "24h"
    description: "JWT token expiration time, supported formats: 1h, 30m, 24h, 7d"
  
  MAX_LOGIN_ATTEMPTS:
    value: "5"
    description: "Maximum user login attempts; account is locked after exceeding this limit"

5. Version Control

• Add version comments before exporting configurations:

# Configuration version: v1.2.0
# Updated: 2024-01-15
# Update notes: Added new cache configuration
name: "my-config"
description: "Application configuration v1.2.0"
variables:
  # ... configuration content

Validation and Testing

1. Syntax Validation

You can use online YAML validators to check syntax before importing:

• YAML Lint
• Online YAML Parser

2. Test Import

We recommend testing YAML imports in a test environment first:

1. Create a test ConfigMap
2. Import the YAML file
3. Verify that variables were imported correctly
4. Check that sensitive information flags are correct

3. Backup Strategy

• Export existing configurations as a backup before importing
• Create ConfigMap snapshots before important configuration changes
• Regularly back up critical ConfigMaps

Troubleshooting

Common Import Errors

1. "YAML format error"

   • Check that indentation is correct (use 2 spaces)
   • Confirm there is a space after colons
   • Check that quotes are properly matched

2. "Variable name does not meet requirements"

   • Variable names can only contain letters, numbers, and underscores
   • Must start with a letter or underscore
   • Cannot contain spaces or special characters

3. "File format not supported"

   • Ensure the file extension is .yaml or .yml
   • Check that the file encoding is UTF-8

4. "Partial import failure"

   • Review the import result statistics
   • Check for duplicate variable names
   • Confirm the "Overwrite Existing Variables" option setting

By following the recommendations and best practices in this guide, you can efficiently use the YAML format to manage ConfigMaps, ensuring the accuracy and maintainability of your configuration data.

Related Documentation

• ConfigMap Overview — ConfigMap basic concepts and operations
• ConfigMap Best Practices — Configuration management best practices
• Environment Variables — Using configuration variables in workflows