ConfigMaps in CGC SDK

Overview

config_maps_data lets you pass configuration data to containers as Kubernetes ConfigMaps. It is an alternative to environment variables (environment_data) – instead of passing individual keys, you can pass whole dictionaries of configuration data.

Data format

config_maps_data accepts a list of strings in the format:

"CONFIG_MAP_NAME=JSON_DATA"

Where:

CONFIG_MAP_NAME – the name of the ConfigMap in Kubernetes
JSON_DATA – a JSON-formatted string representing a dictionary { "key": "value", ... }

Format example:

config_maps_data=[
    "app-config={\"DATABASE_URL\": \"postgres://db:5432\", \"CACHE_TTL\": \"3600\"}",
    "feature-flags={\"ENABLE_NEW_UI\": \"true\", \"MAX_RETRIES\": \"3\"}"
]

How it works in code

Data parsing

The code processes config_maps_data as follows:

config_maps_data_dict = {}
for config_map in config_maps_data:
    key, value = config_map.split("=")  # Splits the name from the data
    config_maps_data_dict[key] = value  # value should be a JSON string
payload["config_maps_data"] = config_maps_data_dict

Important: The value after = is passed as a string – the backend parses it as JSON itself.

Usage examples

Example 1: Basic usage with `resource_create()`

import cgc.sdk.resource as resource

response = resource.resource_create(
    name="my-app-with-config",
    image_name="python:3.9",
    cpu=2,
    memory=4,
    config_maps_data=[
        "app-settings={\"LOG_LEVEL\": \"info\", \"DEBUG\": \"false\"}",
        "database-config={\"DB_HOST\": \"postgres\", \"DB_PORT\": \"5432\"}"
    ]
)

Example 2: Environment variable vs ConfigMap

Environment variable (simple):

environment_data=[
    "LOG_LEVEL=info",
    "DEBUG=false"
]

ConfigMap (structured):

config_maps_data=[
    "logging-config={\"LOG_LEVEL\": \"info\", \"LOG_FORMAT\": \"json\", \"LOG_OUTPUT\": \"/var/log/app.log\"}"
]

Example 3: Complete example with multiple ConfigMaps

import cgc.sdk.resource as resource
import json

# Prepare the configuration data
app_config = {
    "API_URL": "https://api.example.com",
    "TIMEOUT": "30",
    "MAX_CONNECTIONS": "100"
}

db_config = {
    "DB_HOST": "postgres.default.svc",
    "DB_PORT": "5432",
    "DB_NAME": "myapp",
    "DB_POOL_SIZE": "10"
}

feature_flags = {
    "ENABLE_CACHE": "true",
    "CACHE_TTL": "3600",
    "ENABLE_METRICS": "true"
}

response = resource.resource_create(
    name="production-app",
    image_name="my-registry/app:v1.2.3",
    cpu=4,
    memory=8,
    gpu=0,
    environment_data=[
        "ENV=production",
        "APP_VERSION=1.2.3"
    ],
    config_maps_data=[
        f"app-config={json.dumps(app_config)}",
        f"database-config={json.dumps(db_config)}",
        f"features={json.dumps(feature_flags)}"
    ],
    startup_command="python main.py"
)

if response['code'] == 200:
    print("✓ Application started with ConfigMaps")
else:
    print(f"✗ Error: {response.get('message')}")

Example 4: Usage with jobs (`job_create()`)

import cgc.sdk.job as job
import json

batch_config = {
    "BATCH_SIZE": "1000",
    "RETRY_COUNT": "3",
    "OUTPUT_FORMAT": "parquet"
}

response = job.job_create(
    name="data-processing-batch",
    image_name="my-registry/batch-processor:latest",
    cpu=2,
    memory=4,
    startup_command="python process_batch.py",
    config_maps_data=[
        f"batch-settings={json.dumps(batch_config)}"
    ],
    ttl_seconds_after_finished=7200  # Cleanup after 2h
)

How the configuration is available inside the container

