📚 课程目录第2章 ConfigMap创建方式

2、ConfigMap 创建方式：使用 kubectl 命令行创建、使用 YAML 文件创建、从文件/目录创建、从字面量创建

ConfigMap 是 Kubernetes 中用于将非机密配置数据与 Pod 解耦的核心资源。掌握其多种创建方式，是云原生配置管理的基础。本章将系统讲解四种最常用的创建方法，并通过对比表格和内联 SVG 图帮助理解。

2.1 四种创建方式总览

Kubernetes 提供了灵活的命令行与声明式创建路径，适用于不同的场景：

创建方式	核心命令/语法	适用场景	数据来源
kubectl 命令行直接创建	`kubectl create configmap`	快速测试、临时配置	命令行参数
YAML 文件声明式创建	`kubectl apply -f`	生产环境、版本管理、GitOps	YAML 清单文件
从文件/目录创建	`--from-file` / `--from-file=dir/`	批量导入配置文件、日志配置	本地文件系统
从字面量创建	`--from-literal`	注入环境变量、简单键值对	命令行字符串

最佳实践提示： 在 CI/CD 流水线或蓝绿发布场景中，优先使用 YAML 声明式创建（kubectl apply -f），便于版本追踪和回滚。临时调试或快速验证时，可使用 --from-literal 或 --from-file 提高效率。

2.2 方法一：使用 kubectl 命令行直接创建

这是最快速的创建方式，适合在终端中直接定义键值对。语法如下：

# 创建一个名为 app-config 的 ConfigMap，包含两个键值对
kubectl create configmap app-config \
  --from-literal=APP_ENV=production \
  --from-literal=LOG_LEVEL=info

执行后，Kubernetes 会立即生成一个 ConfigMap 资源。可以通过 kubectl describe configmap app-config 查看详情。

2.3 方法二：使用 YAML 文件声明式创建

声明式管理是 Kubernetes 的推荐方式。编写 YAML 文件后，通过 kubectl apply 提交到集群。

# configmap-demo.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  labels:
    app: my-app
    env: production
data:
  APP_ENV: "production"
  LOG_LEVEL: "info"
  config.json: |
    {
      "timeout": 30,
      "retry": 3
    }

# 应用 YAML 文件
kubectl apply -f configmap-demo.yaml

注意： YAML 文件中的 data 字段下，键值对的值必须是字符串。如果值是 JSON 或 YAML 格式，需要使用管道符 | 或折叠块 > 进行多行字符串声明，否则会导致解析错误。

2.4 方法三：从文件/目录创建

当需要将多个配置文件（如 nginx.conf、application.properties）批量导入 ConfigMap 时，--from-file 是最佳选择。

# 从单个文件创建（文件名作为键，文件内容作为值）
kubectl create configmap nginx-config --from-file=./nginx.conf

# 从目录创建（目录下所有文件都会被导入）
kubectl create configmap app-config --from-file=./configs/

# 自定义键名
kubectl create configmap custom-config --from-file=my-key=./settings.ini

从目录创建时，Kubernetes 会遍历目录下的所有文件，将文件名作为 ConfigMap 的键，文件内容作为值。支持二进制文件（通过 --from-file 的 binaryData 字段）。

2.5 方法四：从字面量创建

字面量创建是最简洁的方式，适合注入少量环境变量或简单配置。

# 单个字面量
kubectl create configmap literal-config --from-literal=KEY1=value1

# 多个字面量（可重复使用 --from-literal）
kubectl create configmap app-env \
  --from-literal=DB_HOST=localhost \
  --from-literal=DB_PORT=5432 \
  --from-literal=DB_USER=admin

字面量方式创建的 ConfigMap 数据直接存储在 data 字段中，Pod 可以通过环境变量或卷挂载的方式引用。

2.6 创建方式对比流程图

下图展示了四种创建方式的数据流向与适用场景：

2.7 创建方式选择决策树

在实际项目中，可以根据以下决策树快速选择最合适的创建方式：

是否需要版本管理？
- 是 → 使用 YAML 声明式创建（kubectl apply -f）
- 否 → 进入下一步
数据来源是什么？
- 本地文件/目录 → 使用 --from-file
- 简单键值对 → 使用 --from-literal
- 混合来源 → 使用 kubectl create configmap 组合参数
是否需要批量导入？
- 是 → 优先使用 --from-file=dir/ 从目录创建
- 否 → 根据数据量选择字面量或命令行

  生产环境建议： 在蓝绿发布或金丝雀发布场景中，始终使用 YAML 声明式创建，并将 ConfigMap 清单文件纳入 Git 仓库管理。这样可以在发布前进行代码审查，发布后快速回滚到上一个配置版本。

2.8 常见错误与避坑指南

错误场景	错误示例	正确做法
YAML 中多行 JSON 未使用管道符	`data: config.json: {"key": "value"}`	`data: config.json: \| {"key": "value"}`
从目录创建时包含隐藏文件	`--from-file=./configs/` 包含 `.gitkeep`	清理目录或使用 `--from-file` 指定具体文件
键名包含非法字符	`--from-literal=MY-KEY=value`	使用字母、数字、下划线、连字符（-）和点（.）
ConfigMap 大小超过 1MB	单个 ConfigMap 包含大量数据	拆分多个 ConfigMap 或使用外部存储

掌握这四种创建方式后，你可以根据实际场景灵活选择，为后续的 Pod 配置注入和蓝绿发布配置切换打下坚实基础。