Traefik Consul Catalog 문서

원문 보기 위키 갱신 2026.10.03

Traefik Consul Catalog 문서 (Traefik Consul Catalog Documentation)

출처: Traefik Consul Catalog Documentation

본문

Traefik & Consul Catalog

설정 예시 (Configuration Example)

아래처럼 Consul Catalog 프로바이더를 활성화할 수 있어요:

파일 (YAML)

providers:
  consulCatalog: {}

파일 (TOML)

[providers.consulCatalog]

CLI

--providers.consulcatalog=true

서비스에 태그를 붙이려면:

- traefik.http.routers.my-router.rule=Host(`example.com`)

설정 옵션 (Configuration Options)

| 필드 (Field) | 설명 (Description) | 기본값 (Default) | 필수 (Required) | | providers.providersThrottleDuration | 설정 리로드 후, 새 설정 갱신(refresh) 이벤트를 반영하기 전에 기다리는 최소 시간이에요. 이 시간 안에 여러 이벤트가 발생하면 가장 최근 것만 반영되고 나머지는 버려져요. 이 옵션은 프로바이더별로 설정할 수 없지만, 스로틀링 알고리즘은 각 프로바이더에 독립적으로 적용돼요. | 2s | 아니오 (No) | | providers.consulCatalog.refreshInterval | 폴링 간격을 정의해요. | 15s | 아니오 (No) | | providers.consulCatalog.prefix | Traefik 라벨을 정의하는 Consul Catalog 태그의 접두사(prefix)를 정의해요. | traefik | 아니오 (No) | | providers.consulCatalog.requireConsistent | 읽기를 완전히 일관되게 강제해요. 자세한 내용은 여기를 참고하세요. | false | 아니오 (No) | | providers.consulCatalog.exposedByDefault | Consul Catalog 서비스를 기본적으로 Traefik을 통해 노출해요. false로 설정하면 traefik.enable=true 태그가 없는 서비스는 결과 라우팅 설정에서 제외돼요. 추가 정보는 여기를 참고하세요. | true | 아니오 (no) | | providers.consulCatalog.defaultRule | 모든 서비스의 기본 Host 규칙이에요. 자세한 내용은 여기를 참고하세요. | "Host({{ normalize .Name }})" | 아니오 (No) | | providers.consulCatalog.connectAware | Consul Connect 지원을 활성화해요. true로 설정하면 Traefik이 Connect 서비스와 통신할 수 있게 돼요. | false | 아니오 (No) | | providers.consulCatalog.connectByDefault | 기본적으로 모든 서비스를 Connect 지원 가능으로 간주해요. true로 설정하면 Traefik이 모든 Consul Catalog 서비스를 기본적으로 Connect 지원 가능으로 봐요. 이 옵션은 traefik.consulcatalog.connect 태그로 인스턴스별로 덮어쓸 수 있어요. | false | 아니오 (No) | | providers.consulCatalog.serviceName | Consul Catalog에서 Traefik 서비스의 이름을 정의해요. | "traefik" | 아니오 (No) | | providers.consulCatalog.constraints | Traefik이 컨테이너 라벨과 대조해 해당 컨테이너에 라우트를 만들지 결정하는 식(expression)을 정의해요. 자세한 내용은 여기를 참고하세요. | "" | 아니오 (No) | | providers.consulCatalog.namespaces | 조회할 네임스페이스를 정의해요. 자세한 내용은 여기를 참고하세요. | "" | 아니오 (no) | | providers.consulCatalog.stale | Traefik이 카탈로그 읽기에 stale 일관성을 사용하도록 지시해요. | false | 아니오 (no) | | providers.consulCatalog.cache | Traefik이 카탈로그 읽기에 로컬 에이전트 캐싱을 사용하도록 지시해요. | false | 아니오 (no) | | providers.consulCatalog.endpoint | Consul 서버 끝점(endpoint)을 정의해요. | - | 아니오 (No) | | providers.consulCatalog.endpoint.address | Consul 서버의 주소를 정의해요. | 127.0.0.1:8500 | 아니오 (no) | | providers.consulCatalog.endpoint.scheme | Consul 서버의 URI 스킴을 정의해요. | "" | 아니오 (no) | | providers.consulCatalog.endpoint.datacenter | 사용할 데이터센터를 정의해요. Traefik에서 제공하지 않으면 Consul이 기본 에이전트 데이터센터를 사용해요. | "" | 아니오 (no) | | providers.consulCatalog.endpoint.token | 에이전트의 기본 토큰을 덮어쓰는 요청별 ACL 토큰을 정의해요. | "" | 아니오 (no) | | providers.consulCatalog.endpoint.endpointWaitTime | watch가 블록될 수 있는 시간을 정의해요. 제공하지 않으면 에이전트 기본값이 사용돼요. | "" | 아니오 (no) | | providers.consulCatalog.endpoint.httpAuth | HTTP Basic Authentication을 사용하는 HTTP 클라이언트의 인증 설정을 정의해요. | N/A | 아니오 (no) | | providers.consulCatalog.endpoint.httpAuth.username | HTTP Basic Authentication에 사용할 사용자 이름을 정의해요. | "" | 아니오 (no) | | providers.consulCatalog.endpoint.httpAuth.password | HTTP Basic Authentication에 사용할 비밀번호를 정의해요. | "" | 아니오 (no) | | providers.consulCatalog.strictChecks | 트래픽을 받을 수 있는 Consul 서비스 헬스 체크를 정의해요. | ["passing", "warning"] | 아니오 (no) | | providers.consulCatalog.endpoint.tls.ca | Consul Catalog와의 보안 연결에 사용하는 인증 기관의 경로로, 기본값은 시스템 번들이에요. | "" | 아니오 (No) | | providers.consulCatalog.endpoint.tls.cert | Consul Catalog와의 보안 연결에 사용하는 공개 인증서의 경로예요. 이 옵션을 사용할 때는 key 옵션을 설정해야 합니다. | "" | 예 (Yes) | | providers.consulCatalog.endpoint.tls.key | Consul Catalog와의 보안 연결에 사용하는 개인 키의 경로예요. 이 옵션을 사용할 때는 cert 옵션을 설정해야 합니다. | "" | 예 (Yes) | | providers.consulCatalog.endpoint.tls.insecureSkipVerify | TLS 연결을 맺을 때 인증서가 커버하는 호스트명과 관계없이 Consul Catalog가 제시하는 어떤 인증서든 수락하도록 프로바이더에 지시해요. | false | 아니오 (No) | | providers.consulCatalog.watch | true로 설정하면 Consul 변경을 감시해요 (Consul watches checks). | false | 아니오 (No) |

