정책 리소스

정책 리소스를 사용하면 VirtualServer 및 VirtualServerRoute 리소스에 추가할 수 있는 액세스 제어 및 속도 제한(Rate-Limiting)과 같은 기능을 구성할 수 있습니다.

이 문서는 정책 리소스에 대한 참조 문서입니다. 액세스 제어 정책의 예는 GitHub Repo에서 확인할 수 있습니다.

목차
1. 전제 조건
1-1. 정책 사양
1-2. 액세스 제어
1-2-1. 액세스 제어 병합
1-3. 속도 제한
1-3-1. 속도 제한 병합
1-4. 기본 인증
1-4-1. 기본 인증 병합
1-5. JWT
1-5-1. JWT 합병
1-6. 원격으로 JWKS를 사용하는 JWT
1-6-1. JWT 병합
1-7. IngressMTLS
1-7-1. IngressMTLS 병합
1-8. EgressMTLS
1-8-1. EgressMTLS 병합
1-9. OIDC
1-9-1. 전제 조건
1-9-2. Limitations
1-9-3. OIDC 병합
2. 정책 사용
2-1. WAF
2-1-1. WAF 병합
2-2. 정책 적용
2-3. 잘못된 정책
2-4. 검증
2-4-1. 구조 검증
2-4-2. 포괄적 검증

1. 전제 조건

정책은 별도로 생성해야 하는 VirtualServer 및 VirtualServerRoute 리소스와 함께 작동합니다.

1-1. 정책 사양

다음은 서브넷 10.0.0.0/8에서 클라이언트에 대한 액세스를 허용하고 다른 클라이언트에 대한 액세스를 거부하는 정책의 예입니다.

apiVersion: k8s.nginx.org/v1
kind: Policy
metadata:
  name: allow-localhost
spec:
  accessControl:
    allow:
    - 10.0.0.0/8

Field	설명	Type	Required
`accessControl`	클라이언트 IP 주소를 기반으로 하는 액세스 제어 정책입니다.	accessControl	No
`ingressClassName`	정책 리소스를 처리해야 하는 Ingress Controller를 지정합니다.	`string`	No
`rateLimit`	속도 제한 정책은 정의된 Key당 요청 처리 속도를 제어합니다.	rateLimit	No
`basicAuth`	기본 인증 정책은 HTTP 기본 인증 자격 증명을 사용하여 클라이언트 요청을 인증하도록 NGINX를 구성합니다.	basicAuth	No
`jwt`	JWT 정책은 JSON Web Token을 사용하여 클라이언트 요청을 인증하도록 NGINX Plus를 구성합니다.	jwt	No
`ingressMTLS`	IngressMTLS 정책은 클라이언트 인증서 확인을 구성합니다.	ingressMTLS	No
`egressMTLS`	Egress MTLS 정책은 Upstream 인증 및 인증서 확인을 구성했습니다.	egressMTLS	No
`waf`	WAF 정책은 NGINX AppProtect에 대한 WAF 및 로그 구성 정책을 구성합니다.	WAF	No

* 정책은 정확히 하나의 정책을 포함해야 합니다.

1-2. 액세스 제어

액세스 제어 정책은 지정된 IP 주소/서브넷이 있는 클라이언트의 요청을 거부하거나 허용하도록 NGINX를 구성합니다.

예를 들어 다음 정책은 서브넷 10.0.0.0/8의 클라이언트에 대한 액세스를 허용하고 다른 클라이언트에 대한 액세스를 거부합니다.

accessControl:
  allow:
  - 10.0.0.0/8

반대로 아래 정책은 그 반대입니다. 10.0.0.0/8의 클라이언트에 대한 액세스를 거부하고 다른 모든 클라이언트에 대한 액세스를 허용합니다.

accessControl:
  deny:
  - 10.0.0.0/8

Note: 이 기능은 NGINX ngx_http_access_module을 사용하여 구현됩니다. Ingress Controller 액세스 제어 정책은 허용 또는 거부 규칙을 지원하지만 둘 다 지원하지는 않습니다.

Field	설명	Type	Required
`allow`	지정된 네트워크 또는 주소에 대한 액세스를 허용합니다. 예: `192.168.1.1` 또는 `10.1.1.0/16`	`[]string`	No
`deny`	지정된 네트워크 또는 주소에 대한 액세스를 거부합니다. 예: `192.168.1.1` 또는 `10.1.1.0/16`	`[]string`	No

1-2-1. 액세스 제어 병합

VirtualServer/VirtualServerRoute는 여러 액세스 제어 정책을 참조할 수 있습니다. 예를 들어, 여기서는 두 가지 정책을 참조합니다. 각 정책에는 구성된 허용 목록이 있습니다.

policies:
- name: allow-policy-one
- name: allow-policy-two

둘 이상의 액세스 제어 정책을 참조하는 경우 Ingress Controller는 콘텐츠를 단일 허용 목록 또는 단일 거부 목록으로 병합합니다.

