Skip to main content

ConfigMap Overview

ConfigMap is a feature for storing and managing application configuration data. It allows you to separate configuration information from application code, making configuration management more flexible and secure.

Access Path​

  • Console → Settings → Configuration tab
  • Or navigate directly to /settings?tab=configmaps
  • When configuring environment variables in the workflow editor, click "Go to Configuration" to jump to ConfigMap
Using in Workflows

Variables in a ConfigMap can be used as environment variables in workflows. To learn how to use environment variables in workflows, see the Workflow Environment Variables Guide.

What is a ConfigMap​

A ConfigMap is a container that holds key-value configuration data. Each ConfigMap can contain multiple configuration variables that can be used in your tasks, agents, operators, or other application components. ConfigMaps enable modular configuration management, allowing you to logically group configurations for different services or functions.

Key Features​

  • Configuration Isolation: Create independent ConfigMaps for different services, components, or environments, enabling modular configuration management
  • Team Isolation: Each team can only access and manage its own ConfigMaps
  • Secure Management: Supports secure storage and access control for sensitive information
  • Default Configuration: Supports setting a default ConfigMap
  • Batch Import: Supports batch importing configurations via YAML files
  • Smart Search: Quickly find and filter ConfigMaps and variables
  • Full-Screen Management: Uses a full-screen modal window for a better management experience

Core Concepts​

ConfigMap​

A ConfigMap is a logical grouping of configuration data. You can organize them by component, service function, or environment, enabling modular configuration management. This approach helps reduce configuration complexity and improve maintainability.

Common organizational examples:

  • auth-service - Authentication service configuration
  • redis-config - Redis cache connection information
  • feature-toggles - Feature toggle collection
  • production-secrets - Production environment sensitive information
  • shared-settings - Configuration shared across multiple services

Configuration Variable (ConfigVariable)​

A configuration variable is a specific key-value pair stored in a ConfigMap:

  • Key: The name of the configuration item, e.g., DATABASE_URL
  • Value: The value of the configuration item, e.g., postgresql://localhost:5432/mydb
  • Description: An explanation of the configuration item
  • Sensitive Flag: Marks whether the item contains sensitive information (e.g., passwords, API keys)

Use Cases​

ConfigMaps provide a flexible configuration management approach suitable for a variety of scenarios.

1. Separate Configuration by Service or Component​

Store configurations for different microservices or application components in their respective ConfigMaps.

Authentication Service Configuration (auth-service):

  • JWT_SECRET_KEY: "your-very-secret-key"
  • TOKEN_EXPIRATION: "24h"

Data Processing Task Configuration (data-processor):

  • BATCH_SIZE: 100
  • SOURCE_QUEUE: "raw-data-queue"

2. Manage Feature Toggles​

Use ConfigMaps to centrally manage application feature toggles for dynamic feature adjustments.

Feature Toggle Configuration (feature-toggles):

  • ENABLE_NEW_DASHBOARD: true
  • MAINTENANCE_MODE: false
  • MAX_UPLOAD_SIZE_MB: 100

3. Manage Third-Party Service Credentials​

Centrally store connection information and keys for external services (such as databases, caches, email services).

External Service Configuration (external-services):

  • DATABASE_URL: "postgresql://user:pass@host:5432/db"
  • REDIS_URL: "redis://localhost:6379"
  • S3_BUCKET_NAME: "my-app-storage"

4. Provide Environment-Specific Configuration​

While not the only use case, ConfigMaps are commonly used to differentiate configurations across deployment environments (e.g., development, testing, production).

Production Database (production-db):

  • DATABASE_URL: postgresql://prod-db:5432/app

Development Database (development-db):

  • DATABASE_URL: postgresql://localhost:5432/app_dev

Interface Feature Details​

ConfigMap Management Interface​

Main Functional Areas​

  • Search Bar: Quickly search ConfigMap names and descriptions
  • Create Button: Create a new ConfigMap
  • ConfigMap List: Display detailed information for all ConfigMaps
  • Action Buttons: Manage variables, edit, delete, and other operations

List Information Display​

  • Name: ConfigMap name; the default ConfigMap displays a star icon (⭐)
  • Description: Purpose description of the ConfigMap
  • Default Status: Indicates whether it is the default ConfigMap
  • Variable Count: Number of configuration variables contained
  • Created Time: ConfigMap creation date
  • Action Buttons: Manage variables, edit, delete

