github.com/nginxinc/kubernetes-ingress@v1.12.5/docs-web/configuration/ingress-resources/advanced-configuration-with-annotations.md (about) 1 # Advanced Configuration with Annotations 2 3 The Ingress resource only allows you to use basic NGINX features -- host and path-based routing and TLS termination. Thus, advanced features like rewriting the request URI or inserting additional response headers are not available. 4 5 In addition to using advanced features, often it is necessary to customize or fine tune NGINX behavior. For example, set the value of connection timeouts. 6 7 Annotations applied to an Ingress resource allow you to use advanced NGINX features and customize/fine tune NGINX behavior for that Ingress resource. 8 9 Customization and fine-tuning is also available through the [ConfigMap](/nginx-ingress-controller/configuration/global-configuration/configmap-resource). Annotations take precedence over the ConfigMap. 10 11 ## Using Annotations 12 13 Here is an example of using annotations to customize the configuration for a particular Ingress resource: 14 ```yaml 15 apiVersion: networking.k8s.io/v1beta1 16 kind: Ingress 17 metadata: 18 name: cafe-ingress-with-annotations 19 annotations: 20 nginx.org/proxy-connect-timeout: "30s" 21 nginx.org/proxy-read-timeout: "20s" 22 nginx.org/client-max-body-size: "4m" 23 nginx.org/server-snippets: | 24 location / { 25 return 302 /coffee; 26 } 27 spec: 28 rules: 29 - host: cafe.example.com 30 http: 31 paths: 32 - path: /tea 33 backend: 34 serviceName: tea-svc 35 servicePort: 80 36 - path: /coffee 37 backend: 38 serviceName: coffee-svc 39 servicePort: 80 40 ``` 41 42 ## Validation 43 44 The Ingress Controller validates the annotations of Ingress resources. If an Ingress is invalid, the Ingress Controller will reject it: the Ingress will continue to exist in the cluster, but the Ingress Controller will ignore it. 45 46 You can check if the Ingress Controller successfully applied the configuration for an Ingress. For our example `cafe-ingress-with-annotations` Ingress, we can run: 47 ``` 48 $ kubectl describe ing cafe-ingress-with-annotations 49 . . . 50 Events: 51 Type Reason Age From Message 52 ---- ------ ---- ---- ------- 53 Normal AddedOrUpdated 3s nginx-ingress-controller Configuration for default/cafe-ingress-with-annotations was added or updated 54 ``` 55 Note how the events section includes a Normal event with the AddedOrUpdated reason that informs us that the configuration was successfully applied. 56 57 If you create an invalid Ingress, the Ingress Controller will reject it and emit a Rejected event. For example, if you create an Ingress `cafe-ingress-with-annotations`, with an annotation `nginx.org/redirect-to-https` set to `yes please` instead of `true`, you will get: 58 ``` 59 $ kubectl describe ing cafe-ingress-with-annotations 60 . . . 61 Events: 62 Type Reason Age From Message 63 ---- ------ ---- ---- ------- 64 Warning Rejected 13s nginx-ingress-controller annotations.nginx.org/redirect-to-https: Invalid value: "yes please": must be a boolean 65 ``` 66 Note how the events section includes a Warning event with the Rejected reason. 67 68 **Note**: If you make an existing Ingress invalid, the Ingress Controller will reject it and remove the corresponding configuration from NGINX. 69 70 The following Ingress annotations currently have limited or no validation: 71 72 - `nginx.org/server-tokens`, 73 - `nginx.org/proxy-hide-headers`, 74 - `nginx.org/proxy-pass-headers`, 75 - `nginx.org/rewrites`, 76 - `nginx.com/jwt-key`, 77 - `nginx.com/jwt-realm`, 78 - `nginx.com/jwt-token`, 79 - `nginx.com/jwt-login-url`, 80 - `nginx.com/sticky-cookie-services`, 81 - `appprotect.f5.com/app-protect-policy`, 82 - `appprotect.f5.com/app-protect-security-log`. 83 84 Validation of these annotations will be addressed in the future. 85 86 ## Summary of Annotations 87 88 The table below summarizes the available annotations. 89 90 **Note**: The annotations that start with `nginx.com` are only supported with NGINX Plus. 91 92 ### Ingress Controller (Not Related to NGINX Configuration) 93 94 ```eval_rst 95 .. list-table:: 96 :header-rows: 1 97 98 * - Annotation 99 - ConfigMap Key 100 - Description 101 - Default 102 - Example 103 * - ``kubernetes.io/ingress.class`` 104 - N/A 105 - Specifies which Ingress controller must handle the Ingress resource. Set to ``nginx`` to make NGINX Ingress controller handle it. 106 - N/A 107 - `Multiple Ingress controllers </nginx-ingress-controller/installation/running-multiple-ingress-controllers>`_. 108 ``` 109 110 ### General Customization 111 112 ```eval_rst 113 .. list-table:: 114 :header-rows: 1 115 116 * - Annotation 117 - ConfigMap Key 118 - Description 119 - Default 120 - Example 121 * - ``nginx.org/proxy-connect-timeout`` 122 - ``proxy-connect-timeout`` 123 - Sets the value of the `proxy_connect_timeout <https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout>`_ and `grpc_connect_timeout <https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_connect_timeout>`_ directive. 124 - ``60s`` 125 - 126 * - ``nginx.org/proxy-read-timeout`` 127 - ``proxy-read-timeout`` 128 - Sets the value of the `proxy_read_timeout <https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout>`_ and `grpc_read_timeout <https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_read_timeout>`_ directive. 129 - ``60s`` 130 - 131 * - ``nginx.org/proxy-send-timeout`` 132 - ``proxy-send-timeout`` 133 - Sets the value of the `proxy_send_timeout <https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_send_timeout>`_ and `grpc_send_timeout <https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_send_timeout>`_ directive. 134 - ``60s`` 135 - 136 * - ``nginx.org/client-max-body-size`` 137 - ``client-max-body-size`` 138 - Sets the value of the `client_max_body_size <https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size>`_ directive. 139 - ``1m`` 140 - 141 * - ``nginx.org/proxy-buffering`` 142 - ``proxy-buffering`` 143 - Enables or disables `buffering of responses <https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering>`_ from the proxied server. 144 - ``True`` 145 - 146 * - ``nginx.org/proxy-buffers`` 147 - ``proxy-buffers`` 148 - Sets the value of the `proxy_buffers <https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers>`_ directive. 149 - Depends on the platform. 150 - 151 * - ``nginx.org/proxy-buffer-size`` 152 - ``proxy-buffer-size`` 153 - Sets the value of the `proxy_buffer_size <https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size>`_ and `grpc_buffer_size <https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size>`_ directives. 154 - Depends on the platform. 155 - 156 * - ``nginx.org/proxy-max-temp-file-size`` 157 - ``proxy-max-temp-file-size`` 158 - Sets the value of the `proxy_max_temp_file_size <https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size>`_ directive. 159 - ``1024m`` 160 - 161 * - ``nginx.org/server-tokens`` 162 - ``server-tokens`` 163 - Enables or disables the `server_tokens <https://nginx.org/en/docs/http/ngx_http_core_module.html#server_tokens>`_ directive. Additionally, with the NGINX Plus, you can specify a custom string value, including the empty string value, which disables the emission of the “Server” field. 164 - ``True`` 165 - 166 ``` 167 168 ### Request URI/Header Manipulation 169 170 ```eval_rst 171 .. list-table:: 172 :header-rows: 1 173 174 * - Annotation 175 - ConfigMap Key 176 - Description 177 - Default 178 - Example 179 * - ``nginx.org/proxy-hide-headers`` 180 - ``proxy-hide-headers`` 181 - Sets the value of one or more `proxy_hide_header <https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_hide_header>`_ directives. Example: ``"nginx.org/proxy-hide-headers": "header-a,header-b"`` 182 - N/A 183 - 184 * - ``nginx.org/proxy-pass-headers`` 185 - ``proxy-pass-headers`` 186 - Sets the value of one or more `proxy_pass_header <https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_header>`_ directives. Example: ``"nginx.org/proxy-pass-headers": "header-a,header-b"`` 187 - N/A 188 - 189 * - ``nginx.org/rewrites`` 190 - N/A 191 - Configures URI rewriting. 192 - N/A 193 - `Rewrites Support <https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/rewrites>`_. 194 ``` 195 196 ### Auth and SSL/TLS 197 198 ```eval_rst 199 .. list-table:: 200 :header-rows: 1 201 202 * - Annotation 203 - ConfigMap Key 204 - Description 205 - Default 206 - Example 207 * - ``nginx.org/redirect-to-https`` 208 - ``redirect-to-https`` 209 - Sets the 301 redirect rule based on the value of the ``http_x_forwarded_proto`` header on the server block to force incoming traffic to be over HTTPS. Useful when terminating SSL in a load balancer in front of the Ingress controller — see `115 <https://github.com/nginxinc/kubernetes-ingress/issues/115>`_ 210 - ``False`` 211 - 212 * - ``ingress.kubernetes.io/ssl-redirect`` 213 - ``ssl-redirect`` 214 - Sets an unconditional 301 redirect rule for all incoming HTTP traffic to force incoming traffic over HTTPS. 215 - ``True`` 216 - 217 * - ``nginx.org/hsts`` 218 - ``hsts`` 219 - Enables `HTTP Strict Transport Security (HSTS) <https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/>`_\ : the HSTS header is added to the responses from backends. The ``preload`` directive is included in the header. 220 - ``False`` 221 - 222 * - ``nginx.org/hsts-max-age`` 223 - ``hsts-max-age`` 224 - Sets the value of the ``max-age`` directive of the HSTS header. 225 - ``2592000`` (1 month) 226 - 227 * - ``nginx.org/hsts-include-subdomains`` 228 - ``hsts-include-subdomains`` 229 - Adds the ``includeSubDomains`` directive to the HSTS header. 230 - ``False`` 231 - 232 * - ``nginx.org/hsts-behind-proxy`` 233 - ``hsts-behind-proxy`` 234 - Enables HSTS based on the value of the ``http_x_forwarded_proto`` request header. Should only be used when TLS termination is configured in a load balancer (proxy) in front of the Ingress Controller. Note: to control redirection from HTTP to HTTPS configure the ``nginx.org/redirect-to-https`` annotation. 235 - ``False`` 236 - 237 * - ``nginx.com/jwt-key`` 238 - N/A 239 - Specifies a Secret resource with keys for validating JSON Web Tokens (JWTs). 240 - N/A 241 - `Support for JSON Web Tokens (JWTs) <https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/jwt>`_. 242 * - ``nginx.com/jwt-realm`` 243 - N/A 244 - Specifies a realm. 245 - N/A 246 - `Support for JSON Web Tokens (JWTs) <https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/jwt>`_. 247 * - ``nginx.com/jwt-token`` 248 - N/A 249 - Specifies a variable that contains JSON Web Token. 250 - By default, a JWT is expected in the ``Authorization`` header as a Bearer Token. 251 - `Support for JSON Web Tokens (JWTs) <https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/jwt>`_. 252 * - ``nginx.com/jwt-login-url`` 253 - N/A 254 - Specifies a URL to which a client is redirected in case of an invalid or missing JWT. 255 - N/A 256 - `Support for JSON Web Tokens (JWTs) <https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/jwt>`_. 257 ``` 258 259 ### Listeners 260 261 ```eval_rst 262 .. list-table:: 263 :header-rows: 1 264 265 * - Annotation 266 - ConfigMap Key 267 - Description 268 - Default 269 - Example 270 * - ``nginx.org/listen-ports`` 271 - N/A 272 - Configures HTTP ports that NGINX will listen on. 273 - ``[80]`` 274 - 275 * - ``nginx.org/listen-ports-ssl`` 276 - N/A 277 - Configures HTTPS ports that NGINX will listen on. 278 - ``[443]`` 279 - 280 ``` 281 282 ### Backend Services (Upstreams) 283 284 ```eval_rst 285 .. list-table:: 286 :header-rows: 1 287 288 * - Annotation 289 - ConfigMap Key 290 - Description 291 - Default 292 - Example 293 * - ``nginx.org/lb-method`` 294 - ``lb-method`` 295 - Sets the `load balancing method <https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#choosing-a-load-balancing-method>`_. To use the round-robin method, specify ``"round_robin"``. 296 - ``"random two least_conn"`` 297 - 298 * - ``nginx.org/ssl-services`` 299 - N/A 300 - Enables HTTPS or gRPC over SSL when connecting to the endpoints of services. 301 - N/A 302 - `SSL Services Support <https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/ssl-services>`_. 303 * - ``nginx.org/grpc-services`` 304 - N/A 305 - Enables gRPC for services. Note: requires HTTP/2 (see ``http2`` ConfigMap key); only works for Ingresses with TLS termination enabled. 306 - N/A 307 - `GRPC Services Support <https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/grpc-services>`_. 308 * - ``nginx.org/websocket-services`` 309 - N/A 310 - Enables WebSocket for services. 311 - N/A 312 - `WebSocket support <https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/websocket>`_. 313 * - ``nginx.org/max-fails`` 314 - ``max-fails`` 315 - Sets the value of the `max_fails <https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails>`_ parameter of the ``server`` directive. 316 - ``1`` 317 - 318 * - ``nginx.org/max-conns`` 319 - N\A 320 - Sets the value of the `max_conns <https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns>`_ parameter of the ``server`` directive. 321 - ``0`` 322 - 323 * - ``nginx.org/upstream-zone-size`` 324 - ``upstream-zone-size`` 325 - Sets the size of the shared memory `zone <https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone>`_ for upstreams. For NGINX, the special value 0 disables the shared memory zones. For NGINX Plus, shared memory zones are required and cannot be disabled. The special value 0 will be ignored. 326 - ``256K`` 327 - 328 * - ``nginx.org/fail-timeout`` 329 - ``fail-timeout`` 330 - Sets the value of the `fail_timeout <https://nginx.org/en/docs/http/ngx_http_upstream_module.html#fail_timeout>`_ parameter of the ``server`` directive. 331 - ``10s`` 332 - 333 * - ``nginx.com/sticky-cookie-services`` 334 - N/A 335 - Configures session persistence. 336 - N/A 337 - `Session Persistence <https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/session-persistence>`_. 338 * - ``nginx.org/keepalive`` 339 - ``keepalive`` 340 - Sets the value of the `keepalive <https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive>`_ directive. Note that ``proxy_set_header Connection "";`` is added to the generated configuration when the value > 0. 341 - ``0`` 342 - 343 * - ``nginx.com/health-checks`` 344 - N/A 345 - Enables active health checks. 346 - ``False`` 347 - `Support for Active Health Checks <https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/health-checks>`_. 348 * - ``nginx.com/health-checks-mandatory`` 349 - N/A 350 - Configures active health checks as mandatory. 351 - ``False`` 352 - `Support for Active Health Checks <https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/health-checks>`_. 353 * - ``nginx.com/health-checks-mandatory-queue`` 354 - N/A 355 - When active health checks are mandatory, configures a queue for temporary storing incoming requests during the time when NGINX Plus is checking the health of the endpoints after a configuration reload. 356 - ``0`` 357 - `Support for Active Health Checks <https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/health-checks>`_. 358 * - ``nginx.com/slow-start`` 359 - N/A 360 - Sets the upstream server `slow-start period <https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#server-slow-start>`_. By default, slow-start is activated after a server becomes `available <https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#passive-health-checks>`_ or `healthy <https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#active-health-checks>`_. To enable slow-start for newly added servers, configure `mandatory active health checks <https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/health-checks>`_. 361 - ``"0s"`` 362 - 363 ``` 364 365 ### Snippets and Custom Templates 366 367 ```eval_rst 368 .. list-table:: 369 :header-rows: 1 370 371 * - Annotation 372 - ConfigMap Key 373 - Description 374 - Default 375 - Example 376 * - ``nginx.org/location-snippets`` 377 - ``location-snippets`` 378 - Sets a custom snippet in location context. 379 - N/A 380 - 381 * - ``nginx.org/server-snippets`` 382 - ``server-snippets`` 383 - Sets a custom snippet in server context. 384 - N/A 385 - 386 ``` 387 388 ### App Protect 389 390 **Note**: The App Protect annotations only work if App Protect module is [installed](/nginx-ingress-controller/app-protect/installation/). 391 392 ```eval_rst 393 .. list-table:: 394 :header-rows: 1 395 396 * - Annotation 397 - ConfigMap Key 398 - Description 399 - Default 400 - Example 401 * - ``appprotect.f5.com/app-protect-policy`` 402 - N/A 403 - The name of the App Protect Policy for the Ingress Resource. Format is ``namespace/name``. If no namespace is specified, the same namespace of the Ingress Resource is used. If not specified but ``appprotect.f5.com/app-protect-enable`` is true, a default policy id applied. If the referenced policy resource does not exist, or policy is invalid, this annotation will be ignored, and the default policy will be applied. 404 - N/A 405 - `Example for App Protect <https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/appprotect>`_. 406 * - ``appprotect.f5.com/app-protect-enable`` 407 - N/A 408 - Enable App Protect for the Ingress Resource. 409 - ``False`` 410 - `Example for App Protect <https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/appprotect>`_. 411 * - ``appprotect.f5.com/app-protect-security-log-enable`` 412 - N/A 413 - Enable the `security log </nginx-app-protect/troubleshooting/#app-protect-security-log>`_ for App Protect. 414 - ``False`` 415 - `Example for App Protect <https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/appprotect>`_. 416 * - ``appprotect.f5.com/app-protect-security-log`` 417 - N/A 418 - The App Protect log configuration for the Ingress Resource. Format is ``namespace/name``. If no namespace is specified, the same namespace as the Ingress Resource is used. If not specified the default is used which is: filter: ``illegal``, format: ``default``. Multiple configurations can be specified in a comma seperated list. Both log configurations and destinations list (see below) must be of equal length. Configs and destinations are paired by the list indices. 419 - N/A 420 - `Example for App Protect <https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/appprotect>`_. 421 * - ``appprotect.f5.com/app-protect-security-log-destination`` 422 - N/A 423 - The destination of the security log. For more information check the `DESTINATION argument </nginx-app-protect/troubleshooting/#app-protect-security-log>`_. Multiple destinations can be specified in a coma seperated list. Both log configurations and destinations list (see above) must be of equal length. Configs and destinations are paired by the list indices. 424 - ``syslog:server=localhost:514`` 425 - `Example for App Protect <https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/appprotect>`_. 426 ```