아래 예와 같이 허용 및 거부 정책을 모두 참조하는 것은 지원되지 않습니다. 허용 목록과 거부 목록이 모두 참조되는 경우 Ingress Controller는 허용 목록 정책만 사용합니다.

policies:
- name: deny-policy
- name: allow-policy-one
- name: allow-policy-two

1-3. 속도 제한

속도 제한 정책은 요청의 처리 속도를 제한하도록 NGINX를 구성합니다.

예를 들어, 다음 정책은 초당 10개의 요청 비율을 초과하면 단일 IP 주소에서 들어오는 모든 후속 요청을 제한합니다:

rateLimit:
  rate: 10r/s
  zoneSize: 10M
  key: ${binary_remote_addr}

Note: 이 기능은 NGINX ngx_http_limit_req_module을 사용하여 구현됩니다.

Field	설명	Type	Required
`rate`	허용되는 요청 속도입니다. 속도는 초당 요청 수(r/s) 또는 분당 요청 수(r/m)로 지정됩니다.	`string`	Yes
`key`	속도 제한이 적용되는 Key입니다. 텍스트, 변수 또는 이들의 조합을 포함할 수 있습니다. 변수는 `${}`로 둘러싸여 있어야 합니다. 예: `${binary_remote_addr}`. 허용되는 변수는 `$binary_remote_addr`, `$request_uri`, `$url, $http_`, `$args`, `$arg_`, `$cookie_`입니다.	`string`	Yes
`zoneSize`	공유 메모리 영역의 크기입니다. 양수 값만 허용됩니다. 허용되는 접미사는 `k` 또는 `m`이며, 없는 경우 `k`로 간주됩니다.	`string`	Yes
`delay`	지연 매개변수는 과도한 요청이 지연되는 한계를 지정합니다. 설정하지 않으면 모든 초과 요청이 지연됩니다.	`int`	No
`noDelay`	요청이 제한되는 동안 과도한 요청 Delay을 비활성화합니다. 둘 다 설정된 경우 `delay` 을 재정의합니다.	`bool`	No
`burst`	과도한 요청은 그 수가 `burst` 크기를 초과할 때까지 지연되며, 이 경우 요청은 오류와 함께 종료됩니다.	`int`	No
`dryRun`	테스트 실행 모드를 활성화합니다. 이 모드에서는 속도 제한이 실제로 적용되지 않지만 과도한 요청 수는 공유 메모리 영역에서 평소와 같이 계산됩니다.	`bool`	No
`logLevel`	속도 초과로 인해 서버에서 요청 처리를 거부하거나 요청 처리가 지연되는 경우에 대해 원하는 로깅 수준을 설정합니다. 허용되는 값은 `info`, `notice`, `warn` 또는 `error`입니다. 기본값은 `error`입니다.	`string`	No
`rejectCode`	거부된 요청에 대한 응답으로 반환할 상태 코드를 설정합니다. `400~599` 범위에 속해야 합니다. 기본값은 `503`입니다.	`string`	No

VirtualServer 및/또는 해당 VirtualServerRoutes에서 참조되는 각 정책에 대해 Ingress Controller는 limit_req_zone 지시문으로 정의된 단일 속도 제한 영역을 생성합니다. 두 개의 VirtualServer 리소스가 동일한 정책을 참조하는 경우 Ingress Controller는 두 개의 서로 다른 속도 제한 영역(VirtualServer당 하나의 영역)을 생성합니다.

1-3-1. 속도 제한 병합

VirtualServer/VirtualServerRoute는 여러 속도 제한 정책을 참조할 수 있습니다. 예를 들어, 여기서는 두 가지 정책을 참조합니다.

policies:
- name: rate-limit-policy-one
- name: rate-limit-policy-two

둘 이상의 속도 제한 정책을 참조하는 경우 Ingress Controller는 참조된 모든 속도 제한을 사용하도록 NGINX를 구성합니다. 여러 정책을 정의할 때 각각의 추가 정책은 참조된 첫 번째 정책(위 예에서 rate-limit-policy-one)의 dryRun, logLevel 및 rejectCode 매개변수를 상속합니다.

1-4. 기본 인증

기본 인증 정책은 HTTP 기본 인증 체계를 사용하여 클라이언트 요청을 인증하도록 NGINX를 구성합니다.

예를 들어 다음 정책은 HTTP 헤더 인증(Authentication)에 유효한 사용자 username/password 조합을 포함하지 않는 모든 요청을 거부합니다.

basicAuth:
  secret: htpasswd-secret
  realm: "My API"

Note: 이 기능은 NGINX ngx_http_auth_basic_module을 사용하여 구현됩니다.

Field	설명	Type	Required
`secret`	Htpasswd 구성을 저장하는 Kubernetes Secret의 이름입니다. 정책 리소스와 동일한 Namespace에 있어야 합니다. Secret은 `nginx.org/htpasswd` 유형이어야 하며 구성은 `htpasswd` Key 아래의 Secret에 저장되어야 합니다. 그렇지 않으면 Secret이 잘못된 것으로 거부됩니다.	`string`	Yes
`realm`	기본 인증을 위한 영역입니다.	`string`	No

