API 게이트웨이 구성 참조

API 게이트웨이 구성 참조 (API gateway configuration reference)

가상 머신(VM) 환경의 네트워크에 배포할 수 있는 API 게이트웨이 구성 항목에 대한 참조 정보를 제공해요. Kubernetes에서 Consul API 게이트웨이를 구성하는 방법은 게이트웨이 리소스 구성(Gateway Resource Configuration)을 참조하세요.

출처: 문서

본문

이 항목은 가상 머신(VM) 환경의 네트워크에 배포할 수 있는 API 게이트웨이 구성 항목에 대한 참조 정보를 제공합니다. Kubernetes에서 Consul API 게이트웨이를 구성하는 방법에 대한 참조 정보는 게이트웨이 리소스 구성을 참조하세요.

소개 (Introduction)

게이트웨이는 서비스 트래픽을 어떻게 처리해야 하는지 결정하는 네트워크 인프라 유형입니다. 게이트웨이는 호스트와 포트 집합에 바인딩되는 하나 이상의 리스너를 포함합니다. 그런 다음 HTTP 라우트 또는 TCP 라우트가 게이트웨이 리스너에 연결되어 게이트웨이에서 서비스로 트래픽을 보낼 수 있습니다.

구성 모델 (Configuration model)

다음 목록은 api-gateway 구성 항목의 필드 계층 구조, 언어별 데이터 유형, 요구 사항을 설명합니다. 속성 이름을 클릭하면 기본값을 포함한 추가 세부 정보를 볼 수 있습니다.

Kind : string | "api-gateway"여야 함
Name : string | 기본값 없음
Namespace : string | 기본값 없음 Enterprise
Partition : string | 기본값 없음 Enterprise
Meta : map | 기본값 없음
ExtAuthz : map | none Enterprise
- Enabled : boolean | true
TLS : map | none
- Enabled : boolean | false
- SDS : map | none
  - ClusterName : string | 기본값 없음
  - CertResource : string | 기본값 없음
- TLSMinVersion : string | 기본값 없음
- TLSMaxVersion : string | 기본값 없음
- CipherSuites : string 목록 | Envoy 기본 암호화 스위트
Defaults : map | none
- MaxConnections : number | 0
- MaxPendingRequests : number | 0
- MaxConcurrentRequests : number | 0
Listeners : 객체 목록 | 기본값 없음
- Name : string | 기본값 없음
- Port : number | 기본값 없음
- Hostname : string | "*"
- Protocol : string | "tcp"
- MaxRequestHeadersKB : number | 60
- TLS : map | none
  - MinVersion : string | 기본값 없음
  - MaxVersion : string | 기본값 없음
  - CipherSuites : string 목록 | Envoy 기본 암호화 스위트
  - SDS : map | none
    - ClusterName : string | 기본값 없음
    - CertResource : string | 기본값 없음
  - Certificates : 객체 목록 | 기본값 없음
    - Kind : string | 기본값 없음
    - Name : string | 기본값 없음
    - Namespace : string | 기본값 없음 Enterprise
    - Partition : string | 기본값 없음 Enterprise
- default : map
  - JWT : map
    - Providers : 목록
      - Name : string
      - VerifyClaims : map
        
        Path : 목록
        
        Value : string
- override : map
  - JWT : map
    - Providers : 목록
      - Name : string
      - VerifyClaims : map
        
        Path : 목록
        
        Value : string

TLS SDS 우선 순위 (TLS SDS precedence)

다운스트림 인증서 선택을 위해 Consul은 다음 순서로 유효한 TLS/SDS 소스를 결정합니다.

라우트 서비스 재정의(http-route / tcp-route 서비스 TLS.SDS)
리스너 TLS.SDS
게이트웨이 최상위 TLS.SDS

라우트 서비스 TLS.SDS.ClusterName이 생략되면 Consul은 유효한 리스너 TLS/SDS 구성에서 상속합니다.

완전한 구성 (Complete configuration)

모든 필드가 정의될 때 api-gateway 구성 항목은 다음과 같은 형태를 가집니다.

Kind = "api-gateway"
Name = "<name of api gateway>"
Namespace = "<enterprise: namespace of the gateway>"
Partition = "<enterprise: partition of the gateway>"

Meta = {
  <any key> = "<any value>"
}

ExtAuthz = {
  Enabled = true
}

TLS = {
  Enabled = true
  SDS = {
    ClusterName  = "<sds cluster>"
    CertResource = "<gateway default cert resource>"
  }
  TLSMinVersion = "<version of TLS>"
  TLSMaxVersion = "<version of TLS>"
  CipherSuites = [
    "<cipher suite>"
  ]
}
Defaults = {
  MaxConnections = <number>
  MaxPendingRequests = <number>
  MaxConcurrentRequests = <number>
}

