AWS Ingress Annotations 정리

AWS에서는 AWS 로드 밸런서 컨트롤러가 수신 리소스에 대하여 annotations를 사용하여 트래픽을 Kubernetes 서비스로 라우팅하는 ALB(Application Load Balancer)의 동작을 구성하고 관리한다. annotations를 사용하면 SSL, 라우팅 동작, 보안 그룹 등과 같은 설정을 Kubernetes Ingress 리소스 내에서 직접 지정할 수 있다.

LoadBalancer Controller 동작방식

지정된 annotations를 기반으로 ALB, 해당 리스너 및 대상 그룹을 생성하거나 업데이트한다.
상태 확인, 보안 설정, 라우팅 규칙, SSL 인증서 및 정의된 기타 구성을 관리한다.
annotations가 변경되면 컨트롤러는 수동 개입 없이 ALB를 새로운 설정으로 업데이트하므로 Kubernetes 네이티브 리소스를 통해 복잡한 구성을 관리할 수 있다.

Ingress Group

AWS에서 ingress group은 여러 개의 ingress 리소스를 하나의 로드 밸런서(ALB)로 통합하여 관리할 수 있게 해주는 기능이다.
이를 통해 여러 Kubernetes 네임스페이스나 서로 다른 팀의 애플리케이션들이 같은 ALB를 공유하면서도 각기 다른 Ingress 규칙을 설정할 수 있다.
ingress group을 사용하면 네트워크 리소스를 절약하고 관리 효율성을 높일 수 있다.
기본적으로 ingress는 ingress group에 속하지 않으며, ingress는 "implicit IngressGroup" 이며 즉, 독립적인 엔터티로 존재한다.

Ingress Group 이름 설정

`alb.ingress.kubernetes.io/group.name` 어노테이션을 사용하여 그룹 이름을 정의한다.
동일한 그룹 이름을 가진 ingress 리소스는 하나의 ALB를 공유하게 된다.
ingress group에 할당된 ALB는 `ingress.k8s.aws/stack` 는 AWS 태그를 검색하여 찾는다.(리스너 규칙의 태그로 되어있음) 이 태그의 값으로 IngressGroup의 이름을 가지게 된다.
ingress group을 사용하지 않은 리소스들은 태그 값은 `namespace/ingressname` 형식으로 설정한다.
ingress 리소스에 할당된 groupName을 변경하면, Ingress는 기존 그룹에서 새로운 IngressGroup으로 이동하게 되며, 새로운 IngressGroup의 ALB에서 관리된다.
만약 새로운 IngressGroup에 ALB가 없다면, 새로운 ALB가 자동으로 생성된다.
ingress group의 ALB는 ingress group의 이름을 값으로 하는 AWS 태그 `ingress.k8s.aws/ `스택 태그를 검색하여 찾을 수 있다.
example: `alb.ingress.kubernetes.io/group.name: my-team.awesome-group`

Ingress Group 순위 설정

`alb.ingress.kubernetes.io/group.order` 어노테이션을 사용해 순서를 지정할 수 있다.
낮은 숫자의 order 값을 가진 ingress 규칙이 우선 적용되며, 동일한 path나 host에 대해 특정 우선순위를 지정할 수 있다.
example: `alb.ingress.kubernetes.io/group.order: 10`

Ingress Group 예시

아래 예시에서 두 개의 ingress 리소스가 `my-shared-group` 이라는 그룹을 공유하게 되어 하나의 ALB에서 요청을 처리한다.

# Ingress for Service A
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: service-a-ingress
  annotations:
    alb.ingress.kubernetes.io/group.name: "my-shared-group"
    alb.ingress.kubernetes.io/group.order: "10"
spec:
  rules:
    - host: "service-a.example.com"
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: service-a
                port:
                  number: 80

# Ingress for Service B
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: service-b-ingress
  annotations:
    alb.ingress.kubernetes.io/group.name: "my-shared-group"
    alb.ingress.kubernetes.io/group.order: "20"
spec:
  rules:
    - host: "service-b.example.com"
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: service-b
                port:
                  number: 80

