2026年8月2日

KubernetesのConfigMapの使い方｜作成方法・環境変数とファイルでの渡し方・更新が反映されないときの対処

Docker・コンテナ

ConfigMapは、アプリの設定値をコンテナイメージから切り離して、Kubernetesのリソースとして管理する仕組みです。同じイメージのまま、開発と本番で接続先やログの出力レベルを変えられます。この記事では、ConfigMapの作り方、Podに環境変数として渡す方法とファイルとして渡す方法、設定を変えたのに反映されないときの理由と対処、WordPressのPHP設定をConfigMapで管理する例を説明します。

内容はKubernetesの現行のサポート対象の版（2026年10月現在）で共通して使える機能に絞っています。パスワードやAPIキーのような秘密情報は、ConfigMapではなくSecretで扱います（理由は後で説明します）。

ConfigMapに入れるもの・入れないもの

ConfigMapに向いているのは、見られても問題のない設定です。

環境の種類（production など）、ログの出力レベル
接続先のホスト名やポート番号
nginx.conf やphp.iniなどの設定ファイルそのもの

逆に、データベースのパスワード、APIキー、証明書の秘密鍵は入れません。ConfigMapの中身は暗号化されずに保存され、ConfigMapを読める権限を持つ人やツールなら誰でも平文で読めるからです。秘密情報はSecretに分け、RBACで読める範囲を絞ります。

もう一つの制約として、1つのConfigMapに入れられるデータは1MiBまでです。大きなファイルや、頻繁に書き換わるデータの置き場には使えません。

作成する

コマンドで作る方法と、YAMLで書く方法があります。

# 値を直接指定
kubectl create configmap app-config \
  --from-literal=APP_ENV=production \
  --from-literal=LOG_LEVEL=info

# ファイルから（キー名はファイル名になる）
kubectl create configmap nginx-conf --from-file=default.conf

# KEY=VALUE 形式のファイルから（1行が1キーになる）
kubectl create configmap app-env --from-env-file=app.env

--from-file と --from-env-file は似ていますが、結果が違います。前者はファイル全体を1つの値として持ち、後者はファイルの各行を別々のキーとして持ちます。設定ファイルをそのまま渡したいなら前者、環境変数の一覧を読み込みたいなら後者です。

運用するものはYAMLで管理するほうが変更履歴を追えます。コマンドの結果をYAMLに書き出すこともできます。

kubectl create configmap app-config --from-literal=APP_ENV=production \
  --dry-run=client -o yaml > app-config.yaml

YAMLで書く場合は次の形です。

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  APP_ENV: "production"
  LOG_LEVEL: "info"
  DB_HOST: "mysql.default.svc.cluster.local"
  uploads.ini: |
    upload_max_filesize = 64M
    post_max_size = 64M

data の値は文字列です。"8080" や "true" のような数値・真偽値に見える値は、引用符で囲まないとYAMLの解釈でエラーになります。キー名に使えるのは英数字と -、_、. です。| を使うと複数行のテキストをそのまま値にできます。

環境変数として渡す

Podの中のアプリが環境変数で設定を読むなら、この方法が素直です。

spec:
  containers:
    - name: app
      image: example/app:1.0
      env:
        - name: LOG_LEVEL
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: LOG_LEVEL
      envFrom:
        - configMapRef:
            name: app-env

env と configMapKeyRef は1つずつキーを選んで渡します。envFrom はConfigMapのキーをまとめて環境変数にします。envFrom は手軽ですが、どの変数がどこから来たのかがYAMLから読み取りにくくなるため、キーが少ないうちは env で明示するほうが後から追いやすいです。

ファイルとして渡す

設定ファイルを渡すには、ConfigMapをボリュームとしてマウントします。各キーがファイル名、値がファイルの中身になります。

spec:
  containers:
    - name: nginx
      image: nginx:1.27
      volumeMounts:
        - name: nginx-conf
          mountPath: /etc/nginx/conf.d
          readOnly: true
  volumes:
    - name: nginx-conf
      configMap:
        name: nginx-conf

ここで注意したいのは、ディレクトリにマウントすると、そのディレクトリにもともとあったファイルは見えなくなることです。イメージに入っていた設定ファイルが消えたように見えて、アプリが起動しなくなる原因になります。既存のファイルを残して1ファイルだけ置きたい場合は、subPath を使います（次のWordPressの例を参照）。

