클라우드 프로바이더에 클러스터 자동 합류

에이전트가 데이터센터에 자동으로 합류할 수 있도록 retry_join을 구성하는 방법을 설명해 드릴게요. 이 구성은 정적 IP 또는 DNS 주소와 조합하거나 프로바이더마다 여러 구성을 사용할 수도 있어요.

출처: 문서

본문

이 페이지는 서버가 데이터센터에 자동으로 합류할 수 있도록 에이전트에 대해 retry_join을 구성하는 방법을 설명해요. 이 구성은 정적 IP 또는 DNS 주소와 조합하거나, 여러 프로바이더에 대한 여러 구성과도 조합할 수 있어요.

소개

Consul 0.9.1부터 retry-join은 go-discover 라이브러리를 사용하는 통합 인터페이스를 수용하여 클라우드 메타데이터를 사용해 Consul 데이터센터에 자동으로 합류해요. 지원되는 클라우드 프로바이더에서 retry-join을 사용하려면 명령줄 또는 구성 파일에 key=value key=value ... 문자열로 구성을 지정해 주세요.

Consul 0.9.1-0.9.3에서는 값을 URL 인코딩해야 하지만, 대부분의 실용적인 목적에서는 공백을 + 기호로 바꾸면 돼요.

Consul 1.0부터는 값을 문자 그대로 취하며 URL 인코딩하면 안 돼요. 값에 공백, 등호, 백슬래시 또는 큰따옴표가 포함된 경우 큰따옴표로 묶어야 하며 일반적인 이스케이프 규칙이 적용돼요.

$ consul agent -retry-join 'provider=my-cloud config=val config2="some other val" ...'

또는 구성 파일을 통해:

{
  "retry_join": ["provider=my-cloud config=val config2=\"some other val\" ..."]
}

프록시 뒤에서 디스커버리를 사용하려면 Go 언어 net/http 라이브러리에 따라 HTTP_PROXY, HTTPS_PROXY, NO_PROXY 환경 변수를 설정해야 해요.

네트워크 세그먼트와 자동 합류 (Enterprise)

네트워크 세그먼트와 함께 클라우드 자동 합류를 사용하려면 합류하려는 세그먼트의 포트와 일치하도록 Consul 에이전트의 Serf LAN 포트를 재구성해야 해요.

예를 들어 서버 에이전트에 다음과 같은 세그먼트 구성이 있는 경우:

server-config.hcl

segments = [
  {
    name = "alpha"
    bind = "{{GetPrivateIP}}"
    advertise = "{{GetPrivateIP}}"
    port = 8303
  },
  {
    name = "beta"
    bind = "{{GetPrivateIP}}"
    advertise = "{{GetPrivateIP}}"
    port = 8304
  }
]

"alpha" 세그먼트에 합류하려는 Consul 클라이언트 에이전트는 클러스터에 합류를 시도하기 전에 Serf LAN 포트로 포트 8303을 사용하도록 구성해야 해요.

에이전트 구성 / 명령줄 플래그

다음 예시 구성은 ports.serf_lan 구성 옵션을 사용하여 기본 Serf LAN 포트를 재정의해요.

client-config.hcl

ports {
  serf_lan = 8303
}

다음 예시는 -serf-lan-port 명령줄 플래그를 사용하여 기본 Serf LAN 포트를 재정의해요.

$ consul agent -serf-lan-port=8303 -retry-join "provider=..."

Kubernetes

Kubernetes 프로바이더는 일치하는 레이블 또는 필드 선택자가 있는 pod의 IP 주소를 찾아요. 이는 Kubernetes 내에서 실행되는 서버 클러스터에 합류하는 비-Kubernetes 에이전트에 유용해요.

기본적으로 pod IP가 사용되며, 이 경우 연결하는 에이전트가 pod IP에 네트워크 접근이 가능해야 해요. host_network 불리언을 true로 설정하면 호스트 IP를 대신 사용할 수 있지만, 에이전트 포트(Gossip, RPC 등)도 호스트로 내보내야 해요.

기본적으로 포트가 지정되지 않아요. 이 경우 Consul은 기본 gossip 포트(모든 합류 요청의 기본 동작)를 사용해요. pod는 consul.hashicorp.com/auto-join-port 어노테이션으로 포트를 설정할 수 있어요. 값은 정수 또는 이름이 있는 포트일 수 있어요.

$ consul agent -retry-join "provider=k8s label_selector=\"app=consul,component=server\""

{
  "retry-join": ["provider=k8s label_selector=..."]
}

