RedHat OpenShift 클러스터에서 Consul 버전 업그레이드
RedHat OpenShift 클러스터에서 Consul 버전 업그레이드 (Upgrade Consul version on RedHat OpenShift clusters)
OpenShift 클러스터에서 실행되는 Consul 배포의 버전을 업그레이드하는 프로세스와 고려 사항을 설명해요.
출처: 문서
본문
이 페이지는 OpenShift 클러스터에서 실행되는 Consul 배포의 버전을 업그레이드하는 프로세스와 고려 사항을 설명합니다. Consul이 OpenShift 클러스터에서 실행될 때 업데이트할 패키지가 두 가지 있습니다: Docker Hub에 있는 Helm 차트와 Red Hat Ecosystem Catalog의 Consul 컨테이너입니다. 즉, 컨테이너 이미지와 Helm 차트 버전을 업데이트해야 할 수 있습니다.
업그레이드 유형 (Upgrade types)
다음 경우에 RedHat OpenShift에서 Consul을 업데이트하는 것이 좋습니다.
- Helm 구성을 변경하는 경우
- 새 Helm 차트가 릴리스된 경우
- Consul 버전을 업그레이드하려는 경우
사용하는 업그레이드 절차는 수행하는 업그레이드 유형에 따라 달라집니다.
변경 범위 결정 (Determine scope of changes)
업그레이드 전에 클러스터에 영향을 미치는 변경 사항을 이해하는 것이 중요합니다.
Helm 업그레이드가 무엇을 변경하는지 보여주는 Helm 내장 기능은 없지만, helm-diff Helm 플러그인이 있습니다.
helm-diff를 설치하세요.$ helm plugin install https://github.com/databus23/helm-diff- 로컬 Helm 리포지토리 캐시를 업데이트하세요.
$ helm repo update - 현재 설치된 차트 버전을 확인하세요.
이 예시에서 현재 Helm 차트 버전은 1.4.0입니다. Consul 버전 1.18.0으로 실행되며 OpenShift 클러스터의$ helm list --filter consul --namespace consul NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION consul consul 1 2025-04-22 14:39:13.599498 +0200 CEST deployed consul-1.4.0 1.18.0consul네임스페이스에 설치되어 있습니다. - 사용 가능한 차트 버전을 나열하세요.
서로 다른 Consul 버전은 서로 다른 Helm 차트 요구 사항을 가집니다.$ helm search repo hashicorp/consul --versions hashicorp/consul 1.4.9 1.18.2 Official HashiCorp Consul Chart hashicorp/consul 1.4.8 1.18.2 Official HashiCorp Consul Chart hashicorp/consul 1.4.7 1.18.2 Official HashiCorp Consul Chart hashicorp/consul 1.4.6 1.18.2 Official HashiCorp Consul Chart hashicorp/consul 1.4.5 1.18.2 Official HashiCorp Consul Chart hashicorp/consul 1.4.4 1.18.2 Official HashiCorp Consul Chart hashicorp/consul 1.4.3 1.18.2 Official HashiCorp Consul Chart hashicorp/consul 1.4.2 1.18.2 Official HashiCorp Consul Chart hashicorp/consul 1.4.1 1.18.1 Official HashiCorp Consul Chart hashicorp/consul 1.4.0 1.18.0 Official HashiCorp Consul Chart ... - 업데이트할 버전을 선택하고 다음 업데이트 관련 리소스를 확인하세요.
- 현재 버전과 대상 버전 사이의 호환성이 깨지는 변경에 대한 변경 로그:
CHANGELOG.md - 업그레이드하려는 버전에 대한 특정 지침을 읽으세요.
- 호환성 매트릭스(Compatibility Matrix)를 읽어 현재 Helm 차트 버전이 이 Consul 버전을 지원하는지 확인하세요. 지원하지 않는다면 동시에 Helm 차트 버전도 업그레이드해야 할 수 있습니다. 이 예시에서는 차트 버전 1.4.9와 Consul 버전 1.18.2를 선택합니다. 차트 버전 1.4.9는 Consul 버전 1.18.2와 호환되므로 업그레이드를 진행할 수 있습니다.
- 현재 버전과 대상 버전 사이의 호환성이 깨지는 변경에 대한 변경 로그:
global.image스탠자를 이미지로 편집하세요.values.yaml global: image: "registry.connect.redhat.com/hashicorp/consul:1.18.2-ubi"- 업데이트된
values.yaml파일과 선택한 Helm 차트 버전(이 경우 1.4.9)으로helm diff upgrade를 실행하세요.
이 명령은 업데이트될 매니페스트와 해당 diff를 출력합니다. 업데이트된 객체만 반환하려면$ helm diff upgrade consul hashicorp/consul --namespace consul --version 1.4.9 --values /path/to/your/values.yaml default, consul-server, StatefulSet (apps) has changed: # Source: consul/templates/server-statefulset.yaml # StatefulSet to run the actual Consul server cluster. apiVersion: apps/v1 kind: StatefulSet ... containers: - name: consul image: "registry.connect.redhat.com/hashicorp/consul:1.18.0-ubi" image: "registry.connect.redhat.com/hashicorp/consul:1.18.2-ubi" ...| grep "has changed"를 추가하세요.$ helm diff upgrade consul hashicorp/consul --namespace consul --version 1.4.9 --values /path/to/your/values.yaml | grep "has changed" default, consul-server, StatefulSet (apps) has changed: consul-serverStatefulSet이 나타나면 업데이트된 Helm 값을 적용할 때 Consul 서버 StatefulSet이 재배포된다는 뜻입니다. StatefulSet은 파드 그룹을 실행하며 각 파드에 특정 ID를 유지합니다. 이는 Consul 서버와 같이 영구 저장소가 필요한 애플리케이션을 관리하는 데 유용합니다. StatefulSet을 한 번에 업그레이드하면 다운타임이 발생합니다. 따라서 StatefulSet을 재배포해야 한다면 제로 다운타임을 위한 롤링 업그레이드(Rolling upgrade for zero downtime)를 따라 서버를 하나씩 재배포하세요.consul-clientStatefulSet이 변경되었다고 보이면 업데이트된 Helm 값을 적용할 때 Consul 클라이언트 StatefulSet이 재배포된다는 뜻입니다. Consul 서버와 달리 이 작업은 Consul 클라이언트가 무상태(stateless)이고 한 번에 재배포될 수 있으므로 다운타임을 의미하지 않습니다.
Consul 및 Helm 차트 업그레이드 (Upgrade Consul and Helm chart)
--version플래그를 업그레이드하려는 차트 버전(이 경우 1.4.9)으로 설정해helm upgrade를 수행해 업그레이드합니다.$ helm upgrade consul hashicorp/consul --namespace consul --version "1.4.9" --values /path/to/my/values.yaml Release "consul" has been upgraded. Happy Helming! NAME: consul LAST DEPLOYED: Tue Apr 22 18:24:14 2025 NAMESPACE: consul STATUS: deployed REVISION: 6 NOTES: Thank you for installing HashiCorp Consul! Your release is named consul. To learn more about the release, run: $ helm status consul --namespace default $ helm get all consul --namespace default Consul on Kubernetes Documentation: https://www.consul.io/docs/platform/k8s Consul on Kubernetes CLI Reference: https://www.consul.io/docs/k8s/k8s-cli- Helm 차트를 업그레이드할 때
--version플래그를 전달하지 않으면 Helm은 로컬 캐시의 가장 최근 차트 버전을 사용하며, 이로 인해 의도하지 않은 버전으로 업그레이드될 수 있습니다.
제로 다운타임을 위한 롤링 업그레이드 (Rolling upgrade for zero downtime)
K8s에서 Consul 서버 클러스터를 업그레이드한다면 롤링 업그레이드를 수행해 Consul 클러스터가 항상 사용 가능하도록 보장할 수 있습니다. 이는 Helm 차트 구성에서 updatePartition 값을 설정함으로써 수행됩니다.
updatePartition 값은 서버 클러스터의 인스턴스가 몇 개까지 업데이트되는지 제어합니다. updatePartition 값보다 큰 인덱스(0부터 시작)를 가진 인스턴스만 업데이트됩니다. 따라서 이를 replicas와 같게 설정하면 서버 파드에 대한 업데이트가 즉시 발생하지 않아야 합니다. updatePartition 값은 Helm 차트 구성의 server 섹션에 설정됩니다. 기본값은 0이며, 이는 서버 클러스터의 모든 인스턴스가 한 번에 업데이트된다는 뜻입니다.
롤링 업그레이드를 수행하려면 다음 단계를 따르세요.
global.image값을 원하는 Consul 버전으로 변경하세요. v1.19.1을 실행 중이고 v1.20.0으로 업그레이드한다고 가정합니다. 이 예시에서는 Helm 차트 버전 1.6.0을 사용합니다.server.updatePartition값을 서버 복제본 수로 설정하세요. 기본적으로 서버가 3개이므로 이 값을 3으로 설정합니다.values.yaml global: ... image: 'registry.connect.redhat.com/hashicorp/consul:1.20.0-ubi' ... server: replicas: 3 updatePartition: 3- 다음으로 업그레이드의 초기 단계를 수행합니다.
$ helm upgrade consul hashicorp/consul --namespace consul --version 1.6.0 --values /path/to/your/values.yamlupdatePartition을 3으로 설정하면 이 명령은 리소스가 업데이트되지만 서버를 재배포하지는 않습니다. - 모든 것이 안정적이면
updatePartition값을 1만큼 줄이고helm upgrade를 다시 수행합니다. 이렇게 하면 첫 번째 Consul 서버가 중지되고 새 이미지로 다시 시작됩니다. - Consul 서버 클러스터가 다시 정상이 될 때까지 기다립니다(30초에서 수 분).
이는 이전 서버 중 하나에서
consul members를 실행하고 모든 서버가 나열되고alive상태인지 확인해 확인할 수 있습니다. 예를 들어 세 번째 서버에서 명령을 실행하려면kubectl exec -it -n consul consul-server-2 -- consul members를 실행합니다. updatePartition을 1만큼 줄이고 다시 업그레이드합니다.updatePartition이0이 될 때까지 계속합니다. 이 시점에서updatePartition구성을 제거할 수 있습니다. 서버 업그레이드가 완료된 것입니다.
Consul Dataplane으로 업그레이드 (Upgrading to Consul Dataplane)
이전 버전에서는 Kubernetes의 Consul이 배포에서 클라이언트 에이전트를 사용했습니다. v1.14.0부터 Consul은 Kubernetes 배포에서 클라이언트 에이전트 대신 Consul Dataplane을 사용합니다.
Consul을 v1.14.0 미만 버전에서 v1.14.0 이상 버전으로 업그레이드한다면 다음 단계를 완료해 다운타임 없이 배포를 안전하게 업그레이드하세요.
- ACL이 활성화된 경우 먼저 consul-k8s 0.49.8로 업그레이드해야 합니다. 이 버전은 ACL이 활성화된 경우 다운타임 없는 업그레이드에 필요한
connectInject.prepareDataplanesUpgrade설정을 노출합니다.connectInject.prepareDataplanesUpgrade를true로 설정한 다음 0.49.8로 업그레이드를 수행하세요.connectInject: prepareDataplanesUpgrade: true - Consul dataplane은 기본적으로 Consul 클라이언트를 비활성화하지만, 업그레이드 중에는 Consul 클라이언트가 계속 실행되도록 해야 합니다. Helm 차트 구성을 편집하고
client.enabled필드를true로 설정하며client.updateStrategy필드에 업그레이드 프로세스 중 Consul이 취할 동작을 지정하세요.client: enabled: true updateStrategy: | type: OnDelete - Kubernetes 배포에서 서버 업그레이드에 대한 권장 절차를 따라 새 Consul 버전의 Helm 값을 업그레이드하세요. 1.14.x 미만 버전에서 서버 업그레이드를 수행하는 동안 최신 consul-k8s 구성 요소는 모든 Consul 서버가 1.14.x 이상 버전이 될 때까지 CrashLoopBackoff 상태일 수 있습니다. 이전 버전 구성 요소가 계속 작동하므로 CrashLoopBackoff의 구성 요소는 클러스터에 부정적인 영향을 미치지 않습니다. 모든 서버가 완전히 업그레이드되면 최신 consul-k8s 구성 요소가 자동으로 CrashLoopBackoff에서 복구되고 이전 구성 요소 버전은 종료됩니다.
kubectl rollout restart를 실행해 서비스 메시 애플리케이션을 다시 시작하세요. 서비스 메시 애플리케이션을 다시 시작하면 Kubernetes가 dataplane에 대한 웹훅으로 재주입합니다.- 서비스 메시의 모든 게이트웨이를 다시 시작하세요.
- 이제 모든 서비스와 게이트웨이가 Consul dataplane을 사용하므로 Helm 차트에서
client스탠자를 삭제하거나client.enabled를false로 설정하고 consul-k8s 또는 Helm 업그레이드를 실행해 클라이언트 에이전트를 비활성화하세요. - ACL이 활성화된 경우 업그레이드 결과로 오래된 ACL 토큰이 유지됩니다. Consul 환경을 정리하려면 토큰을 수동으로 삭제할 수 있습니다. 오래된 connect-injector 토큰은 다음 설명을 가집니다:
token created via login: {"component":"connect-injector"}.pod가 키인 설명(예:token created via login: {"component":"connect-injector","pod":"default/consul-connect-injector-576b65747c-9547x"})이 있는 토큰은 삭제하지 마세요. dataplane이 활성화된 connect inject 파드는 이러한 토큰을 사용합니다. 또한 토큰의 생성 날짜를 검토하고 업그레이드 전에 생성된 injector 토큰만 삭제할 수 있지만, 여전히 사용 중인지 고려하지 않고 모든 오래된 토큰을 삭제해서는 안 됩니다. 서버 토큰과 같은 일부 토큰은 여전히 필요합니다.