How to use Kubernetes ConfigMaps
Managing multiple application configurations in Kubernetes can be really inconvenient. Hard-coding these configuration values directly inside your container image is not going to work, as your environments will be different, and you also have the overhead of maintaining these values throughout the image’s lifecycle.
Kubernetes ConfigMaps are the solution for this, and in this guide we will walk you through everything you need to know about Kubernetes ConfigMaps from the basics to practical implementation strategies that you can use in your organization.
What are Kubernetes ConfigMaps?
ConfigMaps are Kubernetes objects that let you store configuration data into key-value pairs. By using them, your non-confidential data is decoupled from your container images and your application code. By leveraging ConfigMaps you can easily reuse your container images in different environments, while deploying different ConfigMaps for your environments.
Kubernetes ConfigMaps can store anything inside them, from simple values, to entire configurations like an index.html file for nginx. Your pods can consume ConfigMaps in different ways, as environment variables, command-line arguments and even as configuration files that are mounted in a volume.
Why should you use ConfigMaps?
ConfigMaps solve several real world problems that you will encounter when working with containers and Kubernetes:
- Portability: ConfigMaps enable you to use different configurations for your applications in different environments without needing to rebuild your container images, or change your code logic. You can simply create a different ConfigMap in a different environment and point your pods to use that.
- Separation of concerns: Your developers can focus on the application logic while your DevOps teams can manage the configuration items independently.
- Version control: ConfigMaps, as any other Kubernetes manifest, can be version controlled so you can easily track configuration changes through your manifests. This also gives you a clear audit trail.
- Dynamic updates: Some of your applications might be able to reload configuration data without any restarts, and ConfigMaps are the feature that make this possible in Kubernetes
When to use Secrets instead of ConfigMaps?
If your application is using sensitive data, then you shouldn’t use ConfigMaps. Kubernetes also offers Secrets that are base-64 encoded by default, and you can enable encryption at rest for additional security.
By leveraging the External Secrets Operator or the Secrets Store CIS you can easily integrate with external secrets management tools like HashiCorp Vault, OpenBao, AWS Secrets Manager, Azure Key Vault and others, to ensure that your secrets are encrypted properly and rotation is also enabled.
How to create ConfigMaps?
You can create ConfigMaps in several ways, so let’s see them.
Using kubectl to create ConfigMaps
The easiest way to create a ConfigMap is by using the kubectl create configmap command:
kubectl create configmap db-conf \
--from-literal=DATABASE_HOST=my_db_host \
--from-literal=DATABASE_PORT=5432
The above command creates a ConfigMap called db-conf that has two parameters, a database host, and a database port.
Creating ConfigMaps from files
When your applications require different configuration files, you can easily create a ConfigMap directly by using the file.
kubectl create configmap nginx-conf --from-file=nginx.conf
The above command creates a ConfigMap called nginx-conf from the nginx.conf file by reading its contents. The key will be the file name, while the value is the file contents.
Using YAML manifests
When it comes to working with ConfigMaps, especially in an enterprise setup, you should always define your ConfigMaps in YAML files alongside your other Kubernetes resources.
apiVersion: v1
kind: ConfigMap
metadata:
name: nginx-config
data:
nginx.conf: |
events {}
http {
server {
listen 80;
location / {
return 200 'Hello from the Lens !\n';
add_header Content-Type text/plain;
}
}
}
As you can see, in the above example, we are using a data field in which we populate our key-value pairs. In this case, we have a single key, and the value has a multi-line attribute. You can use single-line attributes as well.
To create the above ConfigMap you can simply run the following command:
kubectl apply -f file_name.yaml
Using ConfigMaps in Kubernetes
Now that you know the ways in which you can create your ConfigMaps, it is time to understand how to consume them inside of your applications.
The most straightforward way is to use the ConfigMap as environment variables for your resources:
apiVersion: v1
kind: Pod
metadata:
name: app-pod
spec:
containers:
- name: app-container
image: myapp:latest
env:
- name: DB_HOST
valueFrom:
configMapKeyRef:
name: db-conf
key: DATABASE_HOST
- name: DB_PORT
valueFrom:
configMapKeyRef:
name: db-conf
key: DATABASE_PORT
In the above example, we are telling our pod to create two environment variables called DB_HOST and DB_PORT, and load them from our db-conf ConfigMap. One will use the DATABASE_HOST key, while the other will use the DATABASE_PORT key.
At the same time you can easily load all the keys from a ConfigMap as environment variables in one go:
apiVersion: v1
kind: Pod
metadata:
name: app-pod
spec:
containers:
- name: app-container
image: myapp:latest
envFrom:
- configMapRef:
name: db-conf
Based on the fact that we will use the ConfigMap as in the examples provided before, in this case, your environment variables will be called DATABASE_HOST, and DATABASE_PORT.
When you need to provide configuration files to your applications, you need to mount your ConfigMaps as volumes:
apiVersion: v1
kind: Pod
metadata:
name: nginx-pod
spec:
containers:
- name: nginx
image: nginx:latest
volumeMounts:
- name: config-volume
mountPath: /etc/nginx/conf.d
volumes:
- name: config-volume
configMap:
name: nginx-config
The above example will mount the ConfigMap as files in the /etc/nginx/conf.d directory, and each key in the ConfigMap will become a file, and the value of the ConfigMap will be the contents of that particular file.
Best practices when you are working with ConfigMaps
Here are some of the best practices that work well when you are leveraging ConfigMaps:
- Keep ConfigMaps small: Even though ConfigMaps typically have a 1MB size limit, you should keep them much smaller, as larger ones can slow down your pod startup times, and even increase etcd load.
- Don’t store secrets in ConfigMaps: As mentioned above, Kubernetes offers a Secret resource that can be leveraged instead of ConfigMaps for secret values. ConfigMaps are not encrypted, and will always be stored in plain text in etcd.
- Use different namespaces to organize your applications: ConfigMaps are vital when you are using multiple environments for your applications, and to better separate these applications, you need to use different namespaces.
- Use versioning when testing new configurations: Instead of updating a particular ConfigMap when you want to test something, just create a new version of it, as this will let you roll back changes easily and ensure you know exactly which configuration each pod is using.
Managing ConfigMaps with Lens Kubernetes IDE
While kubectl gives you a great starting point when you are leveraging ConfigMaps, managing them across multiple namespaces, and even multiple clusters can easily become a tedious task.
Lens Kubernetes IDE provides a visual interface for working with ConfigMaps that makes managing them much easier. You can easily view all your ConfigMap resources at a glance, edit them directly in the UI, and even understand which pods are consuming them especially when you are taking advantage of Lens Prism, the AI assistant built-in for helping you manage your Kubernetes resources.
Lens also offers a built-in editor that includes syntax highlighting and validation, a built-in terminal, and it also gives you insights of pods that are not working properly, showing you if their configuration is the issue.
Check out how easy it is to work with ConfigMaps by using Lens:
Key points
ConfigMaps are essential for managing configurations in Kubernetes, as they provide the flexibility you require to deploy the same application across different environments while maintaining clear separation between your application code and the configuration per se.
If you want a powerful IDE that can help you with managing Kubernetes resources, and that can help you troubleshoot Kubernetes issues with AI capabilities, download Lens Kubernetes IDE today.