Configuration Variable Management Interface​

Full-Screen Modal Window​

Configuration variable management uses a full-screen modal window design for a better experience:

  • Large Screen Display: Maximum width of 7xl, height of 90vh, making full use of screen space
  • Responsive Design: Adapts to different screen sizes
  • Fixed Header: Displays current ConfigMap information and close button

Feature Toolbar​

  • Search Box: Real-time search for variable keys, values, and descriptions
  • Sensitive Info Toggle: Show/hide sensitive information content
  • Export YAML: Export configuration as a YAML file
  • Import YAML: Batch import configurations from a YAML file
  • Add Variable: Create a new configuration variable

Variable List Table​

  • Sticky Header: Header remains visible while scrolling
  • Hover Effect: Rows highlight on mouse hover
  • Type Indicator: Clearly distinguishes between normal and sensitive variables
  • Action Buttons: Quick operations such as edit and delete

How to Use ConfigMaps​

1. Access ConfigMap Management​

  1. After logging in, click the user avatar in the upper-right corner
  2. Select "Settings" to enter the settings page
  3. Click the "ConfigMap" tab

2. Create a ConfigMap​

  1. Click the "Create New ConfigMap" button
  2. Fill in the following information:
    • Name: Unique identifier for the ConfigMap (only letters, numbers, hyphens, and underscores allowed)
    • Description: Purpose description of the ConfigMap
    • Set as Default: Whether to set this ConfigMap as the team's default configuration
  3. Click "Create ConfigMap" to complete creation

3. Manage ConfigMaps​

View and Search ConfigMaps​

  • List View: Displays detailed information for all ConfigMaps in table format
  • Real-time Search: Enter keywords in the search box for instant filtering
  • Search Scope: Supports searching by name and description
  • Default Indicator: The default ConfigMap displays a star icon (⭐) and a "Default" label

Edit a ConfigMap​

  1. Click the "Edit" button on the ConfigMap row
  2. Modify the name, description, or default status
  3. Click "Save Changes"

Delete a ConfigMap​

  1. Click the "Delete" button on the ConfigMap row
  2. Click "Confirm Delete" in the confirmation dialog
  3. Note: The default ConfigMap cannot be deleted

4. Manage Configuration Variables​

Access the Variable Management Interface​

  1. Click the "Manage Variables" button on the ConfigMap row
  2. The system opens a full-screen modal window displaying all variables for that ConfigMap

Search and Filter Variables​

  • Real-time Search: Enter keywords in the search box to instantly filter matching variables
  • Search Scope: Supports searching by variable name, value, and description
  • Sensitive Info Control: Use the "Show/Hide Sensitive Info" button to control the display of sensitive data

Add a Configuration Variable​

  1. Click the "Add Variable" button
  2. Fill in the variable information:
    • Variable Name: Key name of the configuration item (required)
    • Variable Value: Value of the configuration item (required)
    • Description: Description of the configuration item (optional)
    • Sensitive Info: Check this box to mark the variable as sensitive
  3. Click "Add Variable" to complete creation

Edit a Configuration Variable​

  1. Click the "Edit" button on the variable row
  2. Modify any variable information
  3. Click "Save Changes"

Delete a Configuration Variable​

  1. Click the "Delete" button on the variable row
  2. The system immediately deletes the variable (please proceed with caution)

5. YAML Import/Export​

Export YAML​

  1. Click the "Export YAML" button in the variable management interface
  2. Select the export format:
    • Simplified Format: A concise format suitable for manual editing
    • Kubernetes ConfigMap: Standard K8s ConfigMap format
  3. The system automatically downloads the YAML file

Import YAML​

  1. Click the "Import YAML" button to open the import dialog
  2. Select the YAML format and import options:
    • YAML Format: Choose simplified format or Kubernetes ConfigMap format
    • Import Options: Decide whether to overwrite existing variables
  3. Upload the YAML 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 large text box (24 lines tall)
  4. The system automatically detects the file format and pre-fills the content
  5. Click "Import Configuration" to complete the import

YAML Format Examples​

Simplified Format:

name: my-config
description: "My ConfigMap"
variables:
  DATABASE_URL:
    value: "postgresql://localhost:5432/mydb"
    description: "Database connection URL"
  API_KEY:
    value: "your-api-key"
    description: "API key"
    isSecret: true

