Helm으로 Kubernetes에 Consul 설치

공식 Consul Helm 차트를 사용하여 Kubernetes에 Consul을 설치하는 방법을 설명해 드릴게요. 파티션 간 또는 데이터센터 간 통신이 포함된 멀티 클러스터 배포에 이 방법을 권장해요.

출처: 문서

본문

이 문서에서는 공식 Consul Helm 차트를 사용하여 Kubernetes에 Consul을 설치하는 방법을 설명해요. 파티션 간 또는 데이터센터 간 통신이 포함된 멀티 클러스터 배포에 Consul을 Kubernetes에 설치한다면 이 방법을 권장해요.

Consul K8s CLI를 사용하여 Kubernetes에 Consul을 설치하는 방법에 대한 지침은 Consul K8s CLI로 Kubernetes에 Consul 설치를 참고해 주세요.

소개

파티션 간 또는 데이터센터 간 통신이 포함된 멀티 클러스터 설치에는 Consul Helm 차트를 사용하여 Kubernetes에 Consul을 설치하는 것을 권장해요. Helm 차트는 Consul을 실행하는 데 필요한 모든 구성 요소를 설치하고 구성해요.

Consul은 Kubernetes에서 직접 실행할 수 있으므로 워크로드가 완전히 Kubernetes에 배포된 경우 Consul 기능을 활용할 수 있어요. 이기종(heterogeneous) 워크로드의 경우 Consul 에이전트가 Kubernetes 내부 또는 외부에서 실행되는 서버에 합류할 수 있어요. 일반적인 아키텍처에 대해 자세히 알아보려면 Kubernetes의 Consul 아키텍처를 참고해 주세요.

Helm 차트는 여러 유용한 구성을 노출하고 복잡한 리소스를 자동으로 설정하지만, Consul을 자동으로 운영하지는 않아요. Consul 클러스터를 모니터링, 백업, 업그레이드하는 방법을 여전히 숙지해야 해요.

Helm 차트에는 필수 구성이 없으므로 기본 구성으로 Consul 클러스터를 설치해요. 프로덕션에 들어가기 전에 구성 옵션에 대해 알아보는 것을 강력히 권장해요.

경고

기본적으로 Helm은 보안 구성을 비활성화한 상태로 Consul을 설치하므로 초보 사용자에게 최적화된 기본 경험을 제공해요. 프로덕션에 들어가기 전에 적절히 보안이 설정된 Kubernetes 클러스터를 사용하거나 Consul의 보안 기능을 이해하고 활성화해야 합니다. 일부 보안 기능은 Helm 차트에서 지원되지 않으며 추가 수동 구성이 필요해요.

Kubernetes용 서비스 메시로서의 Consul에 대한 실습 경험을 원한다면 Consul 서비스 메시 시작하기 튜토리얼을 따라 해 주세요.

요구 사항

Helm으로 Kubernetes에 Consul을 설치하려면 다음 요구 사항을 충족해야 해요:

Helm 버전 3.6+. 최신 버전을 다운로드하려면 Helm 웹사이트를 방문해 주세요.
Consul을 설치하려는 Kubernetes 클러스터를 가리키도록 구성된 kubectl.

요구 사항에 따라 다음을 수행할 수 있어요:

기본 Helm 차트 구성을 사용하여 기본 설치를 수행해요. Consul을 테스트하거나 보안 요구 사항이 없는 테스트 환경을 설정하는 경우 이 옵션을 사용해 주세요.
Helm 차트 구성 매개변수를 수정하여 사용자 지정 설치를 수행해요. 프로덕션에 Consul을 설치한다면 권장되는 접근 방식이에요.

HashiCorp Helm 저장소 추가

설치 전에 Helm에 HashiCorp 저장소를 추가해 주세요.

$ helm repo add hashicorp https://helm.releases.hashicorp.com
"hashicorp" has been added to your repositories

Consul 설치

Consul 차트에 접근할 수 있는지 확인해 주세요:

$ helm search repo hashicorp/consul
NAME                CHART VERSION   APP VERSION DESCRIPTION
hashicorp/consul    2.0.1           2.0.1       Official HashiCorp Consul Chart