1-4-1. 기본 인증 병합

VirtualServer/VirtualServerRoute는 여러 기본 인증 정책을 참조할 수 있습니다. 그러나 하나만 적용할 수 있습니다. 모든 후속 참조는 무시됩니다. 예를 들어, 여기서는 두 가지 정책을 참조합니다.

policies:
- name: basic-auth-policy-one
- name: basic-auth-policy-two

이 예에서 Ingress Controller는 첫 번째 정책 참조 basic-auth-policy-one의 구성을 사용하고 basic-auth-policy-two를 무시합니다.

1-5. JWT

Note: 이 기능은 NGINX Plus에서만 사용할 수 있습니다.

JWT 정책은 JSON Web Token을 사용하여 클라이언트 요청을 인증하도록 NGINX Plus를 구성합니다.

예를 들어, 다음 정책은 HTTP 헤더 token에 유효한 JWT를 포함하지 않는 모든 요청을 거부합니다.

jwt:
  secret: jwk-secret
  realm: "My API"
  token: $http_token

JWT Claim 및 JOSE 헤더를 Upstream 서버에 전달할 수 있습니다. 예:

action:
  proxy:
    upstream: webapp
    requestHeaders:
      set:
      - name: user
        value: ${jwt_claim_user}
      - name: alg
        value: ${jwt_header_alg}

Action.Proxy의 requestHeaders를 사용하여 NGINX가 Upstream 서버에 전달할 두 헤더의 값을 설정합니다.

${jwt_claim_user} 변수의 값은 JWT의 user Claim입니다. 다른 Claim의 경우 ${jwt_claim_name}을 사용합니다. 여기서 name은 Claim의 이름입니다. 중첩된 Claim 및 마침표(.)를 포함하는 Claim은 지원되지 않습니다. 마찬가지로 ${jwt_header_name}을 사용하십시오. 여기서 name은 헤더의 이름입니다. 이 예에서는 alg 헤더를 사용합니다.

Note: 이 기능은 NGINX Plus ngx_http_auth_jwt_module을 사용하여 구현됩니다.

Field	설명	Type	Required
`secret`	JWK를 저장하는 Kubernetes Secret의 이름입니다. 정책 리소스와 동일한 Namespace에 있어야 합니다. Secret은 `nginx.org/jwk` 유형이어야 하며 JWK는 `jwk` Key 아래의 Secret에 저장되어야 합니다. 그렇지 않으면 Secret이 유효하지 않은 것으로 거부됩니다.	`string`	Yes
`realm`	JWT의 영역입니다.	`string`	Yes
`token`	토큰은 JSON Web Token을 포함하는 변수를 지정합니다. 기본적으로 JWT는 `인증(Authorization)` 헤더에 Bearer Token으로 전달됩니다. JWT는 Cookie 또는 쿼리 문자열의 일부로 전달될 수도 있습니다(예: `$cookie_auth_token`). 허용되는 변수는 `$http_`, `$arg_`, `$cookie_`입니다.	`string`	No

1-5-1. JWT 병합

VirtualServer/VirtualServerRoute는 여러 JWT 정책을 참조할 수 있습니다. 그러나 하나만 적용할 수 있습니다. 모든 후속 참조는 무시됩니다. 예를 들어, 여기서는 두 가지 정책을 참조합니다.

policies:
- name: jwt-policy-one
- name: jwt-policy-two

이 예에서 Ingress Controller는 첫 번째 정책 참조 jwt-policy-one의 구성을 사용하고 jwt-policy-two를 무시합니다.

1-6. 원격으로 JWKS를 사용하는 JWT

Note: 이 기능은 NGINX Plus에서만 사용할 수 있습니다.

JWT 정책은 JSON 웹 토큰을 사용하여 클라이언트 요청을 인증하도록 NGINX Plus를 구성하여 URL(원격 서버 또는 ID 제공자)을 통해 JWT 정책에 대한 Key(JWKS)를 가져올 수 있으므로 IC Pod에 복사하거나 업데이트할 필요가 없습니다.

다음 예제 정책은 ID 제공자에서 가져온 HTTP 헤더에 유효한 JWT를 포함하지 않는 모든 요청을 거부합니다:

jwt:
  realm: MyProductAPI
  token: $http_token
  jwksURI: <uri_to_remote_server_or_idp>
  keyCache: 1h

Note: 이 기능은 ngx_http_auth_jwt_module 아래의 NGINX Plus 지시문 auth_jwt_key_request를 사용하여 구현됩니다.

