API 게이트웨이 리소스 업그레이드

API 게이트웨이 리소스 업그레이드 (Kubernetes)

Consul 릴리스가 요구할 때 API 게이트웨이 Kubernetes 리소스 유형을 업그레이드하는 방법을 설명하는 문서예요.

출처: 문서

본문

이 주제는 Consul 릴리스가 요구할 때 API 게이트웨이 Kubernetes 리소스 유형을 업그레이드하는 방법을 설명해요.

개요 (Overview)

Consul 2.0.0은 consul.hashicorp.com API 그룹에 API 게이트웨이 리소스 유형을 도입해요. 이 리소스 유형은 OpenShift Container Platform(OCP) 4.19 이상과의 호환성을 개선하고, 플랫폼이 Gateway CRD를 관리하는 환경에서 TCPRoute를 지원해요.

요구 사항 (Requirements)

Kubernetes의 Consul 배포.

사전 요구 사항 (Prerequisites)

kubectl 도구는 비OCP 클러스터용, oc는 OCP 클러스터용으로 설치되어야 해요.
클러스터의 Gateways, HTTPRoutes, TCPRoutes, ReferenceGrants를 백업해요.

예를 들어 다음 명령을 실행해 네임스페이스 수준의 리소스별 백업 파일을 만들어요:

OCP

$ mkdir -p gateway-resource-backup && \
  for ns in $(oc get ns -o jsonpath='{.items[*].metadata.name}'); do \
    oc get gateways -n "$ns" -o yaml > "gateway-resource-backup/${ns}-gateways.yaml"; \
    oc get httproutes -n "$ns" -o yaml > "gateway-resource-backup/${ns}-httproutes.yaml"; \
    oc get tcproutes -n "$ns" -o yaml > "gateway-resource-backup/${ns}-tcproutes.yaml"; \
    oc get referencegrants -n "$ns" -o yaml > "gateway-resource-backup/${ns}-referencegrants.yaml"; \
  done

Non-OCP

$ mkdir -p gateway-resource-backup && \
  for ns in $(kubectl get ns -o jsonpath='{.items[*].metadata.name}'); do \
    kubectl get gateways -n "$ns" -o yaml > "gateway-resource-backup/${ns}-gateways.yaml"; \
    kubectl get httproutes -n "$ns" -o yaml > "gateway-resource-backup/${ns}-httproutes.yaml"; \
    kubectl get tcproutes -n "$ns" -o yaml > "gateway-resource-backup/${ns}-tcproutes.yaml"; \
    kubectl get referencegrants -n "$ns" -o yaml > "gateway-resource-backup/${ns}-referencegrants.yaml"; \
  done

추가 정보 (Additional info)

GoDaddy나 Route53을 DNS 제공자로 사용하고 API 게이트웨이를 가리키는 CNAME 레코드가 있다면, Standard API 게이트웨이에서 Consul API 게이트웨이로 전환할 때 그 CNAME 레코드를 업데이트해요.
Consul 2.0으로 업그레이드하면 Consul이 게이트웨이 선택에 따라 매니페스트를 자동으로 생성하고 적용해요:
- Standard API gateway: Consul은 gateway.networking.k8s.io API 그룹의 v1 버전으로 업데이트된 매니페스트를 생성하고 적용해요.
- Consul API gateway: Consul은 Standard API 게이트웨이와 Consul API 게이트웨이 양쪽 모두에 대한 매니페스트를 생성하고 적용해, 두 게이트웨이를 동시에 만들어요. 이는 Standard API 게이트웨이를 해체하기 전에 DNS 제공자(GoDaddy나 Route53 등)에서 CNAME 레코드를 업데이트할 시간을 제공해요.

업그레이드 시나리오 (Upgrade scenarios)

클러스터가 TCPRoute를 사용하지 않는다면 기존 게이트웨이 리소스를 유지할 수 있어요. 클러스터가 TCPRoute를 사용한다면 다음 경우 중 하나에서 새 API 그룹으로 업그레이드해요:

TCPRoute를 사용하고 OCP 4.18에서 4.19 이상으로 업그레이드하는 OCP 클러스터. OCP 4.19 이상과의 호환성을 유지하려면 consul.hashicorp.com API 그룹으로 이동해요.
TCPRoute와 플랫폼 관리 Gateway CRD를 사용하는 비OCP Kubernetes 클러스터. 호환성을 유지하려면 consul.hashicorp.com API 그룹으로 이동해요.

업그레이드 흐름 차트 (Upgrade flow charts)

다음 흐름 차트를 사용해 업그레이드의 올바른 경로를 선택하세요.

Kubernetes 업그레이드 흐름: 플랫폼 업그레이드 미포함

Kubernetes 업그레이드 흐름: 플랫폼 업그레이드 포함

OpenShift Container Platform(OCP) 업그레이드 단계

업그레이드 프로세스

OCP 4.18에서 4.19+로의 업그레이드를 준비하려면 다음 단계를 따를 수 있어요:

OCP 클러스터가 OCP 4.18 이하에서 실행 중이고 대상 버전이 OCP 4.19 이상인지 확인한다.
클러스터에 Consul이 배포되어 있는지 확인한다.
API 그룹 gateway.networking.k8s.io 아래의 게이트웨이 CRD가 클러스터에 사전 설치되어 있는지 검증한다. 사전 설치되어 있다면 global.installK8sNetworkingCRDs: false로 설정한다.
업그레이드 전에 Gateway 관련 리소스가 백업되었는지 확인한다.

백업 및 업그레이드 프로세스에는 다음 리소스 유형이 포함돼요:

모든 준비가 완료되면 흐름 차트를 사용해 업그레이드의 특정 단계를 파악해요. 마지막으로 자신의 구성에 따라 아래 섹션의 단계를 따르세요.

업그레이드 단계 (Upgrade steps)

OpenShift 4.18에서 4.19+로 업그레이드 (OpenShift upgrade from 4.18 to 4.19+)

요구 사항에 따라 다음 values.yaml 구성 중 하나로 helm upgrade를 실행해요.

No TCP Route - Standard API gateway — values.yaml

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

Require TCP Route - Consul API gateway — values.yaml

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

애플리케이션에 대한 접근을 확인해요.

Standard API gateway — 게이트웨이를 통해 애플리케이션에 대한 접근을 확인해요.

$ oc get cgtw -A

 NAMESPACE   NAME                 CLASS                 ADDRESS   PROGRAMMED   AGE
 consul      api-gateway-consul   consul-custom-class             True         72m

Consul API gateway

$ oc get gtw -A

 NAMESPACE   NAME          CLASS    ADDRESS   PROGRAMMED   AGE
 consul      api-gateway   consul             True         3d19h

처음에는 두 개의 게이트웨이가 보일 수 있어요. 두 게이트웨이 모두를 통해 애플리케이션 접근을 확인해요.

DNS(예: Route53)를 Consul DNS를 가리키도록 업데이트해요.

PVC에서 생성된 매니페스트를 백업해요.
OpenShift 문서를 따라 플랫폼 업그레이드를 완료해요. 여기에는 다음이 포함돼요:
- Gateway CRD 삭제.
- 필요한 경우 adminAck 승인.
플랫폼 업그레이드 후 애플리케이션에 대한 접근을 확인해요.

Standard API gateway 3단계에서 가져온 복사된 매니페스트를 적용해요. 게이트웨이가 준비되면 애플리케이션 접근을 확인해요.

Consul API gateway 애플리케이션 접근을 확인해요.

애플리케이션 접근이 실패하면 다음으로 helm upgrade를 실행해요:

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

비OCP 업그레이드 흐름: 플랫폼 업그레이드 미포함 (Non-OCP upgrade flow: platform upgrade not involved)

다음 values.yaml 구성 중 하나로 helm upgrade를 실행해요.

Gateway CRDs are not managed by platform — values.yaml

global:
  installK8sNetworkingCRDs: true
  generateManifests: true
  crds:
    enableTcpRoute: true

Gateway CRDs are managed by platform — values.yaml

global:
  installK8sNetworkingCRDs: false
  generateManifests: true
  crds:
    enableTcpRoute: true

애플리케이션 접근을 확인해요. Standard API 게이트웨이를 사용해 애플리케이션에 접근해요.
PVC에서 생성된 매니페스트를 백업해요.

비OCP 업그레이드 흐름: 플랫폼 업그레이드 포함 (Non-OCP upgrade flow: platform upgrade involved)

이 섹션은 현재 플랫폼 버전이 Gateway CRD를 관리하지 않고, 업그레이드된 플랫폼 버전은 관리한다고 가정해요.

다음 values.yaml 구성 중 하나로 helm upgrade를 실행해요.

No TCPRoute required - Standard API gateway — values.yaml

global:
  installK8sNetworkingCRDs: true
  generateManifests: true
  crds:
    enableTcpRoute: false

TCPRoute required - Consul API gateway — values.yaml

global:
  installK8sNetworkingCRDs: true
  generateManifests: true
  crds:
    enableTcpRoute: true
    consulapi:
      enabled: true

애플리케이션에 대한 접근을 확인해요.

Standard API gateway — 게이트웨이를 통해 애플리케이션에 대한 접근을 확인해요.

Consul API gateway — 처음에는 두 개의 게이트웨이가 보일 수 있어요. 두 게이트웨이 모두를 통해 접근을 확인해요.

DNS(예: Route53)를 Consul DNS를 가리키도록 업데이트해요.

Standard API 게이트웨이와 관련 객체를 삭제해요.

PVC에서 생성된 매니페스트를 백업해요.
플랫폼의 공식 문서에 따라 플랫폼을 업그레이드해요.
애플리케이션에 대한 접근을 확인해요.

Standard API gateway — 게이트웨이를 통해 애플리케이션에 대한 접근을 확인해요.

Consul API gateway — 게이트웨이를 통해 애플리케이션에 대한 접근을 확인해요.

애플리케이션에 접근할 수 없다면 다음으로 helm upgrade를 실행해요:

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

롤백 (Rollback)

Consul 2.x에서 1.9 또는 1.8.14 이전으로 롤백 (Rollback from Consul 2.x to 1.9 or earlier than 1.8.14)

Helm을 사용해 롤백하는 방법은 두 가지가 있어요.

옵션 1 — 직접 버전 롤백 (Direct version rollback)

helm rollback 명령을 실행해 이전 릴리스로 직접 롤백해요.

$ helm rollback --force-conflicts <release-number>

옵션 2 — 명시적 Helm 값 롤백 (Explicit Helm values rollback)

롤백하려는 대상 버전에서 Helm 값을 내보내요. 이 예시는 버전 1.9.4를 사용해요.

$ helm show values hashicorp/consul --version 1.9.4 > values.yaml

필요에 따라 values.yaml의 모든 관련 필드를 업데이트해요.
업데이트된 값 파일을 사용해 대상 버전으로 업그레이드하도록 helm upgrade 명령을 실행해요.

$ helm upgrade --install <release-name> hashicorp/consul \
    --version 1.9.4 \
    --namespace <namespace> \
    --values values.yaml \
    --force-conflicts

API 게이트웨이 리소스 업그레이드