Connect 프록시 참조

Connect 프록시 참조 (connect-proxy)

서비스 정의에서 서비스 메시 프록시를 선언하는 방법을 설명하는 문서예요. kind를 선언하고 프록시가 나타내는 서비스에 대한 정보를 제공해야 서비스 메시 프록시로 동작할 수 있어요.

출처: 문서

본문

이 주제는 서비스 정의에서 서비스 메시 프록시를 선언하는 방법을 설명합니다.

구성 (Configuration)

서비스 메시 프록시를 다음 구문으로 구성합니다:

name =  <name of the service>
kind = "connect-proxy"
proxy = {
  destination_service_name = "<name of the service that the proxy represents>"
  <additional proxy parameters> = "<additional parameter values>"
}
port = <port where services can discover and connect to proxied services>

{
  "name": "<name of the service>",
  "kind": "connect-proxy",
  "proxy": {
    "destination_service_name": "<name of the service that the proxy represents>",
    "<additional proxy parameters>" : "<additional parameter values>"
  },
  "port": <port where services can discover and connect to proxied services>
}

다음 표는 서비스를 프록시로 선언하기 위해 서비스 정의에 추가해야 하는 매개변수를 설명합니다.

매개변수	설명	필수	기본값
kind	서비스의 유형을 선언하는 문자열 값입니다. 서비스를 서비스 메시 프록시로 선언하려면 항상 connect-proxy로 설정해야 합니다.	필수	없음
proxy	프록시 매개변수를 포함하는 객체입니다. destination_service_name 매개변수는 proxy 구성에 포함되어야 합니다. destination_service_name은 프록시가 나타내는 서비스의 이름을 지정합니다. 이 매개변수는 Consul 1.2.0~1.3.0에서 사용된 proxy_destination을 대체합니다. proxy_destination 매개변수는 1.5.0에서 더 이상 사용되지 않습니다.	필수	없음
port	메시의 다른 서비스들이 프록시된 서비스를 발견하고 연결할 수 있는 포트를 지정하는 정수 값입니다.	필수	없음
address	프록시의 IP 주소를 지정합니다. 노드 구성에서 주소를 상속받습니다.	선택	노드 구성에 지정된 address입니다.

요구 사항에 맞게 프록시를 구성하기 위해 여러 추가 매개변수를 지정할 수 있습니다. 추가 정보는 Proxy Parameters를 참조하세요.

예시 (Example)

다음 예시에서 redis-proxy라는 프록시가 서비스 메시 프록시로 등록됩니다. 이 프록시는 redis 서비스로 프록시하며 포트 8181에서 사용할 수 있습니다. 결과적으로 redis에 대한 메시 지원 엔드포인트를 찾는 모든 서비스 메시 클라이언트는 이 프록시를 찾을 수 있습니다.

kind = "connect-proxy"
name = "redis-proxy"
port = 8181
proxy = {
  destination_service_name = "redis"
}

{
  "name": "redis-proxy",
  "kind": "connect-proxy",
  "proxy": {
    "destination_service_name": "redis"
  },
  "port": 8181
}

사이드카 프록시 구성 (Sidecar proxy configuration)

많은 서비스 메시 프록시가 사이드카로 배포됩니다. 사이드카 프록시는 프록시가 나타내는 단일 서비스 인스턴스와 같은 위치에 배치되며 모든 인바운드 트래픽을 그 인스턴스로 프록시합니다.

자체 서비스 등록에서 사이드카 프록시를 구성하려면 proxy 코드 블록에서 다음 매개변수를 지정하세요:

• destination_service_id: 프록시되는 서비스의 ID를 지정하는 문자열 값입니다. proxy parameters reference를 참조하세요.
• local_service_port: 프록시가 로컬 서비스 인스턴스에 연결하는 데 사용할 포트를 지정하는 정수 값입니다.
• local_service_ports: 로컬 다중 포트 서비스 인스턴스가 노출하는 이름이 붙은 포트를 지정하는 배열 값입니다.
• local_service_address: 프록시가 로컬 서비스에 연결하는 데 사용할 IP 주소 또는 호스트 이름을 지정하는 문자열 값입니다.

