API Gateway 업그레이드

API Gateway 업그레이드 (API Gateway Upgrade)

Consul API 게이트웨이를 네이티브(내장) 버전으로 업그레이드하는 방법과 이전 버전에서의 각 업그레이드 경로를 설명하는 문서예요.

출처: 문서

본문

Consul v1.15부터 Consul API 게이트웨이는 Consul 바이너리 내부의 네이티브 기능이며 일반 Consul 설치 과정에서 설치됩니다. Consul on Kubernetes v1.2(Consul v1.16)부터 Kubernetes용 Consul API 게이트웨이 사용에 필요한 CRD도 포함됩니다. Consul Helm 차트 v1.2 이상으로 Consul v1.16을 설치할 수 있습니다. 추가 정보는 Install API gateway for Kubernetes를 참조하세요.

소개 (Introduction)

Consul API 게이트웨이는 Consul의 일부로 릴리스되므로 더 이상 독립적인 버전 번호가 없습니다. 대신 API 게이트웨이는 Consul 바이너리와 같은 버전 번호를 상속합니다. 자세한 내용은 릴리스 노트를 참조하세요.

네이티브 API 게이트웨이 사용을 시작하려면 다음 업그레이드 경로 중 하나를 완료하세요:

Consul on Kubernetes v1.1.x에서 업그레이드

1. 네이티브 Consul API 게이트웨이로 업그레이드 지침을 완료합니다.

v0.4.x - v0.5.x에서 업그레이드

1. 표준 업그레이드 지침을 완료합니다.
2. 네이티브 Consul API 게이트웨이로 업그레이드 지침을 완료합니다.

v0.3.x에서 업그레이드

1. v0.4.0으로 업그레이드 지침을 완료합니다.
2. 표준 업그레이드 지침을 완료합니다.
3. 네이티브 Consul API 게이트웨이로 업그레이드 지침을 완료합니다.

v0.2.x에서 업그레이드

1. v0.3.0으로 업그레이드 지침을 완료합니다.
2. v0.4.0으로 업그레이드 지침을 완료합니다.
3. 표준 업그레이드 지침을 완료합니다.
4. 네이티브 Consul API 게이트웨이로 업그레이드 지침을 완료합니다.

v0.1.x에서 업그레이드

1. v0.2.0으로 업그레이드 지침을 완료합니다.
2. v0.3.0으로 업그레이드 지침을 완료합니다.
3. v0.4.0으로 업그레이드 지침을 완료합니다.
4. 표준 업그레이드 지침을 완료합니다.
5. 네이티브 Consul API 게이트웨이로 업그레이드 지침을 완료합니다.

네이티브 Consul API 게이트웨이로 업그레이드 (Upgrade to native Consul API gateway)

Consul on Kubernetes v1.1이 설치된 API 게이트웨이로 업그레이드 절차를 시작해야 합니다. 현재 v1.1보다 오래된 Consul on Kubernetes 버전을 사용 중이라면 네이티브 API 게이트웨이로 업그레이드하기 전에 v1.1로의 업그레이드 경로의 필요한 단계를 완료하세요. 업그레이드 경로에 대한 개요는 소개를 참조하세요.

Consul 관리 CRD (Consul-managed CRDs)

애플리케이션의 다운타임을 허용할 수 있다면 이전에 설치된 CRD를 삭제하고 Consul이 향후 업데이트를 위해 CRD를 설치하고 관리하도록 두어야 합니다. 다운타임의 양은 새 Consul 버전을 얼마나 빨리 설치할 수 있는지에 달려 있습니다. 다운타임을 허용할 수 없다면 Self-managed CRDs를 참조해 다운타임 없이 업그레이드하는 방법을 확인하세요.

1. kubectl delete 명령을 실행하고 kustomize 디렉터리를 참조해 기존 CRD를 삭제합니다. 다음 예시는 API 게이트웨이 v0.5.1로 설치된 CRD를 삭제합니다:

$ kubectl delete --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.5.1"

2. 다음 명령을 실행해 Consul에 패키지된 API 게이트웨이를 사용합니다. Consul은 외부 CRD를 감지하지 못하므로 Consul에 패키지된 API 게이트웨이를 설치하려고 시도할 것입니다.