• `service-a` 와 `service-b` 가 각각 ingress 그룹 `my-shared-group` 에 속하게 되며, `service-a` 가 order 10으로 우선 적용된다.

Ingress Traffic Listening

listen-ports

ALB가 수신하는 포트를 지정헌다.
Example: `alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}, {"HTTP": 8080}, {"HTTPS": 8443}]'`
IngressGroup 내의 모든 Ingress에 적용되므로 각 Ingress는 고유한 포트를 정의할 수 있으며 규칙은 각 Ingress에 지정된 포트에만 적용된다.
동일한 수신 포트가 IngressGroup 내의 여러 Ingress에 의해 정의된 경우 IngressGroup의 순서에 따라ㅈ적용된다.
기본값: listen-ports 가 지정되지 않은 경우 인증서가 사용되지 않으면 기본값은 {"HTTP": 80} 이고 인증서가 제공되면 `{"HTTPS": 443}` 이다.
경고: 동일한 그룹 내에서는 중복된 로드 밸런서 포트를 가질 수 없다. (예외 : `alb.ingress.kubernetes.io/group.order: 10` 지정
ALB가 그룹의 모든 Ingress에 대해 이러한 설정을 통합하므로 IngressGroup 내 하나의 Ingress에서 listen-ports 를 정의하는 것으로 충분하다.

ssl-redirect

HTTP 트래픽이 리디렉션되는 포트(일반적으로 HTTPS 포트 443)를 지정하여 SSL 리디렉션을 활성화한다.
Example: `alb.ingress.kubernetes.io/ssl-redirect: '443'`
SSL 리디렉션(ssl-redirect)는 IngressGroup에 정의된 경우 그룹 내의 모든 Ingress에 영향을 준다.
SSL 리디렉션이 활성화되면 모든 HTTP listener는 기본적으로 다른 HTTP 규칙을 무시하고 HTTPS로 리디렉션하도록 구성된다.

etc

`alb.ingress.kubernetes.io/ip-address-type`
- ALB가 IPv4 및 IPv6 트래픽 지원을 위해 ipv4 또는 dualstack 을 사용해야 하는지 여부를 지정할 수 있다.
- Example: `alb.ingress.kubernetes.io/ip-address-type: ipv4 or dualstack`
- ipv4: IPv4 주소만 사용하도록 ALB를 구성합니다. 즉, IPv4 트래픽을 독점적으로 처리한다.
- dualstack: ALB가 IPv4 및 IPv6 트래픽을 모두 지원할 수 있다. dualstack 으로 설정된 경우 ALB는 IPv4 및 IPv6 주소를 갖게 되어 두 주소 유형 모두에서 트래픽을 라우팅할 수 있다.

`alb.ingress.kubernetes.io/customer-owned-ipv4-pool`
- Outpost 환경을 사용할 때 ALB에 대한 고객 소유 IPv4 주소 풀을 지정한다.
- 경고: 이 주석은 변경할 수 없다다 이를 변경하거나 제한하려면 Ingress를 다시 생성해야 한다.
- Example: `alb.ingress.kubernetes.io/customer-owned-ipv4-pool: ipv4pool-coip-xxxxxxx`

Ingress Traffic Routing

`alb.ingress.kubernetes.io/load-balancer-name`
- IngressGroup 내의 모든 Ingress는 동일한 load balancer 이름을 사용해야 한다.
- 이름은 32자를 초과할 수 없으며, 초과 시 오류가 발생한다.

`alb.ingress.kubernetes.io/target-type`
- instance 모드는 서비스를 위해 열린 NodePort의 클러스터 내 모든 ec2 인스턴스로 트래픽을 라우팅한다.
- instance 모드 사용시에는 서비스는 반드시 NodePort or Loadbalacner type을 사용해야 한다.
- ip 모드는 모든 트래픽을 pod로 라우팅한다.
- 네트워크 플러그인은 pod IP가 ip 모드를 사용하려면 ENI의 보조 IP 주소를 사용해야 한다.
- amazon-vpc-cni-k8s
- sticky session이 애플리케이션 로드 밸런서와 함께 작동하려면 ip 모드가 필하하다. ip 모드를 사용할 때 서비스 유형은 중요하지 않다.

`alb.ingress.kubernetes.io/target-node-labels`
- 인스턴스 대상 유형의 target group 등록에 포함할 노드를 지정한다.
- Example: `alb.ingress.kubernetes.io/target-node-labels: label1=value1, label2=value2`

`alb.ingress.kubernetes.io/backend-protocol`
- 트래픽을 파드드 라우팅할 때 사용하는 프로토콜을 지정한다.

`alb.ingress.kubernetes.io/backend-protocol-version`
- 트래픽을 포드로 라우팅하는 데 사용되는 애플리케이션 프로토콜을 지정한다. HTTP 또는 HTTPS가 백엔드 프로토콜로 사용될 때만 유효하다.
- Example:
  - `alb.ingress.kubernetes.io/backend-protocol-version: HTTP2`
  - `alb.ingress.kubernetes.io/backend-protocol-version: GRPC`

`alb.ingress.kubernetes.io/actions.${action-name}`
- redirecton 작업과 같이 loadbalancer listener 규칙을 구성하는 방법을 제공한다.
- annotation의 serviceName은 ingress rule의 serviceName과 일칙해야 하며, servicePort는 무조건 use-annotation 을 줘야 한다.

`alb.ingress.kubernetes.io/conditions.${conditions-name}`
- ingress의 호스트/경로 조건 외에 라우팅 조건을 지정하는 방법을 제공한다.
- annotation의 serviceName은 ingress rule의 serviceName과 일칙해야 하며, servicePort는 무조건 `use-annotation` 을 줘야 한다.

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    namespace: default
    name: ingress
    annotations:
      alb.ingress.kubernetes.io/scheme: internet-facing
      alb.ingress.kubernetes.io/actions.rule-path1: >
        {"type":"fixed-response","fixedResponseConfig":{"contentType":"text/plain","statusCode":"200","messageBody":"Host is www.example.com OR anno.example.com"}}
      alb.ingress.kubernetes.io/conditions.rule-path1: >
        [{"field":"host-header","hostHeaderConfig":{"values":["anno.example.com"]}}]
      alb.ingress.kubernetes.io/actions.rule-path2: >
        {"type":"fixed-response","fixedResponseConfig":{"contentType":"text/plain","statusCode":"200","messageBody":"Path is /path2 OR /anno/path2"}}
      alb.ingress.kubernetes.io/conditions.rule-path2: >
        [{"field":"path-pattern","pathPatternConfig":{"values":["/anno/path2"]}}]
      alb.ingress.kubernetes.io/actions.rule-path3: >
        {"type":"fixed-response","fixedResponseConfig":{"contentType":"text/plain","statusCode":"200","messageBody":"Http header HeaderName is HeaderValue1 OR HeaderValue2"}}
      alb.ingress.kubernetes.io/conditions.rule-path3: >
        [{"field":"http-header","httpHeaderConfig":{"httpHeaderName": "HeaderName", "values":["HeaderValue1", "HeaderValue2"]}}]
      alb.ingress.kubernetes.io/actions.rule-path4: >
        {"type":"fixed-response","fixedResponseConfig":{"contentType":"text/plain","statusCode":"200","messageBody":"Http request method is GET OR HEAD"}}
      alb.ingress.kubernetes.io/conditions.rule-path4: >
        [{"field":"http-request-method","httpRequestMethodConfig":{"Values":["GET", "HEAD"]}}]
      alb.ingress.kubernetes.io/actions.rule-path5: >
        {"type":"fixed-response","fixedResponseConfig":{"contentType":"text/plain","statusCode":"200","messageBody":"Query string is paramA:valueA1 OR paramA:valueA2"}}
      alb.ingress.kubernetes.io/conditions.rule-path5: >
        [{"field":"query-string","queryStringConfig":{"values":[{"key":"paramA","value":"valueA1"},{"key":"paramA","value":"valueA2"}]}}]
      alb.ingress.kubernetes.io/actions.rule-path6: >
        {"type":"fixed-response","fixedResponseConfig":{"contentType":"text/plain","statusCode":"200","messageBody":"Source IP is 192.168.0.0/16 OR 172.16.0.0/16"}}
      alb.ingress.kubernetes.io/conditions.rule-path6: >
        [{"field":"source-ip","sourceIpConfig":{"values":["192.168.0.0/16", "172.16.0.0/16"]}}]
      alb.ingress.kubernetes.io/actions.rule-path7: >
        {"type":"fixed-response","fixedResponseConfig":{"contentType":"text/plain","statusCode":"200","messageBody":"multiple conditions applies"}}
      alb.ingress.kubernetes.io/conditions.rule-path7: >
        [{"field":"http-header","httpHeaderConfig":{"httpHeaderName": "HeaderName", "values":["HeaderValue"]}},{"field":"query-string","queryStringConfig":{"values":[{"key":"paramA","value":"valueA"}]}},{"field":"query-string","queryStringConfig":{"values":[{"key":"paramB","value":"valueB"}]}}]
  spec:
    ingressClassName: alb
    rules:
      - host: www.example.com
        http:
          paths:
            - path: /path1
              pathType: Exact
              backend:
                service:
                  name: rule-path1
                  port:
                    name: use-annotation
            - path: /path2
              pathType: Exact
              backend:
                service:
                  name: rule-path2
                  port:
                    name: use-annotation
            - path: /path3
              pathType: Exact
              backend:
                service:
                  name: rule-path3
                  port:
                    name: use-annotation
            - path: /path4
              pathType: Exact
              backend:
                service:
                  name: rule-path4
                  port:
                    name: use-annotation
            - path: /path5
              pathType: Exact
              backend:
                service:
                  name: rule-path5
                  port:
                    name: use-annotation
            - path: /path6
              pathType: Exact
              backend:
                service:
                  name: rule-path6
                  port:
                    name: use-annotation
            - path: /path7
              pathType: Exact
              backend:
                service:
                  name: rule-path7
                  port:
                    name: use-annotation

Ingress Access Control

`alb.ingress.kubernetes.io/scheme`
- AWS Application Load Balancer(ALB)와 함께 Kubernetes Ingress 구성에서 로드 밸런서 Access 유형을 정의하는 데 사용용다. 이 주석은 ALB가 인터넷 연결(퍼블릭)인지 내부(프라이빗)인지 여부를 AWS에 알려준다.
- `internet-facing`: 인터넷을 통해 ALB에 공개적으로 액세스할 수 있도록 한다.
- `internal`: ALB가 VPC 또는 연결된 네트워크 내에서만 액세스 가능하도록 제한하여 비공개로 만든다.

`alb.ingress.kubernetes.io/inbound-cidrs`
- 지정된 IP 범위(CIDR)만 연결하도록 허용하여 ALB에 대한 액세스를 제한한다.
- ALB에 액세스할 수 있는 IP 범위를 제한하여 개인 애플리케이션 또는 내부 리소스에 대한 액세스를 제어하는 데 특히 유용하다.
- Ingress가 IngressGroup의 일부인 경우 inbound-cidrs 주석은 그룹의 모든 Ingress 리소스에 적용된다.
- 그러나 inbound-cidrs 은 해당 Ingress에 정의된 포트에만 적용된다.
- 따라서 여러 인그레스가 동일한 수신 포트를 공유하는 경우 충돌을 방지하려면 해당 인그레스 중 하나에만 inbound-cidrs 을 정의해야 한다.
- Ingress에서 `alb.ingress.kubernetes.io/security-groups` 을 지정하면 `inbound-cidrs` 주석이 무시된다.
- If you do not specify the inbound-cidrs annotation:
  - 0.0.0.0/0 (all IPv4 addresses) will be allowed if the ALB’s IPAddressType is set to ipv4.
  - 0.0.0.0/0 and ::/0 (all IPv4 and IPv6 addresses) will be allowed if the ALB’s IPAddressType is set to dualstack.

`alb.ingress.kubernetes.io/security-groups`
- 로드밸런서에 연결할 보안 그룹을 지정한다.
- 해당 annotation이 없으면 컨트롤러가 자동으로 하나의 보안 그룹을 생성하고 보안 그룹이 로드밸런서에 연결되며 inbound-cidrs 과 security-group-prefix-lists 에 listen-ports 액세스를 허용한다. 또한 Node/Pod 보안 그룹은 이 보안 그룹에서 인바운드 트래픽을 허용하도록 수정한다. 즉, 내가 생성한 보안그룹을 Pod와 Node에 적용하고 싶으면 사용하면 된다.
- Example: `alb.ingress.kubernetes.io/security-groups: sg-xxxx, nameOfSg1, nameOfSg2`

`alb.ingress.kubernetes.io/manage-backend-security-group-rules`
- 보안안그룹을 지정할 때 트래픽 액세스를 위해 컨트롤러가 Node/Pod에 보안 그룹 규칙을 구성할지 여부를 지정한다.
- `alb.ingress.kubernetes.io/security-groups` 을 통해 보안 그룹을 지정한 경우에만 적용된다.
- Example: `alb.ingress.kubernetes.io/manage-backend-security-group-rules: "true"`

실전 예제: Helm 및 JSON 기반 Listener Rule 구성

1. Helm용 annotations values 템플릿

이 템플릿은 Helm chart 내 `values.yaml` 에서 `Ingress annotations` 를 정의하고, 템플릿에선 `.Values.ingress.annotations` 로 사용하는 구조이다.

📄 `values.yaml`

ingress:
  enabled: true
  annotations:
    alb.ingress.kubernetes.io/scheme: internet-facing
    alb.ingress.kubernetes.io/ssl-redirect: '443'
    alb.ingress.kubernetes.io/target-type: ip
    alb.ingress.kubernetes.io/group.name: my-shared-ingress
    alb.ingress.kubernetes.io/group.order: '10'
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}]'
    alb.ingress.kubernetes.io/inbound-cidrs: '0.0.0.0/0'

