프록시 기본값 구성 항목 참조

프록시 기본값 구성 항목 참조 (Proxy Defaults Configuration Entry Reference)

이 주제는 프록시 기본값(proxy defaults) 구성 항목에 대한 참조 정보를 제공해요. Consul에서 프록시를 사용하는 방법에 대한 정보는 Service mesh proxy 개요를 참고해요.

출처: 문서

본문

소개 (Introduction)

프록시 기본값 구성 항목은 사이드카와 게이트웨이를 포함해 서비스 메시의 프록시에 대한 전역 패스스루(passthrough) Envoy 설정을 정의해요. 프록시 기본값 구성 항목은 피어링된 클러스터, 투명 프록시, TLS 동작의 기능을 제어하지 않아요. 서비스 메시 동작에 영향을 주는 Consul 설정 구성에 대한 정보는 mesh 구성 항목 참조를 참고해요.

Consul은 한 번에 하나의 전역 프록시 기본값 구성 항목만 지원해요. Consul Enterprise에서 여러 구성 항목이 정의된 경우 Consul은 default 파티션의 구성 항목을 구현해요.

구성 모델 (Configuration model)

다음 목록은 프록시 기본값 구성 항목의 필드 계층, 언어별 데이터 유형 및 요구 사항을 설명해요. 기본값을 포함한 추가 세부 정보를 보려면 속성 이름을 클릭해요.

HCL 및 JSON:

  • Kind: string | required | proxy-defaults로 설정해야 함
  • Name: string | global로 설정해야 함
  • Namespace: string | default |

Enterprise

Enterprise

Enterprise