$ consul-k8s install -config-file values.yaml

3. Gateways가 라우팅하는 모든 백엔드 서비스와 통신할 수 있게 하는 ServiceIntentions을 만듭니다. 자세한 내용은 Service intentions 구성 항목 참조를 참조하세요.
4. 기존 Gateways를 새 GatewayClass consul를 참조하도록 변경합니다. 자세한 내용은 gatewayClass를 참조하세요.
5. 모든 gateway 구성을 새 컨트롤러를 사용하도록 업데이트한 후 Helm 차트에서 apiGateway 블록을 제거하고 Consul 클러스터를 업그레이드할 수 있습니다. 이렇게 하면 이전 게이트웨이 컨트롤러가 완전히 제거됩니다.

values.yaml
global:
  image: hashicorp/consul:1.15
  imageK8S: hashicorp/consul-k8s-control-plane:1.1
- apiGateway:
-  enabled: true
-  image: hashicorp/consul-api-gateway:0.5.4
-  managedGatewayClass:
-    enabled: true

$ consul-k8s install -config-file values.yaml

Self-managed CRDs

참고 이 업그레이드 방법은 Consul on Kubernetes v1.2에서 도입된 connectInject.apiGateway.manageExternalCRDs를 사용합니다. 결과적으로 이 업그레이드 방법을 사용하려면 최소 Consul on Kubernetes v1.2를 사용해야 합니다.

다운타임을 허용할 수 없다면 다음 단계를 완료해 네이티브 Consul API 게이트웨이로 업그레이드할 수 있습니다. 이 업그레이드 옵션을 선택하면 API 게이트웨이 운영에 필요한 CRD를 계속 수동으로 설치해야 합니다.

1. Consul과 함께 제공되는 Consul API 게이트웨이 버전을 설치하고 외부 관리 CRD를 비활성화하는 Helm 차트를 만듭니다:

values.yaml
global:
  image: hashicorp/consul:1.16
  imageK8S: hashicorp/consul-k8s-control-plane:1.2
connectInject:
  apiGateway:
    manageExternalCRDs: false
apiGateway:
  enabled: true
  image: hashicorp/consul-api-gateway:0.5.4
  managedGatewayClass:
    enabled: true

connectInject.apiGateway.manageExternalCRDs를 false로 설정해야 합니다. 레거시 설치로 외부 CRD가 있고 이 값을 설정하지 않으면 Helm이 이미 존재하는 CRD를 설치하려고 하므로 업그레이드하려고 할 때 오류가 발생합니다. 2. 다음 명령을 실행해 새 버전의 API 게이트웨이를 설치하고 외부 관리 CRD를 비활성화합니다:

$ consul-k8s install -config-file values.yaml

3. Gateways가 라우팅하는 모든 백엔드 서비스와 통신할 수 있게 하는 ServiceIntentions을 만듭니다.
4. 기존 Gateways를 새 GatewayClass consul를 참조하도록 변경합니다.
5. 모든 gateway 구성을 새 컨트롤러를 사용하도록 업데이트한 후 Helm 차트에서 apiGateway 블록을 제거하고 Consul 클러스터를 업그레이드할 수 있습니다. 이렇게 하면 이전 게이트웨이 컨트롤러가 완전히 제거됩니다.

values.yaml
global:
  image: hashicorp/consul:1.16
  imageK8S: hashicorp/consul-k8s-control-plane:1.2
connectInject:
  apiGateway:
    manageExternalCRDs: false
- apiGateway:
-  enabled: true
-  image: hashicorp/consul-api-gateway:0.5.4
-  managedGatewayClass:
-    enabled: true

$ consul-k8s install -config-file values.yaml

v0.4.0으로 업그레이드 (Upgrade to v0.4.0)

Consul API 게이트웨이 v0.4.0은 Gateway API v0.5.0과 다음 리소스에 대한 지원을 추가합니다:

• 졸업된 v1beta1 GatewayClass, Gateway 및 HTTPRoute 리소스.
• 동일한 ReferencePolicy 리소스를 대체하는 ReferenceGrant 리소스.