사이드카로 서비스 메시 프록시를 구성하는 방법에 대한 추가 정보는 Deploy sidecar services를 참조하세요.

완전 구성 예시 (Complete configuration example)

다음 예시는 프록시 인스턴스를 등록할 때 사용할 수 있는 모든 옵션의 값을 포함합니다.

kind = "connect-proxy"
name = "redis-proxy"
port = 8181
proxy = {
  config = {}
  destination_service_id = "redis1"
  destination_service_name = "redis"
  expose = {}
  local_service_address = "127.0.0.1"
  local_service_port = 9090
  local_service_ports = [
    {
      name = "http"
      port = 9090
      default = true
    },
    {
      name = "metrics"
      port = 9102
    },
  ]
  local_service_socket_path = "/tmp/redis.sock"
  mesh_gateway = {}
  mode = "transparent"
  transparent_proxy = {}
  upstreams = []
}

{
  "name": "redis-proxy",
  "kind": "connect-proxy",
  "proxy": {
    "destination_service_name": "redis",
    "destination_service_id": "redis1",
    "local_service_address": "127.0.0.1",
    "local_service_port": 9090,
    "local_service_ports": [
      {
        "name": "http",
        "port": 9090,
        "default": true
      },
      {
        "name": "metrics",
        "port": 9102
      }
    ],
    "local_service_socket_path": "/tmp/redis.sock",
    "mode": "transparent",
    "transparent_proxy": {},
    "config": {},
    "upstreams": [],
    "mesh_gateway": {},
    "expose": {}
  },
  "port": 8181
}

프록시 매개변수 (Proxy parameters)

다음 표는 proxy 블록에서 정의할 수 있는 모든 매개변수를 설명합니다.

매개변수	설명	필수	기본값
destination_service_id	프록시가 나타내는 단일 서비스 인스턴스의 ID를 지정하는 문자열 값입니다. 이 매개변수는 서비스와 같은 노드에서 실행되는 사이드카 프록시에만 적용됩니다. Consul은 같은 에이전트에서 프록시된 서비스를 확인합니다. ID는 고유하며 name 값과 다를 수 있습니다. 이 매개변수를 지정하면 도구가 어느 사이드카 프록시 인스턴스가 어느 애플리케이션 인스턴스와 연결되는지 식별하고, 프록시에서 오는 메트릭의 세밀한 분석을 가능하게 합니다.	사이드카로 프록시 등록 시 필수	없음
local_service_port	사이드카 프록시가 로컬 서비스 인스턴스에 연결하는 데 사용할 포트를 지정하는 정수 값입니다.	사이드카로 프록시 등록 시 필수	destination_service_id에 구성된 서비스 인스턴스가 광고하는 포트
local_service_ports	다중 포트 서비스에서 로컬 서비스 인스턴스의 이름이 붙은 포트를 지정하는 배열 값입니다. local_service_port는 프록시가 단일 로컬 서비스 포트가 필요할 때 사용하는 기본 포트로 유지됩니다.	선택	없음
local_service_address	사이드카 프록시가 로컬 서비스에 연결하는 데 사용할 IP 주소 또는 호스트 이름을 지정하는 문자열 값입니다.	선택	127.0.0.1
destination_service_name	인스턴스가 프록시하는 서비스의 이름을 지정하는 문자열 값입니다. 이 이름은 서비스 발견 중에 특정 서비스 이름에 대한 올바른 프록시 인스턴스로 라우팅하는 데 사용됩니다.	필수	없음
local_service_socket_path	로컬 애플리케이션 인스턴스에 연결하기 위한 Unix 도메인 소켓의 경로를 지정하는 문자열 값입니다. 이 매개변수 값은 애플리케이션이 만들며 local_service_address 및 local_service_port와 충돌합니다. 프록시로 Envoy를 사용할 때 지원됩니다.	선택	없음
mode	프록시 모드를 지정하는 문자열 값입니다. 추가 정보는 Proxy Modes를 참조하세요.	선택	direct
transparent_proxy	transparent 모드의 프록시에 특화된 구성을 지정하는 객체 값입니다. 이 매개변수는 Consul 1.10.0에서 추가되었습니다.	선택	없음
config	불투명한 JSON 구성을 지정하는 객체 값입니다. 이 JSON은 API에서 호출될 때 서비스 인스턴스와 함께 저장되고 반환됩니다.	선택	없음
upstreams	프록시가 리스너를 만들어야 하는 업스트림 서비스를 지정하는 객체 배열입니다.	선택	없음
mesh_gateway	프록시의 메시 게이트웨이 구성을 지정하는 객체 값입니다.	선택	없음
expose	프록시를 통해 HTTP 경로를 노출하는 구성을 지정하는 객체 값입니다. 이 매개변수는 Envoy 프록시와만 호환됩니다.	선택	없음

