본문 바로가기
WIKI 기술 지식 베이스

Docker Standalone에서 Traefik Proxy 설정하기

원문 보기 위키 갱신

출처: Setup Traefik Proxy in Docker Standalone

본문

Docker

이 가이드는 공식 Traefik Docker 이미지와 Docker Compose를 사용해 Docker 컨테이너 안에 Traefik Proxy를 설치하고 구성하는 과정을 깊이 있게 안내해요. 이 가이드에서 다룰 내용은 다음과 같아요:

  • Docker 프로바이더 활성화하기

  • web(HTTP :80)과 websecure(HTTPS :443) 엔트리포인트 노출하기

  • 모든 HTTP 트래픽을 HTTPS로 리다이렉트하기

  • Traefik 대시보드를 basic-auth로 보호하기

  • *.docker.localhost용 자체 서명 인증서로 TLS 종료하기

  • whoami 데모 서비스 배포하기

  • access-logs와 Prometheus 메트릭 활성화하기

사전 요구 사항

  • Docker Desktop / Engine

  • Docker Compose

  • openssl

  • apache2-utils의 htpasswd

자체 서명 인증서 만들기

Traefik이 로컬에서 HTTPS를 제공하려면 먼저 인증서가 필요해요. 프로덕션에서는 신뢰할 수 있는 CA의 인증서를 사용하겠지만, 단일 머신 스택에서는 빠른 자체 서명 인증서로 충분해요. 다음 명령을 실행해 openssl로 만들 수 있어요:

mkdir -p certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout certs/local.key -out certs/local.crt \
  -subj "/CN=*.docker.localhost"

certs 폴더에는 이제 local.crt와 local.key가 들어 있고, 이것들은 Traefik에 읽기 전용으로 마운트돼요.

Traefik 대시보드 자격 증명 만들기

프로덕션에서는 Traefik 대시보드에 어떤 형태의 인증/보안을 두는 것이 좋아요. Traefik은 basic-auth 미들웨어로 보호할 수 있어요. 그러려면 Traefik의 미들웨어가 검증할 해시된 사용자 이름/비밀번호 쌍을 생성하세요:

htpasswd -nb admin "P@ssw0rd" | sed -e 's/\$/\$\$/g'

전체 출력(예: admin:$$apr1$$…)을 복사하세요. 미들웨어 구성에 필요해요.

docker-compose.yaml 만들기

이제 전체 스택을 Compose 파일로 정의하세요. 이 파일은 Traefik을 선언하고, 인증서를 마운트하며, 전용 네트워크를 설정하고, 나중에 whoami 데모 서비스를 호스팅해요.

Note

Docker CLI와 구성 파일로 Traefik을 실행할 수도 있지만, 이 튜토리얼에서는 Docker Compose를 사용할 거예요.

먼저 dynamic 폴더를 만들고 동적 구성용 tls.yaml 파일을 만드세요. TLS 인증서 구성을 파일에 붙여넣으세요:

tls:
  certificates:
    - certFile: /certs/local.crt
      keyFile:  /certs/local.key

프로젝트 루트 폴더(dynamic/tls.yaml 파일의 상위 폴더)에 docker-compose.yaml 파일을 만들고 다음 내용을 포함하세요:

services:
  traefik:
    image: traefik:v3.7
    container_name: traefik
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true

    networks:
     # Connect to the 'traefik_proxy' overlay network for inter-container communication across nodes
      - proxy

    ports:
      - "80:80"
      - "443:443"

    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./certs:/certs:ro
      - ./dynamic:/dynamic:ro

    command:
      # EntryPoints
      - "--entrypoints.web.address=:80"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--entrypoints.web.http.redirections.entrypoint.permanent=true"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.websecure.http.tls=true"

      # Attach the static configuration tls.yaml file that contains the tls configuration settings
      - "--providers.file.filename=/dynamic/tls.yaml"

      # Providers 
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--providers.docker.network=proxy"

      # API & Dashboard 
      - "--api.dashboard=true"
      - "--api.insecure=false"

      # Observability 
      - "--log.level=INFO"
      - "--accesslog=true"
      - "--metrics.prometheus=true"

  # Traefik Dynamic configuration via Docker labels
    labels:
      # Enable self‑routing
      - "traefik.enable=true"

      # Dashboard router
      - "traefik.http.routers.dashboard.rule=Host(`dashboard.docker.localhost`)"
      - "traefik.http.routers.dashboard.entrypoints=websecure"
      - "traefik.http.routers.dashboard.service=api@internal"
      - "traefik.http.routers.dashboard.tls=true"

      # Basic‑auth middleware
      - "traefik.http.middlewares.dashboard-auth.basicauth.users=<PASTE_HASH_HERE>"
      - "traefik.http.routers.dashboard.middlewares=dashboard-auth@docker"

# Whoami application
  whoami:
    image: traefik/whoami
    container_name: whoami
    restart: unless-stopped
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami.rule=Host(`whoami.docker.localhost`)"
      - "traefik.http.routers.whoami.entrypoints=websecure"
      - "traefik.http.routers.whoami.tls=true"

networks:
  proxy:
    name: proxy

Info

  • 앞서 생성한 해시로 를 반드시 교체하세요.

  • --api.insecure=false 플래그는 API를 보호하고 대시보드가 포트 8080에 노출되지 않게 하는 데 사용돼요. HTTPS 라우터로 대시보드를 노출하고 있기 때문이에요.

스택 실행하기

Compose 파일과 보조 자산이 준비되면 컨테이너를 시작하고 Docker가 네트워킹을 알아서 연결하게 하세요:

docker compose up -d

Traefik이 시작되고 command 인자에서 정적 구성을 읽고, Docker 소켓에 연결하며, 동적 구성(대시보드 라우팅과 인증)을 위해 자신의 라벨을 감지하고, 포트 80과 443에서 수신을 시작해요. HTTP 요청은 HTTPS로 리다이렉트돼요.

대시보드 접근하기

이제 Traefik이 배포됐으니 https://dashboard.docker.localhost에서 대시보드에 접근할 수 있고, 구성한 Basic Authentication 자격 증명을 요구할 거예요:

whoami 애플리케이션 테스트하기

curl로 애플리케이션을 테스트할 수 있어요:

curl -k https://whoami.docker.localhost/

Hostname: whoami-76c9859cfc-k7jzs
IP: 127.0.0.1
IP: ::1
IP: 10.42.0.59
IP: fe80::50d7:a2ff:fed5:2530
RemoteAddr: 10.42.0.60:54148
GET / HTTP/1.1
Host: whoami.docker.localhost
User-Agent: curl/8.7.1
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 10.42.0.1
X-Forwarded-Host: whoami.docker.localhost
X-Forwarded-Port: 443
X-Forwarded-Proto: https
X-Forwarded-Server: traefik-644b7c67d9-f2tn9
X-Real-Ip: 10.42.0.1

HTTP 엔트리포인트에 같은 요청을 하면 다음이 반환돼요:

curl -k http://whoami.docker.localhost

Moved Permanently

위 결과는 리다이렉션이 일어났다는 걸 확인해 주며, 즉 우리 설정이 올바르게 동작한다는 뜻이에요.

브라우저를 열고 https://whoami.docker.localhost로 이동해 서비스의 JSON 덤프를 볼 수도 있어요:

Info

https://dashboard.docker.localhost의 Traefik 대시보드로 이동해 라우트가 생성됐는지 확인할 수도 있어요.

기타 주요 구성 영역

이 초기 설정 외에도 Traefik은 광범위한 구성 가능성을 제공해요. Docker Compose command 인자나 labels를 사용한 간단한 소개와 최소 예시를 여기서 다룰게요. 포괄적인 내용은 링크된 메인 문서를 참고하세요.