Helm으로 Kubernetes에 Consul을 설치하기 전에 consul Kubernetes 네임스페이스가 존재하지 않는지 확인해 주세요. 전용 네임스페이스에 Consul을 설치하는 것을 권장해요.

$ kubectl get namespace
NAME              STATUS   AGE
default           Active   18h
kube-node-lease   Active   18h
kube-public       Active   18h
kube-system       Active   18h

참고

기본 consul과 다른 K8s 네임스페이스에서 Consul을 배포하거나 업그레이드할 때 오류가 발생하면 다음 기술적 제약 목록을 참고해 주세요.

Consul은 대상 K8s 네임스페이스를 자동으로 감지할 수 없으므로 Helm 또는 consul-k8s 도구의 매개변수에 -namespace로 명시적으로 나열해야 해요.

Consul은 대상 K8s 네임스페이스를 connectInjector.k8sAllowNamspaces Helm 차트 값에 추가해야 해요. 자세한 내용은 Consul Helm 차트 참조에서 이 특정 설정을 참고해 주세요.

Helm을 사용하여 Kubernetes에 Consul을 설치해 주세요. Helm 차트는 배포 설정에 필요한 모든 것을 해줘요. 설치 후 에이전트가 자동으로 클러스터를 구성하고, 리더를 선출하며, 필요한 에이전트를 실행해요.

다음 명령을 실행하여 기본 구성으로 Kubernetes에 최신 버전의 Consul을 설치해 주세요.

$ helm install consul hashicorp/consul --set global.name=consul --create-namespace --namespace consul

Helm 설치의 -n 플래그 값을 수정하여 원하는 전용 네임스페이스에 Consul을 설치할 수도 있어요.

Kubernetes에 특정 버전의 Consul을 설치하려면 --version 플래그와 함께 다음 명령을 실행해 주세요:

$ export VERSION=1.0.1 && \
    helm install consul hashicorp/consul
      --set global.name=consul
      --version ${VERSION}
      --create-namespace
      --namespace consul

사용자 지정 설치

설치를 사용자 지정하려면 기본 설정을 재정의하는 values.yaml 파일을 만들어 주세요. 사용할 수 있는 설정을 알아보려면 helm inspect values hashicorp/consul을 실행하거나 Helm 차트 참조를 검토해 주세요.

다음 섹션에는 참조로 사용할 수 있는 사용자 지정 예시가 포함돼 있어요:

최소 Consul 서비스 메시 설치
API 게이트웨이 구성 선택
OpenShift 클러스터에 Consul 설치
Consul CNI 플러그인 활성화
선택한 네임스페이스에서 Consul 서비스 메시 활성화

Consul 서비스 메시용 최소 values.yaml

다음 values.yaml 구성 파일에는 Consul 서비스 메시를 활성화하는 데 필요한 최소 설정이 포함돼 있어요:

values.yaml

global:
  name: consul

values.yaml 파일을 만든 후 --values 플래그와 함께 helm install을 실행해 주세요:

$ helm install consul hashicorp/consul --create-namespace --namespace consul --values values.yaml
NAME: consul
...

API 게이트웨이 구성 선택

완전히 작동하는 Consul 배포에는 API 게이트웨이가 필요해요. 아래 다이어그램을 사용하여 플랫폼을 식별하고 인프라에 맞는 올바른 API 게이트웨이 구현을 선택해 주세요.

이 표는 다이어그램과 동일한 정보를 보여주며 각 플랫폼 구성에 필요한 Helm 값을 설명해요.

Platform	Platform configuration	Gateway	Helm Values
OCP ≤ 4.18	TCPRoute required	Standard API gateway	`global.installK8sNetworkingCRDs=true`, `global.openshift.crds.enableTcpRoute=true`
OCP ≥ 4.19	TCPRoute not required	Standard API gateway	`global.installK8sNetworkingCRDs=false`, `global.openshift.isOcpGreaterthan4_18=true`, `global.openshift.crds.enableTcpRoute=false`
OCP ≥ 4.19	TCPRoute present / required	Consul API gateway	`global.installK8sNetworkingCRDs=false`, `global.openshift.isOcpGreaterthan4_18=true`, `global.openshift.crds.enableTcpRoute=false`, `global.openshift.crds.consulapi.enabled=true`
Non-OCP	Platform does not manage CRDs	Standard API gateway	`global.installK8sNetworkingCRDs=true`, `global.crds.enableTcpRoute=true`
Non-OCP	Platform manages CRDs, TCPRoute not required	Standard API gateway	`global.installK8sNetworkingCRDs=false`, `global.crds.enableTcpRoute=false`
Non-OCP	Platform manages CRDs, TCPRoute required	Consul API gateway	`global.installK8sNetworkingCRDs=false`, `global.crds.enableTcpRoute=false`, `global.crds.consulapi.enabled=true`