업스트림 구성 참조 (Upstream configuration reference)

서비스 메시 프록시가 업스트림 서비스를 위한 리스너를 만들도록 구성할 수 있습니다. 리스너를 통해 업스트림 서비스가 요청을 수락할 수 있습니다. 업스트림 서비스 리스너를 구성하려면 다음 매개변수를 지정할 수 있습니다.

다중 포트 서비스 메시 대상의 경우, destination_port를 업스트림 리스너가 라우팅할 이름이 붙은 포트로 설정합니다. 투명 프록시 모드가 활성화되면 애플리케이션이 <port-name>.<service>.virtual.consul 형식의 이름이 붙은 가상 주소로 다이얼할 수 있습니다.

매개변수	설명	필수	기본값
destination_name	서비스 메시를 라우팅할 서비스 또는 prepared query의 이름을 지정하는 문자열 값입니다. prepared query는 이름 또는 ID여야 합니다.	필수	없음
destination_port	다중 포트 업스트림 서비스에서 대상으로 삼을 이름이 붙은 포트를 지정하는 문자열 값입니다. 값은 대상 서비스에 등록된 이름이 붙은 포트 중 하나와 일치해야 합니다.	선택	없음
destination_namespace	업스트림 서비스를 포함하는 네임스페이스를 지정하는 문자열 값입니다. Enterprise	선택	로컬 네임스페이스로 기본 설정
destination_peer	업스트림 서비스를 포함하는 피어(peer) 클러스터의 이름을 지정하는 문자열 값입니다.	선택	없음
destination_partition	업스트림 서비스를 포함하는 admin 파티션의 이름을 지정하는 문자열 값입니다. destination_peer가 설정되면 destination_partition은 피어링이 설정된 로컬 admin 파티션을 가리킵니다. Enterprise	선택	로컬 파티션으로 기본 설정
local_bind_port	로컬 리스너를 바인딩할 포트를 지정하는 정수 값입니다. 애플리케이션은 로컬 포트에서 업스트림으로 아웃바운드 연결을 만듭니다.	필수	없음
local_bind_address	로컬 리스너를 바인딩할 주소를 지정하는 문자열 값입니다. 애플리케이션은 로컬 바인딩 주소에서 업스트림 서비스로 아웃바운드 연결을 만듭니다.	선택	127.0.0.1
local_bind_socket_path	Unix 도메인 소켓 리스너를 바인딩할 경로를 지정하는 문자열 값입니다. 이 매개변수는 local_bind_port 또는 local_bind_address 매개변수와 충돌합니다. 프록시로 Envoy를 사용할 때 지원됩니다.	선택	없음
local_bind_socket_mode	소켓의 파일 권한을 구성하는 Unix 8진수를 지정하는 문자열 값입니다.	선택	없음
destination_type	프록시가 서비스 메시 인스턴스를 찾는 데 사용할 발견 쿼리 유형을 지정하는 문자열 값입니다. 다음 값을 지원합니다: service: 업스트림 service 유형을 쿼리합니다. prepared_query: 업스트림 prepared query를 쿼리합니다.	선택	service
datacenter	발견 쿼리를 보낼 데이터센터를 지정하는 문자열 값입니다.	선택	로컬 데이터센터로 기본 설정
config	업스트림에 대해 프록시 인스턴스에 제공될 불투명한 구성 옵션을 지정하는 객체 값입니다. 유효한 JSON 객체도 지원됩니다. config 매개변수는 주어진 업스트림에 대해 타임아웃, 재시도 및 기타 프록시 특정 기능을 지정할 수 있습니다.	선택	없음
mesh_gateway	프록시의 메시 게이트웨이 구성을 정의하는 객체입니다.	선택	없음

