사이드카 프록시 서비스 생성 및 등록

이 주제에서는 Consul에서 사이드카 프록시 서비스를 만들고 등록하고 시작하는 방법을 설명해요. 사이드카 프록시는 트래픽을 처리하는 단일 서비스 인스턴스와 같은 노드에서 실행돼요.

출처: 문서

본문

이 주제에서는 Consul에서 사이드카 프록시 서비스를 만들고, 등록하고, 시작하는 방법을 설명합니다. 프록시가 Consul의 기능과 운영을 어떻게 가능하게 하는지에 대한 자세한 내용은 Service mesh proxies 개요를 참조하세요. 서비스 메시 프록시 배포에 대한 정보는 Deploy service mesh proxies를 참조하세요.

개요 (Overview)

사이드카 프록시는 해당 프록시가 트래픽을 처리하는 단일 서비스 인스턴스와 같은 노드에서 실행됩니다. 같은 VM에 있을 수도 있고, 같은 네트워크 네임스페이스의 별도 컨테이너로 실행될 수도 있습니다.

메시에 배포하려는 서비스에 사이드카 프록시를 연결할 수 있습니다.

필수는 아니지만 모든 Envoy 프록시에 대한 전역 패스스루 설정을 포함하는 proxy defaults 구성 항목(configuration entry)을 만들 수 있습니다.
connect 블록이 포함된 서비스 정의를 만듭니다. connect 블록에는 서비스가 메시의 다른 서비스와 상호작용할 수 있게 해주는 사이드카 프록시 구성이 포함됩니다.
API 또는 CLI를 사용하여 서비스를 등록합니다.
사이드카 프록시 서비스를 시작합니다.

요구 사항 (Requirements)

ACL이 활성화되어 있고 proxy defaults 구성 항목에서 전역 Envoy 설정을 구성하려면 operator:write 권한이 있는 토큰을 제시해야 합니다. 자세한 내용은 Create a service token을 참조하세요.

전역 Envoy 패스스루 설정 구성

모든 Envoy 프록시에 대한 전역 패스스루 설정을 정의하려면 proxy defaults 구성 항목을 만들고 액세스 로그 구성과 같은 기본 설정을 지정하세요. Service defaults 구성 항목은 proxy defaults를 재정의하고 개별 서비스 구성이 두 구성 항목을 모두 재정의합니다.

proxy defaults 구성 항목을 만들고 다음 매개변수를 지정합니다.
- Kind: proxy-defaults로 설정해야 합니다.
- Name: global로 설정해야 합니다.
모든 프록시에 적용할 추가 설정을 구성합니다. 구성 항목에서 사용 가능한 모든 설정에 대한 자세한 내용은 Proxy defaults configuration entry reference를 참조하세요.
/config API 엔드포인트를 호출하거나 consul config write CLI 명령을 실행하여 구성을 적용합니다. 다음 예시는 CLI를 사용해 로컬 HCL 파일에서 proxy defaults 구성 항목을 작성합니다.

$ consul config write proxy-defaults.hcl

서비스 메시 프록시 정의

서비스 정의를 만들고 다음 필드를 구성하세요.

name: name 필드에 사이드카 프록시를 연결하려는 서비스의 이름을 지정합니다. 이 필드는 Consul에 등록하려는 모든 서비스에 필수입니다.
port: port 필드에 Consul에 등록된 다른 서비스가 서비스를 발견하고 연결할 수 있는 포트 번호를 지정합니다. 이 필드는 Consul에 등록하려는 모든 서비스에 필수입니다.
connect: connect 필드를 { sidecar_service: {} }로 설정합니다. { sidecar_service: {} } 값은 사이드카를 빠르게 구현할 수 있게 해주는 기본 구성 집합을 적용하는 매크로입니다. 자세한 내용은 Sidecar service defaults를 참조하세요.
서비스에 대한 추가 옵션을 구성합니다. 자세한 내용은 Services configuration reference를 참조하세요.

다음 예시에서는 web이라는 서비스가 사이드카 프록시로 구성됩니다.

service = {
  name = "web"
  port = 8080
  connect = { sidecar_service = {} }
}

Consul이 서비스 정의를 처리하면 sidecar_service 매크로 대신 다음 구성을 생성합니다. 사이드카 프록시 서비스는 connect-proxy 유형을 기반으로 합니다.

services = [
  {
    name = "web"
    port = 8080
  }
    checks = {
      Interval = "10s"
      Name = "Connect Sidecar Listening"
      TCP = "127.0.0.1:20000"
    }
    checks = {
      alias_service = "web"
      name = "Connect Sidecar Aliasing web"
    }
    kind = "connect-proxy"
    name = "web-sidecar-proxy"
    port = 20000
    proxy = {
      destination_service_id = "web"
      destination_service_name = "web"
      local_service_address = "127.0.0.1"
      local_service_port = 8080
    }
]

서비스 등록

프록시 서비스를 등록하려면 Consul 에이전트에 서비스 정의를 제공하세요. 애플리케이션 서비스를 등록할 때와 동일한 방법을 프록시 서비스를 등록할 때 사용할 수 있습니다.

서비스 정의를 Consul 에이전트의 구성 디렉터리에 배치하고 에이전트를 시작, 재시작 또는 다시 로드합니다. 기존 프록시 서비스에 변경 사항을 구현할 때 이 방법을 사용하세요.
consul services register 명령을 사용하여 실행 중인 Consul 에이전트에 프록시 서비스를 등록합니다.
/agent/service/register HTTP API 엔드포인트를 호출하여 실행 중인 Consul 에이전트에 프록시 서비스를 등록합니다.

지침은 Register services and health checks를 참조하세요.

다음 예시에서 consul services register 명령은 proxy.hcl에 저장된 프록시 서비스를 등록합니다.

$ consul services register proxy.hcl

프록시 시작

Envoy는 시작하기 전에 부트스트랩 구성 파일이 필요합니다. consul connect envoy 명령을 사용하여 Envoy 부트스트랩 구성을 만들고 프록시 서비스를 시작하세요. 프록시가 연결된 서비스의 이름을 -sidecar-for 옵션으로 지정합니다.

다음 예시 명령은 web 서비스에 대한 Envoy 사이드카 프록시를 시작합니다.

$ consul connect envoy -sidecar-for=web

Consul에서 Envoy 프록시를 운영하는 방법에 대한 자세한 내용은 아래를 참조하세요.

구성 참조 (Configuration reference)

sidecar_service 블록은 대부분의 일반 서비스 정의 필드를 포함할 수 있는 서비스 정의입니다. 사이드카 프록시에 대해 지원되지 않는 서비스 정의 필드에 대한 정보는 Limitations를 참조하세요.

Consul은 사이드카 프록시 서비스 정의를 루트 수준 서비스 정의로 취급합니다. 중첩 정의의 모든 필드는 선택이며, 사이드카 프록시 설정 부담을 줄이기 위한 기본 설정으로 기본값이 지정됩니다.

사이드카 서비스 기본값 (Sidecar service defaults)

다음 필드는 사이드카 서비스 등록 시 기본적으로 설정됩니다. 기재된 예외를 제외하고 connect.sidecar_service 정의에서 어떤 필드든 명시적으로 재정의하여 프록시 등록을 사용자 지정할 수 있습니다. "부모(parent)" 서비스는 사이드카 프록시를 포함하는 서비스 정의를 말합니다.

id - ID는 기본적으로 <parent-service-id>-sidecar-proxy입니다. 이 값은 등록의 lifecycle을 관리하는 데 사용되므로 재정의할 수 없습니다.
name - 기본적으로 <parent-service-name>-sidecar-proxy입니다.
tags - 기본적으로 부모 서비스의 태그입니다.
meta - 기본적으로 부모 서비스의 서비스 메타데이터입니다.
port - 기본적으로 sidecar_min_port와 sidecar_max_port가 지정하는 구성 가능한 범위에서 자동 할당됩니다.
kind - 기본적으로 connect-proxy입니다. 이 값은 재정의할 수 없습니다.
check, checks - 기본적으로 프록시의 로컬 주소와 포트에 TCP 체크를 추가하고 부모 서비스에 대한 service alias check를 추가합니다. check 또는 checks 필드가 설정되면 제공된 체크만 등록됩니다.
proxy.destination_service_name - 기본적으로 부모 서비스 이름입니다.
proxy.destination_service_id - 기본적으로 부모 서비스 ID입니다.
proxy.local_service_address - 기본적으로 127.0.0.1입니다.
proxy.local_service_port - 기본적으로 부모 서비스 포트입니다.

구성이 재정의된 예시

다음 예시에서 sidecar_service 매크로는 프록시에 대한 기준 구성을 설정하지만, proxy upstreams와 built-in proxy configuration 필드에는 사용자 지정 값이 포함됩니다.

{
  "name": "web",
  "port": 8080,
  "connect": {
    "sidecar_service": {
      "proxy": {
        "upstreams": [
          {
            "destination_name": "db",
            "local_bind_port": 9191
          }
        ],
        "config": {
          "handshake_timeout_ms": 1000
        }
      }
    }
  }
}

제한 사항 (Limitations)

다음 필드는 connect.sidecar_service 블록에서 지원되지 않습니다.

id - 사이드카 서비스에는 ID가 할당되며 이 값을 재정의하면 오류입니다. 이 ID는 나중에 부모 서비스가 제거될 때 에이전트가 사이드카 서비스를 올바르게 등록 해제할 수 있도록 하는 데 필요합니다.
kind - kind는 기본적으로 connect-proxy이며 이 동작을 해제할 방법이 없습니다.
connect.sidecar_service - 서비스 정의는 재귀적으로 중첩할 수 없습니다.
connect.native - kind가 connect-proxy로 고정되어 있으며, 서비스 메시 네이티브이기도 한 connect-proxy를 등록하면 오류입니다.

수명주기 (Lifecycle)

사이드카 서비스 등록은 기본 사이드카 옵션에 대한 많은 부수 코드를 추가하지 않도록 하는 구성 구문 도우미이지만, 에이전트는 이를 더 쉽게 사용할 수 있게 하는 수명주기 관련 특정 동작이 있습니다.

에이전트는 사이드카 서비스의 ID를 부모 서비스의 ID를 기반으로 고정합니다. 이로 인해 다음 동작이 가능합니다.

서비스 인스턴스는 언제나 등록된 사이드카 서비스를 하나만 가질 수 있습니다.
HTTP API로 다시 등록하거나 구성 파일에서 다시 로드할 때:
- 중첩된 사이드카 서비스 정의에 변경이 있으면 새로 만들지 않고 현재 사이드카 등록에 업데이트가 적용됩니다.
- 서비스 등록에서 중첩된 sidecar_service를 제거하면 해당 서비스에 대해 이전에 등록된 사이드카가 자동으로 등록 해제됩니다.
구성 파일을 다시 로드할 때 서비스 정의의 ID가 변경되면 새 서비스 인스턴스와 새 사이드카 인스턴스가 등록됩니다. 이전 인스턴스와 프록시는 더 이상 구성 파일에 없으므로 제거됩니다.

사이드카 프록시 서비스 생성 및 등록