provider (필수) - 프로바이더의 이름 (여기서는 "k8s")
kubeconfig (선택) - kubeconfig 파일의 경로. 설정하지 않으면 인클러스터(in-cluster) 인증을 시도해요. 그게 실패하면 기본 kubeconfig 경로($HOME/.kube/config)를 시도해요.
namespace (선택) - pod를 검색할 네임스페이스. 설정하지 않으면 모든 네임스페이스로 기본 설정돼요.
label_selector (선택) - pod를 매칭하기 위한 레이블 선택자.
field_selector (선택) - pod를 매칭하기 위한 필드 선택자.

프로바이더가 사용하는 Kubernetes 토큰은 원하는 네임스페이스에서 pod를 나열할 수 있는 권한이 필요해요.

AWS EC2 및 ECS

이것은 주어진 tag_key 및 tag_value를 가진 주어진 리전의 모든 서버의 첫 번째 프라이빗 IP 주소를 반환해요.

$ consul agent -retry-join "provider=aws tag_key=... tag_value=..."

{
  "retry_join": ["provider=aws tag_key=... tag_value=..."]
}

provider (필수) - 프로바이더의 이름 (이 경우 "aws")
tag_key (필수) - 자동 합류할 태그의 키
tag_value (필수) - 자동 합류할 태그의 값
region (선택) - 인증할 AWS 리전
addr_type (선택) - 발견할 주소 유형: private_v4, public_v4, public_v6. 기본값은 private_v4예요. (>= 1.0)
access_key_id (선택) - 인증용 AWS 접근 키 (인증에 대한 자세한 내용은 아래 참조)
secret_access_key (선택) - 인증용 AWS 시크릿 접근 키 (인증에 대한 자세한 내용은 아래 참조)
service (선택) - 필터링할 AWS 서비스를 지정하는 문자열 값. ec2 또는 ecs를 지정할 수 있어요. 기본값은 ec2예요.
ecs_cluster (선택) - 특정 AWS ECS 클러스터 이름 또는 전체 ARN으로 검색을 제한하는 문자열 값. 기본적으로 Consul은 지정된 태그 값이 있는 모든 클러스터를 검색해요.
ecs_family (선택) - AWS ECS 작업 정의 패밀리로 검색을 제한하는 문자열 값. 기본적으로 Consul은 지정된 태그가 있는 모든 작업 정의 패밀리를 검색해요.
endpoint (선택) - 사용할 AWS 서비스의 엔드포인트 URL을 지정하는 문자열 값. 설정하지 않으면 AWS 클라이언트가 값을 설정하며, 기본적으로 지정된 리전의 서비스에 대한 공개 DNS 이름으로 설정돼요.

인증 및 우선순위

정적 자격 증명 access_key_id=... secret_access_key=...
환경 변수 (AWS_ACCESS_KEY_ID 및 AWS_SECRET_ACCESS_KEY)
공유 자격 증명 파일 (~/.aws/credentials 또는 AWS_SHARED_CREDENTIALS_FILE에 지정된 경로)
ECS 작업 역할 메타데이터 (컨테이너별)
EC2 인스턴스 역할 메타데이터

EC2 consul-server를 발견하는 데 필요한 유일한 IAM 권한은 ec2:DescribeInstances예요. 데이터센터 자동 합류에만 사용되는 전용 키를 만드는 것을 권장해요. 리전이 생략되면 로컬 인스턴스의 EC2 메타데이터 엔드포인트를 통해 발견돼요.

consul-server를 발견하려는 서비스와 연결된 AWS ECS 작업 역할에는 다음 IAM 권한이 있어야 해요:

ecs:ListClusters (ecs_cluster가 제공되지 않은 경우에만 사용)
ecs:ListServices (ecs_cluster가 제공되지 않은 경우에만 사용)
ecs:DescribeServices (ecs_cluster가 제공되지 않은 경우에만 사용)
ecs:ListTasks
ecs:DescribeTasks

구성에서 리전이 생략되면 Consul은 로컬 인스턴스의 ECS V4 메타데이터 엔드포인트에서 얻어요.

Microsoft Azure

이것은 테넌트와 구독의 가상 NIC에 주어진 tag_name 및 tag_value가 적용된 주어진 리전의 모든 서버의 첫 번째 프라이빗 IP 주소를 반환해요. Virtual Machine Scale Sets의 경우 주어진 resource_group에서.

$ consul agent -retry-join "provider=azure tag_name=... tag_value=... tenant_id=... client_id=... subscription_id=... secret_access_key=..."