업스트림 구성 예시 (Upstream configuration examples)

업스트림은 여러 대상 유형을 지원합니다. 다음 예시는 각 구현에 대한 정보를 포함합니다. 이 주제의 예시는 구성 파일과 API 등록에서 지원되는 형식이기 때문에 밑줄로 단어를 구분하는 규칙인 snake case를 사용합니다.

예시 서비스 대상 업스트림:

destination_type = "service"
destination_name = "redis"
datacenter = "dc1"
local_bind_address = "127.0.0.1"
local_bind_port = 1234
local_bind_socket_path = "/tmp/redis_5678.sock"
local_bind_socket_mode = "0700"
mesh_gateway = {
    mode = "local"
}

{
  "destination_type": "service",
  "destination_name": "redis",
  "datacenter": "dc1",
  "local_bind_address": "127.0.0.1",
  "local_bind_port": 1234,
  "local_bind_socket_path": "/tmp/redis_5678.sock",
  "local_bind_socket_mode": "0700",
  "mesh_gateway": {
    "mode": "local"
  }
}

예시 이름이 붙은 포트에 대한 다중 포트 서비스 대상 업스트림:

destination_type = "service"
destination_name = "redis"
destination_port = "metrics"
local_bind_port = 1235

{
  "destination_type": "service",
  "destination_name": "redis",
  "destination_port": "metrics",
  "local_bind_port": 1235
}

예시 prepared query 업스트림:

destination_type = "prepared_query"
destination_name = "database"
local_bind_address = "127.0.0.1"
local_bind_port = 1234
config = {}

{
  "destination_type": "prepared_query",
  "destination_name": "database",
  "local_bind_address": "127.0.0.1",
  "local_bind_port": 1234,
  "config": {}
}

예시 admin 파티션 간 원격 업스트림 다이얼:

destination_partition = "finance"
destination_namespace = "default"
destination_type = "service"
destination_name = "billing"
local_bind_port = 9090

{
  "destination_partition": "finance",
  "destination_namespace": "default",
  "destination_type": "service",
  "destination_name": "billing",
  "local_bind_port": 9090
}

예시 피어 간 원격 업스트림 다이얼:

destination_peer = "cloud-services"
destination_partition = "finance"
destination_namespace = "default"
destination_type = "service"
destination_name = "api"
local_bind_port = 9090

{
  "destination_peer": "cloud-services",
  "destination_partition": "finance",
  "destination_namespace": "default",
  "destination_type": "service",
  "destination_name": "api",
  "local_bind_port": 9090
}

프록시 모드 (Proxy modes)

mode 매개변수에 "direct" 또는 "transparent"를 지정하여 프록시가 동작하는 모드를 구성할 수 있습니다. 프록시 모드는 프록시가 트래픽을 전달하는 방식을 결정합니다. 이 기능은 Consul 1.10.0에서 추가되었습니다.

• transparent: 이 모드에서 인바운드 및 아웃바운드 애플리케이션 트래픽이 캡처되어 프록시를 통해 리디렉션됩니다. 이 모드는 트래픽 리디렉션을 활성화하지 않습니다. 트래픽이 이미 리디렉션되고 있는 것처럼 Envoy를 구성하도록 Consul에 지시합니다.
• direct: 이 모드에서 프록시의 리스너는 로컬 애플리케이션과 다른 프록시가 직접 다이얼해야 합니다.

빈 문자열("")을 지정할 수도 있으며, 이는 프록시가 기본 모드로 동작하도록 구성합니다. 기본 모드는 다음 우선 순서로 상위 매개변수에서 상속됩니다:

1. 프록시 서비스의 Proxy 구성
2. 서비스의 service-defaults 구성
3. global proxy-defaults

상위 매개변수에서 모드를 결정할 수 없으면 프록시는 기본적으로 direct 모드가 됩니다.

투명 프록시 구성 참조 (Transparent proxy configuration reference)

다음 예시는 투명 프록시에 대한 추가 구성을 보여줍니다.

22500 포트에서 아웃바운드 트래픽용 프록시 리스너 구성