Kubernetes ConfigMap Format:

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-config
data:
  DATABASE_URL: "postgresql://localhost:5432/mydb"
  API_KEY: "your-api-key"

Configuration Access Rules​

Variables in a ConfigMap can be used as environment variables in tasks, operators, agents, and other components. The system merges configurations according to the following priority:

Configuration Access Priority​

Configuration access follows this priority (from highest to lowest):

  1. Task/Operator Direct Configuration (highest priority)

    • Environment variables directly configured in a Task
    • Configuration information directly configured in an Operator
    • These configurations have the highest priority and override configurations from other sources

  2. Bound ConfigMap (medium priority)

    • Tasks, operators, or agents can be bound to a specific ConfigMap
    • Example: ConfigMap: some-operator-config
    • Variables in the bound ConfigMap are accessible as environment variables
    • The ConfigMap's access scope is limited to the bound component

  3. Default ConfigMap (lowest priority)

    • The system default ConfigMap is visible to all components
    • Accessible as environment variables: {{YOUR_KEY}}
    • Serves as the base configuration with the lowest priority
Using in Workflows

To learn how to use these environment variables in workflows (including template syntax, data paths, etc.), see the Workflow Environment Variables Guide.

Configuration Access Scope​

  1. Global Access

    • Variables in the default ConfigMap can be accessed by all components
    • Using the environment variable format: {YOUR_KEY}

  2. Component-Level Access

    • A bound ConfigMap is only visible to the bound component
    • Similar to a ConfigMap bound to a Kubernetes Deployment
    • Provides better isolation and security

  3. Direct Configuration

    • Variables directly configured in a Task or Operator
    • Only visible to the configured component
    • Provides the highest flexibility and priority

Usage Example​

# Scenario: Configuration loading and override process when a task runs

# 1. Default ConfigMap: 'global-config' (lowest priority)
#    Accessible by all components.
#    Suppose it defines:
#    LOG_LEVEL: "info"
#    API_URL: "https://api.service.com"

# 2. Operator-bound ConfigMap: 'some-operator-config' (medium priority)
#    An Operator can be bound to a specific ConfigMap.
#    Suppose the 'my-operator' operator is bound to 'some-operator-config', which defines:
#    LOG_LEVEL: "debug"            # Overrides LOG_LEVEL from 'global-config'
#    DB_HOST: "db.operator.internal" # New operator-specific configuration

# 3. Task-level directly defined environment variables (highest priority)
#    Directly set in the Task definition, overriding same-named variables from all ConfigMaps.
#    Suppose a task 'my-task' using 'my-operator' defines:
#    LOG_LEVEL: "warn"             # Overrides LOG_LEVEL from 'some-operator-config'
#    MAX_RETRIES: "5"              # New task-specific configuration

# ---
# The effective environment variables when 'my-task' runs:
#
# LOG_LEVEL: "warn"
#   - Source: Task direct definition, highest priority.
#
# API_URL: "https://api.service.com"
#   - Source: Default ConfigMap 'global-config', not overridden.
#
# DB_HOST: "db.operator.internal"
#   - Source: Operator-bound 'some-operator-config'.
#
# MAX_RETRIES: "5"
#   - Source: Task direct definition.

Best Practices​

1. Naming Conventions​

ConfigMap Naming:

  • Use descriptive names: auth-service, redis-config, feature-toggles
  • Avoid special characters; only use letters, numbers, hyphens, and underscores
  • Keep names concise and descriptive, reflecting the purpose or associated component

Configuration Variable Naming:

  • Use uppercase letters and underscores: DATABASE_URL, API_KEY
  • Use prefixes to distinguish types: DB_HOST, REDIS_PORT, SMTP_USER

2. Configuration Grouping Strategies​

Choose an appropriate grouping strategy based on your actual needs:

Group by Service:

- auth-service      # Authentication service configuration
- payment-service   # Payment service configuration  
- notification-service # Notification service configuration

Group by Function:

- database-config   # Database-related configuration
- cache-config      # Cache-related configuration
- feature-toggles   # Feature toggles

Group by Environment (optional):

- production-secrets  # Production environment sensitive configuration
- development-config  # Development environment configuration