Field	설명	Type	Required
`jwksURI`	JSON 웹 키 세트를 검색하기 위해 요청을 보낼 원격 URI	`string`	Yes
`keyCache`	`jwksURI`에서 얻은 키의 캐싱을 활성화하고 유효한 만료 시간을 설정합니다.	`string`	Yes
`realm`	JWT의 realm.	`string`	Yes
`token`	Token은 JSON 웹 토큰을 포함하는 변수를 지정합니다. 기본적으로 JWT는 `Authorization` 헤더에서 Bearer Token으로 전달됩니다. JWT는 쿠키 또는 쿼리 문자열의 일부로 전달될 수도 있습니다. 예를 들면 다음과 같습니다. `$cookie_auth_token`. 허용되는 변수는 `$http_`, `$arg_`, `$cookie_`입니다.	`string`	No

1-6-1. JWT 병합

이 동작은 VirtualServer/VirtualServerRoute가 여러 JWT 정책을 참조할 수 있는 로컬 Kubernetes Secret를 사용하는 것과 유사합니다. 그러나 하나만 적용할 수 있으며 다음 모든 후속 참조는 무시됩니다. 예를 들어 여기서는 두 가지 정책을 참조합니다.

두 가지 정책을 참조합니다.

policies:
- name: jwt-policy-one
- name: jwt-policy-two

이 예에서 Ingress Controller는 첫 번째 정책 참조 jwt-policy-one의 구성을 사용하고 jwt-policy-two는 무시합니다.

1-7. IngressMTLS

IngressMTLS 정책은 클라이언트 인증서 확인을 구성합니다.

예를 들어, 다음 정책은 ingress-mtls-secret에 지정된 CA 인증서를 사용하여 클라이언트 인증서를 확인합니다.

ingressMTLS:
  clientCertSecret: ingress-mtls-secret
  verifyClient: "on"
  verifyDepth: 1

IngressMTLS 정책을 참조하는 VirtualServer는 다음을 충족해야 합니다.

TLS Termination을 실행해야 합니다.
VirtualServer spec에서 정책을 참조하십시오. route 또는 VirtualServerRoute subroute에서 IngressMTLS 정책을 참조하는 것은 허용되지 않습니다.

위의 조건이 충족되지 않을 경우 NGINX는 500 상태 코드를 클라이언트에 보냅니다.

인증서를 포함한 클라이언트 인증서 세부 정보를 Upstream 서버에 전달할 수 있습니다. 예:

action:
  proxy:
    upstream: webapp
    requestHeaders:
      set:
      - name: client-cert-subj-dn
        value: ${ssl_client_s_dn} # subject DN
      - name: client-cert
        value: ${ssl_client_escaped_cert} # client certificate in the PEM format (urlencoded)

Action.Proxy의 requestHeaders를 사용하여 NGINX가 Upstream 서버에 전달할 두 헤더의 값을 설정합니다. 클라이언트 인증서 세부 정보를 전달하는 데 사용할 수 있는 ngx_http_ssl_module에서 지원하는 포함된 변수 목록을 참조하세요.

Note: 이 기능은 NGINX ngx_http_ssl_module을 사용하여 구현됩니다.

Field	설명	Type	Required
`clientCertSecret`	CA 인증서를 저장하는 Kubernetes Secret의 이름입니다. 정책 리소스와 동일한 Namespace에 있어야 합니다. Secret은 `nginx.org/ca` 유형이어야 하며 인증서는 `ca.crt` Key 아래의 Secret에 저장되어야 합니다. 그렇지 않으면 Secret이 유효하지 않은 것으로 거부됩니다.	`string`	Yes
`verifyClient`	클라이언트에 대한 확인입니다. 가능한 값은 `'on'`, `'off'`, `'optional'`, `'optional_no_ca'`입니다. 기본값은 `'on'`입니다.	`string`	No
`verifyDepth`	클라이언트 인증서 체인에서 확인 수준을 설정합니다. 기본값은 `1`입니다.	`int`	No

1-7-1. IngressMTLS 병합

VirtualServer는 단일 IngressMTLS 정책만 참조할 수 있습니다. 모든 후속 참조는 무시됩니다. 예를 들어, 여기서는 두 가지 정책을 참조합니다.

policies:
- name: ingress-mtls-policy-one
- name: ingress-mtls-policy-two

이 예에서 Ingress Controller는 첫 번째 정책 참조 ingress-mtls-policy-one의 구성을 사용하고 ingress-mtls-policy-two를 무시합니다.

1-8. EgressMTLS

EgressMTLS 정책은 Upstream 인증 및 인증서 확인을 구성합니다.

예를 들어 다음 정책은 egress-mtls-secret을 사용하여 Upstream 애플리케이션을 인증하고 egress-trusted-ca-secret을 사용하여 애플리케이션의 인증서를 확인합니다.

egressMTLS:
  tlsSecret: egress-mtls-secret
  trustedCertSecret: egress-trusted-ca-secret
  verifyServer: on
  verifyDepth: 2

Note: 이 기능은 NGINX ngx_http_proxy_module을 사용하여 구현됩니다.