OpenShift 클러스터에 Consul 설치

Red Hat OpenShift는 보안에 중점을 둔, 의견이 반영된(opinionated) Kubernetes 래퍼예요. OpenShift 관리 Kubernetes에 Consul을 설치하려면 다음 명령을 실행하여 OCP 버전과 클러스터에 TCPRoute 리소스가 있는지 확인해 주세요:

OCP 버전 확인.

oc version

클러스터가 TCPRoute를 사용하는지 확인.

kubectl get tcproutes -A

출력을 사용하여 올바른 탭을 선택해 주세요:

OCP 버전이 4.19 이상이고 TCPRoute 리소스가 없으면 OpenShift >= 4.19, no TCPRoute required 탭을 사용해 주세요.
OCP 버전이 4.19 이상이고 TCPRoute 리소스가 있으면 OpenShift >= 4.19, TCPRoute required 탭을 사용해 주세요.
OCP 버전이 4.18 이하이면 OpenShift <= 4.18 탭을 사용해 주세요.

OpenShift <= 4.18 (표준 API 게이트웨이):

values.yaml

global:
  installK8sNetworkingCRDs: true
  openshift:
    enabled: true
    crds:
      enableTcpRoute: true

OpenShift >= 4.19, TCPRoute 불필요 (표준 API 게이트웨이):

values.yaml

global:
  installK8sNetworkingCRDs: false
  openshift:
    enabled: true
    isOcpGreaterthan4_18: true
    crds:
      enableTcpRoute: false

OpenShift >= 4.19, TCPRoute 필요 (Consul API 게이트웨이):

values.yaml

global:
  installK8sNetworkingCRDs: false
  openshift:
    enabled: true
    isOcpGreaterthan4_18: true
    crds:
      enableTcpRoute: false
      consulapi:
        enabled: true

자세한 내용은 Helm 차트 참조의 openshift를 참고해 주세요.

Consul 구성 업데이트

Consul을 이미 설치했고 변경하려면 helm upgrade를 실행해야 해요. 자세한 내용은 업그레이드를 참고해 주세요.

Consul CNI 플러그인 활성화

기본적으로 Consul이 투명 프록시 모드일 때 Kubernetes pod 시작 프로세스의 일부로 connect-inject-init init 컨테이너를 주입해요. 이 컨테이너는 사이드카 프록시를 통해 서비스 메시에서 트래픽 리다이렉션을 구성해요. 리다이렉션을 구성하려면 컨테이너에 상승된 CAP_NET_ADMIN 권한이 필요한데, 이는 조직의 보안 정책과 호환되지 않을 수 있어요.

대신 트래픽 리다이렉션을 수행하도록 Consul container network interface(CNI) 플러그인을 활성화할 수 있어요. 이 플러그인은 로컬 Kubernetes kubelet에 의해 실행되므로 네트워크를 구성하는 데 필요한 상승된 권한을 이미 갖고 있어요.

Consul Helm 차트는 Consul CNI 플러그인 설치를 담당해요. 플러그인이 설치되도록 구성하려면 values.yaml 파일에 다음 구성을 추가해 주세요:

참조 구성 / GKE 구성 / OpenShift 구성

values.yaml

global:
  name: consul
connectInject:
  enabled: true
  cni:
    enabled: true
    logLevel: info
    cniBinDir: "/opt/cni/bin"
    cniNetDir: "/etc/cni/net.d"

values.yaml

global:
  name: consul
connectInject:
  enabled: true
  cni:
    enabled: true
    logLevel: info
    cniBinDir: "/home/kubernetes/bin"
    cniNetDir: "/etc/cni/net.d"

