Traefik TLS 인증서

원문 보기 위키 갱신 2026.10.03

Traefik TLS 인증서 (TLS Certificates)

출처: Traefik TLS Certificates Documentation

본문

TLS Certificates

ℹ️ 정보

라우터가 HTTPS 트래픽을 처리해야 한다면, 라우터 정의에 tls 필드가 지정되어야 해요.

Certificates Definition (인증서 정의)

Automated (자동)

Let's Encrypt 페이지를 참고해 주세요.

User defined (사용자 정의)

TLS 인증서를 추가/제거하려면(이미 Traefik이 실행 중일 때도) 동적 구성의 [[tls.certificates]] 섹션에 정의를 추가할 수 있어요:

Structured (YAML)

tls:
  certificates:
    - certFile: /path/to/domain.cert
      keyFile: /path/to/domain.key
    - certFile: /path/to/other-domain.cert
      keyFile: /path/to/other-domain.key

Structured (TOML)

[[tls.certificates]]
  certFile = "/path/to/domain.cert"
  keyFile = "/path/to/domain.key"

[[tls.certificates]]
  certFile = "/path/to/other-domain.cert"
  keyFile = "/path/to/other-domain.key"

⚠️ 제한

위 예시에서는 file provider를 사용해 이 정의들을 처리했어요. 이는 인증서(옵션과 스토어도 마찬가지)를 구성할 수 있는 유일한 방법이에요. 다만 Kubernetes에서는 인증서를 시크릿(secrets)으로 제공할 수 있고 반드시 그래야 해요.

Certificate selection (SNI) (인증서 선택)

Traefik은 TLS 핸드셰이크 중에 클라이언트가 보낸 Server Name Indication(SNI)을 기반으로 제시할 인증서를 선택해요.

다만 HTTP 라우터 규칙(예: Host())은 TLS가 수립된 후에 평가되므로 인증서 선택에는 영향을 주지 않아요.

엄격한 SNI 검사 기본적으로, 클라이언트가 SNI를 보내지 않거나 요청한 서버 이름과 일치하는 인증서가 없으면, Traefik은 TLS 스토어의 기본 인증서(구성된 경우)로 폴백해요.

기본 인증서로 폴백하는 대신 SNI가 없거나(또는 알 수 없는 서버 이름인) 연결을 거부하려면 TLS Options에서 sniStrict를 활성화해요.

Certificates Stores (인증서 스토어)

Traefik에서 인증서는 인증서 스토어(certificates stores)에 함께 그룹화돼요.

⚠️ 제한

default(이름이 default인 것)가 아닌 다른 스토어 정의는 무시돼요. 따라서 전역적으로 사용 가능한 TLS 스토어는 하나뿐이에요.

Kubernetes의 TLSStore

TLSStore 리소스를 사용하면 default라는 이름의 스토어가 정의된 네임스페이스와 무관하게 모든 엔트리포인트에 적용돼요. defaultTLSResourcesNamespace provider 옵션은 이 클러스터 전역 스토어가 정의될 수 있는 네임스페이스를 제한해요.

tls.certificates 섹션에서는 인증서를 저장할 위치를 나타내는 스토어 목록을 지정할 수 있어요:

Structured (YAML)

tls:
  certificates:
    - certFile: /path/to/domain.cert
      keyFile: /path/to/domain.key
      stores:
        - default
    # Note that since no store is defined,
    # the certificate below will be stored in the `default` store.
    - certFile: /path/to/other-domain.cert
      keyFile: /path/to/other-domain.key

Structured (TOML)

[[tls.certificates]]
  certFile = "/path/to/domain.cert"
  keyFile = "/path/to/domain.key"
  stores = ["default"]

[[tls.certificates]]
  # Note that since no store is defined,
  # the certificate below will be stored in the `default` store.
  certFile = "/path/to/other-domain.cert"
  keyFile = "/path/to/other-domain.key"

⚠️ 제한

stores 목록은 실제로 무시되고 자동으로 ["default"]로 설정돼요.

Provider별 예시

Docker: Enable TLS 문서 참고
Swarm: Enable TLS 문서 참고
Kubernetes: Enable TLS 문서 참고

Default Certificate (기본 인증서)

Traefik은 SNI가 없거나 일치하는 도메인이 없는 연결에 대해 기본 인증서를 사용할 수 있어요. 이 기본 인증서는 TLS 스토어에 정의되어야 해요:

Structured (YAML)

tls:
  stores:
    default:
      defaultCertificate:
        certFile: path/to/cert.crt
        keyFile: path/to/cert.key

Structured (TOML)

[tls.stores]
  [tls.stores.default]
    [tls.stores.default.defaultCertificate]
      certFile = "path/to/cert.crt"
      keyFile  = "path/to/cert.key"

defaultCertificate가 제공되지 않으면 Traefik은 생성된 인증서를 사용해요.

ACME Default Certificate (ACME 기본 인증서)

Traefik이 기본 인증서를 생성하도록 ACME provider(예: Let's Encrypt)를 사용하게 구성할 수 있어요. 기본 인증서를 해석하기 위한 구성은 TLS 스토어에 정의되어야 해요:

defaultGeneratedCert 옵션과의 우선순위

defaultGeneratedCert 정의는 ACME 기본 인증서 구성보다 우선해요.

Structured (YAML)

tls:
  stores:
    default:
      defaultGeneratedCert:
        resolver: myresolver
        domain:
          main: example.org
          sans:
            - foo.example.org
            - bar.example.org

Structured (TOML)

[tls.stores]
  [tls.stores.default.defaultGeneratedCert]
    resolver = "myresolver"
    [tls.stores.default.defaultGeneratedCert.domain]
      main = "example.org"
      sans = ["foo.example.org", "bar.example.org"]

Labels

labels:
  - "traefik.tls.stores.default.defaultgeneratedcert.resolver=myresolver"
  - "traefik.tls.stores.default.defaultgeneratedcert.domain.main=example.org"
  - "traefik.tls.stores.default.defaultgeneratedcert.domain.sans=foo.example.org, bar.example.org"

더 알아보기 (Learn more)

Traefik 공식 문서