Field	설명	Type	Required
`tlsSecret`	TLS 인증서 및 Key를 저장하는 Kubernetes Secret의 이름입니다. 정책 리소스와 동일한 Namespace에 있어야 합니다. 보안 Secret은 `kubernetes.io/tls` 유형이어야 하고, 인증서는 `tls.crt` Key 아래 보안 Secret에 저장해야 하며, Key는 `tls.key` Key 아래에 저장해야 합니다. 그렇지 않으면 보안 Secret이 유효하지 않은 것으로 간주되어 거부됩니다.	`string`	No
`trustedCertSecret`	CA 인증서를 저장하는 Kubernetes Secret의 이름입니다. 정책 리소스와 동일한 Namespace에 있어야 합니다. Secret은 `nginx.org/ca` 유형이어야 하며 인증서는 `ca.crt` Key 아래의 Secret에 저장되어야 합니다. 그렇지 않으면 Secret이 유효하지 않은 것으로 거부됩니다.	`string`	No
`verifyServer`	Upstream HTTPS 서버 인증서 확인을 활성화합니다.	`bool`	No
`verifyDepth`	Proxy된 HTTPS 서버 인증서 체인에서 확인 수준을 설정합니다. 기본값은 `1`입니다.	`int`	No
`sessionReuse`	Upstream에 SSL 세션을 재사용할 수 있습니다. 기본값은 `true`입니다.	`bool`	No
`serverName`	`Server Name Indication` 확장을 통해 서버 이름을 전달할 수 있습니다.	`bool`	No
`sslName`	Upstream HTTPS 서버의 인증서를 확인하는 데 사용되는 서버 이름을 재정의할 수 있습니다.	`string`	No
`ciphers`	Upstream HTTPS 서버에 대한 요청에 대해 활성화된 암호를 지정합니다. 기본값은 `DEFAULT`입니다.	`string`	No
`protocols`	Upstream HTTPS 서버에 대한 요청에 대한 프로토콜을 지정합니다. 기본값은 `TLSv1 TLSv1.1 TLSv1.2`입니다.	`string`	No

1-8-1. EgressMTLS 병합

VirtualServer/VirtualServerRoute는 여러 EgressMTLS 정책을 참조할 수 있습니다. 그러나 하나만 적용할 수 있습니다. 모든 후속 참조는 무시됩니다. 예를 들어 여기서는 두 가지 정책을 참조합니다.

policies:
- name: egress-mtls-policy-one
- name: egress-mtls-policy-two

이 예에서 Ingress Controller는 첫 번째 정책 참조 egress-mtls-policy-one의 구성을 사용하고 egress-mtls-policy-two는 무시합니다.

1-9. OIDC

기능 상태: 이 기능은 기본적으로 비활성화되어 있습니다. 활성화하려면 Ingress Controller의 enable-oidc command-line를 설정합니다.

OIDC 정책은 NGINX Plus를 OpenID Connect 인증을 위한 Relying Party로 구성합니다.

예를 들어 다음 정책은 클라이언트 ID nginx-plus 및 클라이언트 Secret oidc-secret을 사용하여 OpenID Connect 공급자 https://idp.example.com으로 인증합니다.

spec:
  oidc:
    clientID: nginx-plus
    clientSecret: oidc-secret
    authEndpoint: https://idp.example.com/openid-connect/auth
    tokenEndpoint: https://idp.example.com/openid-connect/token
    jwksURI: https://idp.example.com/openid-connect/certs

NGINX Plus는 인증된 사용자의 ID를 HTTP 헤더 username의 Backend로 전달합니다.

Note: 이 기능은 NGINX Plus의 참조 구현을 OpenID Connect 인증을 위한 Relying Party로 사용하여 구현됩니다.

1-9-1. 전제 조건

OIDC를 사용하려면 영역 동기화를 활성화해야 합니다. 영역 동기화를 설정하지 않으면 NGINX Plus가 Reload되지 않습니다. 또한 NGINX Plus가 IDP 인증 Endpoint를 확인하는 데 사용할 확인자를 구성해야 합니다. GitHub Repo에서 예제 구성을 찾을 수 있습니다.

Note: 예제의 구성은 TLS를 활성화하지 않으며 복제본 간의 동기화는 일반 텍스트로 발생합니다. 이로 인해 Token이 노출될 수 있습니다.

1-9-2. Limitations

OIDC 정책은 사용자 정의할 수 없는 몇 가지 내부 위치를 정의합니다. /_jwks_uri, /_token, /_refresh, /id_token_validation, /logout, /_logout. 또한 아래 설명된 바와 같이 /_codexch는 리다이렉션 URI의 기본값이지만 사용자 정의할 수 있습니다. VirtualServer 또는 VirtualServerRoute에서 이러한 위치 중 하나를 경로로 지정하면 충돌이 발생하고 NGINX Plus가 Reload되지 않습니다.