Consul API 게이트웨이 v0.4.0은 기존 ReferencePolicy 리소스와 역호환되지만, 향후 릴리스에서 ReferencePolicy 리소스에 대한 지원을 제거할 것입니다. 업그레이드 후 ReferenceGrant로 마이그레이션하는 것을 권장합니다.

요구 사항 (Requirements)

업그레이드 전에 다음 요구 사항이 충족되는지 확인하세요:

• Consul API 게이트웨이가 v0.3.0을 실행 중이어야 합니다.

절차 (Procedure)

1. 표준 업그레이드를 완료합니다.
2. 업그레이드를 완료한 후 업그레이드 후 구성 변경을 완료합니다. 업그레이드 후 절차는 ReferencePolicy 리소스를 ReferenceGrant 리소스로 교체하는 방법과 GatewayClass, Gateway, HTTPRoute 리소스를 v1alpha2에서 v1beta1로 업그레이드하는 방법을 설명합니다.

업그레이드 후 구성 변경 (Post-upgrade configuration changes)

표준 업그레이드 절차를 수행한 후 다음 단계를 완료하세요.

요구 사항 (Requirements)

• Consul API 게이트웨이가 v0.4.0을 실행 중이어야 합니다.
• Consul Helm 차트가 v0.47.0 이상이어야 합니다.
• kubectl CLI 명령을 실행할 수 있어야 합니다.
• kubectl이 업그레이드 중인 설치를 포함하는 클러스터를 가리키도록 구성되어야 합니다.
• Kubernetes 클러스터에 대해 다음 권한이 있어야 합니다:
  • Gateway.read
  • ReferenceGrant.create (Consul Helm 차트 v0.47.0에서 추가됨)
  • ReferencePolicy.delete

절차 (Procedure)

1. consul-api-gateway-controller Deployment의 현재 버전을 확인합니다:

$ kubectl get deployment --namespace consul consul-api-gateway-controller --output=jsonpath="{@.spec.template.spec.containers[?(@.name=='api-gateway-controller')].image}"

다음과 유사한 응답을 받아야 합니다: "hashicorp/consul-api-gateway:0.4.0" 2. 모든 네임스페이스의 모든 ReferencePolicy 리소스를 가져오는 다음 명령을 실행합니다.

$ kubectl get referencepolicy --all-namespaces

활성 ReferencePolicy 리소스가 있으면 다음과 유사한 출력을 받습니다: "Warning: ReferencePolicy has been renamed to ReferenceGrant... ReferencePolicy will be removed in v0.6.0". 출력이 비어 있으면 7단계에서 설명한 대로 GatewayClass, Gateway, HTTPRoute 리소스를 v1beta1로 업그레이드합니다. 3. 소스 YAML 파일의 각 ReferencePolicy에 대해 kind 필드를 ReferenceGrant로 변경합니다. 필요 시 "policy"라는 용어가 포함된 metadata.name 필드나 파일 이름을 선택적으로 업데이트할 수 있습니다. 다음 예시에서 kind와 metadata.name 필드 및 파일 이름이 새 리소스를 반영하도록 변경되었습니다. kind 필드를 업데이트하면 kubectl edit 명령으로 원격 상태를 직접 편집할 수 없게 됩니다.

referencegrant.yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: reference-grant
  namespace: web-namespace
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    namespace: example-namespace
  to:
  - group: ""
    kind: Service
    name: web-backend

4. 각 파일에 대해 업데이트된 YAML을 클러스터에 적용해 새 ReferenceGrant 리소스를 만듭니다.

$ kubectl apply --filename <file>

5. 각 새 ReferenceGrant가 성공적으로 생성되었는지 확인합니다.

$ kubectl get referencegrant <name> --namespace <namespace>

6. 마지막으로 각 해당하는 이전 ReferencePolicy 리소스를 삭제합니다. 교체 ReferenceGrant 리소스가 이미 만들어졌으므로 참조된 Service 또는 Secret의 가용성에 중단이 없어야 합니다.

$ kubectl delete referencepolicy <name> --namespace <namespace>

7. 소스 YAML의 각 GatewayClass, Gateway, HTTPRoute에 대해 apiVersion 필드를 gateway.networking.k8s.io/v1로 업데이트합니다.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
  namespace: gateway-namespace