Listeners = [
  {
    Port = <external service port>
    Name = "<unique name for this listener>"
    Protocol = "<protocol used by external service>"
    MaxRequestHeadersKB = <maximum header size in kilobytes>
    TLS = {
      MaxVersion = "<version of TLS>"
      MinVersion = "<version of TLS>"
      CipherSuites = [
        "<cipher suite>"
      ]
      SDS = {
        ClusterName  = "<listener sds cluster>"
        CertResource = "<listener cert resource>"
      }
      # Certificates and SDS are mutually exclusive on the same listener.
      # Certificates = [
      #   {
      #     Kind = "file-system-certificate"
      #     Name = "<name of file-system-certificate>"
      #     Namespace = "<enterprise: namespace of the certificate>"
      #     Partition = "<enterprise: partition of the certificate>"
      #   }
      # ]
    }
    default = {
      JWT = {
        Providers = [
          {
            Name = "<provider>"
            VerifyClaims = {
              Path = ["<path to claim>"]
              Value = "<value of claim>"
            }
          }
        ]
      }
    }
    override = {
      JWT = {
        Providers = [
          {
            Name = "<provider>"
            VerifyClaims = {
              Path = ["<path to claim>"]
              Value = "<value of claim>"
            }
          }
        ]
      }
    }
  }
]

{
  "Kind": "api-gateway",
  "Name": "<name of api gateway>",
  "Namespace": "<enterprise: namespace of the gateway>",
  "Partition": "<enterprise: partition of the gateway>",
  "Meta": {
    "<any key>": "<any value>"
  },
  "ExtAuthz": {
    "Enabled": true
  },
  "TLS": {
    "Enabled": true,
    "SDS": {
      "ClusterName": "<sds cluster>",
      "CertResource": "<gateway default cert resource>"
    },
    "TLSMinVersion": "<version of TLS>",
    "TLSMaxVersion": "<version of TLS>",
    "CipherSuites": [
      "<cipher suite>"
    ]
  }
  "Defaults": {
    "MaxConnections": <number>,
    "MaxPendingRequests": <number>,
    "MaxConcurrentRequests": <number>
  },
  "Listeners": [
    {
      "Name": "<unique name for this listener>",
      "Port": "<external service port>",
      "Protocol": "<protocol used by external service>",
      "TLS": {
        "MaxVersion": "<version of TLS>",
        "MinVersion": "<version of TLS>",
        "CipherSuites": [
          "<cipher suite>"
        ],
        "SDS": {
          "ClusterName": "<listener sds cluster>",
          "CertResource": "<listener cert resource>"
        }
      },
      "default": {
        "JWT": {
          "Providers": [
            {
              "Name": "<name of provider>",
              "VerifyClaims": {
                "Path": ["<path to claim>"],
                "Value": "<value of the claim>"
              }
            }
          ]
        }
      },
      "override": {
        "JWT": {
          "Providers": [
            {
              "Name": "<name of provider>",
              "VerifyClaims": {
                "Path": ["<path to claim>"],
                "Value": "<value of the claim>"
              }
            }
          ]
        }
      }
    }
  ]
}

사양 (Specification)

이 섹션은 api-gateway 구성 항목에서 구성할 수 있는 필드에 대한 세부 정보를 제공합니다.

Kind

구현할 구성 항목의 유형을 지정합니다. api-gateway여야 합니다.

값 (Values)

기본값: 없음
이 필드는 필수입니다.
데이터 유형: "api-gateway"로 설정해야 하는 string 값입니다.

Name

구성 항목의 이름을 지정합니다. 이름은 특정 클러스터에 구성 항목을 적용하는 것과 같은 Consul 작업을 수행할 때 구성 항목을 참조하는 데 사용할 수 있는 메타데이터입니다.

값 (Values)

기본값: 없음
이 필드는 필수입니다.
데이터 유형: string

Namespace Enterprise

구성 항목에 적용할 Enterprise 네임스페이스를 지정합니다.

값 (Values)

기본값: Enterprise의 "default"
데이터 유형: string

Partition Enterprise

구성 항목에 적용할 Enterprise admin 파티션을 지정합니다.

값 (Values)

기본값: Enterprise의 "default"
데이터 유형: string

ExtAuthz Enterprise

게이트웨이 뒤 라우트에 대한 기본 외부 인증 동작을 지정합니다. true로 설정하면 라우트가 http-route ExtAuthz 필터로 옵트아웃하지 않는 한 Envoy는 모든 라우트에 대해 외부 인증 검사를 실행합니다. false로 설정하면 Envoy는 기본적으로 외부 인증 검사를 건너뛰며 라우트가 옵트인해야 합니다.

값 (Values)

기본값: 없음
데이터 유형: map

ExtAuthz.Enabled Enterprise

값 (Values)

기본값: true
데이터 유형: boolean