{
  "outbound_listener_port": 22500,
  "dialed_directly": true
}

• outbound_listener_port (int: 15001) - 프록시가 아웃바운드 트래픽을 수신할 포트입니다. 아웃바운드 애플리케이션 트래픽이 캡처되어 리디렉션되는 포트여야 합니다.
• dialed_directly (bool: false) - 이 프록시 인스턴스의 IP 주소를 투명 프록시가 직접 다이얼할 수 있는지 여부를 결정합니다. 투명 프록시는 일반적으로 인스턴스 간에 로드 밸런싱하는 "가상(virtual)" 태그 주소를 사용해 업스트림을 다이얼합니다. 리더가 있는 데이터베이스 클러스터는 개별 인스턴스를 다이얼하는 것이 도움이 되는 예시입니다. destination_peer를 정의하는 업스트림과 함께 사용할 수 없습니다. 참고 장애 조치 및 리디렉션 같은 동적 라우팅 규칙은 직접 다이얼된 서비스에 적용되지 않습니다. 또한 연결은 5초 연결 타임아웃이 있는 TCP 프록시를 사용해 프록시됩니다.

메시 게이트웨이 구성 참조 (Mesh gateway configuration reference)

다음 예시는 가능한 모든 메시 게이트웨이 구성을 보여줍니다.

로컬 데이터센터에서 로컬 및 이그레스 게이트웨이 사용

{
  "mode": "local"
}

원격 데이터센터의 원격 및 인그레스 서비스로 직접 연결

{
  "mode": "remote"
}

메시 게이트웨이 비활성화

{
  "mode": "none"
}

기본 메시 게이트웨이 모드 지정

{
  "mode": ""
}

• mode (string: "") - 원격 대상 데이터센터를 가진 업스트림이 어떻게 해석되는지에 대한 동작 모드를 정의합니다.
  • "local" - 로컬 데이터센터의 메시 게이트웨이 서비스가 업스트림 연결의 다음 홉(next-hop) 대상으로 사용됩니다.
  • "remote" - 원격/대상 데이터센터의 메시 게이트웨이 서비스가 업스트림 연결의 다음 홉 대상으로 사용됩니다.
  • "none" - 메시 게이트웨이 서비스를 사용하지 않으며 연결의 다음 홉 대상이 최종 서비스로 직접 연결됩니다.
  • "" - 기본 모드입니다. 다른 구성이 활성화하지 않으면 기본 모드는 "none"입니다. 모드 설정의 우선 순위는 다음과 같습니다: Upstream → 프록시 서비스의 Proxy 구성 → 해당 서비스의 service-defaults 구성 → global proxy-defaults.

경로 노출 구성 참조 (Expose paths configuration reference)

다음 예시는 Envoy를 통해 HTTP 경로를 노출하는 가능한 구성을 보여줍니다. Envoy를 통한 경로 노출은 서비스가 localhost에서만 수신하도록 하여 스스로를 보호하면서도, 비메시(non-mesh) 애플리케이션이 HTTP 엔드포인트에 접촉할 수 있게 합니다. 예를 들어 Prometheus용 /metrics 경로나 kubelet liveness 검사용 /healthz를 노출하는 것이 있습니다.

헬스 검사를 위해 Envoy에서 리스너 노출

다음 예시는 로컬 Consul 에이전트에 등록된 HTTP 및 GRPC 검사를 위해 Envoy 리스너를 노출합니다:

{
  "expose": {
    "checks": true
  }
}

HTTP 리스너 노출

다음 예시는 포트 8080에서 수신하는 HTTP 서버로 라우팅되는 포트 21500의 Envoy HTTP 리스너를 노출합니다:

{
  "expose": {
    "paths": [
      {
        "path": "/healthz",
        "local_path_port": 8080,
        "listener_port": 21500
      }
    ]
  }
}

HTTP2 리스너 노출

다음 예시는 포트 9090에서 수신하는 gRPC 서버로 라우팅되는 포트 21501의 Envoy HTTP2 리스너를 노출합니다:

{
  "expose": {
    "paths": [
      {
        "path": "/grpc.health.v1.Health/Check",
        "protocol": "http2",
        "local_path_port": 9090,
        "listener_port": 21501
      }
    ]
  }
}