spec:
  ...

8. 각 파일에 대해 업데이트된 YAML을 클러스터에 적용해 기존 GatewayClass, Gateway 또는 HTTPRoute 리소스를 업데이트합니다.

$ kubectl apply --filename <file>

v0.2.0 이하에서 v0.3.0으로 업그레이드 (Upgrade to v0.3.0 from v0.2.0 or lower)

Consul API 게이트웨이 v0.3.0은 더 낮은 버전에서 업그레이드하는 사람들을 위한 변경을 도입합니다. 다른 네임스페이스에 정의된 certificateRef가 있는 listeners를 가진 게이트웨이는 이제 certificateRef의 네임스페이스에서 게이트웨이의 네임스페이스의 Gateways가 certificateRef를 사용하도록 명시적으로 허용하는 ReferencePolicy를 요구합니다.

요구 사항: Consul API 게이트웨이 v0.2.1 이하 실행, kubectl CLI 능력, Kubernetes 클러스터에 대한 Gateway.read 및 ReferencePolicy.create 권한. (선택 사항) jq JSON 명령줄 프로세서.

절차: 인증 버전 확인, 다른 네임스페이스에 certificateRefs가 있는 모든 게이트웨이 검색, 각 게이트웨이의 크로스 네임스페이스 certificateRefs에 대한 ReferencePolicy 생성 및 적용을 포함합니다.

v0.2.0으로 업그레이드 (Upgrade to v0.2.0)

Consul API 게이트웨이 v0.2.0은 Consul API 게이트웨이 v0.1.0에서 업그레이드하는 사람들을 위한 변경을 도입합니다. 다른 네임스페이스에 정의된 backendRef가 있는 라우트는 이제 라우트의 네임스페이스에서 backendRef의 네임스페이스로의 트래픽을 명시적으로 허용하는 ReferencePolicy를 요구합니다.

표준 업그레이드 (Standard Upgrade)

참고 명령 또는 구성 설정의 예시에서 VERSION이 보이면 설치하는 릴리스의 버전 번호(예: 0.2.0)로 VERSION을 바꾸세요. VERSION 앞에 소문자 "v"가 있으면 버전 번호는 "v"를 따르며 v0.2.0이 됩니다.

요구 사항: kubectl CLI 능력, kubectl이 업그레이드 중인 설치를 포함하는 클러스터를 가리키도록 구성.

절차 (버전별 특정 단계가 없을 때 사용하는 업그레이드 경로):

1. 새 버전의 CRD를 클러스터에 설치하는 다음 명령을 실행합니다:

$ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=vVERSION"

2. values.yaml에서 apiGateway.image를 업데이트합니다:

values.yaml
...
apiGateway:
  image: hashicorp/consul-api-gateway:VERSION
  ...

3. 다음 명령을 실행해 Consul 설치를 업그레이드합니다:

$ helm upgrade --values values.yaml --namespace consul --version <NEW_VERSION> <DEPLOYMENT_NAME> hashicorp/consul

업그레이드로 인해 Consul API 게이트웨이 컨트롤러가 종료되고 새 버전으로 다시 시작됨을 유의하세요. 4. Kubernetes Gateway API 사양에 따라 Gateway Class 구성은 게이트웨이 생성 시에만 적용되어야 합니다. CRD 설치 업그레이드 후 기존 게이트웨이에 대한 효과를 보려면 다음 명령으로 게이트웨이를 삭제하고 다시 생성하세요:

$ kubectl delete --filename <path_to_gateway_config.yaml>
$ kubectl create --filename <path_to_gateway_config.yaml>

5. (선택 사항) 라우트를 삭제하고 다시 만듭니다. 연결된 라우트가 조정되고 바인딩 오류 보고를 시작하는 데 몇 분이 걸릴 수 있습니다.

$ kubectl delete --filename <path_to_route_config.yaml>
$ kubectl create --filename <path_to_route_config.yaml>

이 업그레이드에는 추가 구성 변경이 필요하지 않습니다.

더 알아보기 (Learn more)

• API Gateway 개요
• 릴리스 노트