서비스 참조

서비스 참조 (service)

Consul에 서비스를 등록할 때 정의할 수 있는 옵션을 설명하는 참조 문서예요. 서비스 정의의 루트 service 블록에서 형식을 지정하는 방법을 다뤄요.

출처: 문서

본문

이 주제는 Consul에 등록하기 위해 서비스를 정의할 때 사용할 수 있는 옵션을 설명합니다. 사용 방법은 다음 주제를 참조하세요.

구성 모델 (Configuration model)

다음 개요는 루트 service 블록에서 구성을 형식화하는 방법을 보여줍니다.

사양 (Specification)

이 주제는 구성 매개변수에 대한 세부 사항을 제공합니다.

name

서비스에 이름을 지정하는 필수 값입니다. 외부 DNS와의 호환성을 위해 서비스 정의 이름에는 유효한 DNS 레이블을 사용하는 것이 좋습니다. id 매개변수를 지정하지 않으면 이 매개변수의 값이 ID로 사용됩니다.

  • 유형: string
  • 기본값: 없음

id

서비스의 ID를 지정합니다. 같은 노드의 서비스는 고유한 ID를 가져야 합니다. 기본 이름이 다른 서비스와 충돌하면 고유한 값을 지정하는 것을 권장합니다.

  • 유형: string
  • 기본값: name 필드의 값

address

서비스별 IP 주소 또는 호스트 이름을 지정하는 문자열 값입니다. 값을 지정하지 않으면 에이전트 노드의 IP 주소가 기본으로 사용됩니다. 이 매개변수에는 서비스 측 검증이 없습니다.

  • 유형: string
  • 기본값: 에이전트 노드의 IP 주소

port

서비스의 포트 번호를 지정합니다. 서비스 발견성을 개선하려면 포트 번호와 함께 tagged_addresses 매개변수에 주소를 지정하는 것이 좋습니다.

이 필드는 서비스 발견과 서비스 메시 사용 사례 모두에 사용할 수 있습니다. 같은 서비스 정의에서 이 매개변수와 ports 매개변수를 함께 구성할 수 없습니다.

  • 유형: integer
  • 기본값: 에이전트의 포트 번호

ports

여러 포트를 가진 서비스를 Consul 카탈로그에 식별하는 일련의 맵을 지정합니다. 이 필드는 서비스 발견 사용 사례만 지원합니다. 같은 서비스 정의에서 이 매개변수와 port 매개변수를 함께 구성할 수 없습니다.

  • 유형: map

지정하려는 각 포트에 대해 다음 매개변수를 정의합니다:

매개변수 설명 유형 기본값
name 포트에 이름을 지정합니다. 이 값은 Consul DNS로 주소 지정할 수 있습니다. 각 이름은 고유해야 합니다. string 없음
port 서비스가 사용 가능한 숫자 포트를 지정합니다. number 없음
default 하나가 포함되지 않았을 때 포트를 기본값으로 설정합니다. 서비스에 대해 하나 이상의 포트를 기본값으로 설정하지 마세요. boolean false

tagged_address 매개변수가 설정되지 않으면 Consul은 서비스의 address와 서비스에 대해 정의된 default 포트를 사용합니다. 여러 포트를 기본값으로 설정하면 서비스를 등록하려고 할 때 Consul이 오류를 반환합니다.

tags

서비스 수준 레이블을 추가하는 문자열 값 목록을 지정합니다. 태그 값은 Consul에 불투명합니다. 외부 DNS와의 호환성을 위해 서비스 정의 ID에는 유효한 DNS 레이블을 사용하는 것이 좋습니다. 다음 예시에서 서비스는 v2와 primary로 태그됩니다:

tags = ["v2", "primary"]

Consul은 태그를 클러스터 상태를 유지하는 안티 엔트로피(anti-entropy) 메커니즘으로 사용합니다. enable_tag_override 설정으로 서비스의 안티 엔트로피 기능을 비활성화할 수 있으며, 이를 통해 외부 에이전트가 카탈로그의 서비스 태그를 수정할 수 있습니다.

meta

meta 필드는 서비스와 연관된 의미론적 메타데이터를 연결하는 사용자 정의 키-값 쌍을 포함합니다. 다음 요구 사항을 충족하는 최대 64쌍을 지정할 수 있습니다:

  • 키와 값은 문자열이어야 합니다.
  • 키는 ASCII 문자(A-Z, a-z, 0-9, _, -)만 포함할 수 있습니다.
  • 키는 특수 문자를 가질 수 없습니다.
  • 키는 128자로 제한됩니다.
  • 값은 512자로 제한됩니다.

