From 467b6d74995fbf086f5e068dc4074e730c8e31ad Mon Sep 17 00:00:00 2001 From: Travis Bot Date: Thu, 3 May 2018 14:08:21 +0000 Subject: [PATCH] Deploy GitHub Pages --- 404.html | 80 +- deploy/index.html | 80 +- deploy/rbac/index.html | 84 +- .../README => deploy/upgrade}/index.html | 417 +++--- development/index.html | 80 +- examples/PREREQUISITES/index.html | 104 +- examples/affinity/cookie/README/index.html | 84 +- examples/auth/basic/README/index.html | 80 +- examples/auth/client-certs/README/index.html | 80 +- examples/auth/external-auth/README/index.html | 84 +- .../oauth-external-auth}/README/index.html | 458 +++--- .../dashboard-ingress.yaml | 0 .../oauth-external-auth}/images/dashboard.png | Bin .../images/github-auth.png | Bin .../images/oauth-login.png | Bin .../images/register-oauth-app-2.png | Bin .../images/register-oauth-app.png | Bin .../oauth-external-auth}/oauth2-proxy.yaml | 0 .../configuration-snippets/README/index.html | 84 +- .../custom-configuration/README/index.html | 80 +- .../custom-errors/README/index.html | 80 +- .../custom-headers/README/index.html | 80 +- .../custom-upstream-check/README/index.html | 84 +- .../README/index.html | 90 +- .../external-auth-headers/README/index.html | 88 +- .../ssl-dh-param/README/index.html | 90 +- .../customization/sysctl/README/index.html | 84 +- examples/docker-registry/README/index.html | 84 +- examples/index.html | 1256 +++++++++++++++++ examples/multi-tls/README/index.html | 84 +- examples/rewrite/README/index.html | 80 +- examples/static-ip/README/index.html | 80 +- examples/tls-termination/README/index.html | 80 +- index.html | 80 +- ingress-controller-catalog/index.html | 80 +- search/search_index.json | 285 ++-- sitemap.xml | 66 +- troubleshooting/index.html | 80 +- user-guide/cli-arguments/index.html | 80 +- user-guide/custom-errors/index.html | 84 +- user-guide/default-backend/index.html | 1145 +++++++++++++++ .../exposing-tcp-udp-services/index.html | 84 +- user-guide/external-articles/index.html | 80 +- user-guide/miscellaneous/index.html | 124 +- user-guide/multiple-ingress/index.html | 174 +-- .../annotations/index.html | 451 +++--- .../nginx-configuration/configmap/index.html | 80 +- .../custom-template/index.html | 80 +- user-guide/nginx-configuration/index.html | 84 +- .../nginx-configuration/log-format/index.html | 193 ++- user-guide/nginx-status-page/index.html | 88 +- .../third-party-addons/modsecurity/index.html | 84 +- .../third-party-addons/opentracing/index.html | 84 +- user-guide/tls/index.html | 317 ++--- 54 files changed, 5641 insertions(+), 2237 deletions(-) rename {examples/README => deploy/upgrade}/index.html (74%) rename examples/{external-auth => auth/oauth-external-auth}/README/index.html (80%) rename examples/{external-auth => auth/oauth-external-auth}/dashboard-ingress.yaml (100%) rename examples/{external-auth => auth/oauth-external-auth}/images/dashboard.png (100%) rename examples/{external-auth => auth/oauth-external-auth}/images/github-auth.png (100%) rename examples/{external-auth => auth/oauth-external-auth}/images/oauth-login.png (100%) rename examples/{external-auth => auth/oauth-external-auth}/images/register-oauth-app-2.png (100%) rename examples/{external-auth => auth/oauth-external-auth}/images/register-oauth-app.png (100%) rename examples/{external-auth => auth/oauth-external-auth}/oauth2-proxy.yaml (100%) create mode 100644 examples/index.html create mode 100644 user-guide/default-backend/index.html diff --git a/404.html b/404.html index 82b45017d..43d06f881 100644 --- a/404.html +++ b/404.html @@ -240,7 +240,7 @@
  • - + Examples @@ -354,6 +354,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -491,6 +503,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -528,8 +552,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -552,8 +576,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -565,13 +589,13 @@
  • - + -
    • @@ -811,8 +847,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -835,8 +871,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -875,18 +911,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination diff --git a/deploy/index.html b/deploy/index.html index ca270965a..fd6d0f175 100644 --- a/deploy/index.html +++ b/deploy/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -537,6 +537,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -674,6 +686,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -711,8 +735,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -735,8 +759,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -748,13 +772,13 @@
  • - + -
    • @@ -994,8 +1030,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -1018,8 +1054,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -1058,18 +1094,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination diff --git a/deploy/rbac/index.html b/deploy/rbac/index.html index 4e6b9a804..6b588f8d6 100644 --- a/deploy/rbac/index.html +++ b/deploy/rbac/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -441,6 +441,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -578,6 +590,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -615,8 +639,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -639,8 +663,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -652,13 +676,13 @@
  • - + -
    • @@ -898,8 +934,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -922,8 +958,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -962,18 +998,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination @@ -1244,13 +1268,13 @@ container arguments, and POD_NAMESPACE should be in the nginx-ingress namespace. -
    + Skip to content @@ -121,7 +121,7 @@ NGINX Ingress Controller - Ingress examples + Upgrading @@ -214,7 +214,7 @@
  • - + Deployment @@ -246,7 +246,7 @@
  • - + Examples @@ -321,10 +321,12 @@ + -
  • + +
  • - +
  • - + Installation Guide
    • @@ -354,12 +356,69 @@
  • - + Role Based Access Control (RBAC)
    • + + + + + + + +
  • + + + + + + + + + + Upgrading + + + + + +
    • + + @@ -497,6 +556,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +605,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +629,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +642,13 @@
  • - + -
    • @@ -818,7 +840,7 @@
  • - + Configuration Snippets
    • @@ -830,7 +852,7 @@
  • - + Custom Configuration
    • @@ -842,7 +864,7 @@
  • - + Custom Errors
    • @@ -854,7 +876,7 @@
  • - + Custom Headers
    • @@ -866,7 +888,7 @@
  • - + Custom Upstream server checks
    • @@ -878,8 +900,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -890,7 +912,7 @@
  • - + External authentication, authentication service response headers propagation
    • @@ -902,8 +924,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -914,7 +936,7 @@
  • - + Sysctl tuning
    • @@ -931,7 +953,7 @@
  • - + Docker registry
    • @@ -943,19 +965,7 @@
  • - - External Authentication - -
    • - - - - - - - -
  • - + Multi TLS certificate termination
    • @@ -967,7 +977,7 @@
  • - + Rewrite
    • @@ -979,7 +989,7 @@
  • - + Static IPs
    • @@ -991,7 +1001,7 @@
  • - + TLS termination
    • @@ -1059,29 +1069,15 @@ @@ -495,6 +507,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -532,8 +556,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -556,8 +580,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -569,13 +593,13 @@
  • - + -
    • @@ -815,8 +851,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -839,8 +875,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -879,18 +915,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination diff --git a/examples/PREREQUISITES/index.html b/examples/PREREQUISITES/index.html index 0e8c9b306..c5bfff8c3 100644 --- a/examples/PREREQUISITES/index.html +++ b/examples/PREREQUISITES/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -497,6 +509,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • @@ -898,8 +934,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -922,8 +958,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -962,18 +998,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination @@ -1334,7 +1358,7 @@ which you can deploy as follows

    -
  • + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -497,6 +509,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • @@ -864,8 +900,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -888,8 +924,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -928,18 +964,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination @@ -1175,7 +1199,7 @@ This means that you can face the situation that you've configured Session Affini
    diff --git a/examples/auth/basic/README/index.html b/examples/auth/basic/README/index.html index bd5e0da9e..9a9646212 100644 --- a/examples/auth/basic/README/index.html +++ b/examples/auth/basic/README/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -497,6 +509,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • @@ -830,8 +866,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -854,8 +890,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -894,18 +930,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination diff --git a/examples/auth/client-certs/README/index.html b/examples/auth/client-certs/README/index.html index 14bd1bd55..950d16d19 100644 --- a/examples/auth/client-certs/README/index.html +++ b/examples/auth/client-certs/README/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -497,6 +509,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • @@ -859,8 +895,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -883,8 +919,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -923,18 +959,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination diff --git a/examples/auth/external-auth/README/index.html b/examples/auth/external-auth/README/index.html index c6d6e6d4a..e9d91213c 100644 --- a/examples/auth/external-auth/README/index.html +++ b/examples/auth/external-auth/README/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -497,6 +509,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • @@ -859,8 +895,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -883,8 +919,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -923,18 +959,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination @@ -1246,13 +1270,13 @@ BODY: -
    • @@ -409,7 +421,7 @@
  • - + NGINX Configuration
    • @@ -421,7 +433,7 @@
  • - + Annotations
    • @@ -433,7 +445,7 @@
  • - + ConfigMaps
    • @@ -445,7 +457,7 @@
  • - + Custom NGINX template
    • @@ -457,7 +469,7 @@
  • - + Log format
    • @@ -474,7 +486,7 @@
  • - + Command line arguments
    • @@ -486,7 +498,7 @@
  • - + Custom errors
    • @@ -498,7 +510,19 @@
  • - + + Default backend + +
    • + + + + + + + +
  • + Exposing TCP and UDP services
    • @@ -510,7 +534,7 @@
  • - + External Articles
    • @@ -522,7 +546,7 @@
  • - + Miscellaneous
    • @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -546,7 +570,7 @@
  • - + NGINX status page
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • - - - - - - - -
  • - - - - - -
    • - - - - - - - -
  • - - Docker registry - -
    • - - @@ -955,13 +832,162 @@ + + + + + + + + + + +
  • + + + + + +
    • + + + + + + + +
  • + + Docker registry + +
    • + + + + + + + +
  • + Multi TLS certificate termination
    • @@ -973,7 +999,7 @@
  • - + Rewrite
    • @@ -985,7 +1011,7 @@
  • - + Static IPs
    • @@ -997,7 +1023,7 @@
  • - + TLS termination
    • @@ -1014,7 +1040,7 @@
  • - + Developing for NGINX Ingress Controller
    • @@ -1026,7 +1052,7 @@
  • - + Ingress Controller Catalog
    • @@ -1038,7 +1064,7 @@
  • - + Debug & Troubleshooting
    • @@ -1114,7 +1140,7 @@
    - +

    External Authentication

    @@ -1209,7 +1235,7 @@ into a Kubernetes cluster and use it to protect the Kubernetes Dashboard using g
    -
  • + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -497,6 +509,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • @@ -866,8 +902,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -890,8 +926,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -930,18 +966,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination @@ -1109,7 +1133,7 @@
    diff --git a/examples/customization/custom-configuration/README/index.html b/examples/customization/custom-configuration/README/index.html index 0c458d77e..225dd91bb 100644 --- a/examples/customization/custom-configuration/README/index.html +++ b/examples/customization/custom-configuration/README/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -497,6 +509,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • @@ -830,8 +866,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -854,8 +890,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -894,18 +930,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination diff --git a/examples/customization/custom-errors/README/index.html b/examples/customization/custom-errors/README/index.html index 775d6800d..1721dfa3d 100644 --- a/examples/customization/custom-errors/README/index.html +++ b/examples/customization/custom-errors/README/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -497,6 +509,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • @@ -830,8 +866,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -854,8 +890,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -894,18 +930,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination diff --git a/examples/customization/custom-headers/README/index.html b/examples/customization/custom-headers/README/index.html index 7d9a399bb..d652e1a11 100644 --- a/examples/customization/custom-headers/README/index.html +++ b/examples/customization/custom-headers/README/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -497,6 +509,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • @@ -859,8 +895,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -883,8 +919,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -923,18 +959,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination diff --git a/examples/customization/custom-upstream-check/README/index.html b/examples/customization/custom-upstream-check/README/index.html index e4fbccb26..60b0fde9a 100644 --- a/examples/customization/custom-upstream-check/README/index.html +++ b/examples/customization/custom-upstream-check/README/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -497,6 +509,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • @@ -830,8 +866,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -854,8 +890,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -894,18 +930,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination @@ -1098,13 +1122,13 @@ spec: -
    + Skip to content @@ -121,7 +121,7 @@ NGINX Ingress Controller - Deploying the Nginx Ingress controller + Custom VTS metrics with Prometheus @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -497,6 +509,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • @@ -830,11 +866,11 @@ - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus @@ -945,8 +981,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -985,18 +1021,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination @@ -1189,7 +1213,7 @@ -

    Deploying the Nginx Ingress controller

    +

    Custom VTS metrics with Prometheus

    This example aims to demonstrate the deployment of an nginx ingress controller and use a ConfigMap to enable nginx vts module to export metrics in prometheus format.

    vts-metrics

    Vts-metrics export NGINX metrics. To deploy all the files simply run kubectl apply -f nginx. A deployment and service will be diff --git a/examples/customization/external-auth-headers/README/index.html b/examples/customization/external-auth-headers/README/index.html index f15370568..61021fcf5 100644 --- a/examples/customization/external-auth-headers/README/index.html +++ b/examples/customization/external-auth-headers/README/index.html @@ -246,7 +246,7 @@

  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -497,6 +509,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • @@ -821,8 +857,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -854,8 +890,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -894,18 +930,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination @@ -1171,7 +1195,7 @@ follows:

    -
    + Skip to content @@ -121,7 +121,7 @@ NGINX Ingress Controller - Deploying the Nginx Ingress controller + Custom DH parameters for perfect forward secrecy @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -497,6 +509,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • @@ -821,8 +857,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -854,11 +890,11 @@ - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy @@ -937,18 +973,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination @@ -1093,7 +1117,7 @@ -

    Deploying the Nginx Ingress controller

    +

    Custom DH parameters for perfect forward secrecy

    This example aims to demonstrate the deployment of an nginx ingress controller and use a ConfigMap to configure custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy".

    diff --git a/examples/customization/sysctl/README/index.html b/examples/customization/sysctl/README/index.html index be4823bda..935cb5766 100644 --- a/examples/customization/sysctl/README/index.html +++ b/examples/customization/sysctl/README/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -497,6 +509,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • @@ -821,8 +857,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -845,8 +881,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -894,18 +930,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination @@ -1045,7 +1069,7 @@ using kubectl patch

    diff --git a/examples/docker-registry/README/index.html b/examples/docker-registry/README/index.html index 6cb902903..7135d6dce 100644 --- a/examples/docker-registry/README/index.html +++ b/examples/docker-registry/README/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -497,6 +509,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • @@ -819,8 +855,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -843,8 +879,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -948,18 +984,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination @@ -1193,13 +1217,13 @@ -
    + Skip to content + + + +
    + +
    + +
    + + + + + + + + + + +
    +
    + + +
    +
    +
    + +
    +
    +
    + + +
    +
    +
    + + +
    +
    +
    + + +
    +
    + + + + + +

    Ingress examples

    +

    This directory contains a catalog of examples on how to run, configure and scale Ingress.
    +Please review the prerequisites before trying them.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    CategoryNameDescriptionComplexity Level
    AppsDocker RegistryTODOTODO
    AuthBasic authenticationpassword protect your websiteIntermediate
    AuthClient certificate authenticationsecure your website with client certificate authenticationIntermediate
    AuthExternal authentication plugindefer to an external authentication serviceIntermediate
    AuthOAuth external authTODOTODO
    CustomizationConfiguration snippetscustomize nginx location configuration using annotationsAdvanced
    CustomizationCustom configurationTODOTODO
    CustomizationCustom DH parameters for perfect forward secrecyTODOTODO
    CustomizationCustom errorsTODOTODO
    CustomizationCustom headersset custom headers before sending traffic to backendsAdvanced
    CustomizationCustom upstream checkTODOTODO
    CustomizationCustom VTS metrics with PrometheusTODOTODO
    CustomizationExternal authentication with response header propagationTODOTODO
    CustomizationSysctl tuningTODOTODO
    FeaturesRewriteTODOTODO
    FeaturesSession stickinessroute requests consistently to the same endpointAdvanced
    ScalingStatic IPa single ingress gets a single static IPIntermediate
    TLSMulti TLS certificate terminationTODOTODO
    TLSTLS terminationTODOTODO
    + + + + + + + + + +
    +
    +
    +
    + + + + +
    + + + + + + + + + + + + + \ No newline at end of file diff --git a/examples/multi-tls/README/index.html b/examples/multi-tls/README/index.html index 390231de3..df567b8e5 100644 --- a/examples/multi-tls/README/index.html +++ b/examples/multi-tls/README/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -497,6 +509,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • @@ -819,8 +855,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -843,8 +879,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -882,18 +918,6 @@ - -
  • - - External Authentication - -
    • - - - - - - @@ -1130,7 +1154,7 @@
    diff --git a/examples/rewrite/README/index.html b/examples/rewrite/README/index.html index a4888ea0f..e088a24d4 100644 --- a/examples/rewrite/README/index.html +++ b/examples/rewrite/README/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -497,6 +509,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • @@ -819,8 +855,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -843,8 +879,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -883,18 +919,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination diff --git a/examples/static-ip/README/index.html b/examples/static-ip/README/index.html index 44745ec2a..abdd7aebc 100644 --- a/examples/static-ip/README/index.html +++ b/examples/static-ip/README/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -497,6 +509,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • @@ -819,8 +855,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -843,8 +879,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -883,18 +919,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination diff --git a/examples/tls-termination/README/index.html b/examples/tls-termination/README/index.html index 1d795f64f..b362a21ea 100644 --- a/examples/tls-termination/README/index.html +++ b/examples/tls-termination/README/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -497,6 +509,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -534,8 +558,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -558,8 +582,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -571,13 +595,13 @@
  • - + -
    • @@ -819,8 +855,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -843,8 +879,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -883,18 +919,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination diff --git a/index.html b/index.html index 735e54467..76e584405 100644 --- a/index.html +++ b/index.html @@ -244,7 +244,7 @@
  • - + Examples @@ -396,6 +396,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -533,6 +545,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -570,8 +594,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -594,8 +618,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -607,13 +631,13 @@
  • - + -
    • @@ -853,8 +889,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -877,8 +913,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -917,18 +953,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination diff --git a/ingress-controller-catalog/index.html b/ingress-controller-catalog/index.html index ca8670a86..dd1445fa7 100644 --- a/ingress-controller-catalog/index.html +++ b/ingress-controller-catalog/index.html @@ -244,7 +244,7 @@
  • - + Examples @@ -358,6 +358,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -495,6 +507,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -532,8 +556,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -556,8 +580,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -569,13 +593,13 @@
  • - + -
    • @@ -815,8 +851,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -839,8 +875,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -879,18 +915,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination diff --git a/search/search_index.json b/search/search_index.json index 1f236fd44..3ff63d8b6 100644 --- a/search/search_index.json +++ b/search/search_index.json @@ -155,6 +155,26 @@ "text": "The ServiceAccount nginx-ingress-serviceaccount is bound to the Role nginx-ingress-role and the ClusterRole nginx-ingress-clusterrole . The serviceAccountName associated with the containers in the deployment must\nmatch the serviceAccount. The namespace references in the Deployment metadata, \ncontainer arguments, and POD_NAMESPACE should be in the nginx-ingress namespace.", "title": "Bindings" }, + { + "location": "/deploy/upgrade/", + "text": "Upgrading\n\u00b6\n\n\n\n\nImportant\n\n\nNo matter the method you use for upgrading, \nif you use template overrides,\nmake sure your templates are compatible with the new version of ingress-nginx\n.\n\n\n\n\nWithout Helm\n\u00b6\n\n\nTo upgrade your ingress-nginx installation, it should be enough to change the version of the image\nin the controller Deployment.\n\n\nI.e. if your deployment resource looks like (partial example):\n\n\nkind\n:\n \nDeployment\n\n\nmetadata\n:\n\n \nname\n:\n \nnginx-ingress-controller\n\n \nnamespace\n:\n \ningress-nginx\n\n\nspec\n:\n\n \nreplicas\n:\n \n1\n\n \nselector\n:\n \n...\n\n \ntemplate\n:\n\n \nmetadata\n:\n \n...\n\n \nspec\n:\n\n \ncontainers\n:\n\n \n-\n \nname\n:\n \nnginx-ingress-controller\n\n \nimage\n:\n \nquay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.9.0\n\n \nargs\n:\n \n...\n\n\n\n\n\n\nsimply change the \n0.9.0\n tag to the version you wish to upgrade to.\nThe easiest way to do this is e.g. (do note you may need to change the name parameter according to your installation):\n\n\nkubectl set image deployment/nginx-ingress-controller \\\n nginx-ingress-controller=nginx:quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.14.0\n\n\n\n\n\nFor interactive editing, use \nkubectl edit deployment nginx-ingress-controller\n.\n\n\nWith Helm\n\u00b6\n\n\nIf you installed ingress-nginx using the Helm command in the deployment docs so its name is \nngx-ingress\n,\nyou should be able to upgrade using\n\n\nhelm upgrade --reuse-values ngx-ingress stable/nginx-ingress", + "title": "Upgrading" + }, + { + "location": "/deploy/upgrade/#upgrading", + "text": "Important No matter the method you use for upgrading, if you use template overrides,\nmake sure your templates are compatible with the new version of ingress-nginx .", + "title": "Upgrading" + }, + { + "location": "/deploy/upgrade/#without-helm", + "text": "To upgrade your ingress-nginx installation, it should be enough to change the version of the image\nin the controller Deployment. I.e. if your deployment resource looks like (partial example): kind : Deployment metadata : \n name : nginx-ingress-controller \n namespace : ingress-nginx spec : \n replicas : 1 \n selector : ... \n template : \n metadata : ... \n spec : \n containers : \n - name : nginx-ingress-controller \n image : quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.9.0 \n args : ... simply change the 0.9.0 tag to the version you wish to upgrade to.\nThe easiest way to do this is e.g. (do note you may need to change the name parameter according to your installation): kubectl set image deployment/nginx-ingress-controller \\\n nginx-ingress-controller=nginx:quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.14.0 For interactive editing, use kubectl edit deployment nginx-ingress-controller .", + "title": "Without Helm" + }, + { + "location": "/deploy/upgrade/#with-helm", + "text": "If you installed ingress-nginx using the Helm command in the deployment docs so its name is ngx-ingress ,\nyou should be able to upgrade using helm upgrade --reuse-values ngx-ingress stable/nginx-ingress", + "title": "With Helm" + }, { "location": "/user-guide/nginx-configuration/", "text": "NGINX Configuration\n\u00b6\n\n\nThere are three ways to customize NGINX:\n\n\n\n\nConfigMap\n: using a Configmap to set global configurations in NGINX.\n\n\nAnnotations\n: use this if you want a specific configuration for a particular Ingress rule.\n\n\nCustom template\n: when more specific settings are required, like \nopen_file_cache\n, adjust \nlisten\n options as \nrcvbuf\n or when is not possible to change the configuration through the ConfigMap.", @@ -167,32 +187,37 @@ }, { "location": "/user-guide/nginx-configuration/annotations/", - "text": "Annotations\n\u00b6\n\n\nYou can add these Kubernetes annotations to specific Ingress objects to customize their behavior.\n\n\n\n\nTip\n\n\nAnnotation keys and values can only be strings.\nOther types, such as boolean or numeric values must be quoted,\ni.e. \n\"true\"\n, \n\"false\"\n, \n\"100\"\n.\n\n\n\n\n\n\n\n\n\n\nName\n\n\ntype\n\n\n\n\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/add-base-url\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/app-root\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/affinity\n\n\ncookie\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-realm\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-secret\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-type\n\n\nbasic or digest\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-tls-secret\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-tls-verify-depth\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-tls-verify-client\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-tls-error-page\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-url\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/base-url-scheme\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/client-body-buffer-size\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/configuration-snippet\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/default-backend\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/enable-cors\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-origin\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-methods\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-headers\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-credentials\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-max-age\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/force-ssl-redirect\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/from-to-www-redirect\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/grpc-backend\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/limit-connections\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/limit-rps\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/permanent-redirect\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-body-size\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-connect-timeout\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-send-timeout\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-read-timeout\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-next-upstream\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-next-upstream-tries\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-request-buffering\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-redirect-from\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-redirect-to\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/rewrite-log\n\n\nURI\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/rewrite-target\n\n\nURI\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/secure-backends\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/secure-verify-ca-secret\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/server-alias\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/server-snippet\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/service-upstream\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/session-cookie-name\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/session-cookie-hash\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/ssl-redirect\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/ssl-passthrough\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/upstream-max-fails\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/upstream-fail-timeout\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/upstream-hash-by\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/load-balance\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/upstream-vhost\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/whitelist-source-range\n\n\nCIDR\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-buffering\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/ssl-ciphers\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/connection-proxy-header\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/enable-access-log\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf-debug\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf-extra-rules\n\n\nstring\n\n\n\n\n\n\n\n\nRewrite\n\u00b6\n\n\nIn some scenarios the exposed URL in the backend service differs from the specified path in the Ingress rule. Without a rewrite any request will return 404.\nSet the annotation \nnginx.ingress.kubernetes.io/rewrite-target\n to the path expected by the service.\n\n\nIf the application contains relative links it is possible to add an additional annotation \nnginx.ingress.kubernetes.io/add-base-url\n that will prepend a \nbase\n tag\n in the header of the returned HTML from the backend.\n\n\nIf the scheme of \nbase\n tag\n need to be specific, set the annotation \nnginx.ingress.kubernetes.io/base-url-scheme\n to the scheme such as \nhttp\n and \nhttps\n.\n\n\nIf the Application Root is exposed in a different path and needs to be redirected, set the annotation \nnginx.ingress.kubernetes.io/app-root\n to redirect requests for \n/\n.\n\n\nPlease check the \nrewrite\n example.\n\n\nSession Affinity\n\u00b6\n\n\nThe annotation \nnginx.ingress.kubernetes.io/affinity\n enables and sets the affinity type in all Upstreams of an Ingress. This way, a request will always be directed to the same upstream server.\nThe only affinity type available for NGINX is \ncookie\n.\n\n\nPlease check the \naffinity\n example.\n\n\nAuthentication\n\u00b6\n\n\nIs possible to add authentication adding additional annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords inside the key \nauth\n.\n\n\nThe annotations are:\n\n\nnginx.ingress.kubernetes.io/auth-type: [basic|digest]\n\n\n\n\n\nIndicates the \nHTTP Authentication Type: Basic or Digest Access Authentication\n.\n\n\nnginx.ingress.kubernetes.io/auth-secret: secretName\n\n\n\n\n\nThe name of the Secret that contains the usernames and passwords which are granted access to the \npath\ns defined in the Ingress rules.\nThis annotation also accepts the alternative form \"namespace/secretName\", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace.\n\n\nnginx.ingress.kubernetes.io/auth-realm: \"realm string\"\n\n\n\n\n\nPlease check the \nauth\n example.\n\n\nCustom NGINX upstream checks\n\u00b6\n\n\nNGINX exposes some flags in the \nupstream configuration\n that enable the configuration of each server in the upstream. The Ingress controller allows custom \nmax_fails\n and \nfail_timeout\n parameters in a global context using \nupstream-max-fails\n and \nupstream-fail-timeout\n in the NGINX ConfigMap or in a particular Ingress rule. \nupstream-max-fails\n defaults to 0. This means NGINX will respect the container's \nreadinessProbe\n if it is defined. If there is no probe and no values for \nupstream-max-fails\n NGINX will continue to send traffic to the container.\n\n\n\n\nTip\n\n\nWith the default configuration NGINX will not health check your backends. Whenever the endpoints controller notices a readiness probe failure, that pod's IP will be removed from the list of endpoints. This will trigger the NGINX controller to also remove it from the upstreams.**\n\n\n\n\nTo use custom values in an Ingress rule define these annotations:\n\n\nnginx.ingress.kubernetes.io/upstream-max-fails\n: number of unsuccessful attempts to communicate with the server that should occur in the duration set by the \nupstream-fail-timeout\n parameter to consider the server unavailable.\n\n\nnginx.ingress.kubernetes.io/upstream-fail-timeout\n: time in seconds during which the specified number of unsuccessful attempts to communicate with the server should occur to consider the server unavailable. This is also the period of time the server will be considered unavailable.\n\n\nIn NGINX, backend server pools are called \"\nupstreams\n\". Each upstream contains the endpoints for a service. An upstream is created for each service that has Ingress rules defined.\n\n\n\n\nImportant\n\n\nAll Ingress rules using the same service will use the same upstream. Only one of the Ingress rules should define annotations to configure the upstream servers.\n\n\n\n\nPlease check the \ncustom upstream check\n example.\n\n\nCustom NGINX upstream hashing\n\u00b6\n\n\nNGINX supports load balancing by client-server mapping based on \nconsistent hashing\n for a given key. The key can contain text, variables or any combination thereof. This feature allows for request stickiness other than client IP or cookies. The \nketama\n consistent hashing method will be used which ensures only a few keys would be remapped to different servers on upstream group changes.\n\n\nTo enable consistent hashing for a backend:\n\n\nnginx.ingress.kubernetes.io/upstream-hash-by\n: the nginx variable, text value or any combination thereof to use for consistent hashing. For example \nnginx.ingress.kubernetes.io/upstream-hash-by: \"$request_uri\"\n to consistently hash upstream requests by the current request URI.\n\n\nCustom NGINX load balancing\n\u00b6\n\n\nThis is similar to (https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/nginx-configuration/configmap.md#load-balance) but configures load balancing algorithm per ingress.\n\n\n\n\nNote that \nnginx.ingress.kubernetes.io/upstream-hash-by\n takes preference over this. If this and \nnginx.ingress.kubernetes.io/upstream-hash-by\n are not set then we fallback to using globally configured load balancing algorithm.\n\n\n\n\nCustom NGINX upstream vhost\n\u00b6\n\n\nThis configuration setting allows you to control the value for host in the following statement: \nproxy_set_header Host $host\n, which forms part of the location block. This is useful if you need to call the upstream server by something other than \n$host\n.\n\n\nClient Certificate Authentication\n\u00b6\n\n\nIt is possible to enable Client Certificate Authentication using additional annotations in Ingress Rule.\n\n\nThe annotations are:\n\n\nnginx.ingress.kubernetes.io/auth-tls-secret: secretName\n\n\n\n\n\nThe name of the Secret that contains the full Certificate Authority chain \nca.crt\n that is enabled to authenticate against this Ingress.\nThis annotation also accepts the alternative form \"namespace/secretName\", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace.\n\n\nnginx.ingress.kubernetes.io/auth-tls-verify-depth\n\n\n\n\n\nThe validation depth between the provided client certificate and the Certification Authority chain.\n\n\nnginx.ingress.kubernetes.io/auth-tls-verify-client\n\n\n\n\n\nEnables verification of client certificates.\n\n\nnginx.ingress.kubernetes.io/auth-tls-error-page\n\n\n\n\n\nThe URL/Page that user should be redirected in case of a Certificate Authentication Error\n\n\nnginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream\n\n\n\n\n\nIndicates if the received certificates should be passed or not to the upstream server.\nBy default this is disabled.\n\n\nPlease check the \nclient-certs\n example.\n\n\n\n\nImportant\n\n\nTLS with Client Authentication is NOT possible in Cloudflare as is not allowed it and might result in unexpected behavior.\n\n\nCloudflare only allows Authenticated Origin Pulls and is required to use their own certificate: \nhttps://blog.cloudflare.com/protecting-the-origin-with-tls-authenticated-origin-pulls/\n\n\nOnly Authenticated Origin Pulls are allowed and can be configured by following their tutorial: \nhttps://support.cloudflare.com/hc/en-us/articles/204494148-Setting-up-NGINX-to-use-TLS-Authenticated-Origin-Pulls\n\n\n\n\nConfiguration snippet\n\u00b6\n\n\nUsing this annotation you can add additional configuration to the NGINX location. For example:\n\n\nnginx.ingress.kubernetes.io/configuration-snippet\n:\n \n|\n\n \nmore_set_headers \"Request-Id: $req_id\";\n\n\n\n\n\n\nDefault Backend\n\u00b6\n\n\nThe ingress controller requires a default backend. This service handles the response when the service in the Ingress rule does not have endpoints.\nThis is a global configuration for the ingress controller. In some cases could be required to return a custom content or format. In this scenario we can use the annotation \nnginx.ingress.kubernetes.io/default-backend: \n to specify a custom default backend.\n\n\nEnable CORS\n\u00b6\n\n\nTo enable Cross-Origin Resource Sharing (CORS) in an Ingress rule add the annotation \nnginx.ingress.kubernetes.io/enable-cors: \"true\"\n. This will add a section in the server location enabling this functionality.\n\n\nCORS can be controlled with the following annotations:\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-methods\n controls which methods are accepted. This is a multi-valued field, separated by ',' and accepts only letters (upper and lower case).\n\n\n\n\nExample: \nnginx.ingress.kubernetes.io/cors-allow-methods: \"PUT, GET, POST, OPTIONS\"\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-headers\n controls which headers are accepted. This is a multi-valued field, separated by ',' and accepts letters, numbers, _ and -.\n\n\n\n\nExample: \nnginx.ingress.kubernetes.io/cors-allow-headers: \"X-Forwarded-For, X-app123-XPTO\"\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-origin\n controls what's the accepted Origin for CORS and defaults to '*'. This is a single field value, with the following format: http(s)://origin-site.com or http(s)://origin-site.com:port\n\n\n\n\nExample: \nnginx.ingress.kubernetes.io/cors-allow-origin: \"https://origin-site.com:4443\"\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-credentials\n controls if credentials can be passed during CORS operations.\n\n\n\n\nExample: \nnginx.ingress.kubernetes.io/cors-allow-credentials: \"true\"\n\n\n\n\nnginx.ingress.kubernetes.io/cors-max-age\n controls how long preflight requests can be cached.\n\n\n\n\nExample: \nnginx.ingress.kubernetes.io/cors-max-age: 600\n\n\nFor more information please see \nhttps://enable-cors.org\n\n\nServer Alias\n\u00b6\n\n\nTo add Server Aliases to an Ingress rule add the annotation \nnginx.ingress.kubernetes.io/server-alias: \"\"\n.\nThis will create a server with the same configuration, but a different server_name as the provided host.\n\n\n\n\nNote\n\n\nA server-alias name cannot conflict with the hostname of an existing server. If it does the server-alias annotation will be ignored. If a server-alias is created and later a new server with the same hostname is created the new server configuration will take place over the alias configuration.\n\n\n\n\nFor more information please see \nhttp://nginx.org\n\n\nServer snippet\n\u00b6\n\n\nUsing the annotation \nnginx.ingress.kubernetes.io/server-snippet\n it is possible to add custom configuration in the server configuration block.\n\n\napiVersion\n:\n \nextensions/v1beta1\n\n\nkind\n:\n \nIngress\n\n\nmetadata\n:\n\n \nannotations\n:\n\n \nnginx.ingress.kubernetes.io/server-snippet\n:\n \n|\n\n\nset $agentflag 0;\n\n\n\nif ($http_user_agent ~* \"(Mobile)\" ){\n\n \nset $agentflag 1;\n\n\n}\n\n\n\nif ( $agentflag = 1 ) {\n\n \nreturn 301 https://m.example.com;\n\n\n}\n\n\n\n\n\n\n\n\nImportant\n\n\nThis annotation can be used only once per host\n\n\n\n\nClient Body Buffer Size\n\u00b6\n\n\nSets buffer size for reading client request body per location. In case the request body is larger than the buffer,\nthe whole body or only its part is written to a temporary file. By default, buffer size is equal to two memory pages.\nThis is 8K on x86, other 32-bit platforms, and x86-64. It is usually 16K on other 64-bit platforms. This annotation is\napplied to each location provided in the ingress rule.\n\n\nNote:\n The annotation value must be given in a valid format otherwise the\nFor example to set the client-body-buffer-size the following can be done:\n\n\n\n\nnginx.ingress.kubernetes.io/client-body-buffer-size: \"1000\"\n # 1000 bytes\n\n\nnginx.ingress.kubernetes.io/client-body-buffer-size: 1k\n # 1 kilobyte\n\n\nnginx.ingress.kubernetes.io/client-body-buffer-size: 1K\n # 1 kilobyte\n\n\nnginx.ingress.kubernetes.io/client-body-buffer-size: 1m\n # 1 megabyte\n\n\nnginx.ingress.kubernetes.io/client-body-buffer-size: 1M\n # 1 megabyte\n\n\n\n\nFor more information please see \nhttp://nginx.org\n\n\nExternal Authentication\n\u00b6\n\n\nTo use an existing service that provides authentication the Ingress rule can be annotated with \nnginx.ingress.kubernetes.io/auth-url\n to indicate the URL where the HTTP request should be sent.\n\n\nnginx.ingress.kubernetes.io/auth-url\n:\n \n\"URL\n \nto\n \nthe\n \nauthentication\n \nservice\"\n\n\n\n\n\n\nAdditionally it is possible to set:\n\n\nnginx.ingress.kubernetes.io/auth-method\n: \n\n to specify the HTTP method to use.\n\n\nnginx.ingress.kubernetes.io/auth-signin\n: \n\n to specify the location of the error page.\n\n\nnginx.ingress.kubernetes.io/auth-response-headers\n: \n\n to specify headers to pass to backend once authorization request completes.\n\n\nnginx.ingress.kubernetes.io/auth-request-redirect\n: \n\n to specify the X-Auth-Request-Redirect header value.\n\n\nPlease check the \nexternal-auth\n example.\n\n\nRate limiting\n\u00b6\n\n\nThe annotations \nnginx.ingress.kubernetes.io/limit-connections\n, \nnginx.ingress.kubernetes.io/limit-rps\n, and \nnginx.ingress.kubernetes.io/limit-rpm\n define a limit on the connections that can be opened by a single client IP address. This can be used to mitigate \nDDoS Attacks\n.\n\n\nnginx.ingress.kubernetes.io/limit-connections\n: number of concurrent connections allowed from a single IP address.\n\n\nnginx.ingress.kubernetes.io/limit-rps\n: number of connections that may be accepted from a given IP each second.\n\n\nnginx.ingress.kubernetes.io/limit-rpm\n: number of connections that may be accepted from a given IP each minute.\n\n\nYou can specify the client IP source ranges to be excluded from rate-limiting through the \nnginx.ingress.kubernetes.io/limit-whitelist\n annotation. The value is a comma separated list of CIDRs.\n\n\nIf you specify multiple annotations in a single Ingress rule, \nlimit-rpm\n, and then \nlimit-rps\n takes precedence.\n\n\nThe annotation \nnginx.ingress.kubernetes.io/limit-rate\n, \nnginx.ingress.kubernetes.io/limit-rate-after\n define a limit the rate of response transmission to a client. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit.\n\n\nnginx.ingress.kubernetes.io/limit-rate-after\n: sets the initial amount after which the further transmission of a response to a client will be rate limited.\n\n\nnginx.ingress.kubernetes.io/limit-rate\n: rate of request that accepted from a client each second.\n\n\nTo configure this setting globally for all Ingress rules, the \nlimit-rate-after\n and \nlimit-rate\n value may be set in the NGINX ConfigMap. if you set the value in ingress annotation will cover global setting.\n\n\nPermanent Redirect\n\u00b6\n\n\nThis annotation allows to return a permanent redirect instead of sending data to the upstream. For example \nnginx.ingress.kubernetes.io/permanent-redirect: https://www.google.com\n would redirect everything to Google.\n\n\nSSL Passthrough\n\u00b6\n\n\nThe annotation \nnginx.ingress.kubernetes.io/ssl-passthrough\n allows to configure TLS termination in the pod and not in NGINX.\n\n\n\n\nImportant\n\n\n\n\n\n\nUsing the annotation \nnginx.ingress.kubernetes.io/ssl-passthrough\n invalidates all the other available annotations. This is because SSL Passthrough works in L4 (TCP).\n\n\n\n\n\n\nThe use of this annotation requires Proxy Protocol to be enabled in the load-balancer. For example enabling Proxy Protocol for AWS ELB is described \nhere\n. If you're using ingress-controller without load balancer then the flag \n--enable-ssl-passthrough\n is required (by default it is disabled).\n\n\n\n\n\n\n\n\nSecure backends\n\u00b6\n\n\nBy default NGINX uses \nhttp\n to reach the services. Adding the annotation \nnginx.ingress.kubernetes.io/secure-backends: \"true\"\n in the Ingress rule changes the protocol to \nhttps\n.\nIf you want to validate the upstream against a specific certificate, you can create a secret with it and reference the secret with the annotation \nnginx.ingress.kubernetes.io/secure-verify-ca-secret\n.\n\n\n\n\nNote that if an invalid or non-existent secret is given, the NGINX ingress controller will ignore the \nsecure-backends\n annotation.\n\n\n\n\nService Upstream\n\u00b6\n\n\nBy default the NGINX ingress controller uses a list of all endpoints (Pod IP/port) in the NGINX upstream configuration. This annotation disables that behavior and instead uses a single upstream in NGINX, the service's Cluster IP and port. This can be desirable for things like zero-downtime deployments as it reduces the need to reload NGINX configuration when Pods come up and down. See issue \n#257\n.\n\n\nKnown Issues\n\u00b6\n\n\nIf the \nservice-upstream\n annotation is specified the following things should be taken into consideration:\n\n\n\n\nSticky Sessions will not work as only round-robin load balancing is supported.\n\n\nThe \nproxy_next_upstream\n directive will not have any effect meaning on error the request will not be dispatched to another upstream.\n\n\n\n\nServer-side HTTPS enforcement through redirect\n\u00b6\n\n\nBy default the controller redirects (301) to \nHTTPS\n if TLS is enabled for that ingress. If you want to disable that behavior globally, you can use \nssl-redirect: \"false\"\n in the NGINX config map.\n\n\nTo configure this feature for specific ingress resources, you can use the \nnginx.ingress.kubernetes.io/ssl-redirect: \"false\"\n annotation in the particular resource.\n\n\nWhen using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to \nHTTPS\n even when there is not TLS cert available. This can be achieved by using the \nnginx.ingress.kubernetes.io/force-ssl-redirect: \"true\"\n annotation in the particular resource.\n\n\nRedirect from to www\n\u00b6\n\n\nIn some scenarios is required to redirect from \nwww.domain.com\n to \ndomain.com\n or viceversa.\nTo enable this feature use the annotation \nnginx.ingress.kubernetes.io/from-to-www-redirect: \"true\"\n\n\n\n\nImportant\n\n\nIf at some point a new Ingress is created with a host equal to one of the options (like \ndomain.com\n) the annotation will be omitted.\n\n\n\n\nWhitelist source range\n\u00b6\n\n\nYou can specify the allowed client IP source ranges through the \nnginx.ingress.kubernetes.io/whitelist-source-range\n annotation. The value is a comma separated list of \nCIDRs\n, e.g. \n10.0.0.0/24,172.10.0.1\n.\n\n\nTo configure this setting globally for all Ingress rules, the \nwhitelist-source-range\n value may be set in the NGINX ConfigMap.\n\n\nNote:\n Adding an annotation to an Ingress rule overrides any global restriction.\n\n\nCookie affinity\n\u00b6\n\n\nIf you use the \ncookie\n type you can also specify the name of the cookie that will be used to route the requests with the annotation \nnginx.ingress.kubernetes.io/session-cookie-name\n. The default is to create a cookie named 'INGRESSCOOKIE'.\n\n\nIn case of NGINX the annotation \nnginx.ingress.kubernetes.io/session-cookie-hash\n defines which algorithm will be used to 'hash' the used upstream. Default value is \nmd5\n and possible values are \nmd5\n, \nsha1\n and \nindex\n.\nThe \nindex\n option is not hashed, an in-memory index is used instead, it's quicker and the overhead is shorter Warning: the matching against upstream servers list is inconsistent. So, at reload, if upstreams servers has changed, index values are not guaranteed to correspond to the same server as before! \nUSE IT WITH CAUTION\n and only if you need to!\n\n\nIn NGINX this feature is implemented by the third party module \nnginx-sticky-module-ng\n. The workflow used to define which upstream server will be used is explained \nhere\n\n\nCustom timeouts\n\u00b6\n\n\nUsing the configuration configmap it is possible to set the default global timeout for connections to the upstream servers.\nIn some scenarios is required to have different values. To allow this we provide annotations that allows this customization:\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-connect-timeout\n\n\nnginx.ingress.kubernetes.io/proxy-send-timeout\n\n\nnginx.ingress.kubernetes.io/proxy-read-timeout\n\n\nnginx.ingress.kubernetes.io/proxy-next-upstream\n\n\nnginx.ingress.kubernetes.io/proxy-next-upstream-tries\n\n\nnginx.ingress.kubernetes.io/proxy-request-buffering\n\n\n\n\nProxy redirect\n\u00b6\n\n\nWith the annotations \nnginx.ingress.kubernetes.io/proxy-redirect-from\n and \nnginx.ingress.kubernetes.io/proxy-redirect-to\n it is possible to set the text that should be changed in the \nLocation\n and \nRefresh\n header fields of a proxied server response (http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect)\nSetting \"off\" or \"default\" in the annotation \nnginx.ingress.kubernetes.io/proxy-redirect-from\n disables \nnginx.ingress.kubernetes.io/proxy-redirect-to\n\nBoth annotations will be used in any other case\nBy default the value is \"off\".\n\n\nCustom max body size\n\u00b6\n\n\nFor NGINX, 413 error will be returned to the client when the size in a request exceeds the maximum allowed size of the client request body. This size can be configured by the parameter \nclient_max_body_size\n.\n\n\nTo configure this setting globally for all Ingress rules, the \nproxy-body-size\n value may be set in the NGINX ConfigMap.\nTo use custom values in an Ingress rule define these annotation:\n\n\nnginx.ingress.kubernetes.io/proxy-body-size\n:\n \n8m\n\n\n\n\n\n\nProxy buffering\n\u00b6\n\n\nEnable or disable proxy buffering \nproxy_buffering\n.\nBy default proxy buffering is disabled in the nginx config.\n\n\nTo configure this setting globally for all Ingress rules, the \nproxy-buffering\n value may be set in the NGINX ConfigMap.\nTo use custom values in an Ingress rule define these annotation:\n\n\nnginx.ingress.kubernetes.io/proxy-buffering\n:\n \n\"on\"\n\n\n\n\n\n\nSSL ciphers\n\u00b6\n\n\nSpecifies the \nenabled ciphers\n.\n\n\nUsing this annotation will set the \nssl_ciphers\n directive at the server level. This configuration is active for all the paths in the host.\n\n\nnginx.ingress.kubernetes.io/ssl-ciphers\n:\n \n\"ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP\"\n\n\n\n\n\n\nConnection proxy header\n\u00b6\n\n\nUsing this annotation will override the default connection header set by nginx. To use custom values in an Ingress rule, define the annotation:\n\n\nnginx.ingress.kubernetes.io/connection-proxy-header\n:\n \n\"keep-alive\"\n\n\n\n\n\n\nEnable Access Log\n\u00b6\n\n\nIn some scenarios could be required to disable NGINX access logs. To enable this feature use the annotation:\n\n\nnginx.ingress.kubernetes.io/enable-access-log\n:\n \n\"false\"\n\n\n\n\n\n\nEnable Rewrite Log\n\u00b6\n\n\nIn some scenarios it could be required to enable NGINX rewrite logs. Note that rewrite logs are sent to the error_log file at the notice level. To enable this feature use the annotation:\n\n\nnginx.ingress.kubernetes.io/enable-rewrite-log\n:\n \n\"true\"\n\n\n\n\n\n\nLua Resty WAF\n\u00b6\n\n\nUsing \nlua-resty-waf-*\n annotations we can enable and control \nlua-resty-waf\n per location.\nFollowing configuration will enable WAF for the paths defined in the corresponding ingress:\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf\n:\n \n\"active\"\n\n\n\n\n\n\nIn order to run it in debugging mode you can set \nnginx.ingress.kubernetes.io/lua-resty-waf-debug\n to \n\"true\"\n in addition to the above configuration.\nThe other possible values for \nnginx.ingress.kubernetes.io/lua-resty-waf\n are \ninactive\n and \nsimulate\n. In \ninactive\n mode WAF won't do anything, whereas\nin \nsimulate\n mode it will log a warning message if there's a matching WAF rule for given request. This is useful to debug a rule and eliminate possible false positives before fully deploying it.\n\n\nlua-resty-waf\n comes with predefined set of rules \nhttps://github.com/p0pr0ck5/lua-resty-waf/tree/84b4f40362500dd0cb98b9e71b5875cb1a40f1ad/rules\n that covers ModSecurity CRS.\nYou can use \nnginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets\n to ignore subset of those rulesets. For an example:\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets\n:\n \n\"41000_sqli,\n \n42000_xss\"\n\n\n\n\n\n\nwill ignore the two mentioned rulesets.\n\n\nIt is also possible to configure custom WAF rules per ingress using \nnginx.ingress.kubernetes.io/lua-resty-waf-extra-rules\n annotation. For an example the following snippet will\nconfigure a WAF rule to deny requests with query string value that contains word \nfoo\n:\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf-extra-rules\n:\n \n'[=[\n \n{\n \n\"access\":\n \n[\n \n{\n \n\"actions\":\n \n{\n \n\"disrupt\"\n \n:\n \n\"DENY\"\n \n},\n \n\"id\":\n \n10001,\n \n\"msg\":\n \n\"my\n \ncustom\n \nrule\",\n \n\"operator\":\n \n\"STR_CONTAINS\",\n \n\"pattern\":\n \n\"foo\",\n \n\"vars\":\n \n[\n \n{\n \n\"parse\":\n \n[\n \n\"values\",\n \n1\n \n],\n \n\"type\":\n \n\"REQUEST_ARGS\"\n \n}\n \n]\n \n}\n \n],\n \n\"body_filter\":\n \n[],\n \n\"header_filter\":[]\n \n}\n \n]=]'\n\n\n\n\n\n\nFor details on how to write WAF rules, please refer to \nhttps://github.com/p0pr0ck5/lua-resty-waf\n.\n\n\ngRPC backend\n\u00b6\n\n\nSince NGINX 1.13.10 it is possible to expose \ngRPC services natively\n\n\nYou only need to add the annotation \nnginx.ingress.kubernetes.io/grpc-backend: \"true\"\n to enable this feature. Additionally, if the gRPC service requires TLS \nnginx.ingress.kubernetes.io/secure-backends: \"true\"\n\n\n\n\nImportant\n\n\nThis feature requires HTTP2 to work which means we need to expose this service using HTTPS.\n\n\n\n\nExposing a gRPC service using HTTP is not supported.", + "text": "Annotations\n\u00b6\n\n\nYou can add these Kubernetes annotations to specific Ingress objects to customize their behavior.\n\n\n\n\nTip\n\n\nAnnotation keys and values can only be strings.\nOther types, such as boolean or numeric values must be quoted,\ni.e. \n\"true\"\n, \n\"false\"\n, \n\"100\"\n.\n\n\n\n\n\n\nNote\n\n\nThe annotation prefix can be changed using the\n\n--annotations-prefix\n command line argument\n,\nbut the default is \nnginx.ingress.kubernetes.io\n, as described in the\ntable below.\n\n\n\n\n\n\n\n\n\n\nName\n\n\ntype\n\n\n\n\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/add-base-url\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/app-root\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/affinity\n\n\ncookie\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-realm\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-secret\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-type\n\n\nbasic or digest\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-tls-secret\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-tls-verify-depth\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-tls-verify-client\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-tls-error-page\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-url\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/base-url-scheme\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/client-body-buffer-size\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/configuration-snippet\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/default-backend\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/enable-cors\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-origin\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-methods\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-headers\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-credentials\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-max-age\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/force-ssl-redirect\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/from-to-www-redirect\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/grpc-backend\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/limit-connections\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/limit-rps\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/permanent-redirect\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-body-size\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-connect-timeout\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-send-timeout\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-read-timeout\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-next-upstream\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-next-upstream-tries\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-request-buffering\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-redirect-from\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-redirect-to\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/rewrite-log\n\n\nURI\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/rewrite-target\n\n\nURI\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/secure-backends\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/secure-verify-ca-secret\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/server-alias\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/server-snippet\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/service-upstream\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/session-cookie-name\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/session-cookie-hash\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/ssl-redirect\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/ssl-passthrough\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/upstream-max-fails\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/upstream-fail-timeout\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/upstream-hash-by\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/load-balance\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/upstream-vhost\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/whitelist-source-range\n\n\nCIDR\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-buffering\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/ssl-ciphers\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/connection-proxy-header\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/enable-access-log\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf-debug\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf-extra-rules\n\n\nstring\n\n\n\n\n\n\n\n\nRewrite\n\u00b6\n\n\nIn some scenarios the exposed URL in the backend service differs from the specified path in the Ingress rule. Without a rewrite any request will return 404.\nSet the annotation \nnginx.ingress.kubernetes.io/rewrite-target\n to the path expected by the service.\n\n\nIf the application contains relative links it is possible to add an additional annotation \nnginx.ingress.kubernetes.io/add-base-url\n that will prepend a \nbase\n tag\n in the header of the returned HTML from the backend.\n\n\nIf the scheme of \nbase\n tag\n need to be specific, set the annotation \nnginx.ingress.kubernetes.io/base-url-scheme\n to the scheme such as \nhttp\n and \nhttps\n.\n\n\nIf the Application Root is exposed in a different path and needs to be redirected, set the annotation \nnginx.ingress.kubernetes.io/app-root\n to redirect requests for \n/\n.\n\n\n\n\nExample\n\n\nPlease check the \nrewrite\n example.\n\n\n\n\nSession Affinity\n\u00b6\n\n\nThe annotation \nnginx.ingress.kubernetes.io/affinity\n enables and sets the affinity type in all Upstreams of an Ingress. This way, a request will always be directed to the same upstream server.\nThe only affinity type available for NGINX is \ncookie\n.\n\n\n\n\nExample\n\n\nPlease check the \naffinity\n example.\n\n\n\n\nCookie affinity\n\u00b6\n\n\nIf you use the \ncookie\n affinity type you can also specify the name of the cookie that will be used to route the requests with the annotation \nnginx.ingress.kubernetes.io/session-cookie-name\n. The default is to create a cookie named 'INGRESSCOOKIE'.\n\n\nIn case of NGINX the annotation \nnginx.ingress.kubernetes.io/session-cookie-hash\n defines which algorithm will be used to hash the used upstream. Default value is \nmd5\n and possible values are \nmd5\n, \nsha1\n and \nindex\n.\n\n\n\n\nAttention\n\n\nThe \nindex\n option is not an actual hash; an in-memory index is used instead, which has less overhead.\nHowever, with \nindex\n, matching against a changing upstream server list is inconsistent.\nSo, at reload, if upstream servers have changed, index values are not guaranteed to correspond to the same server as before!\n\nUse \nindex\n with caution\n and only if you need to!\n\n\n\n\nIn NGINX this feature is implemented by the third party module \nnginx-sticky-module-ng\n. The workflow used to define which upstream server will be used is explained \nhere\n\n\nAuthentication\n\u00b6\n\n\nIs possible to add authentication adding additional annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords inside the key \nauth\n.\n\n\nThe annotations are:\n\n\nnginx.ingress.kubernetes.io/auth-type: [basic|digest]\n\n\n\n\n\nIndicates the \nHTTP Authentication Type: Basic or Digest Access Authentication\n.\n\n\nnginx.ingress.kubernetes.io/auth-secret: secretName\n\n\n\n\n\nThe name of the Secret that contains the usernames and passwords which are granted access to the \npath\ns defined in the Ingress rules.\nThis annotation also accepts the alternative form \"namespace/secretName\", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace.\n\n\nnginx.ingress.kubernetes.io/auth-realm: \"realm string\"\n\n\n\n\n\n\n\nExample\n\n\nPlease check the \nauth\n example.\n\n\n\n\nCustom NGINX upstream checks\n\u00b6\n\n\nNGINX exposes some flags in the \nupstream configuration\n that enable the configuration of each server in the upstream. The Ingress controller allows custom \nmax_fails\n and \nfail_timeout\n parameters in a global context using \nupstream-max-fails\n and \nupstream-fail-timeout\n in the NGINX ConfigMap or in a particular Ingress rule. \nupstream-max-fails\n defaults to 0. This means NGINX will respect the container's \nreadinessProbe\n if it is defined. If there is no probe and no values for \nupstream-max-fails\n NGINX will continue to send traffic to the container.\n\n\n\n\nTip\n\n\nWith the default configuration NGINX will not health check your backends. Whenever the endpoints controller notices a readiness probe failure, that pod's IP will be removed from the list of endpoints. This will trigger the NGINX controller to also remove it from the upstreams.**\n\n\n\n\nTo use custom values in an Ingress rule define these annotations:\n\n\nnginx.ingress.kubernetes.io/upstream-max-fails\n: number of unsuccessful attempts to communicate with the server that should occur in the duration set by the \nupstream-fail-timeout\n parameter to consider the server unavailable.\n\n\nnginx.ingress.kubernetes.io/upstream-fail-timeout\n: time in seconds during which the specified number of unsuccessful attempts to communicate with the server should occur to consider the server unavailable. This is also the period of time the server will be considered unavailable.\n\n\nIn NGINX, backend server pools are called \"\nupstreams\n\". Each upstream contains the endpoints for a service. An upstream is created for each service that has Ingress rules defined.\n\n\n\n\nAttention\n\n\nAll Ingress rules using the same service will use the same upstream.\n\nOnly one of the Ingress rules should define annotations to configure the upstream servers.\n\n\n\n\n\n\nExample\n\n\nPlease check the \ncustom upstream check\n example.\n\n\n\n\nCustom NGINX upstream hashing\n\u00b6\n\n\nNGINX supports load balancing by client-server mapping based on \nconsistent hashing\n for a given key. The key can contain text, variables or any combination thereof. This feature allows for request stickiness other than client IP or cookies. The \nketama\n consistent hashing method will be used which ensures only a few keys would be remapped to different servers on upstream group changes.\n\n\nTo enable consistent hashing for a backend:\n\n\nnginx.ingress.kubernetes.io/upstream-hash-by\n: the nginx variable, text value or any combination thereof to use for consistent hashing. For example \nnginx.ingress.kubernetes.io/upstream-hash-by: \"$request_uri\"\n to consistently hash upstream requests by the current request URI.\n\n\nCustom NGINX load balancing\n\u00b6\n\n\nThis is similar to (https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/nginx-configuration/configmap.md#load-balance) but configures load balancing algorithm per ingress.\n\n\n\n\nNote that \nnginx.ingress.kubernetes.io/upstream-hash-by\n takes preference over this. If this and \nnginx.ingress.kubernetes.io/upstream-hash-by\n are not set then we fallback to using globally configured load balancing algorithm.\n\n\n\n\nCustom NGINX upstream vhost\n\u00b6\n\n\nThis configuration setting allows you to control the value for host in the following statement: \nproxy_set_header Host $host\n, which forms part of the location block. This is useful if you need to call the upstream server by something other than \n$host\n.\n\n\nClient Certificate Authentication\n\u00b6\n\n\nIt is possible to enable Client Certificate Authentication using additional annotations in Ingress Rule.\n\n\nThe annotations are:\n\n\n\n\nnginx.ingress.kubernetes.io/auth-tls-secret: secretName\n:\n The name of the Secret that contains the full Certificate Authority chain \nca.crt\n that is enabled to authenticate against this Ingress.\n This annotation also accepts the alternative form \"namespace/secretName\", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace.\n\n\nnginx.ingress.kubernetes.io/auth-tls-verify-depth\n:\n The validation depth between the provided client certificate and the Certification Authority chain.\n\n\nnginx.ingress.kubernetes.io/auth-tls-verify-client\n:\n Enables verification of client certificates.\n\n\nnginx.ingress.kubernetes.io/auth-tls-error-page\n:\n The URL/Page that user should be redirected in case of a Certificate Authentication Error\n\n\nnginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream\n:\n Indicates if the received certificates should be passed or not to the upstream server. By default this is disabled.\n\n\n\n\n\n\nExample\n\n\nPlease check the \nclient-certs\n example.\n\n\n\n\n\n\nAttention\n\n\nTLS with Client Authentication is \nnot\n possible in Cloudflare and might result in unexpected behavior.\n\n\nCloudflare only allows Authenticated Origin Pulls and is required to use their own certificate: \nhttps://blog.cloudflare.com/protecting-the-origin-with-tls-authenticated-origin-pulls/\n\n\nOnly Authenticated Origin Pulls are allowed and can be configured by following their tutorial: \nhttps://support.cloudflare.com/hc/en-us/articles/204494148-Setting-up-NGINX-to-use-TLS-Authenticated-Origin-Pulls\n\n\n\n\nConfiguration snippet\n\u00b6\n\n\nUsing this annotation you can add additional configuration to the NGINX location. For example:\n\n\nnginx.ingress.kubernetes.io/configuration-snippet\n:\n \n|\n\n \nmore_set_headers \"Request-Id: $req_id\";\n\n\n\n\n\n\nDefault Backend\n\u00b6\n\n\nThe ingress controller requires a \ndefault backend\n.\nThis service handles the response when the service in the Ingress rule does not have endpoints.\nThis is a global configuration for the ingress controller. In some cases could be required to return a custom content or format. In this scenario we can use the annotation \nnginx.ingress.kubernetes.io/default-backend: \n to specify a custom default backend.\n\n\nEnable CORS\n\u00b6\n\n\nTo enable Cross-Origin Resource Sharing (CORS) in an Ingress rule,\nadd the annotation \nnginx.ingress.kubernetes.io/enable-cors: \"true\"\n.\nThis will add a section in the server location enabling this functionality.\n\n\nCORS can be controlled with the following annotations:\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-methods\n\n controls which methods are accepted.\n This is a multi-valued field, separated by ',' and accepts only letters (upper and lower case).\n Example: \nnginx.ingress.kubernetes.io/cors-allow-methods: \"PUT, GET, POST, OPTIONS\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-headers\n\n controls which headers are accepted.\n This is a multi-valued field, separated by ',' and accepts letters, numbers, _ and -.\n Example: \nnginx.ingress.kubernetes.io/cors-allow-headers: \"X-Forwarded-For, X-app123-XPTO\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-origin\n\n controls what's the accepted Origin for CORS and defaults to '*'.\n This is a single field value, with the following format: \nhttp(s)://origin-site.com\n or \nhttp(s)://origin-site.com:port\n\n Example: \nnginx.ingress.kubernetes.io/cors-allow-origin: \"https://origin-site.com:4443\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-credentials\n\n controls if credentials can be passed during CORS operations.\n Example: \nnginx.ingress.kubernetes.io/cors-allow-credentials: \"true\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-max-age\n\n controls how long preflight requests can be cached.\n Example: \nnginx.ingress.kubernetes.io/cors-max-age: 600\n\n\n\n\n\n\n\n\nNote\n\n\nFor more information please see \nhttps://enable-cors.org\n\n\n\n\nServer Alias\n\u00b6\n\n\nTo add Server Aliases to an Ingress rule add the annotation \nnginx.ingress.kubernetes.io/server-alias: \"\"\n.\nThis will create a server with the same configuration, but a different \nserver_name\n as the provided host.\n\n\n\n\nNote\n\n\nA server-alias name cannot conflict with the hostname of an existing server. If it does the server-alias annotation will be ignored.\nIf a server-alias is created and later a new server with the same hostname is created,\nthe new server configuration will take place over the alias configuration.\n\n\n\n\nFor more information please see \nthe \nserver_name\n documentation\n.\n\n\nServer snippet\n\u00b6\n\n\nUsing the annotation \nnginx.ingress.kubernetes.io/server-snippet\n it is possible to add custom configuration in the server configuration block.\n\n\napiVersion\n:\n \nextensions/v1beta1\n\n\nkind\n:\n \nIngress\n\n\nmetadata\n:\n\n \nannotations\n:\n\n \nnginx.ingress.kubernetes.io/server-snippet\n:\n \n|\n\n\nset $agentflag 0;\n\n\n\nif ($http_user_agent ~* \"(Mobile)\" ){\n\n \nset $agentflag 1;\n\n\n}\n\n\n\nif ( $agentflag = 1 ) {\n\n \nreturn 301 https://m.example.com;\n\n\n}\n\n\n\n\n\n\n\n\nAttention\n\n\nThis annotation can be used only once per host.\n\n\n\n\nClient Body Buffer Size\n\u00b6\n\n\nSets buffer size for reading client request body per location. In case the request body is larger than the buffer,\nthe whole body or only its part is written to a temporary file. By default, buffer size is equal to two memory pages.\nThis is 8K on x86, other 32-bit platforms, and x86-64. It is usually 16K on other 64-bit platforms. This annotation is\napplied to each location provided in the ingress rule.\n\n\n\n\nNote\n\n\nThe annotation value must be given in a format understood by Nginx.\n\n\n\n\n\n\nExample\n\n\n\n\nnginx.ingress.kubernetes.io/client-body-buffer-size: \"1000\"\n # 1000 bytes\n\n\nnginx.ingress.kubernetes.io/client-body-buffer-size: 1k\n # 1 kilobyte\n\n\nnginx.ingress.kubernetes.io/client-body-buffer-size: 1K\n # 1 kilobyte\n\n\nnginx.ingress.kubernetes.io/client-body-buffer-size: 1m\n # 1 megabyte\n\n\nnginx.ingress.kubernetes.io/client-body-buffer-size: 1M\n # 1 megabyte\n\n\n\n\n\n\nFor more information please see \nhttp://nginx.org\n\n\nExternal Authentication\n\u00b6\n\n\nTo use an existing service that provides authentication the Ingress rule can be annotated with \nnginx.ingress.kubernetes.io/auth-url\n to indicate the URL where the HTTP request should be sent.\n\n\nnginx.ingress.kubernetes.io/auth-url\n:\n \n\"URL\n \nto\n \nthe\n \nauthentication\n \nservice\"\n\n\n\n\n\n\nAdditionally it is possible to set:\n\n\n\n\nnginx.ingress.kubernetes.io/auth-method\n:\n \n\n to specify the HTTP method to use.\n\n\nnginx.ingress.kubernetes.io/auth-signin\n:\n \n\n to specify the location of the error page.\n\n\nnginx.ingress.kubernetes.io/auth-response-headers\n:\n \n\n to specify headers to pass to backend once authorization request completes.\n\n\nnginx.ingress.kubernetes.io/auth-request-redirect\n:\n \n\n to specify the X-Auth-Request-Redirect header value.\n\n\n\n\n\n\nExample\n\n\nPlease check the \nexternal-auth\n example.\n\n\n\n\nRate limiting\n\u00b6\n\n\nThese annotations define a limit on the connections that can be opened by a single client IP address.\nThis can be used to mitigate \nDDoS Attacks\n.\n\n\n\n\nnginx.ingress.kubernetes.io/limit-connections\n: number of concurrent connections allowed from a single IP address.\n\n\nnginx.ingress.kubernetes.io/limit-rps\n: number of connections that may be accepted from a given IP each second.\n\n\nnginx.ingress.kubernetes.io/limit-rpm\n: number of connections that may be accepted from a given IP each minute.\n\n\nnginx.ingress.kubernetes.io/limit-rate-after\n: sets the initial amount after which the further transmission of a response to a client will be rate limited.\n\n\nnginx.ingress.kubernetes.io/limit-rate\n: rate of request that accepted from a client each second.\n\n\n\n\nYou can specify the client IP source ranges to be excluded from rate-limiting through the \nnginx.ingress.kubernetes.io/limit-whitelist\n annotation. The value is a comma separated list of CIDRs.\n\n\nIf you specify multiple annotations in a single Ingress rule, \nlimit-rpm\n, and then \nlimit-rps\n takes precedence.\n\n\nThe annotation \nnginx.ingress.kubernetes.io/limit-rate\n, \nnginx.ingress.kubernetes.io/limit-rate-after\n define a limit the rate of response transmission to a client. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit.\n\n\nTo configure this setting globally for all Ingress rules, the \nlimit-rate-after\n and \nlimit-rate\n value may be set in the \nNGINX ConfigMap\n. if you set the value in ingress annotation will cover global setting.\n\n\nPermanent Redirect\n\u00b6\n\n\nThis annotation allows to return a permanent redirect instead of sending data to the upstream. For example \nnginx.ingress.kubernetes.io/permanent-redirect: https://www.google.com\n would redirect everything to Google.\n\n\nSSL Passthrough\n\u00b6\n\n\nThe annotation \nnginx.ingress.kubernetes.io/ssl-passthrough\n allows to configure TLS termination in the pod and not in NGINX.\n\n\n\n\nAttention\n\n\nUsing the annotation \nnginx.ingress.kubernetes.io/ssl-passthrough\n invalidates all the other available annotations.\nThis is because SSL Passthrough works on level 4 of the OSI stack (TCP), not on the HTTP/HTTPS level.\n\n\n\n\n\n\nAttention\n\n\nThe use of this annotation requires the Proxy Protocol to be enabled in the front-end load-balancer.\nFor example enabling Proxy Protocol for AWS ELB is described \nhere\n.\nIf you're using ingress-controller without load balancer then the flag\n\n--enable-ssl-passthrough\n is required (by default it is disabled).\n\n\n\n\nSecure backends\n\u00b6\n\n\nBy default NGINX uses plain HTTP to reach the services.\nAdding the annotation \nnginx.ingress.kubernetes.io/secure-backends: \"true\"\n in the Ingress rule changes the protocol to HTTPS.\nIf you want to validate the upstream against a specific certificate, you can create a secret with it and reference the secret with the annotation \nnginx.ingress.kubernetes.io/secure-verify-ca-secret\n.\n\n\n\n\nAttention\n\n\nNote that if an invalid or non-existent secret is given,\nthe ingress controller will ignore the \nsecure-backends\n annotation.\n\n\n\n\nService Upstream\n\u00b6\n\n\nBy default the NGINX ingress controller uses a list of all endpoints (Pod IP/port) in the NGINX upstream configuration.\n\n\nThe \nnginx.ingress.kubernetes.io/service-upstream\n annotation disables that behavior and instead uses a single upstream in NGINX, the service's Cluster IP and port.\n\n\nThis can be desirable for things like zero-downtime deployments as it reduces the need to reload NGINX configuration when Pods come up and down. See issue \n#257\n.\n\n\nKnown Issues\n\u00b6\n\n\nIf the \nservice-upstream\n annotation is specified the following things should be taken into consideration:\n\n\n\n\nSticky Sessions will not work as only round-robin load balancing is supported.\n\n\nThe \nproxy_next_upstream\n directive will not have any effect meaning on error the request will not be dispatched to another upstream.\n\n\n\n\nServer-side HTTPS enforcement through redirect\n\u00b6\n\n\nBy default the controller redirects (308) to HTTPS if TLS is enabled for that ingress.\nIf you want to disable this behavior globally, you can use \nssl-redirect: \"false\"\n in the NGINX \nconfig map\n.\n\n\nTo configure this feature for specific ingress resources, you can use the \nnginx.ingress.kubernetes.io/ssl-redirect: \"false\"\n\nannotation in the particular resource.\n\n\nWhen using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to HTTPS\neven when there is no TLS certificate available.\nThis can be achieved by using the \nnginx.ingress.kubernetes.io/force-ssl-redirect: \"true\"\n annotation in the particular resource.\n\n\nRedirect from/to www.\n\u00b6\n\n\nIn some scenarios is required to redirect from \nwww.domain.com\n to \ndomain.com\n or vice versa.\nTo enable this feature use the annotation \nnginx.ingress.kubernetes.io/from-to-www-redirect: \"true\"\n\n\n\n\nAttention\n\n\nIf at some point a new Ingress is created with a host equal to one of the options (like \ndomain.com\n) the annotation will be omitted.\n\n\n\n\nWhitelist source range\n\u00b6\n\n\nYou can specify allowed client IP source ranges through the \nnginx.ingress.kubernetes.io/whitelist-source-range\n annotation.\nThe value is a comma separated list of \nCIDRs\n, e.g. \n10.0.0.0/24,172.10.0.1\n.\n\n\nTo configure this setting globally for all Ingress rules, the \nwhitelist-source-range\n value may be set in the \nNGINX ConfigMap\n.\n\n\n\n\nNote\n\n\nAdding an annotation to an Ingress rule overrides any global restriction.\n\n\n\n\nCustom timeouts\n\u00b6\n\n\nUsing the configuration configmap it is possible to set the default global timeout for connections to the upstream servers.\nIn some scenarios is required to have different values. To allow this we provide annotations that allows this customization:\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-connect-timeout\n\n\nnginx.ingress.kubernetes.io/proxy-send-timeout\n\n\nnginx.ingress.kubernetes.io/proxy-read-timeout\n\n\nnginx.ingress.kubernetes.io/proxy-next-upstream\n\n\nnginx.ingress.kubernetes.io/proxy-next-upstream-tries\n\n\nnginx.ingress.kubernetes.io/proxy-request-buffering\n\n\n\n\nProxy redirect\n\u00b6\n\n\nWith the annotations \nnginx.ingress.kubernetes.io/proxy-redirect-from\n and \nnginx.ingress.kubernetes.io/proxy-redirect-to\n it is possible to set the text that should be changed in the \nLocation\n and \nRefresh\n header fields of a proxied server response (http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect)\n\n\nSetting \"off\" or \"default\" in the annotation \nnginx.ingress.kubernetes.io/proxy-redirect-from\n disables \nnginx.ingress.kubernetes.io/proxy-redirect-to\n.\n\n\nBoth annotations will be used in any other case. By default the value is \"off\".\n\n\nCustom max body size\n\u00b6\n\n\nFor NGINX, an 413 error will be returned to the client when the size in a request exceeds the maximum allowed size of the client request body. This size can be configured by the parameter \nclient_max_body_size\n.\n\n\nTo configure this setting globally for all Ingress rules, the \nproxy-body-size\n value may be set in the \nNGINX ConfigMap\n.\nTo use custom values in an Ingress rule define these annotation:\n\n\nnginx.ingress.kubernetes.io/proxy-body-size\n:\n \n8m\n\n\n\n\n\n\nProxy buffering\n\u00b6\n\n\nEnable or disable proxy buffering \nproxy_buffering\n.\nBy default proxy buffering is disabled in the NGINX config.\n\n\nTo configure this setting globally for all Ingress rules, the \nproxy-buffering\n value may be set in the \nNGINX ConfigMap\n.\nTo use custom values in an Ingress rule define these annotation:\n\n\nnginx.ingress.kubernetes.io/proxy-buffering\n:\n \n\"on\"\n\n\n\n\n\n\nSSL ciphers\n\u00b6\n\n\nSpecifies the \nenabled ciphers\n.\n\n\nUsing this annotation will set the \nssl_ciphers\n directive at the server level. This configuration is active for all the paths in the host.\n\n\nnginx.ingress.kubernetes.io/ssl-ciphers\n:\n \n\"ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP\"\n\n\n\n\n\n\nConnection proxy header\n\u00b6\n\n\nUsing this annotation will override the default connection header set by NGINX.\nTo use custom values in an Ingress rule, define the annotation:\n\n\nnginx.ingress.kubernetes.io/connection-proxy-header\n:\n \n\"keep-alive\"\n\n\n\n\n\n\nEnable Access Log\n\u00b6\n\n\nAccess logs are enabled by default, but in some scenarios access logs might be required to be disabled for a given\ningress. To do this, use the annotation:\n\n\nnginx.ingress.kubernetes.io/enable-access-log\n:\n \n\"false\"\n\n\n\n\n\n\nEnable Rewrite Log\n\u00b6\n\n\nRewrite logs are not enabled by default. In some scenarios it could be required to enable NGINX rewrite logs.\nNote that rewrite logs are sent to the error_log file at the notice level. To enable this feature use the annotation:\n\n\nnginx.ingress.kubernetes.io/enable-rewrite-log\n:\n \n\"true\"\n\n\n\n\n\n\nLua Resty WAF\n\u00b6\n\n\nUsing \nlua-resty-waf-*\n annotations we can enable and control the \nlua-resty-waf\n\nWeb Application Firewall per location.\n\n\nFollowing configuration will enable the WAF for the paths defined in the corresponding ingress:\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf\n:\n \n\"active\"\n\n\n\n\n\n\nIn order to run it in debugging mode you can set \nnginx.ingress.kubernetes.io/lua-resty-waf-debug\n to \n\"true\"\n in addition to the above configuration.\nThe other possible values for \nnginx.ingress.kubernetes.io/lua-resty-waf\n are \ninactive\n and \nsimulate\n.\nIn \ninactive\n mode WAF won't do anything, whereas in \nsimulate\n mode it will log a warning message if there's a matching WAF rule for given request. This is useful to debug a rule and eliminate possible false positives before fully deploying it.\n\n\nlua-resty-waf\n comes with predefined set of rules \nhttps://github.com/p0pr0ck5/lua-resty-waf/tree/84b4f40362500dd0cb98b9e71b5875cb1a40f1ad/rules\n that covers ModSecurity CRS.\nYou can use \nnginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets\n to ignore a subset of those rulesets. For an example:\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets\n:\n \n\"41000_sqli,\n \n42000_xss\"\n\n\n\n\n\n\nwill ignore the two mentioned rulesets.\n\n\nIt is also possible to configure custom WAF rules per ingress using the \nnginx.ingress.kubernetes.io/lua-resty-waf-extra-rules\n annotation. For an example the following snippet will configure a WAF rule to deny requests with query string value that contains word \nfoo\n:\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf-extra-rules\n:\n \n'[=[\n \n{\n \n\"access\":\n \n[\n \n{\n \n\"actions\":\n \n{\n \n\"disrupt\"\n \n:\n \n\"DENY\"\n \n},\n \n\"id\":\n \n10001,\n \n\"msg\":\n \n\"my\n \ncustom\n \nrule\",\n \n\"operator\":\n \n\"STR_CONTAINS\",\n \n\"pattern\":\n \n\"foo\",\n \n\"vars\":\n \n[\n \n{\n \n\"parse\":\n \n[\n \n\"values\",\n \n1\n \n],\n \n\"type\":\n \n\"REQUEST_ARGS\"\n \n}\n \n]\n \n}\n \n],\n \n\"body_filter\":\n \n[],\n \n\"header_filter\":[]\n \n}\n \n]=]'\n\n\n\n\n\n\nFor details on how to write WAF rules, please refer to \nhttps://github.com/p0pr0ck5/lua-resty-waf\n.\n\n\ngRPC backend\n\u00b6\n\n\nSince NGINX 1.13.10 it is possible to expose \ngRPC services natively\n\n\nYou only need to add the annotation \nnginx.ingress.kubernetes.io/grpc-backend: \"true\"\n to enable this feature.\nAdditionally, if the gRPC service requires TLS, add \nnginx.ingress.kubernetes.io/secure-backends: \"true\"\n.\n\n\n\n\nAttention\n\n\nThis feature requires HTTP2 to work which means we need to expose this service using HTTPS.\nExposing a gRPC service using HTTP is not supported.", "title": "Annotations" }, { "location": "/user-guide/nginx-configuration/annotations/#annotations", - "text": "You can add these Kubernetes annotations to specific Ingress objects to customize their behavior. Tip Annotation keys and values can only be strings.\nOther types, such as boolean or numeric values must be quoted,\ni.e. \"true\" , \"false\" , \"100\" . Name type nginx.ingress.kubernetes.io/add-base-url \"true\" or \"false\" nginx.ingress.kubernetes.io/app-root string nginx.ingress.kubernetes.io/affinity cookie nginx.ingress.kubernetes.io/auth-realm string nginx.ingress.kubernetes.io/auth-secret string nginx.ingress.kubernetes.io/auth-type basic or digest nginx.ingress.kubernetes.io/auth-tls-secret string nginx.ingress.kubernetes.io/auth-tls-verify-depth number nginx.ingress.kubernetes.io/auth-tls-verify-client string nginx.ingress.kubernetes.io/auth-tls-error-page string nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream \"true\" or \"false\" nginx.ingress.kubernetes.io/auth-url string nginx.ingress.kubernetes.io/base-url-scheme string nginx.ingress.kubernetes.io/client-body-buffer-size string nginx.ingress.kubernetes.io/configuration-snippet string nginx.ingress.kubernetes.io/default-backend string nginx.ingress.kubernetes.io/enable-cors \"true\" or \"false\" nginx.ingress.kubernetes.io/cors-allow-origin string nginx.ingress.kubernetes.io/cors-allow-methods string nginx.ingress.kubernetes.io/cors-allow-headers string nginx.ingress.kubernetes.io/cors-allow-credentials \"true\" or \"false\" nginx.ingress.kubernetes.io/cors-max-age number nginx.ingress.kubernetes.io/force-ssl-redirect \"true\" or \"false\" nginx.ingress.kubernetes.io/from-to-www-redirect \"true\" or \"false\" nginx.ingress.kubernetes.io/grpc-backend \"true\" or \"false\" nginx.ingress.kubernetes.io/limit-connections number nginx.ingress.kubernetes.io/limit-rps number nginx.ingress.kubernetes.io/permanent-redirect string nginx.ingress.kubernetes.io/proxy-body-size string nginx.ingress.kubernetes.io/proxy-connect-timeout number nginx.ingress.kubernetes.io/proxy-send-timeout number nginx.ingress.kubernetes.io/proxy-read-timeout number nginx.ingress.kubernetes.io/proxy-next-upstream string nginx.ingress.kubernetes.io/proxy-next-upstream-tries number nginx.ingress.kubernetes.io/proxy-request-buffering string nginx.ingress.kubernetes.io/proxy-redirect-from string nginx.ingress.kubernetes.io/proxy-redirect-to string nginx.ingress.kubernetes.io/rewrite-log URI nginx.ingress.kubernetes.io/rewrite-target URI nginx.ingress.kubernetes.io/secure-backends \"true\" or \"false\" nginx.ingress.kubernetes.io/secure-verify-ca-secret string nginx.ingress.kubernetes.io/server-alias string nginx.ingress.kubernetes.io/server-snippet string nginx.ingress.kubernetes.io/service-upstream \"true\" or \"false\" nginx.ingress.kubernetes.io/session-cookie-name string nginx.ingress.kubernetes.io/session-cookie-hash string nginx.ingress.kubernetes.io/ssl-redirect \"true\" or \"false\" nginx.ingress.kubernetes.io/ssl-passthrough \"true\" or \"false\" nginx.ingress.kubernetes.io/upstream-max-fails number nginx.ingress.kubernetes.io/upstream-fail-timeout number nginx.ingress.kubernetes.io/upstream-hash-by string nginx.ingress.kubernetes.io/load-balance string nginx.ingress.kubernetes.io/upstream-vhost string nginx.ingress.kubernetes.io/whitelist-source-range CIDR nginx.ingress.kubernetes.io/proxy-buffering string nginx.ingress.kubernetes.io/ssl-ciphers string nginx.ingress.kubernetes.io/connection-proxy-header string nginx.ingress.kubernetes.io/enable-access-log \"true\" or \"false\" nginx.ingress.kubernetes.io/lua-resty-waf string nginx.ingress.kubernetes.io/lua-resty-waf-debug \"true\" or \"false\" nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets string nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules string", + "text": "You can add these Kubernetes annotations to specific Ingress objects to customize their behavior. Tip Annotation keys and values can only be strings.\nOther types, such as boolean or numeric values must be quoted,\ni.e. \"true\" , \"false\" , \"100\" . Note The annotation prefix can be changed using the --annotations-prefix command line argument ,\nbut the default is nginx.ingress.kubernetes.io , as described in the\ntable below. Name type nginx.ingress.kubernetes.io/add-base-url \"true\" or \"false\" nginx.ingress.kubernetes.io/app-root string nginx.ingress.kubernetes.io/affinity cookie nginx.ingress.kubernetes.io/auth-realm string nginx.ingress.kubernetes.io/auth-secret string nginx.ingress.kubernetes.io/auth-type basic or digest nginx.ingress.kubernetes.io/auth-tls-secret string nginx.ingress.kubernetes.io/auth-tls-verify-depth number nginx.ingress.kubernetes.io/auth-tls-verify-client string nginx.ingress.kubernetes.io/auth-tls-error-page string nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream \"true\" or \"false\" nginx.ingress.kubernetes.io/auth-url string nginx.ingress.kubernetes.io/base-url-scheme string nginx.ingress.kubernetes.io/client-body-buffer-size string nginx.ingress.kubernetes.io/configuration-snippet string nginx.ingress.kubernetes.io/default-backend string nginx.ingress.kubernetes.io/enable-cors \"true\" or \"false\" nginx.ingress.kubernetes.io/cors-allow-origin string nginx.ingress.kubernetes.io/cors-allow-methods string nginx.ingress.kubernetes.io/cors-allow-headers string nginx.ingress.kubernetes.io/cors-allow-credentials \"true\" or \"false\" nginx.ingress.kubernetes.io/cors-max-age number nginx.ingress.kubernetes.io/force-ssl-redirect \"true\" or \"false\" nginx.ingress.kubernetes.io/from-to-www-redirect \"true\" or \"false\" nginx.ingress.kubernetes.io/grpc-backend \"true\" or \"false\" nginx.ingress.kubernetes.io/limit-connections number nginx.ingress.kubernetes.io/limit-rps number nginx.ingress.kubernetes.io/permanent-redirect string nginx.ingress.kubernetes.io/proxy-body-size string nginx.ingress.kubernetes.io/proxy-connect-timeout number nginx.ingress.kubernetes.io/proxy-send-timeout number nginx.ingress.kubernetes.io/proxy-read-timeout number nginx.ingress.kubernetes.io/proxy-next-upstream string nginx.ingress.kubernetes.io/proxy-next-upstream-tries number nginx.ingress.kubernetes.io/proxy-request-buffering string nginx.ingress.kubernetes.io/proxy-redirect-from string nginx.ingress.kubernetes.io/proxy-redirect-to string nginx.ingress.kubernetes.io/rewrite-log URI nginx.ingress.kubernetes.io/rewrite-target URI nginx.ingress.kubernetes.io/secure-backends \"true\" or \"false\" nginx.ingress.kubernetes.io/secure-verify-ca-secret string nginx.ingress.kubernetes.io/server-alias string nginx.ingress.kubernetes.io/server-snippet string nginx.ingress.kubernetes.io/service-upstream \"true\" or \"false\" nginx.ingress.kubernetes.io/session-cookie-name string nginx.ingress.kubernetes.io/session-cookie-hash string nginx.ingress.kubernetes.io/ssl-redirect \"true\" or \"false\" nginx.ingress.kubernetes.io/ssl-passthrough \"true\" or \"false\" nginx.ingress.kubernetes.io/upstream-max-fails number nginx.ingress.kubernetes.io/upstream-fail-timeout number nginx.ingress.kubernetes.io/upstream-hash-by string nginx.ingress.kubernetes.io/load-balance string nginx.ingress.kubernetes.io/upstream-vhost string nginx.ingress.kubernetes.io/whitelist-source-range CIDR nginx.ingress.kubernetes.io/proxy-buffering string nginx.ingress.kubernetes.io/ssl-ciphers string nginx.ingress.kubernetes.io/connection-proxy-header string nginx.ingress.kubernetes.io/enable-access-log \"true\" or \"false\" nginx.ingress.kubernetes.io/lua-resty-waf string nginx.ingress.kubernetes.io/lua-resty-waf-debug \"true\" or \"false\" nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets string nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules string", "title": "Annotations" }, { "location": "/user-guide/nginx-configuration/annotations/#rewrite", - "text": "In some scenarios the exposed URL in the backend service differs from the specified path in the Ingress rule. Without a rewrite any request will return 404.\nSet the annotation nginx.ingress.kubernetes.io/rewrite-target to the path expected by the service. If the application contains relative links it is possible to add an additional annotation nginx.ingress.kubernetes.io/add-base-url that will prepend a base tag in the header of the returned HTML from the backend. If the scheme of base tag need to be specific, set the annotation nginx.ingress.kubernetes.io/base-url-scheme to the scheme such as http and https . If the Application Root is exposed in a different path and needs to be redirected, set the annotation nginx.ingress.kubernetes.io/app-root to redirect requests for / . Please check the rewrite example.", + "text": "In some scenarios the exposed URL in the backend service differs from the specified path in the Ingress rule. Without a rewrite any request will return 404.\nSet the annotation nginx.ingress.kubernetes.io/rewrite-target to the path expected by the service. If the application contains relative links it is possible to add an additional annotation nginx.ingress.kubernetes.io/add-base-url that will prepend a base tag in the header of the returned HTML from the backend. If the scheme of base tag need to be specific, set the annotation nginx.ingress.kubernetes.io/base-url-scheme to the scheme such as http and https . If the Application Root is exposed in a different path and needs to be redirected, set the annotation nginx.ingress.kubernetes.io/app-root to redirect requests for / . Example Please check the rewrite example.", "title": "Rewrite" }, { "location": "/user-guide/nginx-configuration/annotations/#session-affinity", - "text": "The annotation nginx.ingress.kubernetes.io/affinity enables and sets the affinity type in all Upstreams of an Ingress. This way, a request will always be directed to the same upstream server.\nThe only affinity type available for NGINX is cookie . Please check the affinity example.", + "text": "The annotation nginx.ingress.kubernetes.io/affinity enables and sets the affinity type in all Upstreams of an Ingress. This way, a request will always be directed to the same upstream server.\nThe only affinity type available for NGINX is cookie . Example Please check the affinity example.", "title": "Session Affinity" }, + { + "location": "/user-guide/nginx-configuration/annotations/#cookie-affinity", + "text": "If you use the cookie affinity type you can also specify the name of the cookie that will be used to route the requests with the annotation nginx.ingress.kubernetes.io/session-cookie-name . The default is to create a cookie named 'INGRESSCOOKIE'. In case of NGINX the annotation nginx.ingress.kubernetes.io/session-cookie-hash defines which algorithm will be used to hash the used upstream. Default value is md5 and possible values are md5 , sha1 and index . Attention The index option is not an actual hash; an in-memory index is used instead, which has less overhead.\nHowever, with index , matching against a changing upstream server list is inconsistent.\nSo, at reload, if upstream servers have changed, index values are not guaranteed to correspond to the same server as before! Use index with caution and only if you need to! In NGINX this feature is implemented by the third party module nginx-sticky-module-ng . The workflow used to define which upstream server will be used is explained here", + "title": "Cookie affinity" + }, { "location": "/user-guide/nginx-configuration/annotations/#authentication", - "text": "Is possible to add authentication adding additional annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords inside the key auth . The annotations are: nginx.ingress.kubernetes.io/auth-type: [basic|digest] Indicates the HTTP Authentication Type: Basic or Digest Access Authentication . nginx.ingress.kubernetes.io/auth-secret: secretName The name of the Secret that contains the usernames and passwords which are granted access to the path s defined in the Ingress rules.\nThis annotation also accepts the alternative form \"namespace/secretName\", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace. nginx.ingress.kubernetes.io/auth-realm: \"realm string\" Please check the auth example.", + "text": "Is possible to add authentication adding additional annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords inside the key auth . The annotations are: nginx.ingress.kubernetes.io/auth-type: [basic|digest] Indicates the HTTP Authentication Type: Basic or Digest Access Authentication . nginx.ingress.kubernetes.io/auth-secret: secretName The name of the Secret that contains the usernames and passwords which are granted access to the path s defined in the Ingress rules.\nThis annotation also accepts the alternative form \"namespace/secretName\", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace. nginx.ingress.kubernetes.io/auth-realm: \"realm string\" Example Please check the auth example.", "title": "Authentication" }, { "location": "/user-guide/nginx-configuration/annotations/#custom-nginx-upstream-checks", - "text": "NGINX exposes some flags in the upstream configuration that enable the configuration of each server in the upstream. The Ingress controller allows custom max_fails and fail_timeout parameters in a global context using upstream-max-fails and upstream-fail-timeout in the NGINX ConfigMap or in a particular Ingress rule. upstream-max-fails defaults to 0. This means NGINX will respect the container's readinessProbe if it is defined. If there is no probe and no values for upstream-max-fails NGINX will continue to send traffic to the container. Tip With the default configuration NGINX will not health check your backends. Whenever the endpoints controller notices a readiness probe failure, that pod's IP will be removed from the list of endpoints. This will trigger the NGINX controller to also remove it from the upstreams.** To use custom values in an Ingress rule define these annotations: nginx.ingress.kubernetes.io/upstream-max-fails : number of unsuccessful attempts to communicate with the server that should occur in the duration set by the upstream-fail-timeout parameter to consider the server unavailable. nginx.ingress.kubernetes.io/upstream-fail-timeout : time in seconds during which the specified number of unsuccessful attempts to communicate with the server should occur to consider the server unavailable. This is also the period of time the server will be considered unavailable. In NGINX, backend server pools are called \" upstreams \". Each upstream contains the endpoints for a service. An upstream is created for each service that has Ingress rules defined. Important All Ingress rules using the same service will use the same upstream. Only one of the Ingress rules should define annotations to configure the upstream servers. Please check the custom upstream check example.", + "text": "NGINX exposes some flags in the upstream configuration that enable the configuration of each server in the upstream. The Ingress controller allows custom max_fails and fail_timeout parameters in a global context using upstream-max-fails and upstream-fail-timeout in the NGINX ConfigMap or in a particular Ingress rule. upstream-max-fails defaults to 0. This means NGINX will respect the container's readinessProbe if it is defined. If there is no probe and no values for upstream-max-fails NGINX will continue to send traffic to the container. Tip With the default configuration NGINX will not health check your backends. Whenever the endpoints controller notices a readiness probe failure, that pod's IP will be removed from the list of endpoints. This will trigger the NGINX controller to also remove it from the upstreams.** To use custom values in an Ingress rule define these annotations: nginx.ingress.kubernetes.io/upstream-max-fails : number of unsuccessful attempts to communicate with the server that should occur in the duration set by the upstream-fail-timeout parameter to consider the server unavailable. nginx.ingress.kubernetes.io/upstream-fail-timeout : time in seconds during which the specified number of unsuccessful attempts to communicate with the server should occur to consider the server unavailable. This is also the period of time the server will be considered unavailable. In NGINX, backend server pools are called \" upstreams \". Each upstream contains the endpoints for a service. An upstream is created for each service that has Ingress rules defined. Attention All Ingress rules using the same service will use the same upstream. \nOnly one of the Ingress rules should define annotations to configure the upstream servers. Example Please check the custom upstream check example.", "title": "Custom NGINX upstream checks" }, { @@ -212,7 +237,7 @@ }, { "location": "/user-guide/nginx-configuration/annotations/#client-certificate-authentication", - "text": "It is possible to enable Client Certificate Authentication using additional annotations in Ingress Rule. The annotations are: nginx.ingress.kubernetes.io/auth-tls-secret: secretName The name of the Secret that contains the full Certificate Authority chain ca.crt that is enabled to authenticate against this Ingress.\nThis annotation also accepts the alternative form \"namespace/secretName\", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace. nginx.ingress.kubernetes.io/auth-tls-verify-depth The validation depth between the provided client certificate and the Certification Authority chain. nginx.ingress.kubernetes.io/auth-tls-verify-client Enables verification of client certificates. nginx.ingress.kubernetes.io/auth-tls-error-page The URL/Page that user should be redirected in case of a Certificate Authentication Error nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream Indicates if the received certificates should be passed or not to the upstream server.\nBy default this is disabled. Please check the client-certs example. Important TLS with Client Authentication is NOT possible in Cloudflare as is not allowed it and might result in unexpected behavior. Cloudflare only allows Authenticated Origin Pulls and is required to use their own certificate: https://blog.cloudflare.com/protecting-the-origin-with-tls-authenticated-origin-pulls/ Only Authenticated Origin Pulls are allowed and can be configured by following their tutorial: https://support.cloudflare.com/hc/en-us/articles/204494148-Setting-up-NGINX-to-use-TLS-Authenticated-Origin-Pulls", + "text": "It is possible to enable Client Certificate Authentication using additional annotations in Ingress Rule. The annotations are: nginx.ingress.kubernetes.io/auth-tls-secret: secretName :\n The name of the Secret that contains the full Certificate Authority chain ca.crt that is enabled to authenticate against this Ingress.\n This annotation also accepts the alternative form \"namespace/secretName\", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace. nginx.ingress.kubernetes.io/auth-tls-verify-depth :\n The validation depth between the provided client certificate and the Certification Authority chain. nginx.ingress.kubernetes.io/auth-tls-verify-client :\n Enables verification of client certificates. nginx.ingress.kubernetes.io/auth-tls-error-page :\n The URL/Page that user should be redirected in case of a Certificate Authentication Error nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream :\n Indicates if the received certificates should be passed or not to the upstream server. By default this is disabled. Example Please check the client-certs example. Attention TLS with Client Authentication is not possible in Cloudflare and might result in unexpected behavior. Cloudflare only allows Authenticated Origin Pulls and is required to use their own certificate: https://blog.cloudflare.com/protecting-the-origin-with-tls-authenticated-origin-pulls/ Only Authenticated Origin Pulls are allowed and can be configured by following their tutorial: https://support.cloudflare.com/hc/en-us/articles/204494148-Setting-up-NGINX-to-use-TLS-Authenticated-Origin-Pulls", "title": "Client Certificate Authentication" }, { @@ -222,37 +247,37 @@ }, { "location": "/user-guide/nginx-configuration/annotations/#default-backend", - "text": "The ingress controller requires a default backend. This service handles the response when the service in the Ingress rule does not have endpoints.\nThis is a global configuration for the ingress controller. In some cases could be required to return a custom content or format. In this scenario we can use the annotation nginx.ingress.kubernetes.io/default-backend: to specify a custom default backend.", + "text": "The ingress controller requires a default backend .\nThis service handles the response when the service in the Ingress rule does not have endpoints.\nThis is a global configuration for the ingress controller. In some cases could be required to return a custom content or format. In this scenario we can use the annotation nginx.ingress.kubernetes.io/default-backend: to specify a custom default backend.", "title": "Default Backend" }, { "location": "/user-guide/nginx-configuration/annotations/#enable-cors", - "text": "To enable Cross-Origin Resource Sharing (CORS) in an Ingress rule add the annotation nginx.ingress.kubernetes.io/enable-cors: \"true\" . This will add a section in the server location enabling this functionality. CORS can be controlled with the following annotations: nginx.ingress.kubernetes.io/cors-allow-methods controls which methods are accepted. This is a multi-valued field, separated by ',' and accepts only letters (upper and lower case). Example: nginx.ingress.kubernetes.io/cors-allow-methods: \"PUT, GET, POST, OPTIONS\" nginx.ingress.kubernetes.io/cors-allow-headers controls which headers are accepted. This is a multi-valued field, separated by ',' and accepts letters, numbers, _ and -. Example: nginx.ingress.kubernetes.io/cors-allow-headers: \"X-Forwarded-For, X-app123-XPTO\" nginx.ingress.kubernetes.io/cors-allow-origin controls what's the accepted Origin for CORS and defaults to '*'. This is a single field value, with the following format: http(s)://origin-site.com or http(s)://origin-site.com:port Example: nginx.ingress.kubernetes.io/cors-allow-origin: \"https://origin-site.com:4443\" nginx.ingress.kubernetes.io/cors-allow-credentials controls if credentials can be passed during CORS operations. Example: nginx.ingress.kubernetes.io/cors-allow-credentials: \"true\" nginx.ingress.kubernetes.io/cors-max-age controls how long preflight requests can be cached. Example: nginx.ingress.kubernetes.io/cors-max-age: 600 For more information please see https://enable-cors.org", + "text": "To enable Cross-Origin Resource Sharing (CORS) in an Ingress rule,\nadd the annotation nginx.ingress.kubernetes.io/enable-cors: \"true\" .\nThis will add a section in the server location enabling this functionality. CORS can be controlled with the following annotations: nginx.ingress.kubernetes.io/cors-allow-methods \n controls which methods are accepted.\n This is a multi-valued field, separated by ',' and accepts only letters (upper and lower case).\n Example: nginx.ingress.kubernetes.io/cors-allow-methods: \"PUT, GET, POST, OPTIONS\" nginx.ingress.kubernetes.io/cors-allow-headers \n controls which headers are accepted.\n This is a multi-valued field, separated by ',' and accepts letters, numbers, _ and -.\n Example: nginx.ingress.kubernetes.io/cors-allow-headers: \"X-Forwarded-For, X-app123-XPTO\" nginx.ingress.kubernetes.io/cors-allow-origin \n controls what's the accepted Origin for CORS and defaults to '*'.\n This is a single field value, with the following format: http(s)://origin-site.com or http(s)://origin-site.com:port \n Example: nginx.ingress.kubernetes.io/cors-allow-origin: \"https://origin-site.com:4443\" nginx.ingress.kubernetes.io/cors-allow-credentials \n controls if credentials can be passed during CORS operations.\n Example: nginx.ingress.kubernetes.io/cors-allow-credentials: \"true\" nginx.ingress.kubernetes.io/cors-max-age \n controls how long preflight requests can be cached.\n Example: nginx.ingress.kubernetes.io/cors-max-age: 600 Note For more information please see https://enable-cors.org", "title": "Enable CORS" }, { "location": "/user-guide/nginx-configuration/annotations/#server-alias", - "text": "To add Server Aliases to an Ingress rule add the annotation nginx.ingress.kubernetes.io/server-alias: \"\" .\nThis will create a server with the same configuration, but a different server_name as the provided host. Note A server-alias name cannot conflict with the hostname of an existing server. If it does the server-alias annotation will be ignored. If a server-alias is created and later a new server with the same hostname is created the new server configuration will take place over the alias configuration. For more information please see http://nginx.org", + "text": "To add Server Aliases to an Ingress rule add the annotation nginx.ingress.kubernetes.io/server-alias: \"\" .\nThis will create a server with the same configuration, but a different server_name as the provided host. Note A server-alias name cannot conflict with the hostname of an existing server. If it does the server-alias annotation will be ignored.\nIf a server-alias is created and later a new server with the same hostname is created,\nthe new server configuration will take place over the alias configuration. For more information please see the server_name documentation .", "title": "Server Alias" }, { "location": "/user-guide/nginx-configuration/annotations/#server-snippet", - "text": "Using the annotation nginx.ingress.kubernetes.io/server-snippet it is possible to add custom configuration in the server configuration block. apiVersion : extensions/v1beta1 kind : Ingress metadata : \n annotations : \n nginx.ingress.kubernetes.io/server-snippet : | set $agentflag 0; if ($http_user_agent ~* \"(Mobile)\" ){ \n set $agentflag 1; } if ( $agentflag = 1 ) { \n return 301 https://m.example.com; } Important This annotation can be used only once per host", + "text": "Using the annotation nginx.ingress.kubernetes.io/server-snippet it is possible to add custom configuration in the server configuration block. apiVersion : extensions/v1beta1 kind : Ingress metadata : \n annotations : \n nginx.ingress.kubernetes.io/server-snippet : | set $agentflag 0; if ($http_user_agent ~* \"(Mobile)\" ){ \n set $agentflag 1; } if ( $agentflag = 1 ) { \n return 301 https://m.example.com; } Attention This annotation can be used only once per host.", "title": "Server snippet" }, { "location": "/user-guide/nginx-configuration/annotations/#client-body-buffer-size", - "text": "Sets buffer size for reading client request body per location. In case the request body is larger than the buffer,\nthe whole body or only its part is written to a temporary file. By default, buffer size is equal to two memory pages.\nThis is 8K on x86, other 32-bit platforms, and x86-64. It is usually 16K on other 64-bit platforms. This annotation is\napplied to each location provided in the ingress rule. Note: The annotation value must be given in a valid format otherwise the\nFor example to set the client-body-buffer-size the following can be done: nginx.ingress.kubernetes.io/client-body-buffer-size: \"1000\" # 1000 bytes nginx.ingress.kubernetes.io/client-body-buffer-size: 1k # 1 kilobyte nginx.ingress.kubernetes.io/client-body-buffer-size: 1K # 1 kilobyte nginx.ingress.kubernetes.io/client-body-buffer-size: 1m # 1 megabyte nginx.ingress.kubernetes.io/client-body-buffer-size: 1M # 1 megabyte For more information please see http://nginx.org", + "text": "Sets buffer size for reading client request body per location. In case the request body is larger than the buffer,\nthe whole body or only its part is written to a temporary file. By default, buffer size is equal to two memory pages.\nThis is 8K on x86, other 32-bit platforms, and x86-64. It is usually 16K on other 64-bit platforms. This annotation is\napplied to each location provided in the ingress rule. Note The annotation value must be given in a format understood by Nginx. Example nginx.ingress.kubernetes.io/client-body-buffer-size: \"1000\" # 1000 bytes nginx.ingress.kubernetes.io/client-body-buffer-size: 1k # 1 kilobyte nginx.ingress.kubernetes.io/client-body-buffer-size: 1K # 1 kilobyte nginx.ingress.kubernetes.io/client-body-buffer-size: 1m # 1 megabyte nginx.ingress.kubernetes.io/client-body-buffer-size: 1M # 1 megabyte For more information please see http://nginx.org", "title": "Client Body Buffer Size" }, { "location": "/user-guide/nginx-configuration/annotations/#external-authentication", - "text": "To use an existing service that provides authentication the Ingress rule can be annotated with nginx.ingress.kubernetes.io/auth-url to indicate the URL where the HTTP request should be sent. nginx.ingress.kubernetes.io/auth-url : \"URL to the authentication service\" Additionally it is possible to set: nginx.ingress.kubernetes.io/auth-method : to specify the HTTP method to use. nginx.ingress.kubernetes.io/auth-signin : to specify the location of the error page. nginx.ingress.kubernetes.io/auth-response-headers : to specify headers to pass to backend once authorization request completes. nginx.ingress.kubernetes.io/auth-request-redirect : to specify the X-Auth-Request-Redirect header value. Please check the external-auth example.", + "text": "To use an existing service that provides authentication the Ingress rule can be annotated with nginx.ingress.kubernetes.io/auth-url to indicate the URL where the HTTP request should be sent. nginx.ingress.kubernetes.io/auth-url : \"URL to the authentication service\" Additionally it is possible to set: nginx.ingress.kubernetes.io/auth-method :\n to specify the HTTP method to use. nginx.ingress.kubernetes.io/auth-signin :\n to specify the location of the error page. nginx.ingress.kubernetes.io/auth-response-headers :\n to specify headers to pass to backend once authorization request completes. nginx.ingress.kubernetes.io/auth-request-redirect :\n to specify the X-Auth-Request-Redirect header value. Example Please check the external-auth example.", "title": "External Authentication" }, { "location": "/user-guide/nginx-configuration/annotations/#rate-limiting", - "text": "The annotations nginx.ingress.kubernetes.io/limit-connections , nginx.ingress.kubernetes.io/limit-rps , and nginx.ingress.kubernetes.io/limit-rpm define a limit on the connections that can be opened by a single client IP address. This can be used to mitigate DDoS Attacks . nginx.ingress.kubernetes.io/limit-connections : number of concurrent connections allowed from a single IP address. nginx.ingress.kubernetes.io/limit-rps : number of connections that may be accepted from a given IP each second. nginx.ingress.kubernetes.io/limit-rpm : number of connections that may be accepted from a given IP each minute. You can specify the client IP source ranges to be excluded from rate-limiting through the nginx.ingress.kubernetes.io/limit-whitelist annotation. The value is a comma separated list of CIDRs. If you specify multiple annotations in a single Ingress rule, limit-rpm , and then limit-rps takes precedence. The annotation nginx.ingress.kubernetes.io/limit-rate , nginx.ingress.kubernetes.io/limit-rate-after define a limit the rate of response transmission to a client. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit. nginx.ingress.kubernetes.io/limit-rate-after : sets the initial amount after which the further transmission of a response to a client will be rate limited. nginx.ingress.kubernetes.io/limit-rate : rate of request that accepted from a client each second. To configure this setting globally for all Ingress rules, the limit-rate-after and limit-rate value may be set in the NGINX ConfigMap. if you set the value in ingress annotation will cover global setting.", + "text": "These annotations define a limit on the connections that can be opened by a single client IP address.\nThis can be used to mitigate DDoS Attacks . nginx.ingress.kubernetes.io/limit-connections : number of concurrent connections allowed from a single IP address. nginx.ingress.kubernetes.io/limit-rps : number of connections that may be accepted from a given IP each second. nginx.ingress.kubernetes.io/limit-rpm : number of connections that may be accepted from a given IP each minute. nginx.ingress.kubernetes.io/limit-rate-after : sets the initial amount after which the further transmission of a response to a client will be rate limited. nginx.ingress.kubernetes.io/limit-rate : rate of request that accepted from a client each second. You can specify the client IP source ranges to be excluded from rate-limiting through the nginx.ingress.kubernetes.io/limit-whitelist annotation. The value is a comma separated list of CIDRs. If you specify multiple annotations in a single Ingress rule, limit-rpm , and then limit-rps takes precedence. The annotation nginx.ingress.kubernetes.io/limit-rate , nginx.ingress.kubernetes.io/limit-rate-after define a limit the rate of response transmission to a client. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit. To configure this setting globally for all Ingress rules, the limit-rate-after and limit-rate value may be set in the NGINX ConfigMap . if you set the value in ingress annotation will cover global setting.", "title": "Rate limiting" }, { @@ -262,17 +287,17 @@ }, { "location": "/user-guide/nginx-configuration/annotations/#ssl-passthrough", - "text": "The annotation nginx.ingress.kubernetes.io/ssl-passthrough allows to configure TLS termination in the pod and not in NGINX. Important Using the annotation nginx.ingress.kubernetes.io/ssl-passthrough invalidates all the other available annotations. This is because SSL Passthrough works in L4 (TCP). The use of this annotation requires Proxy Protocol to be enabled in the load-balancer. For example enabling Proxy Protocol for AWS ELB is described here . If you're using ingress-controller without load balancer then the flag --enable-ssl-passthrough is required (by default it is disabled).", + "text": "The annotation nginx.ingress.kubernetes.io/ssl-passthrough allows to configure TLS termination in the pod and not in NGINX. Attention Using the annotation nginx.ingress.kubernetes.io/ssl-passthrough invalidates all the other available annotations.\nThis is because SSL Passthrough works on level 4 of the OSI stack (TCP), not on the HTTP/HTTPS level. Attention The use of this annotation requires the Proxy Protocol to be enabled in the front-end load-balancer.\nFor example enabling Proxy Protocol for AWS ELB is described here .\nIf you're using ingress-controller without load balancer then the flag --enable-ssl-passthrough is required (by default it is disabled).", "title": "SSL Passthrough" }, { "location": "/user-guide/nginx-configuration/annotations/#secure-backends", - "text": "By default NGINX uses http to reach the services. Adding the annotation nginx.ingress.kubernetes.io/secure-backends: \"true\" in the Ingress rule changes the protocol to https .\nIf you want to validate the upstream against a specific certificate, you can create a secret with it and reference the secret with the annotation nginx.ingress.kubernetes.io/secure-verify-ca-secret . Note that if an invalid or non-existent secret is given, the NGINX ingress controller will ignore the secure-backends annotation.", + "text": "By default NGINX uses plain HTTP to reach the services.\nAdding the annotation nginx.ingress.kubernetes.io/secure-backends: \"true\" in the Ingress rule changes the protocol to HTTPS.\nIf you want to validate the upstream against a specific certificate, you can create a secret with it and reference the secret with the annotation nginx.ingress.kubernetes.io/secure-verify-ca-secret . Attention Note that if an invalid or non-existent secret is given,\nthe ingress controller will ignore the secure-backends annotation.", "title": "Secure backends" }, { "location": "/user-guide/nginx-configuration/annotations/#service-upstream", - "text": "By default the NGINX ingress controller uses a list of all endpoints (Pod IP/port) in the NGINX upstream configuration. This annotation disables that behavior and instead uses a single upstream in NGINX, the service's Cluster IP and port. This can be desirable for things like zero-downtime deployments as it reduces the need to reload NGINX configuration when Pods come up and down. See issue #257 .", + "text": "By default the NGINX ingress controller uses a list of all endpoints (Pod IP/port) in the NGINX upstream configuration. The nginx.ingress.kubernetes.io/service-upstream annotation disables that behavior and instead uses a single upstream in NGINX, the service's Cluster IP and port. This can be desirable for things like zero-downtime deployments as it reduces the need to reload NGINX configuration when Pods come up and down. See issue #257 .", "title": "Service Upstream" }, { @@ -282,24 +307,19 @@ }, { "location": "/user-guide/nginx-configuration/annotations/#server-side-https-enforcement-through-redirect", - "text": "By default the controller redirects (301) to HTTPS if TLS is enabled for that ingress. If you want to disable that behavior globally, you can use ssl-redirect: \"false\" in the NGINX config map. To configure this feature for specific ingress resources, you can use the nginx.ingress.kubernetes.io/ssl-redirect: \"false\" annotation in the particular resource. When using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to HTTPS even when there is not TLS cert available. This can be achieved by using the nginx.ingress.kubernetes.io/force-ssl-redirect: \"true\" annotation in the particular resource.", + "text": "By default the controller redirects (308) to HTTPS if TLS is enabled for that ingress.\nIf you want to disable this behavior globally, you can use ssl-redirect: \"false\" in the NGINX config map . To configure this feature for specific ingress resources, you can use the nginx.ingress.kubernetes.io/ssl-redirect: \"false\" \nannotation in the particular resource. When using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to HTTPS\neven when there is no TLS certificate available.\nThis can be achieved by using the nginx.ingress.kubernetes.io/force-ssl-redirect: \"true\" annotation in the particular resource.", "title": "Server-side HTTPS enforcement through redirect" }, { - "location": "/user-guide/nginx-configuration/annotations/#redirect-from-to-www", - "text": "In some scenarios is required to redirect from www.domain.com to domain.com or viceversa.\nTo enable this feature use the annotation nginx.ingress.kubernetes.io/from-to-www-redirect: \"true\" Important If at some point a new Ingress is created with a host equal to one of the options (like domain.com ) the annotation will be omitted.", - "title": "Redirect from to www" + "location": "/user-guide/nginx-configuration/annotations/#redirect-fromto-www", + "text": "In some scenarios is required to redirect from www.domain.com to domain.com or vice versa.\nTo enable this feature use the annotation nginx.ingress.kubernetes.io/from-to-www-redirect: \"true\" Attention If at some point a new Ingress is created with a host equal to one of the options (like domain.com ) the annotation will be omitted.", + "title": "Redirect from/to www." }, { "location": "/user-guide/nginx-configuration/annotations/#whitelist-source-range", - "text": "You can specify the allowed client IP source ranges through the nginx.ingress.kubernetes.io/whitelist-source-range annotation. The value is a comma separated list of CIDRs , e.g. 10.0.0.0/24,172.10.0.1 . To configure this setting globally for all Ingress rules, the whitelist-source-range value may be set in the NGINX ConfigMap. Note: Adding an annotation to an Ingress rule overrides any global restriction.", + "text": "You can specify allowed client IP source ranges through the nginx.ingress.kubernetes.io/whitelist-source-range annotation.\nThe value is a comma separated list of CIDRs , e.g. 10.0.0.0/24,172.10.0.1 . To configure this setting globally for all Ingress rules, the whitelist-source-range value may be set in the NGINX ConfigMap . Note Adding an annotation to an Ingress rule overrides any global restriction.", "title": "Whitelist source range" }, - { - "location": "/user-guide/nginx-configuration/annotations/#cookie-affinity", - "text": "If you use the cookie type you can also specify the name of the cookie that will be used to route the requests with the annotation nginx.ingress.kubernetes.io/session-cookie-name . The default is to create a cookie named 'INGRESSCOOKIE'. In case of NGINX the annotation nginx.ingress.kubernetes.io/session-cookie-hash defines which algorithm will be used to 'hash' the used upstream. Default value is md5 and possible values are md5 , sha1 and index .\nThe index option is not hashed, an in-memory index is used instead, it's quicker and the overhead is shorter Warning: the matching against upstream servers list is inconsistent. So, at reload, if upstreams servers has changed, index values are not guaranteed to correspond to the same server as before! USE IT WITH CAUTION and only if you need to! In NGINX this feature is implemented by the third party module nginx-sticky-module-ng . The workflow used to define which upstream server will be used is explained here", - "title": "Cookie affinity" - }, { "location": "/user-guide/nginx-configuration/annotations/#custom-timeouts", "text": "Using the configuration configmap it is possible to set the default global timeout for connections to the upstream servers.\nIn some scenarios is required to have different values. To allow this we provide annotations that allows this customization: nginx.ingress.kubernetes.io/proxy-connect-timeout nginx.ingress.kubernetes.io/proxy-send-timeout nginx.ingress.kubernetes.io/proxy-read-timeout nginx.ingress.kubernetes.io/proxy-next-upstream nginx.ingress.kubernetes.io/proxy-next-upstream-tries nginx.ingress.kubernetes.io/proxy-request-buffering", @@ -307,17 +327,17 @@ }, { "location": "/user-guide/nginx-configuration/annotations/#proxy-redirect", - "text": "With the annotations nginx.ingress.kubernetes.io/proxy-redirect-from and nginx.ingress.kubernetes.io/proxy-redirect-to it is possible to set the text that should be changed in the Location and Refresh header fields of a proxied server response (http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect)\nSetting \"off\" or \"default\" in the annotation nginx.ingress.kubernetes.io/proxy-redirect-from disables nginx.ingress.kubernetes.io/proxy-redirect-to \nBoth annotations will be used in any other case\nBy default the value is \"off\".", + "text": "With the annotations nginx.ingress.kubernetes.io/proxy-redirect-from and nginx.ingress.kubernetes.io/proxy-redirect-to it is possible to set the text that should be changed in the Location and Refresh header fields of a proxied server response (http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect) Setting \"off\" or \"default\" in the annotation nginx.ingress.kubernetes.io/proxy-redirect-from disables nginx.ingress.kubernetes.io/proxy-redirect-to . Both annotations will be used in any other case. By default the value is \"off\".", "title": "Proxy redirect" }, { "location": "/user-guide/nginx-configuration/annotations/#custom-max-body-size", - "text": "For NGINX, 413 error will be returned to the client when the size in a request exceeds the maximum allowed size of the client request body. This size can be configured by the parameter client_max_body_size . To configure this setting globally for all Ingress rules, the proxy-body-size value may be set in the NGINX ConfigMap.\nTo use custom values in an Ingress rule define these annotation: nginx.ingress.kubernetes.io/proxy-body-size : 8m", + "text": "For NGINX, an 413 error will be returned to the client when the size in a request exceeds the maximum allowed size of the client request body. This size can be configured by the parameter client_max_body_size . To configure this setting globally for all Ingress rules, the proxy-body-size value may be set in the NGINX ConfigMap .\nTo use custom values in an Ingress rule define these annotation: nginx.ingress.kubernetes.io/proxy-body-size : 8m", "title": "Custom max body size" }, { "location": "/user-guide/nginx-configuration/annotations/#proxy-buffering", - "text": "Enable or disable proxy buffering proxy_buffering .\nBy default proxy buffering is disabled in the nginx config. To configure this setting globally for all Ingress rules, the proxy-buffering value may be set in the NGINX ConfigMap.\nTo use custom values in an Ingress rule define these annotation: nginx.ingress.kubernetes.io/proxy-buffering : \"on\"", + "text": "Enable or disable proxy buffering proxy_buffering .\nBy default proxy buffering is disabled in the NGINX config. To configure this setting globally for all Ingress rules, the proxy-buffering value may be set in the NGINX ConfigMap .\nTo use custom values in an Ingress rule define these annotation: nginx.ingress.kubernetes.io/proxy-buffering : \"on\"", "title": "Proxy buffering" }, { @@ -327,27 +347,27 @@ }, { "location": "/user-guide/nginx-configuration/annotations/#connection-proxy-header", - "text": "Using this annotation will override the default connection header set by nginx. To use custom values in an Ingress rule, define the annotation: nginx.ingress.kubernetes.io/connection-proxy-header : \"keep-alive\"", + "text": "Using this annotation will override the default connection header set by NGINX.\nTo use custom values in an Ingress rule, define the annotation: nginx.ingress.kubernetes.io/connection-proxy-header : \"keep-alive\"", "title": "Connection proxy header" }, { "location": "/user-guide/nginx-configuration/annotations/#enable-access-log", - "text": "In some scenarios could be required to disable NGINX access logs. To enable this feature use the annotation: nginx.ingress.kubernetes.io/enable-access-log : \"false\"", + "text": "Access logs are enabled by default, but in some scenarios access logs might be required to be disabled for a given\ningress. To do this, use the annotation: nginx.ingress.kubernetes.io/enable-access-log : \"false\"", "title": "Enable Access Log" }, { "location": "/user-guide/nginx-configuration/annotations/#enable-rewrite-log", - "text": "In some scenarios it could be required to enable NGINX rewrite logs. Note that rewrite logs are sent to the error_log file at the notice level. To enable this feature use the annotation: nginx.ingress.kubernetes.io/enable-rewrite-log : \"true\"", + "text": "Rewrite logs are not enabled by default. In some scenarios it could be required to enable NGINX rewrite logs.\nNote that rewrite logs are sent to the error_log file at the notice level. To enable this feature use the annotation: nginx.ingress.kubernetes.io/enable-rewrite-log : \"true\"", "title": "Enable Rewrite Log" }, { "location": "/user-guide/nginx-configuration/annotations/#lua-resty-waf", - "text": "Using lua-resty-waf-* annotations we can enable and control lua-resty-waf per location.\nFollowing configuration will enable WAF for the paths defined in the corresponding ingress: nginx.ingress.kubernetes.io/lua-resty-waf : \"active\" In order to run it in debugging mode you can set nginx.ingress.kubernetes.io/lua-resty-waf-debug to \"true\" in addition to the above configuration.\nThe other possible values for nginx.ingress.kubernetes.io/lua-resty-waf are inactive and simulate . In inactive mode WAF won't do anything, whereas\nin simulate mode it will log a warning message if there's a matching WAF rule for given request. This is useful to debug a rule and eliminate possible false positives before fully deploying it. lua-resty-waf comes with predefined set of rules https://github.com/p0pr0ck5/lua-resty-waf/tree/84b4f40362500dd0cb98b9e71b5875cb1a40f1ad/rules that covers ModSecurity CRS.\nYou can use nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets to ignore subset of those rulesets. For an example: nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets : \"41000_sqli, 42000_xss\" will ignore the two mentioned rulesets. It is also possible to configure custom WAF rules per ingress using nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules annotation. For an example the following snippet will\nconfigure a WAF rule to deny requests with query string value that contains word foo : nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules : '[=[ { \"access\": [ { \"actions\": { \"disrupt\" : \"DENY\" }, \"id\": 10001, \"msg\": \"my custom rule\", \"operator\": \"STR_CONTAINS\", \"pattern\": \"foo\", \"vars\": [ { \"parse\": [ \"values\", 1 ], \"type\": \"REQUEST_ARGS\" } ] } ], \"body_filter\": [], \"header_filter\":[] } ]=]' For details on how to write WAF rules, please refer to https://github.com/p0pr0ck5/lua-resty-waf .", + "text": "Using lua-resty-waf-* annotations we can enable and control the lua-resty-waf \nWeb Application Firewall per location. Following configuration will enable the WAF for the paths defined in the corresponding ingress: nginx.ingress.kubernetes.io/lua-resty-waf : \"active\" In order to run it in debugging mode you can set nginx.ingress.kubernetes.io/lua-resty-waf-debug to \"true\" in addition to the above configuration.\nThe other possible values for nginx.ingress.kubernetes.io/lua-resty-waf are inactive and simulate .\nIn inactive mode WAF won't do anything, whereas in simulate mode it will log a warning message if there's a matching WAF rule for given request. This is useful to debug a rule and eliminate possible false positives before fully deploying it. lua-resty-waf comes with predefined set of rules https://github.com/p0pr0ck5/lua-resty-waf/tree/84b4f40362500dd0cb98b9e71b5875cb1a40f1ad/rules that covers ModSecurity CRS.\nYou can use nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets to ignore a subset of those rulesets. For an example: nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets : \"41000_sqli, 42000_xss\" will ignore the two mentioned rulesets. It is also possible to configure custom WAF rules per ingress using the nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules annotation. For an example the following snippet will configure a WAF rule to deny requests with query string value that contains word foo : nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules : '[=[ { \"access\": [ { \"actions\": { \"disrupt\" : \"DENY\" }, \"id\": 10001, \"msg\": \"my custom rule\", \"operator\": \"STR_CONTAINS\", \"pattern\": \"foo\", \"vars\": [ { \"parse\": [ \"values\", 1 ], \"type\": \"REQUEST_ARGS\" } ] } ], \"body_filter\": [], \"header_filter\":[] } ]=]' For details on how to write WAF rules, please refer to https://github.com/p0pr0ck5/lua-resty-waf .", "title": "Lua Resty WAF" }, { "location": "/user-guide/nginx-configuration/annotations/#grpc-backend", - "text": "Since NGINX 1.13.10 it is possible to expose gRPC services natively You only need to add the annotation nginx.ingress.kubernetes.io/grpc-backend: \"true\" to enable this feature. Additionally, if the gRPC service requires TLS nginx.ingress.kubernetes.io/secure-backends: \"true\" Important This feature requires HTTP2 to work which means we need to expose this service using HTTPS. Exposing a gRPC service using HTTP is not supported.", + "text": "Since NGINX 1.13.10 it is possible to expose gRPC services natively You only need to add the annotation nginx.ingress.kubernetes.io/grpc-backend: \"true\" to enable this feature.\nAdditionally, if the gRPC service requires TLS, add nginx.ingress.kubernetes.io/secure-backends: \"true\" . Attention This feature requires HTTP2 to work which means we need to expose this service using HTTPS.\nExposing a gRPC service using HTTP is not supported.", "title": "gRPC backend" }, { @@ -932,12 +952,12 @@ }, { "location": "/user-guide/nginx-configuration/log-format/", - "text": "Log format\n\u00b6\n\n\nThe default configuration uses a custom logging format to add additional information about upstreams, response time and status\n\n\n log_format upstreaminfo '\n{{\n \nif\n \n$\ncfg.useProxyProtocol\n \n}}\n$proxy_protocol_addr\n{{\n \nelse\n \n}}\n$remote_addr\n{{\n \nend\n \n}}\n - '\n\n\n '[$the_real_ip] - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" '\n\n\n '$request_length $request_time [$proxy_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status';\n\n\n\n\n\n\nSources:\n\n\n\n\nupstream variables\n\n\nembedded variables\n\n\n\n\nDescription:\n\n\n\n\n$proxy_protocol_addr\n: if PROXY protocol is enabled\n\n\n$remote_addr\n: if PROXY protocol is disabled (default)\n\n\n$the_real_ip\n: the source IP address of the client\n\n\n$remote_user\n: user name supplied with the Basic authentication\n\n\n$time_local\n: local time in the Common Log Format\n\n\n$request\n: full original request line\n\n\n$status\n: response status\n\n\n$body_bytes_sent\n: number of bytes sent to a client, not counting the response header\n\n\n$http_referer\n: value of the Referer header\n\n\n$http_user_agent\n: value of User-Agent header\n\n\n$request_length\n: request length (including request line, header, and request body)\n\n\n$request_time\n: time elapsed since the first bytes were read from the client\n\n\n$proxy_upstream_name\n: name of the upstream. The format is \nupstream---\n\n\n$upstream_addr\n: keeps the IP address and port, or the path to the UNIX-domain socket of the upstream server. If several servers were contacted during request processing, their addresses are separated by commas\n\n\n$upstream_response_length\n: keeps the length of the response obtained from the upstream server\n\n\n$upstream_response_time\n: keeps time spent on receiving the response from the upstream server; the time is kept in seconds with millisecond resolution\n\n\n$upstream_status\n: keeps status code of the response obtained from the upstream server", + "text": "Log format\n\u00b6\n\n\nThe default configuration uses a custom logging format to add additional information about upstreams, response time and status.\n\n\nlog_format upstreaminfo\n\n\n '\n{{\n \nif\n \n$\ncfg.useProxyProtocol\n \n}}\n$proxy_protocol_addr\n{{\n \nelse\n \n}}\n$remote_addr\n{{\n \nend\n \n}}\n - '\n\n\n '[$the_real_ip] - $remote_user [$time_local] \"$request\" '\n\n\n '$status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" '\n\n\n '$request_length $request_time [$proxy_upstream_name] $upstream_addr '\n\n\n '$upstream_response_length $upstream_response_time $upstream_status';\n\n\n\n\n\n\n\n\n\n\n\n\nPlaceholder\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n$proxy_protocol_addr\n\n\nremote address if proxy protocol is enabled\n\n\n\n\n\n\n$remote_addr\n\n\nremote address if proxy protocol is disabled (default)\n\n\n\n\n\n\n$the_real_ip\n\n\nthe source IP address of the client\n\n\n\n\n\n\n$remote_user\n\n\nuser name supplied with the Basic authentication\n\n\n\n\n\n\n$time_local\n\n\nlocal time in the Common Log Format\n\n\n\n\n\n\n$request\n\n\nfull original request line\n\n\n\n\n\n\n$status\n\n\nresponse status\n\n\n\n\n\n\n$body_bytes_sent\n\n\nnumber of bytes sent to a client, not counting the response header\n\n\n\n\n\n\n$http_referer\n\n\nvalue of the Referer header\n\n\n\n\n\n\n$http_user_agent\n\n\nvalue of User-Agent header\n\n\n\n\n\n\n$request_length\n\n\nrequest length (including request line, header, and request body)\n\n\n\n\n\n\n$request_time\n\n\ntime elapsed since the first bytes were read from the client\n\n\n\n\n\n\n$proxy_upstream_name\n\n\nname of the upstream. The format is \nupstream---\n\n\n\n\n\n\n$upstream_addr\n\n\nthe IP address and port (or the path to the domain socket) of the upstream server. If several servers were contacted during request processing, their addresses are separated by commas.\n\n\n\n\n\n\n$upstream_response_length\n\n\nthe length of the response obtained from the upstream server\n\n\n\n\n\n\n$upstream_response_time\n\n\ntime spent on receiving the response from the upstream server as seconds with millisecond resolution\n\n\n\n\n\n\n$upstream_status\n\n\nstatus code of the response obtained from the upstream server\n\n\n\n\n\n\n\n\nSources:\n\n\n\n\nUpstream variables\n\n\nEmbedded variables", "title": "Log format" }, { "location": "/user-guide/nginx-configuration/log-format/#log-format", - "text": "The default configuration uses a custom logging format to add additional information about upstreams, response time and status log_format upstreaminfo ' {{ if $ cfg.useProxyProtocol }} $proxy_protocol_addr {{ else }} $remote_addr {{ end }} - ' '[$the_real_ip] - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" ' '$request_length $request_time [$proxy_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status'; Sources: upstream variables embedded variables Description: $proxy_protocol_addr : if PROXY protocol is enabled $remote_addr : if PROXY protocol is disabled (default) $the_real_ip : the source IP address of the client $remote_user : user name supplied with the Basic authentication $time_local : local time in the Common Log Format $request : full original request line $status : response status $body_bytes_sent : number of bytes sent to a client, not counting the response header $http_referer : value of the Referer header $http_user_agent : value of User-Agent header $request_length : request length (including request line, header, and request body) $request_time : time elapsed since the first bytes were read from the client $proxy_upstream_name : name of the upstream. The format is upstream--- $upstream_addr : keeps the IP address and port, or the path to the UNIX-domain socket of the upstream server. If several servers were contacted during request processing, their addresses are separated by commas $upstream_response_length : keeps the length of the response obtained from the upstream server $upstream_response_time : keeps time spent on receiving the response from the upstream server; the time is kept in seconds with millisecond resolution $upstream_status : keeps status code of the response obtained from the upstream server", + "text": "The default configuration uses a custom logging format to add additional information about upstreams, response time and status. log_format upstreaminfo ' {{ if $ cfg.useProxyProtocol }} $proxy_protocol_addr {{ else }} $remote_addr {{ end }} - ' '[$the_real_ip] - $remote_user [$time_local] \"$request\" ' '$status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" ' '$request_length $request_time [$proxy_upstream_name] $upstream_addr ' '$upstream_response_length $upstream_response_time $upstream_status'; Placeholder Description $proxy_protocol_addr remote address if proxy protocol is enabled $remote_addr remote address if proxy protocol is disabled (default) $the_real_ip the source IP address of the client $remote_user user name supplied with the Basic authentication $time_local local time in the Common Log Format $request full original request line $status response status $body_bytes_sent number of bytes sent to a client, not counting the response header $http_referer value of the Referer header $http_user_agent value of User-Agent header $request_length request length (including request line, header, and request body) $request_time time elapsed since the first bytes were read from the client $proxy_upstream_name name of the upstream. The format is upstream--- $upstream_addr the IP address and port (or the path to the domain socket) of the upstream server. If several servers were contacted during request processing, their addresses are separated by commas. $upstream_response_length the length of the response obtained from the upstream server $upstream_response_time time spent on receiving the response from the upstream server as seconds with millisecond resolution $upstream_status status code of the response obtained from the upstream server Sources: Upstream variables Embedded variables", "title": "Log format" }, { @@ -960,6 +980,16 @@ "text": "In case of an error in a request the body of the response is obtained from the default backend .\nEach request to the default backend includes two headers: X-Code indicates the HTTP code to be returned to the client. X-Format the value of the Accept header. Important The custom backend must return the correct HTTP status code to be returned. NGINX does not change the response from the custom default backend. Using these two headers it's possible to use a custom backend service like this one that inspects each request and returns a custom error page with the format expected by the client. Please check the example custom-errors . NGINX sends additional headers that can be used to build custom response: X-Original-URI X-Namespace X-Ingress-Name X-Service-Name", "title": "Custom errors" }, + { + "location": "/user-guide/default-backend/", + "text": "Default backend\n\u00b6\n\n\nThe default backend is a service which handles all URL paths and hosts the nginx controller doesn't understand\n(i.e., all the requests that are not mapped with an Ingress).\n\n\nBasically a default backend exposes two URLs:\n\n\n\n\n/healthz\n that returns 200\n\n\n/\n that returns 404\n\n\n\n\n\n\nExample\n\n\nThe sub-directory \n/images/404-server\n\nprovides a service which satisfies the requirements for a default backend.\n\n\n\n\n\n\nExample\n\n\nThe sub-directory \n/images/custom-error-pages\n\nprovides an additional service for the purpose of customizing the error pages served via the default backend.", + "title": "Default backend" + }, + { + "location": "/user-guide/default-backend/#default-backend", + "text": "The default backend is a service which handles all URL paths and hosts the nginx controller doesn't understand\n(i.e., all the requests that are not mapped with an Ingress). Basically a default backend exposes two URLs: /healthz that returns 200 / that returns 404 Example The sub-directory /images/404-server \nprovides a service which satisfies the requirements for a default backend. Example The sub-directory /images/custom-error-pages \nprovides an additional service for the purpose of customizing the error pages served via the default backend.", + "title": "Default backend" + }, { "location": "/user-guide/exposing-tcp-udp-services/", "text": "Exposing TCP and UDP services\n\u00b6\n\n\nIngress does not support TCP or UDP services. For this reason this Ingress controller uses the flags \n--tcp-services-configmap\n and \n--udp-services-configmap\n to point to an existing config map where the key is the external port to use and the value indicates the service to expose using the format:\n\n::[PROXY]:[PROXY]\n\n\nIt is also possible to use a number or the name of the port. The two last fields are optional.\nAdding \nPROXY\n in either or both of the two last fields we can use Proxy Protocol decoding (listen) and/or encoding (proxy_pass) in a TCP service (https://www.nginx.com/resources/admin-guide/proxy-protocol/).\n\n\nThe next example shows how to expose the service \nexample-go\n running in the namespace \ndefault\n in the port \n8080\n using the port \n9000\n\n\napiVersion\n:\n \nv1\n\n\nkind\n:\n \nConfigMap\n\n\nmetadata\n:\n\n \nname\n:\n \ntcp-configmap-example\n\n\ndata\n:\n\n \n9000\n:\n \n\"default/example-go:8080\"\n\n\n\n\n\n\nSince 1.9.13 NGINX provides \nUDP Load Balancing\n.\nThe next example shows how to expose the service \nkube-dns\n running in the namespace \nkube-system\n in the port \n53\n using the port \n53\n\n\napiVersion\n:\n \nv1\n\n\nkind\n:\n \nConfigMap\n\n\nmetadata\n:\n\n \nname\n:\n \nudp-configmap-example\n\n\ndata\n:\n\n\n \u00a0\n53\n:\n \n\"kube-system/kube-dns:53\"", @@ -982,7 +1012,7 @@ }, { "location": "/user-guide/miscellaneous/", - "text": "Miscellaneous\n\u00b6\n\n\nConventions\n\u00b6\n\n\nAnytime we reference a tls secret, we mean (x509, pem encoded, RSA 2048, etc). You can generate such a certificate with:\n\nopenssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout \n${\nKEY_FILE\n}\n -out \n${\nCERT_FILE\n}\n -subj \"/CN=\n${\nHOST\n}\n/O=\n${\nHOST\n}\n\"\n\nand create the secret via \nkubectl create secret tls \n${\nCERT_NAME\n}\n --key \n${\nKEY_FILE\n}\n --cert \n${\nCERT_FILE\n}\n\n\nRequirements\n\u00b6\n\n\nThe default backend is a service which handles all url paths and hosts the nginx controller doesn't understand (i.e., all the requests that are not mapped with an Ingress).\nBasically a default backend exposes two URLs:\n\n\n\n\n/healthz\n that returns 200\n\n\n/\n that returns 404\n\n\n\n\nThe sub-directory \n/images/404-server\n provides a service which satisfies the requirements for a default backend. The sub-directory \n/images/custom-error-pages\n provides an additional service for the purpose of customizing the error pages served via the default backend.\n\n\nSource IP address\n\u00b6\n\n\nBy default NGINX uses the content of the header \nX-Forwarded-For\n as the source of truth to get information about the client IP address. This works without issues in L7 \nif we configure the setting \nproxy-real-ip-cidr\n with the correct information of the IP/network address of trusted external load balancer.\n\n\nIf the ingress controller is running in AWS we need to use the VPC IPv4 CIDR.\n\n\nAnother option is to enable proxy protocol using \nuse-proxy-protocol: \"true\"\n.\n\n\nIn this mode NGINX does not use the content of the header to get the source IP address of the connection.\n\n\nProxy Protocol\n\u00b6\n\n\nIf you are using a L4 proxy to forward the traffic to the NGINX pods and terminate HTTP/HTTPS there, you will lose the remote endpoint's IP address. To prevent this you could use the \nProxy Protocol\n for forwarding traffic, this will send the connection details before forwarding the actual TCP connection itself.\n\n\nAmongst others \nELBs in AWS\n and \nHAProxy\n support Proxy Protocol.\n\n\nWebsockets\n\u00b6\n\n\nSupport for websockets is provided by NGINX out of the box. No special configuration required.\n\n\nThe only requirement to avoid the close of connections is the increase of the values of \nproxy-read-timeout\n and \nproxy-send-timeout\n.\n\n\nThe default value of this settings is \n60 seconds\n.\n\n\nA more adequate value to support websockets is a value higher than one hour (\n3600\n).\n\n\n\n\nImportant\n\n\nIf the NGINX ingress controller is exposed with a service \ntype=LoadBalancer\n make sure the protocol between the loadbalancer and NGINX is TCP.\n\n\n\n\nOptimizing TLS Time To First Byte (TTTFB)\n\u00b6\n\n\nNGINX provides the configuration option \nssl_buffer_size\n to allow the optimization of the TLS record size.\n\n\nThis improves the \nTLS Time To First Byte\n (TTTFB).\nThe default value in the Ingress controller is \n4k\n (NGINX default is \n16k\n).\n\n\nRetries in non-idempotent methods\n\u00b6\n\n\nSince 1.9.13 NGINX will not retry non-idempotent requests (POST, LOCK, PATCH) in case of an error.\nThe previous behavior can be restored using \nretry-non-idempotent=true\n in the configuration ConfigMap.\n\n\nLimitations\n\u00b6\n\n\n\n\nIngress rules for TLS require the definition of the field \nhost\n\n\n\n\nWhy endpoints and not services\n\u00b6\n\n\nThe NGINX ingress controller does not use \nServices\n to route traffic to the pods. Instead it uses the Endpoints API in order to bypass \nkube-proxy\n to allow NGINX features like session affinity and custom load balancing algorithms. It also removes some overhead, such as conntrack entries for iptables DNAT.", + "text": "Miscellaneous\n\u00b6\n\n\nSource IP address\n\u00b6\n\n\nBy default NGINX uses the content of the header \nX-Forwarded-For\n as the source of truth to get information about the client IP address. This works without issues in L7 \nif we configure the setting \nproxy-real-ip-cidr\n with the correct information of the IP/network address of trusted external load balancer.\n\n\nIf the ingress controller is running in AWS we need to use the VPC IPv4 CIDR.\n\n\nAnother option is to enable proxy protocol using \nuse-proxy-protocol: \"true\"\n.\n\n\nIn this mode NGINX does not use the content of the header to get the source IP address of the connection.\n\n\nProxy Protocol\n\u00b6\n\n\nIf you are using a L4 proxy to forward the traffic to the NGINX pods and terminate HTTP/HTTPS there, you will lose the remote endpoint's IP address. To prevent this you could use the \nProxy Protocol\n for forwarding traffic, this will send the connection details before forwarding the actual TCP connection itself.\n\n\nAmongst others \nELBs in AWS\n and \nHAProxy\n support Proxy Protocol.\n\n\nWebsockets\n\u00b6\n\n\nSupport for websockets is provided by NGINX out of the box. No special configuration required.\n\n\nThe only requirement to avoid the close of connections is the increase of the values of \nproxy-read-timeout\n and \nproxy-send-timeout\n.\n\n\nThe default value of this settings is \n60 seconds\n.\n\n\nA more adequate value to support websockets is a value higher than one hour (\n3600\n).\n\n\n\n\nImportant\n\n\nIf the NGINX ingress controller is exposed with a service \ntype=LoadBalancer\n make sure the protocol between the loadbalancer and NGINX is TCP.\n\n\n\n\nOptimizing TLS Time To First Byte (TTTFB)\n\u00b6\n\n\nNGINX provides the configuration option \nssl_buffer_size\n to allow the optimization of the TLS record size.\n\n\nThis improves the \nTLS Time To First Byte\n (TTTFB).\nThe default value in the Ingress controller is \n4k\n (NGINX default is \n16k\n).\n\n\nRetries in non-idempotent methods\n\u00b6\n\n\nSince 1.9.13 NGINX will not retry non-idempotent requests (POST, LOCK, PATCH) in case of an error.\nThe previous behavior can be restored using \nretry-non-idempotent=true\n in the configuration ConfigMap.\n\n\nLimitations\n\u00b6\n\n\n\n\nIngress rules for TLS require the definition of the field \nhost\n\n\n\n\nWhy endpoints and not services\n\u00b6\n\n\nThe NGINX ingress controller does not use \nServices\n to route traffic to the pods. Instead it uses the Endpoints API in order to bypass \nkube-proxy\n to allow NGINX features like session affinity and custom load balancing algorithms. It also removes some overhead, such as conntrack entries for iptables DNAT.", "title": "Miscellaneous" }, { @@ -990,16 +1020,6 @@ "text": "", "title": "Miscellaneous" }, - { - "location": "/user-guide/miscellaneous/#conventions", - "text": "Anytime we reference a tls secret, we mean (x509, pem encoded, RSA 2048, etc). You can generate such a certificate with: openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ${ KEY_FILE } -out ${ CERT_FILE } -subj \"/CN= ${ HOST } /O= ${ HOST } \" \nand create the secret via kubectl create secret tls ${ CERT_NAME } --key ${ KEY_FILE } --cert ${ CERT_FILE }", - "title": "Conventions" - }, - { - "location": "/user-guide/miscellaneous/#requirements", - "text": "The default backend is a service which handles all url paths and hosts the nginx controller doesn't understand (i.e., all the requests that are not mapped with an Ingress).\nBasically a default backend exposes two URLs: /healthz that returns 200 / that returns 404 The sub-directory /images/404-server provides a service which satisfies the requirements for a default backend. The sub-directory /images/custom-error-pages provides an additional service for the purpose of customizing the error pages served via the default backend.", - "title": "Requirements" - }, { "location": "/user-guide/miscellaneous/#source-ip-address", "text": "By default NGINX uses the content of the header X-Forwarded-For as the source of truth to get information about the client IP address. This works without issues in L7 if we configure the setting proxy-real-ip-cidr with the correct information of the IP/network address of trusted external load balancer. If the ingress controller is running in AWS we need to use the VPC IPv4 CIDR. Another option is to enable proxy protocol using use-proxy-protocol: \"true\" . In this mode NGINX does not use the content of the header to get the source IP address of the connection.", @@ -1037,28 +1057,18 @@ }, { "location": "/user-guide/multiple-ingress/", - "text": "Multiple ingress controllers\n\u00b6\n\n\nRunning multiple ingress controllers\n\u00b6\n\n\nIf you're running multiple ingress controllers, or running on a cloud provider that natively handles ingress, you need to specify the annotation \nkubernetes.io/ingress.class: \"nginx\"\n in all ingresses that you would like this controller to claim.\n\n\nThis mechanism also provides users the ability to run \nmultiple\n NGINX ingress controllers (e.g. one which serves public traffic, one which serves \"internal\" traffic). When utilizing this functionality the option \n--ingress-class\n should be changed to a value unique for the cluster within the definition of the replication controller. Here is a partial example:\n\n\nspec\n:\n\n \ntemplate\n:\n\n \nspec\n:\n\n \ncontainers\n:\n\n \n-\n \nname\n:\n \nnginx\n-\ningress\n-\ninternal\n-\ncontroller\n\n \nargs\n:\n\n \n-\n \n/\nnginx\n-\ningress\n-\ncontroller\n\n \n-\n \n'--default-backend-service=ingress/nginx-ingress-default-backend'\n\n \n-\n \n'--election-id=ingress-controller-leader-internal'\n\n \n-\n \n'--ingress-class=nginx-internal'\n\n \n-\n \n'--configmap=ingress/nginx-ingress-internal-controller'\n\n\n\n\n\n\nAnnotation ingress.class\n\u00b6\n\n\nIf you have multiple Ingress controllers in a single cluster, you can pick one by specifying the \ningress.class\n \nannotation, eg creating an Ingress with an annotation like\n\n\nmetadata\n:\n\n \nname\n:\n \nfoo\n\n \nannotations\n:\n\n \nkubernetes.io/ingress.class\n:\n \n\"gce\"\n\n\n\n\n\n\nwill target the GCE controller, forcing the nginx controller to ignore it, while an annotation like\n\n\nmetadata\n:\n\n \nname\n:\n \nfoo\n\n \nannotations\n:\n\n \nkubernetes.io/ingress.class\n:\n \n\"nginx\"\n\n\n\n\n\n\nwill target the nginx controller, forcing the GCE controller to ignore it.\n\n\nNote\n: Deploying multiple ingress controller and not specifying the annotation will result in both controllers fighting to satisfy the Ingress.\n\n\nDisabling NGINX ingress controller\n\u00b6\n\n\nSetting the annotation \nkubernetes.io/ingress.class\n to any other value which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress. If you are only running a single NGINX ingress controller, this can be achieved by setting this to any value except \"nginx\" or an empty string.\n\n\nDo this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller.", - "title": "Multiple ingress controllers" + "text": "Multiple Ingress controllers\n\u00b6\n\n\nIf you're running multiple ingress controllers, or running on a cloud provider that natively handles ingress such as GKE,\nyou need to specify the annotation \nkubernetes.io/ingress.class: \"nginx\"\n in all ingresses that you would like the ingress-nginx controller to claim.\n\n\nFor instance,\n\n\nmetadata\n:\n\n \nname\n:\n \nfoo\n\n \nannotations\n:\n\n \nkubernetes.io/ingress.class\n:\n \n\"gce\"\n\n\n\n\n\n\nwill target the GCE controller, forcing the nginx controller to ignore it, while an annotation like\n\n\nmetadata\n:\n\n \nname\n:\n \nfoo\n\n \nannotations\n:\n\n \nkubernetes.io/ingress.class\n:\n \n\"nginx\"\n\n\n\n\n\n\nwill target the nginx controller, forcing the GCE controller to ignore it.\n\n\nTo reiterate, setting the annotation to any value which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress.\nIf you are only running a single NGINX ingress controller, this can be achieved by setting the annotation to any value except \"nginx\" or an empty string.\n\n\nDo this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller.\n\n\n\n\nImportant\n\n\nDeploying multiple Ingress controllers and not specifying a class annotation will\nresult in both or all controllers fighting to satisfy the Ingress, and all of them\nupdating the Ingress status field in confusing ways.\n\n\n\n\nMultiple ingress-nginx controllers\n\u00b6\n\n\nThis mechanism also provides users the ability to run \nmultiple\n NGINX ingress controllers (e.g. one which serves public traffic, one which serves \"internal\" traffic).\nTo do this, the option \n--ingress-class\n must be changed to a value unique for the cluster within the definition of the replication controller.\nHere is a partial example:\n\n\nspec\n:\n\n \ntemplate\n:\n\n \nspec\n:\n\n \ncontainers\n:\n\n \n-\n \nname\n:\n \nnginx-ingress-internal-controller\n\n \nargs\n:\n\n \n-\n \n/nginx-ingress-controller\n\n \n-\n \n'--default-backend-service=ingress/nginx-ingress-default-backend'\n\n \n-\n \n'--election-id=ingress-controller-leader-internal'\n\n \n-\n \n'--ingress-class=nginx-internal'\n\n \n-\n \n'--configmap=ingress/nginx-ingress-internal-controller'", + "title": "Multiple Ingress controllers" }, { "location": "/user-guide/multiple-ingress/#multiple-ingress-controllers", - "text": "", - "title": "Multiple ingress controllers" + "text": "If you're running multiple ingress controllers, or running on a cloud provider that natively handles ingress such as GKE,\nyou need to specify the annotation kubernetes.io/ingress.class: \"nginx\" in all ingresses that you would like the ingress-nginx controller to claim. For instance, metadata : \n name : foo \n annotations : \n kubernetes.io/ingress.class : \"gce\" will target the GCE controller, forcing the nginx controller to ignore it, while an annotation like metadata : \n name : foo \n annotations : \n kubernetes.io/ingress.class : \"nginx\" will target the nginx controller, forcing the GCE controller to ignore it. To reiterate, setting the annotation to any value which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress.\nIf you are only running a single NGINX ingress controller, this can be achieved by setting the annotation to any value except \"nginx\" or an empty string. Do this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller. Important Deploying multiple Ingress controllers and not specifying a class annotation will\nresult in both or all controllers fighting to satisfy the Ingress, and all of them\nupdating the Ingress status field in confusing ways.", + "title": "Multiple Ingress controllers" }, { - "location": "/user-guide/multiple-ingress/#running-multiple-ingress-controllers", - "text": "If you're running multiple ingress controllers, or running on a cloud provider that natively handles ingress, you need to specify the annotation kubernetes.io/ingress.class: \"nginx\" in all ingresses that you would like this controller to claim. This mechanism also provides users the ability to run multiple NGINX ingress controllers (e.g. one which serves public traffic, one which serves \"internal\" traffic). When utilizing this functionality the option --ingress-class should be changed to a value unique for the cluster within the definition of the replication controller. Here is a partial example: spec : \n template : \n spec : \n containers : \n - name : nginx - ingress - internal - controller \n args : \n - / nginx - ingress - controller \n - '--default-backend-service=ingress/nginx-ingress-default-backend' \n - '--election-id=ingress-controller-leader-internal' \n - '--ingress-class=nginx-internal' \n - '--configmap=ingress/nginx-ingress-internal-controller'", - "title": "Running multiple ingress controllers" - }, - { - "location": "/user-guide/multiple-ingress/#annotation-ingressclass", - "text": "If you have multiple Ingress controllers in a single cluster, you can pick one by specifying the ingress.class \nannotation, eg creating an Ingress with an annotation like metadata : \n name : foo \n annotations : \n kubernetes.io/ingress.class : \"gce\" will target the GCE controller, forcing the nginx controller to ignore it, while an annotation like metadata : \n name : foo \n annotations : \n kubernetes.io/ingress.class : \"nginx\" will target the nginx controller, forcing the GCE controller to ignore it. Note : Deploying multiple ingress controller and not specifying the annotation will result in both controllers fighting to satisfy the Ingress.", - "title": "Annotation ingress.class" - }, - { - "location": "/user-guide/multiple-ingress/#disabling-nginx-ingress-controller", - "text": "Setting the annotation kubernetes.io/ingress.class to any other value which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress. If you are only running a single NGINX ingress controller, this can be achieved by setting this to any value except \"nginx\" or an empty string. Do this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller.", - "title": "Disabling NGINX ingress controller" + "location": "/user-guide/multiple-ingress/#multiple-ingress-nginx-controllers", + "text": "This mechanism also provides users the ability to run multiple NGINX ingress controllers (e.g. one which serves public traffic, one which serves \"internal\" traffic).\nTo do this, the option --ingress-class must be changed to a value unique for the cluster within the definition of the replication controller.\nHere is a partial example: spec : \n template : \n spec : \n containers : \n - name : nginx-ingress-internal-controller \n args : \n - /nginx-ingress-controller \n - '--default-backend-service=ingress/nginx-ingress-default-backend' \n - '--election-id=ingress-controller-leader-internal' \n - '--ingress-class=nginx-internal' \n - '--configmap=ingress/nginx-ingress-internal-controller'", + "title": "Multiple ingress-nginx controllers" }, { "location": "/user-guide/nginx-status-page/", @@ -1072,47 +1082,52 @@ }, { "location": "/user-guide/tls/", - "text": "TLS\n\u00b6\n\n\n\n\nDefault SSL Certificate\n\n\nSSL Passthrough\n\n\nHTTPS enforcement\n\n\nHSTS\n\n\nServer-side HTTPS enforcement through redirect\n \n\n\nKube-Lego\n\n\nDefault TLS Version and Ciphers\n\n\nLegacy TLS\n\n\n\n\nDefault SSL Certificate\n\u00b6\n\n\nNGINX provides the option to configure a server as a catch-all with \nserver_name\n for requests that do not match any of the configured server names. This configuration works without issues for HTTP traffic.\nIn case of HTTPS, NGINX requires a certificate.\nFor this reason the Ingress controller provides the flag \n--default-ssl-certificate\n. The secret behind this flag contains the default certificate to be used in the mentioned scenario. If this flag is not provided NGINX will use a self signed certificate.\n\n\nRunning without the flag \n--default-ssl-certificate\n:\n\n\n$\n curl -v https://10.2.78.7:443 -k\n\n* Rebuilt URL to: https://10.2.78.7:443/\n\n\n* Trying 10.2.78.4...\n\n\n* Connected to 10.2.78.7 (10.2.78.7) port 443 (#0)\n\n\n* ALPN, offering http/1.1\n\n\n* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH\n\n\n* successfully set certificate verify locations:\n\n\n* CAfile: /etc/ssl/certs/ca-certificates.crt\n\n\n CApath: /etc/ssl/certs\n\n\n* TLSv1.2 (OUT), TLS header, Certificate Status (22):\n\n\n* TLSv1.2 (OUT), TLS handshake, Client hello (1):\n\n\n* TLSv1.2 (IN), TLS handshake, Server hello (2):\n\n\n* TLSv1.2 (IN), TLS handshake, Certificate (11):\n\n\n* TLSv1.2 (IN), TLS handshake, Server key exchange (12):\n\n\n* TLSv1.2 (IN), TLS handshake, Server finished (14):\n\n\n* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):\n\n\n* TLSv1.2 (OUT), TLS change cipher, Client hello (1):\n\n\n* TLSv1.2 (OUT), TLS handshake, Finished (20):\n\n\n* TLSv1.2 (IN), TLS change cipher, Client hello (1):\n\n\n* TLSv1.2 (IN), TLS handshake, Finished (20):\n\n\n* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256\n\n\n* ALPN, server accepted to use http/1.1\n\n\n* Server certificate:\n\n\n* subject: CN=foo.bar.com\n\n\n* start date: Apr 13 00:50:56 2016 GMT\n\n\n* expire date: Apr 13 00:50:56 2017 GMT\n\n\n* issuer: CN=foo.bar.com\n\n\n* SSL certificate verify result: self signed certificate (18), continuing anyway.\n\n\n>\n GET / HTTP/1.1\n\n>\n Host: \n10\n.2.78.7\n\n>\n User-Agent: curl/7.47.1\n\n>\n Accept: */*\n\n>\n\n\n< HTTP/1.1 404 Not Found\n\n\n< Server: nginx/1.11.1\n\n\n< Date: Thu, 21 Jul 2016 15:38:46 GMT\n\n\n< Content-Type: text/html\n\n\n< Transfer-Encoding: chunked\n\n\n< Connection: keep-alive\n\n\n< Strict-Transport-Security: max-age=15724800; includeSubDomains; preload\n\n\n<\n\n\nThe page you're looking for could not be found.\n\n\n\n* Connection #0 to host 10.2.78.7 left intact\n\n\n\n\n\n\nSpecifying \n--default-ssl-certificate=default/foo-tls\n:\n\n\ncore@localhost ~ $\n curl -v https://10.2.78.7:443 -k\n\n* Rebuilt URL to: https://10.2.78.7:443/\n\n\n* Trying 10.2.78.7...\n\n\n* Connected to 10.2.78.7 (10.2.78.7) port 443 (#0)\n\n\n* ALPN, offering http/1.1\n\n\n* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH\n\n\n* successfully set certificate verify locations:\n\n\n* CAfile: /etc/ssl/certs/ca-certificates.crt\n\n\n CApath: /etc/ssl/certs\n\n\n* TLSv1.2 (OUT), TLS header, Certificate Status (22):\n\n\n* TLSv1.2 (OUT), TLS handshake, Client hello (1):\n\n\n* TLSv1.2 (IN), TLS handshake, Server hello (2):\n\n\n* TLSv1.2 (IN), TLS handshake, Certificate (11):\n\n\n* TLSv1.2 (IN), TLS handshake, Server key exchange (12):\n\n\n* TLSv1.2 (IN), TLS handshake, Server finished (14):\n\n\n* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):\n\n\n* TLSv1.2 (OUT), TLS change cipher, Client hello (1):\n\n\n* TLSv1.2 (OUT), TLS handshake, Finished (20):\n\n\n* TLSv1.2 (IN), TLS change cipher, Client hello (1):\n\n\n* TLSv1.2 (IN), TLS handshake, Finished (20):\n\n\n* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256\n\n\n* ALPN, server accepted to use http/1.1\n\n\n* Server certificate:\n\n\n* subject: CN=foo.bar.com\n\n\n* start date: Apr 13 00:50:56 2016 GMT\n\n\n* expire date: Apr 13 00:50:56 2017 GMT\n\n\n* issuer: CN=foo.bar.com\n\n\n* SSL certificate verify result: self signed certificate (18), continuing anyway.\n\n\n>\n GET / HTTP/1.1\n\n>\n Host: \n10\n.2.78.7\n\n>\n User-Agent: curl/7.47.1\n\n>\n Accept: */*\n\n>\n\n\n< HTTP/1.1 404 Not Found\n\n\n< Server: nginx/1.11.1\n\n\n< Date: Mon, 18 Jul 2016 21:02:59 GMT\n\n\n< Content-Type: text/html\n\n\n< Transfer-Encoding: chunked\n\n\n< Connection: keep-alive\n\n\n< Strict-Transport-Security: max-age=15724800; includeSubDomains; preload\n\n\n<\n\n\nThe page you're looking for could not be found.\n\n\n\n* Connection #0 to host 10.2.78.7 left intact\n\n\n\n\n\n\nSSL Passthrough\n\u00b6\n\n\nThe flag \n--enable-ssl-passthrough\n enables SSL passthrough feature.\nBy default this feature is disabled\n\n\nHTTP Strict Transport Security\n\u00b6\n\n\nHTTP Strict Transport Security (HSTS) is an opt-in security enhancement specified through the use of a special response header. Once a supported browser receives this header that browser will prevent any communications from being sent over HTTP to the specified domain and will instead send all communications over HTTPS.\n\n\nBy default the controller redirects (301) to HTTPS if there is a TLS Ingress rule.\n\n\nTo disable this behavior use \nhsts: \"false\"\n in the configuration ConfigMap.\n\n\nServer-side HTTPS enforcement through redirect\n\u00b6\n\n\nBy default the controller redirects (301) to \nHTTPS\n if TLS is enabled for that ingress. If you want to disable that behavior globally, you can use \nssl-redirect: \"false\"\n in the NGINX config map.\n\n\nTo configure this feature for specific ingress resources, you can use the \nnginx.ingress.kubernetes.io/ssl-redirect: \"false\"\n annotation in the particular resource.\n\n\nWhen using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to \nHTTPS\n even when there is not TLS cert available. This can be achieved by using the \nnginx.ingress.kubernetes.io/force-ssl-redirect: \"true\"\n annotation in the particular resource.\n\n\nAutomated Certificate Management with Kube-Lego\n\u00b6\n\n\nKube-Lego\n automatically requests missing or expired certificates from \nLet's Encrypt\n by monitoring ingress resources and their referenced secrets. To enable this for an ingress resource you have to add an annotation:\n\n\nkubectl annotate ing ingress-demo kubernetes.io/tls-acme=\"true\"\n\n\n\n\n\n\nTo setup Kube-Lego you can take a look at this \nfull example\n. The first\nversion to fully support Kube-Lego is nginx Ingress controller 0.8.\n\n\nDefault TLS Version and Ciphers\n\u00b6\n\n\nTo provide the most secure baseline configuration possible, nginx-ingress defaults to using TLS 1.2 and a \nsecure set of TLS ciphers\n\n\nLegacy TLS\n\u00b6\n\n\nThe default configuration, though secure, does not support some older browsers and operating systems. For instance, 20% of Android phones in use today are not compatible with nginx-ingress's default configuration. To change this default behavior, use a \nConfigMap\n.\n\n\nA sample ConfigMap to allow these older clients connect could look something like the following:\n\n\nkind\n:\n \nConfigMap\n\n\napiVersion\n:\n \nv1\n\n\nmetadata\n:\n\n \nname\n:\n \nnginx\n-\nconfig\n\n\ndata\n:\n\n \nssl\n-\nciphers\n:\n \n\"ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA\"\n\n \nssl\n-\nprotocols\n:\n \n\"TLSv1 TLSv1.1 TLSv1.2\"", - "title": "TLS" + "text": "TLS/HTTPS\n\u00b6\n\n\nTLS Secrets\n\u00b6\n\n\nAnytime we reference a TLS secret, we mean a PEM-encoded X.509, RSA (2048) secret.\n\n\nYou can generate a self-signed certificate and private key with with:\n\n\n$ openssl req -x509 -nodes -days \n365\n -newkey rsa:2048 -keyout \n${\nKEY_FILE\n}\n -out \n${\nCERT_FILE\n}\n -subj \n\"/CN=\n${\nHOST\n}\n/O=\n${\nHOST\n}\n\"\n`\n\n\n\n\n\n\nThen create the secret in the cluster via:\n\n\nkubectl create secret tls \n${\nCERT_NAME\n}\n --key \n${\nKEY_FILE\n}\n --cert \n${\nCERT_FILE\n}\n\n\n\n\n\n\nThe resulting secret will be of type \nkubernetes.io/tls\n.\n\n\nDefault SSL Certificate\n\u00b6\n\n\nNGINX provides the option to configure a server as a catch-all with\n\nserver_name\n\nfor requests that do not match any of the configured server names.\nThis configuration works without out-of-the-box for HTTP traffic.\nFor HTTPS, a certificate is naturally required.\n\n\nFor this reason the Ingress controller provides the flag \n--default-ssl-certificate\n.\nThe secret referred to by this flag contains the default certificate to be used when\naccessing the catch-all server.\nIf this flag is not provided NGINX will use a self-signed certificate.\n\n\nFor instance, if you have a TLS secret \nfoo-tls\n in the \ndefault\n namespace,\nadd \n--default-ssl-certificate=default/foo-tls\n in the \nnginx-controller\n deployment.\n\n\nSSL Passthrough\n\u00b6\n\n\nThe flag \n--enable-ssl-passthrough\n enables the SSL passthrough feature.\nBy default this feature is disabled.\n\n\nThis is required to enable passthrough backends in Ingress configurations.\n\n\nTODO: Improve this documentation.\n\n\nHTTP Strict Transport Security\n\u00b6\n\n\nHTTP Strict Transport Security (HSTS) is an opt-in security enhancement specified\nthrough the use of a special response header. Once a supported browser receives\nthis header that browser will prevent any communications from being sent over\nHTTP to the specified domain and will instead send all communications over HTTPS.\n\n\nHSTS is enabled by default.\n\n\nTo disable this behavior use \nhsts: \"false\"\n in the configuration \nConfigMap\n.\n\n\nServer-side HTTPS enforcement through redirect\n\u00b6\n\n\nBy default the controller redirects HTTP clients to the HTTPS port\n443 using a 308 Permanent Redirect response if TLS is enabled for that Ingress.\n\n\nThis can be disabled globally using \nssl-redirect: \"false\"\n in the NGINX \nconfig map\n,\nor per-Ingress with the \nnginx.ingress.kubernetes.io/ssl-redirect: \"false\"\n\nannotation in the particular resource.\n\n\n\n\nTip\n\n\nWhen using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a\nredirect to HTTPS even when there is no TLS certificate available.\nThis can be achieved by using the \nnginx.ingress.kubernetes.io/force-ssl-redirect: \"true\"\n\nannotation in the particular resource.\n\n\n\n\nAutomated Certificate Management with Kube-Lego\n\u00b6\n\n\n\n\nTip\n\n\nKube-Lego has reached end-of-life and is being\nreplaced by \ncert-manager\n.\n\n\n\n\nKube-Lego\n automatically requests missing or expired certificates from \nLet's Encrypt\n\nby monitoring ingress resources and their referenced secrets.\n\n\nTo enable this for an ingress resource you have to add an annotation:\n\n\nkubectl annotate ing ingress-demo kubernetes.io/tls-acme=\"true\"\n\n\n\n\n\n\nTo setup Kube-Lego you can take a look at this \nfull example\n.\nThe first version to fully support Kube-Lego is Nginx Ingress controller 0.8.\n\n\nDefault TLS Version and Ciphers\n\u00b6\n\n\nTo provide the most secure baseline configuration possible,\n\n\nnginx-ingress defaults to using TLS 1.2 only and a \nsecure set of TLS ciphers\n.\n\n\nLegacy TLS\n\u00b6\n\n\nThe default configuration, though secure, does not support some older browsers and operating systems.\n\n\nFor instance, TLS 1.1+ is only enabled by default from Android 5.0 on. At the time of writing,\nMay 2018, \napproximately 15% of Android devices\n\nare not compatible with nginx-ingress's default configuration.\n\n\nTo change this default behavior, use a \nConfigMap\n.\n\n\nA sample ConfigMap fragment to allow these older clients to connect could look something like the following:\n\n\nkind\n:\n \nConfigMap\n\n\napiVersion\n:\n \nv1\n\n\nmetadata\n:\n\n \nname\n:\n \nnginx\n-\nconfig\n\n\ndata\n:\n\n \nssl\n-\nciphers\n:\n \n\"ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA\"\n\n \nssl\n-\nprotocols\n:\n \n\"TLSv1 TLSv1.1 TLSv1.2\"", + "title": "TLS/HTTPS" }, { - "location": "/user-guide/tls/#tls", - "text": "Default SSL Certificate SSL Passthrough HTTPS enforcement HSTS Server-side HTTPS enforcement through redirect Kube-Lego Default TLS Version and Ciphers Legacy TLS", - "title": "TLS" + "location": "/user-guide/tls/#tlshttps", + "text": "", + "title": "TLS/HTTPS" + }, + { + "location": "/user-guide/tls/#tls-secrets", + "text": "Anytime we reference a TLS secret, we mean a PEM-encoded X.509, RSA (2048) secret. You can generate a self-signed certificate and private key with with: $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ${ KEY_FILE } -out ${ CERT_FILE } -subj \"/CN= ${ HOST } /O= ${ HOST } \" ` Then create the secret in the cluster via: kubectl create secret tls ${ CERT_NAME } --key ${ KEY_FILE } --cert ${ CERT_FILE } The resulting secret will be of type kubernetes.io/tls .", + "title": "TLS Secrets" }, { "location": "/user-guide/tls/#default-ssl-certificate", - "text": "NGINX provides the option to configure a server as a catch-all with server_name for requests that do not match any of the configured server names. This configuration works without issues for HTTP traffic.\nIn case of HTTPS, NGINX requires a certificate.\nFor this reason the Ingress controller provides the flag --default-ssl-certificate . The secret behind this flag contains the default certificate to be used in the mentioned scenario. If this flag is not provided NGINX will use a self signed certificate. Running without the flag --default-ssl-certificate : $ curl -v https://10.2.78.7:443 -k * Rebuilt URL to: https://10.2.78.7:443/ * Trying 10.2.78.4... * Connected to 10.2.78.7 (10.2.78.7) port 443 (#0) * ALPN, offering http/1.1 * Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH * successfully set certificate verify locations: * CAfile: /etc/ssl/certs/ca-certificates.crt CApath: /etc/ssl/certs * TLSv1.2 (OUT), TLS header, Certificate Status (22): * TLSv1.2 (OUT), TLS handshake, Client hello (1): * TLSv1.2 (IN), TLS handshake, Server hello (2): * TLSv1.2 (IN), TLS handshake, Certificate (11): * TLSv1.2 (IN), TLS handshake, Server key exchange (12): * TLSv1.2 (IN), TLS handshake, Server finished (14): * TLSv1.2 (OUT), TLS handshake, Client key exchange (16): * TLSv1.2 (OUT), TLS change cipher, Client hello (1): * TLSv1.2 (OUT), TLS handshake, Finished (20): * TLSv1.2 (IN), TLS change cipher, Client hello (1): * TLSv1.2 (IN), TLS handshake, Finished (20): * SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256 * ALPN, server accepted to use http/1.1 * Server certificate: * subject: CN=foo.bar.com * start date: Apr 13 00:50:56 2016 GMT * expire date: Apr 13 00:50:56 2017 GMT * issuer: CN=foo.bar.com * SSL certificate verify result: self signed certificate (18), continuing anyway. > GET / HTTP/1.1 > Host: 10 .2.78.7 > User-Agent: curl/7.47.1 > Accept: */* > < HTTP/1.1 404 Not Found < Server: nginx/1.11.1 < Date: Thu, 21 Jul 2016 15:38:46 GMT < Content-Type: text/html < Transfer-Encoding: chunked < Connection: keep-alive < Strict-Transport-Security: max-age=15724800; includeSubDomains; preload < The page you're looking for could not be found. * Connection #0 to host 10.2.78.7 left intact Specifying --default-ssl-certificate=default/foo-tls : core@localhost ~ $ curl -v https://10.2.78.7:443 -k * Rebuilt URL to: https://10.2.78.7:443/ * Trying 10.2.78.7... * Connected to 10.2.78.7 (10.2.78.7) port 443 (#0) * ALPN, offering http/1.1 * Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH * successfully set certificate verify locations: * CAfile: /etc/ssl/certs/ca-certificates.crt CApath: /etc/ssl/certs * TLSv1.2 (OUT), TLS header, Certificate Status (22): * TLSv1.2 (OUT), TLS handshake, Client hello (1): * TLSv1.2 (IN), TLS handshake, Server hello (2): * TLSv1.2 (IN), TLS handshake, Certificate (11): * TLSv1.2 (IN), TLS handshake, Server key exchange (12): * TLSv1.2 (IN), TLS handshake, Server finished (14): * TLSv1.2 (OUT), TLS handshake, Client key exchange (16): * TLSv1.2 (OUT), TLS change cipher, Client hello (1): * TLSv1.2 (OUT), TLS handshake, Finished (20): * TLSv1.2 (IN), TLS change cipher, Client hello (1): * TLSv1.2 (IN), TLS handshake, Finished (20): * SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256 * ALPN, server accepted to use http/1.1 * Server certificate: * subject: CN=foo.bar.com * start date: Apr 13 00:50:56 2016 GMT * expire date: Apr 13 00:50:56 2017 GMT * issuer: CN=foo.bar.com * SSL certificate verify result: self signed certificate (18), continuing anyway. > GET / HTTP/1.1 > Host: 10 .2.78.7 > User-Agent: curl/7.47.1 > Accept: */* > < HTTP/1.1 404 Not Found < Server: nginx/1.11.1 < Date: Mon, 18 Jul 2016 21:02:59 GMT < Content-Type: text/html < Transfer-Encoding: chunked < Connection: keep-alive < Strict-Transport-Security: max-age=15724800; includeSubDomains; preload < The page you're looking for could not be found. * Connection #0 to host 10.2.78.7 left intact", + "text": "NGINX provides the option to configure a server as a catch-all with server_name \nfor requests that do not match any of the configured server names.\nThis configuration works without out-of-the-box for HTTP traffic.\nFor HTTPS, a certificate is naturally required. For this reason the Ingress controller provides the flag --default-ssl-certificate .\nThe secret referred to by this flag contains the default certificate to be used when\naccessing the catch-all server.\nIf this flag is not provided NGINX will use a self-signed certificate. For instance, if you have a TLS secret foo-tls in the default namespace,\nadd --default-ssl-certificate=default/foo-tls in the nginx-controller deployment.", "title": "Default SSL Certificate" }, { "location": "/user-guide/tls/#ssl-passthrough", - "text": "The flag --enable-ssl-passthrough enables SSL passthrough feature.\nBy default this feature is disabled", + "text": "The flag --enable-ssl-passthrough enables the SSL passthrough feature.\nBy default this feature is disabled. This is required to enable passthrough backends in Ingress configurations. TODO: Improve this documentation.", "title": "SSL Passthrough" }, { "location": "/user-guide/tls/#http-strict-transport-security", - "text": "HTTP Strict Transport Security (HSTS) is an opt-in security enhancement specified through the use of a special response header. Once a supported browser receives this header that browser will prevent any communications from being sent over HTTP to the specified domain and will instead send all communications over HTTPS. By default the controller redirects (301) to HTTPS if there is a TLS Ingress rule. To disable this behavior use hsts: \"false\" in the configuration ConfigMap.", + "text": "HTTP Strict Transport Security (HSTS) is an opt-in security enhancement specified\nthrough the use of a special response header. Once a supported browser receives\nthis header that browser will prevent any communications from being sent over\nHTTP to the specified domain and will instead send all communications over HTTPS. HSTS is enabled by default. To disable this behavior use hsts: \"false\" in the configuration ConfigMap .", "title": "HTTP Strict Transport Security" }, { "location": "/user-guide/tls/#server-side-https-enforcement-through-redirect", - "text": "By default the controller redirects (301) to HTTPS if TLS is enabled for that ingress. If you want to disable that behavior globally, you can use ssl-redirect: \"false\" in the NGINX config map. To configure this feature for specific ingress resources, you can use the nginx.ingress.kubernetes.io/ssl-redirect: \"false\" annotation in the particular resource. When using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to HTTPS even when there is not TLS cert available. This can be achieved by using the nginx.ingress.kubernetes.io/force-ssl-redirect: \"true\" annotation in the particular resource.", + "text": "By default the controller redirects HTTP clients to the HTTPS port\n443 using a 308 Permanent Redirect response if TLS is enabled for that Ingress. This can be disabled globally using ssl-redirect: \"false\" in the NGINX config map ,\nor per-Ingress with the nginx.ingress.kubernetes.io/ssl-redirect: \"false\" \nannotation in the particular resource. Tip When using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a\nredirect to HTTPS even when there is no TLS certificate available.\nThis can be achieved by using the nginx.ingress.kubernetes.io/force-ssl-redirect: \"true\" \nannotation in the particular resource.", "title": "Server-side HTTPS enforcement through redirect" }, { "location": "/user-guide/tls/#automated-certificate-management-with-kube-lego", - "text": "Kube-Lego automatically requests missing or expired certificates from Let's Encrypt by monitoring ingress resources and their referenced secrets. To enable this for an ingress resource you have to add an annotation: kubectl annotate ing ingress-demo kubernetes.io/tls-acme=\"true\" To setup Kube-Lego you can take a look at this full example . The first\nversion to fully support Kube-Lego is nginx Ingress controller 0.8.", + "text": "Tip Kube-Lego has reached end-of-life and is being\nreplaced by cert-manager . Kube-Lego automatically requests missing or expired certificates from Let's Encrypt \nby monitoring ingress resources and their referenced secrets. To enable this for an ingress resource you have to add an annotation: kubectl annotate ing ingress-demo kubernetes.io/tls-acme=\"true\" To setup Kube-Lego you can take a look at this full example .\nThe first version to fully support Kube-Lego is Nginx Ingress controller 0.8.", "title": "Automated Certificate Management with Kube-Lego" }, { "location": "/user-guide/tls/#default-tls-version-and-ciphers", - "text": "To provide the most secure baseline configuration possible, nginx-ingress defaults to using TLS 1.2 and a secure set of TLS ciphers", + "text": "To provide the most secure baseline configuration possible, nginx-ingress defaults to using TLS 1.2 only and a secure set of TLS ciphers .", "title": "Default TLS Version and Ciphers" }, { "location": "/user-guide/tls/#legacy-tls", - "text": "The default configuration, though secure, does not support some older browsers and operating systems. For instance, 20% of Android phones in use today are not compatible with nginx-ingress's default configuration. To change this default behavior, use a ConfigMap . A sample ConfigMap to allow these older clients connect could look something like the following: kind : ConfigMap apiVersion : v1 metadata : \n name : nginx - config data : \n ssl - ciphers : \"ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA\" \n ssl - protocols : \"TLSv1 TLSv1.1 TLSv1.2\"", + "text": "The default configuration, though secure, does not support some older browsers and operating systems. For instance, TLS 1.1+ is only enabled by default from Android 5.0 on. At the time of writing,\nMay 2018, approximately 15% of Android devices \nare not compatible with nginx-ingress's default configuration. To change this default behavior, use a ConfigMap . A sample ConfigMap fragment to allow these older clients to connect could look something like the following: kind : ConfigMap apiVersion : v1 metadata : \n name : nginx - config data : \n ssl - ciphers : \"ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA\" \n ssl - protocols : \"TLSv1 TLSv1.1 TLSv1.2\"", "title": "Legacy TLS" }, { @@ -1135,6 +1150,16 @@ "text": "Using the third party module opentracing-contrib/nginx-opentracing the NGINX ingress controller can configure NGINX to enable OpenTracing instrumentation.\nBy default this feature is disabled. To enable the instrumentation we just need to enable the instrumentation in the configuration configmap and set the host where we should send the traces. In the rnburn/zipkin-date-server \ngithub repository is an example of a dockerized date service. To install the example and zipkin collector run: kubectl create -f https://raw.githubusercontent.com/rnburn/zipkin-date-server/master/kubernetes/zipkin.yaml\nkubectl create -f https://raw.githubusercontent.com/rnburn/zipkin-date-server/master/kubernetes/deployment.yaml Also we need to configure the NGINX controller configmap with the required values: $ echo ' apiVersion: v1 kind: ConfigMap data: enable-opentracing: \"true\" zipkin-collector-host: zipkin.default.svc.cluster.local metadata: name: nginx-configuration namespace: ingress-nginx labels: app: ingress-nginx ' | kubectl replace -f - Using curl we can generate some traces: $ curl -v http:// $( minikube ip ) $ curl -v http:// $( minikube ip ) In the zipkin interface we can see the details:", "title": "OpenTracing" }, + { + "location": "/examples/", + "text": "Ingress examples\n\u00b6\n\n\nThis directory contains a catalog of examples on how to run, configure and scale Ingress.\n\nPlease review the \nprerequisites\n before trying them.\n\n\n\n\n\n\n\n\nCategory\n\n\nName\n\n\nDescription\n\n\nComplexity Level\n\n\n\n\n\n\n\n\n\n\nApps\n\n\nDocker Registry\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nAuth\n\n\nBasic authentication\n\n\npassword protect your website\n\n\nIntermediate\n\n\n\n\n\n\nAuth\n\n\nClient certificate authentication\n\n\nsecure your website with client certificate authentication\n\n\nIntermediate\n\n\n\n\n\n\nAuth\n\n\nExternal authentication plugin\n\n\ndefer to an external authentication service\n\n\nIntermediate\n\n\n\n\n\n\nAuth\n\n\nOAuth external auth\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nConfiguration snippets\n\n\ncustomize nginx location configuration using annotations\n\n\nAdvanced\n\n\n\n\n\n\nCustomization\n\n\nCustom configuration\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nCustom DH parameters for perfect forward secrecy\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nCustom errors\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nCustom headers\n\n\nset custom headers before sending traffic to backends\n\n\nAdvanced\n\n\n\n\n\n\nCustomization\n\n\nCustom upstream check\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nCustom VTS metrics with Prometheus\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nExternal authentication with response header propagation\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nSysctl tuning\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nFeatures\n\n\nRewrite\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nFeatures\n\n\nSession stickiness\n\n\nroute requests consistently to the same endpoint\n\n\nAdvanced\n\n\n\n\n\n\nScaling\n\n\nStatic IP\n\n\na single ingress gets a single static IP\n\n\nIntermediate\n\n\n\n\n\n\nTLS\n\n\nMulti TLS certificate termination\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nTLS\n\n\nTLS termination\n\n\nTODO\n\n\nTODO", + "title": "Ingress examples" + }, + { + "location": "/examples/#ingress-examples", + "text": "This directory contains a catalog of examples on how to run, configure and scale Ingress. \nPlease review the prerequisites before trying them. Category Name Description Complexity Level Apps Docker Registry TODO TODO Auth Basic authentication password protect your website Intermediate Auth Client certificate authentication secure your website with client certificate authentication Intermediate Auth External authentication plugin defer to an external authentication service Intermediate Auth OAuth external auth TODO TODO Customization Configuration snippets customize nginx location configuration using annotations Advanced Customization Custom configuration TODO TODO Customization Custom DH parameters for perfect forward secrecy TODO TODO Customization Custom errors TODO TODO Customization Custom headers set custom headers before sending traffic to backends Advanced Customization Custom upstream check TODO TODO Customization Custom VTS metrics with Prometheus TODO TODO Customization External authentication with response header propagation TODO TODO Customization Sysctl tuning TODO TODO Features Rewrite TODO TODO Features Session stickiness route requests consistently to the same endpoint Advanced Scaling Static IP a single ingress gets a single static IP Intermediate TLS Multi TLS certificate termination TODO TODO TLS TLS termination TODO TODO", + "title": "Ingress examples" + }, { "location": "/examples/PREREQUISITES/", "text": "Prerequisites\n\u00b6\n\n\nMany of the examples in this directory have common prerequisites.\n\n\nTLS certificates\n\u00b6\n\n\nUnless otherwise mentioned, the TLS secret used in examples is a 2048 bit RSA\nkey/cert pair with an arbitrarily chosen hostname, created as follows\n\n\n$\n openssl req -x509 -nodes -days \n365\n -newkey rsa:2048 -keyout tls.key -out tls.crt -subj \n\"/CN=nginxsvc/O=nginxsvc\"\n\n\nGenerating a 2048 bit RSA private key\n\n\n................+++\n\n\n................+++\n\n\nwriting new private key to 'tls.key'\n\n\n-----\n\n\n\n$\n kubectl create secret tls tls-secret --key tls.key --cert tls.crt\n\nsecret \"tls-secret\" created\n\n\n\n\n\n\nCA Authentication\n\u00b6\n\n\nYou can act as your very own CA, or use an existing one. As an exercise / learning, we're going to generate our\nown CA, and also generate a client certificate.\n\n\nThese instructions are based on CoreOS OpenSSL. \nSee live doc.\n\n\nGenerating a CA\n\u00b6\n\n\nFirst of all, you've to generate a CA. This is going to be the one who will sign your client certificates.\nIn real production world, you may face CAs with intermediate certificates, as the following:\n\n\n$\n openssl s_client -connect www.google.com:443\n\n[...]\n\n\n---\n\n\nCertificate chain\n\n\n 0 s:/C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com\n\n\n i:/C=US/O=Google Inc/CN=Google Internet Authority G2\n\n\n 1 s:/C=US/O=Google Inc/CN=Google Internet Authority G2\n\n\n i:/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA\n\n\n 2 s:/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA\n\n\n i:/C=US/O=Equifax/OU=Equifax Secure Certificate Authority\n\n\n\n\n\n\nTo generate our CA Certificate, we've to run the following commands:\n\n\n$\n openssl genrsa -out ca.key \n2048\n\n\n$\n openssl req -x509 -new -nodes -key ca.key -days \n10000\n -out ca.crt -subj \n\"/CN=example-ca\"\n\n\n\n\n\n\nThis will generate two files: A private key (ca.key) and a public key (ca.crt). This CA is valid for 10000 days.\nThe ca.crt can be used later in the step of creation of CA authentication secret.\n\n\nGenerating the client certificate\n\u00b6\n\n\nThe following steps generate a client certificate signed by the CA generated above. This client can be\nused to authenticate in a tls-auth configured ingress.\n\n\nFirst, we need to generate an 'openssl.cnf' file that will be used while signing the keys:\n\n\n[req]\n\n\nreq_extensions = v3_req\n\n\ndistinguished_name = req_distinguished_name\n\n\n[req_distinguished_name]\n\n\n[ v3_req ]\n\n\nbasicConstraints = CA:FALSE\n\n\nkeyUsage = nonRepudiation, digitalSignature, keyEncipherment\n\n\n\n\n\n\nThen, a user generates his very own private key (that he needs to keep secret)\nand a CSR (Certificate Signing Request) that will be sent to the CA to sign and generate a certificate.\n\n\n$\n openssl genrsa -out client1.key \n2048\n\n\n$\n openssl req -new -key client1.key -out client1.csr -subj \n\"/CN=client1\"\n -config openssl.cnf\n\n\n\n\n\nAs the CA receives the generated 'client1.csr' file, it signs it and generates a client.crt certificate:\n\n\n$\n openssl x509 -req -in client1.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client1.crt -days \n365\n -extensions v3_req -extfile openssl.cnf\n\n\n\n\n\nThen, you'll have 3 files: the client.key (user's private key), client.crt (user's public key) and client.csr (disposable CSR).\n\n\nCreating the CA Authentication secret\n\u00b6\n\n\nIf you're using the CA Authentication feature, you need to generate a secret containing \nall the authorized CAs. You must download them from your CA site in PEM format (like the following):\n\n\n-----BEGIN CERTIFICATE-----\n[....]\n-----END CERTIFICATE-----\n\n\n\n\n\nYou can have as many certificates as you want. If they're in the binary DER format, \nyou can convert them as the following:\n\n\n$\n openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem\n\n\n\n\n\nThen, you've to concatenate them all in only one file, named 'ca.crt' as the following:\n\n\n$\n cat certificate1.crt certificate2.crt certificate3.crt >> ca.crt\n\n\n\n\n\nThe final step is to create a secret with the content of this file. This secret is going to be used in \nthe TLS Auth directive:\n\n\n$\n kubectl create secret generic caingress --namespace\n=\ndefault --from-file\n=\nca.crt\n=\n\n\n\n\n\n\nNote:\n You can also generate the CA Authentication Secret along with the TLS Secret by using:\n\n\n$\n kubectl create secret generic caingress --namespace\n=\ndefault --from-file\n=\nca.crt\n=\n --from-file\n=\ntls.crt\n=\n --from-file\n=\ntls.key\n=\n\n\n\n\n\n\nTest HTTP Service\n\u00b6\n\n\nAll examples that require a test HTTP Service use the standard http-svc pod,\nwhich you can deploy as follows\n\n\n$\n kubectl create -f http-svc.yaml\n\nservice \"http-svc\" created\n\n\nreplicationcontroller \"http-svc\" created\n\n\n\n$\n kubectl get po\n\nNAME READY STATUS RESTARTS AGE\n\n\nhttp-svc-p1t3t 1/1 Running 0 1d\n\n\n\n$\n kubectl get svc\n\nNAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE\n\n\nhttp-svc 10.0.122.116 80:30301/TCP 1d\n\n\n\n\n\n\nYou can test that the HTTP Service works by exposing it temporarily\n\n\n$\n kubectl patch svc http-svc -p \n'{\"spec\":{\"type\": \"LoadBalancer\"}}'\n\n\n\"http-svc\" patched\n\n\n\n$\n kubectl get svc http-svc\n\nNAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE\n\n\nhttp-svc 10.0.122.116 80:30301/TCP 1d\n\n\n\n$\n kubectl describe svc http-svc\n\nName: http-svc\n\n\nNamespace: default\n\n\nLabels: app=http-svc\n\n\nSelector: app=http-svc\n\n\nType: LoadBalancer\n\n\nIP: 10.0.122.116\n\n\nLoadBalancer Ingress: 108.59.87.136\n\n\nPort: http 80/TCP\n\n\nNodePort: http 30301/TCP\n\n\nEndpoints: 10.180.1.6:8080\n\n\nSession Affinity: None\n\n\nEvents:\n\n\n FirstSeen LastSeen Count From SubObjectPath Type Reason Message\n\n\n --------- -------- ----- ---- ------------- -------- ------ -------\n\n\n 1m 1m 1 {service-controller } Normal Type ClusterIP -> LoadBalancer\n\n\n 1m 1m 1 {service-controller } Normal CreatingLoadBalancer Creating load balancer\n\n\n 16s 16s 1 {service-controller } Normal CreatedLoadBalancer Created load balancer\n\n\n\n$\n curl \n108\n.59.87.126\n\nCLIENT VALUES:\n\n\nclient_address=10.240.0.3\n\n\ncommand=GET\n\n\nreal path=/\n\n\nquery=nil\n\n\nrequest_version=1.1\n\n\nrequest_uri=http://108.59.87.136:8080/\n\n\n\nSERVER VALUES:\n\n\nserver_version=nginx: 1.9.11 - lua: 10001\n\n\n\nHEADERS RECEIVED:\n\n\naccept=*/*\n\n\nhost=108.59.87.136\n\n\nuser-agent=curl/7.46.0\n\n\nBODY:\n\n\n-no body in request-\n\n\n\n$\n kubectl patch svc http-svc -p \n'{\"spec\":{\"type\": \"NodePort\"}}'\n\n\n\"http-svc\" patched", @@ -1175,36 +1200,6 @@ "text": "All examples that require a test HTTP Service use the standard http-svc pod,\nwhich you can deploy as follows $ kubectl create -f http-svc.yaml service \"http-svc\" created replicationcontroller \"http-svc\" created $ kubectl get po NAME READY STATUS RESTARTS AGE http-svc-p1t3t 1/1 Running 0 1d $ kubectl get svc NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE http-svc 10.0.122.116 80:30301/TCP 1d You can test that the HTTP Service works by exposing it temporarily $ kubectl patch svc http-svc -p '{\"spec\":{\"type\": \"LoadBalancer\"}}' \"http-svc\" patched $ kubectl get svc http-svc NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE http-svc 10.0.122.116 80:30301/TCP 1d $ kubectl describe svc http-svc Name: http-svc Namespace: default Labels: app=http-svc Selector: app=http-svc Type: LoadBalancer IP: 10.0.122.116 LoadBalancer Ingress: 108.59.87.136 Port: http 80/TCP NodePort: http 30301/TCP Endpoints: 10.180.1.6:8080 Session Affinity: None Events: FirstSeen LastSeen Count From SubObjectPath Type Reason Message --------- -------- ----- ---- ------------- -------- ------ ------- 1m 1m 1 {service-controller } Normal Type ClusterIP -> LoadBalancer 1m 1m 1 {service-controller } Normal CreatingLoadBalancer Creating load balancer 16s 16s 1 {service-controller } Normal CreatedLoadBalancer Created load balancer $ curl 108 .59.87.126 CLIENT VALUES: client_address=10.240.0.3 command=GET real path=/ query=nil request_version=1.1 request_uri=http://108.59.87.136:8080/ SERVER VALUES: server_version=nginx: 1.9.11 - lua: 10001 HEADERS RECEIVED: accept=*/* host=108.59.87.136 user-agent=curl/7.46.0 BODY: -no body in request- $ kubectl patch svc http-svc -p '{\"spec\":{\"type\": \"NodePort\"}}' \"http-svc\" patched", "title": "Test HTTP Service" }, - { - "location": "/examples/README/", - "text": "Ingress examples\n\u00b6\n\n\nThis directory contains a catalog of examples on how to run, configure and\nscale Ingress. Please review the \nprerequisites\n before\ntrying them.\n\n\nScaling\n\u00b6\n\n\n\n\n\n\n\n\nName\n\n\nDescription\n\n\nComplexity Level\n\n\n\n\n\n\n\n\n\n\nStatic-ip\n\n\na single ingress gets a single static ip\n\n\nIntermediate\n\n\n\n\n\n\n\n\nAlgorithms\n\u00b6\n\n\n\n\n\n\n\n\nName\n\n\nDescription\n\n\nComplexity Level\n\n\n\n\n\n\n\n\n\n\nSession stickyness\n\n\nroute requests consistently to the same endpoint\n\n\nAdvanced\n\n\n\n\n\n\n\n\nAuth\n\u00b6\n\n\n\n\n\n\n\n\nName\n\n\nDescription\n\n\nComplexity Level\n\n\n\n\n\n\n\n\n\n\nBasic auth\n\n\npassword protect your website\n\n\nnginx\n\n\n\n\n\n\nClient certificate authentication\n\n\nsecure your website with client certificate authentication\n\n\nnginx\n\n\n\n\n\n\nExternal auth plugin\n\n\ndefer to an external auth service\n\n\nIntermediate\n\n\n\n\n\n\n\n\nCustomization\n\u00b6\n\n\n\n\n\n\n\n\nName\n\n\nDescription\n\n\nComplexity Level\n\n\n\n\n\n\n\n\n\n\nconfiguration-snippets\n\n\ncustomize nginx location configuration using annotations\n\n\nAdvanced\n\n\n\n\n\n\ncustom-headers\n\n\nset custom headers before send traffic to backends\n\n\nAdvanced", - "title": "Ingress examples" - }, - { - "location": "/examples/README/#ingress-examples", - "text": "This directory contains a catalog of examples on how to run, configure and\nscale Ingress. Please review the prerequisites before\ntrying them.", - "title": "Ingress examples" - }, - { - "location": "/examples/README/#scaling", - "text": "Name Description Complexity Level Static-ip a single ingress gets a single static ip Intermediate", - "title": "Scaling" - }, - { - "location": "/examples/README/#algorithms", - "text": "Name Description Complexity Level Session stickyness route requests consistently to the same endpoint Advanced", - "title": "Algorithms" - }, - { - "location": "/examples/README/#auth", - "text": "Name Description Complexity Level Basic auth password protect your website nginx Client certificate authentication secure your website with client certificate authentication nginx External auth plugin defer to an external auth service Intermediate", - "title": "Auth" - }, - { - "location": "/examples/README/#customization", - "text": "Name Description Complexity Level configuration-snippets customize nginx location configuration using annotations Advanced custom-headers set custom headers before send traffic to backends Advanced", - "title": "Customization" - }, { "location": "/examples/affinity/cookie/README/", "text": "Sticky Session\n\u00b6\n\n\nThis example demonstrates how to achieve session affinity using cookies\n\n\nDeployment\n\u00b6\n\n\nSession stickiness is achieved through 3 annotations on the Ingress, as shown in the \nexample\n.\n\n\n\n\n\n\n\n\nName\n\n\nDescription\n\n\nValues\n\n\n\n\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/affinity\n\n\nSets the affinity type\n\n\nstring (in NGINX only \ncookie\n is possible\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/session-cookie-name\n\n\nName of the cookie that will be used\n\n\nstring (default to INGRESSCOOKIE)\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/session-cookie-hash\n\n\nType of hash that will be used in cookie value\n\n\nsha1/md5/index\n\n\n\n\n\n\n\n\nYou can create the ingress to test this\n\n\nkubectl create -f ingress.yaml\n\n\n\n\n\n\nValidation\n\u00b6\n\n\nYou can confirm that the Ingress works.\n\n\n$\n kubectl describe ing nginx-test\n\nName: nginx-test\n\n\nNamespace: default\n\n\nAddress: \n\n\nDefault backend: default-http-backend:80 (10.180.0.4:8080,10.240.0.2:8080)\n\n\nRules:\n\n\n Host Path Backends\n\n\n ---- ---- --------\n\n\n stickyingress.example.com \n\n\n / nginx-service:80 ()\n\n\nAnnotations:\n\n\n affinity: cookie\n\n\n session-cookie-hash: sha1\n\n\n session-cookie-name: INGRESSCOOKIE\n\n\nEvents:\n\n\n FirstSeen LastSeen Count From SubObjectPath Type Reason Message\n\n\n --------- -------- ----- ---- ------------- -------- ------ -------\n\n\n 7s 7s 1 {nginx-ingress-controller } Normal CREATE default/nginx-test\n\n\n\n\n$\n curl -I http://stickyingress.example.com\n\nHTTP/1.1 200 OK\n\n\nServer: nginx/1.11.9\n\n\nDate: Fri, 10 Feb 2017 14:11:12 GMT\n\n\nContent-Type: text/html\n\n\nContent-Length: 612\n\n\nConnection: keep-alive\n\n\nSet-Cookie: INGRESSCOOKIE=a9907b79b248140b56bb13723f72b67697baac3d; Path=/; HttpOnly\n\n\nLast-Modified: Tue, 24 Jan 2017 14:02:19 GMT\n\n\nETag: \"58875e6b-264\"\n\n\nAccept-Ranges: bytes\n\n\n\n\n\n\nIn the example above, you can see a line containing the 'Set-Cookie: INGRESSCOOKIE' setting the right defined stickiness cookie.\nThis cookie is created by NGINX containing the hash of the used upstream in that request. \nIf the user changes this cookie, NGINX creates a new one and redirect the user to another upstream.\n\n\nIf the backend pool grows up NGINX will keep sending the requests through the same server of the first request, even if it's overloaded.\n\n\nWhen the backend server is removed, the requests are then re-routed to another upstream server and NGINX creates a new cookie, as the previous hash became invalid.\n\n\nWhen you have more than one Ingress Object pointing to the same Service, but one containing affinity configuration and other don't, the first created Ingress will be used. \nThis means that you can face the situation that you've configured Session Affinity in one Ingress and it doesn't reflects in NGINX configuration, because there is another Ingress Object pointing to the same service that doesn't configure this.", @@ -1265,6 +1260,36 @@ "text": "Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml\ningress \"external-auth\" created\n\n$ kubectl get ing external-auth\nNAME HOSTS ADDRESS PORTS AGE\nexternal-auth external-auth-01.sample.com 172 .17.4.99 80 13s\n\n$ kubectl get ing external-auth -o yaml\napiVersion: extensions/v1beta1\nkind: Ingress\nmetadata:\n annotations:\n nginx.ingress.kubernetes.io/auth-url: https://httpbin.org/basic-auth/user/passwd\n creationTimestamp: 2016 -10-03T13:50:35Z\n generation: 1 \n name: external-auth\n namespace: default\n resourceVersion: \"2068378\" \n selfLink: /apis/extensions/v1beta1/namespaces/default/ingresses/external-auth\n uid: 5c388f1d-8970-11e6-9004-080027d2dc94\nspec:\n rules:\n - host: external-auth-01.sample.com\n http:\n paths:\n - backend:\n serviceName: http-svc\n servicePort: 80 \n path: /\nstatus:\n loadBalancer:\n ingress:\n - ip: 172 .17.4.99\n$ Test 1: no username/password (expect code 401) $ curl -k http://172.17.4.99 -v -H 'Host: external-auth-01.sample.com' * Rebuilt URL to: http://172.17.4.99/ * Trying 172.17.4.99... * Connected to 172.17.4.99 (172.17.4.99) port 80 (#0) > GET / HTTP/1.1 > Host: external-auth-01.sample.com > User-Agent: curl/7.50.1 > Accept: */* > < HTTP/1.1 401 Unauthorized < Server: nginx/1.11.3 < Date: Mon, 03 Oct 2016 14:52:08 GMT < Content-Type: text/html < Content-Length: 195 < Connection: keep-alive < WWW-Authenticate: Basic realm=\"Fake Realm\" < 401 Authorization Required

    401 Authorization Required

    nginx/1.11.3
    * Connection #0 to host 172.17.4.99 left intact Test 2: valid username/password (expect code 200) $ curl -k http://172.17.4.99 -v -H 'Host: external-auth-01.sample.com' -u 'user:passwd' \n* Rebuilt URL to: http://172.17.4.99/\n* Trying 172 .17.4.99...\n* Connected to 172 .17.4.99 ( 172 .17.4.99 ) port 80 ( #0) \n* Server auth using Basic with user 'user' \n> GET / HTTP/1.1\n> Host: external-auth-01.sample.com\n> Authorization: Basic dXNlcjpwYXNzd2Q = \n> User-Agent: curl/7.50.1\n> Accept: */*\n>\n< HTTP/1.1 200 OK\n< Server: nginx/1.11.3\n< Date: Mon, 03 Oct 2016 14 :52:50 GMT\n< Content-Type: text/plain\n< Transfer-Encoding: chunked\n< Connection: keep-alive\n<\nCLIENT VALUES: client_address = 10 .2.60.2 command = GET\nreal path = / query = nil request_version = 1 .1 request_uri = http://external-auth-01.sample.com:8080/\n\nSERVER VALUES: server_version = nginx: 1 .9.11 - lua: 10001 \n\nHEADERS RECEIVED: accept = */* authorization = Basic dXNlcjpwYXNzd2Q = connection = close host = external-auth-01.sample.com\nuser-agent = curl/7.50.1\nx-forwarded-for = 10 .2.60.1\nx-forwarded-host = external-auth-01.sample.com\nx-forwarded-port = 80 \nx-forwarded-proto = http\nx-real-ip = 10 .2.60.1\nBODY:\n* Connection #0 to host 172.17.4.99 left intact \n-no body in request- Test 3: invalid username/password (expect code 401) curl -k http://172.17.4.99 -v -H 'Host: external-auth-01.sample.com' -u 'user:user'\n* Rebuilt URL to: http://172.17.4.99/\n* Trying 172.17.4.99...\n* Connected to 172.17.4.99 (172.17.4.99) port 80 (#0)\n* Server auth using Basic with user 'user'\n> GET / HTTP/1.1\n> Host: external-auth-01.sample.com\n> Authorization: Basic dXNlcjp1c2Vy\n> User-Agent: curl/7.50.1\n> Accept: */*\n> < HTTP /1.1 401 Unauthorized < Server: nginx/1.11.3 < Date: Mon, 03 Oct 2016 14:53:04 GMT < Content-Type: text/html < Content-Length: 195 < Connection: keep-alive * Authentication problem. Ignoring this. < WWW-Authenticate: Basic realm= \"Fake Realm\" < 401 Authorization Required

    401 Authorization Required

    nginx/1.11.3
    \n* Connection #0 to host 172.17.4.99 left intact", "title": "Example 1:" }, + { + "location": "/examples/auth/oauth-external-auth/README/", + "text": "External Authentication\n\u00b6\n\n\nOverview\n\u00b6\n\n\nThe \nauth-url\n and \nauth-signin\n annotations allow you to use an external\nauthentication provider to protect your Ingress resources.\n\n\n\n\nImportant\n\n\nthis annotation requires \nnginx-ingress-controller v0.9.0\n or greater.)\n\n\n\n\nKey Detail\n\u00b6\n\n\nThis functionality is enabled by deploying multiple Ingress objects for a single host.\nOne Ingress object has no special annotations and handles authentication.\n\n\nOther Ingress objects can then be annotated in such a way that require the user to\nauthenticate against the first Ingress's endpoint, and can redirect \n401\ns to the\nsame endpoint.\n\n\nSample:\n\n\n...\n\n\nmetadata\n:\n\n \nname\n:\n \napplication\n\n \nannotations\n:\n\n \n\"nginx.ingress.kubernetes.io/auth-url\"\n:\n \n\"https://$host/oauth2/auth\"\n\n \n\"nginx.ingress.kubernetes.io/auth-signin\"\n:\n \n\"https://$host/oauth2/sign_in\"\n\n\n...\n\n\n\n\n\n\nExample: OAuth2 Proxy + Kubernetes-Dashboard\n\u00b6\n\n\nThis example will show you how to deploy \noauth2_proxy\n\ninto a Kubernetes cluster and use it to protect the Kubernetes Dashboard using github as oAuth2 provider\n\n\nPrepare\n\u00b6\n\n\n\n\nInstall the kubernetes dashboard\n\n\n\n\nkubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.5.0.yaml\n\n\n\n\n\n\n\n\nCreate a \ncustom Github OAuth application\n\n\n\n\n\n\n\n\nHomepage URL is the FQDN in the Ingress rule, like \nhttps://foo.bar.com\n\n\nAuthorization callback URL is the same as the base FQDN plus \n/oauth2\n, like \nhttps://foo.bar.com/oauth2\n\n\n\n\n\n\n\n\n\n\nConfigure oauth2_proxy values in the file oauth2-proxy.yaml with the values:\n\n\n\n\n\n\nOAUTH2_PROXY_CLIENT_ID with the github \n\n\n\n\n\nOAUTH2_PROXY_CLIENT_SECRET with the github \n\n\n\n\n\nOAUTH2_PROXY_COOKIE_SECRET with value of \npython\n \n-\nc\n \n'import os,base64; print base64.b64encode(os.urandom(16))'\n \n\n\n\n\n\n\nCustomize the contents of the file dashboard-ingress.yaml:\n\n\n\n\n\n\nReplace \n__INGRESS_HOST__\n with a valid FQDN and \n__INGRESS_SECRET__\n with a Secret with a valid SSL certificate.\n\n\n\n\nDeploy the oauth2 proxy and the ingress rules running:\n\n\n\n\n$\n kubectl create -f oauth2-proxy.yaml,dashboard-ingress.yaml\n\n\n\n\n\nTest the oauth integration accessing the configured URL, like \nhttps://foo.bar.com", + "title": "External Authentication" + }, + { + "location": "/examples/auth/oauth-external-auth/README/#external-authentication", + "text": "", + "title": "External Authentication" + }, + { + "location": "/examples/auth/oauth-external-auth/README/#overview", + "text": "The auth-url and auth-signin annotations allow you to use an external\nauthentication provider to protect your Ingress resources. Important this annotation requires nginx-ingress-controller v0.9.0 or greater.)", + "title": "Overview" + }, + { + "location": "/examples/auth/oauth-external-auth/README/#key-detail", + "text": "This functionality is enabled by deploying multiple Ingress objects for a single host.\nOne Ingress object has no special annotations and handles authentication. Other Ingress objects can then be annotated in such a way that require the user to\nauthenticate against the first Ingress's endpoint, and can redirect 401 s to the\nsame endpoint. Sample: ... metadata : \n name : application \n annotations : \n \"nginx.ingress.kubernetes.io/auth-url\" : \"https://$host/oauth2/auth\" \n \"nginx.ingress.kubernetes.io/auth-signin\" : \"https://$host/oauth2/sign_in\" ...", + "title": "Key Detail" + }, + { + "location": "/examples/auth/oauth-external-auth/README/#example-oauth2-proxy-kubernetes-dashboard", + "text": "This example will show you how to deploy oauth2_proxy \ninto a Kubernetes cluster and use it to protect the Kubernetes Dashboard using github as oAuth2 provider", + "title": "Example: OAuth2 Proxy + Kubernetes-Dashboard" + }, + { + "location": "/examples/auth/oauth-external-auth/README/#prepare", + "text": "Install the kubernetes dashboard kubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.5.0.yaml Create a custom Github OAuth application Homepage URL is the FQDN in the Ingress rule, like https://foo.bar.com Authorization callback URL is the same as the base FQDN plus /oauth2 , like https://foo.bar.com/oauth2 Configure oauth2_proxy values in the file oauth2-proxy.yaml with the values: OAUTH2_PROXY_CLIENT_ID with the github OAUTH2_PROXY_CLIENT_SECRET with the github OAUTH2_PROXY_COOKIE_SECRET with value of python - c 'import os,base64; print base64.b64encode(os.urandom(16))' Customize the contents of the file dashboard-ingress.yaml: Replace __INGRESS_HOST__ with a valid FQDN and __INGRESS_SECRET__ with a Secret with a valid SSL certificate. Deploy the oauth2 proxy and the ingress rules running: $ kubectl create -f oauth2-proxy.yaml,dashboard-ingress.yaml Test the oauth integration accessing the configured URL, like https://foo.bar.com", + "title": "Prepare" + }, { "location": "/examples/customization/configuration-snippets/README/", "text": "Configuration Snippets\n\u00b6\n\n\nIngress\n\u00b6\n\n\nThe Ingress in this example adds a custom header to Nginx configuration that only applies to that specific Ingress. If you want to add headers that apply globally to all Ingresses, please have a look at \nthis example\n.\n\n\n$\n kubectl apply -f ingress.yaml\n\n\n\n\n\nTest\n\u00b6\n\n\nCheck if the contents of the annotation are present in the nginx.conf file using:\n\nkubectl exec nginx-ingress-controller-873061567-4n3k2 -n kube-system cat /etc/nginx/nginx.conf", @@ -1332,13 +1357,13 @@ }, { "location": "/examples/customization/custom-vts-metrics-prometheus/README/", - "text": "Deploying the Nginx Ingress controller\n\u00b6\n\n\nThis example aims to demonstrate the deployment of an nginx ingress controller and use a ConfigMap to enable \nnginx vts module\n to export metrics in prometheus format. \n\n\nvts-metrics\n\u00b6\n\n\nVts-metrics export NGINX metrics. To deploy all the files simply run \nkubectl apply -f nginx\n. A deployment and service will be\ncreated which already has a \nprometheus.io/scrape: 'true'\n annotation and if you added\nthe recommended Prometheus service-endpoint scraping \nconfiguration\n,\nPrometheus will scrape it automatically and you start using the generated metrics right away.\n\n\nCustom configuration\n\u00b6\n\n\napiVersion: v1\n\n\ndata:\n\n\n enable-vts-status: \"true\"\n\n\nkind: ConfigMap\n\n\nmetadata:\n\n\n name: nginx-configuration\n\n\n namespace: ingress-nginx\n\n\n labels:\n\n\n app: ingress-nginx\n\n\n\n\n\n\n$\n kubectl apply -f nginx-vts-metrics-conf.yaml\n\n\n\n\n\nResult\n\u00b6\n\n\nCheck whether the ingress controller successfully generated the NGINX vts status:\n\n\n$\n kubectl \nexec\n nginx-ingress-controller-873061567-4n3k2 -n ingress-nginx cat /etc/nginx/nginx.conf\n|\ngrep vhost_traffic_status_display\n\n vhost_traffic_status_display;\n\n\n vhost_traffic_status_display_format html;\n\n\n\n\n\n\nNGINX vts dashboard\n\u00b6\n\n\nThe vts dashboard provides real time metrics. \n\n\n\n\nBecause the vts port it's not yet exposed, you should forward the controller port to see it.\n\n\n$\n kubectl port-forward \n$(\nkubectl get pods --selector\n=\nk8s-app\n=\nnginx-ingress-controller -n ingress-nginx --output\n=\njsonpath\n={\n.items..metadata.name\n}\n)\n -n ingress-nginx \n18080\n\n\n\n\n\n\nNow open the url \nhttp://localhost:18080/nginx_status\n in your browser.\n\n\nPrometheus metrics output\n\u00b6\n\n\nNGINX Ingress controller already has a parser to convert vts metrics to Prometheus format. It exports prometheus metrics to the address \n:10254/metrics\n.\n\n\n$\n kubectl \nexec\n -ti -n ingress-nginx \n$(\nkubectl get pods --selector\n=\nk8s-app\n=\nnginx-ingress-controller -n kube-system --output\n=\njsonpath\n={\n.items..metadata.name\n}\n)\n curl localhost:10254/metrics\n\ningress_controller_ssl_expire_time_seconds{host=\"foo.bar.com\"} -6.21355968e+10\n\n\n#\n HELP ingress_controller_success Cumulative number of Ingress controller reload operations\n\n#\n TYPE ingress_controller_success counter\n\ningress_controller_success{count=\"reloads\"} 3\n\n\n#\n HELP nginx_bytes_total Nginx bytes count\n\n#\n TYPE nginx_bytes_total counter\n\nnginx_bytes_total{direction=\"in\",ingress_class=\"nginx\",namespace=\"\",server_zone=\"*\"} 3708\n\n\nnginx_bytes_total{direction=\"in\",ingress_class=\"nginx\",namespace=\"\",server_zone=\"_\"} 3708\n\n\nnginx_bytes_total{direction=\"out\",ingress_class=\"nginx\",namespace=\"\",server_zone=\"*\"} 5256\n\n\nnginx_bytes_total{direction=\"out\",ingress_class=\"nginx\",namespace=\"\",server_zone=\"_\"} 5256\n\n\n\n\n\n\nCustomize metrics\n\u00b6\n\n\nThe default \nvts vhost key\n is \n$geoip_country_code country::*\n that expose metrics grouped by server and country code. The example below show how to have metrics grouped by server and server path.\n\n\n\n\nNGINX custom configuration ( http level )\n\u00b6\n\n\n apiVersion: v1\n kind: ConfigMap\n data:\n enable-vts-status: \"true\"\n vts-default-filter-key: \"$server_name\"\n...\n\n\n\n\n\nCustomize ingress\n\u00b6\n\n\n apiVersion: extensions/v1beta1\n kind: Ingress\n metadata:\n annotations:\n nginx.ingress.kubernetes.io/vts-filter-key: $uri $server_name\n name: ingress\n\n\n\n\n\nResult\n\u00b6", - "title": "Deploying the Nginx Ingress controller" + "text": "Custom VTS metrics with Prometheus\n\u00b6\n\n\nThis example aims to demonstrate the deployment of an nginx ingress controller and use a ConfigMap to enable \nnginx vts module\n to export metrics in prometheus format. \n\n\nvts-metrics\n\u00b6\n\n\nVts-metrics export NGINX metrics. To deploy all the files simply run \nkubectl apply -f nginx\n. A deployment and service will be\ncreated which already has a \nprometheus.io/scrape: 'true'\n annotation and if you added\nthe recommended Prometheus service-endpoint scraping \nconfiguration\n,\nPrometheus will scrape it automatically and you start using the generated metrics right away.\n\n\nCustom configuration\n\u00b6\n\n\napiVersion: v1\n\n\ndata:\n\n\n enable-vts-status: \"true\"\n\n\nkind: ConfigMap\n\n\nmetadata:\n\n\n name: nginx-configuration\n\n\n namespace: ingress-nginx\n\n\n labels:\n\n\n app: ingress-nginx\n\n\n\n\n\n\n$\n kubectl apply -f nginx-vts-metrics-conf.yaml\n\n\n\n\n\nResult\n\u00b6\n\n\nCheck whether the ingress controller successfully generated the NGINX vts status:\n\n\n$\n kubectl \nexec\n nginx-ingress-controller-873061567-4n3k2 -n ingress-nginx cat /etc/nginx/nginx.conf\n|\ngrep vhost_traffic_status_display\n\n vhost_traffic_status_display;\n\n\n vhost_traffic_status_display_format html;\n\n\n\n\n\n\nNGINX vts dashboard\n\u00b6\n\n\nThe vts dashboard provides real time metrics. \n\n\n\n\nBecause the vts port it's not yet exposed, you should forward the controller port to see it.\n\n\n$\n kubectl port-forward \n$(\nkubectl get pods --selector\n=\nk8s-app\n=\nnginx-ingress-controller -n ingress-nginx --output\n=\njsonpath\n={\n.items..metadata.name\n}\n)\n -n ingress-nginx \n18080\n\n\n\n\n\n\nNow open the url \nhttp://localhost:18080/nginx_status\n in your browser.\n\n\nPrometheus metrics output\n\u00b6\n\n\nNGINX Ingress controller already has a parser to convert vts metrics to Prometheus format. It exports prometheus metrics to the address \n:10254/metrics\n.\n\n\n$\n kubectl \nexec\n -ti -n ingress-nginx \n$(\nkubectl get pods --selector\n=\nk8s-app\n=\nnginx-ingress-controller -n kube-system --output\n=\njsonpath\n={\n.items..metadata.name\n}\n)\n curl localhost:10254/metrics\n\ningress_controller_ssl_expire_time_seconds{host=\"foo.bar.com\"} -6.21355968e+10\n\n\n#\n HELP ingress_controller_success Cumulative number of Ingress controller reload operations\n\n#\n TYPE ingress_controller_success counter\n\ningress_controller_success{count=\"reloads\"} 3\n\n\n#\n HELP nginx_bytes_total Nginx bytes count\n\n#\n TYPE nginx_bytes_total counter\n\nnginx_bytes_total{direction=\"in\",ingress_class=\"nginx\",namespace=\"\",server_zone=\"*\"} 3708\n\n\nnginx_bytes_total{direction=\"in\",ingress_class=\"nginx\",namespace=\"\",server_zone=\"_\"} 3708\n\n\nnginx_bytes_total{direction=\"out\",ingress_class=\"nginx\",namespace=\"\",server_zone=\"*\"} 5256\n\n\nnginx_bytes_total{direction=\"out\",ingress_class=\"nginx\",namespace=\"\",server_zone=\"_\"} 5256\n\n\n\n\n\n\nCustomize metrics\n\u00b6\n\n\nThe default \nvts vhost key\n is \n$geoip_country_code country::*\n that expose metrics grouped by server and country code. The example below show how to have metrics grouped by server and server path.\n\n\n\n\nNGINX custom configuration ( http level )\n\u00b6\n\n\n apiVersion: v1\n kind: ConfigMap\n data:\n enable-vts-status: \"true\"\n vts-default-filter-key: \"$server_name\"\n...\n\n\n\n\n\nCustomize ingress\n\u00b6\n\n\n apiVersion: extensions/v1beta1\n kind: Ingress\n metadata:\n annotations:\n nginx.ingress.kubernetes.io/vts-filter-key: $uri $server_name\n name: ingress\n\n\n\n\n\nResult\n\u00b6", + "title": "Custom VTS metrics with Prometheus" }, { - "location": "/examples/customization/custom-vts-metrics-prometheus/README/#deploying-the-nginx-ingress-controller", + "location": "/examples/customization/custom-vts-metrics-prometheus/README/#custom-vts-metrics-with-prometheus", "text": "This example aims to demonstrate the deployment of an nginx ingress controller and use a ConfigMap to enable nginx vts module to export metrics in prometheus format.", - "title": "Deploying the Nginx Ingress controller" + "title": "Custom VTS metrics with Prometheus" }, { "location": "/examples/customization/custom-vts-metrics-prometheus/README/#vts-metrics", @@ -1397,13 +1422,13 @@ }, { "location": "/examples/customization/ssl-dh-param/README/", - "text": "Deploying the Nginx Ingress controller\n\u00b6\n\n\nThis example aims to demonstrate the deployment of an nginx ingress controller and\nuse a ConfigMap to configure custom Diffie-Hellman parameters file to help with\n\"Perfect Forward Secrecy\".\n\n\nCustom configuration\n\u00b6\n\n\n$\n cat configmap.yaml\n\napiVersion: v1\n\n\ndata:\n\n\n ssl-dh-param: \"ingress-nginx/lb-dhparam\"\n\n\nkind: ConfigMap\n\n\nmetadata:\n\n\n name: nginx-configuration\n\n\n namespace: ingress-nginx\n\n\n labels:\n\n\n app: ingress-nginx\n\n\n\n\n\n\n$\n kubectl create -f configmap.yaml\n\n\n\n\n\nCustom DH parameters secret\n\u00b6\n\n\n$\n> openssl dhparam \n1024\n \n2\n> /dev/null \n|\n base64\n\nLS0tLS1CRUdJTiBESCBQQVJBTUVURVJ...\n\n\n\n\n\n\n$\n cat ssl-dh-param.yaml\n\napiVersion: v1\n\n\ndata:\n\n\n dhparam.pem: \"LS0tLS1CRUdJTiBESCBQQVJBTUVURVJ...\"\n\n\nkind: ConfigMap\n\n\nmetadata:\n\n\n name: nginx-configuration\n\n\n namespace: ingress-nginx\n\n\n labels:\n\n\n app: ingress-nginx\n\n\n\n\n\n\n$\n kubectl create -f ssl-dh-param.yaml\n\n\n\n\n\nTest\n\u00b6\n\n\nCheck the contents of the configmap is present in the nginx.conf file using:\n\nkubectl exec nginx-ingress-controller-873061567-4n3k2 -n kube-system cat /etc/nginx/nginx.conf", - "title": "Deploying the Nginx Ingress controller" + "text": "Custom DH parameters for perfect forward secrecy\n\u00b6\n\n\nThis example aims to demonstrate the deployment of an nginx ingress controller and\nuse a ConfigMap to configure custom Diffie-Hellman parameters file to help with\n\"Perfect Forward Secrecy\".\n\n\nCustom configuration\n\u00b6\n\n\n$\n cat configmap.yaml\n\napiVersion: v1\n\n\ndata:\n\n\n ssl-dh-param: \"ingress-nginx/lb-dhparam\"\n\n\nkind: ConfigMap\n\n\nmetadata:\n\n\n name: nginx-configuration\n\n\n namespace: ingress-nginx\n\n\n labels:\n\n\n app: ingress-nginx\n\n\n\n\n\n\n$\n kubectl create -f configmap.yaml\n\n\n\n\n\nCustom DH parameters secret\n\u00b6\n\n\n$\n> openssl dhparam \n1024\n \n2\n> /dev/null \n|\n base64\n\nLS0tLS1CRUdJTiBESCBQQVJBTUVURVJ...\n\n\n\n\n\n\n$\n cat ssl-dh-param.yaml\n\napiVersion: v1\n\n\ndata:\n\n\n dhparam.pem: \"LS0tLS1CRUdJTiBESCBQQVJBTUVURVJ...\"\n\n\nkind: ConfigMap\n\n\nmetadata:\n\n\n name: nginx-configuration\n\n\n namespace: ingress-nginx\n\n\n labels:\n\n\n app: ingress-nginx\n\n\n\n\n\n\n$\n kubectl create -f ssl-dh-param.yaml\n\n\n\n\n\nTest\n\u00b6\n\n\nCheck the contents of the configmap is present in the nginx.conf file using:\n\nkubectl exec nginx-ingress-controller-873061567-4n3k2 -n kube-system cat /etc/nginx/nginx.conf", + "title": "Custom DH parameters for perfect forward secrecy" }, { - "location": "/examples/customization/ssl-dh-param/README/#deploying-the-nginx-ingress-controller", + "location": "/examples/customization/ssl-dh-param/README/#custom-dh-parameters-for-perfect-forward-secrecy", "text": "This example aims to demonstrate the deployment of an nginx ingress controller and\nuse a ConfigMap to configure custom Diffie-Hellman parameters file to help with\n\"Perfect Forward Secrecy\".", - "title": "Deploying the Nginx Ingress controller" + "title": "Custom DH parameters for perfect forward secrecy" }, { "location": "/examples/customization/ssl-dh-param/README/#custom-configuration", @@ -1460,36 +1485,6 @@ "text": "To test the registry is working correctly we download a known image from docker hub , create a tag pointing to the new registry and upload the image: docker pull ubuntu:16.04 docker tag ubuntu:16.04 `registry./ubuntu:16.04` docker push `registry./ubuntu:16.04` Please replace registry. with your domain.", "title": "Testing" }, - { - "location": "/examples/external-auth/README/", - "text": "External Authentication\n\u00b6\n\n\nOverview\n\u00b6\n\n\nThe \nauth-url\n and \nauth-signin\n annotations allow you to use an external\nauthentication provider to protect your Ingress resources.\n\n\n\n\nImportant\n\n\nthis annotation requires \nnginx-ingress-controller v0.9.0\n or greater.)\n\n\n\n\nKey Detail\n\u00b6\n\n\nThis functionality is enabled by deploying multiple Ingress objects for a single host.\nOne Ingress object has no special annotations and handles authentication.\n\n\nOther Ingress objects can then be annotated in such a way that require the user to\nauthenticate against the first Ingress's endpoint, and can redirect \n401\ns to the\nsame endpoint.\n\n\nSample:\n\n\n...\n\n\nmetadata\n:\n\n \nname\n:\n \napplication\n\n \nannotations\n:\n\n \n\"nginx.ingress.kubernetes.io/auth-url\"\n:\n \n\"https://$host/oauth2/auth\"\n\n \n\"nginx.ingress.kubernetes.io/auth-signin\"\n:\n \n\"https://$host/oauth2/sign_in\"\n\n\n...\n\n\n\n\n\n\nExample: OAuth2 Proxy + Kubernetes-Dashboard\n\u00b6\n\n\nThis example will show you how to deploy \noauth2_proxy\n\ninto a Kubernetes cluster and use it to protect the Kubernetes Dashboard using github as oAuth2 provider\n\n\nPrepare\n\u00b6\n\n\n\n\nInstall the kubernetes dashboard\n\n\n\n\nkubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.5.0.yaml\n\n\n\n\n\n\n\n\nCreate a \ncustom Github OAuth application\n\n\n\n\n\n\n\n\nHomepage URL is the FQDN in the Ingress rule, like \nhttps://foo.bar.com\n\n\nAuthorization callback URL is the same as the base FQDN plus \n/oauth2\n, like \nhttps://foo.bar.com/oauth2\n\n\n\n\n\n\n\n\n\n\nConfigure oauth2_proxy values in the file oauth2-proxy.yaml with the values:\n\n\n\n\n\n\nOAUTH2_PROXY_CLIENT_ID with the github \n\n\n\n\n\nOAUTH2_PROXY_CLIENT_SECRET with the github \n\n\n\n\n\nOAUTH2_PROXY_COOKIE_SECRET with value of \npython\n \n-\nc\n \n'import os,base64; print base64.b64encode(os.urandom(16))'\n \n\n\n\n\n\n\nCustomize the contents of the file dashboard-ingress.yaml:\n\n\n\n\n\n\nReplace \n__INGRESS_HOST__\n with a valid FQDN and \n__INGRESS_SECRET__\n with a Secret with a valid SSL certificate.\n\n\n\n\nDeploy the oauth2 proxy and the ingress rules running:\n\n\n\n\n$\n kubectl create -f oauth2-proxy.yaml,dashboard-ingress.yaml\n\n\n\n\n\nTest the oauth integration accessing the configured URL, like \nhttps://foo.bar.com", - "title": "External Authentication" - }, - { - "location": "/examples/external-auth/README/#external-authentication", - "text": "", - "title": "External Authentication" - }, - { - "location": "/examples/external-auth/README/#overview", - "text": "The auth-url and auth-signin annotations allow you to use an external\nauthentication provider to protect your Ingress resources. Important this annotation requires nginx-ingress-controller v0.9.0 or greater.)", - "title": "Overview" - }, - { - "location": "/examples/external-auth/README/#key-detail", - "text": "This functionality is enabled by deploying multiple Ingress objects for a single host.\nOne Ingress object has no special annotations and handles authentication. Other Ingress objects can then be annotated in such a way that require the user to\nauthenticate against the first Ingress's endpoint, and can redirect 401 s to the\nsame endpoint. Sample: ... metadata : \n name : application \n annotations : \n \"nginx.ingress.kubernetes.io/auth-url\" : \"https://$host/oauth2/auth\" \n \"nginx.ingress.kubernetes.io/auth-signin\" : \"https://$host/oauth2/sign_in\" ...", - "title": "Key Detail" - }, - { - "location": "/examples/external-auth/README/#example-oauth2-proxy-kubernetes-dashboard", - "text": "This example will show you how to deploy oauth2_proxy \ninto a Kubernetes cluster and use it to protect the Kubernetes Dashboard using github as oAuth2 provider", - "title": "Example: OAuth2 Proxy + Kubernetes-Dashboard" - }, - { - "location": "/examples/external-auth/README/#prepare", - "text": "Install the kubernetes dashboard kubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.5.0.yaml Create a custom Github OAuth application Homepage URL is the FQDN in the Ingress rule, like https://foo.bar.com Authorization callback URL is the same as the base FQDN plus /oauth2 , like https://foo.bar.com/oauth2 Configure oauth2_proxy values in the file oauth2-proxy.yaml with the values: OAUTH2_PROXY_CLIENT_ID with the github OAUTH2_PROXY_CLIENT_SECRET with the github OAUTH2_PROXY_COOKIE_SECRET with value of python - c 'import os,base64; print base64.b64encode(os.urandom(16))' Customize the contents of the file dashboard-ingress.yaml: Replace __INGRESS_HOST__ with a valid FQDN and __INGRESS_SECRET__ with a Secret with a valid SSL certificate. Deploy the oauth2 proxy and the ingress rules running: $ kubectl create -f oauth2-proxy.yaml,dashboard-ingress.yaml Test the oauth integration accessing the configured URL, like https://foo.bar.com", - "title": "Prepare" - }, { "location": "/examples/multi-tls/README/", "text": "Multi TLS certificate termination\n\u00b6\n\n\nThis example uses 2 different certificates to terminate SSL for 2 hostnames.\n\n\n\n\nDeploy the controller by creating the rc in the parent dir\n\n\nCreate tls secrets for foo.bar.com and bar.baz.com as indicated in the yaml\n\n\nCreate multi-tls.yaml\n\n\n\n\nThis should generate a segment like:\n\n\n$\n kubectl \nexec\n -it nginx-ingress-controller-6vwd1 -- cat /etc/nginx/nginx.conf \n|\n grep \n\"foo.bar.com\"\n -B \n7\n -A \n35\n\n\n server {\n\n\n listen 80;\n\n\n listen 443 ssl http2;\n\n\n ssl_certificate /etc/nginx-ssl/default-foobar.pem;\n\n\n ssl_certificate_key /etc/nginx-ssl/default-foobar.pem;\n\n\n\n\n server_name foo.bar.com;\n\n\n\n\n if ($scheme = http) {\n\n\n return 301 https://$host$request_uri;\n\n\n }\n\n\n\n\n\n location / {\n\n\n proxy_set_header Host $host;\n\n\n\n #\n Pass Real IP\n\n proxy_set_header X-Real-IP $remote_addr;\n\n\n\n #\n Allow websocket connections\n\n proxy_set_header Upgrade $http_upgrade;\n\n\n proxy_set_header Connection $connection_upgrade;\n\n\n\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n\n\n proxy_set_header X-Forwarded-Host $host;\n\n\n proxy_set_header X-Forwarded-Proto $pass_access_scheme;\n\n\n\n proxy_connect_timeout 5s;\n\n\n proxy_send_timeout 60s;\n\n\n proxy_read_timeout 60s;\n\n\n\n proxy_redirect off;\n\n\n proxy_buffering off;\n\n\n\n proxy_http_version 1.1;\n\n\n\n proxy_pass http://default-http-svc-80;\n\n\n }\n\n\n\n\n\n\nAnd you should be able to reach your nginx service or http-svc service using a hostname switch:\n\n\n$\n kubectl get ing\n\nNAME RULE BACKEND ADDRESS AGE\n\n\nfoo-tls - 104.154.30.67 13m\n\n\n foo.bar.com\n\n\n / http-svc:80\n\n\n bar.baz.com\n\n\n / nginx:80\n\n\n\n$\n curl https://104.154.30.67 -H \n'Host:foo.bar.com'\n -k\n\nCLIENT VALUES:\n\n\nclient_address=10.245.0.6\n\n\ncommand=GET\n\n\nreal path=/\n\n\nquery=nil\n\n\nrequest_version=1.1\n\n\nrequest_uri=http://foo.bar.com:8080/\n\n\n\nSERVER VALUES:\n\n\nserver_version=nginx: 1.9.11 - lua: 10001\n\n\n\nHEADERS RECEIVED:\n\n\naccept=*/*\n\n\nconnection=close\n\n\nhost=foo.bar.com\n\n\nuser-agent=curl/7.35.0\n\n\nx-forwarded-for=10.245.0.1\n\n\nx-forwarded-host=foo.bar.com\n\n\nx-forwarded-proto=https\n\n\n\n$\n curl https://104.154.30.67 -H \n'Host:bar.baz.com'\n -k\n\n\n\n\n\n\n\n\n\n\nWelcome to nginx on Debian!\n\n\n\n$\n curl \n104\n.154.30.67\n\ndefault backend - 404", diff --git a/sitemap.xml b/sitemap.xml index 6c8e570b4..53e521c8b 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -4,7 +4,7 @@ / - 2018-05-02 + 2018-05-03 daily @@ -13,13 +13,19 @@ /deploy/ - 2018-05-02 + 2018-05-03 daily /deploy/rbac/ - 2018-05-02 + 2018-05-03 + daily + + + + /deploy/upgrade/ + 2018-05-03 daily @@ -35,49 +41,55 @@ /user-guide/cli-arguments/ - 2018-05-02 + 2018-05-03 daily /user-guide/custom-errors/ - 2018-05-02 + 2018-05-03 + daily + + + + /user-guide/default-backend/ + 2018-05-03 daily /user-guide/exposing-tcp-udp-services/ - 2018-05-02 + 2018-05-03 daily /user-guide/external-articles/ - 2018-05-02 + 2018-05-03 daily /user-guide/miscellaneous/ - 2018-05-02 + 2018-05-03 daily /user-guide/multiple-ingress/ - 2018-05-02 + 2018-05-03 daily /user-guide/nginx-status-page/ - 2018-05-02 + 2018-05-03 daily /user-guide/tls/ - 2018-05-02 + 2018-05-03 daily @@ -92,20 +104,20 @@ - /examples/PREREQUISITES/ - 2018-05-02 + /examples/ + 2018-05-03 daily - /examples/README/ - 2018-05-02 + /examples/PREREQUISITES/ + 2018-05-03 daily /examples/affinity/cookie/README/ - 2018-05-02 + 2018-05-03 daily @@ -123,37 +135,31 @@ /examples/docker-registry/README/ - 2018-05-02 - daily - - - - /examples/external-auth/README/ - 2018-05-02 + 2018-05-03 daily /examples/multi-tls/README/ - 2018-05-02 + 2018-05-03 daily /examples/rewrite/README/ - 2018-05-02 + 2018-05-03 daily /examples/static-ip/README/ - 2018-05-02 + 2018-05-03 daily /examples/tls-termination/README/ - 2018-05-02 + 2018-05-03 daily @@ -162,7 +168,7 @@ /development/ - 2018-05-02 + 2018-05-03 daily @@ -170,7 +176,7 @@ /ingress-controller-catalog/ - 2018-05-02 + 2018-05-03 daily @@ -178,7 +184,7 @@ /troubleshooting/ - 2018-05-02 + 2018-05-03 daily diff --git a/troubleshooting/index.html b/troubleshooting/index.html index 3231b8d9a..f1bf35036 100644 --- a/troubleshooting/index.html +++ b/troubleshooting/index.html @@ -244,7 +244,7 @@
  • - + Examples @@ -358,6 +358,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -495,6 +507,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -532,8 +556,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -556,8 +580,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -569,13 +593,13 @@
  • - + -
    • @@ -815,8 +851,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -839,8 +875,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -879,18 +915,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination diff --git a/user-guide/cli-arguments/index.html b/user-guide/cli-arguments/index.html index 83e111fb0..180b91a6c 100644 --- a/user-guide/cli-arguments/index.html +++ b/user-guide/cli-arguments/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -508,6 +520,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -545,8 +569,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -569,8 +593,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -582,13 +606,13 @@
  • - + -
    • @@ -828,8 +864,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -852,8 +888,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -892,18 +928,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination diff --git a/user-guide/custom-errors/index.html b/user-guide/custom-errors/index.html index 180197a1e..566617b9d 100644 --- a/user-guide/custom-errors/index.html +++ b/user-guide/custom-errors/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -508,6 +520,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -545,8 +569,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -569,8 +593,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -582,13 +606,13 @@
  • - + -
    • @@ -828,8 +864,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -852,8 +888,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -892,18 +928,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination @@ -1072,13 +1096,13 @@ Each request to the default backend includes two headers:

     -
    + Skip to content + + + +
    + +
    + +
    + + + + + + + + + + +
    +
    + + +
    +
    +
    + +
    +
    +
    + + +
    +
    +
    + + +
    +
    +
    + + +
    +
    + + + + + +

    Default backend

    +

    The default backend is a service which handles all URL paths and hosts the nginx controller doesn't understand +(i.e., all the requests that are not mapped with an Ingress).

    +

    Basically a default backend exposes two URLs:

    +
      +
    • /healthz that returns 200
      • +
    • / that returns 404
      • +
    +
    +

    Example

    +

    The sub-directory /images/404-server +provides a service which satisfies the requirements for a default backend.

    +
    +
    +

    Example

    +

    The sub-directory /images/custom-error-pages +provides an additional service for the purpose of customizing the error pages served via the default backend.

    +
    + + + + + + + + + +
    +
    +
    +
    + + + + +
    + + + + + + + + + + + + + \ No newline at end of file diff --git a/user-guide/exposing-tcp-udp-services/index.html b/user-guide/exposing-tcp-udp-services/index.html index da3307e3d..ed7c40d07 100644 --- a/user-guide/exposing-tcp-udp-services/index.html +++ b/user-guide/exposing-tcp-udp-services/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -498,6 +510,18 @@ + +
  • + + Default backend + +
    • + + + + + + @@ -545,8 +569,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -569,8 +593,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -582,13 +606,13 @@
  • - + -
    • @@ -828,8 +864,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -852,8 +888,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -892,18 +928,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination @@ -1062,7 +1086,7 @@ The next example shows how to expose the service kube-d
    diff --git a/user-guide/external-articles/index.html b/user-guide/external-articles/index.html index 318ba758c..adea47810 100644 --- a/user-guide/external-articles/index.html +++ b/user-guide/external-articles/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -499,6 +511,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -545,8 +569,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -569,8 +593,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -582,13 +606,13 @@
  • - + -
    • @@ -828,8 +864,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -852,8 +888,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -892,18 +928,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination diff --git a/user-guide/miscellaneous/index.html b/user-guide/miscellaneous/index.html index a6eab9a14..a47936ae0 100644 --- a/user-guide/miscellaneous/index.html +++ b/user-guide/miscellaneous/index.html @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -499,6 +511,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -550,20 +574,6 @@
      -
    • - - Conventions - - -
      • - -
    • - - Requirements - - -
      • -
    • Source IP address @@ -630,8 +640,8 @@
    • - - Multiple ingress controllers + + Multiple Ingress controllers
      • @@ -654,8 +664,8 @@
    • - - TLS + + TLS/HTTPS
      • @@ -667,13 +677,13 @@
    • - + -
      • @@ -913,8 +935,8 @@
    • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
      • @@ -937,8 +959,8 @@
    • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
      • @@ -977,18 +999,6 @@ -
    • - - External Authentication - -
      • - - - - - - -
    • Multi TLS certificate termination @@ -1093,20 +1103,6 @@
      • @@ -499,6 +511,18 @@ +
    • + + Default backend + +
      • + + + + + + +
    • Exposing TCP and UDP services @@ -545,11 +569,11 @@ - - Multiple ingress controllers + + Multiple Ingress controllers @@ -563,22 +587,8 @@
      • - - Running multiple ingress controllers - - -
        • - -
      • - - Annotation ingress.class - - -
        • - -
      • - - Disabling NGINX ingress controller + + Multiple ingress-nginx controllers
        • @@ -612,8 +622,8 @@
      • - - TLS + + TLS/HTTPS
        • @@ -625,13 +635,13 @@
      • - + -
        • @@ -871,8 +893,8 @@
      • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
        • @@ -895,8 +917,8 @@
      • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
        • @@ -935,18 +957,6 @@ -
      • - - External Authentication - -
        • - - - - - - -
      • Multi TLS certificate termination @@ -1052,22 +1062,8 @@
        • - - Running multiple ingress controllers - - -
          • - -
        • - - Annotation ingress.class - - -
          • - -
        • - - Disabling NGINX ingress controller + + Multiple ingress-nginx controllers
          • @@ -1091,27 +1087,10 @@ -

          Multiple ingress controllers

          -

          Running multiple ingress controllers

          -

          If you're running multiple ingress controllers, or running on a cloud provider that natively handles ingress, you need to specify the annotation kubernetes.io/ingress.class: "nginx" in all ingresses that you would like this controller to claim.

          -

          This mechanism also provides users the ability to run multiple NGINX ingress controllers (e.g. one which serves public traffic, one which serves "internal" traffic). When utilizing this functionality the option --ingress-class should be changed to a value unique for the cluster within the definition of the replication controller. Here is a partial example:

          -
          spec:
-  template:
-     spec:
-       containers:
-         - name: nginx-ingress-internal-controller
-           args:
-             - /nginx-ingress-controller
-             - '--default-backend-service=ingress/nginx-ingress-default-backend'
-             - '--election-id=ingress-controller-leader-internal'
-             - '--ingress-class=nginx-internal'
-             - '--configmap=ingress/nginx-ingress-internal-controller'
-
          - - -

          Annotation ingress.class

          -

          If you have multiple Ingress controllers in a single cluster, you can pick one by specifying the ingress.class -annotation, eg creating an Ingress with an annotation like

          +

          Multiple Ingress controllers

          +

          If you're running multiple ingress controllers, or running on a cloud provider that natively handles ingress such as GKE, +you need to specify the annotation kubernetes.io/ingress.class: "nginx" in all ingresses that you would like the ingress-nginx controller to claim.

          +

          For instance,

          metadata:
   name: foo
   annotations:
@@ -1128,10 +1107,31 @@ annotation, eg creating an Ingress with an annotation like
          
 
 
 
          will target the nginx controller, forcing the GCE controller to ignore it.
          
-
          Note: Deploying multiple ingress controller and not specifying the annotation will result in both controllers fighting to satisfy the Ingress.
          
-
          Disabling NGINX ingress controller
          
-
          Setting the annotation kubernetes.io/ingress.class to any other value  which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress.  If you are only running a single NGINX ingress controller, this can be achieved by setting this to any value except "nginx" or an empty string.
          
+
          To reiterate, setting the annotation to any value which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress.
+If you are only running a single NGINX ingress controller, this can be achieved by setting the annotation to any value except "nginx" or an empty string.
          
 
          Do this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller.
          
+
          
+
          Important
          
+
          Deploying multiple Ingress controllers and not specifying a class annotation will
+result in both or all controllers fighting to satisfy the Ingress, and all of them
+updating the Ingress status field in confusing ways.
          
+
          
+
          Multiple ingress-nginx controllers
          
+
          This mechanism also provides users the ability to run multiple NGINX ingress controllers (e.g. one which serves public traffic, one which serves "internal" traffic).
+To do this, the option --ingress-class must be changed to a value unique for the cluster within the definition of the replication controller.
+Here is a partial example:
          
+
          spec:
+  template:
+     spec:
+       containers:
+         - name: nginx-ingress-internal-controller
+           args:
+             - /nginx-ingress-controller
+             - '--default-backend-service=ingress/nginx-ingress-default-backend'
+             - '--election-id=ingress-controller-leader-internal'
+             - '--ingress-class=nginx-internal'
+             - '--configmap=ingress/nginx-ingress-internal-controller'
+
          
                 
                   
                 
diff --git a/user-guide/nginx-configuration/annotations/index.html b/user-guide/nginx-configuration/annotations/index.html
index 3672d1210..05fe73dc5 100644
--- a/user-guide/nginx-configuration/annotations/index.html
+++ b/user-guide/nginx-configuration/annotations/index.html
@@ -246,7 +246,7 @@
   
     
        • 
       
-        
+        
           Examples
         
       
@@ -360,6 +360,18 @@
   
          • 
 
         
+          
+          
+          
+
+
+  
        • 
+    
+      Upgrading
+    
+  
          • 
+
+
        • @@ -463,6 +475,19 @@ Session Affinity + +
      • @@ -612,8 +637,8 @@
      • - - Redirect from to www + + Redirect from/to www.
        • @@ -623,13 +648,6 @@ Whitelist source range - - -
      • - - Cookie affinity - -
      • @@ -783,6 +801,18 @@ +
      • + + Default backend + +
        • + + + + + + +
      • Exposing TCP and UDP services @@ -820,8 +850,8 @@
      • - - Multiple ingress controllers + + Multiple Ingress controllers
        • @@ -844,8 +874,8 @@
      • - - TLS + + TLS/HTTPS
        • @@ -857,13 +887,13 @@
      • - + -
        • @@ -1103,8 +1145,8 @@
      • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
        • @@ -1127,8 +1169,8 @@
      • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
        • @@ -1167,18 +1209,6 @@ -
      • - - External Authentication - -
        • - - - - - - -
      • Multi TLS certificate termination @@ -1295,6 +1325,19 @@ Session Affinity + +
      • @@ -1444,8 +1487,8 @@
      • - - Redirect from to www + + Redirect from/to www.
        • @@ -1455,13 +1498,6 @@ Whitelist source range - - -
      • - - Cookie affinity - -
      • @@ -1561,6 +1597,13 @@ Other types, such as boolean or numeric values must be quoted, i.e. "true", "false", "100".

        +
        +

        Note

        +

        The annotation prefix can be changed using the +--annotations-prefix command line argument, +but the default is nginx.ingress.kubernetes.io, as described in the +table below.

        +
        @@ -1825,11 +1868,28 @@ Set the annotation nginx.ingress.kubernetes.io/rewrite-

        If the application contains relative links it is possible to add an additional annotation nginx.ingress.kubernetes.io/add-base-url that will prepend a base tag in the header of the returned HTML from the backend.

        If the scheme of base tag need to be specific, set the annotation nginx.ingress.kubernetes.io/base-url-scheme to the scheme such as http and https.

        If the Application Root is exposed in a different path and needs to be redirected, set the annotation nginx.ingress.kubernetes.io/app-root to redirect requests for /.

        +
        +

        Example

        Please check the rewrite example.

        +

        Session Affinity

        The annotation nginx.ingress.kubernetes.io/affinity enables and sets the affinity type in all Upstreams of an Ingress. This way, a request will always be directed to the same upstream server. The only affinity type available for NGINX is cookie.

        +
        +

        Example

        Please check the affinity example.

        +
        + +

        If you use the cookie affinity type you can also specify the name of the cookie that will be used to route the requests with the annotation nginx.ingress.kubernetes.io/session-cookie-name. The default is to create a cookie named 'INGRESSCOOKIE'.

        +

        In case of NGINX the annotation nginx.ingress.kubernetes.io/session-cookie-hash defines which algorithm will be used to hash the used upstream. Default value is md5 and possible values are md5, sha1 and index.

        +
        +

        Attention

        +

        The index option is not an actual hash; an in-memory index is used instead, which has less overhead. +However, with index, matching against a changing upstream server list is inconsistent. +So, at reload, if upstream servers have changed, index values are not guaranteed to correspond to the same server as before! +Use index with caution and only if you need to!

        +
        +

        In NGINX this feature is implemented by the third party module nginx-sticky-module-ng. The workflow used to define which upstream server will be used is explained here

        Authentication

        Is possible to add authentication adding additional annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords inside the key auth.

        The annotations are:

        @@ -1848,7 +1908,10 @@ This annotation also accepts the alternative form "namespace/secretName", in whi +
        +

        Example

        Please check the auth example.

        +

        Custom NGINX upstream checks

        NGINX exposes some flags in the upstream configuration that enable the configuration of each server in the upstream. The Ingress controller allows custom max_fails and fail_timeout parameters in a global context using upstream-max-fails and upstream-fail-timeout in the NGINX ConfigMap or in a particular Ingress rule. upstream-max-fails defaults to 0. This means NGINX will respect the container's readinessProbe if it is defined. If there is no probe and no values for upstream-max-fails NGINX will continue to send traffic to the container.

        @@ -1859,11 +1922,15 @@ This annotation also accepts the alternative form "namespace/secretName", in whi

        nginx.ingress.kubernetes.io/upstream-max-fails: number of unsuccessful attempts to communicate with the server that should occur in the duration set by the upstream-fail-timeout parameter to consider the server unavailable.

        nginx.ingress.kubernetes.io/upstream-fail-timeout: time in seconds during which the specified number of unsuccessful attempts to communicate with the server should occur to consider the server unavailable. This is also the period of time the server will be considered unavailable.

        In NGINX, backend server pools are called "upstreams". Each upstream contains the endpoints for a service. An upstream is created for each service that has Ingress rules defined.

        -
        -

        Important

        -

        All Ingress rules using the same service will use the same upstream. Only one of the Ingress rules should define annotations to configure the upstream servers.

        +
        +

        Attention

        +

        All Ingress rules using the same service will use the same upstream.
        +Only one of the Ingress rules should define annotations to configure the upstream servers.

        +
        +

        Example

        Please check the custom upstream check example.

        +

        Custom NGINX upstream hashing

        NGINX supports load balancing by client-server mapping based on consistent hashing for a given key. The key can contain text, variables or any combination thereof. This feature allows for request stickiness other than client IP or cookies. The ketama consistent hashing method will be used which ensures only a few keys would be remapped to different servers on upstream group changes.

        To enable consistent hashing for a backend:

        @@ -1878,37 +1945,26 @@ This annotation also accepts the alternative form "namespace/secretName", in whi

        Client Certificate Authentication

        It is possible to enable Client Certificate Authentication using additional annotations in Ingress Rule.

        The annotations are:

        -
        nginx.ingress.kubernetes.io/auth-tls-secret: secretName
-
        - - -

        The name of the Secret that contains the full Certificate Authority chain ca.crt that is enabled to authenticate against this Ingress. -This annotation also accepts the alternative form "namespace/secretName", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace.

        -
        nginx.ingress.kubernetes.io/auth-tls-verify-depth
-
        - - -

        The validation depth between the provided client certificate and the Certification Authority chain.

        -
        nginx.ingress.kubernetes.io/auth-tls-verify-client
-
        - - -

        Enables verification of client certificates.

        -
        nginx.ingress.kubernetes.io/auth-tls-error-page
-
        - - -

        The URL/Page that user should be redirected in case of a Certificate Authentication Error

        -
        nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream
-
        - - -

        Indicates if the received certificates should be passed or not to the upstream server. -By default this is disabled.

        +
          +
        • nginx.ingress.kubernetes.io/auth-tls-secret: secretName: + The name of the Secret that contains the full Certificate Authority chain ca.crt that is enabled to authenticate against this Ingress. + This annotation also accepts the alternative form "namespace/secretName", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace.
          • +
        • nginx.ingress.kubernetes.io/auth-tls-verify-depth: + The validation depth between the provided client certificate and the Certification Authority chain.
          • +
        • nginx.ingress.kubernetes.io/auth-tls-verify-client: + Enables verification of client certificates.
          • +
        • nginx.ingress.kubernetes.io/auth-tls-error-page: + The URL/Page that user should be redirected in case of a Certificate Authentication Error
          • +
        • nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: + Indicates if the received certificates should be passed or not to the upstream server. By default this is disabled.
          • +
        +
        +

        Example

        Please check the client-certs example.

        -
        -

        Important

        -

        TLS with Client Authentication is NOT possible in Cloudflare as is not allowed it and might result in unexpected behavior.

        +
        +
        +

        Attention

        +

        TLS with Client Authentication is not possible in Cloudflare and might result in unexpected behavior.

        Cloudflare only allows Authenticated Origin Pulls and is required to use their own certificate: https://blog.cloudflare.com/protecting-the-origin-with-tls-authenticated-origin-pulls/

        Only Authenticated Origin Pulls are allowed and can be configured by following their tutorial: https://support.cloudflare.com/hc/en-us/articles/204494148-Setting-up-NGINX-to-use-TLS-Authenticated-Origin-Pulls

        @@ -1920,40 +1976,58 @@ By default this is disabled.

        Default Backend

        -

        The ingress controller requires a default backend. This service handles the response when the service in the Ingress rule does not have endpoints. +

        The ingress controller requires a default backend. +This service handles the response when the service in the Ingress rule does not have endpoints. This is a global configuration for the ingress controller. In some cases could be required to return a custom content or format. In this scenario we can use the annotation nginx.ingress.kubernetes.io/default-backend: <svc name> to specify a custom default backend.

        Enable CORS

        -

        To enable Cross-Origin Resource Sharing (CORS) in an Ingress rule add the annotation nginx.ingress.kubernetes.io/enable-cors: "true". This will add a section in the server location enabling this functionality.

        +

        To enable Cross-Origin Resource Sharing (CORS) in an Ingress rule, +add the annotation nginx.ingress.kubernetes.io/enable-cors: "true". +This will add a section in the server location enabling this functionality.

        CORS can be controlled with the following annotations:

          -
        • nginx.ingress.kubernetes.io/cors-allow-methods controls which methods are accepted. This is a multi-valued field, separated by ',' and accepts only letters (upper and lower case).
          • +
        • +

          nginx.ingress.kubernetes.io/cors-allow-methods + controls which methods are accepted. + This is a multi-valued field, separated by ',' and accepts only letters (upper and lower case). + Example: nginx.ingress.kubernetes.io/cors-allow-methods: "PUT, GET, POST, OPTIONS"

          +
          • +
        • +

          nginx.ingress.kubernetes.io/cors-allow-headers + controls which headers are accepted. + This is a multi-valued field, separated by ',' and accepts letters, numbers, _ and -. + Example: nginx.ingress.kubernetes.io/cors-allow-headers: "X-Forwarded-For, X-app123-XPTO"

          +
          • +
        • +

          nginx.ingress.kubernetes.io/cors-allow-origin + controls what's the accepted Origin for CORS and defaults to '*'. + This is a single field value, with the following format: http(s)://origin-site.com or http(s)://origin-site.com:port + Example: nginx.ingress.kubernetes.io/cors-allow-origin: "https://origin-site.com:4443"

          +
          • +
        • +

          nginx.ingress.kubernetes.io/cors-allow-credentials + controls if credentials can be passed during CORS operations. + Example: nginx.ingress.kubernetes.io/cors-allow-credentials: "true"

          +
          • +
        • +

          nginx.ingress.kubernetes.io/cors-max-age + controls how long preflight requests can be cached. + Example: nginx.ingress.kubernetes.io/cors-max-age: 600

          +
        -

        Example: nginx.ingress.kubernetes.io/cors-allow-methods: "PUT, GET, POST, OPTIONS"

        -
          -
        • nginx.ingress.kubernetes.io/cors-allow-headers controls which headers are accepted. This is a multi-valued field, separated by ',' and accepts letters, numbers, _ and -.
          • -
        -

        Example: nginx.ingress.kubernetes.io/cors-allow-headers: "X-Forwarded-For, X-app123-XPTO"

        -
          -
        • nginx.ingress.kubernetes.io/cors-allow-origin controls what's the accepted Origin for CORS and defaults to '*'. This is a single field value, with the following format: http(s)://origin-site.com or http(s)://origin-site.com:port
          • -
        -

        Example: nginx.ingress.kubernetes.io/cors-allow-origin: "https://origin-site.com:4443"

        -
          -
        • nginx.ingress.kubernetes.io/cors-allow-credentials controls if credentials can be passed during CORS operations.
          • -
        -

        Example: nginx.ingress.kubernetes.io/cors-allow-credentials: "true"

        -
          -
        • nginx.ingress.kubernetes.io/cors-max-age controls how long preflight requests can be cached.
          • -
        -

        Example: nginx.ingress.kubernetes.io/cors-max-age: 600

        -

        For more information please see https://enable-cors.org

        -

        Server Alias

        -

        To add Server Aliases to an Ingress rule add the annotation nginx.ingress.kubernetes.io/server-alias: "<alias>". -This will create a server with the same configuration, but a different server_name as the provided host.

        Note

        -

        A server-alias name cannot conflict with the hostname of an existing server. If it does the server-alias annotation will be ignored. If a server-alias is created and later a new server with the same hostname is created the new server configuration will take place over the alias configuration.

        +

        For more information please see https://enable-cors.org

        -

        For more information please see http://nginx.org

        +

        Server Alias

        +

        To add Server Aliases to an Ingress rule add the annotation nginx.ingress.kubernetes.io/server-alias: "<alias>". +This will create a server with the same configuration, but a different server_name as the provided host.

        +
        +

        Note

        +

        A server-alias name cannot conflict with the hostname of an existing server. If it does the server-alias annotation will be ignored. +If a server-alias is created and later a new server with the same hostname is created, +the new server configuration will take place over the alias configuration.

        +
        +

        For more information please see the server_name documentation.

        Server snippet

        Using the annotation nginx.ingress.kubernetes.io/server-snippet it is possible to add custom configuration in the server configuration block.

        apiVersion: extensions/v1beta1
@@ -1973,17 +2047,21 @@ This will create a server with the same configuration, but a different server_na
        -
        -

        Important

        -

        This annotation can be used only once per host

        +
        +

        Attention

        +

        This annotation can be used only once per host.

        Client Body Buffer Size

        Sets buffer size for reading client request body per location. In case the request body is larger than the buffer, the whole body or only its part is written to a temporary file. By default, buffer size is equal to two memory pages. This is 8K on x86, other 32-bit platforms, and x86-64. It is usually 16K on other 64-bit platforms. This annotation is applied to each location provided in the ingress rule.

        -

        Note: The annotation value must be given in a valid format otherwise the -For example to set the client-body-buffer-size the following can be done:

        +
        +

        Note

        +

        The annotation value must be given in a format understood by Nginx.

        +
        +
        +

        Example

        • nginx.ingress.kubernetes.io/client-body-buffer-size: "1000" # 1000 bytes
        • nginx.ingress.kubernetes.io/client-body-buffer-size: 1k # 1 kilobyte
          • @@ -1991,6 +2069,7 @@ For example to set the client-body-buffer-size the following can be done:

        • nginx.ingress.kubernetes.io/client-body-buffer-size: 1m # 1 megabyte
        • nginx.ingress.kubernetes.io/client-body-buffer-size: 1M # 1 megabyte
        +

        For more information please see http://nginx.org

        External Authentication

        To use an existing service that provides authentication the Ingress rule can be annotated with nginx.ingress.kubernetes.io/auth-url to indicate the URL where the HTTP request should be sent.

        @@ -1999,45 +2078,63 @@ For example to set the client-body-buffer-size the following can be done:

        Additionally it is possible to set:

        -

        nginx.ingress.kubernetes.io/auth-method: <Method> to specify the HTTP method to use.

        -

        nginx.ingress.kubernetes.io/auth-signin: <SignIn_URL> to specify the location of the error page.

        -

        nginx.ingress.kubernetes.io/auth-response-headers: <Response_Header_1, ..., Response_Header_n> to specify headers to pass to backend once authorization request completes.

        -

        nginx.ingress.kubernetes.io/auth-request-redirect: <Request_Redirect_URL> to specify the X-Auth-Request-Redirect header value.

        +
          +
        • nginx.ingress.kubernetes.io/auth-method: + <Method> to specify the HTTP method to use.
          • +
        • nginx.ingress.kubernetes.io/auth-signin: + <SignIn_URL> to specify the location of the error page.
          • +
        • nginx.ingress.kubernetes.io/auth-response-headers: + <Response_Header_1, ..., Response_Header_n> to specify headers to pass to backend once authorization request completes.
          • +
        • nginx.ingress.kubernetes.io/auth-request-redirect: + <Request_Redirect_URL> to specify the X-Auth-Request-Redirect header value.
          • +
        +
        +

        Example

        Please check the external-auth example.

        +

        Rate limiting

        -

        The annotations nginx.ingress.kubernetes.io/limit-connections, nginx.ingress.kubernetes.io/limit-rps, and nginx.ingress.kubernetes.io/limit-rpm define a limit on the connections that can be opened by a single client IP address. This can be used to mitigate DDoS Attacks.

        -

        nginx.ingress.kubernetes.io/limit-connections: number of concurrent connections allowed from a single IP address.

        -

        nginx.ingress.kubernetes.io/limit-rps: number of connections that may be accepted from a given IP each second.

        -

        nginx.ingress.kubernetes.io/limit-rpm: number of connections that may be accepted from a given IP each minute.

        +

        These annotations define a limit on the connections that can be opened by a single client IP address. +This can be used to mitigate DDoS Attacks.

        +
          +
        • nginx.ingress.kubernetes.io/limit-connections: number of concurrent connections allowed from a single IP address.
          • +
        • nginx.ingress.kubernetes.io/limit-rps: number of connections that may be accepted from a given IP each second.
          • +
        • nginx.ingress.kubernetes.io/limit-rpm: number of connections that may be accepted from a given IP each minute.
          • +
        • nginx.ingress.kubernetes.io/limit-rate-after: sets the initial amount after which the further transmission of a response to a client will be rate limited.
          • +
        • nginx.ingress.kubernetes.io/limit-rate: rate of request that accepted from a client each second.
          • +

        You can specify the client IP source ranges to be excluded from rate-limiting through the nginx.ingress.kubernetes.io/limit-whitelist annotation. The value is a comma separated list of CIDRs.

        If you specify multiple annotations in a single Ingress rule, limit-rpm, and then limit-rps takes precedence.

        The annotation nginx.ingress.kubernetes.io/limit-rate, nginx.ingress.kubernetes.io/limit-rate-after define a limit the rate of response transmission to a client. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit.

        -

        nginx.ingress.kubernetes.io/limit-rate-after: sets the initial amount after which the further transmission of a response to a client will be rate limited.

        -

        nginx.ingress.kubernetes.io/limit-rate: rate of request that accepted from a client each second.

        -

        To configure this setting globally for all Ingress rules, the limit-rate-after and limit-rate value may be set in the NGINX ConfigMap. if you set the value in ingress annotation will cover global setting.

        +

        To configure this setting globally for all Ingress rules, the limit-rate-after and limit-rate value may be set in the NGINX ConfigMap. if you set the value in ingress annotation will cover global setting.

        Permanent Redirect

        This annotation allows to return a permanent redirect instead of sending data to the upstream. For example nginx.ingress.kubernetes.io/permanent-redirect: https://www.google.com would redirect everything to Google.

        SSL Passthrough

        The annotation nginx.ingress.kubernetes.io/ssl-passthrough allows to configure TLS termination in the pod and not in NGINX.

        -
        -

        Important

        -
          -
        • -

          Using the annotation nginx.ingress.kubernetes.io/ssl-passthrough invalidates all the other available annotations. This is because SSL Passthrough works in L4 (TCP).

          -
          • -
        • -

          The use of this annotation requires Proxy Protocol to be enabled in the load-balancer. For example enabling Proxy Protocol for AWS ELB is described here. If you're using ingress-controller without load balancer then the flag --enable-ssl-passthrough is required (by default it is disabled).

          -
          • -
        +
        +

        Attention

        +

        Using the annotation nginx.ingress.kubernetes.io/ssl-passthrough invalidates all the other available annotations. +This is because SSL Passthrough works on level 4 of the OSI stack (TCP), not on the HTTP/HTTPS level.

        +
        +
        +

        Attention

        +

        The use of this annotation requires the Proxy Protocol to be enabled in the front-end load-balancer. +For example enabling Proxy Protocol for AWS ELB is described here. +If you're using ingress-controller without load balancer then the flag +--enable-ssl-passthrough is required (by default it is disabled).

        Secure backends

        -

        By default NGINX uses http to reach the services. Adding the annotation nginx.ingress.kubernetes.io/secure-backends: "true" in the Ingress rule changes the protocol to https. +

        By default NGINX uses plain HTTP to reach the services. +Adding the annotation nginx.ingress.kubernetes.io/secure-backends: "true" in the Ingress rule changes the protocol to HTTPS. If you want to validate the upstream against a specific certificate, you can create a secret with it and reference the secret with the annotation nginx.ingress.kubernetes.io/secure-verify-ca-secret.

        -
        -

        Note that if an invalid or non-existent secret is given, the NGINX ingress controller will ignore the secure-backends annotation.

        -
        +
        +

        Attention

        +

        Note that if an invalid or non-existent secret is given, +the ingress controller will ignore the secure-backends annotation.

        +

        Service Upstream

        -

        By default the NGINX ingress controller uses a list of all endpoints (Pod IP/port) in the NGINX upstream configuration. This annotation disables that behavior and instead uses a single upstream in NGINX, the service's Cluster IP and port. This can be desirable for things like zero-downtime deployments as it reduces the need to reload NGINX configuration when Pods come up and down. See issue #257.

        +

        By default the NGINX ingress controller uses a list of all endpoints (Pod IP/port) in the NGINX upstream configuration.

        +

        The nginx.ingress.kubernetes.io/service-upstream annotation disables that behavior and instead uses a single upstream in NGINX, the service's Cluster IP and port.

        +

        This can be desirable for things like zero-downtime deployments as it reduces the need to reload NGINX configuration when Pods come up and down. See issue #257.

        Known Issues

        If the service-upstream annotation is specified the following things should be taken into consideration:

          @@ -2045,25 +2142,28 @@ If you want to validate the upstream against a specific certificate, you can cre
        • The proxy_next_upstream directive will not have any effect meaning on error the request will not be dispatched to another upstream.

        Server-side HTTPS enforcement through redirect

        -

        By default the controller redirects (301) to HTTPS if TLS is enabled for that ingress. If you want to disable that behavior globally, you can use ssl-redirect: "false" in the NGINX config map.

        -

        To configure this feature for specific ingress resources, you can use the nginx.ingress.kubernetes.io/ssl-redirect: "false" annotation in the particular resource.

        -

        When using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to HTTPS even when there is not TLS cert available. This can be achieved by using the nginx.ingress.kubernetes.io/force-ssl-redirect: "true" annotation in the particular resource.

        -

        Redirect from to www

        -

        In some scenarios is required to redirect from www.domain.com to domain.com or viceversa. +

        By default the controller redirects (308) to HTTPS if TLS is enabled for that ingress. +If you want to disable this behavior globally, you can use ssl-redirect: "false" in the NGINX config map.

        +

        To configure this feature for specific ingress resources, you can use the nginx.ingress.kubernetes.io/ssl-redirect: "false" +annotation in the particular resource.

        +

        When using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to HTTPS +even when there is no TLS certificate available. +This can be achieved by using the nginx.ingress.kubernetes.io/force-ssl-redirect: "true" annotation in the particular resource.

        +

        Redirect from/to www.

        +

        In some scenarios is required to redirect from www.domain.com to domain.com or vice versa. To enable this feature use the annotation nginx.ingress.kubernetes.io/from-to-www-redirect: "true"

        -
        -

        Important

        +
        +

        Attention

        If at some point a new Ingress is created with a host equal to one of the options (like domain.com) the annotation will be omitted.

        Whitelist source range

        -

        You can specify the allowed client IP source ranges through the nginx.ingress.kubernetes.io/whitelist-source-range annotation. The value is a comma separated list of CIDRs, e.g. 10.0.0.0/24,172.10.0.1.

        -

        To configure this setting globally for all Ingress rules, the whitelist-source-range value may be set in the NGINX ConfigMap.

        -

        Note: Adding an annotation to an Ingress rule overrides any global restriction.

        - -

        If you use the cookie type you can also specify the name of the cookie that will be used to route the requests with the annotation nginx.ingress.kubernetes.io/session-cookie-name. The default is to create a cookie named 'INGRESSCOOKIE'.

        -

        In case of NGINX the annotation nginx.ingress.kubernetes.io/session-cookie-hash defines which algorithm will be used to 'hash' the used upstream. Default value is md5 and possible values are md5, sha1 and index. -The index option is not hashed, an in-memory index is used instead, it's quicker and the overhead is shorter Warning: the matching against upstream servers list is inconsistent. So, at reload, if upstreams servers has changed, index values are not guaranteed to correspond to the same server as before! USE IT WITH CAUTION and only if you need to!

        -

        In NGINX this feature is implemented by the third party module nginx-sticky-module-ng. The workflow used to define which upstream server will be used is explained here

        +

        You can specify allowed client IP source ranges through the nginx.ingress.kubernetes.io/whitelist-source-range annotation. +The value is a comma separated list of CIDRs, e.g. 10.0.0.0/24,172.10.0.1.

        +

        To configure this setting globally for all Ingress rules, the whitelist-source-range value may be set in the NGINX ConfigMap.

        +
        +

        Note

        +

        Adding an annotation to an Ingress rule overrides any global restriction.

        +

        Custom timeouts

        Using the configuration configmap it is possible to set the default global timeout for connections to the upstream servers. In some scenarios is required to have different values. To allow this we provide annotations that allows this customization:

        @@ -2076,13 +2176,12 @@ In some scenarios is required to have different values. To allow this we provide
      • nginx.ingress.kubernetes.io/proxy-request-buffering

        • Proxy redirect

        -

        With the annotations nginx.ingress.kubernetes.io/proxy-redirect-from and nginx.ingress.kubernetes.io/proxy-redirect-to it is possible to set the text that should be changed in the Location and Refresh header fields of a proxied server response (http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect) -Setting "off" or "default" in the annotation nginx.ingress.kubernetes.io/proxy-redirect-from disables nginx.ingress.kubernetes.io/proxy-redirect-to -Both annotations will be used in any other case -By default the value is "off".

        +

        With the annotations nginx.ingress.kubernetes.io/proxy-redirect-from and nginx.ingress.kubernetes.io/proxy-redirect-to it is possible to set the text that should be changed in the Location and Refresh header fields of a proxied server response (http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect)

        +

        Setting "off" or "default" in the annotation nginx.ingress.kubernetes.io/proxy-redirect-from disables nginx.ingress.kubernetes.io/proxy-redirect-to.

        +

        Both annotations will be used in any other case. By default the value is "off".

        Custom max body size

        -

        For NGINX, 413 error will be returned to the client when the size in a request exceeds the maximum allowed size of the client request body. This size can be configured by the parameter client_max_body_size.

        -

        To configure this setting globally for all Ingress rules, the proxy-body-size value may be set in the NGINX ConfigMap. +

        For NGINX, an 413 error will be returned to the client when the size in a request exceeds the maximum allowed size of the client request body. This size can be configured by the parameter client_max_body_size.

        +

        To configure this setting globally for all Ingress rules, the proxy-body-size value may be set in the NGINX ConfigMap. To use custom values in an Ingress rule define these annotation:

        nginx.ingress.kubernetes.io/proxy-body-size: 8m
        @@ -2090,8 +2189,8 @@ To use custom values in an Ingress rule define these annotation:

        Proxy buffering

        Enable or disable proxy buffering proxy_buffering. -By default proxy buffering is disabled in the nginx config.

        -

        To configure this setting globally for all Ingress rules, the proxy-buffering value may be set in the NGINX ConfigMap. +By default proxy buffering is disabled in the NGINX config.

        +

        To configure this setting globally for all Ingress rules, the proxy-buffering value may be set in the NGINX ConfigMap. To use custom values in an Ingress rule define these annotation:

        nginx.ingress.kubernetes.io/proxy-buffering: "on"
        @@ -2105,42 +2204,45 @@ To use custom values in an Ingress rule define these annotation:

        Connection proxy header

        -

        Using this annotation will override the default connection header set by nginx. To use custom values in an Ingress rule, define the annotation:

        +

        Using this annotation will override the default connection header set by NGINX. +To use custom values in an Ingress rule, define the annotation:

        nginx.ingress.kubernetes.io/connection-proxy-header: "keep-alive"

        Enable Access Log

        -

        In some scenarios could be required to disable NGINX access logs. To enable this feature use the annotation:

        +

        Access logs are enabled by default, but in some scenarios access logs might be required to be disabled for a given +ingress. To do this, use the annotation:

        nginx.ingress.kubernetes.io/enable-access-log: "false"

        Enable Rewrite Log

        -

        In some scenarios it could be required to enable NGINX rewrite logs. Note that rewrite logs are sent to the error_log file at the notice level. To enable this feature use the annotation:

        +

        Rewrite logs are not enabled by default. In some scenarios it could be required to enable NGINX rewrite logs. +Note that rewrite logs are sent to the error_log file at the notice level. To enable this feature use the annotation:

        nginx.ingress.kubernetes.io/enable-rewrite-log: "true"

        Lua Resty WAF

        -

        Using lua-resty-waf-* annotations we can enable and control lua-resty-waf per location. -Following configuration will enable WAF for the paths defined in the corresponding ingress:

        +

        Using lua-resty-waf-* annotations we can enable and control the lua-resty-waf +Web Application Firewall per location.

        +

        Following configuration will enable the WAF for the paths defined in the corresponding ingress:

        nginx.ingress.kubernetes.io/lua-resty-waf: "active"

        In order to run it in debugging mode you can set nginx.ingress.kubernetes.io/lua-resty-waf-debug to "true" in addition to the above configuration. -The other possible values for nginx.ingress.kubernetes.io/lua-resty-waf are inactive and simulate. In inactive mode WAF won't do anything, whereas -in simulate mode it will log a warning message if there's a matching WAF rule for given request. This is useful to debug a rule and eliminate possible false positives before fully deploying it.

        +The other possible values for nginx.ingress.kubernetes.io/lua-resty-waf are inactive and simulate. +In inactive mode WAF won't do anything, whereas in simulate mode it will log a warning message if there's a matching WAF rule for given request. This is useful to debug a rule and eliminate possible false positives before fully deploying it.

        lua-resty-waf comes with predefined set of rules https://github.com/p0pr0ck5/lua-resty-waf/tree/84b4f40362500dd0cb98b9e71b5875cb1a40f1ad/rules that covers ModSecurity CRS. -You can use nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets to ignore subset of those rulesets. For an example:

        +You can use nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets to ignore a subset of those rulesets. For an example:

        nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets: "41000_sqli, 42000_xss"

        will ignore the two mentioned rulesets.

        -

        It is also possible to configure custom WAF rules per ingress using nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules annotation. For an example the following snippet will -configure a WAF rule to deny requests with query string value that contains word foo:

        +

        It is also possible to configure custom WAF rules per ingress using the nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules annotation. For an example the following snippet will configure a WAF rule to deny requests with query string value that contains word foo:

        nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules: '[=[ { "access": [ { "actions": { "disrupt" : "DENY" }, "id": 10001, "msg": "my custom rule", "operator": "STR_CONTAINS", "pattern": "foo", "vars": [ { "parse": [ "values", 1 ], "type": "REQUEST_ARGS" } ] } ], "body_filter": [], "header_filter":[] } ]=]'
        @@ -2148,12 +2250,13 @@ configure a WAF rule to deny requests with query string value that contains word

        For details on how to write WAF rules, please refer to https://github.com/p0pr0ck5/lua-resty-waf.

        gRPC backend

        Since NGINX 1.13.10 it is possible to expose gRPC services natively

        -

        You only need to add the annotation nginx.ingress.kubernetes.io/grpc-backend: "true" to enable this feature. Additionally, if the gRPC service requires TLS nginx.ingress.kubernetes.io/secure-backends: "true"

        -
        -

        Important

        -

        This feature requires HTTP2 to work which means we need to expose this service using HTTPS.

        +

        You only need to add the annotation nginx.ingress.kubernetes.io/grpc-backend: "true" to enable this feature. +Additionally, if the gRPC service requires TLS, add nginx.ingress.kubernetes.io/secure-backends: "true".

        +
        +

        Attention

        +

        This feature requires HTTP2 to work which means we need to expose this service using HTTPS. +Exposing a gRPC service using HTTP is not supported.

        -

        Exposing a gRPC service using HTTP is not supported.

        diff --git a/user-guide/nginx-configuration/configmap/index.html b/user-guide/nginx-configuration/configmap/index.html index 57eba3878..9b1105de7 100644 --- a/user-guide/nginx-configuration/configmap/index.html +++ b/user-guide/nginx-configuration/configmap/index.html @@ -246,7 +246,7 @@
      • - + Examples @@ -360,6 +360,18 @@
        • + + + + + +
      • + + Upgrading + +
        • + + @@ -1316,6 +1328,18 @@ +
      • + + Default backend + +
        • + + + + + + +
      • Exposing TCP and UDP services @@ -1353,8 +1377,8 @@
      • - - Multiple ingress controllers + + Multiple Ingress controllers
        • @@ -1377,8 +1401,8 @@
      • - - TLS + + TLS/HTTPS
        • @@ -1390,13 +1414,13 @@
      • - + -
        • @@ -1636,8 +1672,8 @@
      • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
        • @@ -1660,8 +1696,8 @@
      • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
        • @@ -1700,18 +1736,6 @@ -
      • - - External Authentication - -
        • - - - - - - -
      • Multi TLS certificate termination diff --git a/user-guide/nginx-configuration/custom-template/index.html b/user-guide/nginx-configuration/custom-template/index.html index a4dd970ae..600b87049 100644 --- a/user-guide/nginx-configuration/custom-template/index.html +++ b/user-guide/nginx-configuration/custom-template/index.html @@ -246,7 +246,7 @@
      • - + Examples @@ -360,6 +360,18 @@
        • + + + + + +
      • + + Upgrading + +
        • + + @@ -510,6 +522,18 @@ +
      • + + Default backend + +
        • + + + + + + +
      • Exposing TCP and UDP services @@ -547,8 +571,8 @@
      • - - Multiple ingress controllers + + Multiple Ingress controllers
        • @@ -571,8 +595,8 @@
      • - - TLS + + TLS/HTTPS
        • @@ -584,13 +608,13 @@
      • - + -
        • @@ -830,8 +866,8 @@
      • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
        • @@ -854,8 +890,8 @@
      • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
        • @@ -894,18 +930,6 @@ -
      • - - External Authentication - -
        • - - - - - - -
      • Multi TLS certificate termination diff --git a/user-guide/nginx-configuration/index.html b/user-guide/nginx-configuration/index.html index e93388135..0789c4edb 100644 --- a/user-guide/nginx-configuration/index.html +++ b/user-guide/nginx-configuration/index.html @@ -246,7 +246,7 @@
      • - + Examples @@ -360,6 +360,18 @@
        • + + + + + +
      • + + Upgrading + +
        • + + @@ -510,6 +522,18 @@ +
      • + + Default backend + +
        • + + + + + + +
      • Exposing TCP and UDP services @@ -547,8 +571,8 @@
      • - - Multiple ingress controllers + + Multiple Ingress controllers
        • @@ -571,8 +595,8 @@
      • - - TLS + + TLS/HTTPS
        • @@ -584,13 +608,13 @@
      • - + -
        • @@ -830,8 +866,8 @@
      • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
        • @@ -854,8 +890,8 @@
      • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
        • @@ -894,18 +930,6 @@ -
      • - - External Authentication - -
        • - - - - - - -
      • Multi TLS certificate termination @@ -1047,7 +1071,7 @@
        diff --git a/user-guide/nginx-configuration/log-format/index.html b/user-guide/nginx-configuration/log-format/index.html index d3f817217..7c7981671 100644 --- a/user-guide/nginx-configuration/log-format/index.html +++ b/user-guide/nginx-configuration/log-format/index.html @@ -246,7 +246,7 @@
      • - + Examples @@ -360,6 +360,18 @@
        • + + + + + +
      • + + Upgrading + +
        • + + @@ -510,6 +522,18 @@ +
      • + + Default backend + +
        • + + + + + + +
      • Exposing TCP and UDP services @@ -547,8 +571,8 @@
      • - - Multiple ingress controllers + + Multiple Ingress controllers
        • @@ -571,8 +595,8 @@
      • - - TLS + + TLS/HTTPS
        • @@ -584,13 +608,13 @@
      • - + -
        • @@ -830,8 +866,8 @@
      • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
        • @@ -854,8 +890,8 @@
      • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
        • @@ -894,18 +930,6 @@ -
      • - - External Authentication - -
        • - - - - - - -
      • Multi TLS certificate termination @@ -1021,37 +1045,98 @@

        Log format

        -

        The default configuration uses a custom logging format to add additional information about upstreams, response time and status

        -
            log_format upstreaminfo '{{ if $cfg.useProxyProtocol }}$proxy_protocol_addr{{ else }}$remote_addr{{ end }} - '
-        '[$the_real_ip] - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" '
-        '$request_length $request_time [$proxy_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status';
+
        The default configuration uses a custom logging format to add additional information about upstreams, response time and status.
        
+
        log_format upstreaminfo
+    '{{ if $cfg.useProxyProtocol }}$proxy_protocol_addr{{ else }}$remote_addr{{ end }} - '
+    '[$the_real_ip] - $remote_user [$time_local] "$request" '
+    '$status $body_bytes_sent "$http_referer" "$http_user_agent" '
+    '$request_length $request_time [$proxy_upstream_name] $upstream_addr '
+    '$upstream_response_length $upstream_response_time $upstream_status';
 
        
 
 
+
        • + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
        PlaceholderDescription
        $proxy_protocol_addrremote address if proxy protocol is enabled
        $remote_addrremote address if proxy protocol is disabled (default)
        $the_real_ipthe source IP address of the client
        $remote_useruser name supplied with the Basic authentication
        $time_locallocal time in the Common Log Format
        $requestfull original request line
        $statusresponse status
        $body_bytes_sentnumber of bytes sent to a client, not counting the response header
        $http_referervalue of the Referer header
        $http_user_agentvalue of User-Agent header
        $request_lengthrequest length (including request line, header, and request body)
        $request_timetime elapsed since the first bytes were read from the client
        $proxy_upstream_namename of the upstream. The format is upstream-<namespace>-<service name>-<service port>
        $upstream_addrthe IP address and port (or the path to the domain socket) of the upstream server. If several servers were contacted during request processing, their addresses are separated by commas.
        $upstream_response_lengththe length of the response obtained from the upstream server
        $upstream_response_timetime spent on receiving the response from the upstream server as seconds with millisecond resolution
        $upstream_statusstatus code of the response obtained from the upstream server

        Sources:

        -

        Description:

        -
          -
        • $proxy_protocol_addr: if PROXY protocol is enabled
          • -
        • $remote_addr: if PROXY protocol is disabled (default)
          • -
        • $the_real_ip: the source IP address of the client
          • -
        • $remote_user: user name supplied with the Basic authentication
          • -
        • $time_local: local time in the Common Log Format
          • -
        • $request: full original request line
          • -
        • $status: response status
          • -
        • $body_bytes_sent: number of bytes sent to a client, not counting the response header
          • -
        • $http_referer: value of the Referer header
          • -
        • $http_user_agent: value of User-Agent header
          • -
        • $request_length: request length (including request line, header, and request body)
          • -
        • $request_time: time elapsed since the first bytes were read from the client
          • -
        • $proxy_upstream_name: name of the upstream. The format is upstream-<namespace>-<service name>-<service port>
          • -
        • $upstream_addr: keeps the IP address and port, or the path to the UNIX-domain socket of the upstream server. If several servers were contacted during request processing, their addresses are separated by commas
          • -
        • $upstream_response_length: keeps the length of the response obtained from the upstream server
          • -
        • $upstream_response_time: keeps time spent on receiving the response from the upstream server; the time is kept in seconds with millisecond resolution
          • -
        • $upstream_status: keeps status code of the response obtained from the upstream server
          • +
        • Upstream variables
          • +
        • Embedded variables
        diff --git a/user-guide/nginx-status-page/index.html b/user-guide/nginx-status-page/index.html index a80ffea51..fdc8353e7 100644 --- a/user-guide/nginx-status-page/index.html +++ b/user-guide/nginx-status-page/index.html @@ -246,7 +246,7 @@
      • - + Examples @@ -360,6 +360,18 @@
        • + + + + + +
      • + + Upgrading + +
        • + +
      • @@ -499,6 +511,18 @@ +
    • + + Default backend + +
      • + + + + + + +
    • Exposing TCP and UDP services @@ -536,8 +560,8 @@
    • - - Multiple ingress controllers + + Multiple Ingress controllers
      • @@ -569,8 +593,8 @@
    • - - TLS + + TLS/HTTPS
      • @@ -582,13 +606,13 @@
    • - + -
      • @@ -828,8 +864,8 @@
    • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
      • @@ -852,8 +888,8 @@
    • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
      • @@ -892,18 +928,6 @@ -
    • - - External Authentication - -
      • - - - - - - -
    • Multi TLS certificate termination @@ -1045,7 +1069,7 @@ To use this module just set in the configuration configmap
    • @@ -499,6 +511,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -536,8 +560,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -560,8 +584,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -575,13 +599,13 @@
  • - + -
    • @@ -830,8 +866,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -854,8 +890,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -894,18 +930,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination @@ -1052,7 +1076,7 @@ Using enable-owasp-modsecurity-crs: "true"
    • @@ -499,6 +511,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -536,8 +560,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -560,8 +584,8 @@
  • - - TLS + + TLS/HTTPS
    • @@ -575,13 +599,13 @@
  • - + -
    • @@ -830,8 +866,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
    • @@ -854,8 +890,8 @@
  • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
    • @@ -894,18 +930,6 @@ -
  • - - External Authentication - -
    • - - - - - - -
  • Multi TLS certificate termination @@ -1090,13 +1114,13 @@ kubectl create -f https://raw.githubusercontent.com/rnburn/zipkin-date-server/ma -
    + Skip to content @@ -121,7 +121,7 @@ NGINX Ingress Controller - TLS + TLS/HTTPS @@ -246,7 +246,7 @@
  • - + Examples @@ -360,6 +360,18 @@
    • + + + + + +
  • + + Upgrading + +
    • + + @@ -499,6 +511,18 @@ +
  • + + Default backend + +
    • + + + + + + +
  • Exposing TCP and UDP services @@ -536,8 +560,8 @@
  • - - Multiple ingress controllers + + Multiple Ingress controllers
    • @@ -569,11 +593,11 @@ - - TLS + + TLS/HTTPS @@ -586,6 +610,13 @@
      +
    • + + TLS Secrets + + +
      • +
    • Default SSL Certificate @@ -626,14 +657,20 @@ Default TLS Version and Ciphers -
      • - -
    • + + +
      • @@ -653,13 +690,13 @@
    • - + -
      • @@ -899,8 +948,8 @@
    • - - Deploying the Nginx Ingress controller + + Custom VTS metrics with Prometheus
      • @@ -923,8 +972,8 @@
    • - - Deploying the Nginx Ingress controller + + Custom DH parameters for perfect forward secrecy
      • @@ -963,18 +1012,6 @@ -
    • - - External Authentication - -
      • - - - - - - -
    • Multi TLS certificate termination @@ -1079,6 +1116,13 @@
        +
      • + + TLS Secrets + + +
        • +
      • Default SSL Certificate @@ -1119,14 +1163,20 @@ Default TLS Version and Ciphers -
        • - -
      • + + +
        • @@ -1147,141 +1197,82 @@ -

        TLS

        - +

        TLS/HTTPS

        +

        TLS Secrets

        +

        Anytime we reference a TLS secret, we mean a PEM-encoded X.509, RSA (2048) secret.

        +

        You can generate a self-signed certificate and private key with with:

        +
        $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ${KEY_FILE} -out ${CERT_FILE} -subj "/CN=${HOST}/O=${HOST}"`
+
        + + +

        Then create the secret in the cluster via:

        +
        kubectl create secret tls ${CERT_NAME} --key ${KEY_FILE} --cert ${CERT_FILE}
+
        + + +

        The resulting secret will be of type kubernetes.io/tls.

        Default SSL Certificate

        -

        NGINX provides the option to configure a server as a catch-all with server_name for requests that do not match any of the configured server names. This configuration works without issues for HTTP traffic. -In case of HTTPS, NGINX requires a certificate. -For this reason the Ingress controller provides the flag --default-ssl-certificate. The secret behind this flag contains the default certificate to be used in the mentioned scenario. If this flag is not provided NGINX will use a self signed certificate.

        -

        Running without the flag --default-ssl-certificate:

        -
        $ curl -v https://10.2.78.7:443 -k
-* Rebuilt URL to: https://10.2.78.7:443/
-*   Trying 10.2.78.4...
-* Connected to 10.2.78.7 (10.2.78.7) port 443 (#0)
-* ALPN, offering http/1.1
-* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
-* successfully set certificate verify locations:
-*   CAfile: /etc/ssl/certs/ca-certificates.crt
-  CApath: /etc/ssl/certs
-* TLSv1.2 (OUT), TLS header, Certificate Status (22):
-* TLSv1.2 (OUT), TLS handshake, Client hello (1):
-* TLSv1.2 (IN), TLS handshake, Server hello (2):
-* TLSv1.2 (IN), TLS handshake, Certificate (11):
-* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
-* TLSv1.2 (IN), TLS handshake, Server finished (14):
-* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
-* TLSv1.2 (OUT), TLS change cipher, Client hello (1):
-* TLSv1.2 (OUT), TLS handshake, Finished (20):
-* TLSv1.2 (IN), TLS change cipher, Client hello (1):
-* TLSv1.2 (IN), TLS handshake, Finished (20):
-* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256
-* ALPN, server accepted to use http/1.1
-* Server certificate:
-*    subject: CN=foo.bar.com
-*    start date: Apr 13 00:50:56 2016 GMT
-*    expire date: Apr 13 00:50:56 2017 GMT
-*    issuer: CN=foo.bar.com
-*    SSL certificate verify result: self signed certificate (18), continuing anyway.
-> GET / HTTP/1.1
-> Host: 10.2.78.7
-> User-Agent: curl/7.47.1
-> Accept: */*
->
-< HTTP/1.1 404 Not Found
-< Server: nginx/1.11.1
-< Date: Thu, 21 Jul 2016 15:38:46 GMT
-< Content-Type: text/html
-< Transfer-Encoding: chunked
-< Connection: keep-alive
-< Strict-Transport-Security: max-age=15724800; includeSubDomains; preload
-<
-<span>The page you're looking for could not be found.</span>
-
-* Connection #0 to host 10.2.78.7 left intact
-
        - - -

        Specifying --default-ssl-certificate=default/foo-tls:

        -
        core@localhost ~ $ curl -v https://10.2.78.7:443 -k
-* Rebuilt URL to: https://10.2.78.7:443/
-*   Trying 10.2.78.7...
-* Connected to 10.2.78.7 (10.2.78.7) port 443 (#0)
-* ALPN, offering http/1.1
-* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
-* successfully set certificate verify locations:
-*   CAfile: /etc/ssl/certs/ca-certificates.crt
-  CApath: /etc/ssl/certs
-* TLSv1.2 (OUT), TLS header, Certificate Status (22):
-* TLSv1.2 (OUT), TLS handshake, Client hello (1):
-* TLSv1.2 (IN), TLS handshake, Server hello (2):
-* TLSv1.2 (IN), TLS handshake, Certificate (11):
-* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
-* TLSv1.2 (IN), TLS handshake, Server finished (14):
-* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
-* TLSv1.2 (OUT), TLS change cipher, Client hello (1):
-* TLSv1.2 (OUT), TLS handshake, Finished (20):
-* TLSv1.2 (IN), TLS change cipher, Client hello (1):
-* TLSv1.2 (IN), TLS handshake, Finished (20):
-* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256
-* ALPN, server accepted to use http/1.1
-* Server certificate:
-*    subject: CN=foo.bar.com
-*    start date: Apr 13 00:50:56 2016 GMT
-*    expire date: Apr 13 00:50:56 2017 GMT
-*    issuer: CN=foo.bar.com
-*    SSL certificate verify result: self signed certificate (18), continuing anyway.
-> GET / HTTP/1.1
-> Host: 10.2.78.7
-> User-Agent: curl/7.47.1
-> Accept: */*
->
-< HTTP/1.1 404 Not Found
-< Server: nginx/1.11.1
-< Date: Mon, 18 Jul 2016 21:02:59 GMT
-< Content-Type: text/html
-< Transfer-Encoding: chunked
-< Connection: keep-alive
-< Strict-Transport-Security: max-age=15724800; includeSubDomains; preload
-<
-<span>The page you're looking for could not be found.</span>
-
-* Connection #0 to host 10.2.78.7 left intact
-
        - - +

        NGINX provides the option to configure a server as a catch-all with +server_name +for requests that do not match any of the configured server names. +This configuration works without out-of-the-box for HTTP traffic. +For HTTPS, a certificate is naturally required.

        +

        For this reason the Ingress controller provides the flag --default-ssl-certificate. +The secret referred to by this flag contains the default certificate to be used when +accessing the catch-all server. +If this flag is not provided NGINX will use a self-signed certificate.

        +

        For instance, if you have a TLS secret foo-tls in the default namespace, +add --default-ssl-certificate=default/foo-tls in the nginx-controller deployment.

        SSL Passthrough

        -

        The flag --enable-ssl-passthrough enables SSL passthrough feature. -By default this feature is disabled

        +

        The flag --enable-ssl-passthrough enables the SSL passthrough feature. +By default this feature is disabled.

        +

        This is required to enable passthrough backends in Ingress configurations.

        +

        TODO: Improve this documentation.

        HTTP Strict Transport Security

        -

        HTTP Strict Transport Security (HSTS) is an opt-in security enhancement specified through the use of a special response header. Once a supported browser receives this header that browser will prevent any communications from being sent over HTTP to the specified domain and will instead send all communications over HTTPS.

        -

        By default the controller redirects (301) to HTTPS if there is a TLS Ingress rule.

        -

        To disable this behavior use hsts: "false" in the configuration ConfigMap.

        +

        HTTP Strict Transport Security (HSTS) is an opt-in security enhancement specified +through the use of a special response header. Once a supported browser receives +this header that browser will prevent any communications from being sent over +HTTP to the specified domain and will instead send all communications over HTTPS.

        +

        HSTS is enabled by default.

        +

        To disable this behavior use hsts: "false" in the configuration ConfigMap.

        Server-side HTTPS enforcement through redirect

        -

        By default the controller redirects (301) to HTTPS if TLS is enabled for that ingress. If you want to disable that behavior globally, you can use ssl-redirect: "false" in the NGINX config map.

        -

        To configure this feature for specific ingress resources, you can use the nginx.ingress.kubernetes.io/ssl-redirect: "false" annotation in the particular resource.

        -

        When using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to HTTPS even when there is not TLS cert available. This can be achieved by using the nginx.ingress.kubernetes.io/force-ssl-redirect: "true" annotation in the particular resource.

        +

        By default the controller redirects HTTP clients to the HTTPS port +443 using a 308 Permanent Redirect response if TLS is enabled for that Ingress.

        +

        This can be disabled globally using ssl-redirect: "false" in the NGINX config map, +or per-Ingress with the nginx.ingress.kubernetes.io/ssl-redirect: "false" +annotation in the particular resource.

        +
        +

        Tip

        +

        When using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a +redirect to HTTPS even when there is no TLS certificate available. +This can be achieved by using the nginx.ingress.kubernetes.io/force-ssl-redirect: "true" +annotation in the particular resource.

        +

        Automated Certificate Management with Kube-Lego

        -

        Kube-Lego automatically requests missing or expired certificates from Let's Encrypt by monitoring ingress resources and their referenced secrets. To enable this for an ingress resource you have to add an annotation:

        +
        +

        Tip

        +

        Kube-Lego has reached end-of-life and is being +replaced by cert-manager.

        +
        +

        Kube-Lego automatically requests missing or expired certificates from Let's Encrypt +by monitoring ingress resources and their referenced secrets.

        +

        To enable this for an ingress resource you have to add an annotation:

        kubectl annotate ing ingress-demo kubernetes.io/tls-acme="true"
        -

        To setup Kube-Lego you can take a look at this full example. The first -version to fully support Kube-Lego is nginx Ingress controller 0.8.

        +

        To setup Kube-Lego you can take a look at this full example. +The first version to fully support Kube-Lego is Nginx Ingress controller 0.8.

        Default TLS Version and Ciphers

        -

        To provide the most secure baseline configuration possible, nginx-ingress defaults to using TLS 1.2 and a secure set of TLS ciphers

        -

        Legacy TLS

        -

        The default configuration, though secure, does not support some older browsers and operating systems. For instance, 20% of Android phones in use today are not compatible with nginx-ingress's default configuration. To change this default behavior, use a ConfigMap.

        -

        A sample ConfigMap to allow these older clients connect could look something like the following:

        +

        To provide the most secure baseline configuration possible,

        +

        nginx-ingress defaults to using TLS 1.2 only and a secure set of TLS ciphers.

        +

        Legacy TLS

        +

        The default configuration, though secure, does not support some older browsers and operating systems.

        +

        For instance, TLS 1.1+ is only enabled by default from Android 5.0 on. At the time of writing, +May 2018, approximately 15% of Android devices +are not compatible with nginx-ingress's default configuration.

        +

        To change this default behavior, use a ConfigMap.

        +

        A sample ConfigMap fragment to allow these older clients to connect could look something like the following:

        kind: ConfigMap
 apiVersion: v1
 metadata: