사용자 정의 Annotations

사용자 정의 Annotations 을 사용하면 Rate Limiting, 캐싱 등과 같은 NGINX의 많은 고급 기능을 지원하도록 Ingress 리소스를 빠르게 확장할 수 있습니다.

목차

1. 사용자 정의 Annotations 이란
2. Annotations 사용
2-1. 병합 가능한 Ingress 리소스가 있는 사용자 정의 Annotations
2-2. 도우미 기능

1. 사용자 정의 Annotations 이란

NGINX Ingress Controller는 NGINX 구성(예: 연결 시간 초과)을 미세 조정하거나 추가 기능(예: JWT 유효성 검사)을 활성화하는 Ingress 리소스에 대한 여러 Annotations을 지원합니다. 전체 Annotations 목록은 여기에서 확인할 수 있습니다.

Annotations은 가장 일반적인 기능 및 사용 사례에 대해서만 제공됩니다. 즉, Annotations을 통해 모든 NGINX 기능 또는 사용자 정의 옵션을 사용할 수 있는 것은 아닙니다. 또한 Annotations을 사용할 수 있더라도 특정 NGINX 기능에 대한 만족스러운 제어 수준을 제공하지 못할 수 있습니다.

사용자 정의 Annotations을 사용하면 일반 Annotations으로 사용할 수 없는 NGINX 기능에 대한 Annotations을 추가할 수 있습니다. 일반 Annotations과 달리 사용자 정의 Annotations을 추가하려면 Ingress Controller Source 코드를 수정할 필요 없이 템플릿만 수정하면 됩니다. 또한 사용자 정의 Annotations을 사용하면 NGINX 구성에서 기능이 구현되는 방식을 완전히 제어할 수 있습니다.

2. Annotations 사용

Ingress Controller는 구성 템플릿을 실행하여 Ingress 리소스에 대한 NGINX 구성을 생성합니다. NGINX 템플릿 또는 NGINX Plus 템플릿을 참조하세요.

사용자 정의 Annotations을 지원하기 위해 템플릿은 이름, Namespace 및 Annotations과 같은 Ingress 리소스에 대한 정보에 액세스할 수 있습니다. Ingress 리소스에 특정 Annotations이 있는지 확인하고 조건부로 여러 NGINX Context(http, server, location 또는 upstream)에 NGINX 구성 지시문을 삽입할 수 있습니다. 또한 Annotations에 설정된 값을 가져올 수 있습니다.

두 개의 사용자 정의 Annotations을 지원하도록 확장된 템플릿에서 다음 발췌문을 고려하십시오.

# This is the configuration for {{$.Ingress.Name}}/{{$.Ingress.Namespace}}

{{if index $.Ingress.Annotations "custom.nginx.org/feature-a"}}
# Insert config for feature A if the annotation is set
{{end}}

{{with $value := index $.Ingress.Annotations "custom.nginx.org/feature-b"}}
# Insert config for feature B if the annotation is set
# Print the value assigned to the annotation: {{$value}}
{{end}}

다음 Ingress 리소스를 고려하고 두 가지 Annotations을 설정하는 방법에 유의하십시오.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  namespace: production
  annotations:
    custom.nginx.org/feature-a: "on"
    custom.nginx.org/feature-b: "512"
spec:
  rules:
  - host: example.com
    . . .

Ingress Controller가 사용자 정의된 템플릿을 사용한다고 가정하면 템플릿 발췌 부분에서 생성된 다음 부분을 포함하는 Ingress 리소스에 대한 구성을 생성합니다.

# This is the configuration for cafe-ingress/default

# Insert config for feature A if the annotation is set



# Insert config for feature B if the annotation is set
# Print the value assigned to the annotation: 512

Notes:

• 사용자 정의 템플릿을 통해 사용자 정의 Annotations을 삽입하도록 템플릿을 사용자 정의할 수 있습니다.
• Ingress Controller는 Go 템플릿을 사용하여 NGINX 구성을 생성합니다. 여기에서 Go 템플릿에 대한 자세한 정보를 읽을 수 있습니다.

사용자 정의 Annotations을 사용하여 NGINX 기능을 구성하는 다음 섹션의 예를 참조하세요.

2-1. 병합 가능한 Ingress 리소스가 있는 사용자 정의 Annotations

Mergeable Ingress 리소스는 여러 Ingress 리소스(하나의 Master와 하나 이상의 Minions)로 구성됩니다. 여기에서 Mergeable Ingress 리소스에 대해 자세히 알아보세요.

Mergeable Ingress 리소스와 함께 사용자 정의 Annotations을 사용하려면 다음 사항에 유의하십시오.

사용자 정의 Annotations은 Master와 Minions에서 사용할 수 있습니다. Minions의 경우 location를 처리할 때만 템플릿에서 액세스할 수 있습니다.

Ingress 템플릿의 어디에서나 $.Ingress에 액세스하면 Master Ingress 리소스를 얻게 됩니다. Minion Ingress 리소스에 액세스하려면 $location.MinionIngress를 사용합니다. 그러나 location을 처리할 때만 사용할 수 있습니다.

{{range $location := $server.Locations}}
location {{$location.Path}} {
    {{with $location.MinionIngress}}
    # location for minion {{$location.MinionIngress.Namespace}}/{{$location.MinionIngress.Name}}
    {{end}}
    . . .
} {{end}}

Note: $location.MinionIngress는 포인터입니다. 템플릿에서 일반 Ingress 리소스를 처리할 때 포인터의 값은 nil입니다. 따라서 with 작업을 사용하는 위의 예에서와 같이 $location.MinionIngress가 nil이 아닌지 확인하는 것이 중요합니다.

Minions은 Master의 사용자 정의 Annotations을 내재하지 않습니다.

2-2. 도우미 기능

도우미 기능은 Ingress 템플릿에서 사용자 정의 Annotations의 값을 구문 분석하는 데 사용할 수 있습니다.

Function	Input Arguments	Return Arguments	Description
split	s, sep string	[]string	문자열을 sep로 구분하여 분할합니다.
trim	s string	string	문자열 s에서 앞, 뒤 공백을 제거합니다.

쉼표로 구분된 IP 주소 목록을 예상하는 다음 사용자 정의 Annotations custom.nginx.org/allowed-ips를 고려하십시오.

annotations:
  custom.nginx.org/allowed-ips: "192.168.1.3, 10.0.0.13"

도우미 기능은 custom.nginx.org/allowed-ips Annotations의 값을 구문 분석할 수 있으므로 템플릿에서 각 IP 주소를 개별적으로 사용할 수 있습니다. 다음 템플릿 발췌를 고려하십시오.

{{range $ip := split (index $.Ingress.Annotations "custom.nginx.org/allowed-ips") ","}}
    allow {{trim $ip}};
{{end}}
deny all;

템플릿 발췌는 다음 구성을 생성합니다.

allow 192.168.1.3;
allow 10.0.0.13;
deny all;

Example