다음 예시에서 env 키가 prod로 설정됩니다:

meta = {
  env = "prod"
}

{
  "meta" : {
    "env" : "prod"
  }
}

tagged_addresses

tagged_address 필드는 노드 또는 서비스에 대한 추가 주소를 구성하는 객체입니다. 원격 에이전트와 서비스는 address 필드에 지정된 주소의 대안으로 태그된 주소를 사용해 서비스와 통신할 수 있습니다. 노드 또는 서비스에 대해 여러 주소를 구성할 수 있습니다. 다음 태그가 지원됩니다:

  • lan: 노드 또는 서비스에 접근할 수 있는 IPv4 LAN 주소.
  • lan_ipv4: 노드 또는 서비스에 접근할 수 있는 IPv4 LAN 주소.
  • lan_ipv6: 노드 또는 서비스에 접근할 수 있는 IPv6 LAN 주소.
  • virtual: 주어진 논리적 서비스의 인스턴스에 대한 고정 주소.
  • wan: 원격 데이터 센터에서 다이얼할 때 노드 또는 서비스에 접근할 수 있는 IPv4 WAN 주소.
  • wan_ipv4: 원격 데이터 센터에서 다이얼할 때 노드 또는 서비스에 접근할 수 있는 IPv4 WAN 주소.
  • wan_ipv6: 원격 데이터 센터에서 다이얼할 때 노드 또는 서비스에 접근할 수 있는 IPv6 WAN 주소.

서비스 정의에서 tagged_address를 구성하지 않으면 Consul은 정의의 address와 port 속성을 사용합니다. ports 매개변수로 다중 포트 서비스를 정의할 때 Consul은 ports.default 매개변수에서 기본값으로 구성된 포트를 사용합니다.

tagged_addresses.lan

서비스 또는 노드에 접근할 수 있는 IPv4 또는 IPv6 LAN 주소와 포트 번호를 지정하는 객체입니다. 다음 필드 중 하나 이상을 지정할 수 있습니다:

  • lan
  • lan_ipv4
  • lan_ipv6

이 필드는 다음 매개변수를 포함합니다:

  • address
  • port

다음 예시에서 redis 서비스는 IPv4 LAN 주소 192.0.2.10:80, IPv6 LAN 주소 [2001:db8:1:2:cafe::1337]:80을 가집니다:

service {
  name = "redis"
  address = "192.0.2.10"
  port = 80
  tagged_addresses {
    lan = {
      address = "192.0.2.10"
      port = 80
    }
    lan_ipv4 = {
      address = "192.0.2.10"
      port = 80
    }
    lan_ipv6 = {
      address = "2001:db8:1:2:cafe::1337"
      port = 80
    }
  }
}

{
  "service": {
    "name": "redis",
    "address": "192.0.2.10",
    "port": 80,
    "tagged_addresses": {
      "lan": {
        "address": "192.0.2.10",
        "port": 80
      },
      "lan_ipv4": {
        "address": "192.0.2.10",
        "port": 80
      },
      "lan_ipv6": {
        "address": "2001:db8:1:2:cafe::1337",
        "port": 80
      }
    }
  }
}

tagged_addresses.virtual

서비스 메시의 다운스트림 서비스가 서비스에 연결하는 데 사용할 수 있는 고정 IP 주소와 포트 번호를 지정하는 객체입니다. virtual 필드는 다음 매개변수를 포함합니다:

  • address
  • port

가상 주소는 네트워크 내에서 라우팅 가능한 IP일 필요가 없습니다. 이는 엄격히 논리적 서비스의 인스턴스에 대한 고정 주소를 제공하는 데 사용되는 컨트롤 플레인 구조입니다. 프록시에서 업스트림 서비스로의 이그레스 연결은 논리적 서비스의 가상 주소가 아니라 개별 서비스 인스턴스의 IP 주소로 이동합니다.

다음 조건이 충족되면 가상 주소에 대한 연결이 서비스의 사용 가능한 인스턴스 간에 로드 밸런싱됩니다:

  1. 다운스트림과 업스트림 서비스 모두에 대해 Transparent proxy가 활성화되어 있습니다.
  2. 업스트림 서비스가 개별 인스턴스를 직접 다이얼(dialed directly)하도록 구성되지 않았습니다.