例：WordPressのPHP設定を変える

公式のWordPressイメージは、/usr/local/etc/php/conf.d/ にある .ini ファイルを読み込みます。このディレクトリには拡張機能の設定ファイルがすでにあるため、ディレクトリごとではなく subPath で1ファイルだけ追加します。

spec:
  containers:
    - name: wordpress
      image: wordpress:php8.3-apache
      env:
        - name: WORDPRESS_DB_HOST
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: DB_HOST
        - name: WORDPRESS_DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: wp-db
              key: password
      volumeMounts:
        - name: php-ini
          mountPath: /usr/local/etc/php/conf.d/uploads.ini
          subPath: uploads.ini
  volumes:
    - name: php-ini
      configMap:
        name: app-config
        items:
          - key: uploads.ini
            path: uploads.ini

接続先のホスト名はConfigMapから、パスワードはSecretから渡している点に注目してください。反映されたかは、Podの中で php -i | grep upload_max_filesize を実行するか、管理画面のサイトヘルスの情報画面で確認できます。イメージのタグ（ここでは php8.3-apache）は例なので、使っているWordPressとPHPの版に合わせてください。

更新しても反映されないとき

ConfigMapを書き換えても、アプリの動きが変わらないことがあります。どの渡し方をしているかで理由が違います。

環境変数で渡している場合：環境変数はコンテナの起動時に一度だけ読み込まれます。ConfigMapを変えても、動いているPodには反映されません。Podを作り直す必要があります。
ボリュームでマウントしている場合：ファイルの中身はしばらくすると自動で更新されます。ただし反映までに数十秒から1分程度かかることがあり、またアプリ側がファイルを読み直さなければ動きは変わりません。nginxやPHP-FPMのように、起動時にだけ設定を読むものは再起動が必要です。
**subPath でマウントしている場合**：自動更新の対象外です。Podを作り直すまで古い内容のままです。

どの渡し方でも通用するのは、DeploymentのPodを順に作り直す方法です。

kubectl apply -f app-config.yaml
kubectl rollout restart deployment/wordpress
kubectl rollout status deployment/wordpress

この操作を忘れないための仕組みとして、Kustomizeの configMapGenerator があります。中身から計算したハッシュをConfigMapの名前に付けるため、設定が変わると名前が変わり、それを参照するDeploymentが自動でローリングアップデートされます。

ConfigMapが原因でPodが起動しないとき

Podの状態が CreateContainerConfigError になっていたら、ConfigMapが見つからない可能性が高いです。kubectl describe pod <Pod名> の Events に、configmap "app-config" not found やキーが見つからない旨のメッセージが出ます。

確認する点は次の順です。

名前空間：ConfigMapはPodと同じ名前空間にある必要があります。kubectl get configmap -n <名前空間> で確認します。
名前とキーの綴り：kubectl get configmap app-config -o yaml で実際のキー名を見ます。大文字・小文字も区別されます。
作成の順番：PodよりConfigMapを先に作ります。まとめて apply するなら、ConfigMapを先に書くか、同じディレクトリをまとめて適用します。

キーがなくても起動させたい任意の設定には、configMapKeyRef や configMapRef に optional: true を付けられます。

変更させたくない設定は immutable にする

immutable: true を付けたConfigMapは、作成後に data を変えられなくなります。誤って本番の設定を書き換える事故を防げるほか、大規模なクラスターではkubeletが変更を監視しなくて済むため、APIサーバーの負荷も下がります。変更したいときは、新しい名前のConfigMapを作り、Deploymentの参照先を切り替えます。

まとめ

ConfigMapは秘密でない設定用。パスワードやAPIキーはSecretに分け、上限は1MiB。
--from-file はファイル丸ごと、--from-env-file は1行1キー。運用するものはYAMLで管理する。
環境変数は env / envFrom、ファイルはボリュームでマウント。ディレクトリへのマウントは既存のファイルを隠すので、1ファイルだけなら subPath を使う。
環境変数と subPath は自動で更新されない。変更後は kubectl rollout restart で反映する。
CreateContainerConfigError は名前空間、名前とキー、作成の順番を確認する。