외부 서비스의 TLS 인증서로 인그레스 게이트웨이 구성
외부 서비스의 TLS 인증서로 인그레스 게이트웨이 구성 (Ingress Gateway with External TLS Certificates)
이 문서는 시크릿 디스커버리 서비스(SDS)를 사용해 외부 서비스에서 얻은 TLS 인증서를 인바운드 트래픽에 제공하도록 인그레스 게이트웨이를 구성하는 방법을 설명해요. 정적 SDS 클러스터 구성부터 구성 항목 등록까지의 과정을 다룰게요.
출처: 문서
본문
참고
인그레스 게이트웨이는 더 이상 권장되지 않으며 더 이상 업데이트되지 않을 것입니다. 인그레스 게이트웨이는 이 버전에서 완전히 지원되지만 향후 Consul 릴리즈에서 제거할 것입니다. 대신 Consul API 게이트웨이를 사용하세요.
이 페이지는 시크릿 디스커버리 서비스(SDS)를 사용해 외부 서비스에서 얻은 TLS 인증서를 인바운드 트래픽에 제공하도록 인그레스 게이트웨이를 구성하는 방법을 설명합니다. SDS는 맞춤형 TLS 관리 솔루션과 통합을 구축하는 개발자를 위해 설계된 저수준 기능입니다. 더 일반적인 인그레스 게이트웨이 구현에 대한 지침은 가상 머신에서 인그레스 게이트웨이 생성·관리를 참조하세요.
개요 (Overview)
다음 프로세스는 외부 서비스에서 얻은 TLS 인증서를 제공하도록 인그레스 게이트웨이를 구성하는 일반적인 절차를 설명합니다:
- 인그레스 게이트웨이 서비스 정의에서 정적 SDS 클러스터를 구성합니다.
- 서비스 정의를 등록합니다.
- TLS 클라이언트 인증을 구성합니다.
- Envoy를 시작합니다.
- 인그레스 게이트웨이 구성 항목에서 SDS 설정을 구성합니다.
- 인그레스 게이트웨이 구성 항목을 Consul에 등록합니다.
요구 사항 (Requirements)
- 외부 서비스는 Envoy의 gRPC 시크릿 디스커버리 서비스 (SDS) API를 구현해야 합니다.
- Envoy 구성과 SDS 프로토콜에 대한 어느 정도의 친숙함이 있어야 합니다.
- Consul 데이터센터의 모든 서버 에이전트에 대해
connect.enabled매개변수가true로 설정되어야 합니다. - Consul 데이터센터의 모든 서버 에이전트에 대해
ports.grpc매개변수가 구성되어야 합니다.
ACL 요구 사항 (ACL requirements)
ACL이 활성화되어 있다면 다음 권한을 부여하는 토큰을 인그레스 게이트웨이 등록 시 제공해야 합니다:
- 인그레스 게이트웨이의 서비스 이름에 대한
service:write - 인그레스 게이트웨이 구성 항목의 모든 서비스에 대한
service:read - 인그레스 게이트웨이 구성 항목의 서비스의 모든 노드에 대한
node:read
이 권한들은 토큰이 메시의 다른 서비스로 통신을 라우팅하도록 승인합니다. 게이트웨이 노드의 Consul 클라이언트 에이전트가 기본 gRPC 포트 8502를 사용하도록 구성되지 않은 경우, 게이트웨이의 토큰은 에이전트의 gRPC 포트를 발견하기 위해 노드 이름에 대한 agent:read도 제공해야 합니다. gRPC는 Envoy의 xDS API를 Envoy 프록시에 노출하는 데 사용됩니다.
정적 SDS 클러스터 구성 (Configure static SDS clusters)
게이트웨이와 연결된 각 Envoy 프록시에 대해 인그레스 게이트웨이 서비스 정의에서 하나 이상의 추가 정적 클러스터를 정의해야 합니다. 추가 클러스터는 Envoy가 필요한 SDS 서비스에 어떻게 연결해야 하는지 정의합니다.
서비스 정의의 Proxy.Config.envoy_envoy_extra_static_clusters_json 매개변수에서 정적 클러스터를 구성합니다.
클러스터는 연결 정보와 mTLS 자격 증명 같은 필요한 인증 정보를 제공해야 합니다.
Envoy의 부트스트랩 구성에 추가 클러스터를 정의하려면 인그레스 게이트웨이를 Consul 프록시로 수동으로 등록해야 합니다. 정적 클러스터를 정의하기 위해 consul connect envoy -gateway=ingress로 프록시를 자동 등록하는 -register 플래그를 사용할 수 없습니다.
다음 예제에서 public-ingress 게이트웨이는 SDS 인증서와 SDS 인증서 검증 파일 경로를 지정하는 sds-cluster라는 정적 클러스터를 포함합니다:
public-ingress-service.hcl:
Services {
Name = "public-ingress"
Kind = "ingress-gateway"
Proxy {
Config {
envoy_extra_static_clusters_json = <<EOF
{
"name": "sds-cluster",
"connect_timeout": "5s",
"typed_extension_protocol_options": {
"envoy.extensions.upstreams.http.v3.HttpProtocolOptions": {
"@type": "type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions",
"explicit_http_config": {
"http2_protocol_options": {}
}
}
},
"type": "LOGICAL_DNS",
"transport_socket": {
"name":"tls",
"typed_config": {
"@type":"type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext",
"common_tls_context":{
"tls_certificate_sds_secret_configs": [
{
"name":"tls_sds",
"sds_config":{
"path":"/certs/sds-auth-cert.json"
}
}
],
"validation_context_sds_secret_config": {
"name":"validation_context_sds",
"sds_config":{
"path":"/certs/sds-validation.json"
}
}
}
}
},
"load_assignment": {
"cluster_name": "sds-cluster",
"endpoints": [
{
"lb_endpoints": [
{
"endpoint": {
"address": {
"socket_address": {
"address": "sds-server.svc.cluster.local",
"port_value": 8080,
}
}
}
}
]
}
]
}
}
EOF
}
}
}
SDS 클러스터의 구성 매개변수에 대한 자세한 내용은 Envoy 문서를 참조하세요.
인그레스 게이트웨이 서비스 정의 등록 (Register the ingress gateway service definition)
Envoy 프록시 노드의 Consul 에이전트에서 consul services register 명령을 실행해 서비스를 등록합니다. 다음 예제 명령은 public-ingress.hcl 파일에서 인그레스 게이트웨이 프록시를 등록합니다:
$ consul services register public-ingress.hcl
Consul에서 서비스 등록에 대한 추가 정보는 서비스·헬스 체크 등록을 참조하세요.
TLS 클라이언트 인증 구성 (Configure TLS client authentication)
TLS 클라이언트 인증 파일, 인증서 파일, 키를 Envoy 프록시가 실행되는 디스크에 저장하고 Consul에서 사용할 수 있도록 합니다. 인증 파일 구성에 대한 자세한 내용은 Envoy 문서를 참조하세요.
다음 예제는 인증서 체인을 지정합니다:
certs/sds-auth-cert.json:
{
"resources": [
{
"@type": "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret",
"name": "tls_sds",
"tls_certificate": {
"certificate_chain": {
"filename": "/certs/sds-client-auth.crt"
},
"private_key": {
"filename": "/certs/sds-client-auth.key"
}
}
}
]
}
다음 예제는 검증 컨텍스트를 지정합니다:
/certs/sds-validation.json:
{
"resources": [
{
"@type": "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret",
"name": "validation_context_sds",
"validation_context": {
"trusted_ca": {
"filename": "/certs/sds-ca.crt"
}
}
}
]
}
Envoy 시작 (Start Envoy)
consul connect envoy 명령을 실행해 Envoy를 부트스트랩합니다. 다음 예제는 Envoy를 시작하고 public-ingress라는 서비스로 등록합니다:
$ consul connect envoy -gateway=ingress -service public-ingress
consul connect envoy 명령 사용에 대한 추가 정보는 Consul Connect Envoy를 참조하세요.
인그레스 게이트웨이 구성 항목 정의 (Define an ingress gateway configuration entry)
게이트웨이가 SDS의 인증서를 사용할 수 있게 하는 인그레스 게이트웨이 구성 항목을 만듭니다. 구성 항목은 또한 다운스트림 인그레스 리스너를 업스트림 서비스에 매핑합니다. 다음 필드를 구성합니다:
Kind: 값을ingress-gateway로 설정합니다.Name: Consul은Name필드와 일치하는 이름의 인그레스 게이트웨이 프록시에 구성 항목 설정을 적용합니다.TLS: 구성 항목의 메인TLS매개변수가 SDS 구성을 보유합니다. 리스너별·서비스별로 TLS 구성을 지정할 수도 있습니다.TLS.SDS:SDS맵에는 다음 구성 설정이 포함됩니다:ClusterName: SDS 클러스터 구성 시 지정한 클러스터의 이름을 지정합니다.CertResource: 로드할 인증서 리소스의 이름을 지정합니다.
Listeners: 하나 이상의 리스너를 지정합니다.Listeners.Port: 리스너에 대한 포트를 지정합니다. 각 리스너는 포트 번호로 고유하게 식별됩니다.Listeners.Protocol: 기본 프로토콜은tcp이지만 트래픽을 허용하려는 서비스가 사용하는 프로토콜을 지정해야 합니다.Listeners.Services:Services필드에는 업스트림 서비스에 노출하려는 서비스가 포함됩니다. 이 필드는 헬스 체크와 TLS 구성 같은 인그레스 트래픽에 대한 세밀한 제어를 가능하게 하는 여러 옵션과 하위 구성을 포함합니다.
Consul Enterprise 서비스 메시의 경우 게이트웨이와 각 노출된 서비스에 대해 Partition과 Namespace 필드도 구성해야 할 수 있습니다.
지원되는 매개변수에 대한 자세한 내용은 인그레스 게이트웨이 구성 항목 참조를 참조하세요.
다음 예제는 Consul이 sds-cluster라는 SDS 클러스터에서 example.com-public-cert 인증서를 검색해 모든 리스너에 제공하도록 지시합니다:
public-ingress-cfg.hcl:
Kind = "ingress-gateway"
Name = "public-ingress"
TLS {
SDS {
ClusterName = "sds-cluster"
CertResource = "example.com-public-cert"
}
}
Listeners = [
{
Port = 8443
Protocol = "http"
Services = ["*"]
}
]
인그레스 게이트웨이 구성 항목 등록 (Register the ingress gateway configuration entry)
consul config 명령을 사용하거나 /config API 엔드포인트를 호출해 구성 항목을 등록할 수 있습니다.
다음 예제는 로컬 시스템에 저장된 public-ingress-cfg.hcl이라는 인그레스 게이트웨이 구성 항목을 등록합니다:
$ consul config write public-ingress-cfg.hcl
Envoy 인스턴스는 구성 항목에 지정된 포트에서 리스너를 시작하고 SDS 서버에서 이름이 지정된 TLS 인증서를 가져옵니다.