Kubernetes Ingress 라우팅 구성

원문 보기 위키 갱신 2026.10.03

출처: Kubernetes Ingress Routing Configuration

본문

Traefik & Kubernetes with Ingress

라우팅 구성

Kubernetes Ingress 프로바이더는 아래 예시 같은 들어오는 ingress 이벤트를 감시하고, 그로부터 해당하는 동적 구성을 도출하며, 그 결과 라우터, 서비스, 핸들러 등을 만들어내요.

설정 예시

Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myingress
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: web

spec:
  rules:
    - host: example.com
      http:
        paths:
          - path: /bar
            pathType: Exact
            backend:
              service:
                name:  whoami
                port:
                  number: 80
          - path: /foo
            pathType: Exact
            backend:
              service:
                name:  whoami
                port:
                  number: 80

주석(Annotations)

주석에서 리소스 참조하기

주석에서 다른 프로바이더가 정의한 리소스를 참조할 때는 프로바이더 네임스페이스 문법을 사용해야 해요.

Ingress에서

Service에서

| Annotation | Description | Value | | traefik.ingress.kubernetes.io/service.nativelb | Controls, when creating the load-balancer, LB의 하위 요소가 pod IP들인지 아니면 유일한 하위 요소가 Kubernetes Service clusterIP인지 제어해요. To put it more plainly, setting nativelb to true ensures Traefik routes traffic to the Kubernetes Service (using your cluster's networking such as kube-proxy, Cilium, Calico, etc.) and load balancing is handled by Kubernetes itself. If nativelb is set to false, Traefik routes traffic directly to the pods and makes load balancing decisions internally. By default, Traefik reuses the established connections to the backends for performance purposes regardless of the nativelb configuration. However, connection reuse combined with nativelb: true can cause uneven load balancing. If this is unacceptable, you can disable connection reuse by setting maxIdleConnsPerHost to -1. Default: false | "true" | | traefik.ingress.kubernetes.io/service.nodeportlb | 로드 밸런서를 만들 때 서비스 유형이 NodePort인 경우 LB의 하위 요소가 nodePort를 사용하는 노드 내부 IP들인지 제어해요. Traefik이 Kubernetes 클러스터 외부에서 실행되지만 노드와 같은 네트워크에 있을 때 서비스에 도달할 수 있게 해줘요. 기본값: false | "true" | | traefik.ingress.kubernetes.io/service.serversscheme | 기본 스킴을 재정의해요. | h2c | | traefik.ingress.kubernetes.io/service.serverstransport | 자세한 내용은 ServersTransport를 참고하세요. | foobar@file | | traefik.ingress.kubernetes.io/service.passhostheader | Host 헤더를 백엔드로 전달할지 여부를 제어해요. | "true" | | traefik.ingress.kubernetes.io/service.sticky.cookie | 쿠키를 사용한 스티키 세션을 활성화해요. 자세한 내용은 스티키 세션을 참고하세요. | "true" | | traefik.ingress.kubernetes.io/service.sticky.cookie.name | 스티키 세션의 쿠키 이름을 정의해요. 자세한 내용은 스티키 세션을 참고하세요. | foobar | | traefik.ingress.kubernetes.io/service.sticky.cookie.secure | 스티키 세션 쿠키에 Secure 플래그를 설정해요. 자세한 내용은 스티키 세션을 참고하세요. | "true" | | traefik.ingress.kubernetes.io/service.sticky.cookie.samesite | 스티키 세션 쿠키에 SameSite 속성을 설정해요. 자세한 내용은 스티키 세션을 참고하세요. | "none" | | traefik.ingress.kubernetes.io/service.sticky.cookie.domain | 스티키 세션 쿠키에 Domain 속성을 설정해, 쿠키가 전송될 호스트를 정의해요. 자세한 내용은 스티키 세션을 참고하세요. | "foo.com" | | traefik.ingress.kubernetes.io/service.sticky.cookie.httponly | 스티키 세션 쿠키에 HttpOnly 플래그를 설정해요. 자세한 내용은 스티키 세션을 참고하세요. | "true" | | traefik.ingress.kubernetes.io/service.sticky.cookie.maxage | 스티키 세션 쿠키에 Max-Age 속성(초 단위)을 설정해요. 자세한 내용은 스티키 세션을 참고하세요. | 42 | | traefik.ingress.kubernetes.io/service.sticky.cookie.path | 스티키 세션 쿠키에 Path 속성을 설정해, 요청 URL에 있어야 하는 경로를 정의해요. 자세한 내용은 스티키 세션을 참고하세요. | /foobar |

Service 주석과 미들웨어

이 service 주석들은 Kubernetes Service가 Ingress의 백엔드로 사용될 때만 그 Service를 구성해요. ErrorPages 미들웨어처럼 미들웨어가 참조하는 Service에는 적용되지 않아요. 미들웨어의 서비스는 Kubernetes Service에 설정된 주석을 읽지 않는 미들웨어 정의에서 구성되기 때문이에요. 그런 경우 serversTransport 를 설정하려면 미들웨어 정의에 선언하세요.

traefik.ingress.kubernetes.io/service.middlewares 자세한 내용은 서비스 미들웨어를 참고하세요.

traefik.ingress.kubernetes.io/service.middlewares: auth@file,prefix@kubernetescrd

TLS

엔트리 포인트의 HTTP 옵션으로 TLS 활성화하기

TLS는 엔트리 포인트의 HTTP 옵션을 통해 활성화할 수 있어요:

CLI

# Static configuration
--entryPoints.websecure.address=:443
--entryPoints.websecure.http.tls

File (YAML)

# Static configuration
entryPoints:
  websecure:
    address: ':443'
    http:
      tls: {}

File (TOML)

# Static configuration
[entryPoints.websecure]
  address = ":443"

    [entryPoints.websecure.http.tls]

이렇게 하면 이 엔트리 포인트에 연결된 모든 Ingress는 기본적으로 TLS 종료를 가지게 돼요.

엔트리 포인트에서 TLS로 Kubernetes Ingress Controller 구성하기

RBAC

---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: traefik-ingress-controller
rules:
  - apiGroups:
      - ""
    resources:
      - services
      - secrets
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - discovery.k8s.io
    resources:
      - endpointslices
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - extensions
      - networking.k8s.io
    resources:
      - ingresses
      - ingressclasses
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - extensions
      - networking.k8s.io
    resources:
      - ingresses/status
    verbs:
      - update

---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: traefik-ingress-controller
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: traefik-ingress-controller
subjects:
  - kind: ServiceAccount
    name: traefik-ingress-controller
    namespace: default

Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myingress
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: websecure

spec:
  rules:
    - host: example.com
      http:
        paths:
          - path: /bar
            pathType: Exact
            backend:
              service:
                name:  whoami
                port:
                  number: 80
          - path: /foo
            pathType: Exact
            backend:
              service:
                name:  whoami
                port:
                  number: 80

Traefik

apiVersion: v1
kind: ServiceAccount
metadata:
  name: traefik-ingress-controller

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: traefik
  labels:
    app: traefik

spec:
  replicas: 1
  selector:
    matchLabels:
      app: traefik
  template:
    metadata:
      labels:
        app: traefik
    spec:
      serviceAccountName: traefik-ingress-controller
      containers:
        - name: traefik
          image: traefik:v3.7
          args:
            - --entryPoints.websecure.address=:443
            - --entryPoints.websecure.http.tls
            - --providers.kubernetesingress
          ports:
            - name: websecure
              containerPort: 443

---
apiVersion: v1
kind: Service
metadata:
  name: traefik
spec:
  type: LoadBalancer
  selector:
    app: traefik
  ports:
    - protocol: TCP
      port: 443
      name: websecure
      targetPort: 443

Whoami

apiVersion: apps/v1
kind: Deployment
metadata:
  name: whoami
  labels:
    app: traefiklabs
    name: whoami

spec:
  replicas: 2
  selector:
    matchLabels:
      app: traefiklabs
      task: whoami
  template:
    metadata:
      labels:
        app: traefiklabs
        task: whoami
    spec:
      containers:
        - name: whoami
          image: traefik/whoami
          ports:
            - containerPort: 80

---
apiVersion: v1
kind: Service
metadata:
  name: whoami

spec:
  ports:
    - name: http
      port: 80
  selector:
    app: traefiklabs
    task: whoami

주석으로 TLS 활성화하기

Ingress에서 생성된 기본 라우터에서 TLS를 활성화하려면 주석을 통해 구성해야 해요:

traefik.ingress.kubernetes.io/router.tls: "true"

더 많은 옵션은 사용 가능한 주석을 참고하세요.

TLS로 Kubernetes Ingress Controller 구성하기

Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myingress
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: websecure
    traefik.ingress.kubernetes.io/router.tls: "true"

spec:
  rules:
    - host: example.com
      http:
        paths:
          - path: /bar
            pathType: Exact
            backend:
              service:
                name:  whoami
                port:
                  number: 80
          - path: /foo
            pathType: Exact
            backend:
              service:
                name:  whoami
                port:
                  number: 80

인증서 관리

secret 사용하기

Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: foo
  namespace: production

spec:
  rules:
  - host: example.net
    http:
      paths:
      - path: /bar
        pathType: Exact
        backend:
          service:
            name:  service1
            port:
              number: 80
  # Only selects which certificate(s) should be loaded from the secret, in order to terminate TLS.
  # Doesn't enable TLS for that ingress (hence for the underlying router).
  # Please see the TLS annotations on ingress made for that purpose.
  tls:
  - secretName: supersecret

Secret

apiVersion: v1
kind: Secret
metadata:
  name: supersecret

data:
  tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
  tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=

TLS 인증서는 Secrets 객체에서 관리할 수 있어요.

Info

사용자가 제공한 TLS 인증서만 Kubernetes Secrets에 저장할 수 있어요. Let's Encrypt 인증서는 아직 Kubernetes Secrets에서 관리할 수 없어요.

Traefik과 Pod 사이의 통신

Kubernetes 서비스로 직접 라우팅하기

Kubernetes 서비스로 직접 라우팅하려면 Kubernetes Service에 traefik.ingress.kubernetes.io/service.nativelb 주석을 사용할 수 있어요. 이 주석은 로드 밸런서를 만들 때 LB의 하위 요소가 pod IP들인지 아니면 유일한 하위 요소가 Kubernetes Service clusterIP인지 제어해요.

또 다른 방법은 ExternalName 서비스를 사용해 DNS를 통해 Kubernetes 서비스로 요청을 전달하는 거예요. 그러려면 외부 이름 서비스(external name services)를 허용해야 해요.

Traefik은 ingress 사양에 제공된 서비스를 기반으로 엔드포인트 정보를 자동으로 요청해요. Traefik이 엔드포인트(pod)에 직접 연결하지만, TLS 통신이 필요한지 확인하기 위해 여전히 서비스 포트를 확인해요.

Traefik이 pod와 통신할 때 HTTPS를 사용하도록 구성하는 방법은 3가지예요:

ingress 사양에 정의된 서비스 포트가 443인 경우 (pod에서 다른 포트를 사용하려면 여전히 targetPort를 사용할 수 있다는 점에 유의하세요).
ingress 사양에 정의된 서비스 포트 이름이 https 로 시작하는 경우(예: https-api, https-web 또는 그냥 https).
서비스 사양에 traefik.ingress.kubernetes.io/service.serversscheme: https 주석이 포함된 경우.

이 구성 옵션 중 하나라도 있으면 백엔드 통신 프로토콜이 TLS로 간주되고, 자동으로 TLS로 연결해요.

Info

Traefik과 pod 사이의 TLS 통신을 활성화하면, 적절한 신뢰 체인과 IP 주체 이름을 가진 신뢰할 수 있는 인증서가 필요하다는 점에 유의하세요. 그렇게 할 수 없다면 TLS 인증서 검증을 건너뛰어야 할 수도 있어요. 자세한 내용은 insecureSkipVerify TLSOption 설정을 참고하세요.

글로벌 기본 백엔드 Ingress

다음과 같은 Ingress를 만들 수 있어요:

Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: cheese

spec:
  defaultBackend:
    service:
      name: stilton
      port:
        number: 80

이 ingress는 ingress의 글로벌 기본 백엔드(Global Default Backend) 속성을 따릅니다. 이를 통해 사용자는 일치하지 않는 모든 요청을 매칭하는 "기본 라우터(default router)"를 만들 수 있어요.

Info

Traefik의 우선순위 사용 방식 때문에, 이 글로벌 ingress가 다른 ingress와 매칭될 수 있는 요청을 대신 처리하지 않도록 환경의 다른 ingress보다 이 ingress의 우선순위를 낮게 설정해야 할 수도 있어요. 이 글로벌 ingress가 다른 ingress와도 매칭될 수 있는 요청을 처리해버리는 것을 피하려면 말이죠.

이를 위해 Ingress의 주석에서 본 traefik.ingress.kubernetes.io/router.priority 주석을 ingress에 적절히 사용하세요.

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

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

API 게이트웨이 데모 영상 보기
24/7/365 OSS 지원 요청하기

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

더 알아보기 (Learn more)

Traefik 공식 문서