[Kubernetes] 파드에 환경 변수 주입하는 5가지 방법

1. 정적 설정

spec.containers[].env[] 배열에 정적인 값들을 설정한다. 다음과 같은 매니페스트로 파드를 생성해본다.

apiVersion: v1
kind: Pod
metadata:
  name: sample-env
  labels:
    app: sample-app
spec:
  containers:
    - name: nginx-container
      image: nginx:1.27
      env:
        - name: MAX_CONNECTION
          value: "100"

아래 커맨드를 이용해서 컨테이너 내부에 환경 변수가 설정된 것을 확인한다.

$ kubectl exec -it sample-env -- env | grep MAX_CONNECTION
MAX_CONNECTION=100

기본적으로 컨테이너의 timezone 은 UTC 로 설정되어 있다. 아래 커맨드를 실행해보자.

$ kubectl exec -it sample-env -- date
Sun Jan  4 07:10:26 UTC 2026

 

아래처럼 정적 설정을 통해서 타임존을 Asia/Seoul 로 변경해보자.

...
      env:
        - name: MAX_CONNECTION
          value: "100"
        - name: TZ
          value: Asia/Seoul
...

단, Standalone Pod 이므로, 매니페스트 변경 후 kubectl apply 로는 변경점 적용이 되지 않는다. k8s 는 파드를 불변 객체에 가깝게 취급하기 때문에 컨테이너 환경변수를 런타임에 직접 바꾸는 것이 허용되지 않는 것이다.(허용된 필드만 런타임에 수정 적용 가능함) 따라서 파드를 삭제한 후 다시 생성한다. Deployment 로 관리하는 파드라면 Deployment 변경을 apply 하면 된다.

$ kubectl delete -f sample-env.yaml

# 매니페스트의 spec.containers[].env 변경 후 파드 재생성
$ kubectl apply -f sample-env.yaml
$ kubectl exec -it sample-env -- cat date
Sun Jan  4 16:33:23 KST 2026

 

2. 파드 정보로 설정

파드 매니페스트에서 지정한 값 이외에, 파드가 기동된 후에야 알 수 있는 값들이 있다. 이러한 추가적인 파드 정보들을 환경변수로 사용하려면, valueFrom.fieldRef.fieldPath 항목을 사용할 수 있다. fieldPath 에 들어오는 값은 kubectl get pods <파드명> -o yaml 으로 조회한 경로를 사용하면 된다.(-o json | jq 또는 -o jsonpath 으로 path 를 선택하여 보면 편하다.)

아래 예시는 파드가 실제 띄워진 노드의 이름을 K8S_NODE 라는 컨테이너 환경변수로 지정한 것이다.

apiVersion: v1
kind: Pod
metadata:
  name: sample-env-pod
  labels:
    app: sample-app
spec:
  containers:
    - name: nginx-container
      image: nginx:1.27
      env:
        - name: K8S_NODE
          valueFrom:
            fieldRef:
              fieldPath: spec.nodeName

아래 명령어를 실행하여 컨테이너 내부 환경변수를 확인한다.

$ kubectl exec -it sample-env-pod -- env | grep K8S_NODE
K8S_NODE=worker02

 

3. 컨테이너 정보로 설정

파드 정보가 아닌 파드 내의 컨테이너 정보를  환경변수로 설정하기 위해서는 valueFrom.resourceFieldRef 항목을 사용한다. 세팅 가능한 path 는 파드와 마찬가지로 kubectl get pods <파드명> -o yaml 에서 확인 가능하다.(아래 예제에서는 컨테이너에 resources 항목을 직접 지정하지 않았기 때문에 -o yaml 이나 describe 로는 조회되지는 않는다.)

아래 매니페스트를 이용하여 CPU_REQUEST 에 nginx-container 컨테이너의 CPU 리소스 최솟값을, CPU_LIMITS 에 CPU 리소스 최댓값을 환경변수로 설정해 보자.

apiVersion: v1
kind: Pod
metadata:
  name: sample-env-container
  labels:
    app: sample-app
spec:
  containers:
    - name: nginx-container
      image: nginx:1.27
      env:
        - name: CPU_REQUESTS
          valueFrom:
            resourceFieldRef:
              containerName: nginx-container
              resource: requests.cpu
        - name: CPU_LIMITS
          valueFrom:
            resourceFieldRef:
              containerName: nginx-container
              resource: limits.cpu