• checks (bool: false) - 활성화하면 에이전트에 등록된 모든 HTTP 및 gRPC 검사가 Envoy를 통해 노출됩니다. Envoy는 이러한 검사에 대한 리스너를 노출하며 localhost 또는 Consul의 advertise address에서 시작된 연결만 수락합니다. 이 리스너의 포트는 expose_min_port부터 expose_max_port까지 동적으로 할당됩니다. 이 플래그는 Consul 클라이언트가 localhost를 통해 등록된 서비스에 도달할 수 없을 때 유용합니다. 한 가지 예는 Kubernetes에서 Consul을 실행할 때 Consul 에이전트가 자체 파드 안에서 실행되는 경우입니다.
• paths array<Path>: [] - Envoy를 통해 노출할 경로 목록.
  • path (string: "") - 노출할 HTTP 경로입니다. 경로는 슬래시로 시작해야 합니다. 예: /metrics.
  • local_path_port (int: 0) - 로컬 서비스가 해당 경로에 대한 연결을 수신하는 포트입니다.
  • listener_port (int: 0) - 프록시가 연결을 수신할 포트입니다. 이 포트는 리스너가 설정되려면 사용 가능해야 합니다. 포트가 비어 있지 않으면 Envoy는 해당 경로에 대한 리스너를 노출하지 않지만 프록시 등록은 실패하지 않습니다.
  • protocol (string: "http") - 리스너의 프로토콜을 설정합니다. http 또는 http2 중 하나입니다. gRPC에는 http2를 사용합니다.

Unix 도메인 소켓 (Unix domain sockets)

포트 대신 로컬 Unix 도메인 소켓을 사용해 서비스에 연결하려면 서비스의 업스트림 구성에 local_bind_socket_path와 선택적으로 local_bind_socket_mode를 추가합니다.

upstreams = [
  {
    destination_name = "service-1"
    local_bind_socket_path = "/tmp/socket_service_1"
    local_bind_socket_mode = "0700"
  }
]

{
  "upstreams": [
    {
        "destination_name":  "service-1",
        "local_bind_socket_path": "/tmp/socket_service_1",
        "local_bind_socket_mode": "0700"
    }
  ]
}

Envoy는 지정된 경로와 모드로 소켓을 만들고 service-1에 연결합니다. mode 필드는 선택 사항입니다. 생략하면 Envoy가 기본 모드를 사용합니다. 추상 소켓에는 적용되지 않습니다. 자세한 내용은 Envoy documentation을 참조하세요.

참고 이 옵션들은 local_bind_socket_port 및 local_bind_socket_address 옵션과 충돌합니다. 주어진 업스트림에 대해 프록시는 IP 포트 또는 Unix 소켓 중 하나에만 바인딩할 수 있으며 둘 다 할 수는 없습니다.

마찬가지로 Unix 도메인 소켓에서 수신하는 서비스를 서비스 메시에 노출하려면 서비스 정의의 socket_path 필드 또는 프록시 정의의 local_service_socket_path 필드를 사용하세요. 이 필드들은 각각의 위치에서 port 및 service_port 필드와 유사합니다.

services {
  name = "service-2"
  socket_path = "/tmp/socket_service_2"
}

{
  "services": {
    "name": "service-2",
    "socket_path": "/tmp/socket_service_2"
  }
}

또는 프록시 정의에서:

services {
  name = "socket_service_2"
  connect {
    sidecar_service {
      proxy {
        name = "service-2"
        local_service_socket_path = "/tmp/socket_service_2"
      }
    }
  }
}

{
  "services": [
    {
      "name": "socket_service_2",
      "connect": {
        "sidecar_service": {
          "proxy": {
            "name": "service-2",
            "local_service_socket_path": "/tmp/socket_service_2"
          }
        }
      }
    }
  ]
}

서비스가 수신하는 소켓을 만들 것으로 기대되므로 모드 필드가 없습니다. 다시 말해, socket_path와 local_service_socket_path 필드는 address/port 및 local_service_address/local_service_port 구성 옵션과 충돌합니다.

더 알아보기 (Learn more)

• 서비스 메시 프록시 배포
• 사이드카 서비스 배포