다음 예시에서 메시의 다운스트림 서비스는 포트 80의 203.0.113.50에서 redis 서비스에 연결할 수 있습니다:

service {
  name = "redis"
  address = "192.0.2.10"
  port = 80
  tagged_addresses {
    virtual = {
      address = "203.0.113.50"
      port = 80
    }
  }
}

{
  "service": {
    "name": "redis",
    "address": "192.0.2.10",
    "port": 80,
    "tagged_addresses": {
      "virtual": {
        "address": "203.0.113.50",
        "port": 80
      }
    }
  }
}

tagged_addresses.wan

원격 데이터센터에서 서비스 또는 노드에 접근할 수 있는 IPv4 또는 IPv6 WAN 주소와 포트 번호를 지정하는 객체입니다. 다음 필드 중 하나 이상을 지정할 수 있습니다:

  • wan
  • wan_ipv4
  • wan_ipv6

이 필드는 다음 매개변수를 포함합니다:

  • address
  • port

다음 예시에서 원격 데이터센터의 서비스나 노드는 198.51.100.200:80 및 [2001:db8:5:6:1337::1eaf]:80에서 redis 서비스에 도달할 수 있습니다:

service {
  name = "redis"
  address = "192.0.2.10"
  port = 80
  tagged_addresses {
    wan = {
      address = "198.51.100.200"
      port = 80
    }
    wan_ipv4 = {
      address = "198.51.100.200"
      port = 80
    }
    wan_ipv6 = {
      address = "2001:db8:5:6:1337::1eaf"
      port = 80
    }
  }
}

{
  "service": {
    "name": "redis",
    "address": "192.0.2.10",
    "port": 80,
    "tagged_addresses": {
      "wan": {
        "address": "198.51.100.200",
        "port": 80
      },
      "wan_ipv4": {
        "address": "198.51.100.200",
        "port": 80
      },
      "wan_ipv6": {
        "address": "2001:db8:5:6:1337::1eaf",
        "port": 80
      }
    }
  }
}

socket_path

서비스 소켓의 경로를 지정하는 문자열 값입니다. 서비스가 Unix 도메인 소켓에서 수신한다면 이 매개변수를 지정해 서비스를 메시에 노출하세요.

  • 유형: string
  • 기본값: 없음

enable_tag_override

서비스의 안티 엔트로피 기능이 활성화되는지 여부를 결정하는 boolean 값입니다. 외부 Consul 에이전트가 Consul 카탈로그의 서비스 태그를 수정하도록 허용하려면 true로 설정합니다. 로컬 Consul 에이전트는 이후 동기화 작업 중에 업데이트된 태그를 무시합니다.

이 매개변수는 로컬에 등록된 서비스에만 적용됩니다. 여러 노드가 같은 name으로 서비스를 등록하면 enable_tag_override 구성과 다른 모든 서비스 구성 항목이 독립적으로 동작합니다.

  • 유형: boolean
  • 기본값: false

checks

checks 블록은 서비스에 대한 헬스 검사를 정의하는 객체 배열을 포함합니다. 헬스 검사는 웹 밸런서가 실패한 노드를 정상적으로 제거하고 데이터베이스가 실패한 보조(secondary)를 교체하는 것 같은 여러 안전 기능을 수행합니다. 헬스 검사 구성에 대한 정보는 Health Check Configuration Reference를 참조하세요.

kind

서비스를 프록시로 식별하고 서비스 메시에서의 역할을 결정하는 문자열 값입니다. 비프록시 서비스 인스턴스에는 kind 매개변수를 구성하지 마세요. 추가 정보는 Consul Service Mesh를 참조하세요.

다음 값을 지정할 수 있습니다:

비서비스 등록 역할의 경우, kind 필드는 service-defaults 같은 구성 항목을 정의할 때 다른 문맥을 가집니다.

proxy

서비스가 서비스 메시에서 프록시로 동작하도록 구성될 때 프록시 구성을 지정하는 객체입니다. 비프록시 서비스 인스턴스에는 proxy 매개변수를 구성하지 마세요. 서비스를 서비스 메시 프록시로 등록하는 방법에 대한 세부 사항은 Service mesh proxies overview를 참조하세요. 정의할 수 있는 프록시 유형에 대한 정보는 kind를 참조하세요.

connect

Consul 서비스 메시 연결을 구성하는 객체입니다. Consul 서비스 메시를 사용할 때만 connect 매개변수 블록을 구성해야 합니다.