📄 `templates/ingress.yaml`

metadata:
  name: {{ include "my-chart.fullname" . }}
  annotations:
    {{- with .Values.ingress.annotations }}
    {{- toYaml . | nindent 4 }}
    {{- end }}

활용 팁
`group.name, scheme, target-type` 등은 여러 서비스 간 공통으로 쓰는 경우가 많아, 이를 `global.ingress.annotations 등으로 빼두고 공유하는 패턴도 좋다.

2. 실제 JSON 기반 Listener Rule 조합 샘플 (Actions + Conditions)

이 예시는 `alb.ingress.kubernetes.io/actions.*` 와 `conditions.*` 조합을 활용한 라우팅 제어입니다. 아래는 예시 Ingress 리소스의 일부이다.

annotations:
  alb.ingress.kubernetes.io/actions.redirect-path1: >
    {"type":"redirect","redirectConfig":{"protocol":"HTTPS","port":"443","statusCode":"HTTP_301"}}

  alb.ingress.kubernetes.io/conditions.redirect-path1: >
    [{"field":"path-pattern","pathPatternConfig":{"values":["/redirect/*"]}}]

  alb.ingress.kubernetes.io/actions.fixed-response-path2: >
    {"type":"fixed-response","fixedResponseConfig":{"contentType":"text/plain","statusCode":"200","messageBody":"Blocked Path"}}

  alb.ingress.kubernetes.io/conditions.fixed-response-path2: >
    [{"field":"host-header","hostHeaderConfig":{"values":["block.example.com"]}}]

기능 설명

`/redirect/*` 요청은 HTTPS 443 포트로 리디렉션
`block.example.com` 으로 들어오는 요청은 “Blocked Path” 텍스트로 응답

이 구조는 복잡한 ALB listener rule을 선언형으로 제어하고자 할 때 매우 유용하며, 특히 Helm에서도 동일한 구조로 values.yaml에 정의 후 템플릿으로 주입할 수 있다.

💡 실무 적용 팁 및 추가 자료

Ingress Annotations은 단순히 Kubernetes 리소스 정의에 그치지 않고,

실제 서비스 구성에서의 선언형 인프라 설계 도구로 활용된다.

아래 자료들은 실무에 바로 적용할 수 있는 형태로 정리되어 있어,

팀 단위 운영이나 GitOps 기반 배포 환경에서 특히 유용하다.

첫째, 자주 쓰는 Ingress Annotation 모음 시트를 활용해

Helm values 또는 Kustomize에서 공통적으로 쓰는 키를 정리해두면 좋다.

예를 들어 `alb.ingress.kubernetes.io/ssl-redirect, group.name, target-type, scheme` 같은 항목들을

일괄 관리하면 환경에 따른 일관성을 유지할 수 있다.

둘째, IngressGroup 별 ALB 구성도 예시를 통해 하나의 ALB를

다수의 서비스가 어떻게 공유할 수 있는지를 도식화해두면 설계와 설명이 수월하다.

예를 들어 `service-a, service-b` 가 동일한 ALB를 사용하면서 `group.order` 로

라우팅 우선순위를 나누는 구조를 시각적으로 표현해볼 수 있다.

셋째, 서비스별 ALB, 보안그룹, 트래픽 설정 비교표를 만들어두면

프로젝트별 차이를 한눈에 파악하기 좋다.

특히 `inbound-cidrs, security-groups, scheme, ip-address-type` 등은

서비스의 보안 수준과 노출 범위를 가르는 핵심 포인트이므로 체크리스트화해두면 운영에 큰 도움이 된다.

마지막으로, 실제 서비스에서의 Listener Rule 구성 방식도 정리해두는 것이 좋다.

ALB의 경로 기반 라우팅을 단순 path뿐 아니라 헤더, 쿼리 스트링, IP, 메서드 조합까지

복합 조건으로 구성하는 방식은 고급 트래픽 제어 전략에 해당하며, 많은 실무자들이 적용하고 있는 방식이다.

특히 `alb.ingress.kubernetes.io/actions.rule-pathX 및 conditions.rule-pathX` 와 같은 조합을

JSON으로 구성하여 라우팅 정책을 세분화할 수 있다.

마무리: Ingress Annotations는 선언형 로드밸런싱 전략의 핵심

AWS Ingress Annotations를 잘 활용하면 다음과 같은 이점을 누릴 수 있다.

EKS 네이티브 구성 관리: YAML 기반으로 ALB 설정을 선언형 관리
보안성과 유연성 강화: CIDR/IP 제한, 보안 그룹 지정, SSL 리디렉션
트래픽 제어 및 로직 적용: 경로/호스트/쿼리/헤더 기반 라우팅
운영 비용 절감: IngressGroup을 통한 ALB 통합 운영

단순히 외부에 노출하는 라우팅만 넘어서, 운영 전략에 따라 다양한 트래픽 패턴을 관리하고자 한다면 Annotation의 조합을 익히는 것이 중요하다.

CI/CD 파이프라인과 Helm을 연동한 자동화까지 고려한다면 Annotation 템플릿을 사전에 준비해 두는 것이 효율적이다.

EKS를 중심으로 멀티 서비스, 마이크로서비스를 운영하고 있다면 반드시 Ingress Annotations을 제대로 학습해보세요.
선언적 ALB 설정은 운영 효율성과 보안 모두를 향상시킬 수 있는 무기이다.

Reference

https://github.com/kubernetes-sigs/aws-load-balancer-controller/blob/main/docs/guide/ingress/annotations.md

https://aws.amazon.com/ko/blogs/containers/exposing-kubernetes-applications-part-3-nginx-ingress-controller/

https://github.com/somaz94/DevOps-Engineer/wiki/KR_AWS#2-ingress-group

728x90

'AWS' 카테고리의 다른 글

ALB access Log 활성화 → S3 권한 설정 및 로그 저장 (0)	2024.11.21
AWS Network ACL vs Security Group (0)	2024.11.16
AWS Assume Role이란? (0)	2024.11.04
AWS IRSA(IAM Roles for Service Accounts)란? (0)	2023.05.28
AWS VPC란? (0)	2023.04.07

현재글AWS Ingress Annotations 정리

Somaz의 IT 공부 일지