requireConsistent

읽기를 완전히 일관되게 강제해요. 이 옵션은 추가 왕복(round-trip) 때문에 비용이 들 수 있지만, stale 읽기를 막아줘요.

자세한 내용은 일관성에 관한 Consul 문서를 참고하세요.

defaultRule

모든 서비스의 기본 host 규칙이에요.

주어진 서비스에 대해 태그로 라우팅 규칙이 정의되지 않았다면, 대신 이 defaultRule로 정의돼요. defaultRule은 유효한 Go 템플릿이어야 하며, sprig 템플릿 함수를 포함할 수 있어요. 서비스 이름은 Name 식별자로 접근할 수 있고, 템플릿은 이 서비스에 정의된 모든 라벨(즉 prefix로 시작하는 태그)에 접근할 수 있어요.

이 옵션은 traefik.http.routers.{name-of-your-choice}.rule 태그로 인스턴스별로 덮어쓸 수 있어요.

파일 (YAML)

providers:
  consulCatalog:
    defaultRule: "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
    # ...

파일 (TOML)

[providers.consulCatalog]
  defaultRule = "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
  # ...

CLI

--providers.consulcatalog.defaultRule="Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"

기본 규칙과 Traefik 서비스 (Default rule and Traefik service) Traefik 컨테이너의 노출이 기본 규칙 메커니즘과 결합되면, 자기 자신을 대상으로 하는 라우터가 루프처럼 만들어질 수 있어요. 이 경우 무한 루프를 막기 위해, Traefik은 같은 라우터에서 온 요청이라면 거부하는 내부 미들웨어를 추가해요.

constraints

constraints 옵션은 Traefik이 서비스 태그와 대조해 해당 서비스에 라우트를 만들지 결정하는 식으로 설정할 수 있어요. 어떤 서비스 태그도 식과 일치하지 않으면 해당 서비스에 라우트가 만들어지지 않아요. 식이 비어 있으면 감지된 모든 서비스가 포함돼요.

식 구문은 아래 예시처럼 Tag(tag), TagRegex(tag) 함수와 일반적인 불리언 논리를 기반으로 해요.

Constraints 키 제한 사항 (Constraints key limitations)

traefik.*는 설정용 예약 라벨 네임스페이스라서 커스텀 constraints의 키로 사용할 수 없다는 점에 주의하세요.

Constraints 식 예시 (Constraints Expression Examples)

# Includes only services having the tag `a.tag.name=foo`
constraints = "Tag(`a.tag.name=foo`)"

# Excludes services having any tag `a.tag.name=foo`
constraints = "!Tag(`a.tag.name=foo`)"

# With logical AND.
constraints = "Tag(`a.tag.name`) && Tag(`another.tag.name`)"

# With logical OR.
constraints = "Tag(`a.tag.name`) || Tag(`another.tag.name`)"

# With logical AND and OR, with precedence set by parentheses.
constraints = "Tag(`a.tag.name`) && (Tag(`another.tag.name`) || Tag(`yet.another.tag.name`))"

# Includes only services having a tag matching the `a\.tag\.t.+` regular expression.
constraints = "TagRegex(`a\.tag\.t.+`)"

파일 (YAML)

providers:
  consulCatalog:
    constraints: "Tag(`a.tag.name`)"
    # ...

파일 (TOML)

[providers.consulCatalog]
  constraints = "Tag(`a.tag.name`)"
  # ...

CLI

--providers.consulcatalog.constraints="Tag(`a.tag.name`)"
# ...

추가 정보는 서비스 발견 범위 제한(Restrict the Scope of Service Discovery)을 참고하세요.

namespaces

namespaces 옵션은 consul catalog 서비스가 발견될 네임스페이스를 정의해요. namespaces 옵션을 사용하면 발견된 설정 객체 이름에 아래처럼 접미사가 붙어요:

<resource-name>@consulcatalog-<namespace>

경고 (Warning)

namespaces 옵션은 Namespaces 기능을 제공하는 Consul Enterprise에서만 동작해요.
namespaces 옵션과 namespace 옵션 중 하나만 정의해야 해요.

파일 (YAML)

providers:
  consulCatalog:
    namespaces: 
      - "ns1"
      - "ns2"
    # ...

파일 (TOML)

[providers.consulCatalog]
  namespaces = ["ns1", "ns2"]
  # ...

CLI

--providers.consulcatalog.namespaces=ns1,ns2
# ...

라우팅 설정 (Routing Configuration)

라우팅의 전용 섹션을 참고하세요.

더 알아보기 (Learn more)

Traefik 공식 문서