다음 표는 connect 블록에 넣을 수 있는 매개변수를 설명합니다:

매개변수 설명 기본값
native 서비스를 네이티브 서비스 메시 프록시로 광고하는 boolean 값입니다. 애플리케이션을 connect API와 통합하려면 이 매개변수를 사용하세요. true로 설정하면 sidecar_service를 구성하지 마세요. false
sidecar_service 서비스에 대한 사이드카 프록시를 정의하는 객체입니다. native가 true로 설정되면 구성하지 마세요. Sidecar service defaults를 참조하세요.

locality (Enterprise)

서비스가 사용 가능한 클라우드 서비스 제공자(CSP)의 리전과 존을 지정하는 구성 맵입니다. Consul이 가장 가까운 물리적 서비스 인스턴스로 트래픽을 라우팅하도록 이 필드를 구성하세요. 서비스는 등록된 Consul 에이전트의 locality 구성을 상속하지만, 재정의가 필요하면 서비스 인스턴스에 대한 locality를 명시적으로 정의할 수 있습니다.

  • 기본값: 없음
  • 데이터 타입: Map
매개변수 설명 데이터 타입 기본값
region Consul 에이전트가 실행되는 리전을 지정합니다. Consul은 이 값을 해당 에이전트에 등록된 서비스에 할당합니다. String 없음
zone Consul 에이전트가 실행되는 가용 영역을 지정합니다. String 없음

weights

서비스의 건강 상태를 기준으로 서비스가 DNS SRV 요청에 응답하는 방식을 구성하는 객체입니다. 구성하면 더 많은 용량을 가진 서비스 인스턴스가 DNS SRV 요청에 응답할 수 있게 합니다. 또한 warning 상태의 검사가 있는 서비스의 부하를 줄입니다.

다음 상태 중 하나 이상을 지정하고 가중치를 나타내는 정수 값을 구성할 수 있습니다:

  • passing
  • warning
  • critical

더 큰 정수 값이 가중치 상태를 높입니다. 서비스는 다음 기본 가중치를 가집니다:

  • "passing" : 1
  • "warning" : 1

critical 상태의 서비스는 기본적으로 DNS 응답에서 제외됩니다. warning 검사가 있는 서비스는 기본적으로 응답에 포함됩니다.

다음 예시에서 passing 상태의 서비스 인스턴스는 DNS SRV 요청에 응답하고, critical 인스턴스도 더 낮은 빈도로 응답할 수 있습니다:

service {
  name = "redis"
  address = "192.0.2.10"
  port = 6379
  weights = {
    passing = 3
    warning = 2
    critical   = 1
  }
}

{
  "service": {
    "name": "redis",
    "address": "192.0.2.10",
    "port": 6379,
    "weights": {
      "passing": 3,
      "warning": 2,
      "critical": 1
    }
  }
}

token

ACL이 활성화될 때 서비스를 등록할 때 제시할 ACL 토큰을 지정하는 문자열 값입니다. 이 토큰은 서비스가 서비스 카탈로그와 상호작용하는 데 필요합니다.

ACL과 네임스페이스가 활성화되면 Consul 클러스터에서 ACL 토큰과 연결된 특정 namespace에 범위가 지정된 서비스를 등록할 수 있습니다.

서비스 정의로 등록된 서비스는 token 필드에 지정된 ACL 토큰과 연결된 네임스페이스를 상속하지 않습니다. 서비스가 ACL 토큰이 범위 지정된 네임스페이스에 등록되도록 하려면 namespace와 token 매개변수를 서비스 정의에 포함해야 합니다.

  • 유형: string
  • 기본값: 없음

namespace

서비스를 등록할 네임스페이스를 지정하는 문자열 값입니다. 추가 정보는 Namespaces를 참조하세요.

  • 유형: string
  • 기본값: 없음

여러 서비스 정의 (Multiple service definitions)

단일 정의 파일의 services 블록에서 여러 서비스를 정의할 수 있습니다. 이를 통해 단일 명령으로 여러 서비스를 등록할 수 있습니다. HTTP API는 services 블록을 지원하지 않음에 유의하세요.

services {
  id = "red0"
  name = "redis"
  tags = [
    "primary"
  ]
  address = ""
  port = 6000
  checks = [
    {
      args = ["/bin/check_redis", "-p", "6000"]
      interval = "5s"
      timeout = "20s"
    }
  ]
}
services {
  id = "red1"
  name = "redis"
  tags = [
    "delayed",
    "secondary"
  ]
  address = ""
  port = 7000
  checks = [
    {
      args = ["/bin/check_redis", "-p", "7000"]
      interval = "30s"
      timeout = "60s"
    }
  ]
}