Field	설명	Type	Required
`clientID`	OpenID Connect 공급자가 제공한 클라이언트 ID입니다.	`string`	Yes
`clientSecret`	OpenID Connect 제공자가 제공한 클라이언트 Secret을 저장하는 Kubernetes Secret의 이름입니다. 정책 리소스와 동일한 Namespace에 있어야 합니다. Secret은 `nginx.org/oidc` 유형이어야 하고 `client-secret` Key 아래의 Secret이어야 합니다. 그렇지 않으면 Secret이 유효하지 않은 것으로 거부됩니다.	`string`	Yes
`authEndpoint`	OpenID Connect 공급자가 제공한 권한 부여 Endpoint의 URL입니다.	`string`	Yes
`tokenEndpoint`	OpenID Connect 공급자가 제공한 Token Endpoint의 URL입니다.	`string`	Yes
`jwksURI`	OpenID Connect 공급자가 제공한 JSON Web Key Set (JWK) 문서의 URL입니다.	`string`	Yes
`scope`	OpenID Connect 범위 목록입니다. 가능한 값은 `openid`, `profile`, `email`, `address`, `phone`입니다. scope `openid`는 항상 있어야 하며 다른 항목은 `+` 기호로 연결하여 추가할 수 있습니다(예: `openid+profile+email`). 기본값은 `openid`입니다.	`string`	No
`redirectURI`	기본 리다이렉션 URI 재정의를 허용합니다. 기본값은 `/_codexch`입니다.	`string`	No
`zoneSyncLeeway`	Ingress Controller Pod 간에 ID Token 및 공유 값을 동기화하기 위한 최대 제한 시간(ms)을 지정합니다. 기본값은 `200`입니다.	`int`	No

Note: VirtualServer 및 해당 VirtualServerRoute에서 하나의 OIDC 정책만 참조할 수 있습니다. 그러나 동일한 정책을 VirtualServer 및 VirtualServerRoutes의 다른 경로에 계속 적용할 수 있습니다.

1-9-3. OIDC 병합

VirtualServer/VirtualServerRoute는 단일 OIDC 정책만 참조할 수 있습니다. 모든 후속 참조는 무시됩니다. 예를 들어 여기서는 두 가지 정책을 참조합니다.

policies:
- name: oidc-policy-one
- name: oidc-policy-two

이 예에서 Ingress Controller는 첫 번째 정책 참조 oidc-policy-one의 구성을 사용하고 oidc-policy-two는 무시합니다.

2. 정책 사용

기본 제공 Kubernetes 리소스와 마찬가지로 일반 kubectl 명령을 사용하여 정책 리소스를 사용할 수 있습니다.

예를 들어 다음 명령은 webapp-policy라는 이름으로 access-control-policy-allow.yaml에 정의된 정책 리소스를 생성합니다.

$ kubectl apply -f access-control-policy-allow.yaml
policy.k8s.nginx.org/webapp-policy configured

다음을 실행하여 리소스를 가져올 수 있습니다.

$ kubectl get policy webapp-policy
NAME            AGE
webapp-policy   27m

kubectl get 및 유사한 명령의 경우 policy 대신 단축 이름 pol을 사용할 수도 있습니다.

2-1. WAF

Note: 이 기능은 AppProtect가 포함된 NGINX Plus에서만 사용할 수 있습니다.

WAF 정책은 App Protect WAF 정책을 사용하여 클라이언트 요청을 보호하도록 NGINX Plus를 구성합니다.

예를 들어, 다음 정책은 참조된 APPolicy를 활성화합니다. 로그 대상을 사용하여 여러 APLogConf를 구성할 수 있습니다.

waf:
  enable: true
  apPolicy: "default/dataguard-alarm"
  securityLogs:
  - enable: true
    apLogConf: "default/logconf"
    logDest: "syslog:server=syslog-svc.default:514"
  - enable: true
    apLogConf: "default/logconf"
    logDest: "syslog:server=syslog-svc-secondary.default:514"

Note: 필드 waf.securityLog는 더 이상 사용되지 않으며 향후 릴리스에서 제거될 예정입니다. waf.securityLogs가 채워진 경우 무시됩니다.

Note: 이 기능은 NGINX Plus NGINX App Protect WAF 모듈을 사용하여 구현됩니다.

Field	설명	Type	Required
`enable`	NGINX App Protect WAF를 활성화합니다.	`bool`	Yes
`apPolicy`	WAF의 App Protect WAF 정책입니다. 선택적 Namespace를 허용합니다.	`string`	No
`securityLog.enable`	보안 로그를 활성화합니다.	`bool`	No
`securityLog.apLogConf`	App Protect WAF log conf 리소스입니다. 선택적 Namespace를 허용합니다.	`string`	No
`securityLog.logDest`	보안 로그의 로그 대상입니다. 허용되는 변수는 `syslog:server=<ip-address \| localhost; fqdn>:<port>`, `stderr`, `<absolute path to file>`. 기본값은 `'syslog:server=127.0.0.1:514'`입니다.	`string`	No

2-1-1. WAF 병합

VirtualServer/VirtualServerRoute는 여러 WAF 정책을 참조할 수 있습니다. 그러나 하나만 적용할 수 있습니다. 모든 후속 참조는 무시됩니다. 예를 들어 여기서는 두 가지 정책을 참조합니다.

policies:
- name: waf-policy-one
- name: waf-policy-two