* [`Mode`](/consul/docs/reference/config-entry/proxy-defaults#prioritizebylocality): string | `failover`

YAML:

  • apiVersion: string | required | consul.hashicorp.com/v1alpha1로 설정해야 함
  • kind: string | required | ProxyDefaults로 설정해야 함
  • metadata: map | required
    • name: string | required | global로 설정해야 함
    • namespace: string | default |

Enterprise

Enterprise

  * [`mode`](/consul/docs/reference/config-entry/proxy-defaults#prioritizebylocality): string | `failover`
* [`accessLogs`](/consul/docs/reference/config-entry/proxy-defaults#spec-accesslogs): map
  * [`enabled`](/consul/docs/reference/config-entry/proxy-defaults#spec-accesslogs): boolean | `false`
  * [`disableListenerLogs`](/consul/docs/reference/config-entry/proxy-defaults#spec-accesslogs): boolean | `false`
  * [`type`](/consul/docs/reference/config-entry/proxy-defaults#spec-accesslogs): string | `stdout`
  * [`path`](/consul/docs/reference/config-entry/proxy-defaults#spec-accesslogs): string
  * [`jsonFormat`](/consul/docs/reference/config-entry/proxy-defaults#spec-accesslogs): string
  * [`textFormat`](/consul/docs/reference/config-entry/proxy-defaults#spec-accesslogs): string

전체 구성 (Complete configuration)

모든 필드가 정의되면 프록시 기본값 구성 항목은 다음 형식을 가져요.

HCL:

Kind      = "proxy-defaults"
Name      = "global"
Namespace = "default"
Meta {
  <arbitrary string key> = "<arbitrary string value>"
}
Config {
  <arbitrary string key> = <arbitrary value>
}
EnvoyExtensions = [
  {
    Name= "<name of the extension>"
    Required = "required"
    Arguments = "<arguments to pass to the extension>"
    ConsulVersion = "<Consul version required by the extension>"
    EnvoyVersion = "<Envoy version required by the extension>"
  }
]
Mode = "<name of proxy mode>"
TransparentProxy {
  OutboundListenerPort = <port the proxy should listen on for outbound traffic>
  DialedDirectly       = <true if proxy instances should be dialed directly>
}
MutualTLSMode = "<mutual TLS mode for all proxies>"
MeshGateway {
  Mode = "<name of mesh gateway configuration for all proxies>"
}
Expose {
  Checks = <true to expose all HTTP and gRPC checks through Envoy>

  Paths = [
    {
      Path          = "<the HTTP path to expose>"
      LocalPathPort = <port where the local service is listening for connections to the path>
      ListenerPort  = <port where the proxy will listen for connections>
      Protocol      = "<protocol of the listener>"
    }
  ]
}
PrioritizeByLocality = {
   Mode = "failover"
}
AccessLogs {
  Enabled              = < true | false >
  DisableListenerLogs  = < true | false , disables listener access logs for unrecognized traffic>
  Type                 = "< file | stdout | stdout, the destination for access logs >"
  Path                 = "< set the output path for 'file' based access logs >"
  JSONFormat           = "< json representation of access log format >"
  TextFormat           = "< text representation of access log format >"
}

YAML:

apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
metadata:
  name: global
  namespace: default
spec:
  meta:
    <arbitrary string key>: <arbitrary string value>
  config:
    <arbitrary string key>: <arbitrary value>
  EnvoyExtensions:
  - name: <name of the extension>
    required: required
    arguments: <arguments to pass to the extension>
    consulVersion: <Consul version required by the extension>
    envoyVersion: <Envoy version required by the extension>
  mode: <name of proxy mode>
  transparentProxy:
    outboundListenerPort: <port the proxy should listen on for outbound traffic>
    dialedDirectly: <true if proxy instances should be dialed directly>
  mutualTLSMode: <mutual TLS mode for all proxies>
  meshGateway:
    mode: <name of mesh gateway configuration for all proxies>
  expose:
    checks: <true to expose all HTTP and gRPC checks through Envoy>
    paths:
      - path: <the HTTP path to expose>
        localPathPort: <port where the local service is listening for connections to the path>
        listenerPort: <port where the proxy will listen for connections>
        protocol:= <protocol of the listener>
  accessLogs:
    enabled: < true | false >
    disableListenerLogs:  < true | false , disables listener access logs for unrecognized traffic>
    type: < file | stdout | stdout, the destination for access logs >
    path: < set the output path for 'file' based access logs >
    jsonFormat: < json representation of access log format >
    textFormat: < text representation of access log format >

JSON:

{
  "Kind": "proxy-defaults",
  "Name": "global",
  "Namespace": "default",
  "Meta": {
    "<arbitrary string key>": "<arbitrary string value>"
  },
  "Config": {
    "<arbitrary string key>": <arbitrary value>
  },
  "EnvoyExtensions": [
    {
      "Name": "<name of the extension>",
      "Required": "required",
      "Arguments": "<arguments to pass to the extension>",
      "ConsulVersion": "<Consul version required by the extension>",
      "EnvoyVersion": "<Envoy version required by the extension>"
    }
  ],
  "Mode": "<name of proxy mode>",
  "TransparentProxy": {
    "OutboundListenerPort": <port the proxy should listen on for outbound traffic>,
    "DialedDirectly": <true if proxy instances should be dialed directly>
  },
  "MutualTLSMode": "<mutual TLS mode for all proxies>",
  "MeshGateway": {
    "Mode": = "<name of mesh gateway configuration for all proxies>"
  },
  "Expose": {
    "Checks": <true to expose all HTTP and gRPC checks through Envoy>,
    "Paths": [
      {
        "Path": "<the HTTP path to expose>",
        "LocalPathPort": <port where the local service is listening for connections to the path>,
        "ListenerPort": <port where the proxy will listen for connections>,
        "Protocol": "<protocol of the listener>"
      }
    ]
  },
  "AccessLogs": {
    "Enabled": < true | false >,
    "DisableListenerLogs": < true | false , disables listener access logs for unrecognized traffic>,
    "Type": "< file | stdout | stdout, the destination for access logs >",
    "Path": "< set the output path for 'file' based access logs >",
    "JSONFormat": "< json representation of access log format >",
    "TextFormat": "< text representation of access log format >"
  }
}

사양 (Specification)

이 섹션은 프록시 기본값 구성 항목에서 구성할 수 있는 필드에 대한 세부 정보를 제공해요.

HCL 및 JSON:

Kind

구현할 구성 항목의 유형을 지정해요. proxy-defaults로 설정해야 해요.

값 (Values)
  • 기본값: None
  • 이 필드는 필수예요.
  • 데이터 유형: proxy-defaults로 설정해야 하는 문자열 값.

Name

구성 항목을 식별하는 데 사용되는 구성 항목의 이름을 지정해요. global로 설정해야 해요.

값 (Values)
  • 기본값: None
  • 이 필드는 필수예요.
  • 데이터 유형: global로 설정해야 하는 문자열.

Namespace

프록시 기본값이 적용되는 네임스페이스를 지정해요. default 네임스페이스만 지정할 수 있어요.

값 (Values)
  • 기본값: default
  • 데이터 유형: String

Partition

프록시 기본값이 적용되는 로컬 admin partition을 지정해요. 자세한 내용은 admin partitions을 참고해요.

값 (Values)
  • 기본값: default
  • 데이터 유형: String

Meta

Consul KV 저장소에 추가할 사용자 지정 키-값 쌍 집합을 지정해요.

값 (Values)
  • 기본값: None
  • 데이터 유형: 하나 이상의 키-값 쌍의 맵.
    • Keys: String
    • Values: String, integer 또는 float

Config

서비스 메시 프록시가 사용하는 구성 값의 임의 맵을 지정해요. 사용 가능한 구성은 사용하는 메시 프록시에 따라 달라져요. 이 필드에서 프록시가 허용하는 모든 전역 값을 구성할 수 있어요. 추가 정보는 다음 주제를 참고해요:

값 (Values)
  • 기본값: None
  • 데이터 유형: Map

EnvoyExtensions

Envoy 프록시 구성을 수정하는 확장 목록을 지정해요. 추가 정보는 Envoy extensions을 참고해요.

값 (Values)

다음 표는 EnvoyExtensions 맵의 값 구성 방법을 설명해요:

매개변수 설명 데이터 유형 기본값
Name 확장의 이름을 지정해요. String None
Required Consul이 확장을 구현하도록 요구하려면 true를 지정해요. 이 매개변수를 사용해 보안 통신에 필요한 확장이 의도치 않게 우회되지 않도록 해요. Required가 true로 설정되고 확장이 Envoy 리소스를 업데이트하지 않으면 Consul은 오류를 반환해요. String None
Arguments 확장 실행 파일에 전달할 인수를 지정해요. 구현하려는 확장에 대한 문서를 참고해요. Map None
ConsulVersion 확장이 함께 작동할 수 있는 Consul 버전을 지정해요. Consul은 xDS 업데이트 중에 버전을 검증해요. 다른 버전이 사용 중이면 Consul은 확장을 건너뛰고 이벤트를 로그에 기록해요. Consul이 확장을 구현하려면 ConsulVersion과 EnvoyVersion이 모두 검증되어야 해요. String None
EnvoyVersion 확장이 함께 작동할 수 있는 Envoy 버전을 지정해요. Consul은 xDS 업데이트 중에 버전을 검증해요. 다른 버전이 사용 중이면 Consul은 확장을 건너뛰고 이벤트를 로그에 기록해요. Consul이 확장을 구현하려면 ConsulVersion과 EnvoyVersion이 모두 검증되어야 해요. String None

Mode

프록시가 인바운드 및 아웃바운드 트래픽을 전달하는 방식에 대한 모드를 지정해요. 다음 값 중 하나를 지정할 수 있어요:

  • transparent: 투명 모드에서 프록시는 인바운드 및 아웃바운드 트래픽을 캡처하고 리디렉션해요. 이 모드는 트래픽 리디렉션을 활성화하지 않지만, 트래픽이 이미 리디렉션되고 있는 것처럼 Envoy를 구성하도록 Consul에 지시해요.

  • direct: 이 모드에서 로컬 애플리케이션과 다른 프록시는 프록시 리스너를 직접 다이얼해야 해요.

값 (Values)
  • 기본값: None
  • 데이터 유형: String

TransparentProxy

투명 프록시 모드로 실행되는 프록시에 대한 구성을 포함해요. 이 모드를 사용하면 Consul에 대해 관대한(permissive) mTLS를 활성화해 Consul DNS 대신 Kubernetes 클러스터의 DNS 서비스를 사용할 수 있어요. 추가 정보는 Transparent proxy mode를 참고해요.

구성 항목을 사용해 업스트림 라우팅에 영향을 주는 호출 경로를 정의할 때 다운스트림 및 업스트림 서비스 모두에서 투명 프록시를 활성화해야 해요. 업스트림이 메시를 우회해야 하는 경우 해당 업스트림에 메시 기반 호출 경로를 가정하는 ServiceDefaults 또는 ProxyDefaults 같은 구성 항목을 적용하지 마세요.

값 (Values)

다음 표는 TransparentProxy 맵의 값 구성 방법을 설명해요:

매개변수 설명 데이터 유형 기본값
OutboundListenerPort 프록시가 아웃바운드 트래픽에 대해 수신하는 포트를 지정해요. 아웃바운드 애플리케이션 트래픽은 이 포트로 캡처 및 리디렉션되어야 해요. Integer 15001
DialedDirectly 투명 모드의 다른 프록시가 이 프록시 인스턴스의 IP 주소를 직접 다이얼할 수 있는지 결정해요. 투명 모드의 프록시는 일반적으로 인스턴스 간에 로드 밸런싱하는 virtual 태그 주소에서 업스트림을 다이얼해요. 리더가 있는 데이터베이스 클러스터 같은 상태 저장 서비스에 요청을 보낼 때 개별 인스턴스를 다이얼하는 것이 유용할 수 있어요. Boolean false

MutualTLSMode

모든 프록시의 기본 상호 TLS(mTLS) 모드를 제어해요. 투명 프록시 모드의 서비스에 대해서만 상호 TLS 모드를 설정할 수 있어요.

다음 모드 중 하나를 지정할 수 있어요:

strict: 사이드카 프록시는 수신 트래픽에 mTLS를 요구해요. permissive: 사이드카 프록시는 사이드카 프록시 서비스 포트에서 mTLS 트래픽을 수락하고 대상 서비스 포트에서 모든 트래픽을 수락해요. 서비스를 서비스 메시에 온보딩하는 동안 필요한 경우에만 permissive 모드를 사용할 것을 권장해요.

값 (Values)
  • 기본값: strict
  • 데이터 유형: 다음 문자열 값 중 하나:

MeshGateway

모든 프록시의 기본 메시 게이트웨이 mode 필드를 설정해요. mode 필드에 대해 다음 문자열 값을 지정할 수 있어요:

  • none: 프록시는 메시 게이트웨이를 통해 아웃바운드 연결을 만들지 않아요. 대신 대상 서비스에 직접 아웃바운드 연결을 만들어요.
  • local: 프록시는 같은 데이터 센터에서 실행되는 게이트웨이에 아웃바운드 연결을 만들어요.
  • remote: 프록시는 대상 데이터 센터에서 실행되는 게이트웨이에 아웃바운드 연결을 만들어요.
값 (Values)
  • 기본값: None
  • 데이터 유형: mode 필드를 포함하는 맵

Expose

Envoy를 통해 HTTP 경로를 노출하기 위한 기본 구성을 지정해요. Envoy를 통해 경로를 노출하면 서비스가 localhost에서만 수신하여 스스로를 보호할 수 있어요. Consul 서비스 메시가 활성화되지 않은 애플리케이션도 HTTP 엔드포인트에 접촉할 수 있어요.

예시 사용 사례는 Prometheus 같은 모니터링 시스템에 /metrics 엔드포인트를 노출하고, 라이브니스 검사를 위해 kubelet에 /healthz 엔드포인트를 노출하는 것이에요. 추가 정보는 Expose Paths Configuration Reference를 참고해요.

값 (Values)
  • 기본값: None
  • 데이터 유형: 다음 매개변수를 포함하는 맵:

Expose{}.Checks

true로 설정하면 에이전트에 등록된 모든 HTTP 및 gRPC 검사를 노출해요. Envoy는 검사용 리스너를 노출하고 localhost 또는 Consul 에이전트의 advertise_addr에서 시작된 연결만 수락해요. 리스너의 포트는 에이전트의 expose_min_port 및 expose_max_port 구성에서 동적으로 할당돼요.

Consul 클라이언트가 localhost를 통해 등록된 서비스에 도달할 수 없을 때 Checks 구성을 활성화할 것을 권장해요.

값 (Values)
  • 기본값: false
  • 데이터 유형: Boolean

Expose{}.Paths[]

Expose.Checks가 true로 설정된 경우 Envoy를 통해 노출할 경로를 정의하는 구성 맵 목록을 지정해요.

값 (Values)
  • 기본값: None
  • 데이터 유형: maps 목록

다음 표는 목록에서 정의할 수 있는 각 맵의 매개변수를 설명해요:

매개변수 설명 데이터 유형 기본값
Path 노출할 HTTP 경로를 지정해요. 경로 앞에 슬래시(/)를 붙여야 해요. String None
LocalPathPort 로컬 서비스가 경로에 대한 연결을 수신하는 포트를 지정해요. Integer 0
ListenPort 프록시가 연결을 수신하는 포트를 지정해요. 포트는 사용 가능해야 해요. 포트를 사용할 수 없으면 Envoy는 경로에 대한 리스너를 노출하지 않으며 프록시 등록은 여전히 성공해요. Integer 0
Protocol 리스너의 프로토콜을 지정해요. 다음 값 중 하나를 구성할 수 있어요: \n* http \n* http2: gRPC 트래픽과 함께 사용 \n String http

PrioritizeByLocality

인스턴스가 같은 네트워크 지역 및 영역에 있는 업스트림 대상을 우선시하도록 허용하는 서비스 모드를 설정해요. mode 필드에 대해 다음 문자열 값을 지정할 수 있어요:

  • failover: 서비스가 연결된 업스트림 대상에 도달할 수 없게 되면 서비스는 일치하는 Locality 구성을 가진 정상 업스트림 인스턴스를 우선시해요. 추가 정보는 Route traffic to local upstreams을 참고해요.
값 (Values)
  • 기본값: None
  • 데이터 유형: Map

AccessLogs

게이트웨이를 포함한 서비스 메시의 모든 프록시에 대한 Envoy access logger 구성을 지정해요. 이 필드는 Envoy의 관리 인터페이스의 접근 로그도 구성해요.

값 (Values)
  • 기본값: None
  • 데이터 유형: Map

다음 표는 AccessLogs 맵에서 정의할 수 있는 매개변수를 설명해요:

매개변수 설명 데이터 유형 기본값
Enabled 서비스 메시의 모든 프록시에 대한 접근 로그를 내보내도록 Envoy를 활성화해요. Boolean false
DisabledListenerLogs 리스너 수준에서 거부된 트래픽에 대한 접근 로그를 비활성화해요. 거부된 트래픽에는 Envoy의 구성된 필터 중 어느 것과도 일치하지 않는 연결(예: Consul 업스트림 서비스)이 포함돼요. Envoy가 전달하지 않는 알 수 없는 요청을 기록하고 싶지 않으면 이 옵션을 true로 설정해요. Boolean false
Type 접근 로그의 대상을 지정해요. 다음 유형 중 하나를 지정할 수 있어요: \n* stdout \n* stderr \n* file \n String None
Path Type이 file로 설정된 경우 접근 로그를 파일에 기록할 대상을 지정해요. String None
JSONFormat 각 내보내진 접근 로그의 형식을 나타내는 JSON 형식 문자열을 지정해요. Envoy 명령 연산자를 사용해 내보내진 데이터를 사용자 지정할 수 있어요. 데이터를 중첩할 수도 있어요. 이 필드와 TextFormat 필드를 동시에 설정할 수 없어요. String 기본 로그 형식
TextFormat 각 내보내진 접근 로그의 형식을 나타내는 텍스트 형식 문자열을 지정해요. Envoy 명령 연산자를 사용해 내보내진 데이터를 사용자 지정할 수 있어요. 데이터를 중첩할 수도 있어요. 이 필드와 JSONFormat 필드를 동시에 설정할 수 없어요. String None

YAML:

apiVersion

구성 항목을 적용하는 데 사용할 Consul API 버전을 지정해요. consul.hashicorp.com/v1alpha1로 설정해야 해요.

값 (Values)
  • 기본값: None
  • 이 필드는 필수예요.
  • 데이터 유형: consul.hashicorp.com/v1alpha1로 설정해야 하는 문자열 값.

kind

구현할 구성 항목의 유형을 지정해요. ProxyDefaults로 설정해야 해요.

값 (Values)
  • 기본값: None
  • 이 필드는 필수예요.
  • 데이터 유형: ProxyDefaults로 설정해야 하는 문자열 값.

metadata

구성 항목이 적용되는 서비스 이름, 네임스페이스 및 admin partition을 포함하는 맵.

값 (Values)
  • 기본값: none
  • 다음 문자열을 포함하는 맵:

metadata.name

구성 항목을 식별하는 데 사용되는 구성 항목의 이름을 지정해요. global로 설정해야 해요.

값 (Values)
  • 기본값: None
  • 이 필드는 필수예요.
  • 데이터 유형: global로 설정해야 하는 문자열.

metadata.namespace

프록시 기본값이 적용되는 네임스페이스를 지정해요. 커뮤니티 버전을 사용하는 경우 Consul은 namespace 필드를 무시해요. 추가 정보는 Kubernetes namespaces in Consul을 참고해요. Consul Enterprise를 사용하는 경우 추가 정보는 Kubernetes namespaces in Consul Enterprise를 참고해요.

값 (Values)
  • 기본값: default
  • 데이터 유형: String

spec

ProxyDefaults 구성 항목에 대한 세부 정보를 포함하는 맵. apiVersion, kind, metadata 필드는 spec 필드의 형제(sibling)이며, 다른 모든 구성은 자식이에요.

spec.config

서비스 메시 프록시가 사용하는 구성 값의 임의 맵을 지정해요. 사용 가능한 구성은 사용하는 메시 프록시에 따라 달라져요. 이 필드에서 프록시가 허용하는 모든 전역 값을 구성할 수 있어요. 추가 정보는 다음 주제를 참고해요:

값 (Values)
  • 기본값: None
  • 데이터 유형: Map

spec.envoyExtensions

Envoy 프록시 구성을 수정하는 확장 목록을 지정해요. 추가 정보는 Envoy extensions을 참고해요.

값 (Values)

다음 표는 EnvoyExtensions 맵의 값 구성 방법을 설명해요:

매개변수 설명 데이터 유형 기본값
name 확장의 이름을 지정해요. String None
required Consul이 확장을 구현하도록 요구하려면 true를 지정해요. 이 매개변수를 사용해 보안 통신에 필요한 확장이 의도치 않게 우회되지 않도록 해요. Required가 true로 설정되고 확장이 Envoy 리소스를 업데이트하지 않으면 Consul은 오류를 반환해요. String None
arguments 확장 실행 파일에 전달할 인수를 지정해요. 구현하려는 확장에 대한 문서를 참고해요. Map None
consulVersion 확장이 함께 작동할 수 있는 Consul 버전을 지정해요. Consul은 xDS 업데이트 중에 버전을 검증해요. 다른 버전이 사용 중이면 Consul은 확장을 건너뛰고 이벤트를 로그에 기록해요. Consul이 확장을 구현하려면 consulVersion과 envoyVersion이 모두 검증되어야 해요. String None
envoyVersion 확장이 함께 작동할 수 있는 Envoy 버전을 지정해요. Consul은 xDS 업데이트 중에 버전을 검증해요. 다른 버전이 사용 중이면 Consul은 확장을 건너뛰고 이벤트를 로그에 기록해요. Consul이 확장을 구현하려면 consulVersion과 envoyVersion이 모두 검증되어야 해요. String None

spec.mode

프록시가 인바운드 및 아웃바운드 트래픽을 전달하는 방식에 대한 모드를 지정해요. 다음 값 중 하나를 지정할 수 있어요:

  • transparent: 투명 모드에서 프록시는 인바운드 및 아웃바운드 트래픽을 캡처하고 리디렉션해요. 이 모드는 트래픽 리디렉션을 활성화하지 않지만, 트래픽이 이미 리디렉션되고 있는 것처럼 Envoy를 구성하도록 Consul에 지시해요.

  • direct: 이 모드에서 로컬 애플리케이션과 다른 프록시는 프록시 리스너를 직접 다이얼해야 해요.

값 (Values)
  • 기본값: None
  • 데이터 유형: String

spec.transparentProxy

투명 프록시 모드로 실행되는 프록시에 대한 구성을 포함해요. 이 모드를 사용하면 Consul에 대해 관대한(permissive) mTLS를 활성화해 Consul DNS 대신 Kubernetes 클러스터의 DNS 서비스를 사용할 수 있어요. 추가 정보는 Transparent proxy mode를 참고해요.

값 (Values)

다음 표는 TransparentProxy 맵의 값 구성 방법을 설명해요:

매개변수 설명 데이터 유형 기본값
outboundListenerPort 프록시가 아웃바운드 트래픽에 대해 수신하는 포트를 지정해요. 아웃바운드 애플리케이션 트래픽은 이 포트로 캡처 및 리디렉션되어야 해요. Integer 15001
dialedDirectly 투명 모드의 다른 프록시가 이 프록시 인스턴스의 IP 주소를 직접 다이얼할 수 있는지 결정해요. 투명 모드의 프록시는 일반적으로 인스턴스 간에 로드 밸런싱하는 virtual 태그 주소에서 업스트림을 다이얼해요. 리더가 있는 데이터베이스 클러스터 같은 상태 저장 서비스에 요청을 보낼 때 개별 인스턴스를 다이얼하는 것이 유용할 수 있어요. Boolean false

spec.mutualTLSMode

모든 프록시의 기본 상호 TLS(mTLS) 모드를 제어해요. 투명 프록시 모드의 서비스에 대해서만 상호 TLS 모드를 설정할 수 있어요.

다음 모드 중 하나를 지정할 수 있어요:

strict: 사이드카 프록시는 수신 트래픽에 mTLS를 요구해요. permissive: 사이드카 프록시는 사이드카 프록시 서비스 포트에서 mTLS 트래픽을 수락하고 대상 서비스 포트에서 모든 트래픽을 수락해요. 서비스를 서비스 메시에 온보딩하는 동안 필요한 경우에만 permissive 모드를 사용할 것을 권장해요.

값 (Values)
  • 기본값: strict
  • 데이터 유형: 다음 문자열 값 중 하나:

spec.meshGateway

모든 프록시의 기본 메시 게이트웨이 mode 필드를 설정해요. mode 필드에 대해 다음 문자열 값을 지정할 수 있어요:

  • none: 프록시는 메시 게이트웨이를 통해 아웃바운드 연결을 만들지 않아요. 대신 대상 서비스에 직접 아웃바운드 연결을 만들어요.
  • local: 프록시는 같은 데이터 센터에서 실행되는 게이트웨이에 아웃바운드 연결을 만들어요.
  • remote: 프록시는 대상 데이터 센터에서 실행되는 게이트웨이에 아웃바운드 연결을 만들어요.
값 (Values)
  • 기본값: None
  • 데이터 유형: mode 필드를 포함하는 맵

spec.expose

Envoy를 통해 HTTP 경로를 노출하기 위한 기본 구성을 지정해요. Envoy를 통해 경로를 노출하면 서비스가 localhost에서만 수신하여 스스로를 보호할 수 있어요. Consul 서비스 메시가 활성화되지 않은 애플리케이션도 HTTP 엔드포인트에 접촉할 수 있어요.

예시 사용 사례는 Prometheus 같은 모니터링 시스템에 /metrics 엔드포인트를 노출하고, 라이브니스 검사를 위해 kubelet에 /healthz 엔드포인트를 노출하는 것이에요. 추가 정보는 Expose Paths Configuration Reference를 참고해요.

값 (Values)
  • 기본값: None
  • 데이터 유형: 다음 매개변수를 포함하는 맵:

spec.expose{}.checks

true로 설정하면 에이전트에 등록된 모든 HTTP 및 gRPC 검사를 노출해요. Envoy는 검사용 리스너를 노출하고 localhost 또는 Consul 에이전트의 advertise_addr에서 시작된 연결만 수락해요. 리스너의 포트는 에이전트의 expose_min_port 및 expose_max_port 구성에서 동적으로 할당돼요.

Consul 클라이언트가 localhost를 통해 등록된 서비스에 도달할 수 없을 때(예: Kubernetes에서 Consul 에이전트가 자체 pod에서 실행될 때) Checks 구성을 활성화할 것을 권장해요.

값 (Values)
  • 기본값: false
  • 데이터 유형: Boolean

spec.expose{}.paths[]

spec.expose.checks가 true로 설정된 경우 Envoy를 통해 노출할 경로를 정의하는 구성 맵 목록을 지정해요.

값 (Values)
  • 기본값: None
  • 데이터 유형: maps 목록.

다음 표는 목록에서 정의할 수 있는 각 맵의 매개변수를 설명해요:

매개변수 설명 데이터 유형 기본값
path 노출할 HTTP 경로를 지정해요. 경로 앞에 슬래시(/)를 붙여야 해요. String None
localPathPort 로컬 서비스가 경로에 대한 연결을 수신하는 포트를 지정해요. Integer 0
listenPort 프록시가 연결을 수신하는 포트를 지정해요. 포트는 사용 가능해야 해요. 포트를 사용할 수 없으면 Envoy는 경로에 대한 리스너를 노출하지 않으며 프록시 등록은 여전히 성공해요. Integer 0
protocol 리스너의 프로토콜을 지정해요. 다음 값 중 하나를 구성할 수 있어요: \n* http \n* http2: gRPC 트래픽과 함께 사용 \n String http

spec.prioritizeByLocality

인스턴스가 같은 네트워크 지역 및 영역에 있는 업스트림 대상을 우선시하도록 허용하는 서비스 모드를 설정해요. mode 필드에 대해 다음 문자열 값을 지정할 수 있어요:

  • failover: 서비스가 연결된 업스트림 대상에 도달할 수 없게 되면 서비스는 일치하는 locality 구성을 가진 정상 업스트림 인스턴스를 우선시해요. 추가 정보는 Route traffic to local upstreams을 참고해요.
값 (Values)
  • 기본값: None
  • 데이터 유형: Map

spec.accessLogs

게이트웨이를 포함한 서비스 메시의 모든 프록시에 대한 Envoy access logger 구성을 지정해요. 이 필드는 Envoy의 관리 인터페이스의 접근 로그도 구성해요.

값 (Values)
  • 기본값: None
  • 데이터 유형: Map

다음 표는 accessLogs 맵에서 정의할 수 있는 매개변수를 설명해요:

매개변수 설명 데이터 유형 기본값
enabled 서비스 메시의 모든 프록시에 대한 접근 로그를 내보내도록 Envoy를 활성화해요. Boolean false
disabledListenerLogs 리스너 수준에서 거부된 트래픽에 대한 접근 로그를 비활성화해요. 거부된 트래픽에는 Envoy의 구성된 필터 중 어느 것과도 일치하지 않는 연결(예: Consul 업스트림 서비스)이 포함돼요. Envoy가 전달하지 않는 알 수 없는 요청을 기록하고 싶지 않으면 이 옵션을 true로 설정해요. Boolean false
type 접근 로그의 대상을 지정해요. 다음 유형 중 하나를 지정할 수 있어요: \n* stdout \n* stderr \n* file \n String None
path type이 file로 설정된 경우 접근 로그를 파일에 기록할 대상을 지정해요. String None
jsonFormat 각 내보내진 접근 로그의 형식을 나타내는 JSON 형식 문자열을 지정해요. Envoy 명령 연산자를 사용해 내보내진 데이터를 사용자 지정할 수 있어요. 데이터를 중첩할 수도 있어요. 이 필드와 textFormat 필드를 동시에 설정할 수 없어요. String 기본 로그 형식
textFormat 각 내보내진 접근 로그의 형식을 나타내는 텍스트 형식 문자열을 지정해요. Envoy 명령 연산자를 사용해 내보내진 데이터를 사용자 지정할 수 있어요. 데이터를 중첩할 수도 있어요. 이 필드와 jsonFormat 필드를 동시에 설정할 수 없어요. String None

예시 (Examples)

다음 예시는 프록시 기본값 구성 항목 구성의 일반적인 패턴을 보여줘요.

기본 프로토콜 (Default protocol)

다음 예시는 모든 프록시의 기본 프로토콜을 http로 설정해요.

HCL — Community edition:

Kind      = "proxy-defaults"
Name      = "global"
Config {
  protocol = "http"
}

Consul Enterprise에서 여러 네임스페이스를 사용할 때 프록시 기본값에 영향을 주는 유일한 구성 항목은 default 네임스페이스의 항목이에요. 이 구성은 모든 네임스페이스의 프록시에 적용돼요.

Kind      = "proxy-defaults"
Name      = "global"
Namespace = "default" # Can only be set to "default".
Config {
  protocol = "http"
}

YAML — Community edition:

apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
metadata:
  name: global
spec:
  config:
    protocol: http

Consul Enterprise에서 여러 네임스페이스를 사용할 때 프록시 기본값에 영향을 주는 유일한 구성 항목은 default 네임스페이스의 항목이에요. 이 구성은 모든 네임스페이스의 프록시에 적용돼요.

apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
metadata:
  name: global
  namespace: default
spec:
  config:
    protocol: http

JSON — Community edition:

{
  "Kind": "proxy-defaults",
  "Name": "global",
  "Config": {
    "protocol": "http"
  }
}

Consul Enterprise에서 여러 네임스페이스를 사용할 때 프록시 기본값에 영향을 주는 유일한 구성 항목은 default 네임스페이스의 항목이에요. 이 구성은 모든 네임스페이스의 프록시에 적용돼요.

{
  "Kind": "proxy-defaults",
  "Name": "global",
  "Namespace": "default",
  "Config": {
    "protocol": "http"
  }
}

Prometheus

다음 예시는 모든 프록시가 Prometheus 메트릭을 노출하도록 구성해요.

HCL:

Kind      = "proxy-defaults"
Name      = "global"
Config {
  envoy_prometheus_bind_addr = "0.0.0.0:9102"
}

YAML:

apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
metadata:
  name: global
spec:
  config:
    envoy_prometheus_bind_addr: '0.0.0.0:9102'

JSON:

{
  "Kind": "proxy-defaults",
  "Name": "global",
  "Config": {
    "envoy_prometheus_bind_addr": "0.0.0.0:9102"
  }
}

접근 로그 (Access Logs)

다음 예시는 모든 프록시에 대한 접근 로그를 활성화해요. 더 자세한 예시는 access logs를 참고해요.

HCL:

Kind      = "proxy-defaults"
Name      = "global"
AccessLogs {
  Enabled = true
}

YAML:

apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
metadata:
  name: global
spec:
  accessLogs:
    enabled: true

JSON:

{
  "Kind": "proxy-defaults",
  "Name": "global",
  "AccessLogs": {
    "Enabled": true
  }
}

프록시별 기본값 (Proxy-specific defaults)

다음 예시는 모든 프록시에 대한 사용자 지정 기본값을 구성해요.

HCL:

Kind      = "proxy-defaults"
Name      = "global"
Config {
  local_connect_timeout_ms = 1000
  handshake_timeout_ms     = 10000
  max_request_headers_kb   = 96
}

YAML:

apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
metadata:
  name: global
spec:
  config:
    local_connect_timeout_ms: 1000
    handshake_timeout_ms: 10000
    max_request_headers_kb: 96

JSON:

{
  "Kind": "proxy-defaults",
  "Name": "global",
  "Config": {
    "local_connect_timeout_ms": 1000,
    "handshake_timeout_ms": 10000,
    "max_request_headers_kb": 96
  }
}

HTTP 요청 헤더 크기 제한 (HTTP Request Header Size Limits)

다음 예시는 과대한 헤더로부터 서비스를 보호하는 데 도움이 되도록 HTTP 요청 헤더에 대한 96KB 전역 제한을 구성해요. max_request_headers_kb는 프로토콜이 HTTP 기반 프로토콜(http, http2 또는 grpc)로 설정된 경우에만 적용된다는 점에 유의해요.

HCL:

Kind      = "proxy-defaults"
Name      = "global"
Config {
  protocol               = "http"
  max_request_headers_kb = 96
}

YAML:

apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
metadata:
  name: global
spec:
  config:
    protocol: http
    max_request_headers_kb: 96

JSON:

{
  "Kind": "proxy-defaults",
  "Name": "global",
  "Config": {
    "protocol": "http",
    "max_request_headers_kb": 96
  }
}

더 알아보기 (Learn more)