🐳 Dockerfile vs Helm values 환경 변수 관리

배포 환경 변수, 어떻게 관리하는 게 좋을까?

작년에 진행한 프로젝트에서 쿠버네티스 기반의 사내 배포 툴을 활용해 개발, 스테이징, 운영 환경을 구축하게 되었다. 그런데 배포 환경별로 환경 변수를 어떻게 효율적으로 관리할지 고민이 생겼다.

왜 이 문제를 고민했을까?
기존 방식에서는 사내 배포 툴에서 직접 Docker에 환경 변수를 입력해야 했다. 이렇게 하면 운영 환경과 개발 환경을 분리할 수는 있지만, 문제는 코드상에서 어떤 환경이 적용되는지 확인할 수 없다는 점이었다. 배포 설정이 사내 툴 내부에서만 관리되다 보니, 코드만 봐서는 어떤 환경에서 실행되는지 알기 어려웠다.

그래서 환경 변수를 코드에서도 명확히 확인할 수 있으면서도, 관리가 더 편리한 방법을 찾기로 했다. 처음에는 Dockerfile에서 환경을 설정하는 방식을 고려했지만, 운영 환경이 커지면서 이 방식이 과연 최선인지 의문이 들었다. 여러 가지 시도를 거친 끝에, 최종적으로 Helm의 values.yaml을 활용하는 방식으로 전환하게 되었다.

이 글에서는 처음 사용했던 Dockerfile 기반 환경 변수 관리 방식과 Helm을 활용한 방식의 차이점, 그리고 최종적으로 Helm을 선택한 이유를 정리해보려고 한다.

---

기존 방식: Dockerfile에서 ARG와 ENV를 활용한 환경 설정

처음에는 Dockerfile에서 ARG와 ENV를 활용해서 배포 환경을 구분하는 방식으로 설정을 진행했다. 빌드 시점에서 환경 변수를 받아 ENVIRONMENT 값을 설정하고, 이를 런타임에서도 활용할 수 있도록 구성하는 방식이다.

기존 방식의 Dockerfile 예시

FROM openjdk:11

# 빌드 시 환경 변수를 설정 (기본값: dev)
ARG SPRING_PROFILES_ACTIVE=dev
ENV SPRING_PROFILES_ACTIVE=${SPRING_PROFILES_ACTIVE}

WORKDIR /app
COPY . .

CMD ["java", "-jar", "app.jar"]

 

🔍 이 코드의 역할

이 Dockerfile은 Python 애플리케이션을 실행하는 컨테이너 이미지를 빌드하는 용도로 작성되었다.

• ARG ENVIRONMENT=development: 빌드 시점에 환경 변수를 받을 수 있도록 설정하며, 기본값은 development로 설정되어 있음
• ENV ENVIRONMENT=${ENVIRONMENT}: ARG로 받은 값을 컨테이너 내부 환경 변수로 저장해 런타임에서도 사용할 수 있도록 설정
• WORKDIR /app: 컨테이너 내부에서 작업 디렉토리를 /app으로 설정
• COPY . .: 현재 디렉토리의 모든 파일을 컨테이너의 /app 디렉토리에 복사
• CMD ["python", "app.py"]: 컨테이너가 실행될 때 python app.py를 실행하도록 설정

이렇게 하면 Docker 이미지를 빌드할 때 --build-arg ENVIRONMENT=production 같은 옵션이나 사내툴에 파라미터를 넣어서 운영 환경과 개발 환경을 구분할 수 있다. 기본값은 development로 설정해 두었기 때문에 별다른 설정 없이도 개발 환경에서 동작하도록 했다.

이 방식은 배포 환경을 구분할 수 있는 유용한 방법이지만, 몇 가지 불편한 점이 있었다.

기존 방식의 장점

• 빌드 시점에 환경을 설정할 수 있어 운영 환경과 개발 환경을 명확하게 구분할 수 있다.
• Dockerfile 내에서 직접 환경 변수를 관리할 수 있어 구조적으로 이해하기 쉬운 편이다.
• 빌드된 이미지 내부에서 환경을 정의하기 때문에 별도의 설정 없이 실행할 수 있다.

기존 방식의 단점

• 이미지를 환경별로 따로 빌드해야 한다. 운영 환경과 개발 환경을 각각 다른 이미지로 만들어야 하므로 배포 프로세스가 복잡해진다.
• Dockerfile을 수정해야 환경을 변경할 수 있다. ENVIRONMENT 값을 바꾸려면 Dockerfile을 수정하거나, 빌드 시마다 --build-arg 옵션을 명시적으로 줘야 한다.
• Kubernetes 환경과 자연스럽게 맞지 않는다. 쿠버네티스에서 ConfigMap이나 Secret을 사용해 환경을 제어하는 것이 일반적인데, 이 방식은 Docker 빌드 과정에서 이미 환경이 결정되기 때문에 운영 환경에서 쉽게 변경하기 어렵다.