이 예에서 Ingress Controller는 첫 번째 정책 참조 waf-policy-one의 구성을 사용하고 waf-policy-two를 무시합니다.

2-2. 정책 적용

VirtualServer 및 VirtualServerRoute 리소스 모두에 정책을 적용할 수 있습니다. 예를 들어:

VirtualServer:

apiVersion: k8s.nginx.org/v1
kind: VirtualServer
metadata:
  name: cafe
  namespace: cafe
spec:
  host: cafe.example.com
  tls:
    secret: cafe-secret
  policies: # spec policies
  - name: policy1
  upstreams:
  - name: coffee
    service: coffee-svc
    port: 80
  routes:
  - path: /tea
    policies: # route policies
    - name: policy2
      namespace: cafe
    route: tea/tea
  - path: /coffee
    policies: # route policies
    - name: policy3
      namespace: cafe
    action:
      pass: coffee

VirtualServer의 경우 정책을 적용할 수 있습니다.

모든 경로에(사양 정책)
특정 경로에(경로 정책)

동일한 유형의 경로 정책은 사양 정책을 재정의합니다. 위의 예에서 policy-1 및 policy-3 정책 유형이 accessControl인 경우 cafe.example.com/coffee에 대한 요청에 대해 NGINX는 policy-3을 적용합니다.

재정의는 NGINX에 의해 시행됩니다. 사양 정책은 구성의 server 지시문에서 구현되고 경로 정책은 location 지시문에서 구현됩니다. 결과적으로 동일한 유형의 경로 정책이 우선합니다.

위의 VirtualServer에서 참조하는 VirtualServerRoute:

apiVersion: k8s.nginx.org/v1
kind: VirtualServerRoute
metadata:
  name: tea
  namespace: tea
spec:
  host: cafe.example.com
  upstreams:
  - name: tea
    service: tea-svc
    port: 80
  subroutes: # subroute policies
  - path: /tea
    policies:
    - name: policy4
      namespace: tea
    action:
      pass: tea

VirtualServerRoute의 경우 하위 경로에 정책을 적용할 수 있습니다(서브 경로 정책).

동일한 유형의 하위 경로 정책은 사양 정책을 재정의합니다. 위의 예에서 정책 policy-1(VirtualServer에서) 및 policy-4의 유형이 accessControl인 경우 cafe.example.com/tea에 대한 요청에 대해 NGINX는 policy-4를 적용합니다. VirtualServer와 마찬가지로 재정의는 NGINX에 의해 시행됩니다.

하위 경로 정책은 유형에 관계없이 항상 경로 정책보다 우선합니다. 예를 들어 VirtualServer 경로의 정책 policy-2는 하위 경로 /tea에 대해 무시됩니다. 하위 경로에는 자체 정책이 있기 때문입니다(이 경우 하나만 policy4). 하위 경로에 정책이 없으면 policy-2가 적용됩니다. 이 재정의는 Ingress Controller에 의해 시행됩니다. 하위 경로의 location 지시문에는 경로 정책 또는 하위 경로 정책이 있지만 둘 다는 없습니다.

2-3. 잘못된 정책

NGINX는 다음 조건 중 하나가 충족되면 정책을 유효하지 않은 것으로 처리합니다.

정책이 포괄적인 유효성 검사를 통과하지 않습니다.
정책이 클러스터에 없습니다.
정책이 유형별 요구 사항을 충족하지 않습니다. 예를 들어, ingressMTLS 정책은 VirtualServer에서 활성화된 TLS Termination를 요구합니다.

잘못된 정책의 경우 NGINX는 다음 규칙을 사용하여 클라이언트 요청에 대해 500 상태 코드를 반환합니다.

정책이 VirtualServer route 또는 VirtualServerRoute subroute에서 참조되는 경우 NGINX는 해당 경route/subroute의 URI에 대한 요청에 대해 500 상태 코드를 반환합니다.

정책이 VirtualServer spec에서 참조되는 경우 NGINX는 해당 VirtualServer의 모든 URI에 대한 요청에 대해 500 상태 코드를 반환합니다.

정책이 잘못된 경우 VirtualServer 또는 VirtualServerRoute는 Warning 상태와 정책이 잘못된 것으로 간주되지 않은 이유를 설명하는 메시지를 갖게 됩니다.

2-4. 검증

정책 리소스에 대해 두 가지 유형의 유효성 검사를 사용할 수 있습니다.

kubectl 및 Kubernetes API 서버에서 수행되는 구조적 유효성 검사.
Ingress Controller가 수행하는 포괄적인 유효성 검사입니다.

2-4-1. 구조 검증

정책에 대한 사용자 정의 리소스 정의에는 리소스의 모든 필드 유형을 설명하는 구조적 OpenAPI 스키마가 포함됩니다.

예를 들어, 리소스가 허용 필드의 문자열 배열 대신 문자열 값을 사용하는 등 구조적 스키마를 위반하는 리소스를 생성(또는 업데이트)하려고 하면 kubectl 및 Kubernetes API 서버가 리소스를 거부합니다.