{
  "retry_join": [
    "provider=azure tag_name=... tag_value=... tenant_id=... client_id=... subscription_id=... secret_access_key=..."
  ]
}

provider (필수) - 프로바이더의 이름 (이 경우 "azure")
tenant_id (필수) - 머신을 합류시킬 테넌트
client_id (필수) - 인증할 클라이언트
secret_access_key (필수) - 시크릿 클라이언트 키. 참고 이 값은 특히 Azure Portal에서 생성된 경우 값에 등호가 포함되는 경우가 많으므로 secret_access_key='fpOfcHQJAQBczjAxiVpeyLmX1M0M0KPBST+GU2GvEN4='처럼 작은따옴표로 묶는 것이 중요해요.

변수는 환경 변수로도 제공할 수 있어요:

구독에는 ARM_SUBSCRIPTION_ID
테넌트에는 ARM_TENANT_ID
클라이언트에는 ARM_CLIENT_ID
시크릿 접근 키에는 ARM_CLIENT_SECRET

TENANT, CLIENT 또는 CLIENT_SECRET 인수 중 하나라도 생략하면 Consul은 Managed Service Identities(MSI)로 기본 설정돼요. MSI의 목적상 지정된 클라이언트 식별은 무시돼요. MSI에 클라이언트 ID를 전달하려면 AZURE_CLIENT_ID 환경 변수를 사용해야 해요. 자세한 내용은 Azure autorest 패키지 문서를 참고해 주세요.

태그를 사용할 때는 다음 구성 매개변수를 사용해 주세요:

tag_name - 자동 합류할 태그의 이름
tag_value - 자동 합류할 태그의 값

Virtual Machine Scale Sets(Consul 1.0.3 이상)를 사용할 때는 (tag_name 및 tag_value 대신) 다음 구성 매개변수를 사용해 주세요:

resource_group - 필터링할 리소스 그룹의 이름
vm_scale_set - 필터링할 가상 머신 스케일 세트의 이름

태그를 사용할 때 필요한 유일한 권한은 Microsoft.Network/networkInterfaces/read예요. 이 권한의 범위는 Virtual Machine용 가상 NIC가 포함된 Resource Group이에요.