TLS

API 게이트웨이에 대한 최상위 TLS 기본값을 지정합니다. 리스너 TLS 설정이 이러한 기본값을 재정의할 수 있습니다.

Defaults

API 게이트웨이에 연결된 라우트를 통해 도달하는 서비스에 대한 기본 업스트림 회로 차단기(circuit-breaker) 한도를 지정합니다. http-route 대상 서비스 또는 tcp-route 대상 서비스에 구성된 서비스별 한도가 이러한 값을 재정의합니다. 여러 연결된 라우트가 동일한 업스트림 서비스를 참조할 때 Consul은 각 한도에 대해 가장 낮은 0이 아닌 값을 적용하므로 생성된 Envoy 클러스터가 일관성을 유지합니다.

값 (Values)

기본값: 없음
데이터 유형: Enabled, SDS, TLSMinVersion, TLSMaxVersion, CipherSuites를 포함하는 map입니다.

TLS.Enabled

게이트웨이 기본 수준에서 TLS를 활성화합니다.

값 (Values)

기본값: false
데이터 유형: boolean

TLS.SDS

리스너 수준 TLS.SDS를 정의하지 않는 리스너에 대한 폴백으로 사용되는 최상위 SDS 구성을 지정합니다.

값 (Values)

기본값: 없음
데이터 유형: ClusterName, CertResource를 포함하는 map입니다.

TLS.SDS.ClusterName

SDS에 연결하는 데 사용되는 Envoy 클러스터 이름을 지정합니다.

값 (Values)

기본값: 없음
CertResource가 설정되면 필수입니다.
데이터 유형: string

TLS.SDS.CertResource

Envoy가 요청하는 SDS 인증서 리소스 이름을 지정합니다.

값 (Values)

기본값: 없음
ClusterName이 설정되면 필수입니다.
데이터 유형: string

TLS.TLSMinVersion

최상위 게이트웨이 기본값에 대한 최소 TLS 버전을 지정합니다.

값 (Values)

기본값: 없음
데이터 유형: TLS_AUTO, TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3 중 하나

TLS.TLSMaxVersion

최상위 게이트웨이 기본값에 대한 최대 TLS 버전을 지정합니다.

값 (Values)

기본값: 없음
데이터 유형: TLS_AUTO, TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3 중 하나

TLS.CipherSuites[]

최상위 게이트웨이 기본값에 대한 기본 암호화 스위트를 지정합니다.

값 (Values)

기본값: Envoy 기본값
데이터 유형: string 목록
데이터 유형: MaxConnections, MaxPendingRequests, MaxConcurrentRequests 필드를 포함할 수 있는 맵

Defaults.MaxConnections

라우트 대상 서비스가 설정할 수 있는 최대 업스트림 연결 수를 지정합니다.

값 (Values)

기본값: 0으로, Consul이 프록시의 기본 구성을 사용하도록 지시합니다. Envoy의 경우 기본값은 1024입니다.
데이터 유형: Integer

Defaults.MaxPendingRequests

업스트림 연결을 설정하는 동안 대기열에 넣을 수 있는 최대 요청 수를 지정합니다.

이 구성이 적용되려면 연결된 리스너가 http, http2 또는 grpc 같은 L7 프로토콜을 사용해야 합니다.

값 (Values)

기본값: 0으로, Consul이 프록시의 기본 구성을 사용하도록 지시합니다. Envoy의 경우 기본값은 1024입니다.
데이터 유형: Integer

Defaults.MaxConcurrentRequests

한 시점에 허용되는 최대 동시 업스트림 요청 수를 지정합니다.

이 구성이 적용되려면 연결된 리스너가 http, http2 또는 grpc 같은 L7 프로토콜을 사용해야 합니다.

값 (Values)

기본값: 0으로, Consul이 프록시의 기본 구성을 사용하도록 지시합니다. Envoy의 경우 기본값은 1024입니다.
데이터 유형: Integer

Listeners[]

게이트웨이가 설정해야 하는 리스너 목록을 지정합니다. 리스너는 포트 번호로 고유하게 식별됩니다.

값 (Values)

기본값: 없음
이 필드는 필수입니다.
데이터 유형: map 목록. 각 구성원은 Name, Port, Hostname, Protocol, TLS 필드를 포함합니다.

Listeners[].Name

리스너의 고유 이름을 지정합니다. 이 필드는 문자, 숫자, 하이픈을 허용합니다.

값 (Values)

기본값: 없음
이 필드는 필수입니다.
데이터 유형: string

Listeners[].Port

리스너가 트래픽을 수신하는 포트 번호를 지정합니다.

값 (Values)

기본값: 0
이 필드는 필수입니다.
데이터 유형: integer

Listeners[].Hostname

리스너가 트래픽을 수신하는 호스트 이름을 지정합니다.

값 (Values)

