Kubernetes에서 API 게이트웨이 스케일링

Kubernetes에서 API 게이트웨이 스케일링 (Scale API Gateways on Kubernetes)

Gateway 주석을 사용해 관리되는 Consul GatewayClass에 대해 게이트웨이별 스케일링을 구성해요. 게이트웨이에 고정 복제본 수를 설정하거나 Consul이 해당 게이트웨이의 Kubernetes 수평 파드 자동 스케일러(HPA)를 관리하도록 할 수 있어요.

출처: 문서

본문

Gateway 주석을 사용해 Kubernetes에서 관리되는 Consul GatewayClass에 대해 게이트웨이별 스케일링을 구성해요. 게이트웨이에 고정 복제본 수를 설정하거나 Consul이 해당 게이트웨이의 Kubernetes 수평 파드 자동 스케일러(HPA)를 관리하도록 할 수 있어요.

Enterprise

이 기능은 Consul Enterprise가 필요해요.

요구 사항 (Requirements)

게이트웨이 스케일링은 다음이 모두 참일 때만 사용할 수 있어요:

Kubernetes에서 관리되는 Consul API 게이트웨이 클래스를 사용 중이어야 해요.
Helm 값 connectInject.apiGateway.managedGatewayClass.scaling.enabled가 true로 설정되어야 해요.
연결된 Consul 클러스터가 유효한 Consul Enterprise 라이선스를 보고해야 해요.

게이트웨이 스케일링이 활성화되지 않으면 Consul은 게이트웨이 스케일링 주석을 무시하고 컨트롤러 관리 HPA를 생성하지 않아요.

게이트웨이 스케일링 활성화 (Enable gateway scaling)

Consul을 설치하거나 업그레이드할 때 connectInject.apiGateway.managedGatewayClass.scaling.enabled Helm 값을 true로 설정해요:

values.yaml:

connectInject:
  enabled: true
  apiGateway:
    managedGatewayClass:
      scaling:
        enabled: true

추가 컨텍스트는 connectInject.apiGateway에 대한 Helm 차트 참조를 참고해요.

정적 복제본 구성 (Configure static replicas)

Consul이 게이트웨이 배포를 고정된 복제본 수로 유지하려면 Gateway 리소스에 consul.hashicorp.com/default-replicas 주석을 추가해요.

gateway.yaml:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: api-gateway
  annotations:
    consul.hashicorp.com/default-replicas: "4"
spec:
  gatewayClassName: consul
  listeners:
    - name: http
      protocol: HTTP
      port: 8080

default-replicas는 양의 정수여야 해요.

컨트롤러 관리 HPA 구성 (Configure controller-managed HPA)

Consul이 게이트웨이 배포에 대한 HPA를 생성하고 조정하도록 하려면 Gateway 리소스에 HPA 주석을 추가해요.

gateway.yaml:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: api-gateway
  annotations:
    consul.hashicorp.com/hpa-enabled: "true"
    consul.hashicorp.com/hpa-minimum-replicas: "3"
    consul.hashicorp.com/hpa-maximum-replicas: "25"
    consul.hashicorp.com/hpa-cpu-utilisation-target: "70"
spec:
  gatewayClassName: consul
  listeners:
    - name: http
      protocol: HTTP
      port: 8080

HPA 모드가 활성화되면 Consul은 <gateway-name>-hpa라는 이름의 컨트롤러 관리 HPA를 생성해요.

선택적 HPA 주석을 생략하면 Consul은 다음 기본값을 사용해요:

최소 복제본: 1
최대 복제본: 10
CPU 사용률 목표: 80

HPA 주석은 다음 검증 규칙을 사용해요:

consul.hashicorp.com/hpa-minimum-replicas는 최소 1이어야 해요.
consul.hashicorp.com/hpa-maximum-replicas는 최소 1이어야 해요.
최소 복제본은 최대 복제본보다 클 수 없어요.
consul.hashicorp.com/hpa-cpu-utilisation-target은 1과 100 사이여야 해요.

우선 순위 및 더 이상 사용되지 않는 필드 (Precedence and deprecated fields)

Consul은 다음 순서로 게이트웨이 스케일링을 해석해요:

게이트웨이 배포를 대상으로 하는 사용자 관리 HPA
게이트웨이 스케일링 주석
더 이상 사용되지 않는 Helm 차트 connectInject.apiGateway.managedGatewayClass.deployment 필드

사용자 관리 HPA가 이미 게이트웨이 배포를 대상으로 하면 Consul은 해당 게이트웨이에 대한 자체 HPA를 생성하거나 관리하지 않아요.

우선 순위 예시 (Precedence examples)

사례 1: 사용자 관리 HPA가 Gateway 주석보다 우선

