
정책 리소스
정책 리소스를 사용하면 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
또는 VirtualServerRoutesubroute
에서 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가 이를 거부합니다.