k3s와 Helm, 정확히 알아보기: “내장되어 있다”

Helm CLI 없이 차트를 자동으로 배포하는 k3s의 강력한 기능 파헤치기

“k3s에는 Helm이 내장되어 있다”는 말을 들어보셨나요? 많은 개발자들이 이 말 때문에 k3s를 설치하면 바로 helm 명령어를 사용할 수 있을 것이라고 기대하지만, 막상 터미널에 입력해보면 command not found 오류를 마주치게 됩니다.

이 문장은 반은 맞고 반은 틀린, 오해를 부르기 쉬운 표현입니다. 이번 글에서는 k3s와 Helm의 관계를 명확히 짚어보고, k3s가 제공하는 강력한 Helm 차트 자동 배포 기능을 어떻게 활용할 수 있는지 예제와 함께 자세히 알아보겠습니다.

✅ 1. “k3s에 Helm이 내장돼 있다”는 오해와 진실

가장 중요한 핵심부터 정리해 보겠습니다.

• Helm CLI (명령어 도구) ❌
  k3s는 helm install, helm upgrade 같은 명령어를 실행하는 Helm CLI를 내장하고 있지 않습니다. 만약 CLI를 사용하고 싶다면, 다른 쿠버네티스 환경과 마찬가지로 직접 설치해야 합니다.
• Helm Controller (차트 자동 배포 기능) ✅
  k3s가 내장하고 있는 것은 Helm 차트를 자동으로 감지하고 설치/관리해주는 컨트롤러입니다. 즉, 특정 디렉터리에 Helm 차트 정보를 담은 YAML 파일을 넣어두기만 하면, k3s가 알아서 차트를 배포해주는 GitOps 스타일의 선언적 관리 방식을 지원합니다.

결론적으로, k3s는 Helm을 명령어가 아닌 자동화 기능의 형태로 내장하고 있는 것입니다.

✅ 2. k3s의 마법 같은 애드온 설치 방식: manifests 디렉터리

k3s의 Helm 차트 자동 배포 기능은 아래의 특별한 디렉터리를 통해 동작합니다.

• 경로: /var/lib/rancher/k3s/server/manifests/

k3s는 실행될 때 이 디렉터리 안에 있는 모든 .yaml 또는 .yml 파일을 읽어 클러스터에 자동으로 적용(apply)합니다. 이곳에 일반적인 쿠버네티스 YAML(Deployment, Service 등)을 넣어도 배포되고, k3s가 지원하는 특별한 HelmChart 리소스를 넣으면 Helm 차트가 자동으로 설치됩니다.

📄 실전 예제: HelmChart CR로 Nginx 자동 설치하기

이제 실제로 manifests 디렉터리에 HelmChart 커스텀 리소스(CR) 파일을 추가하여 Nginx를 설치해 보겠습니다.

1. 아래 내용으로 YAML 파일을 작성합니다.

• 파일 경로: /var/lib/rancher/k3s/server/manifests/my-nginx-helmchart.yaml

# /var/lib/rancher/k3s/server/manifests/my-nginx-helmchart.yaml

apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  name: my-nginx         # 이 HelmChart 리소스의 이름
  namespace: kube-system  # 이 리소스가 관리될 네임스페이스
spec:
  # --- 설치할 Helm 차트 정보 ---
  chart: bitnami/nginx                      # 차트 이름 (저장소 이름 포함)
  repo: https://charts.bitnami.com/bitnami  # 차트가 있는 Helm 저장소 주소
  version: 15.5.2                           # 설치할 차트 버전

  # --- 배포 관련 설정 ---
  targetNamespace: default  # 차트의 리소스들이 실제로 설치될 네임스페이스

  # --- values.yaml 설정 (set) ---
  set:
    # service.type을 LoadBalancer로 설정
    service.type: "LoadBalancer"
    # replicaCount를 2로 설정
    replicaCount: 2

2. 파일을 저장합니다.

위 파일을 /var/lib/rancher/k3s/server/manifests/ 디렉터리에 저장하는 순간, k3s의 Helm 컨트롤러가 이를 감지하고 백그라운드에서 다음 작업을 자동으로 수행합니다.

1. repo에 지정된 Helm 저장소를 추가합니다.
2. bitnami/nginx 차트 15.5.2 버전을 다운로드합니다.
3. set에 정의된 값(service.type=LoadBalancer, replicaCount=2)으로 values.yaml을 오버라이드합니다.
4. targetNamespace인 default 네임스페이스에 최종적으로 차트를 설치합니다.

이제 kubectl get pods -n default 명령어로 확인해보면, 별도의 helm install 명령어 없이 Nginx 파드 2개가 실행되고 있는 것을 볼 수 있습니다. 🎉

💡 추가로 알아두면 좋은 CRD

k3s는 Helm 자동화를 위해 두 가지 주요 커스텀 리소스 정의(CRD)를 사용합니다.

• HelmChart
  : 어떤 Helm 차트를, 어떤 버전으로, 어떤 값(values)을 주어 설치할지 정의하는 핵심 리소스입니다. (위 예제에서 사용)
• HelmChartConfig
  : HelmChart에 대한 추가 설정을 정의합니다. set으로 넣기에는 내용이 너무 많거나 복잡할 때, valuesContent 필드를 이용해 values.yaml 파일의 내용을 통째로 넣는 등 설정을 분리하여 관리할 수 있게 해줍니다.

🚀 핵심 요약

헷갈리는 k3s와 Helm의 관계를 마지막으로 명확하게 정리해 드립니다.

---

쿠버네티스 패키지관리

     📕교보문고 종이책 구매
     📱교보문고 이북 구매
🛒부크크 종이책 구매

실수로 배우는 자바

📕교보문고 종이책 구매
📱교보문고 이북 구매
🛒 부크크 종이책 구매

AI와 함께하는 협업 바이블

📱교보문고 이북 구매
     🛒부크크 종이책 구매
책은 yes24, 알라딘에도 판매 되고 있습니다.