In a Kubernetes container, ConfigMaps are mounted by default as files in the /etc/config/ directory or as environment variables, depending on the deployment configuration.

Option A: As files (default)

/etc/config/app-config       # Contents: {"API_URL": "...", ...}
/etc/config/database-config  # Contents: {"DB_HOST": "...", ...}

Option B: As environment variables (if configured)

echo $app-config  # {"API_URL": "...", ...}

Note: The exact mounting method depends on the deployment template used by CGC. Check the cgc-server documentation or ask about the details of ConfigMap mounting in your namespace.

Common mistakes

❌ Mistake 1: Invalid JSON format

# BAD - missing quotes in JSON
config_maps_data=[
    "app-config={LOG_LEVEL: info}"  # ❌ Invalid JSON
]

# GOOD - valid JSON string
config_maps_data=[
    "app-config={\"LOG_LEVEL\": \"info\"}"  # ✅ Valid
]

❌ Mistake 2: Missing `=` sign

# BAD
config_maps_data=[
    "app-config{\"LOG_LEVEL\": \"info\"}"  # ❌ Missing '='
]

# GOOD
config_maps_data=[
    "app-config={\"LOG_LEVEL\": \"info\"}"  # ✅
]

❌ Mistake 3: Incorrect escaping in Python

# BAD - conflicting quotes
config_maps_data=[
    "app-config={"LOG_LEVEL": "info"}"  # ❌ SyntaxError
]

# GOOD - use json.dumps() or escape
import json
config_maps_data=[
    f"app-config={json.dumps({'LOG_LEVEL': 'info'})}"  # ✅
]
# OR
config_maps_data=[
    "app-config={\\\"LOG_LEVEL\\\": \\\"info\\\"}"  # ✅
]

Comparison: `environment_data` vs `config_maps_data`

Feature	`environment_data`	`config_maps_data`
Format	`KEY=VALUE`	`NAME={JSON_DATA}`
Structure	Flat dictionary	Nested dictionaries
Organization	All variables together	Grouped by topic
Readability	Good for simple configurations	Better for complex ones
Example	`["LOG_LEVEL=info", "DEBUG=false"]`	`["logging={\"LOG_LEVEL\": \"info\", \"DEBUG\": \"false\"}"]`
Use case	Simple environment variables	Complex configurations, config files

Best Practices

Use json.dumps() to generate JSON:

import json
config_maps_data=[
    f"my-config={json.dumps({'KEY': 'value'})}"
]

Group configuration by topic:

config_maps_data=[
    "database={...}",
    "cache={...}",
    "logging={...}"
]

Avoid storing secrets in ConfigMaps – use Kubernetes Secrets instead.

Validate JSON before sending:

import json
try:
    json.dumps(my_dict)  # Validation
except TypeError as e:
    print(f"Invalid format: {e}")

Summary

config_maps_data is a powerful tool for passing structured configuration data to containers in CGC. Use it when:

You have complex configurations with many related keys
You want to group configuration by topic
You need to pass data in JSON/XML/YAML format

For simple environment variables, keep using environment_data.

Sources: Analysis of the cgc-client code:

cgc/commands/jobs/job_utils.py (lines 123-137)
cgc/commands/compute/compute_utils.py (lines 310-324)
cgc/sdk/resource.py (lines 254, 326, 362-363)
cgc/sdk/examples/basic_compute.py

Overview​

Data format​

Format example:​

How it works in code​

Data parsing​

Usage examples​

Example 1: Basic usage with resource_create()​

Example 2: Environment variable vs ConfigMap​

Example 3: Complete example with multiple ConfigMaps​

Example 4: Usage with jobs (job_create())​

How the configuration is available inside the container​

Option A: As files (default)​

Option B: As environment variables (if configured)​

Common mistakes​

❌ Mistake 1: Invalid JSON format​

❌ Mistake 2: Missing = sign​

❌ Mistake 3: Incorrect escaping in Python​

Comparison: environment_data vs config_maps_data​

Best Practices​

Summary​