기본값: "*"
이 필드는 선택 사항입니다.
데이터 유형: string

Listeners[].Protocol

리스너와 연결된 프로토콜을 지정합니다.

값 (Values)

기본값: 없음
이 필드는 필수입니다.
데이터 유형은 다음 string 값 중 하나입니다: "tcp" 또는 "http".

Listeners[].MaxRequestHeadersKB

다운스트림 클라이언트에서 업스트림 서비스로 전송되는 요청 헤더의 최대 크기(킬로바이트)를 지정합니다. 이 설정은 HTTP 기반 프로토콜(HTTP, HTTP/2, gRPC)에만 적용됩니다. 요청이 이 한도를 초과하면 게이트웨이는 HTTP 431(요청 헤더 필드가 너무 큼, Request Header Fields Too Large) 오류를 반환합니다. 지정하지 않으면 Envoy의 기본 한도(60KB)를 사용합니다.

값 (Values)

기본값: 60(Envoy의 기본값)
데이터 유형: Integer

Listeners[].TLS

리스너에 대한 TLS 구성을 지정합니다.

값 (Values)

기본값: 없음
MaxVersion, MinVersion, CipherSuites, SDS, Certificates 필드를 포함하는 map입니다.

Listeners[].TLS.SDS

리스너 수준 SDS 구성을 지정합니다.

값 (Values)

기본값: 없음
데이터 유형: ClusterName, CertResource를 포함하는 map입니다.
Listeners[].TLS.SDS와 Listeners[].TLS.Certificates는 상호 배타적입니다.

Listeners[].TLS.SDS.ClusterName

리스너가 SDS에 사용하는 Envoy 클러스터 이름을 지정합니다.

값 (Values)

기본값: 없음
CertResource가 설정되면 필수입니다.
데이터 유형: string

Listeners[].TLS.SDS.CertResource

리스너에 대한 SDS 인증서 리소스 이름을 지정합니다.

값 (Values)

기본값: 없음
ClusterName이 설정되면 필수입니다.
데이터 유형: string

Listeners[].TLS.Certificates[]

리스너가 TLS 종료에 사용하는 파일 시스템 또는 인라인 인증서에 대한 참조 목록입니다. 인증서에 대한 구성 항목을 별도로 만든 다음 Name 필드에서 구성 항목을 참조해야 합니다.

값 (Values)

기본값: 없음
데이터 유형: map 목록.

Listeners[].default

게이트웨이 리스너에 적용할 기본 구성 블록을 지정합니다. 리스너에 연결된 모든 라우트는 기본 구성을 상속합니다. override 블록뿐만 아니라 HTTP 라우트 구성 항목의 JWT 블록에서도 기본 구성보다 우선 순위가 있는 override 구성을 지정할 수 있습니다.

값 (Values)

기본값: 없음
데이터 유형: map

Listeners[].override

게이트웨이 리스너에 적용할 구성 블록을 지정합니다. override 설정은 Listeners[].default 블록의 구성보다 우선 순위가 있습니다.

값 (Values)

기본값: 없음
데이터 유형: map

예시 (Examples)

다음 예시는 특정 사용 사례에 대한 일반적인 API 게이트웨이 구성 패턴을 보여줍니다.

JWT 검증 설정 구성 (Configure JWT verification settings)

다음 예시는 listener-one이 기본적으로 요청에 Okta 사용자 권한이 있는 토큰이 포함되어 있는지 검증하도록 구성합니다. 리스너는 또한 토큰에 api.apps.organization.com의 청중(audience)이 있는지 검증합니다.

Kind = "api-gateway"
Name = "api-gateway"
Listeners = [
  {
    name = "listener-one"
    port = 9001
    protocol = "http"
    override = {
      JWT = {
        Providers = [
          {
            Name = "okta"
            VerifyClaims = {
              Path = ["aud"]
              Value = "api.apps.organization.com"
            }
          }
        ]
      }
    }
    default = {
      JWT = {
        Providers = [
          {
            Name = "okta"
            VerifyClaims = {
              Path = ["perms", "role"]
              Value = "user"
            }
          }
        ]
      }
    }
  }
]

{
  "Kind": "api-gateway",
  "Name": "api-gateway",
  "Listeners": [
    {
      "name": "listener-one",
      "port": 9001,
      "protocol": "http",
      "override": {
        "JWT": {
          "Providers": [
            {
              "Name": "okta",
              "VerifyClaims": {
                "Path": ["aud"],
                "Value": "api.apps.organization.com"
              }
            }
          ]
        }
      },
      "default": {
        "JWT": {
          "Providers": [
            {
              "Name": "okta",
              "VerifyClaims": {
                "Path": ["perms", "role"],
                "Value": "user"
              }
            }
          ]
        }
      }
    }
  ]
}

API 게이트웨이 구성 참조