3. Sensitive Information Management​

  • Mark passwords, API keys, and other sensitive information as "sensitive"
  • Sensitive information is displayed as •••••••• in the interface
  • Real content is only shown when using the "Show Sensitive Info" feature
  • Regularly update sensitive information
  • Do not include sensitive information in configuration descriptions

4. Configuration Organization​

Group configurations by function or service:

Authentication Service ConfigMap (auth-service):

- JWT_SECRET_KEY
- TOKEN_EXPIRATION
- OAUTH_CLIENT_ID
- OAUTH_CLIENT_SECRET

Database ConfigMap (database-config):

- DB_HOST
- DB_PORT  
- DB_NAME
- DB_USER
- DB_PASSWORD

External Services ConfigMap (external-services):

- SMTP_HOST
- SMTP_PORT
- REDIS_URL
- S3_BUCKET_NAME

5. Default ConfigMap​

  • Each team has only one default ConfigMap
  • The default ConfigMap typically contains globally common configurations such as system-level settings
  • Variables in the default ConfigMap are accessible by all components
  • The default ConfigMap cannot be deleted, ensuring system stability
  • It is recommended to place commonly used, non-sensitive configurations in the default ConfigMap

6. Search and Filtering Tips​

  • Quick Locate: Use the search function to quickly find specific ConfigMaps or variables
  • Fuzzy Matching: Search supports partial matching; entering keywords will find related configurations
  • Multi-field Search: Search matches across multiple fields including name and description
  • Real-time Filtering: Search results update in real time without pressing Enter

7. Batch Operation Recommendations​

  • YAML Import: Ideal for batch creating or updating large numbers of configuration variables
  • Format Selection: Choose the appropriate YAML format based on your use case
  • Backup First: Export existing configurations as a backup before large-scale operations
  • Import in Batches: For large volumes of configurations, import in batches for easier management

Security Considerations​

1. Access Control​

  • Only team members can access the team's ConfigMaps
  • Ensure team member permissions are set correctly

2. Sensitive Information Protection​

  • Always mark passwords and API keys as sensitive information
  • Use the "Hide Sensitive Info" feature to protect sensitive data from accidental exposure
  • Do not expose sensitive configurations in logs or error messages
  • Regularly review and update sensitive configurations

3. Configuration Change Management​

  • Back up important configurations using the export feature before making changes
  • Validate configuration changes in a test environment
  • Document the reasons and impacts of configuration changes
  • Use the search function to verify that changes have been applied correctly

4. File Upload Security​

  • Only upload YAML files from trusted sources
  • Carefully review YAML content before importing
  • Exercise extra caution when using the "Overwrite Existing Variables" option

FAQ​

Q: How do I use ConfigMaps in my application?​

A: Variables in a ConfigMap can be accessed through the API or SDK in your agents and tasks. Refer to the relevant developer documentation for specific usage methods.

Q: How many ConfigMaps can I create?​

A: There is no hard limit, but we recommend creating them reasonably based on actual needs to avoid overly fragmented configurations.

Q: How do I back up ConfigMaps?​

A: Use the "Export YAML" feature to export ConfigMaps as files for backup. We recommend regularly backing up important configurations.

Q: Can a deleted ConfigMap be recovered?​

A: A deleted ConfigMap cannot be directly recovered. Please confirm before deleting and use the export feature to create a backup.

Q: Why can't I delete the default ConfigMap?​

A: The default ConfigMap is the system's base configuration. Deleting it could affect the normal operation of applications that depend on it.

Q: What should I do if an error occurs during YAML import?​

A: Check whether the YAML file format is correct and ensure indentation and syntax conform to YAML specifications. The system will display specific error messages to help you identify the issue.

Q: How can I quickly find a specific configuration variable?​

A: Use the search function in the variable management interface to search by variable name, value, or description, with real-time filtering support.

Q: How do I securely manage sensitive information?​

A: Mark sensitive configurations as "sensitive information," and the system will automatically hide the display. Use the "Show Sensitive Info" feature only when needed to view actual content.

Q: How do I close the full-screen modal window?​

A: Click the "Close" button in the upper-right corner, or press the ESC key to quickly close the modal window.

Q: Are there restrictions on YAML file uploads?​

A: .yaml and .yml file formats are supported. Files can be uploaded by dragging and dropping or by clicking to select. The system automatically detects the file format.