개요
- k8s Ingress Annotation
- k8s Ingress 어노테이션
- Ingress 리소스에 부가 동작을 지시하는 어노테이션 키-값 메타데이터
- 대부분 컨트롤러 구현체별(예: NGINX, AWS Load Balancer Controller, GCE, Traefik)로 정의되며, 표준 스펙 필드로 대체되는 경우도 있다.
- 레이블과 달리 셀렉터 대상이 아니며(질의용 아님), 주로 라우팅/보안/백엔드 연결/헤더 가공/헬스체크 등의 세부 동작을 조정한다.
컨트롤러별 예시
NGINX Ingress Controller
| 어노테이션 키 | 설명 | 값 예시 |
|---|---|---|
| nginx.ingress.kubernetes.io/rewrite-target | 경로 재작성(Target Path) | / |
| nginx.ingress.kubernetes.io/ssl-redirect | HTTP→HTTPS 리다이렉트 강제 | "true" |
| nginx.ingress.kubernetes.io/force-ssl-redirect | 클라이언트 스킴과 무관하게 HTTPS 강제 | "true" |
| nginx.ingress.kubernetes.io/proxy-body-size | 업로드/바디 최대 크기 | 10m |
| nginx.ingress.kubernetes.io/proxy-read-timeout | 백엔드 응답 대기 시간 | "60" |
| nginx.ingress.kubernetes.io/backend-protocol | 백엔드와 통신 프로토콜 지정 | "HTTP" / "HTTPS" / "GRPC" |
| nginx.ingress.kubernetes.io/configuration-snippet | 서버/로케이션 블록에 NGINX 스니펫 삽입. 멀티테넌트 환경에서 보안상 주의. | |
| nginx.ingress.kubernetes.io/whitelist-source-range | 클라이언트 소스 IP 허용 범위 | 1.2.3.0/24,10.0.0.0/8 |
| nginx.ingress.kubernetes.io/enable-cors | CORS 활성화 | "true" |
| nginx.ingress.kubernetes.io/cors-allow-origin | CORS Origin 허용 | https://example.com |
AWS Load Balancer Controller (ALB)
| 어노테이션 키 | 설명 | 값 예시 |
|---|---|---|
| alb.ingress.kubernetes.io/scheme | 로드밸런서 스킴 | internet-facing / internal |
| alb.ingress.kubernetes.io/target-type | Target 유형 | instance / ip |
| alb.ingress.kubernetes.io/listen-ports | 리스너 포트/프로토콜 | '[{"HTTP":80},{"HTTPS":443}]' |
| alb.ingress.kubernetes.io/certificate-arn | HTTPS 인증서(ARN) | arn:aws:acm:... |
| alb.ingress.kubernetes.io/healthcheck-path | 헬스체크 경로 | /healthz |
| alb.ingress.kubernetes.io/load-balancer-attributes | 세부 속성(IdleTimeout 등) | idle_timeout.timeout_seconds=60 |
GCE / GKE (L7)
| 어노테이션 키 | 설명 | 값 예시 |
|---|---|---|
| kubernetes.io/ingress.allow-http | HTTP 허용 여부 | "false" |
| networking.gke.io/managed-certificates | GKE Managed Certificate 리소스 연결 | my-cert |
| networking.gke.io/ssl-pre-shared-cert | 사전공유 SSL 인증서 | my-precert |
Traefik
| 어노테이션 키 | 설명 | 값 예시 |
|---|---|---|
| traefik.ingress.kubernetes.io/router.entrypoints | 엔트리포인트 | web,websecure |
| traefik.ingress.kubernetes.io/router.tls | TLS 활성화 | "true" |
| traefik.ingress.kubernetes.io/router.middlewares | 미들웨어 체인 | ns-auth@kubernetescrd |
사용 예시
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: demo
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /
nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
ingressClassName: nginx
tls:
- hosts: [ "demo.example.com" ]
secretName: demo-tls
rules:
- host: demo.example.com
http:
paths:
- path: /app
pathType: Prefix
backend:
service:
name: demo-svc
port:
number: 8080