Virtual Machine Scale Sets를 사용할 때 필요한 유일한 역할 작업은 Microsoft.Compute/virtualMachineScaleSets/*/read예요.

참고

Consul 데이터센터가 Azure에서 호스팅되는 경우 Consul은 환경 변수, 공유 클라이언트 ID 및 시크릿 대신 Managed Service Identities(MSI)를 사용하여 Azure에 접근할 수 있어요. MSI는 Consul을 호스팅하는 VM 또는 Virtual Machine Scale Sets에서 활성화되어야 해요. MSI는 Azure 자격 증명이 Consul 구성에 저장되는 것을 방지하므로 선호되는 구성이에요. 이 기능은 Consul 1.7 이상에서 지원돼요. MSI를 사용할 때 Virtual machine에는 tag_name, tag_value, subscription_id를 제공해야 해요. Azure가 VM이 MSI 권한을 감지하는 데 걸리는 시간은 1분에서 1시간 사이일 수 있다는 점에 유의해 주세요.

Google Compute Engine

이것은 주어진 tag_value를 가진 주어진 프로젝트의 모든 서버의 첫 번째 프라이빗 IP 주소를 반환해요.

$ consul agent -retry-join "provider=gce project_name=... tag_value=..."

{
  "retry_join": ["provider=gce project_name=... tag_value=..."]
}

provider (필수) - 프로바이더의 이름 (이 경우 "gce")
tag_value (필수) - 자동 합류할 태그의 값
project_name (선택) - 자동 합류할 프로젝트의 이름. 설정하지 않으면 발견돼요.
zone_pattern (선택) - RE2 호환 정규 표현식을 통해 영역 목록을 제한할 수 있어요. 생략하면 모든 영역의 서버가 반환돼요.
credentials_file (선택) - 인증용 자격 증명 파일. -config-dir를 설정한 경우 credentials.json 파일을 구성 디렉터리에 저장하지 마세요. 구성 파일로 파싱되어 Consul이 시작에 실패할 거예요. 자세한 내용은 아래를 참조하세요.

인증 및 우선순위

디스커버리에는 GCE Service Account가 필요해요. 자격 증명은 우선순위 순서대로 다음 경로에서 검색돼요.

제공된 경우 credentials_file의 자격 증명 사용.
GOOGLE_APPLICATION_CREDENTIALS 환경 변수의 JSON 파일 사용.
gcloud 명령줄 도구가 알 수 있는 위치의 JSON 파일 사용.
Windows에서는 %APPDATA%/gcloud/application_default_credentials.json 경로.
다른 시스템에서는 $HOME/.config/gcloud/application_default_credentials.json 경로.
Google Compute Engine에서는 메타데이터 서버의 자격 증명을 사용해요. 이 마지막 경우 제공된 모든 범위는 무시돼요.

IBM SoftLayer

이것은 주어진 tag_value를 가진 주어진 데이터센터의 모든 서버의 첫 번째 프라이빗 IP 주소를 반환해요.

$ consul agent -retry-join "provider=softlayer datacenter=... tag_value=... username=... api_key=..."

{
  "retry_join": [
    "provider=softlayer datacenter=... tag_value=... username=... api_key=..."
  ]
}

provider (필수) - 프로바이더의 이름 (이 경우 "softlayer")
datacenter (필수) - 합류할 데이터센터의 이름
tag_value (필수) - 자동 합류할 태그의 값
username (필수) - 인증에 사용할 사용자 이름
api_key (필수) - 인증에 사용할 API 키

Aliyun (Alibaba Cloud)

이것은 주어진 tag_key 및 tag_value를 가진 주어진 region의 모든 서버의 첫 번째 프라이빗 IP 주소를 반환해요.

$ consul agent -retry-join "provider=aliyun region=... tag_key=consul tag_value=... access_key_id=... access_key_secret=..."

{
  "retry_join": [
    "provider=aliyun region=... tag_key=consul tag_value=... access_key_id=... access_key_secret=..."
  ]
}

provider (필수) - 프로바이더의 이름 (이 경우 "aliyun")
region (필수) - 리전의 이름
tag_key (필수) - 자동 합류할 태그의 키
tag_value (필수) - 자동 합류할 태그의 값
access_key_id (필수) - 인증에 사용할 접근 키
access_key_secret (필수) - 인증에 사용할 시크릿 키

필요한 RAM 권한은 ecs:DescribeInstances예요. 자동 합류에 사용되는 전용 키를 만드는 것을 권장해요.

Digital Ocean

이것은 주어진 tag_name을 가진 주어진 region의 모든 서버의 첫 번째 프라이빗 IP 주소를 반환해요.

$ consul agent -retry-join "provider=digitalocean region=... tag_name=... api_token=..."

{
  "retry_join": ["provider=digitalocean region=... tag_name=... api_token=..."]
}

provider (필수) - 프로바이더의 이름 (이 경우 "digitalocean")
region (필수) - 리전의 이름
tag_name (필수) - 자동 합류할 태그의 값
api_token (필수) - 인증에 사용할 토큰

Openstack

이것은 주어진 tag_key 및 tag_value를 가진 주어진 region의 모든 서버의 첫 번째 프라이빗 IP 주소를 반환해요.

$ consul agent -retry-join "provider=os tag_key=consul tag_value=server user_name=... password=... auth_url=..."

{
  "retry_join": [
    "provider=os tag_key=consul tag_value=server user_name=... password=... auth_url=..."
  ]
}

provider (필수) - 프로바이더의 이름 (이 경우 "os")
tag_key (필수) - 자동 합류할 태그의 키
tag_value (필수) - 자동 합류할 태그의 값
domain_name (선택) - 도메인의 이름
domain_id (선택) - 도메인의 ID
project_id (선택) - 프로젝트(테넌트)의 ID
region (선택) - 리전의 이름
user_name (선택) - 인증에 사용할 사용자 이름
password (선택) - 인증에 사용할 비밀번호
token (선택) - 인증에 사용할 토큰
auth_url (선택) - 인증에 사용할 ID 엔드포인트
insecure (선택) - API 인증서를 확인하지 않을지 여부. 값이 있으면 true를 의미해요.

구성은 환경 변수로도 제공할 수 있어요.

Scaleway

이것은 주어진 tag_name을 가진 주어진 region의 모든 서버의 첫 번째 프라이빗 IP 주소를 반환해요.

$ consul agent -retry-join "provider=scaleway organization=my-org tag_name=consul-server token=... region=..."

{
  "retry_join": [
    "provider=scaleway organization=my-org tag_name=consul-server token=... region=..."
  ]
}

provider (필수) - 프로바이더의 이름 (이 경우 "scaleway")
region (필수) - 리전의 이름
tag_name (필수) - 자동 합류할 태그의 이름
organization (필수) - 인증에 사용할 조직 접근 키 (접근 키와 동일)
token (필수) - 인증에 사용할 토큰

TencentCloud

이것은 주어진 tag_key 및 tag_value를 가진 주어진 region의 모든 서버의 첫 번째 IP 주소를 반환해요.

$ consul agent -retry-join "provider=tencentcloud region=... tag_key=consul tag_value=... access_key_id=... access_key_secret=..."

{
  "retry_join": [
    "provider=tencentcloud region=... tag_key=consul tag_value=... access_key_id=... access_key_secret=..."
  ]
}

provider (필수) - 프로바이더의 이름 (이 경우 "tencentcloud")
region (필수) - TencentCloud 리전
tag_key (필수) - 자동 합류할 태그 키
tag_value (필수) - 자동 합류할 태그 값
address_type (선택) - "private_v4" 또는 "public_v4", 기본값은 "private_v4"예요.
access_key_id (필수) - TencentCloud의 시크릿 ID
access_key_secret (필수) - TencentCloud의 시크릿 키

필요한 권한은 cvm:DescribeInstances예요. Consul 데이터센터 자동 합류에 사용되는 전용 키를 만드는 것을 권장해요.

Joyent Triton

이것은 주어진 tag_key 및 tag_value를 가진 모든 서버의 첫 번째 PrimaryIP 주소를 반환해요.

$ consul agent -retry-join "provider=triton account=testaccount url=https://us-sw-1.api.joyentcloud.com key_id=... tag_key=consul-role tag_value=server"

{
  "retry_join": [
    "provider=triton account=testaccount url=https://us-sw-1.api.joyentcloud.com key_id=... tag_key=consul-role tag_value=server"
  ]
}

provider (필수) - 프로바이더의 이름 (이 경우 "triton")
account (필수) - 계정의 이름
url (필수) - 사용할 Triton API 엔드포인트의 URL
key_id (필수) - 사용할 키 ID
tag_key (선택) - 사용할 인스턴스 태그 키
tag_value (선택) - 사용할 태그 값

vSphere

이것은 주어진 tag_name 및 category_name을 가진 주어진 리전의 모든 서버의 첫 번째 프라이빗 IP 주소를 반환해요.

$ consul agent -retry-join "provider=vsphere category_name=consul-role tag_name=consul-server host=... user=... password=... insecure_ssl=[true|false]"

{
  "retry-join": [
    "provider=vsphere category_name=consul-role tag_name=consul-server host=... user=... password=... insecure_ssl=[true|false]"
  ]
}

provider (필수) - 프로바이더의 이름 (여기서는 "vsphere")
tag_name (필수) - 조회할 태그의 이름
category_name (필수) - 조회할 태그의 카테고리
host (필수) - 연결할 vSphere 서버의 호스트
user (필수) - 연결할 사용자 이름
password (필수) - vSphere에 연결할 사용자의 비밀번호
insecure_ssl (선택) - SSL 인증서 검증을 건너뛸지 여부
timeout (선택) - 디스커버리 컨텍스트 시간 초과 (기본값: 10m)

Packet

이것은 주어진 project 및 auth_token을 가진 모든 서버의 첫 번째 프라이빗 IP 주소(또는 address type의 IP 주소)를 반환해요.

$ consul agent -retry-join "provider=packet auth_token=token project=uuid url=... address_type=..."

{
  "retry-join": [
    "provider=packet auth_token=token project=uuid url=... address_type=..."
  ]
}

provider (필수) - 프로바이더의 이름 (여기서는 "packet")
project (필수) - packet 프로젝트의 UUID
auth_token (필수) - packet의 인증 토큰
url (선택) - packet의 REST URL
address_type (선택) - 이 프로바이더에서 확인할 주소 유형 ("private_v4", "public_v4" 또는 "public_v6". 기본값은 "private_v4")

Linode

이것은 주어진 tag_name을 가진 주어진 region의 모든 서버의 첫 번째 프라이빗 IP 주소를 반환해요.

$ consul agent -retry-join "provider=linode region=us-east tag_name=consul-server"

{
  "retry-join": ["provider=linode region=us-east tag_name=consul-server"]
}

provider (필수) - linode
api_token (필수) - 사용할 Linode API 토큰
region (선택) - 필터링할 Linode 리전
tag_name (선택) - 필터링할 태그 이름
address_type (선택) - 이 프로바이더에서 확인할 주소 유형 ("private_v4", "public_v4" 또는 "public_v6". 기본값은 "private_v4")

변수는 환경 변수로도 제공할 수 있어요:

api_token에는 LINODE_TOKEN

클라우드 프로바이더에 클러스터 자동 합류