Dockerfile을 활용한 방식도 충분히 활용할 수 있었지만, Kubernetes 환경에서 운영하기에는 제약이 많았다. 특히 배포 환경마다 이미지를 다르게 빌드해야 하는 점이 비효율적으로 느껴졌다. 그래서 다른 방법을 고민하게 되었다.

---

Helm values.yaml을 활용한 환경 설정

기존 방식의 단점을 해결하기 위해 Dockerfile에서 환경을 직접 설정하는 대신, Helm의 values.yaml을 활용하여 환경을 구분하는 방식으로 변경했다.

Helm을 사용하면 애플리케이션의 설정을 배포 시점에 동적으로 변경할 수 있다. 따라서 Docker 이미지는 하나만 빌드하고, 환경에 맞는 설정값을 values.yaml을 통해 적용할 수 있다.

새로운 방식의 설정 예시

개발 환경 (values-dev.yaml)

env:
  SPRING_PROFILES_ACTIVE: dev

운영 환경 (values-prod.yaml)

env:
  SPRING_PROFILES_ACTIVE: production

Helm의 deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-backend
spec:
  template:
    spec:
      containers:
        - name: backend
          image: my-backend-image
          env:
            - name: SPRING_PROFILES_ACTIVE
              value: {{ .Values.env.SPRING_PROFILES_ACTIVE }}

이제 배포할 때 helm install 명령어에서 values.yaml을 선택하는 것만으로 환경을 다르게 적용할 수 있다.

# 개발 환경 배포
helm install my-backend ./helm-chart -f values-dev.yaml

# 운영 환경 배포
helm install my-backend ./helm-chart -f values-prod.yaml

이 방식에서는 Docker 이미지를 하나만 빌드하면 되고, 배포 시점에서 values.yaml을 통해 환경을 변경할 수 있다. 이는 Kubernetes 환경에 훨씬 적합한 구조다.

새로운 방식의 장점

• Docker 이미지를 한 번만 빌드하면 된다. 운영 환경과 개발 환경이 동일한 이미지를 공유할 수 있다.
• 환경 변수를 Helm values.yaml에서 관리할 수 있다. 환경별로 values.yaml을 따로 만들어 관리하면 설정이 훨씬 깔끔해진다.
• Kubernetes 네이티브한 방식이다. Kubernetes에서는 ConfigMap이나 Secret을 활용해 환경을 관리하는 것이 일반적인데, 이 방식이 이에 적합하다.
• 배포 시점에서 환경을 동적으로 변경할 수 있다. 기존 방식에서는 Dockerfile에서 빌드 시 환경을 정해야 했지만, 이제는 배포할 때 선택만 하면 된다.

새로운 방식의 단점

• Helm을 사용하지 않는다면 적용하기 어렵다. 로컬 개발 환경에서 docker run 같은 방식으로 실행할 경우, 환경 설정을 따로 관리해야 한다.
• 환경이 Helm에 종속된다. Kubernetes가 아닌 환경에서 사용하려면 추가적인 설정이 필요할 수 있다.

---

내가 선택한 결론: Helm values.yaml이 더 효율적이었다

이번 프로젝트를 진행하면서 Dockerfile에서 환경을 관리하는 방식과 Helm을 활용하는 방식을 비교할 수 있었다. 여러 가지 시도를 해 본 결과, Helm values.yaml을 활용하는 방식이 더 유연하고, 배포 환경을 깔끔하게 정리할 수 있었다는 점에서 적합하다고 판단했다.

 

이 방식을 적용한 후 Docker 이미지를 빌드하는 과정이 단순해졌고, 배포 환경을 관리하는 것이 훨씬 쉬워졌다. 같은 이미지를 사용하면서도 환경별 설정을 유연하게 바꿀 수 있어 유지보수 측면에서도 장점이 많았다. 또한, 사내 배포 툴에서 Docker에 직접 값을 넣어야 했던 번거로움이 사라지고, Helm에서 코드로 명시할 수 있어 실수 없이 관리할 수 있게 되었다.

 

물론 모든 프로젝트에 무조건 Helm이 정답은 아닐 수도 있다. 하지만 내가 경험한 프로젝트에서는 이 방식이 더 적합했고, 더 효율적이었다. Kubernetes를 활용하는 환경이라면, Dockerfile에서 ARG와 ENV를 활용하는 것보다 Helm values.yaml을 통해 환경을 분리하는 것이 더 나은 선택일 가능성이 높다.