게이트웨이 배포를 대상으로 하는 자체 HorizontalPodAutoscaler를 만들고 Gateway 리소스에도 스케일링 주석이 있으면 Consul은 사용자 관리 HPA를 사용하고 주석을 완전히 무시해요. Consul은 기존 HPA를 생성하거나 덮어쓰지 않아요.

# User-managed HPA — this takes priority
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: my-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: api-gateway
  minReplicas: 2
  maxReplicas: 8
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 60

다음 Gateway 리소스에 hpa-enabled: "true"가 있더라도 Consul은 이전 예시의 my-hpa를 따르고 두 번째 HPA를 만들지 않아요.

# Gateway annotations are ignored when a user-managed HPA already exists
apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: api-gateway
  annotations:
    consul.hashicorp.com/hpa-enabled: "true"
    consul.hashicorp.com/hpa-minimum-replicas: "3"
    consul.hashicorp.com/hpa-maximum-replicas: "25"
spec:
  gatewayClassName: consul
  listeners:
    - name: http
      protocol: HTTP
      port: 8080

사례 2: Gateway 주석이 더 이상 사용되지 않는 Helm 값보다 우선

Gateway 리소스에 default-replicas 주석이 있고 Helm 차트에 여전히 deployment.defaultInstances 값이 설정되어 있으면 Consul은 주석을 사용하고 Helm 값을 무시해요. 주석이 전혀 평가되려면 scaling.enabled가 true여야 합니다.

# values.yaml — scaling must be enabled; the deprecated defaultInstances is ignored
connectInject:
  apiGateway:
    managedGatewayClass:
      scaling:
        enabled: true       # required for annotations to take effect
      deployment:
        defaultInstances: 2   # ignored because the annotation below is present

# gateway.yaml — annotation wins
apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: api-gateway
  annotations:
    consul.hashicorp.com/default-replicas: "4"   # this value is used
spec:
  gatewayClassName: consul
  listeners:
    - name: http
      protocol: HTTP
      port: 8080

사례 3: 더 이상 사용되지 않는 Helm 값만 있는 경우

Gateway 주석과 사용자 관리 HPA가 모두 없으면 Consul은 더 이상 사용되지 않는 deployment.* Helm 값으로 폴백해요. Consul은 defaultInstances 복제본으로 게이트웨이 배포를 만들고 컨트롤러가 minInstances와 maxInstances를 경계로 강제해요.

# values.yaml — used only as a fallback when no annotations exist
connectInject:
  apiGateway:
    managedGatewayClass:
      deployment:
        defaultInstances: 3
        minInstances: 1
        maxInstances: 5

connectInject.apiGateway.managedGatewayClass.deployment 아래의 다음 Helm 값은 더 이상 사용되지 않으며 향후 릴리스에서 제거될 예정이에요. 각각을 해당하는 Gateway 주석으로 마이그레이션해요.

`deployment.defaultInstances` 마이그레이션 (Migrate `deployment.defaultInstances`)

이전(더 이상 사용되지 않음):

values.yaml:

connectInject:
  apiGateway:
    managedGatewayClass:
      deployment:
        defaultInstances: 4

이후:

gateway.yaml:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: api-gateway
  annotations:
    consul.hashicorp.com/default-replicas: "4"
spec:
  gatewayClassName: consul
  listeners:
    - name: http
      protocol: HTTP
      port: 8080

`deployment.minInstances` 및 `deployment.maxInstances` 마이그레이션 (Migrate `deployment.minInstances` and `deployment.maxInstances`)

이전(더 이상 사용되지 않음):

values.yaml:

connectInject:
  apiGateway:
    managedGatewayClass:
      deployment:
        minInstances: 2
        maxInstances: 10

이후:

gateway.yaml:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: api-gateway
  annotations:
    consul.hashicorp.com/hpa-enabled: "true"
    consul.hashicorp.com/hpa-minimum-replicas: "2"
    consul.hashicorp.com/hpa-maximum-replicas: "10"
spec:
  gatewayClassName: consul
  listeners:
    - name: http
      protocol: HTTP
      port: 8080

더 이상 사용되지 않는 필드의 전체 목록은 connectInject.apiGateway에 대한 Helm 차트 참조를 참고해요.

수동 스케일링 동작 (Manual scaling behavior)

게이트웨이가 게이트웨이 주석이나 컨트롤러 관리 HPA를 사용하지 않으면 초기 배포가 생성된 후 Kubernetes 배포 스케일은 사용자 관리로 유지돼요. 이렇게 하면 Consul이 항상 이전 복제본 수로 강제하지 않고 게이트웨이 배포를 수동으로 스케일링할 수 있어요.

Kubernetes에서 API 게이트웨이 스케일링