This topic describes the scenarios and procedures for using ConfigMaps in containers.

Background

Enterprise application deployment involves significant configuration management. Hardcoding configurations into container images creates environment-specific dependencies, requiring separate image builds per environment. ConfigMaps decouple configuration from applications, enabling a single image to run across multiple environments (development, testing, and production) by storing non-sensitive configuration data.

After creating a ConfigMap, you can use it in containers via two methods.

Usage methods	Description	Application scenario
Environment variable injection	Injects key-value pairs from the ConfigMap directly into container environment variables.	Simple runtime parameters, feature flags, database connection strings, and other short configuration items.
Data volume mounting	Mounts data stored in the ConfigMap as a file into a specified container directory. This method supports automatic synchronization and hot updates.	Complete configuration file management and scenarios requiring dynamic updates without container restarts.

Preparation

Prepare the ConfigMap in advance. For details, see Creating ConfigMaps. ‌To facilitate validation of ConfigMap usage, this topic uses the sample ConfigMap file demo-config.yaml below.

Procedure

Scenario 1: Environment variable injection

This section illustrates how to use a ConfigMap to set environment variables for a workload (in this example, a Deployment).

Configure through the console

Configure through kubectl

Log in to the VKE console.

In the left navigation bar, click Cluster.

On the Cluster page, click the name of the target cluster.

Click Workload > Deployment. On the Deployment page, click Create Deployment.

On the Create Deployment page, configure the following parameters as described below and other parameters as needed. For detailed instructions, see Creating Deployments.

In Step 2 Container configuration, click the + icon in the Environment variables section to use the ConfigMap prepared in the prerequisites as the environment variables for the Deployment.

Click Confirm to create the Deployment.

Check the Deployment creation result and verify whether the environment variables have been injected successfully.

On the Deployment page, find the newly created Deployment and click its name to enter the Deployment details page.

On the Deployment details page, click the List of instances tab to view whether all pods corresponding to the Deployment are in the status of Running.

Click the Pod name to enter the Pods details page. Click Console in the upper-right corner of the page to log in to the Pod and then run the following command to verify whether the environment variables have been injected successfully.

env | grep CONFIG_

If the output matches the ConfigMap data, environment variable injection has successfully enabled the Deployment to access the ConfigMap data.

Scenario 2: Data volume mounting

This section illustrates how to mount a ConfigMap as a data volume for a workload (in this example, a Deployment).

Configure through the console

Configure through kubectl

Log in to the VKE console.

In the left navigation bar, click Cluster.

On the Cluster page, click the name of the target cluster.

Click Workload > Deployment. On the Deployment page, click Create Deployment.

On the Create Deployment page, configure the following parameters as described below and other parameters as needed. For detailed instructions, see Creating Deployments.

In Step 2 Container configuration, configure Storage configuration parameters as described below.

For Add volume, click the + icon and configure the ConfigMap as a volume.

For Mount volume, click the + icon to mount the ConfigMap.

Click Confirm to create the Deployment.

Check the Deployment creation result and verify whether the environment variables have been injected successfully.

On the Deployment page, find the newly created Deployment and click its name to enter the Deployment details page.

On the Deployment details page, click the List of instances tab to view whether all pods corresponding to the Deployment are in the status of Running.

Click the Pod name to enter the Pods details page. Click Console in the upper-right corner of the page to log in to the Pod and then run the following command to verify whether the ConfigMap has been mounted successfully.

ls /etc/config/

If the output is the filenames corresponding to each key in the ConfigMap (for example, APP_MODE and LOG_LEVEL), the mounting is successful.

Run the following command to check whether the configuration file's content is correct.

cat /etc/config/APP_MODE

If the output is the value corresponding to the APP_MODE file (such as prod), the configuration is correct.

Connect to the target cluster using kubectl. For details, see Connecting to a cluster via kubectl.

The following Deployment YAML file configmap-volume-demo.yaml serves as an example. For detailed YAML configuration instructions, see Creating Deployments.

apiVersion: apps/v1
kind: Deployment
metadata:
name: configmap-volume-demo # Deployment name.
namespace: default # Namespace of the Deployment. The namespace must match the ConfigMap's namespace.
spec:
replicas: 1 # The number of replicas for the Deployment.
selector:
matchLabels:
app: configmap-volume-demo
template:
metadata:
labels:
app: configmap-volume-demo
spec:
containers:
- name: nginx
image: vke-cn-beijing.cr.volces.com/vke/nginx:latest # Container image. Replace it with your image address.
command: ["/bin/sh", "-c", "cat /etc/config/game.properties && sleep 3600"]
volumeMounts: # In-container mount settings.
- name: config-volume # Reference the volume name defined in the volumes section below.
mountPath: /etc/config #-In-container mount directory. Files mapped from the ConfigMap will appear here, and applications can read them directly via file paths.
readOnly: true # Enable read-only mounting to prevent accidental modifications inside containers.
volumes: # Pod-level volume definition.
- name: config-volume # Volume name (corresponding to volumeMounts.name).
configMap:
name: demo-config # Name of the referenced ConfigMap.
items: # (Optional) Mount only some keys.
- key: game.properties
path: game.properties

Run the following command to create the Deployment.

kubectl apply -f configmap-volume-demo.yaml

Run the following command to check whether the workload is running normally. If the Pod is in the Running state, the Deployment has been created successfully.

kubectl get pods -l app=configmap-volume-demo -n default

Run the following command to verify that the ConfigMap is mounted successfully and contains the correct content.

kubectl exec deployment/configmap-volume-demo -n default -- ls -l /etc/config

If the mount directory list in the output contains the game.properties file, the mount is successful.

Run the following command to check whether the ConfigMap data is correct.

kubectl exec deployment/configmap-volume-demo -n default -- cat /etc/config/game.properties

If the output matches the key-value pairs defined in the ConfigMap (as shown in the following example), the data volume has been mounted successfully.

APP_MODE=prod
LOG_LEVEL=info
PLAYER_NAME=vke-user

Subsequent operations

To apply ConfigMap updates to your workload promptly, follow the instructions below:

In environment variable scenarios, a rolling update is typically required. For example, for a Deployment, run the following command to perform a rolling update.

kubectl rollout restart deployment/<deployment-name> -n <namespace>
# Replace <deployment-name> with your Deployment name.
# Replace <namespace> with the namespace of your Deployment.

In data volume mounting scenarios, determine if a restart is needed based on your application's hot configuration reload mechanism.

Volcengine Kubernetes Engine