{
  "services": [
    {
      "id": "red0",
      "name": "redis",
      "tags": [
        "primary"
      ],
      "address": "",
      "port": 6000,
      "checks": [
        {
          "args": ["/bin/check_redis", "-p", "6000"],
          "interval": "5s",
          "timeout": "20s"
        }
      ]
    },
    {
      "id": "red1",
      "name": "redis",
      "tags": [
        "delayed",
        "secondary"
      ],
      "address": "",
      "port": 7000,
      "checks": [
        {
          "args": ["/bin/check_redis", "-p", "7000"],
          "interval": "30s",
          "timeout": "60s"
        }
      ]
    }
  ]
}

예시 정의 (Example definitions)

다음 예시는 가능한 모든 매개변수를 포함하지만, 기본적으로 최상위 service 매개변수와 그 name 매개변수만 필수입니다.

service {
  name = "redis"
  id   = "redis"
  port = 80
  tags = ["primary"]
 
  meta = {
    custom_meta_key = "custom_meta_value"
  }
 
  tagged_addresses = {
    lan = {
      address = "192.168.0.55"
      port    = 8000
    }
 
    wan = {
      address = "198.18.0.23"
      port    = 80
    }
  }
 
  port                = 8000
  socket_path         = "/tmp/redis.sock"
  enable_tag_override = false
 
  checks = [
    {
      args     = ["/usr/local/bin/check_redis.py"]
      interval = "10s"
    }
  ]
 
  kind              = "connect-proxy"
  proxy_destination = "redis"
 
  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 {
      outbound_listener_port = 22500
    }
 
    mesh_gateway = {
      mode = "local"
    }
 
    expose = {
      checks = true
 
      paths = [
        {
          path            = "/healthz"
          local_path_port = 8080
          listener_port   = 21500
          protocol        = "http2"
        }
      ]
    }
  }
 
  connect = {
    native = false
  }
 
  weights = {
    passing = 5
    warning = 1
  }
 
  token     = "233b604b-b92e-48c8-a253-5f11514e4b50"
  namespace = "foo"
}

{
  "service": {
    "id": "redis",
    "name": "redis",
    "tags": ["primary"],
    "address": "",
    "meta": {
      "meta": "for my service"
    },
    "tagged_addresses": {
      "lan": {
        "address": "192.168.0.55",
        "port": 8000
      },
      "wan": {
        "address": "198.18.0.23",
        "port": 80
      }
    },
    "port": 8000,
    "socket_path": "/tmp/redis.sock",
    "enable_tag_override": false,
    "checks": [
      {
        "args": ["/usr/local/bin/check_redis.py"],
        "interval": "10s"
      }
    ],
    "kind": "connect-proxy",
    "proxy_destination": "redis", // Deprecated
    "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": {
        "outbound_listener_port": 22500
      },
      "config": {},
      "upstreams": [],
      "mesh_gateway": {
        "mode": "local"
      },
      "expose": {
        "checks": true,
        "paths": [
          {
            "path": "/healthz",
            "local_path_port": 8080,
            "listener_port": 21500,
            "protocol": "http2"
          }
       ]
      }
    },
    "connect": {
      "native": false,
      "sidecar_service": {},
      "proxy": {  // Deprecated
        "command": [],
        "config": {}
      }
    },
    "weights": {
      "passing": 5,
      "warning": 1
    },
    "token": "233b604b-b92e-48c8-a253-5f11514e4b50",
    "namespace": "foo"
  }
}

다중 포트 서비스 정의 (Multiport service definition)

다음 예시는 ports 매개변수를 사용해 여러 포트를 가진 서비스를 정의합니다. 이 정의는 orders 서비스를 http 포트와 metrics 포트로 등록합니다. 자세한 내용은 Consul Multiport overview를 참조하세요.

service {
  name = "orders"
  id   = "order-service-1"
  ports = [
    {
      name = "http"
      port = 8080
      default = true
    },
    {
      name = "metrics"
      port = 9090
    }
  ]
}

{
  "name": "orders",
  "id" : "order-service-1",
  "ports": [
    {
      "name": "http",
      "port": 8080,
      "default": true
    },
    {
      "name": "metrics",
      "port": 9090,
      "default": false
    }
  ]
}

더 알아보기 (Learn more)