아래 커맨드를 이용해 컨테이너 내부 환경변수를 확인한다.

$ kubectl exec -it sample-env-container -- env | grep CPU
CPU_REQUESTS=0
CPU_LIMITS=4

 

4. 시크릿 리소스 참조

기밀정보를 환경변수로 사용하고자 할 때는 시크릿 리소스를 생성하여 파드에서는 이를 참조하게 한다. 참조 방식이기 때문에 관리가 편하다.

 

5. 컨피그맵 리소스 참조

단순 키-밸류 값이나 설정파일을 환경변수로 사용하고자 할 때는 ConfigMap 리소스를 생성하여 파드에서는 이를 참조하게 한다. 참조 방식이기 때문에 관리가 편하다.

 

5. 환경변수를 command, args 에서 사용시 유의사항

아래 매니페스트로 파드를 실행하면 "echo ${TESTENV} ${HOSTNAME}" 커맨드가 실행되어 "100 sample-env-fail" 같은 출력이 예상된다. 하지만 실제 실행해보면 "${TESTENV} ${HOSTNAME}" 가 문자열 그대로 출력됨을 알 수 있다.

apiVersion: v1
kind: Pod
metadata:
  name: sample-env-fail
  labels:
    app: sample-app
spec:
  containers:
    - name: nginx-container
      image: nginx:1.27
      command: ["echo"]
      args: ["${TESTENV}", "${HOSTNAME}"]
      env:
        - name: TESTENV
          value: "100"

$ kubectl logs sample-env-fail
${TESTENV} ${HOSTNAME}

쿠버네티스에서 파드 템플릿의 command 나 args 로 명령어를 실행할 때에는 일반적인 쉘 스크립트처럼 ${변수명} 이나 $변수명 으로 변수를 사용할 수 없다. 대신 $(변수명) 을 사용해야 한다. 또한, 파드 템플릿에 정의된 환경변수만 사용 가능하다. $(변수명) 형태로 수정된 매니페스트로 파드를 실행한 후 출력 결과를 확인해보자

$ kubectl logs sample-env-fail2
100 $(HOSTNAME)

$(TESTENV) 는 정상 출력되었지만, $(HOSTNAME) 은 문자열 그대로 출력되었다. 파드 템플릿에서 정의된 변수는 TESTENV 뿐이기 때문이다. 만약 HOSTNAME 처럼 OS 에서 참조 가능한 환경 변수를 사용하고 싶다면, 별도의 셸 스크립트로 만든 후 실행해야 한다. 아래 매니페스트로 파드를 실행해 확인해보자

apiVersion: v1
kind: Pod
metadata:
  name: sample-env-success
  labels:
    app: sample-app
spec:
  containers:
    - name: nginx-container
      image: nginx:1.27
      command: ["/bin/sh", "-c"]
      args:
        - |
          cat << 'EOF' > /endpoint.sh
          #!/bin/sh
          echo "Endpoint script started"
          echo ${TESTENV} ${HOSTNAME}
          EOF

          chmod +x /endpoint.sh
          exec /endpoint.sh
      env:
        - name: TESTENV
          value: "100"

$ kubectl logs sample-env-success
Endpoint script started
100 sample-env-success

정상적으로 ${TESTENV} 와 ${HOSTNAME} 이 모두 출력되는 것을 볼 수 있다.

시크릿 리소스를 참조하는 방식, 컨피그맵 리소스를 참조하는 방식, 파드 정보를 참조하는 방식(fieldRef), 컨테이너 정보를 참조하는 방식(resourceFieldRef) 모두 마찬가지로 $(변수명) 으로 사용해야 하며, 파드 템플릿에 정의한 환경변수만 사용 가능하다. 아래 매니페스트로 파드를 실행해 확인해보자

apiVersion: v1
kind: Pod
metadata:
  name: sample-env-fail3
  labels:
    app: sample-app
spec:
  containers:
    - name: nginx-container
      image: nginx:1.27
      command: ["echo"]
      args: ["$(K8S_NODE)", "${K8S_NODE}"]
      env:
        - name: K8S_NODE
          valueFrom:
            fieldRef:
              fieldPath: spec.nodeName

$ kubectl logs sample-env-fail3
worker01 ${K8S_NODE}