values.yaml

global:
  name: consul
  openshift:
    enabled: true
connectInject:
  enabled: true
  cni:
    enabled: true
    logLevel: info
    multus: true
    cniBinDir: "/var/lib/cni/bin"
    cniNetDir: "/etc/kubernetes/cni/net.d"

다음 표는 사용 가능한 CNI 플러그인 옵션을 설명해요:

Option	Description	Default
`cni.enabled`	CNI 플러그인을 활성화하거나 비활성화하는 불리언 값. `true`이면 플러그인이 서비스 메시에서 트래픽 리다이렉션을 담당해요. `false`이면 `connect-inject init` 컨테이너가 리다이렉션을 처리해요.	`false`
`cni.logLevel`	설치 프로그램과 플러그인의 로그 레벨을 지정하는 문자열 값. `info`, `debug`, `error` 값을 지정할 수 있어요.	`info`
`cni.namespace`	CNI 플러그인을 설치할 네임스페이스 설정. CNI 리소스에 대한 전역 네임스페이스 설정을 재정의해요. 예: `kube-system`	`consul-k8s` 설치에 사용되는 네임스페이스 (예: `consul`)
`cni.multus`	multus CNI 플러그인 지원을 활성화하는 불리언 값. `true`이면 multus가 활성화돼요. `false`이면 Consul CNI가 체인된 플러그인으로 작동해요.	`false`
`cni.cniBinDir`	CNI 플러그인이 설치되는 Kubernetes 노드의 위치를 지정하는 문자열 값.	`/opt/cni/bin`
`cni.cniNetDir`	CNI 구성을 저장하기 위한 Kubernetes 노드의 위치를 지정하는 문자열 값.	`/etc/cni/net.d`

참고

GKE Autopilot 클러스터는 Consul CNI 플러그인 설치를 지원하지 않아요.

Consul CNI 플러그인 설치 프로그램은 Kubernetes 노드 수준의 hostPath 볼륨에 대한 쓰기 접근이 필요해요. 이 접근은 노드 CNI bin 디렉터리에 CNI 바이너리를 배치하고, /etc/cni/net.d 아래에 CNI 구성을 쓰고, CNI 설치를 조정(예: 토큰 회전, CNI 플러그인 구성 업데이트)하는 데 필요해요.

GKE Autopilot은 쓰기 모드의 hostPath 볼륨을 제한하고 privileged 워크로드를 차단하므로 autogke-no-write-mode-hostpath 및 autogke-disallow-privilege 같은 admission 오류로 CNI 설치가 실패할 수 있어요. Google의 Autopilot 보안 제한을 참고해 주세요.

GKE Autopilot에서 트래픽 리다이렉션을 구성하려면 CAP_NET_ADMIN 권한으로 Pod 수준에서 connect-inject-init 컨테이너를 사용해 주세요. Autopilot에서 클러스터에 --workload-policies=allow-net-admin을 사용하여 NET_ADMIN을 활성화하고 Pod 보안 컨텍스트에서 NET_ADMIN을 허용하여 init 컨테이너가 iptables를 구성할 수 있게 해 주세요.

선택한 네임스페이스에서 Consul 서비스 메시 활성화

기본적으로 Consul 서비스 메시는 kube-system 및 local-path-storage를 제외한 Kubernetes 클러스터의 거의 모든 네임스페이스에서 활성화돼요. 서비스 메시를 네임스페이스 하위 집합으로 제한하려면:

서비스 메시를 배포하려는 각 네임스페이스에 연결된 레이블과 일치하는 namespaceSelector를 지정해 주세요. 기본적으로 레이블별로 선택한 네임스페이스에서 서비스 메시를 활성화하려면 connectInject.default 값을 true로 설정해야 해요.

values.yaml

global:
  name: consul
connectInject:
  enabled: true
  default: true
  namespaceSelector: |
    matchLabels:
      connect-inject : enabled

Consul 서비스 메시를 활성화하려는 네임스페이스에 레이블을 지정해 주세요.

$ export NAMESPACE=foo && \
    kubectl create ns $NAMESPACE && \
    kubectl label namespace $NAMESPACE connect-inject=enabled

--values 플래그와 함께 helm install을 실행해 주세요:

$ helm install consul hashicorp/consul --create-namespace --namespace consul --values values.yaml
NAME: consul

사용

설치 후 Consul UI를 보고 Consul HTTP API에 접근할 수 있어요.

Consul UI 보기

Helm 차트를 사용할 때 Consul UI는 기본적으로 활성화돼요.

보안상의 이유로 기본적으로 LoadBalancer 서비스를 통해 노출되지 않아요. UI를 방문하려면 kubectl port-forward를 사용해야 해요.

TLS 비활성화 상태에서 포트 포워딩

TLS가 비활성화된 상태로 실행 중이면 Consul UI는 포트 8500에서 http로 접근할 수 있어요:

$ kubectl port-forward service/consul-server --namespace consul 8500:8500

포트 포워딩을 설정한 후 http://localhost:8500으로 이동해 주세요.

TLS 활성화 상태에서 포트 포워딩

TLS가 활성화된 상태로 실행 중이면 Consul UI는 포트 8501에서 https로 접근할 수 있어요:

$ kubectl port-forward service/consul-server --namespace consul 8501:8501

포트 포워딩을 설정한 후 https://localhost:8501으로 이동해 주세요.

팁

Consul 인증 기관(CA)이 자체 서명되어 브라우저의 신뢰 저장소에 없으므로 브라우저의 SSL 경고를 클릭해서 통과해야 해요.

ACL 활성화

ACL이 활성화된 경우 UI에서 모든 리소스를 표시하고 수정하려면 ACL 토큰을 입력해야 해요.

전체 권한이 있는 부트스트랩 토큰을 검색하려면 다음을 실행해 주세요:

$ kubectl get secrets/consul-bootstrap-acl-token --template='{{.data.token | base64decode }}'
e7924dd1-dc3f-f644-da54-81a73ba0a178%

그런 다음 UI의 ACLs 탭 아래에 토큰을 붙여넣어 주세요(% 제외).

참고

멀티 클러스터 연동(federation)을 사용하는 경우 보조 데이터센터는 권한이 적은 별도의 토큰을 사용하므로 부트스트랩 토큰을 검색하려면 kubectl 컨텍스트가 기본 데이터센터에 있어야 해요.

서비스를 통해 UI 노출

Kubernetes Service를 통해 UI를 노출하려면 ui.service 차트 값을 구성해 주세요. 이 서비스는 Consul 서버에 대한 요청을 허용하므로 외부에 열어서는 안 돼요.

Consul HTTP API 접근

기술적으로 모든 수신 에이전트가 HTTP API에 응답할 수 있지만, 로컬 Consul 노드와 통신하면 중요한 캐싱 동작이 있고 서비스와 체크에 더 간단한 /agent 엔드포인트를 사용할 수 있어요.

노드에 대한 정보를 찾으려면 downward API를 사용할 수 있어요.

다음은 예시 pod 사양이에요. pod 외에도 pod 템플릿이 있는 모든 것(StatefulSets, Deployments, Jobs 등)이 Consul API에 접근할 수 있고 따라서 Consul에도 접근할 수 있어요.

apiVersion: v1
kind: Pod
metadata:
  name: consul-example
spec:
  containers:
    - name: example
      image: 'hashicorp/consul:latest'
      env:
        - name: HOST_IP
          valueFrom:
            fieldRef:
              fieldPath: status.hostIP
      command:
        - '/bin/sh'
        - '-ec'
        - |
          export CONSUL_HTTP_ADDR="${HOST_IP}:8500"
          consul kv put hello world
  restartPolicy: Never

다음 예시 Deployment는 중첩된 pod 사양에서 호스트 IP에 접근하는 방법을 보여줘요:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: consul-example-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: consul-example
  template:
    metadata:
      labels:
        app: consul-example
    spec:
      containers:
        - name: example
          image: 'hashicorp/consul:latest'
          env:
            - name: HOST_IP
              valueFrom:
                fieldRef:
                  fieldPath: status.hostIP
          command:
            - '/bin/sh'
            - '-ec'
            - |
              export CONSUL_HTTP_ADDR="${HOST_IP}:8500"
              consul kv put hello world

Helm으로 Kubernetes에 Consul 설치