TLS 인증서 관리 (Let's Encrypt)

websecure 엔트리포인트가 유효한 HTTPS 인증서를 자동으로 제공하게 하려면 Let's Encrypt(ACME)를 활성화하세요.

command 추가 예시:

command:
  # ... other command arguments ...
  - "[email protected]"
  - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json" # Path inside container volume
  - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"

  # - "--certificatesresolvers.le.acme.dnschallenge.provider=your-dns-provider" # Needs provider setup

  # Optionally make 'le' the default resolver for TLS-enabled routers
  - "--entrypoints.websecure.http.tls.certresolver=le"

이것은 le라는 리졸버를 정의하고, 필요한 이메일과 저장 경로(마운트된 /letsencrypt 볼륨 안)를 설정하며, HTTP 챌린지를 활성화해요. 챌린지와 DNS 프로바이더 구성에 대한 자세한 내용은 HTTPS/TLS 문서와 Let's Encrypt 문서를 참고하세요.

메트릭 (Prometheus)

Traefik의 내부 메트릭을 Prometheus로 모니터링하기 위해 노출할 수 있어요. 우리는 이미 설정에서 prometheus를 활성화했지만 더 구성할 수 있어요. command 추가 예시:

command:
  # If using a dedicated metrics entry point, define it:
  - "--entrypoints.metrics.address=:8082"

  # ... other command arguments ...
  - "--metrics.prometheus=true"

  # Optionally change the entry point metrics are exposed on (defaults to 'traefik')
  - "--metrics.prometheus.entrypoint=metrics"

  # Add labels to metrics for routers/services (can increase cardinality)
  - "--metrics.prometheus.addrouterslabels=true"
  - "--metrics.prometheus.addserviceslabels=true"

이것은 /metrics 엔드포인트를 활성화해요(보통 내부 API 포트(보안되지 않으면 기본적으로 8080) 또는 전용 엔트리포인트를 통해 접근). 옵션에 대해서는 Metrics 문서를 참고하세요.

트레이싱 (OTel):

Traefik을 통해 요청을 따라가도록 분산 트레이싱을 활성화할 수 있어요. command 추가 예시:

command:
  # ... other command arguments ...
  - "--tracing.otel=true"
  - "--tracing.otel.grpcendpoint=otel-collector:4317" # Adjust endpoint as needed
  - "--tracing.otel.httpendpoint=otel-collector.observability:4318" # Adjust endpoint as needed

Note

이 옵션은 Traefik이 접근할 수 있는 실행 중인 OTEL 컬렉터가 필요해요. Tracing 문서를 참고하세요.

접근 로그 (Access Logs)

들어오는 요청을 디버깅과 분석을 위해 기록하도록 Traefik을 구성할 수 있어요. command 추가 예시:

command:
  # ... other command arguments ...
  - "--accesslog=true" # Enable access logs to stdout

  # Optionally change format or output file (requires volume)
  - "--accesslog.format=json"
  - "--accesslog.filepath=/path/to/access.log"

  # Optionally filter logs
  - "--accesslog.filters.statuscodes=400-599"

이것은 컨테이너의 표준 출력으로 접근 로그를 활성화해요(docker compose logs로 확인 가능). Access Logs 문서를 참고하세요.

결론

이제 보안 대시보드 접근과 HTTP-to-HTTPS 리다이렉션을 갖춘 기본 Traefik Docker 설정이 완성됐어요.

프로덕션에서 Traefik OSS를 사용 중인가요?

업무에서 Traefik을 사용한다면 엔터프라이즈급 API 게이트웨이 기능이나 Traefik OSS용 상용 지원을 고려해 보세요.

  • API Gateway 데모 영상 보기

  • 24/7/365 OSS 지원 요청하기

Traefik OSS에 API 게이트웨이 기능을 추가하는 건 빠르고 매끄러워요. 대체(rip and replace)가 필요 없고 모든 구성이 그대로 유지돼요. 이 짧은 영상으로 직접 확인해 보세요.

더 알아보기