kubectl 유효성 검사의 예:

$ kubectl apply -f access-control-policy-allow.yaml
error: error validating "access-control-policy-allow.yaml": error validating data: ValidationError(Policy.spec.accessControl.allow): invalid type for org.nginx.k8s.v1.Policy.spec.accessControl.allow: got "string", expected "array"; if you choose to ignore these errors, turn validation off with --validate=false

Kubernetes API 서버 유효성 검사의 예:

$ kubectl apply -f access-control-policy-allow.yaml --validate=false
The Policy "webapp-policy" is invalid: spec.accessControl.allow: Invalid value: "string": spec.accessControl.allow in body must be of type array: "string"

리소스가 구조적 유효성 검사를 통과하면 Ingress Controller의 포괄적인 유효성 검사가 실행됩니다.

2-4-2. 포괄적 검증

Ingress Controller는 정책 리소스의 필드를 검증합니다. 리소스가 유효하지 않으면 Ingress Controller가 리소스를 거부합니다. 리소스는 클러스터에 계속 존재하지만 Ingress Controller는 이를 무시합니다.

kubectl을 사용하여 Ingress Controller가 정책 구성을 성공적으로 적용했는지 여부를 확인할 수 있습니다. 예제 webapp-policy 정책의 경우 다음을 실행할 수 있습니다.

$ kubectl describe pol webapp-policy
. . .
Events:
  Type    Reason          Age   From                      Message
  ----    ------          ----  ----                      -------
  Normal  AddedOrUpdated  11s   nginx-ingress-controller  Policy default/webapp-policy was added or updated

구성이 성공적으로 적용되었음을 알리는 AddedOrUpdated 이유가 있는 Normal 이벤트가 이벤트 섹션에 어떻게 포함되어 있는지 확인하십시오.

잘못된 리소스를 생성하면 Ingress Controller가 이를 거부하고 Rejected 이벤트를 내보냅니다. 예를 들어 유효하지 않은 IP 10.0.0으로 정책 webapp-policy를 생성하는 경우입니다. allow 필드에 다음이 표시됩니다.

$ kubectl describe policy webapp-policy
. . .
Events:
  Type     Reason    Age   From                      Message
  ----     ------    ----  ----                      -------
  Warning  Rejected  7s    nginx-ingress-controller  Policy default/webapp-policy is invalid and was rejected: spec.accessControl.allow[0]: Invalid value: "10.0.0.": must be a CIDR or IP

이벤트 섹션에 Rejected 이유가 있는 경고 이벤트가 어떻게 포함되어 있는지 확인하십시오.

또한 이 정보는 정책 리소스의 status 필드에서도 사용할 수 있습니다. 정책의 상태 섹션에 유의하십시오.

$ kubectl describe pol webapp-policy
. . .
Status:
  Message:  Policy default/webapp-policy is invalid and was rejected: spec.accessControl.allow[0]: Invalid value: "10.0.0.": must be a CIDR or IP
  Reason:   Rejected
  State:    Invalid

Note: 기존 리소스를 유효하지 않게 만들면 Ingress Controller가 이를 거부합니다.

정책 리소스

1. 전제 조건

1-1. 정책 사양

1-2. 액세스 제어

1-2-1. 액세스 제어 병합

1-3. 속도 제한

1-3-1. 속도 제한 병합

1-4. 기본 인증

1-4-1. 기본 인증 병합

1-5. JWT

1-5-1. JWT 병합

1-6. 원격으로 JWKS를 사용하는 JWT

1-6-1. JWT 병합

1-7. IngressMTLS

1-7-1. IngressMTLS 병합

1-8. EgressMTLS

1-8-1. EgressMTLS 병합

1-9. OIDC

1-9-1. 전제 조건

1-9-2. Limitations

1-9-3. OIDC 병합

2. 정책 사용

2-1. WAF

2-1-1. WAF 병합

2-2. 정책 적용

2-3. 잘못된 정책

2-4. 검증

2-4-1. 구조 검증

2-4-2. 포괄적 검증

Company

API Gateway

Contacts

정책 리소스

1. 전제 조건

1-1. 정책 사양

1-2. 액세스 제어

1-2-1. 액세스 제어 병합

1-3. 속도 제한

1-3-1. 속도 제한 병합

1-4. 기본 인증

1-4-1. 기본 인증 병합

1-5. JWT

1-5-1. JWT 병합

1-6. 원격으로 JWKS를 사용하는 JWT

1-6-1. JWT 병합

1-7. IngressMTLS

1-7-1. IngressMTLS 병합

1-8. EgressMTLS

1-8-1. EgressMTLS 병합

1-9. OIDC

1-9-1. 전제 조건

1-9-2. Limitations

1-9-3. OIDC 병합

2. 정책 사용

2-1. WAF

2-1-1. WAF 병합

2-2. 정책 적용

2-3. 잘못된 정책

2-4. 검증

2-4-1. 구조 검증

2-4-2. 포괄적 검증

Newsletter