Bare-metal considerations ¶ In traditional cloud environments, where network load balancers are available on-demand, a single Kubernetes manifest suffices to provide a single point of contact to the NGINX Ingress controller to external clients and, indirectly, to any application running inside the cluster. Bare-metal environments lack this commodity, requiring a slightly different setup to offer the same kind of access to external consumers. The rest of this document describes a few recommended approaches to deploying the NGINX Ingress controller inside a Kubernetes cluster running on bare-metal. A pure software solution: MetalLB ¶ MetalLB provides a network load-balancer implementation for Kubernetes clusters that do not run on a supported cloud provider, effectively allowing the usage of LoadBalancer Services within any cluster. This section demonstrates how to use the Layer 2 configuration mode of MetalLB together with the NGINX Ingress controller in a Kubernetes cluster that has publicly accessible nodes. In this mode, one node attracts all the traffic for the ingress-nginx Service IP. See Traffic policies for more details. Note The description of other supported configuration modes is off-scope for this document. Warning MetalLB is currently in beta. Read about the Project maturity and make sure you inform yourself by reading the official documentation thoroughly. MetalLB can be deployed either with a simple Kubernetes manifest or with Helm. The rest of this example assumes MetalLB was deployed following the Installation instructions, and that the NGINX Ingress controller was installed using the steps described in the quickstart section of the installation guide. MetalLB requires a pool of IP addresses in order to be able to take ownership of the ingress-nginx Service. This pool can be defined through IPAddressPool objects in the same namespace as the MetalLB controller. This pool of IPs must be dedicated to MetalLB's use, you can't reuse the Kubernetes node IPs or IPs handed out by a DHCP server. Example Given the following 3-node Kubernetes cluster (the external IP is added as an example, in most bare-metal environments this value is <None>) $ kubectl get node + Bare-metal considerations - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Bare-metal considerations Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Bare-metal considerations Table of contents A pure software solution: MetalLB Over a NodePort Service Via the host network Using a self-provisioned edge External IPs Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents A pure software solution: MetalLB Over a NodePort Service Via the host network Using a self-provisioned edge External IPs Bare-metal considerations ¶ In traditional cloud environments, where network load balancers are available on-demand, a single Kubernetes manifest suffices to provide a single point of contact to the Ingress-Nginx Controller to external clients and, indirectly, to any application running inside the cluster. Bare-metal environments lack this commodity, requiring a slightly different setup to offer the same kind of access to external consumers. The rest of this document describes a few recommended approaches to deploying the Ingress-Nginx Controller inside a Kubernetes cluster running on bare-metal. A pure software solution: MetalLB ¶ MetalLB provides a network load-balancer implementation for Kubernetes clusters that do not run on a supported cloud provider, effectively allowing the usage of LoadBalancer Services within any cluster. This section demonstrates how to use the Layer 2 configuration mode of MetalLB together with the NGINX Ingress controller in a Kubernetes cluster that has publicly accessible nodes. In this mode, one node attracts all the traffic for the ingress-nginx Service IP. See Traffic policies for more details. Note The description of other supported configuration modes is off-scope for this document. Warning MetalLB is currently in beta. Read about the Project maturity and make sure you inform yourself by reading the official documentation thoroughly. MetalLB can be deployed either with a simple Kubernetes manifest or with Helm. The rest of this example assumes MetalLB was deployed following the Installation instructions, and that the Ingress-Nginx Controller was installed using the steps described in the quickstart section of the installation guide. MetalLB requires a pool of IP addresses in order to be able to take ownership of the ingress-nginx Service. This pool can be defined through IPAddressPool objects in the same namespace as the MetalLB controller. This pool of IPs must be dedicated to MetalLB's use, you can't reuse the Kubernetes node IPs or IPs handed out by a DHCP server. Example Given the following 3-node Kubernetes cluster (the external IP is added as an example, in most bare-metal environments this value is <None>) $ kubectl get node NAME STATUS ROLES EXTERNAL-IP host-1 Ready master 203.0.113.1 host-2 Ready node 203.0.113.2 @@ -38,7 +38,7 @@ host-1 Ready master 203.0.113.1 host-2 Ready node 203.0.113.2 host-3 Ready node 203.0.113.3 - a client would reach an Ingress with host: myapp.example.com at http://myapp.example.com:30100, where the myapp.example.com subdomain resolves to the 203.0.113.2 IP address. Impact on the host system While it may sound tempting to reconfigure the NodePort range using the --service-node-port-range API server flag to include unprivileged ports and be able to expose ports 80 and 443, doing so may result in unexpected issues including (but not limited to) the use of ports otherwise reserved to system daemons and the necessity to grant kube-proxy privileges it may otherwise not require. This practice is therefore discouraged. See the other approaches proposed in this page for alternatives. This approach has a few other limitations one ought to be aware of: Source IP address Services of type NodePort perform source address translation by default. This means the source IP of a HTTP request is always the IP address of the Kubernetes node that received the request from the perspective of NGINX. The recommended way to preserve the source IP in a NodePort setup is to set the value of the externalTrafficPolicy field of the ingress-nginx Service spec to Local (example). Warning This setting effectively drops packets sent to Kubernetes nodes which are not running any instance of the NGINX Ingress controller. Consider assigning NGINX Pods to specific nodes in order to control on what nodes the NGINX Ingress controller should be scheduled or not scheduled. Example In a Kubernetes cluster composed of 3 nodes (the external IP is added as an example, in most bare-metal environments this value is <None>) $ kubectl get node + a client would reach an Ingress with host: myapp.example.com at http://myapp.example.com:30100, where the myapp.example.com subdomain resolves to the 203.0.113.2 IP address. Impact on the host system While it may sound tempting to reconfigure the NodePort range using the --service-node-port-range API server flag to include unprivileged ports and be able to expose ports 80 and 443, doing so may result in unexpected issues including (but not limited to) the use of ports otherwise reserved to system daemons and the necessity to grant kube-proxy privileges it may otherwise not require. This practice is therefore discouraged. See the other approaches proposed in this page for alternatives. This approach has a few other limitations one ought to be aware of: Source IP address Services of type NodePort perform source address translation by default. This means the source IP of a HTTP request is always the IP address of the Kubernetes node that received the request from the perspective of NGINX. The recommended way to preserve the source IP in a NodePort setup is to set the value of the externalTrafficPolicy field of the ingress-nginx Service spec to Local (example). Warning This setting effectively drops packets sent to Kubernetes nodes which are not running any instance of the NGINX Ingress controller. Consider assigning NGINX Pods to specific nodes in order to control on what nodes the Ingress-Nginx Controller should be scheduled or not scheduled. Example In a Kubernetes cluster composed of 3 nodes (the external IP is added as an example, in most bare-metal environments this value is <None>) $ kubectl get node NAME STATUS ROLES EXTERNAL-IP host-1 Ready master 203.0.113.1 host-2 Ready node 203.0.113.2 @@ -48,10 +48,10 @@ default-http-backend-7c5bc89cc9-p86md 1/1 Running 172.17.1.1 host-2 ingress-nginx-controller-cf9ff8c96-8vvf8 1/1 Running 172.17.0.3 host-3 ingress-nginx-controller-cf9ff8c96-pxsds 1/1 Running 172.17.1.4 host-2 - Requests sent to host-2 and host-3 would be forwarded to NGINX and original client's IP would be preserved, while requests to host-1 would get dropped because there is no NGINX replica running on that node. Ingress status Because NodePort Services do not get a LoadBalancerIP assigned by definition, the NGINX Ingress controller does not update the status of Ingress objects it manages. $ kubectl get ingress + Requests sent to host-2 and host-3 would be forwarded to NGINX and original client's IP would be preserved, while requests to host-1 would get dropped because there is no NGINX replica running on that node. Ingress status Because NodePort Services do not get a LoadBalancerIP assigned by definition, the Ingress-Nginx Controller does not update the status of Ingress objects it manages. $ kubectl get ingress NAME HOSTS ADDRESS PORTS test-ingress myapp.example.com 80 - Despite the fact there is no load balancer providing a public IP address to the NGINX Ingress controller, it is possible to force the status update of all managed Ingress objects by setting the externalIPs field of the ingress-nginx Service. Warning There is more to setting externalIPs than just enabling the NGINX Ingress controller to update the status of Ingress objects. Please read about this option in the Services page of official Kubernetes documentation as well as the section about External IPs in this document for more information. Example Given the following 3-node Kubernetes cluster (the external IP is added as an example, in most bare-metal environments this value is <None>) $ kubectl get node + Despite the fact there is no load balancer providing a public IP address to the Ingress-Nginx Controller, it is possible to force the status update of all managed Ingress objects by setting the externalIPs field of the ingress-nginx Service. Warning There is more to setting externalIPs than just enabling the Ingress-Nginx Controller to update the status of Ingress objects. Please read about this option in the Services page of official Kubernetes documentation as well as the section about External IPs in this document for more information. Example Given the following 3-node Kubernetes cluster (the external IP is added as an example, in most bare-metal environments this value is <None>) $ kubectl get node NAME STATUS ROLES EXTERNAL-IP host-1 Ready master 203.0.113.1 host-2 Ready node 203.0.113.2 @@ -68,24 +68,24 @@ HTTP/1.1 308 Permanent Redirect Server: nginx/1.15.2 Location: https://myapp.example.com/ #-> missing NodePort in HTTPS redirect - Via the host network ¶ In a setup where there is no external load balancer available but using NodePorts is not an option, one can configure ingress-nginx Pods to use the network of the host they run on instead of a dedicated network namespace. The benefit of this approach is that the NGINX Ingress controller can bind ports 80 and 443 directly to Kubernetes nodes' network interfaces, without the extra network translation imposed by NodePort Services. Note This approach does not leverage any Service object to expose the NGINX Ingress controller. If the ingress-nginx Service exists in the target cluster, it is recommended to delete it. This can be achieved by enabling the hostNetwork option in the Pods' spec. template: + Via the host network ¶ In a setup where there is no external load balancer available but using NodePorts is not an option, one can configure ingress-nginx Pods to use the network of the host they run on instead of a dedicated network namespace. The benefit of this approach is that the Ingress-Nginx Controller can bind ports 80 and 443 directly to Kubernetes nodes' network interfaces, without the extra network translation imposed by NodePort Services. Note This approach does not leverage any Service object to expose the Ingress-Nginx Controller. If the ingress-nginx Service exists in the target cluster, it is recommended to delete it. This can be achieved by enabling the hostNetwork option in the Pods' spec. template: spec: hostNetwork: true - Security considerations Enabling this option exposes every system daemon to the NGINX Ingress controller on any network interface, including the host's loopback. Please evaluate the impact this may have on the security of your system carefully. Example Consider this ingress-nginx-controller Deployment composed of 2 replicas, NGINX Pods inherit from the IP address of their host instead of an internal Pod IP. $ kubectl -n ingress-nginx get pod -o wide + Security considerations Enabling this option exposes every system daemon to the Ingress-Nginx Controller on any network interface, including the host's loopback. Please evaluate the impact this may have on the security of your system carefully. Example Consider this ingress-nginx-controller Deployment composed of 2 replicas, NGINX Pods inherit from the IP address of their host instead of an internal Pod IP. $ kubectl -n ingress-nginx get pod -o wide NAME READY STATUS IP NODE default-http-backend-7c5bc89cc9-p86md 1/1 Running 172.17.1.1 host-2 ingress-nginx-controller-5b4cf5fc6-7lg6c 1/1 Running 203.0.113.3 host-3 ingress-nginx-controller-5b4cf5fc6-lzrls 1/1 Running 203.0.113.2 host-2 - One major limitation of this deployment approach is that only a single NGINX Ingress controller Pod may be scheduled on each cluster node, because binding the same port multiple times on the same network interface is technically impossible. Pods that are unschedulable due to such situation fail with the following event: $ kubectl -n ingress-nginx describe pod <unschedulable-ingress-nginx-controller-pod> + One major limitation of this deployment approach is that only a single Ingress-Nginx Controller Pod may be scheduled on each cluster node, because binding the same port multiple times on the same network interface is technically impossible. Pods that are unschedulable due to such situation fail with the following event: $ kubectl -n ingress-nginx describe pod <unschedulable-ingress-nginx-controller-pod> ... Events: Type Reason From Message ---- ------ ---- ------- Warning FailedScheduling default-scheduler 0/3 nodes are available: 3 node(s) didn't have free ports for the requested pod ports. - One way to ensure only schedulable Pods are created is to deploy the NGINX Ingress controller as a DaemonSet instead of a traditional Deployment. Info A DaemonSet schedules exactly one type of Pod per cluster node, masters included, unless a node is configured to repel those Pods. For more information, see DaemonSet. Because most properties of DaemonSet objects are identical to Deployment objects, this documentation page leaves the configuration of the corresponding manifest at the user's discretion. Like with NodePorts, this approach has a few quirks it is important to be aware of. DNS resolution Pods configured with hostNetwork: true do not use the internal DNS resolver (i.e. kube-dns or CoreDNS), unless their dnsPolicy spec field is set to ClusterFirstWithHostNet. Consider using this setting if NGINX is expected to resolve internal names for any reason. Ingress status Because there is no Service exposing the NGINX Ingress controller in a configuration using the host network, the default --publish-service flag used in standard cloud setups does not apply and the status of all Ingress objects remains blank. $ kubectl get ingress + One way to ensure only schedulable Pods are created is to deploy the Ingress-Nginx Controller as a DaemonSet instead of a traditional Deployment. Info A DaemonSet schedules exactly one type of Pod per cluster node, masters included, unless a node is configured to repel those Pods. For more information, see DaemonSet. Because most properties of DaemonSet objects are identical to Deployment objects, this documentation page leaves the configuration of the corresponding manifest at the user's discretion. Like with NodePorts, this approach has a few quirks it is important to be aware of. DNS resolution Pods configured with hostNetwork: true do not use the internal DNS resolver (i.e. kube-dns or CoreDNS), unless their dnsPolicy spec field is set to ClusterFirstWithHostNet. Consider using this setting if NGINX is expected to resolve internal names for any reason. Ingress status Because there is no Service exposing the Ingress-Nginx Controller in a configuration using the host network, the default --publish-service flag used in standard cloud setups does not apply and the status of all Ingress objects remains blank. $ kubectl get ingress NAME HOSTS ADDRESS PORTS test-ingress myapp.example.com 80 - Instead, and because bare-metal nodes usually don't have an ExternalIP, one has to enable the --report-node-internal-ip-address flag, which sets the status of all Ingress objects to the internal IP address of all nodes running the NGINX Ingress controller. Example Given a ingress-nginx-controller DaemonSet composed of 2 replicas $ kubectl -n ingress-nginx get pod -o wide + Instead, and because bare-metal nodes usually don't have an ExternalIP, one has to enable the --report-node-internal-ip-address flag, which sets the status of all Ingress objects to the internal IP address of all nodes running the Ingress-Nginx Controller. Example Given a ingress-nginx-controller DaemonSet composed of 2 replicas $ kubectl -n ingress-nginx get pod -o wide NAME READY STATUS IP NODE default-http-backend-7c5bc89cc9-p86md 1/1 Running 172.17.1.1 host-2 ingress-nginx-controller-5b4cf5fc6-7lg6c 1/1 Running 203.0.113.3 host-3 diff --git a/deploy/hardening-guide/index.html b/deploy/hardening-guide/index.html index e3f0a0e16..6ee5d55bf 100644 --- a/deploy/hardening-guide/index.html +++ b/deploy/hardening-guide/index.html @@ -1,4 +1,4 @@ - Hardening guide - NGINX Ingress Controller Skip to content NGINX Ingress Controller Hardening guide Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide Hardening guide Table of contents Overview Configuration Guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Configuration Guide Hardening Guide ¶ Overview ¶ There are several ways to do hardening and securing of nginx. In this documentation two guides are used, the guides are overlapping in some points: nginx CIS Benchmark cipherlist.eu (one of many forks of the now dead project cipherli.st) This guide describes, what of the different configurations described in those guides is already implemented as default in the nginx implementation of kubernetes ingress, what needs to be configured, what is obsolete due to the fact that the nginx is running as container (the CIS benchmark relates to a non-containerized installation) and what is difficult or not possible. Be aware that this is only a guide and you are responsible for your own implementation. Some of the configurations may lead to have specific clients unable to reach your site or similar consequences. This guide refers to chapters in the CIS Benchmark. For full explanation you should refer to the benchmark document itself Configuration Guide ¶ Chapter in CIS benchmark Status Default Action to do if not default 1 Initial Setup 1.1 Installation 1.1.1 Ensure NGINX is installed (Scored) OK done through helm charts / following documentation to deploy nginx ingress 1.1.2 Ensure NGINX is installed from source (Not Scored) OK done through helm charts / following documentation to deploy nginx ingress 1.2 Configure Software Updates 1.2.1 Ensure package manager repositories are properly configured (Not Scored) OK done via helm, nginx version could be overwritten, however compatibility is not ensured then 1.2.2 Ensure the latest software package is installed (Not Scored) ACTION NEEDED done via helm, nginx version could be overwritten, however compatibility is not ensured then Plan for periodic updates 2 Basic Configuration 2.1 Minimize NGINX Modules 2.1.1 Ensure only required modules are installed (Not Scored) OK Already only needed modules are installed, however proposals for further reduction are welcome 2.1.2 Ensure HTTP WebDAV module is not installed (Scored) OK 2.1.3 Ensure modules with gzip functionality are disabled (Scored) OK 2.1.4 Ensure the autoindex module is disabled (Scored) OK No autoindex configs so far in ingress defaults 2.2 Account Security 2.2.1 Ensure that NGINX is run using a non-privileged, dedicated service account (Not Scored) OK Pod configured as user www-data: See this line in helm chart values. Compiled with user www-data: See this line in build script 2.2.2 Ensure the NGINX service account is locked (Scored) OK Docker design ensures this 2.2.3 Ensure the NGINX service account has an invalid shell (Scored) OK Shell is nologin: see this line in build script 2.3 Permissions and Ownership 2.3.1 Ensure NGINX directories and files are owned by root (Scored) OK Obsolete through docker-design and ingress controller needs to update the configs dynamically 2.3.2 Ensure access to NGINX directories and files is restricted (Scored) OK See previous answer 2.3.3 Ensure the NGINX process ID (PID) file is secured (Scored) OK No PID-File due to docker design 2.3.4 Ensure the core dump directory is secured (Not Scored) OK No working_directory configured by default 2.4 Network Configuration 2.4.1 Ensure NGINX only listens for network connections on authorized ports (Not Scored) OK Ensured by automatic nginx.conf configuration 2.4.2 Ensure requests for unknown host names are rejected (Not Scored) OK They are not rejected but send to the "default backend" delivering appropriate errors (mostly 404) 2.4.3 Ensure keepalive_timeout is 10 seconds or less, but not 0 (Scored) ACTION NEEDED Default is 75s configure keep-alive to 10 seconds according to this documentation 2.4.4 Ensure send_timeout is set to 10 seconds or less, but not 0 (Scored) RISK TO BE ACCEPTED Not configured, however the nginx default is 60s Not configurable 2.5 Information Disclosure 2.5.1 Ensure server_tokens directive is set to off (Scored) OK server_tokens is configured to off by default 2.5.2 Ensure default error and index.html pages do not reference NGINX (Scored) ACTION NEEDED 404 shows no version at all, 503 and 403 show "nginx", which is hardcoded see this line in nginx source code configure custom error pages at least for 403, 404 and 503 and 500 2.5.3 Ensure hidden file serving is disabled (Not Scored) ACTION NEEDED config not set configure a config.server-snippet Snippet, but beware of .well-known challenges or similar. Refer to the benchmark here please 2.5.4 Ensure the NGINX reverse proxy does not enable information disclosure (Scored) ACTION NEEDED hide not configured configure hide-headers with array of "X-Powered-By" and "Server": according to this documentation 3 Logging 3.1 Ensure detailed logging is enabled (Not Scored) OK nginx ingress has a very detailed log format by default 3.2 Ensure access logging is enabled (Scored) OK Access log is enabled by default 3.3 Ensure error logging is enabled and set to the info logging level (Scored) OK Error log is configured by default. The log level does not matter, because it is all sent to STDOUT anyway 3.4 Ensure log files are rotated (Scored) OBSOLETE Log file handling is not part of the nginx ingress and should be handled separately 3.5 Ensure error logs are sent to a remote syslog server (Not Scored) OBSOLETE See previous answer 3.6 Ensure access logs are sent to a remote syslog server (Not Scored) OBSOLETE See previous answer 3.7 Ensure proxies pass source IP information (Scored) OK Headers are set by default 4 Encryption 4.1 TLS / SSL Configuration 4.1.1 Ensure HTTP is redirected to HTTPS (Scored) OK Redirect to TLS is default 4.1.2 Ensure a trusted certificate and trust chain is installed (Not Scored) ACTION NEEDED For installing certs there are enough manuals in the web. A good way is to use lets encrypt through cert-manager Install proper certificates or use lets encrypt with cert-manager 4.1.3 Ensure private key permissions are restricted (Scored) ACTION NEEDED See previous answer 4.1.4 Ensure only modern TLS protocols are used (Scored) OK/ACTION NEEDED Default is TLS 1.2 + 1.3, while this is okay for CIS Benchmark, cipherlist.eu only recommends 1.3. This may cut off old OS's Set controller.config.ssl-protocols to "TLSv1.3" 4.1.5 Disable weak ciphers (Scored) ACTION NEEDED Default ciphers are already good, but cipherlist.eu recommends even stronger ciphers Set controller.config.ssl-ciphers to "EECDH+AESGCM:EDH+AESGCM" 4.1.6 Ensure custom Diffie-Hellman parameters are used (Scored) ACTION NEEDED No custom DH parameters are generated Generate dh parameters for each ingress deployment you use - see here for a how to 4.1.7 Ensure Online Certificate Status Protocol (OCSP) stapling is enabled (Scored) ACTION NEEDED Not enabled set via this configuration parameter 4.1.8 Ensure HTTP Strict Transport Security (HSTS) is enabled (Scored) OK HSTS is enabled by default 4.1.9 Ensure HTTP Public Key Pinning is enabled (Not Scored) ACTION NEEDED / RISK TO BE ACCEPTED HKPK not enabled by default If lets encrypt is not used, set correct HPKP header. There are several ways to implement this - with the helm charts it works via controller.add-headers. If lets encrypt is used, this is complicated, a solution here is yet unknown 4.1.10 Ensure upstream server traffic is authenticated with a client certificate (Scored) DEPENDS ON BACKEND Highly dependent on backends, not every backend allows configuring this, can also be mitigated via a service mesh If backend allows it, manual is here 4.1.11 Ensure the upstream traffic server certificate is trusted (Not Scored) DEPENDS ON BACKEND Highly dependent on backends, not every backend allows configuring this, can also be mitigated via a service mesh If backend allows it, see configuration here 4.1.12 Ensure your domain is preloaded (Not Scored) ACTION NEEDED Preload is not active by default Set controller.config.hsts-preload to true 4.1.13 Ensure session resumption is disabled to enable perfect forward security (Scored) OK Session tickets are disabled by default 4.1.14 Ensure HTTP/2.0 is used (Not Scored) OK http2 is set by default 5 Request Filtering and Restrictions 5.1 Access Control 5.1.1 Ensure allow and deny filters limit access to specific IP addresses (Not Scored) OK/ACTION NEEDED Depends on use case, geo ip module is compiled into nginx ingress controller, there are several ways to use it If needed set IP restrictions via annotations or work with config snippets (be careful with lets-encrypt-http-challenge!) 5.1.2 Ensure only whitelisted HTTP methods are allowed (Not Scored) OK/ACTION NEEDED Depends on use case If required it can be set via config snippet 5.2 Request Limits 5.2.1 Ensure timeout values for reading the client header and body are set correctly (Scored) ACTION NEEDED Default timeout is 60s Set via this configuration parameter and respective body equivalent 5.2.2 Ensure the maximum request body size is set correctly (Scored) ACTION NEEDED Default is 1m set via this configuration parameter 5.2.3 Ensure the maximum buffer size for URIs is defined (Scored) ACTION NEEDED Default is 4 8k Set via this configuration parameter 5.2.4 Ensure the number of connections per IP address is limited (Not Scored) OK/ACTION NEEDED No limit set Depends on use case, limit can be set via these annotations 5.2.5 Ensure rate limits by IP address are set (Not Scored) OK/ACTION NEEDED No limit set Depends on use case, limit can be set via these annotations 5.3 Browser Security 5.3.1 Ensure X-Frame-Options header is configured and enabled (Scored) ACTION NEEDED Header not set by default Several ways to implement this - with the helm charts it works via controller.add-headers 5.3.2 Ensure X-Content-Type-Options header is configured and enabled (Scored) ACTION NEEDED See previous answer See previous answer 5.3.3 Ensure the X-XSS-Protection Header is enabled and configured properly (Scored) ACTION NEEDED See previous answer See previous answer 5.3.4 Ensure that Content Security Policy (CSP) is enabled and configured properly (Not Scored) ACTION NEEDED See previous answer See previous answer 5.3.5 Ensure the Referrer Policy is enabled and configured properly (Not Scored) ACTION NEEDED Depends on application. It should be handled in the applications webserver itself, not in the load balancing ingress check backend webserver 6 Mandatory Access Control n/a too high level, depends on backends Skip to content Ingress-Nginx Controller Hardening guide Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide Hardening guide Table of contents Overview Configuration Guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Configuration Guide Hardening Guide ¶ Overview ¶ There are several ways to do hardening and securing of nginx. In this documentation two guides are used, the guides are overlapping in some points: nginx CIS Benchmark cipherlist.eu (one of many forks of the now dead project cipherli.st) This guide describes, what of the different configurations described in those guides is already implemented as default in the nginx implementation of kubernetes ingress, what needs to be configured, what is obsolete due to the fact that the nginx is running as container (the CIS benchmark relates to a non-containerized installation) and what is difficult or not possible. Be aware that this is only a guide and you are responsible for your own implementation. Some of the configurations may lead to have specific clients unable to reach your site or similar consequences. This guide refers to chapters in the CIS Benchmark. For full explanation you should refer to the benchmark document itself Configuration Guide ¶ Chapter in CIS benchmark Status Default Action to do if not default 1 Initial Setup 1.1 Installation 1.1.1 Ensure NGINX is installed (Scored) OK done through helm charts / following documentation to deploy nginx ingress 1.1.2 Ensure NGINX is installed from source (Not Scored) OK done through helm charts / following documentation to deploy nginx ingress 1.2 Configure Software Updates 1.2.1 Ensure package manager repositories are properly configured (Not Scored) OK done via helm, nginx version could be overwritten, however compatibility is not ensured then 1.2.2 Ensure the latest software package is installed (Not Scored) ACTION NEEDED done via helm, nginx version could be overwritten, however compatibility is not ensured then Plan for periodic updates 2 Basic Configuration 2.1 Minimize NGINX Modules 2.1.1 Ensure only required modules are installed (Not Scored) OK Already only needed modules are installed, however proposals for further reduction are welcome 2.1.2 Ensure HTTP WebDAV module is not installed (Scored) OK 2.1.3 Ensure modules with gzip functionality are disabled (Scored) OK 2.1.4 Ensure the autoindex module is disabled (Scored) OK No autoindex configs so far in ingress defaults 2.2 Account Security 2.2.1 Ensure that NGINX is run using a non-privileged, dedicated service account (Not Scored) OK Pod configured as user www-data: See this line in helm chart values. Compiled with user www-data: See this line in build script 2.2.2 Ensure the NGINX service account is locked (Scored) OK Docker design ensures this 2.2.3 Ensure the NGINX service account has an invalid shell (Scored) OK Shell is nologin: see this line in build script 2.3 Permissions and Ownership 2.3.1 Ensure NGINX directories and files are owned by root (Scored) OK Obsolete through docker-design and ingress controller needs to update the configs dynamically 2.3.2 Ensure access to NGINX directories and files is restricted (Scored) OK See previous answer 2.3.3 Ensure the NGINX process ID (PID) file is secured (Scored) OK No PID-File due to docker design 2.3.4 Ensure the core dump directory is secured (Not Scored) OK No working_directory configured by default 2.4 Network Configuration 2.4.1 Ensure NGINX only listens for network connections on authorized ports (Not Scored) OK Ensured by automatic nginx.conf configuration 2.4.2 Ensure requests for unknown host names are rejected (Not Scored) OK They are not rejected but send to the "default backend" delivering appropriate errors (mostly 404) 2.4.3 Ensure keepalive_timeout is 10 seconds or less, but not 0 (Scored) ACTION NEEDED Default is 75s configure keep-alive to 10 seconds according to this documentation 2.4.4 Ensure send_timeout is set to 10 seconds or less, but not 0 (Scored) RISK TO BE ACCEPTED Not configured, however the nginx default is 60s Not configurable 2.5 Information Disclosure 2.5.1 Ensure server_tokens directive is set to off (Scored) OK server_tokens is configured to off by default 2.5.2 Ensure default error and index.html pages do not reference NGINX (Scored) ACTION NEEDED 404 shows no version at all, 503 and 403 show "nginx", which is hardcoded see this line in nginx source code configure custom error pages at least for 403, 404 and 503 and 500 2.5.3 Ensure hidden file serving is disabled (Not Scored) ACTION NEEDED config not set configure a config.server-snippet Snippet, but beware of .well-known challenges or similar. Refer to the benchmark here please 2.5.4 Ensure the NGINX reverse proxy does not enable information disclosure (Scored) ACTION NEEDED hide not configured configure hide-headers with array of "X-Powered-By" and "Server": according to this documentation 3 Logging 3.1 Ensure detailed logging is enabled (Not Scored) OK nginx ingress has a very detailed log format by default 3.2 Ensure access logging is enabled (Scored) OK Access log is enabled by default 3.3 Ensure error logging is enabled and set to the info logging level (Scored) OK Error log is configured by default. The log level does not matter, because it is all sent to STDOUT anyway 3.4 Ensure log files are rotated (Scored) OBSOLETE Log file handling is not part of the nginx ingress and should be handled separately 3.5 Ensure error logs are sent to a remote syslog server (Not Scored) OBSOLETE See previous answer 3.6 Ensure access logs are sent to a remote syslog server (Not Scored) OBSOLETE See previous answer 3.7 Ensure proxies pass source IP information (Scored) OK Headers are set by default 4 Encryption 4.1 TLS / SSL Configuration 4.1.1 Ensure HTTP is redirected to HTTPS (Scored) OK Redirect to TLS is default 4.1.2 Ensure a trusted certificate and trust chain is installed (Not Scored) ACTION NEEDED For installing certs there are enough manuals in the web. A good way is to use lets encrypt through cert-manager Install proper certificates or use lets encrypt with cert-manager 4.1.3 Ensure private key permissions are restricted (Scored) ACTION NEEDED See previous answer 4.1.4 Ensure only modern TLS protocols are used (Scored) OK/ACTION NEEDED Default is TLS 1.2 + 1.3, while this is okay for CIS Benchmark, cipherlist.eu only recommends 1.3. This may cut off old OS's Set controller.config.ssl-protocols to "TLSv1.3" 4.1.5 Disable weak ciphers (Scored) ACTION NEEDED Default ciphers are already good, but cipherlist.eu recommends even stronger ciphers Set controller.config.ssl-ciphers to "EECDH+AESGCM:EDH+AESGCM" 4.1.6 Ensure custom Diffie-Hellman parameters are used (Scored) ACTION NEEDED No custom DH parameters are generated Generate dh parameters for each ingress deployment you use - see here for a how to 4.1.7 Ensure Online Certificate Status Protocol (OCSP) stapling is enabled (Scored) ACTION NEEDED Not enabled set via this configuration parameter 4.1.8 Ensure HTTP Strict Transport Security (HSTS) is enabled (Scored) OK HSTS is enabled by default 4.1.9 Ensure HTTP Public Key Pinning is enabled (Not Scored) ACTION NEEDED / RISK TO BE ACCEPTED HKPK not enabled by default If lets encrypt is not used, set correct HPKP header. There are several ways to implement this - with the helm charts it works via controller.add-headers. If lets encrypt is used, this is complicated, a solution here is yet unknown 4.1.10 Ensure upstream server traffic is authenticated with a client certificate (Scored) DEPENDS ON BACKEND Highly dependent on backends, not every backend allows configuring this, can also be mitigated via a service mesh If backend allows it, manual is here 4.1.11 Ensure the upstream traffic server certificate is trusted (Not Scored) DEPENDS ON BACKEND Highly dependent on backends, not every backend allows configuring this, can also be mitigated via a service mesh If backend allows it, see configuration here 4.1.12 Ensure your domain is preloaded (Not Scored) ACTION NEEDED Preload is not active by default Set controller.config.hsts-preload to true 4.1.13 Ensure session resumption is disabled to enable perfect forward security (Scored) OK Session tickets are disabled by default 4.1.14 Ensure HTTP/2.0 is used (Not Scored) OK http2 is set by default 5 Request Filtering and Restrictions 5.1 Access Control 5.1.1 Ensure allow and deny filters limit access to specific IP addresses (Not Scored) OK/ACTION NEEDED Depends on use case, geo ip module is compiled into Ingress-Nginx Controller, there are several ways to use it If needed set IP restrictions via annotations or work with config snippets (be careful with lets-encrypt-http-challenge!) 5.1.2 Ensure only whitelisted HTTP methods are allowed (Not Scored) OK/ACTION NEEDED Depends on use case If required it can be set via config snippet 5.2 Request Limits 5.2.1 Ensure timeout values for reading the client header and body are set correctly (Scored) ACTION NEEDED Default timeout is 60s Set via this configuration parameter and respective body equivalent 5.2.2 Ensure the maximum request body size is set correctly (Scored) ACTION NEEDED Default is 1m set via this configuration parameter 5.2.3 Ensure the maximum buffer size for URIs is defined (Scored) ACTION NEEDED Default is 4 8k Set via this configuration parameter 5.2.4 Ensure the number of connections per IP address is limited (Not Scored) OK/ACTION NEEDED No limit set Depends on use case, limit can be set via these annotations 5.2.5 Ensure rate limits by IP address are set (Not Scored) OK/ACTION NEEDED No limit set Depends on use case, limit can be set via these annotations 5.3 Browser Security 5.3.1 Ensure X-Frame-Options header is configured and enabled (Scored) ACTION NEEDED Header not set by default Several ways to implement this - with the helm charts it works via controller.add-headers 5.3.2 Ensure X-Content-Type-Options header is configured and enabled (Scored) ACTION NEEDED See previous answer See previous answer 5.3.3 Ensure the X-XSS-Protection Header is enabled and configured properly (Scored) ACTION NEEDED See previous answer See previous answer 5.3.4 Ensure that Content Security Policy (CSP) is enabled and configured properly (Not Scored) ACTION NEEDED See previous answer See previous answer 5.3.5 Ensure the Referrer Policy is enabled and configured properly (Not Scored) ACTION NEEDED Depends on application. It should be handled in the applications webserver itself, not in the load balancing ingress check backend webserver 6 Mandatory Access Control n/a too high level, depends on backends Skip to content NGINX Ingress Controller Installation Guide Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Installation Guide Table of contents Contents Quick start Pre-flight check Local testing Online testing Environment-specific instructions Local development clusters minikube MicroK8s Docker Desktop Rancher Desktop Cloud deployments AWS Network Load Balancer (NLB) TLS termination in AWS Load Balancer (NLB) NLB Idle Timeouts GCE-GKE Azure Digital Ocean Scaleway Exoscale Oracle Cloud Infrastructure OVHcloud Bare metal clusters Miscellaneous Checking ingress controller version Scope Webhook network access Certificate generation Running on Kubernetes versions older than 1.19 Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Contents Quick start Pre-flight check Local testing Online testing Environment-specific instructions Local development clusters minikube MicroK8s Docker Desktop Rancher Desktop Cloud deployments AWS Network Load Balancer (NLB) TLS termination in AWS Load Balancer (NLB) NLB Idle Timeouts GCE-GKE Azure Digital Ocean Scaleway Exoscale Oracle Cloud Infrastructure OVHcloud Bare metal clusters Miscellaneous Checking ingress controller version Scope Webhook network access Certificate generation Running on Kubernetes versions older than 1.19 Installation Guide ¶ There are multiple ways to install the NGINX ingress controller: with Helm, using the project repository chart; with kubectl apply, using YAML manifests; with specific addons (e.g. for minikube or MicroK8s). On most Kubernetes clusters, the ingress controller will work without requiring any extra configuration. If you want to get started as fast as possible, you can check the quick start instructions. However, in many environments, you can improve the performance or get better logs by enabling extra features. We recommend that you check the environment-specific instructions for details about optimizing the ingress controller for your particular environment or cloud provider. Contents ¶ Quick start Environment-specific instructions ... Docker Desktop ... Rancher Desktop ... minikube ... MicroK8s ... AWS ... GCE - GKE ... Azure ... Digital Ocean ... Scaleway ... Exoscale ... Oracle Cloud Infrastructure ... OVHcloud ... Bare-metal Miscellaneous Quick start Environment-specific instructions ... Docker Desktop ... Rancher Desktop ... minikube ... MicroK8s ... AWS ... GCE - GKE ... Azure ... Digital Ocean ... Scaleway ... Exoscale ... Oracle Cloud Infrastructure ... OVHcloud ... Bare-metal Miscellaneous e2e test suite for Ingress NGINX Controller ¶ [Admission] admission controller ¶ reject ingress with global-rate-limit annotations when memcached is not configured should not allow overlaps of host and paths without canary annotations should allow overlaps of host and paths with canary annotation should block ingress with invalid path should return an error if there is an error validating the ingress definition should return an error if there is an invalid value in some annotation should return an error if there is a forbidden value in some annotation should not return an error if the Ingress V1 definition is valid with Ingress Class should not return an error if the Ingress V1 definition is valid with IngressClass annotation should return an error if the Ingress V1 definition contains invalid annotations should not return an error for an invalid Ingress when it has unknown class affinitymode ¶ Balanced affinity mode should balance Check persistent affinity mode server-alias ¶ should return status code 200 for host 'foo' and 404 for 'bar' should return status code 200 for host 'foo' and 'bar' should return status code 200 for hosts defined in two ingresses, different path with one alias app-root ¶ should redirect to /foo auth-tls-* ¶ should set sslClientCertificate, sslVerifyClient and sslVerifyDepth with auth-tls-secret should set valid auth-tls-secret, sslVerify to off, and sslVerifyDepth to 2 should 302 redirect to error page instead of 400 when auth-tls-error-page is set should pass URL-encoded certificate to upstream should validate auth-tls-verify-client should return 403 using auth-tls-match-cn with no matching CN from client should return 200 using auth-tls-match-cn with matching CN from client should return 200 using auth-tls-match-cn where atleast one of the regex options matches CN from client backend-protocol ¶ should set backend protocol to https:// and use proxy_pass should set backend protocol to $scheme:// and use proxy_pass should set backend protocol to grpc:// and use grpc_pass should set backend protocol to grpcs:// and use grpc_pass should set backend protocol to '' and use fastcgi_pass should set backend protocol to '' and use ajp_pass client-body-buffer-size ¶ should set client_body_buffer_size to 1000 should set client_body_buffer_size to 1K should set client_body_buffer_size to 1k should set client_body_buffer_size to 1m should set client_body_buffer_size to 1M should not set client_body_buffer_size to invalid 1b connection-proxy-header ¶ set connection header to keep-alive cors-* ¶ should enable cors should set cors methods to only allow POST, GET should set cors max-age should disable cors allow credentials should allow origin for cors should allow headers for cors should expose headers for cors should allow - single origin for multiple cors values should not allow - single origin for multiple cors values should allow correct origins - single origin for multiple cors values should not break functionality should not break functionality with extra domain should not match should allow - single origin with required port should not allow - single origin with port and origin without port should not allow - single origin without port and origin with required port should allow - matching origin with wildcard origin (2 subdomains) should not allow - unmatching origin with wildcard origin (2 subdomains) should allow - matching origin+port with wildcard origin should not allow - portless origin with wildcard origin should allow correct origins - missing subdomain + origin with wildcard origin and correct origin should allow - missing origins (should allow all origins) custom-http-errors ¶ configures Nginx correctly default-backend ¶ should use a custom default backend as upstream disable-access-log disable-http-access-log disable-stream-access-log ¶ disable-access-log set access_log off disable-http-access-log set access_log off disable-stream-access-log set access_log off force-ssl-redirect ¶ should redirect to https from-to-www-redirect ¶ should redirect from www HTTP to HTTP should redirect from www HTTPS to HTTPS annotation-global-rate-limit ¶ generates correct configuration backend-protocol - GRPC ¶ should use grpc_pass in the configuration file should return OK for service with backend protocol GRPC authorization metadata should be overwritten by external auth response headers should return OK for service with backend protocol GRPCS http2-push-preload ¶ enable the http2-push-preload directive whitelist-source-range ¶ should set valid ip whitelist range Annotation - limit-connections ¶ should limit-connections limit-rate ¶ Check limit-rate annotation enable-access-log enable-rewrite-log ¶ set access_log off set rewrite_log on mirror-* ¶ should set mirror-target to http://localhost/mirror should set mirror-target to https://test.env.com/$request_uri should disable mirror-request-body modsecurity owasp ¶ should enable modsecurity should enable modsecurity with transaction ID and OWASP rules should disable modsecurity should enable modsecurity with snippet should enable modsecurity without using 'modsecurity on;' should disable modsecurity using 'modsecurity off;' should enable modsecurity with snippet and block requests should enable modsecurity globally and with modsecurity-snippet block requests should enable modsecurity when enable-owasp-modsecurity-crs is set to true should enable modsecurity through the config map should enable modsecurity through the config map but ignore snippet as disabled by admin should disable default modsecurity conf setting when modsecurity-snippet is specified preserve-trailing-slash ¶ should allow preservation of trailing slashes proxy-* ¶ should set proxy_redirect to off should set proxy_redirect to default should set proxy_redirect to hello.com goodbye.com should set proxy client-max-body-size to 8m should not set proxy client-max-body-size to incorrect value should set valid proxy timeouts should not set invalid proxy timeouts should turn on proxy-buffering should turn off proxy-request-buffering should build proxy next upstream should setup proxy cookies should change the default proxy HTTP version proxy-ssl-* ¶ should set valid proxy-ssl-secret should set valid proxy-ssl-secret, proxy-ssl-verify to on, proxy-ssl-verify-depth to 2, and proxy-ssl-server-name to on should set valid proxy-ssl-secret, proxy-ssl-ciphers to HIGH:!AES should set valid proxy-ssl-secret, proxy-ssl-protocols proxy-ssl-location-only flag should change the nginx config server part permanent-redirect permanent-redirect-code ¶ should respond with a standard redirect code should respond with a custom redirect code satisfy ¶ should configure satisfy directive correctly should allow multiple auth with satisfy any server-snippet ¶ add valid directives to server via server snippet drops server snippet if disabled by the administrator service-upstream ¶ should use the Service Cluster IP and Port should use the Service Cluster IP and Port should not use the Service Cluster IP and Port configuration-snippet ¶ ssl-ciphers ¶ should change ssl ciphers stream-snippet ¶ should add value of stream-snippet to nginx config should add stream-snippet and drop annotations per admin config upstream-hash-by-* ¶ should connect to the same pod should connect to the same subset of pods upstream-vhost ¶ set host to upstreamvhost.bar.com x-forwarded-prefix ¶ should set the X-Forwarded-Prefix to the annotation value should not add X-Forwarded-Prefix if the annotation value is empty denylist-source-range ¶ only deny explicitly denied IPs, allow all others only allow explicitly allowed IPs, deny all others affinity session-cookie-name ¶ should set sticky cookie SERVERID should change cookie name on ingress definition change should set the path to /something on the generated cookie does not set the path to / on the generated cookie if there's more than one rule referring to the same backend should set cookie with expires should set cookie with domain should not set cookie without domain annotation should work with use-regex annotation and session-cookie-path should warn user when use-regex is true and session-cookie-path is not set should not set affinity across all server locations when using separate ingresses should set sticky cookie without host should work with server-alias annotation should set secure in cookie with provided true annotation on http should not set secure in cookie with provided false annotation on http should set secure in cookie with provided false annotation on https rewrite-target use-regex enable-rewrite-log ¶ should write rewrite logs should use correct longest path match should use ~* location modifier if regex annotation is present should fail to use longest match for documented warning should allow for custom rewrite parameters backend-protocol - FastCGI ¶ should use fastcgi_pass in the configuration file should add fastcgi_index in the configuration file should add fastcgi_param in the configuration file should return OK for service with backend protocol FastCGI auth-* ¶ should return status code 200 when no authentication is configured should return status code 503 when authentication is configured with an invalid secret should return status code 401 when authentication is configured but Authorization header is not configured should return status code 401 when authentication is configured and Authorization header is sent with invalid credentials should return status code 401 and cors headers when authentication and cors is configured but Authorization header is not configured should return status code 200 when authentication is configured and Authorization header is sent should return status code 200 when authentication is configured with a map and Authorization header is sent should return status code 401 when authentication is configured with invalid content and Authorization header is sent when external auth is configured when external auth is not configured when auth-headers are set should set cache_key when external auth cache is configured user retains cookie by default user does not retain cookie if upstream returns error status code user with annotated ingress retains cookie if upstream returns error status code should return status code 200 when signed in should redirect to signin url when not signed in keeps processing new ingresses even if one of the existing ingresses is misconfigured should overwrite Foo header with auth response should not create additional upstream block when auth-keepalive is not set should not create additional upstream block when host part of auth-url contains a variable should not create additional upstream block when auth-keepalive is negative should not create additional upstream block when auth-keepalive is set with HTTP/2 should create additional upstream block when auth-keepalive is set with HTTP/1.x should return status code 200 when signed in should redirect to signin url when not signed in keeps processing new ingresses even if one of the existing ingresses is misconfigured should return status code 200 when signed in after auth backend is deleted should deny login for different location on same server should deny login for different servers should redirect to signin url when not signed in should return 503 (location was denied) should add error to the config canary-* ¶ should response with a 200 status from the mainline upstream when requests are made to the mainline ingress should return 404 status for requests to the canary if no matching ingress is found should return the correct status codes when endpoints are unavailable should route requests to the correct upstream if mainline ingress is created before the canary ingress should route requests to the correct upstream if mainline ingress is created after the canary ingress should route requests to the correct upstream if the mainline ingress is modified should route requests to the correct upstream if the canary ingress is modified should route requests to the correct upstream should route requests to the correct upstream should route requests to the correct upstream should route requests to the correct upstream should routes to mainline upstream when the given Regex causes error should route requests to the correct upstream respects always and never values should route requests only to mainline if canary weight is 0 should route requests only to canary if canary weight is 100 should route requests only to canary if canary weight is equal to canary weight total should route requests split between mainline and canary if canary weight is 50 should route requests split between mainline and canary if canary weight is 100 and weight total is 200 should not use canary as a catch-all server should not use canary with domain as a server does not crash when canary ingress has multiple paths to the same non-matching backend always routes traffic to canary if first request was affinitized to canary (default behavior) always routes traffic to canary if first request was affinitized to canary (explicit sticky behavior) routes traffic to either mainline or canary backend (legacy behavior) Debug CLI ¶ should list the backend servers should get information for a specific backend server should produce valid JSON for /dbg general [Default Backend] custom service ¶ uses custom default backend that returns 200 as status code [Default Backend] ¶ should return 404 sending requests when only a default backend is running enables access logging for default backend disables access logging for default backend [Default Backend] SSL ¶ should return a self generated SSL certificate [Default Backend] change default settings ¶ should apply the annotation to the default backend ¶ [Endpointslices] long service name ¶ should return 200 when service name has max allowed number of characters 63 [TopologyHints] topology aware routing ¶ should return 200 when service has topology hints ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ [Setting] ¶ ¶ ¶ ¶ ¶ ¶ ¶ [Shutdown] Grace period shutdown ¶ /healthz should return status code 500 during shutdown grace period [Shutdown] ingress controller ¶ should shutdown in less than 60 secons without pending connections should shutdown after waiting 60 seconds for pending connections to be closed should shutdown after waiting 150 seconds for pending connections to be closed [Shutdown] Graceful shutdown with pending request ¶ should let slow requests finish before shutting down [Ingress] DeepInspection ¶ should drop whole ingress if one path matches invalid regex single ingress - multiple hosts ¶ should set the correct $service_name NGINX variable [Ingress] [PathType] exact ¶ should choose exact location for /exact [Ingress] [PathType] mix Exact and Prefix paths ¶ should choose the correct location [Ingress] [PathType] prefix checks ¶ should return 404 when prefix /aaa does not match request /aaaccc [Ingress] definition without host ¶ should set ingress details variables for ingresses without a host should set ingress details variables for ingresses with host without IngressRuleValue, only Backend [Memory Leak] Dynamic Certificates ¶ should not leak memory from ingress SSL certificates or configuration updates [Load Balancer] load-balance ¶ should apply the configmap load-balance setting [Load Balancer] EWMA ¶ does not fail requests [Load Balancer] round-robin ¶ should evenly distribute requests with round-robin (default algorithm) [Lua] dynamic certificates ¶ picks up the certificate when we add TLS spec to existing ingress picks up the previously missing secret for a given ingress without reloading supports requests with domain with trailing dot picks up the updated certificate without reloading falls back to using default certificate when secret gets deleted without reloading picks up a non-certificate only change removes HTTPS configuration when we delete TLS spec [Lua] dynamic configuration ¶ configures balancer Lua middleware correctly handles endpoints only changes handles endpoints only changes (down scaling of replicas) handles endpoints only changes consistently (down scaling of replicas vs. empty service) handles an annotation change nginx-configuration ¶ start nginx with default configuration fails when using alias directive fails when using root directive [Security] request smuggling ¶ should not return body content from error_page [Service] backend status code 503 ¶ should return 503 when backend service does not exist should return 503 when all backend service endpoints are unavailable [Service] Type ExternalName ¶ works with external name set to incomplete fqdn should return 200 for service type=ExternalName without a port defined should return 200 for service type=ExternalName with a port defined should return status 502 for service type=ExternalName with an invalid host should return 200 for service type=ExternalName using a port name should return 200 for service type=ExternalName using FQDN with trailing dot should update the external name after a service update should sync ingress on external name service addition/deletion [Service] Nil Service Backend ¶ should return 404 when backend service is nil access-log ¶ use the default configuration use the specified configuration use the specified configuration use the specified configuration use the specified configuration Bad annotation values ¶ [BAD_ANNOTATIONS] should drop an ingress if there is an invalid character in some annotation [BAD_ANNOTATIONS] should drop an ingress if there is a forbidden word in some annotation [BAD_ANNOTATIONS] should allow an ingress if there is a default blocklist config in place [BAD_ANNOTATIONS] should drop an ingress if there is a custom blocklist config in place and allow others to pass brotli ¶ condition add-headers ¶ Add a custom header Add multiple custom headers [SSL] [Flag] default-ssl-certificate ¶ uses default ssl certificate for catch-all ingress uses default ssl certificate for host based ingress when configured certificate does not match host [Flag] disable-catch-all ¶ should ignore catch all Ingress with backend should ignore catch all Ingress with backend and rules should delete Ingress updated to catch-all should allow Ingress with rules [Flag] disable-service-external-name ¶ should ignore services of external-name type enable-real-ip ¶ trusts X-Forwarded-For header only when setting is true should not trust X-Forwarded-For header when setting is false use-forwarded-headers ¶ should trust X-Forwarded headers when setting is true should not trust X-Forwarded headers when setting is false Geoip2 ¶ should include geoip2 line in config when enabled and db file exists should only allow requests from specific countries [Security] block-* ¶ should block CIDRs defined in the ConfigMap should block User-Agents defined in the ConfigMap should block Referers defined in the ConfigMap [Security] global-auth-url ¶ should return status code 401 when request any protected service should return status code 200 when request whitelisted (via no-auth-locations) service and 401 when request protected service should return status code 200 when request whitelisted (via ingress annotation) service and 401 when request protected service should still return status code 200 after auth backend is deleted using cache should proxy_method method when global-auth-method is configured should add custom error page when global-auth-signin url is configured should add auth headers when global-auth-response-headers is configured should set request-redirect when global-auth-request-redirect is configured should set snippet when global external auth is configured user retains cookie by default user does not retain cookie if upstream returns error status code user with global-auth-always-set-cookie key in configmap retains cookie if upstream returns error status code global-options ¶ should have worker_rlimit_nofile option should have worker_rlimit_nofile option and be independent on amount of worker processes settings-global-rate-limit ¶ generates correct NGINX configuration hash size ¶ should set server_names_hash_bucket_size should set server_names_hash_max_size should set proxy-headers-hash-bucket-size should set proxy-headers-hash-max-size should set variables-hash-bucket-size should set variables-hash-max-size should set vmap-hash-bucket-size [Flag] ingress-class ¶ should ignore Ingress with a different class annotation should ignore Ingress with different controller class should accept both Ingresses with default IngressClassName and IngressClass annotation should ignore Ingress without IngressClass configuration should delete Ingress when class is removed should serve Ingress when class is added should serve Ingress when class is updated between annotation and ingressClassName should ignore Ingress with no class and accept the correctly configured Ingresses should watch Ingress with no class and ignore ingress with a different class should watch Ingress that uses the class name even if spec is different should watch Ingress with correct annotation should ignore Ingress with only IngressClassName keep-alive keep-alive-requests ¶ should set keepalive_timeout should set keepalive_requests should set keepalive connection to upstream server should set keep alive connection timeout to upstream server should set keepalive time to upstream server should set the request count to upstream server through one keep alive connection Configmap - limit-rate ¶ Check limit-rate config [Flag] custom HTTP and HTTPS ports ¶ should set X-Forwarded-Port headers accordingly when listening on a non-default HTTP port should set X-Forwarded-Port header to 443 should set the X-Forwarded-Port header to 443 log-format-* ¶ should not configure log-format escape by default should enable the log-format-escape-json should disable the log-format-escape-json should enable the log-format-escape-none should disable the log-format-escape-none log-format-escape-json enabled log-format default escape log-format-escape-none enabled [Lua] lua-shared-dicts ¶ configures lua shared dicts main-snippet ¶ should add value of main-snippet setting to nginx config [Security] modsecurity-snippet ¶ should add value of modsecurity-snippet setting to nginx config enable-multi-accept ¶ should be enabled by default should be enabled when set to true should be disabled when set to false Add no tls redirect locations ¶ Check no tls redirect locations config OCSP ¶ should enable OCSP and contain stapling information in the connection Configure OpenTracing ¶ should not exists opentracing directive should exists opentracing directive when is enabled should include opentracing_trust_incoming_span off directive when disabled should not exists opentracing_operation_name directive when is empty should exists opentracing_operation_name directive when is configured should not exists opentracing_location_operation_name directive when is empty should exists opentracing_location_operation_name directive when is configured should enable opentracing using zipkin should enable opentracing using jaeger should enable opentracing using jaeger with sampler host should propagate the w3c header when configured with jaeger should enable opentracing using jaeger with an HTTP endpoint should enable opentracing using datadog plugins ¶ should exist a x-hello-world header [Security] Pod Security Policies ¶ should be running with a Pod Security Policy [Security] Pod Security Policies with volumes ¶ should be running with a Pod Security Policy proxy-connect-timeout ¶ should set valid proxy timeouts using configmap values should not set invalid proxy timeouts using configmap values Dynamic $proxy_host ¶ should exist a proxy_host should exist a proxy_host using the upstream-vhost annotation value proxy-next-upstream ¶ should build proxy next upstream using configmap values use-proxy-protocol ¶ should respect port passed by the PROXY Protocol should respect proto passed by the PROXY Protocol server port should enable PROXY Protocol for HTTPS should enable PROXY Protocol for TCP proxy-read-timeout ¶ should set valid proxy read timeouts using configmap values should not set invalid proxy read timeouts using configmap values proxy-send-timeout ¶ should set valid proxy send timeouts using configmap values should not set invalid proxy send timeouts using configmap values reuse-port ¶ reuse port should be enabled by default reuse port should be disabled reuse port should be enabled configmap server-snippet ¶ should add value of server-snippet setting to all ingress config should add global server-snippet and drop annotations per admin config server-tokens ¶ should not exists Server header in the response should exists Server header in the response when is enabled ssl-ciphers ¶ Add ssl ciphers configmap stream-snippet ¶ should add value of stream-snippet via config map to nginx config [SSL] TLS protocols, ciphers and headers) ¶ setting cipher suite setting max-age parameter setting includeSubDomains parameter setting preload parameter overriding what's set from the upstream should not use ports during the HTTP to HTTPS redirection should not use ports or X-Forwarded-Host during the HTTP to HTTPS redirection [Flag] disable-sync-events ¶ should create sync events (default) should create sync events should not create sync events gzip ¶ should be disabled by default should be enabled with default settings should set gzip_comp_level to 4 should set gzip_disable to msie6 should set gzip_min_length to 100 should set gzip_types to application/javascript Configmap change ¶ should reload after an update in the configuration [Flag] watch namespace selector ¶ should ingore Ingress of namespace without label foo=bar and accept those of namespace with label foo=bar With enable-ssl-passthrough enabled ¶ should enable ssl-passthrough-proxy-port on a different port should pass unknown traffic to default backend and handle known traffic [Security] no-auth-locations ¶ should return status code 401 when accessing '/' unauthentication should return status code 200 when accessing '/' authentication should return status code 200 when accessing '/noauth' unauthenticated Configure Opentelemetry ¶ should not exists opentelemetry directive should exists opentelemetry directive when is enabled should include opentelemetry_trust_incoming_spans on directive when enabled should not exists opentelemetry_operation_name directive when is empty should exists opentelemetry_operation_name directive when is configured [SSL] redirect to HTTPS ¶ should redirect from HTTP to HTTPS when secret is missing [SSL] secret update ¶ should not appear references to secret updates not used in ingress rules should return the fake SSL certificate if the secret is invalid [Status] status update ¶ should update status field after client-go reconnection [TCP] tcp-services ¶ should expose a TCP service should expose an ExternalName TCP service should reload after an update in the configuration ¶ [metrics] exported prometheus metrics ¶ exclude socket request metrics are absent exclude socket request metrics are present Skip to content NGINX Ingress Controller Remove static SSL configuration mode Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation Details/Notes/Constraints Drawbacks Alternatives Remove static SSL configuration mode ¶ Table of Contents ¶ Summary Motivation Goals Non-Goals Proposal Implementation Details/Notes/Constraints Drawbacks Alternatives Summary ¶ Since release 0.19.0 is possible to configure SSL certificates without the need of NGINX reloads (thanks to lua) and after release 0.24.0 the default enabled mode is dynamic. Motivation ¶ The static configuration implies reloads, something that affects the majority of the users. Goals ¶ Deprecation of the flag --enable-dynamic-certificates. Cleanup of the codebase. Non-Goals ¶ Features related to certificate authentication are not changed in any way. Proposal ¶ Remove static SSL configuration Implementation Details/Notes/Constraints ¶ Deprecate the flag Move the directives ssl_certificate and ssl_certificate_key from each server block to the http section. These settings are required to avoid NGINX errors in the logs. Remove any action of the flag --enable-dynamic-certificates Drawbacks ¶ Alternatives ¶ Keep both implementations Skip to content Ingress-Nginx Controller Remove static SSL configuration mode Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation Details/Notes/Constraints Drawbacks Alternatives Remove static SSL configuration mode ¶ Table of Contents ¶ Summary Motivation Goals Non-Goals Proposal Implementation Details/Notes/Constraints Drawbacks Alternatives Summary ¶ Since release 0.19.0 is possible to configure SSL certificates without the need of NGINX reloads (thanks to lua) and after release 0.24.0 the default enabled mode is dynamic. Motivation ¶ The static configuration implies reloads, something that affects the majority of the users. Goals ¶ Deprecation of the flag --enable-dynamic-certificates. Cleanup of the codebase. Non-Goals ¶ Features related to certificate authentication are not changed in any way. Proposal ¶ Remove static SSL configuration Implementation Details/Notes/Constraints ¶ Deprecate the flag Move the directives ssl_certificate and ssl_certificate_key from each server block to the http section. These settings are required to avoid NGINX errors in the logs. Remove any action of the flag --enable-dynamic-certificates Drawbacks ¶ Alternatives ¶ Keep both implementations Skip to content NGINX Ingress Controller Availability zone aware routing Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation History Drawbacks [optional] Availability zone aware routing ¶ Table of Contents ¶ Availability zone aware routing Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation History Drawbacks [optional] Summary ¶ Teach ingress-nginx about availability zones where endpoints are running in. This way ingress-nginx pod will do its best to proxy to zone-local endpoint. Motivation ¶ When users run their services across multiple availability zones they usually pay for egress traffic between zones. Providers such as GCP, and Amazon EC2 usually charge extra for this feature. ingress-nginx when picking an endpoint to route request to does not consider whether the endpoint is in a different zone or the same one. That means it's at least equally likely that it will pick an endpoint from another zone and proxy the request to it. In this situation response from the endpoint to the ingress-nginx pod is considered inter-zone traffic and usually costs extra money. At the time of this writing, GCP charges $0.01 per GB of inter-zone egress traffic according to https://cloud.google.com/compute/network-pricing. According to https://datapath.io/resources/blog/what-are-aws-data-transfer-costs-and-how-to-minimize-them/ Amazon also charges the same amount of money as GCP for cross-zone, egress traffic. This can be a lot of money depending on once's traffic. By teaching ingress-nginx about zones we can eliminate or at least decrease this cost. Arguably inter-zone network latency should also be better than cross-zone. Goals ¶ Given a regional cluster running ingress-nginx, ingress-nginx should do best-effort to pick a zone-local endpoint when proxying This should not impact canary feature ingress-nginx should be able to operate successfully if there are no zonal endpoints Non-Goals ¶ This feature inherently assumes that endpoints are distributed across zones in a way that they can handle all the traffic from ingress-nginx pod(s) in that zone This feature will be relying on https://kubernetes.io/docs/reference/kubernetes-api/labels-annotations-taints/#failure-domainbetakubernetesiozone, it is not this KEP's goal to support other cases Proposal ¶ The idea here is to have the controller part of ingress-nginx (1) detect what zone its current pod is running in and (2) detect the zone for every endpoint it knows about. After that, it will post that data as part of endpoints to Lua land. When picking an endpoint, the Lua balancer will try to pick zone-local endpoint first and if there is no zone-local endpoint then it will fall back to current behavior. Initially, this feature should be optional since it is going to make it harder to reason about the load balancing and not everyone might want that. How does controller know what zone it runs in? We can have the pod spec pass the node name using downward API as an environment variable. Upon startup, the controller can get node details from the API based on the node name. Once the node details are obtained we can extract the zone from the failure-domain.beta.kubernetes.io/zone annotation. Then we can pass that value to Lua land through Nginx configuration when loading lua_ingress.lua module in init_by_lua phase. How do we extract zones for endpoints? We can have the controller watch create and update events on nodes in the entire cluster and based on that keep the map of nodes to zones in the memory. And when we generate endpoints list, we can access node name using .subsets.addresses[i].nodeName and based on that fetch zone from the map in memory and store it as a field on the endpoint. This solution assumes failure-domain.beta.kubernetes.io/zone annotation does not change until the end of the node's life. Otherwise, we have to watch update events as well on the nodes and that'll add even more overhead. Alternatively, we can get the list of nodes only when there's no node in the memory for the given node name. This is probably a better solution because then we would avoid watching for API changes on node resources. We can eagerly fetch all the nodes and build node name to zone mapping on start. From there on, it will sync during endpoint building in the main event loop if there's no existing entry for the node of an endpoint. This means an extra API call in case cluster has expanded. How do we make sure we do our best to choose zone-local endpoint? This will be done on the Lua side. For every backend, we will initialize two balancer instances: (1) with all endpoints (2) with all endpoints corresponding to the current zone for the backend. Then given the request once we choose what backend needs to serve the request, we will first try to use a zonal balancer for that backend. If a zonal balancer does not exist (i.e. there's no zonal endpoint) then we will use a general balancer. In case of zonal outages, we assume that the readiness probe will fail and the controller will see no endpoints for the backend and therefore we will use a general balancer. We can enable the feature using a configmap setting. Doing it this way makes it easier to rollback in case of a problem. Implementation History ¶ initial version of KEP is shipped proposal and implementation details are done Drawbacks [optional] ¶ More load on the Kubernetes API server. Skip to content Ingress-Nginx Controller Availability zone aware routing Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation History Drawbacks [optional] Availability zone aware routing ¶ Table of Contents ¶ Availability zone aware routing Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation History Drawbacks [optional] Summary ¶ Teach ingress-nginx about availability zones where endpoints are running in. This way ingress-nginx pod will do its best to proxy to zone-local endpoint. Motivation ¶ When users run their services across multiple availability zones they usually pay for egress traffic between zones. Providers such as GCP, and Amazon EC2 usually charge extra for this feature. ingress-nginx when picking an endpoint to route request to does not consider whether the endpoint is in a different zone or the same one. That means it's at least equally likely that it will pick an endpoint from another zone and proxy the request to it. In this situation response from the endpoint to the ingress-nginx pod is considered inter-zone traffic and usually costs extra money. At the time of this writing, GCP charges $0.01 per GB of inter-zone egress traffic according to https://cloud.google.com/compute/network-pricing. According to https://datapath.io/resources/blog/what-are-aws-data-transfer-costs-and-how-to-minimize-them/ Amazon also charges the same amount of money as GCP for cross-zone, egress traffic. This can be a lot of money depending on once's traffic. By teaching ingress-nginx about zones we can eliminate or at least decrease this cost. Arguably inter-zone network latency should also be better than cross-zone. Goals ¶ Given a regional cluster running ingress-nginx, ingress-nginx should do best-effort to pick a zone-local endpoint when proxying This should not impact canary feature ingress-nginx should be able to operate successfully if there are no zonal endpoints Non-Goals ¶ This feature inherently assumes that endpoints are distributed across zones in a way that they can handle all the traffic from ingress-nginx pod(s) in that zone This feature will be relying on https://kubernetes.io/docs/reference/kubernetes-api/labels-annotations-taints/#failure-domainbetakubernetesiozone, it is not this KEP's goal to support other cases Proposal ¶ The idea here is to have the controller part of ingress-nginx (1) detect what zone its current pod is running in and (2) detect the zone for every endpoint it knows about. After that, it will post that data as part of endpoints to Lua land. When picking an endpoint, the Lua balancer will try to pick zone-local endpoint first and if there is no zone-local endpoint then it will fall back to current behavior. Initially, this feature should be optional since it is going to make it harder to reason about the load balancing and not everyone might want that. How does controller know what zone it runs in? We can have the pod spec pass the node name using downward API as an environment variable. Upon startup, the controller can get node details from the API based on the node name. Once the node details are obtained we can extract the zone from the failure-domain.beta.kubernetes.io/zone annotation. Then we can pass that value to Lua land through Nginx configuration when loading lua_ingress.lua module in init_by_lua phase. How do we extract zones for endpoints? We can have the controller watch create and update events on nodes in the entire cluster and based on that keep the map of nodes to zones in the memory. And when we generate endpoints list, we can access node name using .subsets.addresses[i].nodeName and based on that fetch zone from the map in memory and store it as a field on the endpoint. This solution assumes failure-domain.beta.kubernetes.io/zone annotation does not change until the end of the node's life. Otherwise, we have to watch update events as well on the nodes and that'll add even more overhead. Alternatively, we can get the list of nodes only when there's no node in the memory for the given node name. This is probably a better solution because then we would avoid watching for API changes on node resources. We can eagerly fetch all the nodes and build node name to zone mapping on start. From there on, it will sync during endpoint building in the main event loop if there's no existing entry for the node of an endpoint. This means an extra API call in case cluster has expanded. How do we make sure we do our best to choose zone-local endpoint? This will be done on the Lua side. For every backend, we will initialize two balancer instances: (1) with all endpoints (2) with all endpoints corresponding to the current zone for the backend. Then given the request once we choose what backend needs to serve the request, we will first try to use a zonal balancer for that backend. If a zonal balancer does not exist (i.e. there's no zonal endpoint) then we will use a general balancer. In case of zonal outages, we assume that the readiness probe will fail and the controller will see no endpoints for the backend and therefore we will use a general balancer. We can enable the feature using a configmap setting. Doing it this way makes it easier to rollback in case of a problem. Implementation History ¶ initial version of KEP is shipped proposal and implementation details are done Drawbacks [optional] ¶ More load on the Kubernetes API server. Skip to content NGINX Ingress Controller KEP Template Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Table of Contents Summary Motivation Goals Non-Goals Proposal User Stories [optional] Story 1 Story 2 Implementation Details/Notes/Constraints [optional] Risks and Mitigations Design Details Test Plan Removing a deprecated flag Implementation History Drawbacks [optional] Alternatives [optional] Title ¶ This is the title of the KEP. Keep it simple and descriptive. A good title can help communicate what the KEP is and should be considered as part of any review. The title should be lowercased and spaces/punctuation should be replaced with -. To get started with this template: Make a copy of this template. Create a copy of this template and name it YYYYMMDD-my-title.md, where YYYYMMDD is the date the KEP was first drafted. Fill out the "overview" sections. This includes the Summary and Motivation sections. These should be easy if you've preflighted the idea of the KEP in an issue. Create a PR. Assign it to folks that are sponsoring this process. Create an issue When filing an enhancement tracking issue, please ensure to complete all fields in the template. Merge early. Avoid getting hung up on specific details and instead aim to get the goal of the KEP merged quickly. The best way to do this is to just start with the "Overview" sections and fill out details incrementally in follow on PRs. View anything marked as a provisional as a working document and subject to change. Aim for single topic PRs to keep discussions focused. If you disagree with what is already in a document, open a new PR with suggested changes. The canonical place for the latest set of instructions (and the likely source of this file) is here. The Metadata section above is intended to support the creation of tooling around the KEP process. This will be a YAML section that is fenced as a code block. See the KEP process for details on each of these items. Table of Contents ¶ A table of contents is helpful for quickly jumping to sections of a KEP and for highlighting any additional information provided beyond the standard KEP template. Ensure the TOC is wrapped with <!-- toc --&rt;<!-- /toc --&rt; tags, and then generate with hack/update-toc.sh. Summary Motivation Goals Non-Goals Proposal User Stories [optional] Story 1 Story 2 Implementation Details/Notes/Constraints [optional] Risks and Mitigations Design Details Test Plan Removing a deprecated flag Implementation History Drawbacks [optional] Alternatives [optional] Summary ¶ The Summary section is incredibly important for producing high quality user-focused documentation such as release notes or a development roadmap. It should be possible to collect this information before implementation begins in order to avoid requiring implementers to split their attention between writing release notes and implementing the feature itself. A good summary is probably at least a paragraph in length. Motivation ¶ This section is for explicitly listing the motivation, goals and non-goals of this KEP. Describe why the change is important and the benefits to users. The motivation section can optionally provide links to experience reports to demonstrate the interest in a KEP within the wider Kubernetes community. Goals ¶ List the specific goals of the KEP. How will we know that this has succeeded? Non-Goals ¶ What is out of scope for this KEP? Listing non-goals helps to focus discussion and make progress. Proposal ¶ This is where we get down to the nitty gritty of what the proposal actually is. User Stories [optional] ¶ Detail the things that people will be able to do if this KEP is implemented. Include as much detail as possible so that people can understand the "how" of the system. The goal here is to make this feel real for users without getting bogged down. Story 1 ¶ Story 2 ¶ Implementation Details/Notes/Constraints [optional] ¶ What are the caveats to the implementation? What are some important details that didn't come across above. Go in to as much detail as necessary here. This might be a good place to talk about core concepts and how they relate. Risks and Mitigations ¶ What are the risks of this proposal and how do we mitigate. Think broadly. For example, consider both security and how this will impact the larger kubernetes ecosystem. How will security be reviewed and by whom? How will UX be reviewed and by whom? Consider including folks that also work outside project. Design Details ¶ Test Plan ¶ Note: Section not required until targeted at a release. Consider the following in developing a test plan for this enhancement: Will there be e2e and integration tests, in addition to unit tests? How will it be tested in isolation vs with other components? No need to outline all of the test cases, just the general strategy. Anything that would count as tricky in the implementation and anything particularly challenging to test should be called out. All code is expected to have adequate tests (eventually with coverage expectations). Please adhere to the Kubernetes testing guidelines when drafting this test plan. Removing a deprecated flag ¶ Announce deprecation and support policy of the existing flag Two versions passed since introducing the functionality which deprecates the flag (to address version skew) Address feedback on usage/changed behavior, provided on GitHub issues Deprecate the flag Implementation History ¶ Major milestones in the life cycle of a KEP should be tracked in Implementation History. Major milestones might include the Summary and Motivation sections being merged signaling acceptance the Proposal section being merged signaling agreement on a proposed design the date implementation started the first Kubernetes release where an initial version of the KEP was available the version of Kubernetes where the KEP graduated to general availability when the KEP was retired or superseded Drawbacks [optional] ¶ Why should this KEP not be implemented. Alternatives [optional] ¶ Similar to the Drawbacks section the Alternatives section is used to highlight and record other possible approaches to delivering the value proposed by a KEP. Skip to content Ingress-Nginx Controller KEP Template Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Table of Contents Summary Motivation Goals Non-Goals Proposal User Stories [optional] Story 1 Story 2 Implementation Details/Notes/Constraints [optional] Risks and Mitigations Design Details Test Plan Removing a deprecated flag Implementation History Drawbacks [optional] Alternatives [optional] Title ¶ This is the title of the KEP. Keep it simple and descriptive. A good title can help communicate what the KEP is and should be considered as part of any review. The title should be lowercased and spaces/punctuation should be replaced with -. To get started with this template: Make a copy of this template. Create a copy of this template and name it YYYYMMDD-my-title.md, where YYYYMMDD is the date the KEP was first drafted. Fill out the "overview" sections. This includes the Summary and Motivation sections. These should be easy if you've preflighted the idea of the KEP in an issue. Create a PR. Assign it to folks that are sponsoring this process. Create an issue When filing an enhancement tracking issue, please ensure to complete all fields in the template. Merge early. Avoid getting hung up on specific details and instead aim to get the goal of the KEP merged quickly. The best way to do this is to just start with the "Overview" sections and fill out details incrementally in follow on PRs. View anything marked as a provisional as a working document and subject to change. Aim for single topic PRs to keep discussions focused. If you disagree with what is already in a document, open a new PR with suggested changes. The canonical place for the latest set of instructions (and the likely source of this file) is here. The Metadata section above is intended to support the creation of tooling around the KEP process. This will be a YAML section that is fenced as a code block. See the KEP process for details on each of these items. Table of Contents ¶ A table of contents is helpful for quickly jumping to sections of a KEP and for highlighting any additional information provided beyond the standard KEP template. Ensure the TOC is wrapped with <!-- toc --&rt;<!-- /toc --&rt; tags, and then generate with hack/update-toc.sh. Summary Motivation Goals Non-Goals Proposal User Stories [optional] Story 1 Story 2 Implementation Details/Notes/Constraints [optional] Risks and Mitigations Design Details Test Plan Removing a deprecated flag Implementation History Drawbacks [optional] Alternatives [optional] Summary ¶ The Summary section is incredibly important for producing high quality user-focused documentation such as release notes or a development roadmap. It should be possible to collect this information before implementation begins in order to avoid requiring implementers to split their attention between writing release notes and implementing the feature itself. A good summary is probably at least a paragraph in length. Motivation ¶ This section is for explicitly listing the motivation, goals and non-goals of this KEP. Describe why the change is important and the benefits to users. The motivation section can optionally provide links to experience reports to demonstrate the interest in a KEP within the wider Kubernetes community. Goals ¶ List the specific goals of the KEP. How will we know that this has succeeded? Non-Goals ¶ What is out of scope for this KEP? Listing non-goals helps to focus discussion and make progress. Proposal ¶ This is where we get down to the nitty gritty of what the proposal actually is. User Stories [optional] ¶ Detail the things that people will be able to do if this KEP is implemented. Include as much detail as possible so that people can understand the "how" of the system. The goal here is to make this feel real for users without getting bogged down. Story 1 ¶ Story 2 ¶ Implementation Details/Notes/Constraints [optional] ¶ What are the caveats to the implementation? What are some important details that didn't come across above. Go in to as much detail as necessary here. This might be a good place to talk about core concepts and how they relate. Risks and Mitigations ¶ What are the risks of this proposal and how do we mitigate. Think broadly. For example, consider both security and how this will impact the larger kubernetes ecosystem. How will security be reviewed and by whom? How will UX be reviewed and by whom? Consider including folks that also work outside project. Design Details ¶ Test Plan ¶ Note: Section not required until targeted at a release. Consider the following in developing a test plan for this enhancement: Will there be e2e and integration tests, in addition to unit tests? How will it be tested in isolation vs with other components? No need to outline all of the test cases, just the general strategy. Anything that would count as tricky in the implementation and anything particularly challenging to test should be called out. All code is expected to have adequate tests (eventually with coverage expectations). Please adhere to the Kubernetes testing guidelines when drafting this test plan. Removing a deprecated flag ¶ Announce deprecation and support policy of the existing flag Two versions passed since introducing the functionality which deprecates the flag (to address version skew) Address feedback on usage/changed behavior, provided on GitHub issues Deprecate the flag Implementation History ¶ Major milestones in the life cycle of a KEP should be tracked in Implementation History. Major milestones might include the Summary and Motivation sections being merged signaling acceptance the Proposal section being merged signaling agreement on a proposed design the date implementation started the first Kubernetes release where an initial version of the KEP was available the version of Kubernetes where the KEP graduated to general availability when the KEP was retired or superseded Drawbacks [optional] ¶ Why should this KEP not be implemented. Alternatives [optional] ¶ Similar to the Drawbacks section the Alternatives section is used to highlight and record other possible approaches to delivering the value proposed by a KEP. Skip to content NGINX Ingress Controller Kubernetes Enhancement Proposals (KEPs) Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Quick start for the KEP process Do I have to use the KEP process? Why would I want to use the KEP process? Kubernetes Enhancement Proposals (KEPs) ¶ A Kubernetes Enhancement Proposal (KEP) is a way to propose, communicate and coordinate on new efforts for the Kubernetes project. For this reason, the ingress-nginx project is adopting it. Quick start for the KEP process ¶ Follow the process outlined in the KEP template Do I have to use the KEP process? ¶ No... but we hope that you will. Over time having a rich set of KEPs in one place will make it easier for people to track what is going on in the community and find a structured historic record. KEPs are only required when the changes are wide ranging and impact most of the project. Why would I want to use the KEP process? ¶ Our aim with KEPs is to clearly communicate new efforts to the Kubernetes contributor community. As such, we want to build a well curated set of clear proposals in a common format with useful metadata. Benefits to KEP users (in the limit): Exposure on a kubernetes blessed web site that is findable via web search engines. Cross indexing of KEPs so that users can find connections and the current status of any KEP. A clear process with approvers and reviewers for making decisions. This will lead to more structured decisions that stick as there is a discoverable record around the decisions. We are inspired by IETF RFCs, Python PEPs, and Rust RFCs. Skip to content Ingress-Nginx Controller Kubernetes Enhancement Proposals (KEPs) Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Quick start for the KEP process Do I have to use the KEP process? Why would I want to use the KEP process? Kubernetes Enhancement Proposals (KEPs) ¶ A Kubernetes Enhancement Proposal (KEP) is a way to propose, communicate and coordinate on new efforts for the Kubernetes project. For this reason, the ingress-nginx project is adopting it. Quick start for the KEP process ¶ Follow the process outlined in the KEP template Do I have to use the KEP process? ¶ No... but we hope that you will. Over time having a rich set of KEPs in one place will make it easier for people to track what is going on in the community and find a structured historic record. KEPs are only required when the changes are wide ranging and impact most of the project. Why would I want to use the KEP process? ¶ Our aim with KEPs is to clearly communicate new efforts to the Kubernetes contributor community. As such, we want to build a well curated set of clear proposals in a common format with useful metadata. Benefits to KEP users (in the limit): Exposure on a kubernetes blessed web site that is findable via web search engines. Cross indexing of KEPs so that users can find connections and the current status of any KEP. A clear process with approvers and reviewers for making decisions. This will lead to more structured decisions that stick as there is a discoverable record around the decisions. We are inspired by IETF RFCs, Python PEPs, and Rust RFCs. Skip to content NGINX Ingress Controller Prerequisites Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Prerequisites Table of contents TLS certificates Client Certificate Authentication Test HTTP Service Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents TLS certificates Client Certificate Authentication Test HTTP Service Prerequisites ¶ Many of the examples in this directory have common prerequisites. TLS certificates ¶ Unless otherwise mentioned, the TLS secret used in examples is a 2048 bit RSA key/cert pair with an arbitrarily chosen hostname, created as follows $ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=nginxsvc/O=nginxsvc" + Prerequisites - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Prerequisites Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Prerequisites Table of contents TLS certificates Client Certificate Authentication Test HTTP Service Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents TLS certificates Client Certificate Authentication Test HTTP Service Prerequisites ¶ Many of the examples in this directory have common prerequisites. TLS certificates ¶ Unless otherwise mentioned, the TLS secret used in examples is a 2048 bit RSA key/cert pair with an arbitrarily chosen hostname, created as follows $ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=nginxsvc/O=nginxsvc" Generating a 2048 bit RSA private key ................+++ ................+++ diff --git a/examples/affinity/cookie/index.html b/examples/affinity/cookie/index.html index e32048cd3..2e403cf3d 100644 --- a/examples/affinity/cookie/index.html +++ b/examples/affinity/cookie/index.html @@ -1,4 +1,4 @@ - Sticky Sessions - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sticky Sessions Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Sticky Sessions Table of contents Deployment Validation Caveats Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Validation Caveats Sticky sessions ¶ This example demonstrates how to achieve session affinity using cookies. Deployment ¶ Session affinity can be configured using the following annotations: Name Description Value nginx.ingress.kubernetes.io/affinity Type of the affinity, set this to cookie to enable session affinity string (NGINX only supports cookie) nginx.ingress.kubernetes.io/affinity-mode The affinity mode defines how sticky a session is. Use balanced to redistribute some sessions when scaling pods or persistent for maximum stickiness. balanced (default) or persistent nginx.ingress.kubernetes.io/affinity-canary-behavior Defines session affinity behavior of canaries. By default the behavior is sticky, and canaries respect session affinity configuration. Set this to legacy to restore original canary behavior, when session affinity parameters were not respected. sticky (default) or legacy nginx.ingress.kubernetes.io/session-cookie-name Name of the cookie that will be created string (defaults to INGRESSCOOKIE) nginx.ingress.kubernetes.io/session-cookie-secure Set the cookie as secure regardless the protocol of the incoming request "true" or "false" nginx.ingress.kubernetes.io/session-cookie-path Path that will be set on the cookie (required if your Ingress paths use regular expressions) string (defaults to the currently matched path) nginx.ingress.kubernetes.io/session-cookie-domain Domain that will be set on the cookie string nginx.ingress.kubernetes.io/session-cookie-samesite SameSite attribute to apply to the cookie Browser accepted values are None, Lax, and Strict nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none Will omit SameSite=None attribute for older browsers which reject the more-recently defined SameSite=None value "true" or "false" nginx.ingress.kubernetes.io/session-cookie-max-age Time until the cookie expires, corresponds to the Max-Age cookie directive number of seconds nginx.ingress.kubernetes.io/session-cookie-expires Legacy version of the previous annotation for compatibility with older browsers, generates an Expires cookie directive by adding the seconds to the current date number of seconds nginx.ingress.kubernetes.io/session-cookie-change-on-failure When set to false nginx ingress will send request to upstream pointed by sticky cookie even if previous attempt failed. When set to true and previous attempt failed, sticky cookie will be changed to point to another upstream. true or false (defaults to false) You can create the session affinity example Ingress to test this: kubectl create -f ingress.yaml + Sticky Sessions - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sticky Sessions Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Sticky Sessions Table of contents Deployment Validation Caveats Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Validation Caveats Sticky sessions ¶ This example demonstrates how to achieve session affinity using cookies. Deployment ¶ Session affinity can be configured using the following annotations: Name Description Value nginx.ingress.kubernetes.io/affinity Type of the affinity, set this to cookie to enable session affinity string (NGINX only supports cookie) nginx.ingress.kubernetes.io/affinity-mode The affinity mode defines how sticky a session is. Use balanced to redistribute some sessions when scaling pods or persistent for maximum stickiness. balanced (default) or persistent nginx.ingress.kubernetes.io/affinity-canary-behavior Defines session affinity behavior of canaries. By default the behavior is sticky, and canaries respect session affinity configuration. Set this to legacy to restore original canary behavior, when session affinity parameters were not respected. sticky (default) or legacy nginx.ingress.kubernetes.io/session-cookie-name Name of the cookie that will be created string (defaults to INGRESSCOOKIE) nginx.ingress.kubernetes.io/session-cookie-secure Set the cookie as secure regardless the protocol of the incoming request "true" or "false" nginx.ingress.kubernetes.io/session-cookie-path Path that will be set on the cookie (required if your Ingress paths use regular expressions) string (defaults to the currently matched path) nginx.ingress.kubernetes.io/session-cookie-domain Domain that will be set on the cookie string nginx.ingress.kubernetes.io/session-cookie-samesite SameSite attribute to apply to the cookie Browser accepted values are None, Lax, and Strict nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none Will omit SameSite=None attribute for older browsers which reject the more-recently defined SameSite=None value "true" or "false" nginx.ingress.kubernetes.io/session-cookie-max-age Time until the cookie expires, corresponds to the Max-Age cookie directive number of seconds nginx.ingress.kubernetes.io/session-cookie-expires Legacy version of the previous annotation for compatibility with older browsers, generates an Expires cookie directive by adding the seconds to the current date number of seconds nginx.ingress.kubernetes.io/session-cookie-change-on-failure When set to false nginx ingress will send request to upstream pointed by sticky cookie even if previous attempt failed. When set to true and previous attempt failed, sticky cookie will be changed to point to another upstream. true or false (defaults to false) You can create the session affinity example Ingress to test this: kubectl create -f ingress.yaml Validation ¶ You can confirm that the Ingress works: $ kubectl describe ing nginx-test Name: nginx-test Namespace: default @@ -31,7 +31,7 @@ Last-Modified: Tue, 24 Jan 2017 14:02:19 GMT ETag: "58875e6b-264" Accept-Ranges: bytes - In the example above, you can see that the response contains a Set-Cookie header with the settings we have defined. This cookie is created by the NGINX Ingress Controller, it contains a randomly generated key corresponding to the upstream used for that request (selected using consistent hashing) and has an Expires directive. If a client sends a cookie that doesn't correspond to an upstream, NGINX selects an upstream and creates a corresponding cookie. If the backend pool grows NGINX will keep sending the requests through the same server of the first request, even if it's overloaded. When the backend server is removed, the requests are re-routed to another upstream server. This does not require the cookie to be updated because the key's consistent hash will change. Caveats ¶ When you have a Service pointing to more than one Ingress, with only one containing affinity configuration, the first created Ingress will be used. This means that you can face the situation that you've configured session affinity on one Ingress and it doesn't work because the Service is pointing to another Ingress that doesn't configure this. Skip to content NGINX Ingress Controller Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Basic Authentication Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Basic Authentication ¶ This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with htpasswd. It's important the file generated is named auth (actually - that the secret has a key data.auth), otherwise the ingress-controller returns a 503. Create htpasswd file ¶ $ htpasswd -c auth foo + Basic Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Basic Authentication Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Basic Authentication ¶ This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with htpasswd. It's important the file generated is named auth (actually - that the secret has a key data.auth), otherwise the ingress-controller returns a 503. Create htpasswd file ¶ $ htpasswd -c auth foo New password: <bar> New password: Re-type new password: diff --git a/examples/auth/client-certs/index.html b/examples/auth/client-certs/index.html index 8b7f00ce4..fbf4a96af 100644 --- a/examples/auth/client-certs/index.html +++ b/examples/auth/client-certs/index.html @@ -1,4 +1,4 @@ - Client Certificate Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller Client Certificate Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication Client Certificate Authentication Table of contents Creating Certificate Secrets Setup Instructions External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Creating Certificate Secrets Setup Instructions Client Certificate Authentication ¶ It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource. Before getting started you must have the following Certificates configured: CA certificate and Key (Intermediate Certs need to be in CA) Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use) Client Certificate (Signed by CA) and Key For more details on the generation process, checkout the Prerequisite docs. You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following: openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem + Client Certificate Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Client Certificate Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication Client Certificate Authentication Table of contents Creating Certificate Secrets Setup Instructions External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Creating Certificate Secrets Setup Instructions Client Certificate Authentication ¶ It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource. Before getting started you must have the following Certificates configured: CA certificate and Key (Intermediate Certs need to be in CA) Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use) Client Certificate (Signed by CA) and Key For more details on the generation process, checkout the Prerequisite docs. You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following: openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem Then, you can concatenate them all into one file, named 'ca.crt' with the following: cat certificate1.crt certificate2.crt certificate3.crt >> ca.crt Note: Make sure that the Key Size is greater than 1024 and Hashing Algorithm (Digest) is something better than md5 for each certificate generated. Otherwise you will receive an error. Creating Certificate Secrets ¶ There are many different ways of configuring your secrets to enable Client-Certificate Authentication to work properly. You can create a secret containing just the CA certificate and another Secret containing the Server Certificate which is Signed by the CA. kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt kubectl create secret generic tls-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key diff --git a/examples/auth/external-auth/index.html b/examples/auth/external-auth/index.html index 11e3532f8..92246dfe9 100644 --- a/examples/auth/external-auth/index.html +++ b/examples/auth/external-auth/index.html @@ -1,4 +1,4 @@ - External Basic Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml + External Basic Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml ingress "external-auth" created $ kubectl get ing external-auth diff --git a/examples/auth/oauth-external-auth/index.html b/examples/auth/oauth-external-auth/index.html index b8f965b29..49db55e3b 100644 --- a/examples/auth/oauth-external-auth/index.html +++ b/examples/auth/oauth-external-auth/index.html @@ -1,4 +1,4 @@ - External OAUTH Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... + External OAUTH Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... metadata: name: application annotations: diff --git a/examples/customization/configuration-snippets/index.html b/examples/customization/configuration-snippets/index.html index 5f11f913a..45c6ffd1e 100644 --- a/examples/customization/configuration-snippets/index.html +++ b/examples/customization/configuration-snippets/index.html @@ -1,4 +1,4 @@ - Configuration Snippets - NGINX Ingress Controller Skip to content NGINX Ingress Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml + Configuration Snippets - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml Test ¶ Check if the contents of the annotation are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml + Custom Configuration - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml apiVersion: v1 data: proxy-connect-timeout: "10" diff --git a/examples/customization/custom-errors/index.html b/examples/customization/custom-errors/index.html index cae969aeb..2b1b16f7d 100644 --- a/examples/customization/custom-errors/index.html +++ b/examples/customization/custom-errors/index.html @@ -1,4 +1,4 @@ - Custom Errors - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml + Custom Errors - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml service "nginx-errors" created deployment.apps "nginx-errors" created This should have created a Deployment and a Service with the name nginx-errors. $ kubectl get deploy,svc @@ -7,7 +7,7 @@ deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s - Ingress controller configuration ¶ If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the NGINX Ingress controller Service. $ kubectl get svc ingress-nginx + Ingress controller configuration ¶ If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the Ingress-Nginx Controller Service. $ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example. Testing error pages ¶ Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/ diff --git a/examples/customization/custom-headers/index.html b/examples/customization/custom-headers/index.html index ddd97dc36..ca6c12c4a 100644 --- a/examples/customization/custom-headers/index.html +++ b/examples/customization/custom-headers/index.html @@ -1,6 +1,6 @@ - Custom Headers - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Bare-metal considerations ¶ In traditional cloud environments, where network load balancers are available on-demand, a single Kubernetes manifest suffices to provide a single point of contact to the Ingress-Nginx Controller to external clients and, indirectly, to any application running inside the cluster. Bare-metal environments lack this commodity, requiring a slightly different setup to offer the same kind of access to external consumers. The rest of this document describes a few recommended approaches to deploying the Ingress-Nginx Controller inside a Kubernetes cluster running on bare-metal. A pure software solution: MetalLB ¶ MetalLB provides a network load-balancer implementation for Kubernetes clusters that do not run on a supported cloud provider, effectively allowing the usage of LoadBalancer Services within any cluster. This section demonstrates how to use the Layer 2 configuration mode of MetalLB together with the NGINX Ingress controller in a Kubernetes cluster that has publicly accessible nodes. In this mode, one node attracts all the traffic for the ingress-nginx Service IP. See Traffic policies for more details. Note The description of other supported configuration modes is off-scope for this document. Warning MetalLB is currently in beta. Read about the Project maturity and make sure you inform yourself by reading the official documentation thoroughly. MetalLB can be deployed either with a simple Kubernetes manifest or with Helm. The rest of this example assumes MetalLB was deployed following the Installation instructions, and that the Ingress-Nginx Controller was installed using the steps described in the quickstart section of the installation guide. MetalLB requires a pool of IP addresses in order to be able to take ownership of the ingress-nginx Service. This pool can be defined through IPAddressPool objects in the same namespace as the MetalLB controller. This pool of IPs must be dedicated to MetalLB's use, you can't reuse the Kubernetes node IPs or IPs handed out by a DHCP server. Example Given the following 3-node Kubernetes cluster (the external IP is added as an example, in most bare-metal environments this value is <None>) $ kubectl get node NAME STATUS ROLES EXTERNAL-IP host-1 Ready master 203.0.113.1 host-2 Ready node 203.0.113.2 @@ -38,7 +38,7 @@ host-1 Ready master 203.0.113.1 host-2 Ready node 203.0.113.2 host-3 Ready node 203.0.113.3 - a client would reach an Ingress with host: myapp.example.com at http://myapp.example.com:30100, where the myapp.example.com subdomain resolves to the 203.0.113.2 IP address. Impact on the host system While it may sound tempting to reconfigure the NodePort range using the --service-node-port-range API server flag to include unprivileged ports and be able to expose ports 80 and 443, doing so may result in unexpected issues including (but not limited to) the use of ports otherwise reserved to system daemons and the necessity to grant kube-proxy privileges it may otherwise not require. This practice is therefore discouraged. See the other approaches proposed in this page for alternatives. This approach has a few other limitations one ought to be aware of: Source IP address Services of type NodePort perform source address translation by default. This means the source IP of a HTTP request is always the IP address of the Kubernetes node that received the request from the perspective of NGINX. The recommended way to preserve the source IP in a NodePort setup is to set the value of the externalTrafficPolicy field of the ingress-nginx Service spec to Local (example). Warning This setting effectively drops packets sent to Kubernetes nodes which are not running any instance of the NGINX Ingress controller. Consider assigning NGINX Pods to specific nodes in order to control on what nodes the NGINX Ingress controller should be scheduled or not scheduled. Example In a Kubernetes cluster composed of 3 nodes (the external IP is added as an example, in most bare-metal environments this value is <None>) $ kubectl get node + a client would reach an Ingress with host: myapp.example.com at http://myapp.example.com:30100, where the myapp.example.com subdomain resolves to the 203.0.113.2 IP address. Impact on the host system While it may sound tempting to reconfigure the NodePort range using the --service-node-port-range API server flag to include unprivileged ports and be able to expose ports 80 and 443, doing so may result in unexpected issues including (but not limited to) the use of ports otherwise reserved to system daemons and the necessity to grant kube-proxy privileges it may otherwise not require. This practice is therefore discouraged. See the other approaches proposed in this page for alternatives. This approach has a few other limitations one ought to be aware of: Source IP address Services of type NodePort perform source address translation by default. This means the source IP of a HTTP request is always the IP address of the Kubernetes node that received the request from the perspective of NGINX. The recommended way to preserve the source IP in a NodePort setup is to set the value of the externalTrafficPolicy field of the ingress-nginx Service spec to Local (example). Warning This setting effectively drops packets sent to Kubernetes nodes which are not running any instance of the NGINX Ingress controller. Consider assigning NGINX Pods to specific nodes in order to control on what nodes the Ingress-Nginx Controller should be scheduled or not scheduled. Example In a Kubernetes cluster composed of 3 nodes (the external IP is added as an example, in most bare-metal environments this value is <None>) $ kubectl get node NAME STATUS ROLES EXTERNAL-IP host-1 Ready master 203.0.113.1 host-2 Ready node 203.0.113.2 @@ -48,10 +48,10 @@ default-http-backend-7c5bc89cc9-p86md 1/1 Running 172.17.1.1 host-2 ingress-nginx-controller-cf9ff8c96-8vvf8 1/1 Running 172.17.0.3 host-3 ingress-nginx-controller-cf9ff8c96-pxsds 1/1 Running 172.17.1.4 host-2 - Requests sent to host-2 and host-3 would be forwarded to NGINX and original client's IP would be preserved, while requests to host-1 would get dropped because there is no NGINX replica running on that node. Ingress status Because NodePort Services do not get a LoadBalancerIP assigned by definition, the NGINX Ingress controller does not update the status of Ingress objects it manages. $ kubectl get ingress + Requests sent to host-2 and host-3 would be forwarded to NGINX and original client's IP would be preserved, while requests to host-1 would get dropped because there is no NGINX replica running on that node.
Hardening Guide ¶ Overview ¶ There are several ways to do hardening and securing of nginx. In this documentation two guides are used, the guides are overlapping in some points: nginx CIS Benchmark cipherlist.eu (one of many forks of the now dead project cipherli.st) This guide describes, what of the different configurations described in those guides is already implemented as default in the nginx implementation of kubernetes ingress, what needs to be configured, what is obsolete due to the fact that the nginx is running as container (the CIS benchmark relates to a non-containerized installation) and what is difficult or not possible. Be aware that this is only a guide and you are responsible for your own implementation. Some of the configurations may lead to have specific clients unable to reach your site or similar consequences. This guide refers to chapters in the CIS Benchmark. For full explanation you should refer to the benchmark document itself Configuration Guide ¶ Chapter in CIS benchmark Status Default Action to do if not default 1 Initial Setup 1.1 Installation 1.1.1 Ensure NGINX is installed (Scored) OK done through helm charts / following documentation to deploy nginx ingress 1.1.2 Ensure NGINX is installed from source (Not Scored) OK done through helm charts / following documentation to deploy nginx ingress 1.2 Configure Software Updates 1.2.1 Ensure package manager repositories are properly configured (Not Scored) OK done via helm, nginx version could be overwritten, however compatibility is not ensured then 1.2.2 Ensure the latest software package is installed (Not Scored) ACTION NEEDED done via helm, nginx version could be overwritten, however compatibility is not ensured then Plan for periodic updates 2 Basic Configuration 2.1 Minimize NGINX Modules 2.1.1 Ensure only required modules are installed (Not Scored) OK Already only needed modules are installed, however proposals for further reduction are welcome 2.1.2 Ensure HTTP WebDAV module is not installed (Scored) OK 2.1.3 Ensure modules with gzip functionality are disabled (Scored) OK 2.1.4 Ensure the autoindex module is disabled (Scored) OK No autoindex configs so far in ingress defaults 2.2 Account Security 2.2.1 Ensure that NGINX is run using a non-privileged, dedicated service account (Not Scored) OK Pod configured as user www-data: See this line in helm chart values. Compiled with user www-data: See this line in build script 2.2.2 Ensure the NGINX service account is locked (Scored) OK Docker design ensures this 2.2.3 Ensure the NGINX service account has an invalid shell (Scored) OK Shell is nologin: see this line in build script 2.3 Permissions and Ownership 2.3.1 Ensure NGINX directories and files are owned by root (Scored) OK Obsolete through docker-design and ingress controller needs to update the configs dynamically 2.3.2 Ensure access to NGINX directories and files is restricted (Scored) OK See previous answer 2.3.3 Ensure the NGINX process ID (PID) file is secured (Scored) OK No PID-File due to docker design 2.3.4 Ensure the core dump directory is secured (Not Scored) OK No working_directory configured by default 2.4 Network Configuration 2.4.1 Ensure NGINX only listens for network connections on authorized ports (Not Scored) OK Ensured by automatic nginx.conf configuration 2.4.2 Ensure requests for unknown host names are rejected (Not Scored) OK They are not rejected but send to the "default backend" delivering appropriate errors (mostly 404) 2.4.3 Ensure keepalive_timeout is 10 seconds or less, but not 0 (Scored) ACTION NEEDED Default is 75s configure keep-alive to 10 seconds according to this documentation 2.4.4 Ensure send_timeout is set to 10 seconds or less, but not 0 (Scored) RISK TO BE ACCEPTED Not configured, however the nginx default is 60s Not configurable 2.5 Information Disclosure 2.5.1 Ensure server_tokens directive is set to off (Scored) OK server_tokens is configured to off by default 2.5.2 Ensure default error and index.html pages do not reference NGINX (Scored) ACTION NEEDED 404 shows no version at all, 503 and 403 show "nginx", which is hardcoded see this line in nginx source code configure custom error pages at least for 403, 404 and 503 and 500 2.5.3 Ensure hidden file serving is disabled (Not Scored) ACTION NEEDED config not set configure a config.server-snippet Snippet, but beware of .well-known challenges or similar. Refer to the benchmark here please 2.5.4 Ensure the NGINX reverse proxy does not enable information disclosure (Scored) ACTION NEEDED hide not configured configure hide-headers with array of "X-Powered-By" and "Server": according to this documentation 3 Logging 3.1 Ensure detailed logging is enabled (Not Scored) OK nginx ingress has a very detailed log format by default 3.2 Ensure access logging is enabled (Scored) OK Access log is enabled by default 3.3 Ensure error logging is enabled and set to the info logging level (Scored) OK Error log is configured by default. The log level does not matter, because it is all sent to STDOUT anyway 3.4 Ensure log files are rotated (Scored) OBSOLETE Log file handling is not part of the nginx ingress and should be handled separately 3.5 Ensure error logs are sent to a remote syslog server (Not Scored) OBSOLETE See previous answer 3.6 Ensure access logs are sent to a remote syslog server (Not Scored) OBSOLETE See previous answer 3.7 Ensure proxies pass source IP information (Scored) OK Headers are set by default 4 Encryption 4.1 TLS / SSL Configuration 4.1.1 Ensure HTTP is redirected to HTTPS (Scored) OK Redirect to TLS is default 4.1.2 Ensure a trusted certificate and trust chain is installed (Not Scored) ACTION NEEDED For installing certs there are enough manuals in the web. A good way is to use lets encrypt through cert-manager Install proper certificates or use lets encrypt with cert-manager 4.1.3 Ensure private key permissions are restricted (Scored) ACTION NEEDED See previous answer 4.1.4 Ensure only modern TLS protocols are used (Scored) OK/ACTION NEEDED Default is TLS 1.2 + 1.3, while this is okay for CIS Benchmark, cipherlist.eu only recommends 1.3. This may cut off old OS's Set controller.config.ssl-protocols to "TLSv1.3" 4.1.5 Disable weak ciphers (Scored) ACTION NEEDED Default ciphers are already good, but cipherlist.eu recommends even stronger ciphers Set controller.config.ssl-ciphers to "EECDH+AESGCM:EDH+AESGCM" 4.1.6 Ensure custom Diffie-Hellman parameters are used (Scored) ACTION NEEDED No custom DH parameters are generated Generate dh parameters for each ingress deployment you use - see here for a how to 4.1.7 Ensure Online Certificate Status Protocol (OCSP) stapling is enabled (Scored) ACTION NEEDED Not enabled set via this configuration parameter 4.1.8 Ensure HTTP Strict Transport Security (HSTS) is enabled (Scored) OK HSTS is enabled by default 4.1.9 Ensure HTTP Public Key Pinning is enabled (Not Scored) ACTION NEEDED / RISK TO BE ACCEPTED HKPK not enabled by default If lets encrypt is not used, set correct HPKP header. There are several ways to implement this - with the helm charts it works via controller.add-headers. If lets encrypt is used, this is complicated, a solution here is yet unknown 4.1.10 Ensure upstream server traffic is authenticated with a client certificate (Scored) DEPENDS ON BACKEND Highly dependent on backends, not every backend allows configuring this, can also be mitigated via a service mesh If backend allows it, manual is here 4.1.11 Ensure the upstream traffic server certificate is trusted (Not Scored) DEPENDS ON BACKEND Highly dependent on backends, not every backend allows configuring this, can also be mitigated via a service mesh If backend allows it, see configuration here 4.1.12 Ensure your domain is preloaded (Not Scored) ACTION NEEDED Preload is not active by default Set controller.config.hsts-preload to true 4.1.13 Ensure session resumption is disabled to enable perfect forward security (Scored) OK Session tickets are disabled by default 4.1.14 Ensure HTTP/2.0 is used (Not Scored) OK http2 is set by default 5 Request Filtering and Restrictions 5.1 Access Control 5.1.1 Ensure allow and deny filters limit access to specific IP addresses (Not Scored) OK/ACTION NEEDED Depends on use case, geo ip module is compiled into nginx ingress controller, there are several ways to use it If needed set IP restrictions via annotations or work with config snippets (be careful with lets-encrypt-http-challenge!) 5.1.2 Ensure only whitelisted HTTP methods are allowed (Not Scored) OK/ACTION NEEDED Depends on use case If required it can be set via config snippet 5.2 Request Limits 5.2.1 Ensure timeout values for reading the client header and body are set correctly (Scored) ACTION NEEDED Default timeout is 60s Set via this configuration parameter and respective body equivalent 5.2.2 Ensure the maximum request body size is set correctly (Scored) ACTION NEEDED Default is 1m set via this configuration parameter 5.2.3 Ensure the maximum buffer size for URIs is defined (Scored) ACTION NEEDED Default is 4 8k Set via this configuration parameter 5.2.4 Ensure the number of connections per IP address is limited (Not Scored) OK/ACTION NEEDED No limit set Depends on use case, limit can be set via these annotations 5.2.5 Ensure rate limits by IP address are set (Not Scored) OK/ACTION NEEDED No limit set Depends on use case, limit can be set via these annotations 5.3 Browser Security 5.3.1 Ensure X-Frame-Options header is configured and enabled (Scored) ACTION NEEDED Header not set by default Several ways to implement this - with the helm charts it works via controller.add-headers 5.3.2 Ensure X-Content-Type-Options header is configured and enabled (Scored) ACTION NEEDED See previous answer See previous answer 5.3.3 Ensure the X-XSS-Protection Header is enabled and configured properly (Scored) ACTION NEEDED See previous answer See previous answer 5.3.4 Ensure that Content Security Policy (CSP) is enabled and configured properly (Not Scored) ACTION NEEDED See previous answer See previous answer 5.3.5 Ensure the Referrer Policy is enabled and configured properly (Not Scored) ACTION NEEDED Depends on application. It should be handled in the applications webserver itself, not in the load balancing ingress check backend webserver 6 Mandatory Access Control n/a too high level, depends on backends Skip to content Ingress-Nginx Controller Hardening guide Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide Hardening guide Table of contents Overview Configuration Guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Configuration Guide Hardening Guide ¶ Overview ¶ There are several ways to do hardening and securing of nginx. In this documentation two guides are used, the guides are overlapping in some points: nginx CIS Benchmark cipherlist.eu (one of many forks of the now dead project cipherli.st) This guide describes, what of the different configurations described in those guides is already implemented as default in the nginx implementation of kubernetes ingress, what needs to be configured, what is obsolete due to the fact that the nginx is running as container (the CIS benchmark relates to a non-containerized installation) and what is difficult or not possible. Be aware that this is only a guide and you are responsible for your own implementation. Some of the configurations may lead to have specific clients unable to reach your site or similar consequences. This guide refers to chapters in the CIS Benchmark. For full explanation you should refer to the benchmark document itself Configuration Guide ¶ Chapter in CIS benchmark Status Default Action to do if not default 1 Initial Setup 1.1 Installation 1.1.1 Ensure NGINX is installed (Scored) OK done through helm charts / following documentation to deploy nginx ingress 1.1.2 Ensure NGINX is installed from source (Not Scored) OK done through helm charts / following documentation to deploy nginx ingress 1.2 Configure Software Updates 1.2.1 Ensure package manager repositories are properly configured (Not Scored) OK done via helm, nginx version could be overwritten, however compatibility is not ensured then 1.2.2 Ensure the latest software package is installed (Not Scored) ACTION NEEDED done via helm, nginx version could be overwritten, however compatibility is not ensured then Plan for periodic updates 2 Basic Configuration 2.1 Minimize NGINX Modules 2.1.1 Ensure only required modules are installed (Not Scored) OK Already only needed modules are installed, however proposals for further reduction are welcome 2.1.2 Ensure HTTP WebDAV module is not installed (Scored) OK 2.1.3 Ensure modules with gzip functionality are disabled (Scored) OK 2.1.4 Ensure the autoindex module is disabled (Scored) OK No autoindex configs so far in ingress defaults 2.2 Account Security 2.2.1 Ensure that NGINX is run using a non-privileged, dedicated service account (Not Scored) OK Pod configured as user www-data: See this line in helm chart values. Compiled with user www-data: See this line in build script 2.2.2 Ensure the NGINX service account is locked (Scored) OK Docker design ensures this 2.2.3 Ensure the NGINX service account has an invalid shell (Scored) OK Shell is nologin: see this line in build script 2.3 Permissions and Ownership 2.3.1 Ensure NGINX directories and files are owned by root (Scored) OK Obsolete through docker-design and ingress controller needs to update the configs dynamically 2.3.2 Ensure access to NGINX directories and files is restricted (Scored) OK See previous answer 2.3.3 Ensure the NGINX process ID (PID) file is secured (Scored) OK No PID-File due to docker design 2.3.4 Ensure the core dump directory is secured (Not Scored) OK No working_directory configured by default 2.4 Network Configuration 2.4.1 Ensure NGINX only listens for network connections on authorized ports (Not Scored) OK Ensured by automatic nginx.conf configuration 2.4.2 Ensure requests for unknown host names are rejected (Not Scored) OK They are not rejected but send to the "default backend" delivering appropriate errors (mostly 404) 2.4.3 Ensure keepalive_timeout is 10 seconds or less, but not 0 (Scored) ACTION NEEDED Default is 75s configure keep-alive to 10 seconds according to this documentation 2.4.4 Ensure send_timeout is set to 10 seconds or less, but not 0 (Scored) RISK TO BE ACCEPTED Not configured, however the nginx default is 60s Not configurable 2.5 Information Disclosure 2.5.1 Ensure server_tokens directive is set to off (Scored) OK server_tokens is configured to off by default 2.5.2 Ensure default error and index.html pages do not reference NGINX (Scored) ACTION NEEDED 404 shows no version at all, 503 and 403 show "nginx", which is hardcoded see this line in nginx source code configure custom error pages at least for 403, 404 and 503 and 500 2.5.3 Ensure hidden file serving is disabled (Not Scored) ACTION NEEDED config not set configure a config.server-snippet Snippet, but beware of .well-known challenges or similar. Refer to the benchmark here please 2.5.4 Ensure the NGINX reverse proxy does not enable information disclosure (Scored) ACTION NEEDED hide not configured configure hide-headers with array of "X-Powered-By" and "Server": according to this documentation 3 Logging 3.1 Ensure detailed logging is enabled (Not Scored) OK nginx ingress has a very detailed log format by default 3.2 Ensure access logging is enabled (Scored) OK Access log is enabled by default 3.3 Ensure error logging is enabled and set to the info logging level (Scored) OK Error log is configured by default. The log level does not matter, because it is all sent to STDOUT anyway 3.4 Ensure log files are rotated (Scored) OBSOLETE Log file handling is not part of the nginx ingress and should be handled separately 3.5 Ensure error logs are sent to a remote syslog server (Not Scored) OBSOLETE See previous answer 3.6 Ensure access logs are sent to a remote syslog server (Not Scored) OBSOLETE See previous answer 3.7 Ensure proxies pass source IP information (Scored) OK Headers are set by default 4 Encryption 4.1 TLS / SSL Configuration 4.1.1 Ensure HTTP is redirected to HTTPS (Scored) OK Redirect to TLS is default 4.1.2 Ensure a trusted certificate and trust chain is installed (Not Scored) ACTION NEEDED For installing certs there are enough manuals in the web. A good way is to use lets encrypt through cert-manager Install proper certificates or use lets encrypt with cert-manager 4.1.3 Ensure private key permissions are restricted (Scored) ACTION NEEDED See previous answer 4.1.4 Ensure only modern TLS protocols are used (Scored) OK/ACTION NEEDED Default is TLS 1.2 + 1.3, while this is okay for CIS Benchmark, cipherlist.eu only recommends 1.3. This may cut off old OS's Set controller.config.ssl-protocols to "TLSv1.3" 4.1.5 Disable weak ciphers (Scored) ACTION NEEDED Default ciphers are already good, but cipherlist.eu recommends even stronger ciphers Set controller.config.ssl-ciphers to "EECDH+AESGCM:EDH+AESGCM" 4.1.6 Ensure custom Diffie-Hellman parameters are used (Scored) ACTION NEEDED No custom DH parameters are generated Generate dh parameters for each ingress deployment you use - see here for a how to 4.1.7 Ensure Online Certificate Status Protocol (OCSP) stapling is enabled (Scored) ACTION NEEDED Not enabled set via this configuration parameter 4.1.8 Ensure HTTP Strict Transport Security (HSTS) is enabled (Scored) OK HSTS is enabled by default 4.1.9 Ensure HTTP Public Key Pinning is enabled (Not Scored) ACTION NEEDED / RISK TO BE ACCEPTED HKPK not enabled by default If lets encrypt is not used, set correct HPKP header. There are several ways to implement this - with the helm charts it works via controller.add-headers. If lets encrypt is used, this is complicated, a solution here is yet unknown 4.1.10 Ensure upstream server traffic is authenticated with a client certificate (Scored) DEPENDS ON BACKEND Highly dependent on backends, not every backend allows configuring this, can also be mitigated via a service mesh If backend allows it, manual is here 4.1.11 Ensure the upstream traffic server certificate is trusted (Not Scored) DEPENDS ON BACKEND Highly dependent on backends, not every backend allows configuring this, can also be mitigated via a service mesh If backend allows it, see configuration here 4.1.12 Ensure your domain is preloaded (Not Scored) ACTION NEEDED Preload is not active by default Set controller.config.hsts-preload to true 4.1.13 Ensure session resumption is disabled to enable perfect forward security (Scored) OK Session tickets are disabled by default 4.1.14 Ensure HTTP/2.0 is used (Not Scored) OK http2 is set by default 5 Request Filtering and Restrictions 5.1 Access Control 5.1.1 Ensure allow and deny filters limit access to specific IP addresses (Not Scored) OK/ACTION NEEDED Depends on use case, geo ip module is compiled into Ingress-Nginx Controller, there are several ways to use it If needed set IP restrictions via annotations or work with config snippets (be careful with lets-encrypt-http-challenge!) 5.1.2 Ensure only whitelisted HTTP methods are allowed (Not Scored) OK/ACTION NEEDED Depends on use case If required it can be set via config snippet 5.2 Request Limits 5.2.1 Ensure timeout values for reading the client header and body are set correctly (Scored) ACTION NEEDED Default timeout is 60s Set via this configuration parameter and respective body equivalent 5.2.2 Ensure the maximum request body size is set correctly (Scored) ACTION NEEDED Default is 1m set via this configuration parameter 5.2.3 Ensure the maximum buffer size for URIs is defined (Scored) ACTION NEEDED Default is 4 8k Set via this configuration parameter 5.2.4 Ensure the number of connections per IP address is limited (Not Scored) OK/ACTION NEEDED No limit set Depends on use case, limit can be set via these annotations 5.2.5 Ensure rate limits by IP address are set (Not Scored) OK/ACTION NEEDED No limit set Depends on use case, limit can be set via these annotations 5.3 Browser Security 5.3.1 Ensure X-Frame-Options header is configured and enabled (Scored) ACTION NEEDED Header not set by default Several ways to implement this - with the helm charts it works via controller.add-headers 5.3.2 Ensure X-Content-Type-Options header is configured and enabled (Scored) ACTION NEEDED See previous answer See previous answer 5.3.3 Ensure the X-XSS-Protection Header is enabled and configured properly (Scored) ACTION NEEDED See previous answer See previous answer 5.3.4 Ensure that Content Security Policy (CSP) is enabled and configured properly (Not Scored) ACTION NEEDED See previous answer See previous answer 5.3.5 Ensure the Referrer Policy is enabled and configured properly (Not Scored) ACTION NEEDED Depends on application. It should be handled in the applications webserver itself, not in the load balancing ingress check backend webserver 6 Mandatory Access Control n/a too high level, depends on backends Skip to content NGINX Ingress Controller Installation Guide Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Installation Guide Table of contents Contents Quick start Pre-flight check Local testing Online testing Environment-specific instructions Local development clusters minikube MicroK8s Docker Desktop Rancher Desktop Cloud deployments AWS Network Load Balancer (NLB) TLS termination in AWS Load Balancer (NLB) NLB Idle Timeouts GCE-GKE Azure Digital Ocean Scaleway Exoscale Oracle Cloud Infrastructure OVHcloud Bare metal clusters Miscellaneous Checking ingress controller version Scope Webhook network access Certificate generation Running on Kubernetes versions older than 1.19 Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Contents Quick start Pre-flight check Local testing Online testing Environment-specific instructions Local development clusters minikube MicroK8s Docker Desktop Rancher Desktop Cloud deployments AWS Network Load Balancer (NLB) TLS termination in AWS Load Balancer (NLB) NLB Idle Timeouts GCE-GKE Azure Digital Ocean Scaleway Exoscale Oracle Cloud Infrastructure OVHcloud Bare metal clusters Miscellaneous Checking ingress controller version Scope Webhook network access Certificate generation Running on Kubernetes versions older than 1.19 Installation Guide ¶ There are multiple ways to install the NGINX ingress controller: with Helm, using the project repository chart; with kubectl apply, using YAML manifests; with specific addons (e.g. for minikube or MicroK8s). On most Kubernetes clusters, the ingress controller will work without requiring any extra configuration. If you want to get started as fast as possible, you can check the quick start instructions. However, in many environments, you can improve the performance or get better logs by enabling extra features. We recommend that you check the environment-specific instructions for details about optimizing the ingress controller for your particular environment or cloud provider. Contents ¶ Quick start Environment-specific instructions ... Docker Desktop ... Rancher Desktop ... minikube ... MicroK8s ... AWS ... GCE - GKE ... Azure ... Digital Ocean ... Scaleway ... Exoscale ... Oracle Cloud Infrastructure ... OVHcloud ... Bare-metal Miscellaneous Quick start Environment-specific instructions ... Docker Desktop ... Rancher Desktop ... minikube ... MicroK8s ... AWS ... GCE - GKE ... Azure ... Digital Ocean ... Scaleway ... Exoscale ... Oracle Cloud Infrastructure ... OVHcloud ... Bare-metal Miscellaneous e2e test suite for Ingress NGINX Controller ¶ [Admission] admission controller ¶ reject ingress with global-rate-limit annotations when memcached is not configured should not allow overlaps of host and paths without canary annotations should allow overlaps of host and paths with canary annotation should block ingress with invalid path should return an error if there is an error validating the ingress definition should return an error if there is an invalid value in some annotation should return an error if there is a forbidden value in some annotation should not return an error if the Ingress V1 definition is valid with Ingress Class should not return an error if the Ingress V1 definition is valid with IngressClass annotation should return an error if the Ingress V1 definition contains invalid annotations should not return an error for an invalid Ingress when it has unknown class affinitymode ¶ Balanced affinity mode should balance Check persistent affinity mode server-alias ¶ should return status code 200 for host 'foo' and 404 for 'bar' should return status code 200 for host 'foo' and 'bar' should return status code 200 for hosts defined in two ingresses, different path with one alias app-root ¶ should redirect to /foo auth-tls-* ¶ should set sslClientCertificate, sslVerifyClient and sslVerifyDepth with auth-tls-secret should set valid auth-tls-secret, sslVerify to off, and sslVerifyDepth to 2 should 302 redirect to error page instead of 400 when auth-tls-error-page is set should pass URL-encoded certificate to upstream should validate auth-tls-verify-client should return 403 using auth-tls-match-cn with no matching CN from client should return 200 using auth-tls-match-cn with matching CN from client should return 200 using auth-tls-match-cn where atleast one of the regex options matches CN from client backend-protocol ¶ should set backend protocol to https:// and use proxy_pass should set backend protocol to $scheme:// and use proxy_pass should set backend protocol to grpc:// and use grpc_pass should set backend protocol to grpcs:// and use grpc_pass should set backend protocol to '' and use fastcgi_pass should set backend protocol to '' and use ajp_pass client-body-buffer-size ¶ should set client_body_buffer_size to 1000 should set client_body_buffer_size to 1K should set client_body_buffer_size to 1k should set client_body_buffer_size to 1m should set client_body_buffer_size to 1M should not set client_body_buffer_size to invalid 1b connection-proxy-header ¶ set connection header to keep-alive cors-* ¶ should enable cors should set cors methods to only allow POST, GET should set cors max-age should disable cors allow credentials should allow origin for cors should allow headers for cors should expose headers for cors should allow - single origin for multiple cors values should not allow - single origin for multiple cors values should allow correct origins - single origin for multiple cors values should not break functionality should not break functionality with extra domain should not match should allow - single origin with required port should not allow - single origin with port and origin without port should not allow - single origin without port and origin with required port should allow - matching origin with wildcard origin (2 subdomains) should not allow - unmatching origin with wildcard origin (2 subdomains) should allow - matching origin+port with wildcard origin should not allow - portless origin with wildcard origin should allow correct origins - missing subdomain + origin with wildcard origin and correct origin should allow - missing origins (should allow all origins) custom-http-errors ¶ configures Nginx correctly default-backend ¶ should use a custom default backend as upstream disable-access-log disable-http-access-log disable-stream-access-log ¶ disable-access-log set access_log off disable-http-access-log set access_log off disable-stream-access-log set access_log off force-ssl-redirect ¶ should redirect to https from-to-www-redirect ¶ should redirect from www HTTP to HTTP should redirect from www HTTPS to HTTPS annotation-global-rate-limit ¶ generates correct configuration backend-protocol - GRPC ¶ should use grpc_pass in the configuration file should return OK for service with backend protocol GRPC authorization metadata should be overwritten by external auth response headers should return OK for service with backend protocol GRPCS http2-push-preload ¶ enable the http2-push-preload directive whitelist-source-range ¶ should set valid ip whitelist range Annotation - limit-connections ¶ should limit-connections limit-rate ¶ Check limit-rate annotation enable-access-log enable-rewrite-log ¶ set access_log off set rewrite_log on mirror-* ¶ should set mirror-target to http://localhost/mirror should set mirror-target to https://test.env.com/$request_uri should disable mirror-request-body modsecurity owasp ¶ should enable modsecurity should enable modsecurity with transaction ID and OWASP rules should disable modsecurity should enable modsecurity with snippet should enable modsecurity without using 'modsecurity on;' should disable modsecurity using 'modsecurity off;' should enable modsecurity with snippet and block requests should enable modsecurity globally and with modsecurity-snippet block requests should enable modsecurity when enable-owasp-modsecurity-crs is set to true should enable modsecurity through the config map should enable modsecurity through the config map but ignore snippet as disabled by admin should disable default modsecurity conf setting when modsecurity-snippet is specified preserve-trailing-slash ¶ should allow preservation of trailing slashes proxy-* ¶ should set proxy_redirect to off should set proxy_redirect to default should set proxy_redirect to hello.com goodbye.com should set proxy client-max-body-size to 8m should not set proxy client-max-body-size to incorrect value should set valid proxy timeouts should not set invalid proxy timeouts should turn on proxy-buffering should turn off proxy-request-buffering should build proxy next upstream should setup proxy cookies should change the default proxy HTTP version proxy-ssl-* ¶ should set valid proxy-ssl-secret should set valid proxy-ssl-secret, proxy-ssl-verify to on, proxy-ssl-verify-depth to 2, and proxy-ssl-server-name to on should set valid proxy-ssl-secret, proxy-ssl-ciphers to HIGH:!AES should set valid proxy-ssl-secret, proxy-ssl-protocols proxy-ssl-location-only flag should change the nginx config server part permanent-redirect permanent-redirect-code ¶ should respond with a standard redirect code should respond with a custom redirect code satisfy ¶ should configure satisfy directive correctly should allow multiple auth with satisfy any server-snippet ¶ add valid directives to server via server snippet drops server snippet if disabled by the administrator service-upstream ¶ should use the Service Cluster IP and Port should use the Service Cluster IP and Port should not use the Service Cluster IP and Port configuration-snippet ¶ ssl-ciphers ¶ should change ssl ciphers stream-snippet ¶ should add value of stream-snippet to nginx config should add stream-snippet and drop annotations per admin config upstream-hash-by-* ¶ should connect to the same pod should connect to the same subset of pods upstream-vhost ¶ set host to upstreamvhost.bar.com x-forwarded-prefix ¶ should set the X-Forwarded-Prefix to the annotation value should not add X-Forwarded-Prefix if the annotation value is empty denylist-source-range ¶ only deny explicitly denied IPs, allow all others only allow explicitly allowed IPs, deny all others affinity session-cookie-name ¶ should set sticky cookie SERVERID should change cookie name on ingress definition change should set the path to /something on the generated cookie does not set the path to / on the generated cookie if there's more than one rule referring to the same backend should set cookie with expires should set cookie with domain should not set cookie without domain annotation should work with use-regex annotation and session-cookie-path should warn user when use-regex is true and session-cookie-path is not set should not set affinity across all server locations when using separate ingresses should set sticky cookie without host should work with server-alias annotation should set secure in cookie with provided true annotation on http should not set secure in cookie with provided false annotation on http should set secure in cookie with provided false annotation on https rewrite-target use-regex enable-rewrite-log ¶ should write rewrite logs should use correct longest path match should use ~* location modifier if regex annotation is present should fail to use longest match for documented warning should allow for custom rewrite parameters backend-protocol - FastCGI ¶ should use fastcgi_pass in the configuration file should add fastcgi_index in the configuration file should add fastcgi_param in the configuration file should return OK for service with backend protocol FastCGI auth-* ¶ should return status code 200 when no authentication is configured should return status code 503 when authentication is configured with an invalid secret should return status code 401 when authentication is configured but Authorization header is not configured should return status code 401 when authentication is configured and Authorization header is sent with invalid credentials should return status code 401 and cors headers when authentication and cors is configured but Authorization header is not configured should return status code 200 when authentication is configured and Authorization header is sent should return status code 200 when authentication is configured with a map and Authorization header is sent should return status code 401 when authentication is configured with invalid content and Authorization header is sent when external auth is configured when external auth is not configured when auth-headers are set should set cache_key when external auth cache is configured user retains cookie by default user does not retain cookie if upstream returns error status code user with annotated ingress retains cookie if upstream returns error status code should return status code 200 when signed in should redirect to signin url when not signed in keeps processing new ingresses even if one of the existing ingresses is misconfigured should overwrite Foo header with auth response should not create additional upstream block when auth-keepalive is not set should not create additional upstream block when host part of auth-url contains a variable should not create additional upstream block when auth-keepalive is negative should not create additional upstream block when auth-keepalive is set with HTTP/2 should create additional upstream block when auth-keepalive is set with HTTP/1.x should return status code 200 when signed in should redirect to signin url when not signed in keeps processing new ingresses even if one of the existing ingresses is misconfigured should return status code 200 when signed in after auth backend is deleted should deny login for different location on same server should deny login for different servers should redirect to signin url when not signed in should return 503 (location was denied) should add error to the config canary-* ¶ should response with a 200 status from the mainline upstream when requests are made to the mainline ingress should return 404 status for requests to the canary if no matching ingress is found should return the correct status codes when endpoints are unavailable should route requests to the correct upstream if mainline ingress is created before the canary ingress should route requests to the correct upstream if mainline ingress is created after the canary ingress should route requests to the correct upstream if the mainline ingress is modified should route requests to the correct upstream if the canary ingress is modified should route requests to the correct upstream should route requests to the correct upstream should route requests to the correct upstream should route requests to the correct upstream should routes to mainline upstream when the given Regex causes error should route requests to the correct upstream respects always and never values should route requests only to mainline if canary weight is 0 should route requests only to canary if canary weight is 100 should route requests only to canary if canary weight is equal to canary weight total should route requests split between mainline and canary if canary weight is 50 should route requests split between mainline and canary if canary weight is 100 and weight total is 200 should not use canary as a catch-all server should not use canary with domain as a server does not crash when canary ingress has multiple paths to the same non-matching backend always routes traffic to canary if first request was affinitized to canary (default behavior) always routes traffic to canary if first request was affinitized to canary (explicit sticky behavior) routes traffic to either mainline or canary backend (legacy behavior) Debug CLI ¶ should list the backend servers should get information for a specific backend server should produce valid JSON for /dbg general [Default Backend] custom service ¶ uses custom default backend that returns 200 as status code [Default Backend] ¶ should return 404 sending requests when only a default backend is running enables access logging for default backend disables access logging for default backend [Default Backend] SSL ¶ should return a self generated SSL certificate [Default Backend] change default settings ¶ should apply the annotation to the default backend ¶ [Endpointslices] long service name ¶ should return 200 when service name has max allowed number of characters 63 [TopologyHints] topology aware routing ¶ should return 200 when service has topology hints ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ [Setting] ¶ ¶ ¶ ¶ ¶ ¶ ¶ [Shutdown] Grace period shutdown ¶ /healthz should return status code 500 during shutdown grace period [Shutdown] ingress controller ¶ should shutdown in less than 60 secons without pending connections should shutdown after waiting 60 seconds for pending connections to be closed should shutdown after waiting 150 seconds for pending connections to be closed [Shutdown] Graceful shutdown with pending request ¶ should let slow requests finish before shutting down [Ingress] DeepInspection ¶ should drop whole ingress if one path matches invalid regex single ingress - multiple hosts ¶ should set the correct $service_name NGINX variable [Ingress] [PathType] exact ¶ should choose exact location for /exact [Ingress] [PathType] mix Exact and Prefix paths ¶ should choose the correct location [Ingress] [PathType] prefix checks ¶ should return 404 when prefix /aaa does not match request /aaaccc [Ingress] definition without host ¶ should set ingress details variables for ingresses without a host should set ingress details variables for ingresses with host without IngressRuleValue, only Backend [Memory Leak] Dynamic Certificates ¶ should not leak memory from ingress SSL certificates or configuration updates [Load Balancer] load-balance ¶ should apply the configmap load-balance setting [Load Balancer] EWMA ¶ does not fail requests [Load Balancer] round-robin ¶ should evenly distribute requests with round-robin (default algorithm) [Lua] dynamic certificates ¶ picks up the certificate when we add TLS spec to existing ingress picks up the previously missing secret for a given ingress without reloading supports requests with domain with trailing dot picks up the updated certificate without reloading falls back to using default certificate when secret gets deleted without reloading picks up a non-certificate only change removes HTTPS configuration when we delete TLS spec [Lua] dynamic configuration ¶ configures balancer Lua middleware correctly handles endpoints only changes handles endpoints only changes (down scaling of replicas) handles endpoints only changes consistently (down scaling of replicas vs. empty service) handles an annotation change nginx-configuration ¶ start nginx with default configuration fails when using alias directive fails when using root directive [Security] request smuggling ¶ should not return body content from error_page [Service] backend status code 503 ¶ should return 503 when backend service does not exist should return 503 when all backend service endpoints are unavailable [Service] Type ExternalName ¶ works with external name set to incomplete fqdn should return 200 for service type=ExternalName without a port defined should return 200 for service type=ExternalName with a port defined should return status 502 for service type=ExternalName with an invalid host should return 200 for service type=ExternalName using a port name should return 200 for service type=ExternalName using FQDN with trailing dot should update the external name after a service update should sync ingress on external name service addition/deletion [Service] Nil Service Backend ¶ should return 404 when backend service is nil access-log ¶ use the default configuration use the specified configuration use the specified configuration use the specified configuration use the specified configuration Bad annotation values ¶ [BAD_ANNOTATIONS] should drop an ingress if there is an invalid character in some annotation [BAD_ANNOTATIONS] should drop an ingress if there is a forbidden word in some annotation [BAD_ANNOTATIONS] should allow an ingress if there is a default blocklist config in place [BAD_ANNOTATIONS] should drop an ingress if there is a custom blocklist config in place and allow others to pass brotli ¶ condition add-headers ¶ Add a custom header Add multiple custom headers [SSL] [Flag] default-ssl-certificate ¶ uses default ssl certificate for catch-all ingress uses default ssl certificate for host based ingress when configured certificate does not match host [Flag] disable-catch-all ¶ should ignore catch all Ingress with backend should ignore catch all Ingress with backend and rules should delete Ingress updated to catch-all should allow Ingress with rules [Flag] disable-service-external-name ¶ should ignore services of external-name type enable-real-ip ¶ trusts X-Forwarded-For header only when setting is true should not trust X-Forwarded-For header when setting is false use-forwarded-headers ¶ should trust X-Forwarded headers when setting is true should not trust X-Forwarded headers when setting is false Geoip2 ¶ should include geoip2 line in config when enabled and db file exists should only allow requests from specific countries [Security] block-* ¶ should block CIDRs defined in the ConfigMap should block User-Agents defined in the ConfigMap should block Referers defined in the ConfigMap [Security] global-auth-url ¶ should return status code 401 when request any protected service should return status code 200 when request whitelisted (via no-auth-locations) service and 401 when request protected service should return status code 200 when request whitelisted (via ingress annotation) service and 401 when request protected service should still return status code 200 after auth backend is deleted using cache should proxy_method method when global-auth-method is configured should add custom error page when global-auth-signin url is configured should add auth headers when global-auth-response-headers is configured should set request-redirect when global-auth-request-redirect is configured should set snippet when global external auth is configured user retains cookie by default user does not retain cookie if upstream returns error status code user with global-auth-always-set-cookie key in configmap retains cookie if upstream returns error status code global-options ¶ should have worker_rlimit_nofile option should have worker_rlimit_nofile option and be independent on amount of worker processes settings-global-rate-limit ¶ generates correct NGINX configuration hash size ¶ should set server_names_hash_bucket_size should set server_names_hash_max_size should set proxy-headers-hash-bucket-size should set proxy-headers-hash-max-size should set variables-hash-bucket-size should set variables-hash-max-size should set vmap-hash-bucket-size [Flag] ingress-class ¶ should ignore Ingress with a different class annotation should ignore Ingress with different controller class should accept both Ingresses with default IngressClassName and IngressClass annotation should ignore Ingress without IngressClass configuration should delete Ingress when class is removed should serve Ingress when class is added should serve Ingress when class is updated between annotation and ingressClassName should ignore Ingress with no class and accept the correctly configured Ingresses should watch Ingress with no class and ignore ingress with a different class should watch Ingress that uses the class name even if spec is different should watch Ingress with correct annotation should ignore Ingress with only IngressClassName keep-alive keep-alive-requests ¶ should set keepalive_timeout should set keepalive_requests should set keepalive connection to upstream server should set keep alive connection timeout to upstream server should set keepalive time to upstream server should set the request count to upstream server through one keep alive connection Configmap - limit-rate ¶ Check limit-rate config [Flag] custom HTTP and HTTPS ports ¶ should set X-Forwarded-Port headers accordingly when listening on a non-default HTTP port should set X-Forwarded-Port header to 443 should set the X-Forwarded-Port header to 443 log-format-* ¶ should not configure log-format escape by default should enable the log-format-escape-json should disable the log-format-escape-json should enable the log-format-escape-none should disable the log-format-escape-none log-format-escape-json enabled log-format default escape log-format-escape-none enabled [Lua] lua-shared-dicts ¶ configures lua shared dicts main-snippet ¶ should add value of main-snippet setting to nginx config [Security] modsecurity-snippet ¶ should add value of modsecurity-snippet setting to nginx config enable-multi-accept ¶ should be enabled by default should be enabled when set to true should be disabled when set to false Add no tls redirect locations ¶ Check no tls redirect locations config OCSP ¶ should enable OCSP and contain stapling information in the connection Configure OpenTracing ¶ should not exists opentracing directive should exists opentracing directive when is enabled should include opentracing_trust_incoming_span off directive when disabled should not exists opentracing_operation_name directive when is empty should exists opentracing_operation_name directive when is configured should not exists opentracing_location_operation_name directive when is empty should exists opentracing_location_operation_name directive when is configured should enable opentracing using zipkin should enable opentracing using jaeger should enable opentracing using jaeger with sampler host should propagate the w3c header when configured with jaeger should enable opentracing using jaeger with an HTTP endpoint should enable opentracing using datadog plugins ¶ should exist a x-hello-world header [Security] Pod Security Policies ¶ should be running with a Pod Security Policy [Security] Pod Security Policies with volumes ¶ should be running with a Pod Security Policy proxy-connect-timeout ¶ should set valid proxy timeouts using configmap values should not set invalid proxy timeouts using configmap values Dynamic $proxy_host ¶ should exist a proxy_host should exist a proxy_host using the upstream-vhost annotation value proxy-next-upstream ¶ should build proxy next upstream using configmap values use-proxy-protocol ¶ should respect port passed by the PROXY Protocol should respect proto passed by the PROXY Protocol server port should enable PROXY Protocol for HTTPS should enable PROXY Protocol for TCP proxy-read-timeout ¶ should set valid proxy read timeouts using configmap values should not set invalid proxy read timeouts using configmap values proxy-send-timeout ¶ should set valid proxy send timeouts using configmap values should not set invalid proxy send timeouts using configmap values reuse-port ¶ reuse port should be enabled by default reuse port should be disabled reuse port should be enabled configmap server-snippet ¶ should add value of server-snippet setting to all ingress config should add global server-snippet and drop annotations per admin config server-tokens ¶ should not exists Server header in the response should exists Server header in the response when is enabled ssl-ciphers ¶ Add ssl ciphers configmap stream-snippet ¶ should add value of stream-snippet via config map to nginx config [SSL] TLS protocols, ciphers and headers) ¶ setting cipher suite setting max-age parameter setting includeSubDomains parameter setting preload parameter overriding what's set from the upstream should not use ports during the HTTP to HTTPS redirection should not use ports or X-Forwarded-Host during the HTTP to HTTPS redirection [Flag] disable-sync-events ¶ should create sync events (default) should create sync events should not create sync events gzip ¶ should be disabled by default should be enabled with default settings should set gzip_comp_level to 4 should set gzip_disable to msie6 should set gzip_min_length to 100 should set gzip_types to application/javascript Configmap change ¶ should reload after an update in the configuration [Flag] watch namespace selector ¶ should ingore Ingress of namespace without label foo=bar and accept those of namespace with label foo=bar With enable-ssl-passthrough enabled ¶ should enable ssl-passthrough-proxy-port on a different port should pass unknown traffic to default backend and handle known traffic [Security] no-auth-locations ¶ should return status code 401 when accessing '/' unauthentication should return status code 200 when accessing '/' authentication should return status code 200 when accessing '/noauth' unauthenticated Configure Opentelemetry ¶ should not exists opentelemetry directive should exists opentelemetry directive when is enabled should include opentelemetry_trust_incoming_spans on directive when enabled should not exists opentelemetry_operation_name directive when is empty should exists opentelemetry_operation_name directive when is configured [SSL] redirect to HTTPS ¶ should redirect from HTTP to HTTPS when secret is missing [SSL] secret update ¶ should not appear references to secret updates not used in ingress rules should return the fake SSL certificate if the secret is invalid [Status] status update ¶ should update status field after client-go reconnection [TCP] tcp-services ¶ should expose a TCP service should expose an ExternalName TCP service should reload after an update in the configuration ¶ [metrics] exported prometheus metrics ¶ exclude socket request metrics are absent exclude socket request metrics are present Skip to content NGINX Ingress Controller Remove static SSL configuration mode Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation Details/Notes/Constraints Drawbacks Alternatives Remove static SSL configuration mode ¶ Table of Contents ¶ Summary Motivation Goals Non-Goals Proposal Implementation Details/Notes/Constraints Drawbacks Alternatives Summary ¶ Since release 0.19.0 is possible to configure SSL certificates without the need of NGINX reloads (thanks to lua) and after release 0.24.0 the default enabled mode is dynamic. Motivation ¶ The static configuration implies reloads, something that affects the majority of the users. Goals ¶ Deprecation of the flag --enable-dynamic-certificates. Cleanup of the codebase. Non-Goals ¶ Features related to certificate authentication are not changed in any way. Proposal ¶ Remove static SSL configuration Implementation Details/Notes/Constraints ¶ Deprecate the flag Move the directives ssl_certificate and ssl_certificate_key from each server block to the http section. These settings are required to avoid NGINX errors in the logs. Remove any action of the flag --enable-dynamic-certificates Drawbacks ¶ Alternatives ¶ Keep both implementations Skip to content Ingress-Nginx Controller Remove static SSL configuration mode Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation Details/Notes/Constraints Drawbacks Alternatives Remove static SSL configuration mode ¶ Table of Contents ¶ Summary Motivation Goals Non-Goals Proposal Implementation Details/Notes/Constraints Drawbacks Alternatives Summary ¶ Since release 0.19.0 is possible to configure SSL certificates without the need of NGINX reloads (thanks to lua) and after release 0.24.0 the default enabled mode is dynamic. Motivation ¶ The static configuration implies reloads, something that affects the majority of the users. Goals ¶ Deprecation of the flag --enable-dynamic-certificates. Cleanup of the codebase. Non-Goals ¶ Features related to certificate authentication are not changed in any way. Proposal ¶ Remove static SSL configuration Implementation Details/Notes/Constraints ¶ Deprecate the flag Move the directives ssl_certificate and ssl_certificate_key from each server block to the http section. These settings are required to avoid NGINX errors in the logs. Remove any action of the flag --enable-dynamic-certificates Drawbacks ¶ Alternatives ¶ Keep both implementations Skip to content NGINX Ingress Controller Availability zone aware routing Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation History Drawbacks [optional] Availability zone aware routing ¶ Table of Contents ¶ Availability zone aware routing Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation History Drawbacks [optional] Summary ¶ Teach ingress-nginx about availability zones where endpoints are running in. This way ingress-nginx pod will do its best to proxy to zone-local endpoint. Motivation ¶ When users run their services across multiple availability zones they usually pay for egress traffic between zones. Providers such as GCP, and Amazon EC2 usually charge extra for this feature. ingress-nginx when picking an endpoint to route request to does not consider whether the endpoint is in a different zone or the same one. That means it's at least equally likely that it will pick an endpoint from another zone and proxy the request to it. In this situation response from the endpoint to the ingress-nginx pod is considered inter-zone traffic and usually costs extra money. At the time of this writing, GCP charges $0.01 per GB of inter-zone egress traffic according to https://cloud.google.com/compute/network-pricing. According to https://datapath.io/resources/blog/what-are-aws-data-transfer-costs-and-how-to-minimize-them/ Amazon also charges the same amount of money as GCP for cross-zone, egress traffic. This can be a lot of money depending on once's traffic. By teaching ingress-nginx about zones we can eliminate or at least decrease this cost. Arguably inter-zone network latency should also be better than cross-zone. Goals ¶ Given a regional cluster running ingress-nginx, ingress-nginx should do best-effort to pick a zone-local endpoint when proxying This should not impact canary feature ingress-nginx should be able to operate successfully if there are no zonal endpoints Non-Goals ¶ This feature inherently assumes that endpoints are distributed across zones in a way that they can handle all the traffic from ingress-nginx pod(s) in that zone This feature will be relying on https://kubernetes.io/docs/reference/kubernetes-api/labels-annotations-taints/#failure-domainbetakubernetesiozone, it is not this KEP's goal to support other cases Proposal ¶ The idea here is to have the controller part of ingress-nginx (1) detect what zone its current pod is running in and (2) detect the zone for every endpoint it knows about. After that, it will post that data as part of endpoints to Lua land. When picking an endpoint, the Lua balancer will try to pick zone-local endpoint first and if there is no zone-local endpoint then it will fall back to current behavior. Initially, this feature should be optional since it is going to make it harder to reason about the load balancing and not everyone might want that. How does controller know what zone it runs in? We can have the pod spec pass the node name using downward API as an environment variable. Upon startup, the controller can get node details from the API based on the node name. Once the node details are obtained we can extract the zone from the failure-domain.beta.kubernetes.io/zone annotation. Then we can pass that value to Lua land through Nginx configuration when loading lua_ingress.lua module in init_by_lua phase. How do we extract zones for endpoints? We can have the controller watch create and update events on nodes in the entire cluster and based on that keep the map of nodes to zones in the memory. And when we generate endpoints list, we can access node name using .subsets.addresses[i].nodeName and based on that fetch zone from the map in memory and store it as a field on the endpoint. This solution assumes failure-domain.beta.kubernetes.io/zone annotation does not change until the end of the node's life. Otherwise, we have to watch update events as well on the nodes and that'll add even more overhead. Alternatively, we can get the list of nodes only when there's no node in the memory for the given node name. This is probably a better solution because then we would avoid watching for API changes on node resources. We can eagerly fetch all the nodes and build node name to zone mapping on start. From there on, it will sync during endpoint building in the main event loop if there's no existing entry for the node of an endpoint. This means an extra API call in case cluster has expanded. How do we make sure we do our best to choose zone-local endpoint? This will be done on the Lua side. For every backend, we will initialize two balancer instances: (1) with all endpoints (2) with all endpoints corresponding to the current zone for the backend. Then given the request once we choose what backend needs to serve the request, we will first try to use a zonal balancer for that backend. If a zonal balancer does not exist (i.e. there's no zonal endpoint) then we will use a general balancer. In case of zonal outages, we assume that the readiness probe will fail and the controller will see no endpoints for the backend and therefore we will use a general balancer. We can enable the feature using a configmap setting. Doing it this way makes it easier to rollback in case of a problem. Implementation History ¶ initial version of KEP is shipped proposal and implementation details are done Drawbacks [optional] ¶ More load on the Kubernetes API server. Skip to content Ingress-Nginx Controller Availability zone aware routing Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation History Drawbacks [optional] Availability zone aware routing ¶ Table of Contents ¶ Availability zone aware routing Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation History Drawbacks [optional] Summary ¶ Teach ingress-nginx about availability zones where endpoints are running in. This way ingress-nginx pod will do its best to proxy to zone-local endpoint. Motivation ¶ When users run their services across multiple availability zones they usually pay for egress traffic between zones. Providers such as GCP, and Amazon EC2 usually charge extra for this feature. ingress-nginx when picking an endpoint to route request to does not consider whether the endpoint is in a different zone or the same one. That means it's at least equally likely that it will pick an endpoint from another zone and proxy the request to it. In this situation response from the endpoint to the ingress-nginx pod is considered inter-zone traffic and usually costs extra money. At the time of this writing, GCP charges $0.01 per GB of inter-zone egress traffic according to https://cloud.google.com/compute/network-pricing. According to https://datapath.io/resources/blog/what-are-aws-data-transfer-costs-and-how-to-minimize-them/ Amazon also charges the same amount of money as GCP for cross-zone, egress traffic. This can be a lot of money depending on once's traffic. By teaching ingress-nginx about zones we can eliminate or at least decrease this cost. Arguably inter-zone network latency should also be better than cross-zone. Goals ¶ Given a regional cluster running ingress-nginx, ingress-nginx should do best-effort to pick a zone-local endpoint when proxying This should not impact canary feature ingress-nginx should be able to operate successfully if there are no zonal endpoints Non-Goals ¶ This feature inherently assumes that endpoints are distributed across zones in a way that they can handle all the traffic from ingress-nginx pod(s) in that zone This feature will be relying on https://kubernetes.io/docs/reference/kubernetes-api/labels-annotations-taints/#failure-domainbetakubernetesiozone, it is not this KEP's goal to support other cases Proposal ¶ The idea here is to have the controller part of ingress-nginx (1) detect what zone its current pod is running in and (2) detect the zone for every endpoint it knows about. After that, it will post that data as part of endpoints to Lua land. When picking an endpoint, the Lua balancer will try to pick zone-local endpoint first and if there is no zone-local endpoint then it will fall back to current behavior. Initially, this feature should be optional since it is going to make it harder to reason about the load balancing and not everyone might want that. How does controller know what zone it runs in? We can have the pod spec pass the node name using downward API as an environment variable. Upon startup, the controller can get node details from the API based on the node name. Once the node details are obtained we can extract the zone from the failure-domain.beta.kubernetes.io/zone annotation. Then we can pass that value to Lua land through Nginx configuration when loading lua_ingress.lua module in init_by_lua phase. How do we extract zones for endpoints? We can have the controller watch create and update events on nodes in the entire cluster and based on that keep the map of nodes to zones in the memory. And when we generate endpoints list, we can access node name using .subsets.addresses[i].nodeName and based on that fetch zone from the map in memory and store it as a field on the endpoint. This solution assumes failure-domain.beta.kubernetes.io/zone annotation does not change until the end of the node's life. Otherwise, we have to watch update events as well on the nodes and that'll add even more overhead. Alternatively, we can get the list of nodes only when there's no node in the memory for the given node name. This is probably a better solution because then we would avoid watching for API changes on node resources. We can eagerly fetch all the nodes and build node name to zone mapping on start. From there on, it will sync during endpoint building in the main event loop if there's no existing entry for the node of an endpoint. This means an extra API call in case cluster has expanded. How do we make sure we do our best to choose zone-local endpoint? This will be done on the Lua side. For every backend, we will initialize two balancer instances: (1) with all endpoints (2) with all endpoints corresponding to the current zone for the backend. Then given the request once we choose what backend needs to serve the request, we will first try to use a zonal balancer for that backend. If a zonal balancer does not exist (i.e. there's no zonal endpoint) then we will use a general balancer. In case of zonal outages, we assume that the readiness probe will fail and the controller will see no endpoints for the backend and therefore we will use a general balancer. We can enable the feature using a configmap setting. Doing it this way makes it easier to rollback in case of a problem. Implementation History ¶ initial version of KEP is shipped proposal and implementation details are done Drawbacks [optional] ¶ More load on the Kubernetes API server. Skip to content NGINX Ingress Controller KEP Template Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Table of Contents Summary Motivation Goals Non-Goals Proposal User Stories [optional] Story 1 Story 2 Implementation Details/Notes/Constraints [optional] Risks and Mitigations Design Details Test Plan Removing a deprecated flag Implementation History Drawbacks [optional] Alternatives [optional] Title ¶ This is the title of the KEP. Keep it simple and descriptive. A good title can help communicate what the KEP is and should be considered as part of any review. The title should be lowercased and spaces/punctuation should be replaced with -. To get started with this template: Make a copy of this template. Create a copy of this template and name it YYYYMMDD-my-title.md, where YYYYMMDD is the date the KEP was first drafted. Fill out the "overview" sections. This includes the Summary and Motivation sections. These should be easy if you've preflighted the idea of the KEP in an issue. Create a PR. Assign it to folks that are sponsoring this process. Create an issue When filing an enhancement tracking issue, please ensure to complete all fields in the template. Merge early. Avoid getting hung up on specific details and instead aim to get the goal of the KEP merged quickly. The best way to do this is to just start with the "Overview" sections and fill out details incrementally in follow on PRs. View anything marked as a provisional as a working document and subject to change. Aim for single topic PRs to keep discussions focused. If you disagree with what is already in a document, open a new PR with suggested changes. The canonical place for the latest set of instructions (and the likely source of this file) is here. The Metadata section above is intended to support the creation of tooling around the KEP process. This will be a YAML section that is fenced as a code block. See the KEP process for details on each of these items. Table of Contents ¶ A table of contents is helpful for quickly jumping to sections of a KEP and for highlighting any additional information provided beyond the standard KEP template. Ensure the TOC is wrapped with <!-- toc --&rt;<!-- /toc --&rt; tags, and then generate with hack/update-toc.sh. Summary Motivation Goals Non-Goals Proposal User Stories [optional] Story 1 Story 2 Implementation Details/Notes/Constraints [optional] Risks and Mitigations Design Details Test Plan Removing a deprecated flag Implementation History Drawbacks [optional] Alternatives [optional] Summary ¶ The Summary section is incredibly important for producing high quality user-focused documentation such as release notes or a development roadmap. It should be possible to collect this information before implementation begins in order to avoid requiring implementers to split their attention between writing release notes and implementing the feature itself. A good summary is probably at least a paragraph in length. Motivation ¶ This section is for explicitly listing the motivation, goals and non-goals of this KEP. Describe why the change is important and the benefits to users. The motivation section can optionally provide links to experience reports to demonstrate the interest in a KEP within the wider Kubernetes community. Goals ¶ List the specific goals of the KEP. How will we know that this has succeeded? Non-Goals ¶ What is out of scope for this KEP? Listing non-goals helps to focus discussion and make progress. Proposal ¶ This is where we get down to the nitty gritty of what the proposal actually is. User Stories [optional] ¶ Detail the things that people will be able to do if this KEP is implemented. Include as much detail as possible so that people can understand the "how" of the system. The goal here is to make this feel real for users without getting bogged down. Story 1 ¶ Story 2 ¶ Implementation Details/Notes/Constraints [optional] ¶ What are the caveats to the implementation? What are some important details that didn't come across above. Go in to as much detail as necessary here. This might be a good place to talk about core concepts and how they relate. Risks and Mitigations ¶ What are the risks of this proposal and how do we mitigate. Think broadly. For example, consider both security and how this will impact the larger kubernetes ecosystem. How will security be reviewed and by whom? How will UX be reviewed and by whom? Consider including folks that also work outside project. Design Details ¶ Test Plan ¶ Note: Section not required until targeted at a release. Consider the following in developing a test plan for this enhancement: Will there be e2e and integration tests, in addition to unit tests? How will it be tested in isolation vs with other components? No need to outline all of the test cases, just the general strategy. Anything that would count as tricky in the implementation and anything particularly challenging to test should be called out. All code is expected to have adequate tests (eventually with coverage expectations). Please adhere to the Kubernetes testing guidelines when drafting this test plan. Removing a deprecated flag ¶ Announce deprecation and support policy of the existing flag Two versions passed since introducing the functionality which deprecates the flag (to address version skew) Address feedback on usage/changed behavior, provided on GitHub issues Deprecate the flag Implementation History ¶ Major milestones in the life cycle of a KEP should be tracked in Implementation History. Major milestones might include the Summary and Motivation sections being merged signaling acceptance the Proposal section being merged signaling agreement on a proposed design the date implementation started the first Kubernetes release where an initial version of the KEP was available the version of Kubernetes where the KEP graduated to general availability when the KEP was retired or superseded Drawbacks [optional] ¶ Why should this KEP not be implemented. Alternatives [optional] ¶ Similar to the Drawbacks section the Alternatives section is used to highlight and record other possible approaches to delivering the value proposed by a KEP. Skip to content Ingress-Nginx Controller KEP Template Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Table of Contents Summary Motivation Goals Non-Goals Proposal User Stories [optional] Story 1 Story 2 Implementation Details/Notes/Constraints [optional] Risks and Mitigations Design Details Test Plan Removing a deprecated flag Implementation History Drawbacks [optional] Alternatives [optional] Title ¶ This is the title of the KEP. Keep it simple and descriptive. A good title can help communicate what the KEP is and should be considered as part of any review. The title should be lowercased and spaces/punctuation should be replaced with -. To get started with this template: Make a copy of this template. Create a copy of this template and name it YYYYMMDD-my-title.md, where YYYYMMDD is the date the KEP was first drafted. Fill out the "overview" sections. This includes the Summary and Motivation sections. These should be easy if you've preflighted the idea of the KEP in an issue. Create a PR. Assign it to folks that are sponsoring this process. Create an issue When filing an enhancement tracking issue, please ensure to complete all fields in the template. Merge early. Avoid getting hung up on specific details and instead aim to get the goal of the KEP merged quickly. The best way to do this is to just start with the "Overview" sections and fill out details incrementally in follow on PRs. View anything marked as a provisional as a working document and subject to change. Aim for single topic PRs to keep discussions focused. If you disagree with what is already in a document, open a new PR with suggested changes. The canonical place for the latest set of instructions (and the likely source of this file) is here. The Metadata section above is intended to support the creation of tooling around the KEP process. This will be a YAML section that is fenced as a code block. See the KEP process for details on each of these items. Table of Contents ¶ A table of contents is helpful for quickly jumping to sections of a KEP and for highlighting any additional information provided beyond the standard KEP template. Ensure the TOC is wrapped with <!-- toc --&rt;<!-- /toc --&rt; tags, and then generate with hack/update-toc.sh. Summary Motivation Goals Non-Goals Proposal User Stories [optional] Story 1 Story 2 Implementation Details/Notes/Constraints [optional] Risks and Mitigations Design Details Test Plan Removing a deprecated flag Implementation History Drawbacks [optional] Alternatives [optional] Summary ¶ The Summary section is incredibly important for producing high quality user-focused documentation such as release notes or a development roadmap. It should be possible to collect this information before implementation begins in order to avoid requiring implementers to split their attention between writing release notes and implementing the feature itself. A good summary is probably at least a paragraph in length. Motivation ¶ This section is for explicitly listing the motivation, goals and non-goals of this KEP. Describe why the change is important and the benefits to users. The motivation section can optionally provide links to experience reports to demonstrate the interest in a KEP within the wider Kubernetes community. Goals ¶ List the specific goals of the KEP. How will we know that this has succeeded? Non-Goals ¶ What is out of scope for this KEP? Listing non-goals helps to focus discussion and make progress. Proposal ¶ This is where we get down to the nitty gritty of what the proposal actually is. User Stories [optional] ¶ Detail the things that people will be able to do if this KEP is implemented. Include as much detail as possible so that people can understand the "how" of the system. The goal here is to make this feel real for users without getting bogged down. Story 1 ¶ Story 2 ¶ Implementation Details/Notes/Constraints [optional] ¶ What are the caveats to the implementation? What are some important details that didn't come across above. Go in to as much detail as necessary here. This might be a good place to talk about core concepts and how they relate. Risks and Mitigations ¶ What are the risks of this proposal and how do we mitigate. Think broadly. For example, consider both security and how this will impact the larger kubernetes ecosystem. How will security be reviewed and by whom? How will UX be reviewed and by whom? Consider including folks that also work outside project. Design Details ¶ Test Plan ¶ Note: Section not required until targeted at a release. Consider the following in developing a test plan for this enhancement: Will there be e2e and integration tests, in addition to unit tests? How will it be tested in isolation vs with other components? No need to outline all of the test cases, just the general strategy. Anything that would count as tricky in the implementation and anything particularly challenging to test should be called out. All code is expected to have adequate tests (eventually with coverage expectations). Please adhere to the Kubernetes testing guidelines when drafting this test plan. Removing a deprecated flag ¶ Announce deprecation and support policy of the existing flag Two versions passed since introducing the functionality which deprecates the flag (to address version skew) Address feedback on usage/changed behavior, provided on GitHub issues Deprecate the flag Implementation History ¶ Major milestones in the life cycle of a KEP should be tracked in Implementation History. Major milestones might include the Summary and Motivation sections being merged signaling acceptance the Proposal section being merged signaling agreement on a proposed design the date implementation started the first Kubernetes release where an initial version of the KEP was available the version of Kubernetes where the KEP graduated to general availability when the KEP was retired or superseded Drawbacks [optional] ¶ Why should this KEP not be implemented. Alternatives [optional] ¶ Similar to the Drawbacks section the Alternatives section is used to highlight and record other possible approaches to delivering the value proposed by a KEP. Skip to content NGINX Ingress Controller Kubernetes Enhancement Proposals (KEPs) Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Quick start for the KEP process Do I have to use the KEP process? Why would I want to use the KEP process? Kubernetes Enhancement Proposals (KEPs) ¶ A Kubernetes Enhancement Proposal (KEP) is a way to propose, communicate and coordinate on new efforts for the Kubernetes project. For this reason, the ingress-nginx project is adopting it. Quick start for the KEP process ¶ Follow the process outlined in the KEP template Do I have to use the KEP process? ¶ No... but we hope that you will. Over time having a rich set of KEPs in one place will make it easier for people to track what is going on in the community and find a structured historic record. KEPs are only required when the changes are wide ranging and impact most of the project. Why would I want to use the KEP process? ¶ Our aim with KEPs is to clearly communicate new efforts to the Kubernetes contributor community. As such, we want to build a well curated set of clear proposals in a common format with useful metadata. Benefits to KEP users (in the limit): Exposure on a kubernetes blessed web site that is findable via web search engines. Cross indexing of KEPs so that users can find connections and the current status of any KEP. A clear process with approvers and reviewers for making decisions. This will lead to more structured decisions that stick as there is a discoverable record around the decisions. We are inspired by IETF RFCs, Python PEPs, and Rust RFCs. Skip to content Ingress-Nginx Controller Kubernetes Enhancement Proposals (KEPs) Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Quick start for the KEP process Do I have to use the KEP process? Why would I want to use the KEP process? Kubernetes Enhancement Proposals (KEPs) ¶ A Kubernetes Enhancement Proposal (KEP) is a way to propose, communicate and coordinate on new efforts for the Kubernetes project. For this reason, the ingress-nginx project is adopting it. Quick start for the KEP process ¶ Follow the process outlined in the KEP template Do I have to use the KEP process? ¶ No... but we hope that you will. Over time having a rich set of KEPs in one place will make it easier for people to track what is going on in the community and find a structured historic record. KEPs are only required when the changes are wide ranging and impact most of the project. Why would I want to use the KEP process? ¶ Our aim with KEPs is to clearly communicate new efforts to the Kubernetes contributor community. As such, we want to build a well curated set of clear proposals in a common format with useful metadata. Benefits to KEP users (in the limit): Exposure on a kubernetes blessed web site that is findable via web search engines. Cross indexing of KEPs so that users can find connections and the current status of any KEP. A clear process with approvers and reviewers for making decisions. This will lead to more structured decisions that stick as there is a discoverable record around the decisions. We are inspired by IETF RFCs, Python PEPs, and Rust RFCs. Skip to content NGINX Ingress Controller Prerequisites Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Prerequisites Table of contents TLS certificates Client Certificate Authentication Test HTTP Service Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents TLS certificates Client Certificate Authentication Test HTTP Service Prerequisites ¶ Many of the examples in this directory have common prerequisites. TLS certificates ¶ Unless otherwise mentioned, the TLS secret used in examples is a 2048 bit RSA key/cert pair with an arbitrarily chosen hostname, created as follows $ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=nginxsvc/O=nginxsvc" + Prerequisites - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Prerequisites Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Prerequisites Table of contents TLS certificates Client Certificate Authentication Test HTTP Service Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents TLS certificates Client Certificate Authentication Test HTTP Service Prerequisites ¶ Many of the examples in this directory have common prerequisites. TLS certificates ¶ Unless otherwise mentioned, the TLS secret used in examples is a 2048 bit RSA key/cert pair with an arbitrarily chosen hostname, created as follows $ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=nginxsvc/O=nginxsvc" Generating a 2048 bit RSA private key ................+++ ................+++ diff --git a/examples/affinity/cookie/index.html b/examples/affinity/cookie/index.html index e32048cd3..2e403cf3d 100644 --- a/examples/affinity/cookie/index.html +++ b/examples/affinity/cookie/index.html @@ -1,4 +1,4 @@ - Sticky Sessions - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sticky Sessions Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Sticky Sessions Table of contents Deployment Validation Caveats Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Validation Caveats Sticky sessions ¶ This example demonstrates how to achieve session affinity using cookies. Deployment ¶ Session affinity can be configured using the following annotations: Name Description Value nginx.ingress.kubernetes.io/affinity Type of the affinity, set this to cookie to enable session affinity string (NGINX only supports cookie) nginx.ingress.kubernetes.io/affinity-mode The affinity mode defines how sticky a session is. Use balanced to redistribute some sessions when scaling pods or persistent for maximum stickiness. balanced (default) or persistent nginx.ingress.kubernetes.io/affinity-canary-behavior Defines session affinity behavior of canaries. By default the behavior is sticky, and canaries respect session affinity configuration. Set this to legacy to restore original canary behavior, when session affinity parameters were not respected. sticky (default) or legacy nginx.ingress.kubernetes.io/session-cookie-name Name of the cookie that will be created string (defaults to INGRESSCOOKIE) nginx.ingress.kubernetes.io/session-cookie-secure Set the cookie as secure regardless the protocol of the incoming request "true" or "false" nginx.ingress.kubernetes.io/session-cookie-path Path that will be set on the cookie (required if your Ingress paths use regular expressions) string (defaults to the currently matched path) nginx.ingress.kubernetes.io/session-cookie-domain Domain that will be set on the cookie string nginx.ingress.kubernetes.io/session-cookie-samesite SameSite attribute to apply to the cookie Browser accepted values are None, Lax, and Strict nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none Will omit SameSite=None attribute for older browsers which reject the more-recently defined SameSite=None value "true" or "false" nginx.ingress.kubernetes.io/session-cookie-max-age Time until the cookie expires, corresponds to the Max-Age cookie directive number of seconds nginx.ingress.kubernetes.io/session-cookie-expires Legacy version of the previous annotation for compatibility with older browsers, generates an Expires cookie directive by adding the seconds to the current date number of seconds nginx.ingress.kubernetes.io/session-cookie-change-on-failure When set to false nginx ingress will send request to upstream pointed by sticky cookie even if previous attempt failed. When set to true and previous attempt failed, sticky cookie will be changed to point to another upstream. true or false (defaults to false) You can create the session affinity example Ingress to test this: kubectl create -f ingress.yaml + Sticky Sessions - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sticky Sessions Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Sticky Sessions Table of contents Deployment Validation Caveats Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Validation Caveats Sticky sessions ¶ This example demonstrates how to achieve session affinity using cookies. Deployment ¶ Session affinity can be configured using the following annotations: Name Description Value nginx.ingress.kubernetes.io/affinity Type of the affinity, set this to cookie to enable session affinity string (NGINX only supports cookie) nginx.ingress.kubernetes.io/affinity-mode The affinity mode defines how sticky a session is. Use balanced to redistribute some sessions when scaling pods or persistent for maximum stickiness. balanced (default) or persistent nginx.ingress.kubernetes.io/affinity-canary-behavior Defines session affinity behavior of canaries. By default the behavior is sticky, and canaries respect session affinity configuration. Set this to legacy to restore original canary behavior, when session affinity parameters were not respected. sticky (default) or legacy nginx.ingress.kubernetes.io/session-cookie-name Name of the cookie that will be created string (defaults to INGRESSCOOKIE) nginx.ingress.kubernetes.io/session-cookie-secure Set the cookie as secure regardless the protocol of the incoming request "true" or "false" nginx.ingress.kubernetes.io/session-cookie-path Path that will be set on the cookie (required if your Ingress paths use regular expressions) string (defaults to the currently matched path) nginx.ingress.kubernetes.io/session-cookie-domain Domain that will be set on the cookie string nginx.ingress.kubernetes.io/session-cookie-samesite SameSite attribute to apply to the cookie Browser accepted values are None, Lax, and Strict nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none Will omit SameSite=None attribute for older browsers which reject the more-recently defined SameSite=None value "true" or "false" nginx.ingress.kubernetes.io/session-cookie-max-age Time until the cookie expires, corresponds to the Max-Age cookie directive number of seconds nginx.ingress.kubernetes.io/session-cookie-expires Legacy version of the previous annotation for compatibility with older browsers, generates an Expires cookie directive by adding the seconds to the current date number of seconds nginx.ingress.kubernetes.io/session-cookie-change-on-failure When set to false nginx ingress will send request to upstream pointed by sticky cookie even if previous attempt failed. When set to true and previous attempt failed, sticky cookie will be changed to point to another upstream. true or false (defaults to false) You can create the session affinity example Ingress to test this: kubectl create -f ingress.yaml Validation ¶ You can confirm that the Ingress works: $ kubectl describe ing nginx-test Name: nginx-test Namespace: default @@ -31,7 +31,7 @@ Last-Modified: Tue, 24 Jan 2017 14:02:19 GMT ETag: "58875e6b-264" Accept-Ranges: bytes - In the example above, you can see that the response contains a Set-Cookie header with the settings we have defined. This cookie is created by the NGINX Ingress Controller, it contains a randomly generated key corresponding to the upstream used for that request (selected using consistent hashing) and has an Expires directive. If a client sends a cookie that doesn't correspond to an upstream, NGINX selects an upstream and creates a corresponding cookie. If the backend pool grows NGINX will keep sending the requests through the same server of the first request, even if it's overloaded. When the backend server is removed, the requests are re-routed to another upstream server. This does not require the cookie to be updated because the key's consistent hash will change. Caveats ¶ When you have a Service pointing to more than one Ingress, with only one containing affinity configuration, the first created Ingress will be used. This means that you can face the situation that you've configured session affinity on one Ingress and it doesn't work because the Service is pointing to another Ingress that doesn't configure this. Skip to content NGINX Ingress Controller Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Basic Authentication Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Basic Authentication ¶ This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with htpasswd. It's important the file generated is named auth (actually - that the secret has a key data.auth), otherwise the ingress-controller returns a 503. Create htpasswd file ¶ $ htpasswd -c auth foo + Basic Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Basic Authentication Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Basic Authentication ¶ This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with htpasswd. It's important the file generated is named auth (actually - that the secret has a key data.auth), otherwise the ingress-controller returns a 503. Create htpasswd file ¶ $ htpasswd -c auth foo New password: <bar> New password: Re-type new password: diff --git a/examples/auth/client-certs/index.html b/examples/auth/client-certs/index.html index 8b7f00ce4..fbf4a96af 100644 --- a/examples/auth/client-certs/index.html +++ b/examples/auth/client-certs/index.html @@ -1,4 +1,4 @@ - Client Certificate Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller Client Certificate Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication Client Certificate Authentication Table of contents Creating Certificate Secrets Setup Instructions External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Creating Certificate Secrets Setup Instructions Client Certificate Authentication ¶ It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource. Before getting started you must have the following Certificates configured: CA certificate and Key (Intermediate Certs need to be in CA) Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use) Client Certificate (Signed by CA) and Key For more details on the generation process, checkout the Prerequisite docs. You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following: openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem + Client Certificate Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Client Certificate Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication Client Certificate Authentication Table of contents Creating Certificate Secrets Setup Instructions External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Creating Certificate Secrets Setup Instructions Client Certificate Authentication ¶ It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource. Before getting started you must have the following Certificates configured: CA certificate and Key (Intermediate Certs need to be in CA) Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use) Client Certificate (Signed by CA) and Key For more details on the generation process, checkout the Prerequisite docs. You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following: openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem Then, you can concatenate them all into one file, named 'ca.crt' with the following: cat certificate1.crt certificate2.crt certificate3.crt >> ca.crt Note: Make sure that the Key Size is greater than 1024 and Hashing Algorithm (Digest) is something better than md5 for each certificate generated. Otherwise you will receive an error. Creating Certificate Secrets ¶ There are many different ways of configuring your secrets to enable Client-Certificate Authentication to work properly. You can create a secret containing just the CA certificate and another Secret containing the Server Certificate which is Signed by the CA. kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt kubectl create secret generic tls-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key diff --git a/examples/auth/external-auth/index.html b/examples/auth/external-auth/index.html index 11e3532f8..92246dfe9 100644 --- a/examples/auth/external-auth/index.html +++ b/examples/auth/external-auth/index.html @@ -1,4 +1,4 @@ - External Basic Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml + External Basic Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml ingress "external-auth" created $ kubectl get ing external-auth diff --git a/examples/auth/oauth-external-auth/index.html b/examples/auth/oauth-external-auth/index.html index b8f965b29..49db55e3b 100644 --- a/examples/auth/oauth-external-auth/index.html +++ b/examples/auth/oauth-external-auth/index.html @@ -1,4 +1,4 @@ - External OAUTH Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... + External OAUTH Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... metadata: name: application annotations: diff --git a/examples/customization/configuration-snippets/index.html b/examples/customization/configuration-snippets/index.html index 5f11f913a..45c6ffd1e 100644 --- a/examples/customization/configuration-snippets/index.html +++ b/examples/customization/configuration-snippets/index.html @@ -1,4 +1,4 @@ - Configuration Snippets - NGINX Ingress Controller Skip to content NGINX Ingress Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml + Configuration Snippets - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml Test ¶ Check if the contents of the annotation are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml + Custom Configuration - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml apiVersion: v1 data: proxy-connect-timeout: "10" diff --git a/examples/customization/custom-errors/index.html b/examples/customization/custom-errors/index.html index cae969aeb..2b1b16f7d 100644 --- a/examples/customization/custom-errors/index.html +++ b/examples/customization/custom-errors/index.html @@ -1,4 +1,4 @@ - Custom Errors - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml + Custom Errors - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml service "nginx-errors" created deployment.apps "nginx-errors" created This should have created a Deployment and a Service with the name nginx-errors. $ kubectl get deploy,svc @@ -7,7 +7,7 @@ deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s - Ingress controller configuration ¶ If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the NGINX Ingress controller Service. $ kubectl get svc ingress-nginx + Ingress controller configuration ¶ If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the Ingress-Nginx Controller Service. $ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example. Testing error pages ¶ Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/ diff --git a/examples/customization/custom-headers/index.html b/examples/customization/custom-headers/index.html index ddd97dc36..ca6c12c4a 100644 --- a/examples/customization/custom-headers/index.html +++ b/examples/customization/custom-headers/index.html @@ -1,6 +1,6 @@ - Custom Headers - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Hardening Guide ¶ Overview ¶ There are several ways to do hardening and securing of nginx. In this documentation two guides are used, the guides are overlapping in some points: nginx CIS Benchmark cipherlist.eu (one of many forks of the now dead project cipherli.st) This guide describes, what of the different configurations described in those guides is already implemented as default in the nginx implementation of kubernetes ingress, what needs to be configured, what is obsolete due to the fact that the nginx is running as container (the CIS benchmark relates to a non-containerized installation) and what is difficult or not possible. Be aware that this is only a guide and you are responsible for your own implementation. Some of the configurations may lead to have specific clients unable to reach your site or similar consequences. This guide refers to chapters in the CIS Benchmark. For full explanation you should refer to the benchmark document itself Configuration Guide ¶ Chapter in CIS benchmark Status Default Action to do if not default 1 Initial Setup 1.1 Installation 1.1.1 Ensure NGINX is installed (Scored) OK done through helm charts / following documentation to deploy nginx ingress 1.1.2 Ensure NGINX is installed from source (Not Scored) OK done through helm charts / following documentation to deploy nginx ingress 1.2 Configure Software Updates 1.2.1 Ensure package manager repositories are properly configured (Not Scored) OK done via helm, nginx version could be overwritten, however compatibility is not ensured then 1.2.2 Ensure the latest software package is installed (Not Scored) ACTION NEEDED done via helm, nginx version could be overwritten, however compatibility is not ensured then Plan for periodic updates 2 Basic Configuration 2.1 Minimize NGINX Modules 2.1.1 Ensure only required modules are installed (Not Scored) OK Already only needed modules are installed, however proposals for further reduction are welcome 2.1.2 Ensure HTTP WebDAV module is not installed (Scored) OK 2.1.3 Ensure modules with gzip functionality are disabled (Scored) OK 2.1.4 Ensure the autoindex module is disabled (Scored) OK No autoindex configs so far in ingress defaults 2.2 Account Security 2.2.1 Ensure that NGINX is run using a non-privileged, dedicated service account (Not Scored) OK Pod configured as user www-data: See this line in helm chart values. Compiled with user www-data: See this line in build script 2.2.2 Ensure the NGINX service account is locked (Scored) OK Docker design ensures this 2.2.3 Ensure the NGINX service account has an invalid shell (Scored) OK Shell is nologin: see this line in build script 2.3 Permissions and Ownership 2.3.1 Ensure NGINX directories and files are owned by root (Scored) OK Obsolete through docker-design and ingress controller needs to update the configs dynamically 2.3.2 Ensure access to NGINX directories and files is restricted (Scored) OK See previous answer 2.3.3 Ensure the NGINX process ID (PID) file is secured (Scored) OK No PID-File due to docker design 2.3.4 Ensure the core dump directory is secured (Not Scored) OK No working_directory configured by default 2.4 Network Configuration 2.4.1 Ensure NGINX only listens for network connections on authorized ports (Not Scored) OK Ensured by automatic nginx.conf configuration 2.4.2 Ensure requests for unknown host names are rejected (Not Scored) OK They are not rejected but send to the "default backend" delivering appropriate errors (mostly 404) 2.4.3 Ensure keepalive_timeout is 10 seconds or less, but not 0 (Scored) ACTION NEEDED Default is 75s configure keep-alive to 10 seconds according to this documentation 2.4.4 Ensure send_timeout is set to 10 seconds or less, but not 0 (Scored) RISK TO BE ACCEPTED Not configured, however the nginx default is 60s Not configurable 2.5 Information Disclosure 2.5.1 Ensure server_tokens directive is set to off (Scored) OK server_tokens is configured to off by default 2.5.2 Ensure default error and index.html pages do not reference NGINX (Scored) ACTION NEEDED 404 shows no version at all, 503 and 403 show "nginx", which is hardcoded see this line in nginx source code configure custom error pages at least for 403, 404 and 503 and 500 2.5.3 Ensure hidden file serving is disabled (Not Scored) ACTION NEEDED config not set configure a config.server-snippet Snippet, but beware of .well-known challenges or similar. Refer to the benchmark here please 2.5.4 Ensure the NGINX reverse proxy does not enable information disclosure (Scored) ACTION NEEDED hide not configured configure hide-headers with array of "X-Powered-By" and "Server": according to this documentation 3 Logging 3.1 Ensure detailed logging is enabled (Not Scored) OK nginx ingress has a very detailed log format by default 3.2 Ensure access logging is enabled (Scored) OK Access log is enabled by default 3.3 Ensure error logging is enabled and set to the info logging level (Scored) OK Error log is configured by default. The log level does not matter, because it is all sent to STDOUT anyway 3.4 Ensure log files are rotated (Scored) OBSOLETE Log file handling is not part of the nginx ingress and should be handled separately 3.5 Ensure error logs are sent to a remote syslog server (Not Scored) OBSOLETE See previous answer 3.6 Ensure access logs are sent to a remote syslog server (Not Scored) OBSOLETE See previous answer 3.7 Ensure proxies pass source IP information (Scored) OK Headers are set by default 4 Encryption 4.1 TLS / SSL Configuration 4.1.1 Ensure HTTP is redirected to HTTPS (Scored) OK Redirect to TLS is default 4.1.2 Ensure a trusted certificate and trust chain is installed (Not Scored) ACTION NEEDED For installing certs there are enough manuals in the web. A good way is to use lets encrypt through cert-manager Install proper certificates or use lets encrypt with cert-manager 4.1.3 Ensure private key permissions are restricted (Scored) ACTION NEEDED See previous answer 4.1.4 Ensure only modern TLS protocols are used (Scored) OK/ACTION NEEDED Default is TLS 1.2 + 1.3, while this is okay for CIS Benchmark, cipherlist.eu only recommends 1.3. This may cut off old OS's Set controller.config.ssl-protocols to "TLSv1.3" 4.1.5 Disable weak ciphers (Scored) ACTION NEEDED Default ciphers are already good, but cipherlist.eu recommends even stronger ciphers Set controller.config.ssl-ciphers to "EECDH+AESGCM:EDH+AESGCM" 4.1.6 Ensure custom Diffie-Hellman parameters are used (Scored) ACTION NEEDED No custom DH parameters are generated Generate dh parameters for each ingress deployment you use - see here for a how to 4.1.7 Ensure Online Certificate Status Protocol (OCSP) stapling is enabled (Scored) ACTION NEEDED Not enabled set via this configuration parameter 4.1.8 Ensure HTTP Strict Transport Security (HSTS) is enabled (Scored) OK HSTS is enabled by default 4.1.9 Ensure HTTP Public Key Pinning is enabled (Not Scored) ACTION NEEDED / RISK TO BE ACCEPTED HKPK not enabled by default If lets encrypt is not used, set correct HPKP header. There are several ways to implement this - with the helm charts it works via controller.add-headers. If lets encrypt is used, this is complicated, a solution here is yet unknown 4.1.10 Ensure upstream server traffic is authenticated with a client certificate (Scored) DEPENDS ON BACKEND Highly dependent on backends, not every backend allows configuring this, can also be mitigated via a service mesh If backend allows it, manual is here 4.1.11 Ensure the upstream traffic server certificate is trusted (Not Scored) DEPENDS ON BACKEND Highly dependent on backends, not every backend allows configuring this, can also be mitigated via a service mesh If backend allows it, see configuration here 4.1.12 Ensure your domain is preloaded (Not Scored) ACTION NEEDED Preload is not active by default Set controller.config.hsts-preload to true 4.1.13 Ensure session resumption is disabled to enable perfect forward security (Scored) OK Session tickets are disabled by default 4.1.14 Ensure HTTP/2.0 is used (Not Scored) OK http2 is set by default 5 Request Filtering and Restrictions 5.1 Access Control 5.1.1 Ensure allow and deny filters limit access to specific IP addresses (Not Scored) OK/ACTION NEEDED Depends on use case, geo ip module is compiled into Ingress-Nginx Controller, there are several ways to use it If needed set IP restrictions via annotations or work with config snippets (be careful with lets-encrypt-http-challenge!) 5.1.2 Ensure only whitelisted HTTP methods are allowed (Not Scored) OK/ACTION NEEDED Depends on use case If required it can be set via config snippet 5.2 Request Limits 5.2.1 Ensure timeout values for reading the client header and body are set correctly (Scored) ACTION NEEDED Default timeout is 60s Set via this configuration parameter and respective body equivalent 5.2.2 Ensure the maximum request body size is set correctly (Scored) ACTION NEEDED Default is 1m set via this configuration parameter 5.2.3 Ensure the maximum buffer size for URIs is defined (Scored) ACTION NEEDED Default is 4 8k Set via this configuration parameter 5.2.4 Ensure the number of connections per IP address is limited (Not Scored) OK/ACTION NEEDED No limit set Depends on use case, limit can be set via these annotations 5.2.5 Ensure rate limits by IP address are set (Not Scored) OK/ACTION NEEDED No limit set Depends on use case, limit can be set via these annotations 5.3 Browser Security 5.3.1 Ensure X-Frame-Options header is configured and enabled (Scored) ACTION NEEDED Header not set by default Several ways to implement this - with the helm charts it works via controller.add-headers 5.3.2 Ensure X-Content-Type-Options header is configured and enabled (Scored) ACTION NEEDED See previous answer See previous answer 5.3.3 Ensure the X-XSS-Protection Header is enabled and configured properly (Scored) ACTION NEEDED See previous answer See previous answer 5.3.4 Ensure that Content Security Policy (CSP) is enabled and configured properly (Not Scored) ACTION NEEDED See previous answer See previous answer 5.3.5 Ensure the Referrer Policy is enabled and configured properly (Not Scored) ACTION NEEDED Depends on application. It should be handled in the applications webserver itself, not in the load balancing ingress check backend webserver 6 Mandatory Access Control n/a too high level, depends on backends Skip to content NGINX Ingress Controller Installation Guide Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Installation Guide Table of contents Contents Quick start Pre-flight check Local testing Online testing Environment-specific instructions Local development clusters minikube MicroK8s Docker Desktop Rancher Desktop Cloud deployments AWS Network Load Balancer (NLB) TLS termination in AWS Load Balancer (NLB) NLB Idle Timeouts GCE-GKE Azure Digital Ocean Scaleway Exoscale Oracle Cloud Infrastructure OVHcloud Bare metal clusters Miscellaneous Checking ingress controller version Scope Webhook network access Certificate generation Running on Kubernetes versions older than 1.19 Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Contents Quick start Pre-flight check Local testing Online testing Environment-specific instructions Local development clusters minikube MicroK8s Docker Desktop Rancher Desktop Cloud deployments AWS Network Load Balancer (NLB) TLS termination in AWS Load Balancer (NLB) NLB Idle Timeouts GCE-GKE Azure Digital Ocean Scaleway Exoscale Oracle Cloud Infrastructure OVHcloud Bare metal clusters Miscellaneous Checking ingress controller version Scope Webhook network access Certificate generation Running on Kubernetes versions older than 1.19 Installation Guide ¶ There are multiple ways to install the NGINX ingress controller: with Helm, using the project repository chart; with kubectl apply, using YAML manifests; with specific addons (e.g. for minikube or MicroK8s). On most Kubernetes clusters, the ingress controller will work without requiring any extra configuration. If you want to get started as fast as possible, you can check the quick start instructions. However, in many environments, you can improve the performance or get better logs by enabling extra features. We recommend that you check the environment-specific instructions for details about optimizing the ingress controller for your particular environment or cloud provider. Contents ¶ Quick start Environment-specific instructions ... Docker Desktop ... Rancher Desktop ... minikube ... MicroK8s ... AWS ... GCE - GKE ... Azure ... Digital Ocean ... Scaleway ... Exoscale ... Oracle Cloud Infrastructure ... OVHcloud ... Bare-metal Miscellaneous Quick start Environment-specific instructions ... Docker Desktop ... Rancher Desktop ... minikube ... MicroK8s ... AWS ... GCE - GKE ... Azure ... Digital Ocean ... Scaleway ... Exoscale ... Oracle Cloud Infrastructure ... OVHcloud ... Bare-metal Miscellaneous e2e test suite for Ingress NGINX Controller ¶ [Admission] admission controller ¶ reject ingress with global-rate-limit annotations when memcached is not configured should not allow overlaps of host and paths without canary annotations should allow overlaps of host and paths with canary annotation should block ingress with invalid path should return an error if there is an error validating the ingress definition should return an error if there is an invalid value in some annotation should return an error if there is a forbidden value in some annotation should not return an error if the Ingress V1 definition is valid with Ingress Class should not return an error if the Ingress V1 definition is valid with IngressClass annotation should return an error if the Ingress V1 definition contains invalid annotations should not return an error for an invalid Ingress when it has unknown class affinitymode ¶ Balanced affinity mode should balance Check persistent affinity mode server-alias ¶ should return status code 200 for host 'foo' and 404 for 'bar' should return status code 200 for host 'foo' and 'bar' should return status code 200 for hosts defined in two ingresses, different path with one alias app-root ¶ should redirect to /foo auth-tls-* ¶ should set sslClientCertificate, sslVerifyClient and sslVerifyDepth with auth-tls-secret should set valid auth-tls-secret, sslVerify to off, and sslVerifyDepth to 2 should 302 redirect to error page instead of 400 when auth-tls-error-page is set should pass URL-encoded certificate to upstream should validate auth-tls-verify-client should return 403 using auth-tls-match-cn with no matching CN from client should return 200 using auth-tls-match-cn with matching CN from client should return 200 using auth-tls-match-cn where atleast one of the regex options matches CN from client backend-protocol ¶ should set backend protocol to https:// and use proxy_pass should set backend protocol to $scheme:// and use proxy_pass should set backend protocol to grpc:// and use grpc_pass should set backend protocol to grpcs:// and use grpc_pass should set backend protocol to '' and use fastcgi_pass should set backend protocol to '' and use ajp_pass client-body-buffer-size ¶ should set client_body_buffer_size to 1000 should set client_body_buffer_size to 1K should set client_body_buffer_size to 1k should set client_body_buffer_size to 1m should set client_body_buffer_size to 1M should not set client_body_buffer_size to invalid 1b connection-proxy-header ¶ set connection header to keep-alive cors-* ¶ should enable cors should set cors methods to only allow POST, GET should set cors max-age should disable cors allow credentials should allow origin for cors should allow headers for cors should expose headers for cors should allow - single origin for multiple cors values should not allow - single origin for multiple cors values should allow correct origins - single origin for multiple cors values should not break functionality should not break functionality with extra domain should not match should allow - single origin with required port should not allow - single origin with port and origin without port should not allow - single origin without port and origin with required port should allow - matching origin with wildcard origin (2 subdomains) should not allow - unmatching origin with wildcard origin (2 subdomains) should allow - matching origin+port with wildcard origin should not allow - portless origin with wildcard origin should allow correct origins - missing subdomain + origin with wildcard origin and correct origin should allow - missing origins (should allow all origins) custom-http-errors ¶ configures Nginx correctly default-backend ¶ should use a custom default backend as upstream disable-access-log disable-http-access-log disable-stream-access-log ¶ disable-access-log set access_log off disable-http-access-log set access_log off disable-stream-access-log set access_log off force-ssl-redirect ¶ should redirect to https from-to-www-redirect ¶ should redirect from www HTTP to HTTP should redirect from www HTTPS to HTTPS annotation-global-rate-limit ¶ generates correct configuration backend-protocol - GRPC ¶ should use grpc_pass in the configuration file should return OK for service with backend protocol GRPC authorization metadata should be overwritten by external auth response headers should return OK for service with backend protocol GRPCS http2-push-preload ¶ enable the http2-push-preload directive whitelist-source-range ¶ should set valid ip whitelist range Annotation - limit-connections ¶ should limit-connections limit-rate ¶ Check limit-rate annotation enable-access-log enable-rewrite-log ¶ set access_log off set rewrite_log on mirror-* ¶ should set mirror-target to http://localhost/mirror should set mirror-target to https://test.env.com/$request_uri should disable mirror-request-body modsecurity owasp ¶ should enable modsecurity should enable modsecurity with transaction ID and OWASP rules should disable modsecurity should enable modsecurity with snippet should enable modsecurity without using 'modsecurity on;' should disable modsecurity using 'modsecurity off;' should enable modsecurity with snippet and block requests should enable modsecurity globally and with modsecurity-snippet block requests should enable modsecurity when enable-owasp-modsecurity-crs is set to true should enable modsecurity through the config map should enable modsecurity through the config map but ignore snippet as disabled by admin should disable default modsecurity conf setting when modsecurity-snippet is specified preserve-trailing-slash ¶ should allow preservation of trailing slashes proxy-* ¶ should set proxy_redirect to off should set proxy_redirect to default should set proxy_redirect to hello.com goodbye.com should set proxy client-max-body-size to 8m should not set proxy client-max-body-size to incorrect value should set valid proxy timeouts should not set invalid proxy timeouts should turn on proxy-buffering should turn off proxy-request-buffering should build proxy next upstream should setup proxy cookies should change the default proxy HTTP version proxy-ssl-* ¶ should set valid proxy-ssl-secret should set valid proxy-ssl-secret, proxy-ssl-verify to on, proxy-ssl-verify-depth to 2, and proxy-ssl-server-name to on should set valid proxy-ssl-secret, proxy-ssl-ciphers to HIGH:!AES should set valid proxy-ssl-secret, proxy-ssl-protocols proxy-ssl-location-only flag should change the nginx config server part permanent-redirect permanent-redirect-code ¶ should respond with a standard redirect code should respond with a custom redirect code satisfy ¶ should configure satisfy directive correctly should allow multiple auth with satisfy any server-snippet ¶ add valid directives to server via server snippet drops server snippet if disabled by the administrator service-upstream ¶ should use the Service Cluster IP and Port should use the Service Cluster IP and Port should not use the Service Cluster IP and Port configuration-snippet ¶ ssl-ciphers ¶ should change ssl ciphers stream-snippet ¶ should add value of stream-snippet to nginx config should add stream-snippet and drop annotations per admin config upstream-hash-by-* ¶ should connect to the same pod should connect to the same subset of pods upstream-vhost ¶ set host to upstreamvhost.bar.com x-forwarded-prefix ¶ should set the X-Forwarded-Prefix to the annotation value should not add X-Forwarded-Prefix if the annotation value is empty denylist-source-range ¶ only deny explicitly denied IPs, allow all others only allow explicitly allowed IPs, deny all others affinity session-cookie-name ¶ should set sticky cookie SERVERID should change cookie name on ingress definition change should set the path to /something on the generated cookie does not set the path to / on the generated cookie if there's more than one rule referring to the same backend should set cookie with expires should set cookie with domain should not set cookie without domain annotation should work with use-regex annotation and session-cookie-path should warn user when use-regex is true and session-cookie-path is not set should not set affinity across all server locations when using separate ingresses should set sticky cookie without host should work with server-alias annotation should set secure in cookie with provided true annotation on http should not set secure in cookie with provided false annotation on http should set secure in cookie with provided false annotation on https rewrite-target use-regex enable-rewrite-log ¶ should write rewrite logs should use correct longest path match should use ~* location modifier if regex annotation is present should fail to use longest match for documented warning should allow for custom rewrite parameters backend-protocol - FastCGI ¶ should use fastcgi_pass in the configuration file should add fastcgi_index in the configuration file should add fastcgi_param in the configuration file should return OK for service with backend protocol FastCGI auth-* ¶ should return status code 200 when no authentication is configured should return status code 503 when authentication is configured with an invalid secret should return status code 401 when authentication is configured but Authorization header is not configured should return status code 401 when authentication is configured and Authorization header is sent with invalid credentials should return status code 401 and cors headers when authentication and cors is configured but Authorization header is not configured should return status code 200 when authentication is configured and Authorization header is sent should return status code 200 when authentication is configured with a map and Authorization header is sent should return status code 401 when authentication is configured with invalid content and Authorization header is sent when external auth is configured when external auth is not configured when auth-headers are set should set cache_key when external auth cache is configured user retains cookie by default user does not retain cookie if upstream returns error status code user with annotated ingress retains cookie if upstream returns error status code should return status code 200 when signed in should redirect to signin url when not signed in keeps processing new ingresses even if one of the existing ingresses is misconfigured should overwrite Foo header with auth response should not create additional upstream block when auth-keepalive is not set should not create additional upstream block when host part of auth-url contains a variable should not create additional upstream block when auth-keepalive is negative should not create additional upstream block when auth-keepalive is set with HTTP/2 should create additional upstream block when auth-keepalive is set with HTTP/1.x should return status code 200 when signed in should redirect to signin url when not signed in keeps processing new ingresses even if one of the existing ingresses is misconfigured should return status code 200 when signed in after auth backend is deleted should deny login for different location on same server should deny login for different servers should redirect to signin url when not signed in should return 503 (location was denied) should add error to the config canary-* ¶ should response with a 200 status from the mainline upstream when requests are made to the mainline ingress should return 404 status for requests to the canary if no matching ingress is found should return the correct status codes when endpoints are unavailable should route requests to the correct upstream if mainline ingress is created before the canary ingress should route requests to the correct upstream if mainline ingress is created after the canary ingress should route requests to the correct upstream if the mainline ingress is modified should route requests to the correct upstream if the canary ingress is modified should route requests to the correct upstream should route requests to the correct upstream should route requests to the correct upstream should route requests to the correct upstream should routes to mainline upstream when the given Regex causes error should route requests to the correct upstream respects always and never values should route requests only to mainline if canary weight is 0 should route requests only to canary if canary weight is 100 should route requests only to canary if canary weight is equal to canary weight total should route requests split between mainline and canary if canary weight is 50 should route requests split between mainline and canary if canary weight is 100 and weight total is 200 should not use canary as a catch-all server should not use canary with domain as a server does not crash when canary ingress has multiple paths to the same non-matching backend always routes traffic to canary if first request was affinitized to canary (default behavior) always routes traffic to canary if first request was affinitized to canary (explicit sticky behavior) routes traffic to either mainline or canary backend (legacy behavior) Debug CLI ¶ should list the backend servers should get information for a specific backend server should produce valid JSON for /dbg general [Default Backend] custom service ¶ uses custom default backend that returns 200 as status code [Default Backend] ¶ should return 404 sending requests when only a default backend is running enables access logging for default backend disables access logging for default backend [Default Backend] SSL ¶ should return a self generated SSL certificate [Default Backend] change default settings ¶ should apply the annotation to the default backend ¶ [Endpointslices] long service name ¶ should return 200 when service name has max allowed number of characters 63 [TopologyHints] topology aware routing ¶ should return 200 when service has topology hints ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ [Setting] ¶ ¶ ¶ ¶ ¶ ¶ ¶ [Shutdown] Grace period shutdown ¶ /healthz should return status code 500 during shutdown grace period [Shutdown] ingress controller ¶ should shutdown in less than 60 secons without pending connections should shutdown after waiting 60 seconds for pending connections to be closed should shutdown after waiting 150 seconds for pending connections to be closed [Shutdown] Graceful shutdown with pending request ¶ should let slow requests finish before shutting down [Ingress] DeepInspection ¶ should drop whole ingress if one path matches invalid regex single ingress - multiple hosts ¶ should set the correct $service_name NGINX variable [Ingress] [PathType] exact ¶ should choose exact location for /exact [Ingress] [PathType] mix Exact and Prefix paths ¶ should choose the correct location [Ingress] [PathType] prefix checks ¶ should return 404 when prefix /aaa does not match request /aaaccc [Ingress] definition without host ¶ should set ingress details variables for ingresses without a host should set ingress details variables for ingresses with host without IngressRuleValue, only Backend [Memory Leak] Dynamic Certificates ¶ should not leak memory from ingress SSL certificates or configuration updates [Load Balancer] load-balance ¶ should apply the configmap load-balance setting [Load Balancer] EWMA ¶ does not fail requests [Load Balancer] round-robin ¶ should evenly distribute requests with round-robin (default algorithm) [Lua] dynamic certificates ¶ picks up the certificate when we add TLS spec to existing ingress picks up the previously missing secret for a given ingress without reloading supports requests with domain with trailing dot picks up the updated certificate without reloading falls back to using default certificate when secret gets deleted without reloading picks up a non-certificate only change removes HTTPS configuration when we delete TLS spec [Lua] dynamic configuration ¶ configures balancer Lua middleware correctly handles endpoints only changes handles endpoints only changes (down scaling of replicas) handles endpoints only changes consistently (down scaling of replicas vs. empty service) handles an annotation change nginx-configuration ¶ start nginx with default configuration fails when using alias directive fails when using root directive [Security] request smuggling ¶ should not return body content from error_page [Service] backend status code 503 ¶ should return 503 when backend service does not exist should return 503 when all backend service endpoints are unavailable [Service] Type ExternalName ¶ works with external name set to incomplete fqdn should return 200 for service type=ExternalName without a port defined should return 200 for service type=ExternalName with a port defined should return status 502 for service type=ExternalName with an invalid host should return 200 for service type=ExternalName using a port name should return 200 for service type=ExternalName using FQDN with trailing dot should update the external name after a service update should sync ingress on external name service addition/deletion [Service] Nil Service Backend ¶ should return 404 when backend service is nil access-log ¶ use the default configuration use the specified configuration use the specified configuration use the specified configuration use the specified configuration Bad annotation values ¶ [BAD_ANNOTATIONS] should drop an ingress if there is an invalid character in some annotation [BAD_ANNOTATIONS] should drop an ingress if there is a forbidden word in some annotation [BAD_ANNOTATIONS] should allow an ingress if there is a default blocklist config in place [BAD_ANNOTATIONS] should drop an ingress if there is a custom blocklist config in place and allow others to pass brotli ¶ condition add-headers ¶ Add a custom header Add multiple custom headers [SSL] [Flag] default-ssl-certificate ¶ uses default ssl certificate for catch-all ingress uses default ssl certificate for host based ingress when configured certificate does not match host [Flag] disable-catch-all ¶ should ignore catch all Ingress with backend should ignore catch all Ingress with backend and rules should delete Ingress updated to catch-all should allow Ingress with rules [Flag] disable-service-external-name ¶ should ignore services of external-name type enable-real-ip ¶ trusts X-Forwarded-For header only when setting is true should not trust X-Forwarded-For header when setting is false use-forwarded-headers ¶ should trust X-Forwarded headers when setting is true should not trust X-Forwarded headers when setting is false Geoip2 ¶ should include geoip2 line in config when enabled and db file exists should only allow requests from specific countries [Security] block-* ¶ should block CIDRs defined in the ConfigMap should block User-Agents defined in the ConfigMap should block Referers defined in the ConfigMap [Security] global-auth-url ¶ should return status code 401 when request any protected service should return status code 200 when request whitelisted (via no-auth-locations) service and 401 when request protected service should return status code 200 when request whitelisted (via ingress annotation) service and 401 when request protected service should still return status code 200 after auth backend is deleted using cache should proxy_method method when global-auth-method is configured should add custom error page when global-auth-signin url is configured should add auth headers when global-auth-response-headers is configured should set request-redirect when global-auth-request-redirect is configured should set snippet when global external auth is configured user retains cookie by default user does not retain cookie if upstream returns error status code user with global-auth-always-set-cookie key in configmap retains cookie if upstream returns error status code global-options ¶ should have worker_rlimit_nofile option should have worker_rlimit_nofile option and be independent on amount of worker processes settings-global-rate-limit ¶ generates correct NGINX configuration hash size ¶ should set server_names_hash_bucket_size should set server_names_hash_max_size should set proxy-headers-hash-bucket-size should set proxy-headers-hash-max-size should set variables-hash-bucket-size should set variables-hash-max-size should set vmap-hash-bucket-size [Flag] ingress-class ¶ should ignore Ingress with a different class annotation should ignore Ingress with different controller class should accept both Ingresses with default IngressClassName and IngressClass annotation should ignore Ingress without IngressClass configuration should delete Ingress when class is removed should serve Ingress when class is added should serve Ingress when class is updated between annotation and ingressClassName should ignore Ingress with no class and accept the correctly configured Ingresses should watch Ingress with no class and ignore ingress with a different class should watch Ingress that uses the class name even if spec is different should watch Ingress with correct annotation should ignore Ingress with only IngressClassName keep-alive keep-alive-requests ¶ should set keepalive_timeout should set keepalive_requests should set keepalive connection to upstream server should set keep alive connection timeout to upstream server should set keepalive time to upstream server should set the request count to upstream server through one keep alive connection Configmap - limit-rate ¶ Check limit-rate config [Flag] custom HTTP and HTTPS ports ¶ should set X-Forwarded-Port headers accordingly when listening on a non-default HTTP port should set X-Forwarded-Port header to 443 should set the X-Forwarded-Port header to 443 log-format-* ¶ should not configure log-format escape by default should enable the log-format-escape-json should disable the log-format-escape-json should enable the log-format-escape-none should disable the log-format-escape-none log-format-escape-json enabled log-format default escape log-format-escape-none enabled [Lua] lua-shared-dicts ¶ configures lua shared dicts main-snippet ¶ should add value of main-snippet setting to nginx config [Security] modsecurity-snippet ¶ should add value of modsecurity-snippet setting to nginx config enable-multi-accept ¶ should be enabled by default should be enabled when set to true should be disabled when set to false Add no tls redirect locations ¶ Check no tls redirect locations config OCSP ¶ should enable OCSP and contain stapling information in the connection Configure OpenTracing ¶ should not exists opentracing directive should exists opentracing directive when is enabled should include opentracing_trust_incoming_span off directive when disabled should not exists opentracing_operation_name directive when is empty should exists opentracing_operation_name directive when is configured should not exists opentracing_location_operation_name directive when is empty should exists opentracing_location_operation_name directive when is configured should enable opentracing using zipkin should enable opentracing using jaeger should enable opentracing using jaeger with sampler host should propagate the w3c header when configured with jaeger should enable opentracing using jaeger with an HTTP endpoint should enable opentracing using datadog plugins ¶ should exist a x-hello-world header [Security] Pod Security Policies ¶ should be running with a Pod Security Policy [Security] Pod Security Policies with volumes ¶ should be running with a Pod Security Policy proxy-connect-timeout ¶ should set valid proxy timeouts using configmap values should not set invalid proxy timeouts using configmap values Dynamic $proxy_host ¶ should exist a proxy_host should exist a proxy_host using the upstream-vhost annotation value proxy-next-upstream ¶ should build proxy next upstream using configmap values use-proxy-protocol ¶ should respect port passed by the PROXY Protocol should respect proto passed by the PROXY Protocol server port should enable PROXY Protocol for HTTPS should enable PROXY Protocol for TCP proxy-read-timeout ¶ should set valid proxy read timeouts using configmap values should not set invalid proxy read timeouts using configmap values proxy-send-timeout ¶ should set valid proxy send timeouts using configmap values should not set invalid proxy send timeouts using configmap values reuse-port ¶ reuse port should be enabled by default reuse port should be disabled reuse port should be enabled configmap server-snippet ¶ should add value of server-snippet setting to all ingress config should add global server-snippet and drop annotations per admin config server-tokens ¶ should not exists Server header in the response should exists Server header in the response when is enabled ssl-ciphers ¶ Add ssl ciphers configmap stream-snippet ¶ should add value of stream-snippet via config map to nginx config [SSL] TLS protocols, ciphers and headers) ¶ setting cipher suite setting max-age parameter setting includeSubDomains parameter setting preload parameter overriding what's set from the upstream should not use ports during the HTTP to HTTPS redirection should not use ports or X-Forwarded-Host during the HTTP to HTTPS redirection [Flag] disable-sync-events ¶ should create sync events (default) should create sync events should not create sync events gzip ¶ should be disabled by default should be enabled with default settings should set gzip_comp_level to 4 should set gzip_disable to msie6 should set gzip_min_length to 100 should set gzip_types to application/javascript Configmap change ¶ should reload after an update in the configuration [Flag] watch namespace selector ¶ should ingore Ingress of namespace without label foo=bar and accept those of namespace with label foo=bar With enable-ssl-passthrough enabled ¶ should enable ssl-passthrough-proxy-port on a different port should pass unknown traffic to default backend and handle known traffic [Security] no-auth-locations ¶ should return status code 401 when accessing '/' unauthentication should return status code 200 when accessing '/' authentication should return status code 200 when accessing '/noauth' unauthenticated Configure Opentelemetry ¶ should not exists opentelemetry directive should exists opentelemetry directive when is enabled should include opentelemetry_trust_incoming_spans on directive when enabled should not exists opentelemetry_operation_name directive when is empty should exists opentelemetry_operation_name directive when is configured [SSL] redirect to HTTPS ¶ should redirect from HTTP to HTTPS when secret is missing [SSL] secret update ¶ should not appear references to secret updates not used in ingress rules should return the fake SSL certificate if the secret is invalid [Status] status update ¶ should update status field after client-go reconnection [TCP] tcp-services ¶ should expose a TCP service should expose an ExternalName TCP service should reload after an update in the configuration ¶ [metrics] exported prometheus metrics ¶ exclude socket request metrics are absent exclude socket request metrics are present Skip to content NGINX Ingress Controller Remove static SSL configuration mode Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation Details/Notes/Constraints Drawbacks Alternatives Remove static SSL configuration mode ¶ Table of Contents ¶ Summary Motivation Goals Non-Goals Proposal Implementation Details/Notes/Constraints Drawbacks Alternatives Summary ¶ Since release 0.19.0 is possible to configure SSL certificates without the need of NGINX reloads (thanks to lua) and after release 0.24.0 the default enabled mode is dynamic. Motivation ¶ The static configuration implies reloads, something that affects the majority of the users. Goals ¶ Deprecation of the flag --enable-dynamic-certificates. Cleanup of the codebase. Non-Goals ¶ Features related to certificate authentication are not changed in any way. Proposal ¶ Remove static SSL configuration Implementation Details/Notes/Constraints ¶ Deprecate the flag Move the directives ssl_certificate and ssl_certificate_key from each server block to the http section. These settings are required to avoid NGINX errors in the logs. Remove any action of the flag --enable-dynamic-certificates Drawbacks ¶ Alternatives ¶ Keep both implementations Skip to content Ingress-Nginx Controller Remove static SSL configuration mode Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation Details/Notes/Constraints Drawbacks Alternatives Remove static SSL configuration mode ¶ Table of Contents ¶ Summary Motivation Goals Non-Goals Proposal Implementation Details/Notes/Constraints Drawbacks Alternatives Summary ¶ Since release 0.19.0 is possible to configure SSL certificates without the need of NGINX reloads (thanks to lua) and after release 0.24.0 the default enabled mode is dynamic. Motivation ¶ The static configuration implies reloads, something that affects the majority of the users. Goals ¶ Deprecation of the flag --enable-dynamic-certificates. Cleanup of the codebase. Non-Goals ¶ Features related to certificate authentication are not changed in any way. Proposal ¶ Remove static SSL configuration Implementation Details/Notes/Constraints ¶ Deprecate the flag Move the directives ssl_certificate and ssl_certificate_key from each server block to the http section. These settings are required to avoid NGINX errors in the logs. Remove any action of the flag --enable-dynamic-certificates Drawbacks ¶ Alternatives ¶ Keep both implementations Skip to content NGINX Ingress Controller Availability zone aware routing Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation History Drawbacks [optional] Availability zone aware routing ¶ Table of Contents ¶ Availability zone aware routing Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation History Drawbacks [optional] Summary ¶ Teach ingress-nginx about availability zones where endpoints are running in. This way ingress-nginx pod will do its best to proxy to zone-local endpoint. Motivation ¶ When users run their services across multiple availability zones they usually pay for egress traffic between zones. Providers such as GCP, and Amazon EC2 usually charge extra for this feature. ingress-nginx when picking an endpoint to route request to does not consider whether the endpoint is in a different zone or the same one. That means it's at least equally likely that it will pick an endpoint from another zone and proxy the request to it. In this situation response from the endpoint to the ingress-nginx pod is considered inter-zone traffic and usually costs extra money. At the time of this writing, GCP charges $0.01 per GB of inter-zone egress traffic according to https://cloud.google.com/compute/network-pricing. According to https://datapath.io/resources/blog/what-are-aws-data-transfer-costs-and-how-to-minimize-them/ Amazon also charges the same amount of money as GCP for cross-zone, egress traffic. This can be a lot of money depending on once's traffic. By teaching ingress-nginx about zones we can eliminate or at least decrease this cost. Arguably inter-zone network latency should also be better than cross-zone. Goals ¶ Given a regional cluster running ingress-nginx, ingress-nginx should do best-effort to pick a zone-local endpoint when proxying This should not impact canary feature ingress-nginx should be able to operate successfully if there are no zonal endpoints Non-Goals ¶ This feature inherently assumes that endpoints are distributed across zones in a way that they can handle all the traffic from ingress-nginx pod(s) in that zone This feature will be relying on https://kubernetes.io/docs/reference/kubernetes-api/labels-annotations-taints/#failure-domainbetakubernetesiozone, it is not this KEP's goal to support other cases Proposal ¶ The idea here is to have the controller part of ingress-nginx (1) detect what zone its current pod is running in and (2) detect the zone for every endpoint it knows about. After that, it will post that data as part of endpoints to Lua land. When picking an endpoint, the Lua balancer will try to pick zone-local endpoint first and if there is no zone-local endpoint then it will fall back to current behavior. Initially, this feature should be optional since it is going to make it harder to reason about the load balancing and not everyone might want that. How does controller know what zone it runs in? We can have the pod spec pass the node name using downward API as an environment variable. Upon startup, the controller can get node details from the API based on the node name. Once the node details are obtained we can extract the zone from the failure-domain.beta.kubernetes.io/zone annotation. Then we can pass that value to Lua land through Nginx configuration when loading lua_ingress.lua module in init_by_lua phase. How do we extract zones for endpoints? We can have the controller watch create and update events on nodes in the entire cluster and based on that keep the map of nodes to zones in the memory. And when we generate endpoints list, we can access node name using .subsets.addresses[i].nodeName and based on that fetch zone from the map in memory and store it as a field on the endpoint. This solution assumes failure-domain.beta.kubernetes.io/zone annotation does not change until the end of the node's life. Otherwise, we have to watch update events as well on the nodes and that'll add even more overhead. Alternatively, we can get the list of nodes only when there's no node in the memory for the given node name. This is probably a better solution because then we would avoid watching for API changes on node resources. We can eagerly fetch all the nodes and build node name to zone mapping on start. From there on, it will sync during endpoint building in the main event loop if there's no existing entry for the node of an endpoint. This means an extra API call in case cluster has expanded. How do we make sure we do our best to choose zone-local endpoint? This will be done on the Lua side. For every backend, we will initialize two balancer instances: (1) with all endpoints (2) with all endpoints corresponding to the current zone for the backend. Then given the request once we choose what backend needs to serve the request, we will first try to use a zonal balancer for that backend. If a zonal balancer does not exist (i.e. there's no zonal endpoint) then we will use a general balancer. In case of zonal outages, we assume that the readiness probe will fail and the controller will see no endpoints for the backend and therefore we will use a general balancer. We can enable the feature using a configmap setting. Doing it this way makes it easier to rollback in case of a problem. Implementation History ¶ initial version of KEP is shipped proposal and implementation details are done Drawbacks [optional] ¶ More load on the Kubernetes API server. Skip to content Ingress-Nginx Controller Availability zone aware routing Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation History Drawbacks [optional] Availability zone aware routing ¶ Table of Contents ¶ Availability zone aware routing Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation History Drawbacks [optional] Summary ¶ Teach ingress-nginx about availability zones where endpoints are running in. This way ingress-nginx pod will do its best to proxy to zone-local endpoint. Motivation ¶ When users run their services across multiple availability zones they usually pay for egress traffic between zones. Providers such as GCP, and Amazon EC2 usually charge extra for this feature. ingress-nginx when picking an endpoint to route request to does not consider whether the endpoint is in a different zone or the same one. That means it's at least equally likely that it will pick an endpoint from another zone and proxy the request to it. In this situation response from the endpoint to the ingress-nginx pod is considered inter-zone traffic and usually costs extra money. At the time of this writing, GCP charges $0.01 per GB of inter-zone egress traffic according to https://cloud.google.com/compute/network-pricing. According to https://datapath.io/resources/blog/what-are-aws-data-transfer-costs-and-how-to-minimize-them/ Amazon also charges the same amount of money as GCP for cross-zone, egress traffic. This can be a lot of money depending on once's traffic. By teaching ingress-nginx about zones we can eliminate or at least decrease this cost. Arguably inter-zone network latency should also be better than cross-zone. Goals ¶ Given a regional cluster running ingress-nginx, ingress-nginx should do best-effort to pick a zone-local endpoint when proxying This should not impact canary feature ingress-nginx should be able to operate successfully if there are no zonal endpoints Non-Goals ¶ This feature inherently assumes that endpoints are distributed across zones in a way that they can handle all the traffic from ingress-nginx pod(s) in that zone This feature will be relying on https://kubernetes.io/docs/reference/kubernetes-api/labels-annotations-taints/#failure-domainbetakubernetesiozone, it is not this KEP's goal to support other cases Proposal ¶ The idea here is to have the controller part of ingress-nginx (1) detect what zone its current pod is running in and (2) detect the zone for every endpoint it knows about. After that, it will post that data as part of endpoints to Lua land. When picking an endpoint, the Lua balancer will try to pick zone-local endpoint first and if there is no zone-local endpoint then it will fall back to current behavior. Initially, this feature should be optional since it is going to make it harder to reason about the load balancing and not everyone might want that. How does controller know what zone it runs in? We can have the pod spec pass the node name using downward API as an environment variable. Upon startup, the controller can get node details from the API based on the node name. Once the node details are obtained we can extract the zone from the failure-domain.beta.kubernetes.io/zone annotation. Then we can pass that value to Lua land through Nginx configuration when loading lua_ingress.lua module in init_by_lua phase. How do we extract zones for endpoints? We can have the controller watch create and update events on nodes in the entire cluster and based on that keep the map of nodes to zones in the memory. And when we generate endpoints list, we can access node name using .subsets.addresses[i].nodeName and based on that fetch zone from the map in memory and store it as a field on the endpoint. This solution assumes failure-domain.beta.kubernetes.io/zone annotation does not change until the end of the node's life. Otherwise, we have to watch update events as well on the nodes and that'll add even more overhead. Alternatively, we can get the list of nodes only when there's no node in the memory for the given node name. This is probably a better solution because then we would avoid watching for API changes on node resources. We can eagerly fetch all the nodes and build node name to zone mapping on start. From there on, it will sync during endpoint building in the main event loop if there's no existing entry for the node of an endpoint. This means an extra API call in case cluster has expanded. How do we make sure we do our best to choose zone-local endpoint? This will be done on the Lua side. For every backend, we will initialize two balancer instances: (1) with all endpoints (2) with all endpoints corresponding to the current zone for the backend. Then given the request once we choose what backend needs to serve the request, we will first try to use a zonal balancer for that backend. If a zonal balancer does not exist (i.e. there's no zonal endpoint) then we will use a general balancer. In case of zonal outages, we assume that the readiness probe will fail and the controller will see no endpoints for the backend and therefore we will use a general balancer. We can enable the feature using a configmap setting. Doing it this way makes it easier to rollback in case of a problem. Implementation History ¶ initial version of KEP is shipped proposal and implementation details are done Drawbacks [optional] ¶ More load on the Kubernetes API server. Skip to content NGINX Ingress Controller KEP Template Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Table of Contents Summary Motivation Goals Non-Goals Proposal User Stories [optional] Story 1 Story 2 Implementation Details/Notes/Constraints [optional] Risks and Mitigations Design Details Test Plan Removing a deprecated flag Implementation History Drawbacks [optional] Alternatives [optional] Title ¶ This is the title of the KEP. Keep it simple and descriptive. A good title can help communicate what the KEP is and should be considered as part of any review. The title should be lowercased and spaces/punctuation should be replaced with -. To get started with this template: Make a copy of this template. Create a copy of this template and name it YYYYMMDD-my-title.md, where YYYYMMDD is the date the KEP was first drafted. Fill out the "overview" sections. This includes the Summary and Motivation sections. These should be easy if you've preflighted the idea of the KEP in an issue. Create a PR. Assign it to folks that are sponsoring this process. Create an issue When filing an enhancement tracking issue, please ensure to complete all fields in the template. Merge early. Avoid getting hung up on specific details and instead aim to get the goal of the KEP merged quickly. The best way to do this is to just start with the "Overview" sections and fill out details incrementally in follow on PRs. View anything marked as a provisional as a working document and subject to change. Aim for single topic PRs to keep discussions focused. If you disagree with what is already in a document, open a new PR with suggested changes. The canonical place for the latest set of instructions (and the likely source of this file) is here. The Metadata section above is intended to support the creation of tooling around the KEP process. This will be a YAML section that is fenced as a code block. See the KEP process for details on each of these items. Table of Contents ¶ A table of contents is helpful for quickly jumping to sections of a KEP and for highlighting any additional information provided beyond the standard KEP template. Ensure the TOC is wrapped with <!-- toc --&rt;<!-- /toc --&rt; tags, and then generate with hack/update-toc.sh. Summary Motivation Goals Non-Goals Proposal User Stories [optional] Story 1 Story 2 Implementation Details/Notes/Constraints [optional] Risks and Mitigations Design Details Test Plan Removing a deprecated flag Implementation History Drawbacks [optional] Alternatives [optional] Summary ¶ The Summary section is incredibly important for producing high quality user-focused documentation such as release notes or a development roadmap. It should be possible to collect this information before implementation begins in order to avoid requiring implementers to split their attention between writing release notes and implementing the feature itself. A good summary is probably at least a paragraph in length. Motivation ¶ This section is for explicitly listing the motivation, goals and non-goals of this KEP. Describe why the change is important and the benefits to users. The motivation section can optionally provide links to experience reports to demonstrate the interest in a KEP within the wider Kubernetes community. Goals ¶ List the specific goals of the KEP. How will we know that this has succeeded? Non-Goals ¶ What is out of scope for this KEP? Listing non-goals helps to focus discussion and make progress. Proposal ¶ This is where we get down to the nitty gritty of what the proposal actually is. User Stories [optional] ¶ Detail the things that people will be able to do if this KEP is implemented. Include as much detail as possible so that people can understand the "how" of the system. The goal here is to make this feel real for users without getting bogged down. Story 1 ¶ Story 2 ¶ Implementation Details/Notes/Constraints [optional] ¶ What are the caveats to the implementation? What are some important details that didn't come across above. Go in to as much detail as necessary here. This might be a good place to talk about core concepts and how they relate. Risks and Mitigations ¶ What are the risks of this proposal and how do we mitigate. Think broadly. For example, consider both security and how this will impact the larger kubernetes ecosystem. How will security be reviewed and by whom? How will UX be reviewed and by whom? Consider including folks that also work outside project. Design Details ¶ Test Plan ¶ Note: Section not required until targeted at a release. Consider the following in developing a test plan for this enhancement: Will there be e2e and integration tests, in addition to unit tests? How will it be tested in isolation vs with other components? No need to outline all of the test cases, just the general strategy. Anything that would count as tricky in the implementation and anything particularly challenging to test should be called out. All code is expected to have adequate tests (eventually with coverage expectations). Please adhere to the Kubernetes testing guidelines when drafting this test plan. Removing a deprecated flag ¶ Announce deprecation and support policy of the existing flag Two versions passed since introducing the functionality which deprecates the flag (to address version skew) Address feedback on usage/changed behavior, provided on GitHub issues Deprecate the flag Implementation History ¶ Major milestones in the life cycle of a KEP should be tracked in Implementation History. Major milestones might include the Summary and Motivation sections being merged signaling acceptance the Proposal section being merged signaling agreement on a proposed design the date implementation started the first Kubernetes release where an initial version of the KEP was available the version of Kubernetes where the KEP graduated to general availability when the KEP was retired or superseded Drawbacks [optional] ¶ Why should this KEP not be implemented. Alternatives [optional] ¶ Similar to the Drawbacks section the Alternatives section is used to highlight and record other possible approaches to delivering the value proposed by a KEP. Skip to content Ingress-Nginx Controller KEP Template Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Table of Contents Summary Motivation Goals Non-Goals Proposal User Stories [optional] Story 1 Story 2 Implementation Details/Notes/Constraints [optional] Risks and Mitigations Design Details Test Plan Removing a deprecated flag Implementation History Drawbacks [optional] Alternatives [optional] Title ¶ This is the title of the KEP. Keep it simple and descriptive. A good title can help communicate what the KEP is and should be considered as part of any review. The title should be lowercased and spaces/punctuation should be replaced with -. To get started with this template: Make a copy of this template. Create a copy of this template and name it YYYYMMDD-my-title.md, where YYYYMMDD is the date the KEP was first drafted. Fill out the "overview" sections. This includes the Summary and Motivation sections. These should be easy if you've preflighted the idea of the KEP in an issue. Create a PR. Assign it to folks that are sponsoring this process. Create an issue When filing an enhancement tracking issue, please ensure to complete all fields in the template. Merge early. Avoid getting hung up on specific details and instead aim to get the goal of the KEP merged quickly. The best way to do this is to just start with the "Overview" sections and fill out details incrementally in follow on PRs. View anything marked as a provisional as a working document and subject to change. Aim for single topic PRs to keep discussions focused. If you disagree with what is already in a document, open a new PR with suggested changes. The canonical place for the latest set of instructions (and the likely source of this file) is here. The Metadata section above is intended to support the creation of tooling around the KEP process. This will be a YAML section that is fenced as a code block. See the KEP process for details on each of these items. Table of Contents ¶ A table of contents is helpful for quickly jumping to sections of a KEP and for highlighting any additional information provided beyond the standard KEP template. Ensure the TOC is wrapped with <!-- toc --&rt;<!-- /toc --&rt; tags, and then generate with hack/update-toc.sh. Summary Motivation Goals Non-Goals Proposal User Stories [optional] Story 1 Story 2 Implementation Details/Notes/Constraints [optional] Risks and Mitigations Design Details Test Plan Removing a deprecated flag Implementation History Drawbacks [optional] Alternatives [optional] Summary ¶ The Summary section is incredibly important for producing high quality user-focused documentation such as release notes or a development roadmap. It should be possible to collect this information before implementation begins in order to avoid requiring implementers to split their attention between writing release notes and implementing the feature itself. A good summary is probably at least a paragraph in length. Motivation ¶ This section is for explicitly listing the motivation, goals and non-goals of this KEP. Describe why the change is important and the benefits to users. The motivation section can optionally provide links to experience reports to demonstrate the interest in a KEP within the wider Kubernetes community. Goals ¶ List the specific goals of the KEP. How will we know that this has succeeded? Non-Goals ¶ What is out of scope for this KEP? Listing non-goals helps to focus discussion and make progress. Proposal ¶ This is where we get down to the nitty gritty of what the proposal actually is. User Stories [optional] ¶ Detail the things that people will be able to do if this KEP is implemented. Include as much detail as possible so that people can understand the "how" of the system. The goal here is to make this feel real for users without getting bogged down. Story 1 ¶ Story 2 ¶ Implementation Details/Notes/Constraints [optional] ¶ What are the caveats to the implementation? What are some important details that didn't come across above. Go in to as much detail as necessary here. This might be a good place to talk about core concepts and how they relate. Risks and Mitigations ¶ What are the risks of this proposal and how do we mitigate. Think broadly. For example, consider both security and how this will impact the larger kubernetes ecosystem. How will security be reviewed and by whom? How will UX be reviewed and by whom? Consider including folks that also work outside project. Design Details ¶ Test Plan ¶ Note: Section not required until targeted at a release. Consider the following in developing a test plan for this enhancement: Will there be e2e and integration tests, in addition to unit tests? How will it be tested in isolation vs with other components? No need to outline all of the test cases, just the general strategy. Anything that would count as tricky in the implementation and anything particularly challenging to test should be called out. All code is expected to have adequate tests (eventually with coverage expectations). Please adhere to the Kubernetes testing guidelines when drafting this test plan. Removing a deprecated flag ¶ Announce deprecation and support policy of the existing flag Two versions passed since introducing the functionality which deprecates the flag (to address version skew) Address feedback on usage/changed behavior, provided on GitHub issues Deprecate the flag Implementation History ¶ Major milestones in the life cycle of a KEP should be tracked in Implementation History. Major milestones might include the Summary and Motivation sections being merged signaling acceptance the Proposal section being merged signaling agreement on a proposed design the date implementation started the first Kubernetes release where an initial version of the KEP was available the version of Kubernetes where the KEP graduated to general availability when the KEP was retired or superseded Drawbacks [optional] ¶ Why should this KEP not be implemented. Alternatives [optional] ¶ Similar to the Drawbacks section the Alternatives section is used to highlight and record other possible approaches to delivering the value proposed by a KEP. Skip to content NGINX Ingress Controller Kubernetes Enhancement Proposals (KEPs) Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Quick start for the KEP process Do I have to use the KEP process? Why would I want to use the KEP process? Kubernetes Enhancement Proposals (KEPs) ¶ A Kubernetes Enhancement Proposal (KEP) is a way to propose, communicate and coordinate on new efforts for the Kubernetes project. For this reason, the ingress-nginx project is adopting it. Quick start for the KEP process ¶ Follow the process outlined in the KEP template Do I have to use the KEP process? ¶ No... but we hope that you will. Over time having a rich set of KEPs in one place will make it easier for people to track what is going on in the community and find a structured historic record. KEPs are only required when the changes are wide ranging and impact most of the project. Why would I want to use the KEP process? ¶ Our aim with KEPs is to clearly communicate new efforts to the Kubernetes contributor community. As such, we want to build a well curated set of clear proposals in a common format with useful metadata. Benefits to KEP users (in the limit): Exposure on a kubernetes blessed web site that is findable via web search engines. Cross indexing of KEPs so that users can find connections and the current status of any KEP. A clear process with approvers and reviewers for making decisions. This will lead to more structured decisions that stick as there is a discoverable record around the decisions. We are inspired by IETF RFCs, Python PEPs, and Rust RFCs. Skip to content Ingress-Nginx Controller Kubernetes Enhancement Proposals (KEPs) Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Quick start for the KEP process Do I have to use the KEP process? Why would I want to use the KEP process? Kubernetes Enhancement Proposals (KEPs) ¶ A Kubernetes Enhancement Proposal (KEP) is a way to propose, communicate and coordinate on new efforts for the Kubernetes project. For this reason, the ingress-nginx project is adopting it. Quick start for the KEP process ¶ Follow the process outlined in the KEP template Do I have to use the KEP process? ¶ No... but we hope that you will. Over time having a rich set of KEPs in one place will make it easier for people to track what is going on in the community and find a structured historic record. KEPs are only required when the changes are wide ranging and impact most of the project. Why would I want to use the KEP process? ¶ Our aim with KEPs is to clearly communicate new efforts to the Kubernetes contributor community. As such, we want to build a well curated set of clear proposals in a common format with useful metadata. Benefits to KEP users (in the limit): Exposure on a kubernetes blessed web site that is findable via web search engines. Cross indexing of KEPs so that users can find connections and the current status of any KEP. A clear process with approvers and reviewers for making decisions. This will lead to more structured decisions that stick as there is a discoverable record around the decisions. We are inspired by IETF RFCs, Python PEPs, and Rust RFCs. Skip to content NGINX Ingress Controller Prerequisites Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Prerequisites Table of contents TLS certificates Client Certificate Authentication Test HTTP Service Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents TLS certificates Client Certificate Authentication Test HTTP Service Prerequisites ¶ Many of the examples in this directory have common prerequisites. TLS certificates ¶ Unless otherwise mentioned, the TLS secret used in examples is a 2048 bit RSA key/cert pair with an arbitrarily chosen hostname, created as follows $ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=nginxsvc/O=nginxsvc" + Prerequisites - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Prerequisites Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Prerequisites Table of contents TLS certificates Client Certificate Authentication Test HTTP Service Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents TLS certificates Client Certificate Authentication Test HTTP Service Prerequisites ¶ Many of the examples in this directory have common prerequisites. TLS certificates ¶ Unless otherwise mentioned, the TLS secret used in examples is a 2048 bit RSA key/cert pair with an arbitrarily chosen hostname, created as follows $ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=nginxsvc/O=nginxsvc" Generating a 2048 bit RSA private key ................+++ ................+++ diff --git a/examples/affinity/cookie/index.html b/examples/affinity/cookie/index.html index e32048cd3..2e403cf3d 100644 --- a/examples/affinity/cookie/index.html +++ b/examples/affinity/cookie/index.html @@ -1,4 +1,4 @@ - Sticky Sessions - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sticky Sessions Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Sticky Sessions Table of contents Deployment Validation Caveats Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Validation Caveats Sticky sessions ¶ This example demonstrates how to achieve session affinity using cookies. Deployment ¶ Session affinity can be configured using the following annotations: Name Description Value nginx.ingress.kubernetes.io/affinity Type of the affinity, set this to cookie to enable session affinity string (NGINX only supports cookie) nginx.ingress.kubernetes.io/affinity-mode The affinity mode defines how sticky a session is. Use balanced to redistribute some sessions when scaling pods or persistent for maximum stickiness. balanced (default) or persistent nginx.ingress.kubernetes.io/affinity-canary-behavior Defines session affinity behavior of canaries. By default the behavior is sticky, and canaries respect session affinity configuration. Set this to legacy to restore original canary behavior, when session affinity parameters were not respected. sticky (default) or legacy nginx.ingress.kubernetes.io/session-cookie-name Name of the cookie that will be created string (defaults to INGRESSCOOKIE) nginx.ingress.kubernetes.io/session-cookie-secure Set the cookie as secure regardless the protocol of the incoming request "true" or "false" nginx.ingress.kubernetes.io/session-cookie-path Path that will be set on the cookie (required if your Ingress paths use regular expressions) string (defaults to the currently matched path) nginx.ingress.kubernetes.io/session-cookie-domain Domain that will be set on the cookie string nginx.ingress.kubernetes.io/session-cookie-samesite SameSite attribute to apply to the cookie Browser accepted values are None, Lax, and Strict nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none Will omit SameSite=None attribute for older browsers which reject the more-recently defined SameSite=None value "true" or "false" nginx.ingress.kubernetes.io/session-cookie-max-age Time until the cookie expires, corresponds to the Max-Age cookie directive number of seconds nginx.ingress.kubernetes.io/session-cookie-expires Legacy version of the previous annotation for compatibility with older browsers, generates an Expires cookie directive by adding the seconds to the current date number of seconds nginx.ingress.kubernetes.io/session-cookie-change-on-failure When set to false nginx ingress will send request to upstream pointed by sticky cookie even if previous attempt failed. When set to true and previous attempt failed, sticky cookie will be changed to point to another upstream. true or false (defaults to false) You can create the session affinity example Ingress to test this: kubectl create -f ingress.yaml + Sticky Sessions - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sticky Sessions Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Sticky Sessions Table of contents Deployment Validation Caveats Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Validation Caveats Sticky sessions ¶ This example demonstrates how to achieve session affinity using cookies. Deployment ¶ Session affinity can be configured using the following annotations: Name Description Value nginx.ingress.kubernetes.io/affinity Type of the affinity, set this to cookie to enable session affinity string (NGINX only supports cookie) nginx.ingress.kubernetes.io/affinity-mode The affinity mode defines how sticky a session is. Use balanced to redistribute some sessions when scaling pods or persistent for maximum stickiness. balanced (default) or persistent nginx.ingress.kubernetes.io/affinity-canary-behavior Defines session affinity behavior of canaries. By default the behavior is sticky, and canaries respect session affinity configuration. Set this to legacy to restore original canary behavior, when session affinity parameters were not respected. sticky (default) or legacy nginx.ingress.kubernetes.io/session-cookie-name Name of the cookie that will be created string (defaults to INGRESSCOOKIE) nginx.ingress.kubernetes.io/session-cookie-secure Set the cookie as secure regardless the protocol of the incoming request "true" or "false" nginx.ingress.kubernetes.io/session-cookie-path Path that will be set on the cookie (required if your Ingress paths use regular expressions) string (defaults to the currently matched path) nginx.ingress.kubernetes.io/session-cookie-domain Domain that will be set on the cookie string nginx.ingress.kubernetes.io/session-cookie-samesite SameSite attribute to apply to the cookie Browser accepted values are None, Lax, and Strict nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none Will omit SameSite=None attribute for older browsers which reject the more-recently defined SameSite=None value "true" or "false" nginx.ingress.kubernetes.io/session-cookie-max-age Time until the cookie expires, corresponds to the Max-Age cookie directive number of seconds nginx.ingress.kubernetes.io/session-cookie-expires Legacy version of the previous annotation for compatibility with older browsers, generates an Expires cookie directive by adding the seconds to the current date number of seconds nginx.ingress.kubernetes.io/session-cookie-change-on-failure When set to false nginx ingress will send request to upstream pointed by sticky cookie even if previous attempt failed. When set to true and previous attempt failed, sticky cookie will be changed to point to another upstream. true or false (defaults to false) You can create the session affinity example Ingress to test this: kubectl create -f ingress.yaml Validation ¶ You can confirm that the Ingress works: $ kubectl describe ing nginx-test Name: nginx-test Namespace: default @@ -31,7 +31,7 @@ Last-Modified: Tue, 24 Jan 2017 14:02:19 GMT ETag: "58875e6b-264" Accept-Ranges: bytes - In the example above, you can see that the response contains a Set-Cookie header with the settings we have defined. This cookie is created by the NGINX Ingress Controller, it contains a randomly generated key corresponding to the upstream used for that request (selected using consistent hashing) and has an Expires directive. If a client sends a cookie that doesn't correspond to an upstream, NGINX selects an upstream and creates a corresponding cookie. If the backend pool grows NGINX will keep sending the requests through the same server of the first request, even if it's overloaded. When the backend server is removed, the requests are re-routed to another upstream server. This does not require the cookie to be updated because the key's consistent hash will change. Caveats ¶ When you have a Service pointing to more than one Ingress, with only one containing affinity configuration, the first created Ingress will be used. This means that you can face the situation that you've configured session affinity on one Ingress and it doesn't work because the Service is pointing to another Ingress that doesn't configure this. Skip to content NGINX Ingress Controller Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Basic Authentication Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Basic Authentication ¶ This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with htpasswd. It's important the file generated is named auth (actually - that the secret has a key data.auth), otherwise the ingress-controller returns a 503. Create htpasswd file ¶ $ htpasswd -c auth foo + Basic Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Basic Authentication Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Basic Authentication ¶ This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with htpasswd. It's important the file generated is named auth (actually - that the secret has a key data.auth), otherwise the ingress-controller returns a 503. Create htpasswd file ¶ $ htpasswd -c auth foo New password: <bar> New password: Re-type new password: diff --git a/examples/auth/client-certs/index.html b/examples/auth/client-certs/index.html index 8b7f00ce4..fbf4a96af 100644 --- a/examples/auth/client-certs/index.html +++ b/examples/auth/client-certs/index.html @@ -1,4 +1,4 @@ - Client Certificate Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller Client Certificate Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication Client Certificate Authentication Table of contents Creating Certificate Secrets Setup Instructions External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Creating Certificate Secrets Setup Instructions Client Certificate Authentication ¶ It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource. Before getting started you must have the following Certificates configured: CA certificate and Key (Intermediate Certs need to be in CA) Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use) Client Certificate (Signed by CA) and Key For more details on the generation process, checkout the Prerequisite docs. You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following: openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem + Client Certificate Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Client Certificate Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication Client Certificate Authentication Table of contents Creating Certificate Secrets Setup Instructions External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Creating Certificate Secrets Setup Instructions Client Certificate Authentication ¶ It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource. Before getting started you must have the following Certificates configured: CA certificate and Key (Intermediate Certs need to be in CA) Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use) Client Certificate (Signed by CA) and Key For more details on the generation process, checkout the Prerequisite docs. You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following: openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem Then, you can concatenate them all into one file, named 'ca.crt' with the following: cat certificate1.crt certificate2.crt certificate3.crt >> ca.crt Note: Make sure that the Key Size is greater than 1024 and Hashing Algorithm (Digest) is something better than md5 for each certificate generated. Otherwise you will receive an error. Creating Certificate Secrets ¶ There are many different ways of configuring your secrets to enable Client-Certificate Authentication to work properly. You can create a secret containing just the CA certificate and another Secret containing the Server Certificate which is Signed by the CA. kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt kubectl create secret generic tls-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key diff --git a/examples/auth/external-auth/index.html b/examples/auth/external-auth/index.html index 11e3532f8..92246dfe9 100644 --- a/examples/auth/external-auth/index.html +++ b/examples/auth/external-auth/index.html @@ -1,4 +1,4 @@ - External Basic Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml + External Basic Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml ingress "external-auth" created $ kubectl get ing external-auth diff --git a/examples/auth/oauth-external-auth/index.html b/examples/auth/oauth-external-auth/index.html index b8f965b29..49db55e3b 100644 --- a/examples/auth/oauth-external-auth/index.html +++ b/examples/auth/oauth-external-auth/index.html @@ -1,4 +1,4 @@ - External OAUTH Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... + External OAUTH Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... metadata: name: application annotations: diff --git a/examples/customization/configuration-snippets/index.html b/examples/customization/configuration-snippets/index.html index 5f11f913a..45c6ffd1e 100644 --- a/examples/customization/configuration-snippets/index.html +++ b/examples/customization/configuration-snippets/index.html @@ -1,4 +1,4 @@ - Configuration Snippets - NGINX Ingress Controller Skip to content NGINX Ingress Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml + Configuration Snippets - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml Test ¶ Check if the contents of the annotation are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml + Custom Configuration - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml apiVersion: v1 data: proxy-connect-timeout: "10" diff --git a/examples/customization/custom-errors/index.html b/examples/customization/custom-errors/index.html index cae969aeb..2b1b16f7d 100644 --- a/examples/customization/custom-errors/index.html +++ b/examples/customization/custom-errors/index.html @@ -1,4 +1,4 @@ - Custom Errors - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml + Custom Errors - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml service "nginx-errors" created deployment.apps "nginx-errors" created This should have created a Deployment and a Service with the name nginx-errors. $ kubectl get deploy,svc @@ -7,7 +7,7 @@ deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s - Ingress controller configuration ¶ If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the NGINX Ingress controller Service. $ kubectl get svc ingress-nginx + Ingress controller configuration ¶ If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the Ingress-Nginx Controller Service. $ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example. Testing error pages ¶ Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/ diff --git a/examples/customization/custom-headers/index.html b/examples/customization/custom-headers/index.html index ddd97dc36..ca6c12c4a 100644 --- a/examples/customization/custom-headers/index.html +++ b/examples/customization/custom-headers/index.html @@ -1,6 +1,6 @@ - Custom Headers - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Installation Guide ¶ There are multiple ways to install the NGINX ingress controller: with Helm, using the project repository chart; with kubectl apply, using YAML manifests; with specific addons (e.g. for minikube or MicroK8s). On most Kubernetes clusters, the ingress controller will work without requiring any extra configuration. If you want to get started as fast as possible, you can check the quick start instructions. However, in many environments, you can improve the performance or get better logs by enabling extra features. We recommend that you check the environment-specific instructions for details about optimizing the ingress controller for your particular environment or cloud provider. Contents ¶ Quick start Environment-specific instructions ... Docker Desktop ... Rancher Desktop ... minikube ... MicroK8s ... AWS ... GCE - GKE ... Azure ... Digital Ocean ... Scaleway ... Exoscale ... Oracle Cloud Infrastructure ... OVHcloud ... Bare-metal Miscellaneous Quick start Environment-specific instructions ... Docker Desktop ... Rancher Desktop ... minikube ... MicroK8s ... AWS ... GCE - GKE ... Azure ... Digital Ocean ... Scaleway ... Exoscale ... Oracle Cloud Infrastructure ... OVHcloud ... Bare-metal Miscellaneous e2e test suite for Ingress NGINX Controller ¶ [Admission] admission controller ¶ reject ingress with global-rate-limit annotations when memcached is not configured should not allow overlaps of host and paths without canary annotations should allow overlaps of host and paths with canary annotation should block ingress with invalid path should return an error if there is an error validating the ingress definition should return an error if there is an invalid value in some annotation should return an error if there is a forbidden value in some annotation should not return an error if the Ingress V1 definition is valid with Ingress Class should not return an error if the Ingress V1 definition is valid with IngressClass annotation should return an error if the Ingress V1 definition contains invalid annotations should not return an error for an invalid Ingress when it has unknown class affinitymode ¶ Balanced affinity mode should balance Check persistent affinity mode server-alias ¶ should return status code 200 for host 'foo' and 404 for 'bar' should return status code 200 for host 'foo' and 'bar' should return status code 200 for hosts defined in two ingresses, different path with one alias app-root ¶ should redirect to /foo auth-tls-* ¶ should set sslClientCertificate, sslVerifyClient and sslVerifyDepth with auth-tls-secret should set valid auth-tls-secret, sslVerify to off, and sslVerifyDepth to 2 should 302 redirect to error page instead of 400 when auth-tls-error-page is set should pass URL-encoded certificate to upstream should validate auth-tls-verify-client should return 403 using auth-tls-match-cn with no matching CN from client should return 200 using auth-tls-match-cn with matching CN from client should return 200 using auth-tls-match-cn where atleast one of the regex options matches CN from client backend-protocol ¶ should set backend protocol to https:// and use proxy_pass should set backend protocol to $scheme:// and use proxy_pass should set backend protocol to grpc:// and use grpc_pass should set backend protocol to grpcs:// and use grpc_pass should set backend protocol to '' and use fastcgi_pass should set backend protocol to '' and use ajp_pass client-body-buffer-size ¶ should set client_body_buffer_size to 1000 should set client_body_buffer_size to 1K should set client_body_buffer_size to 1k should set client_body_buffer_size to 1m should set client_body_buffer_size to 1M should not set client_body_buffer_size to invalid 1b connection-proxy-header ¶ set connection header to keep-alive cors-* ¶ should enable cors should set cors methods to only allow POST, GET should set cors max-age should disable cors allow credentials should allow origin for cors should allow headers for cors should expose headers for cors should allow - single origin for multiple cors values should not allow - single origin for multiple cors values should allow correct origins - single origin for multiple cors values should not break functionality should not break functionality with extra domain should not match should allow - single origin with required port should not allow - single origin with port and origin without port should not allow - single origin without port and origin with required port should allow - matching origin with wildcard origin (2 subdomains) should not allow - unmatching origin with wildcard origin (2 subdomains) should allow - matching origin+port with wildcard origin should not allow - portless origin with wildcard origin should allow correct origins - missing subdomain + origin with wildcard origin and correct origin should allow - missing origins (should allow all origins) custom-http-errors ¶ configures Nginx correctly default-backend ¶ should use a custom default backend as upstream disable-access-log disable-http-access-log disable-stream-access-log ¶ disable-access-log set access_log off disable-http-access-log set access_log off disable-stream-access-log set access_log off force-ssl-redirect ¶ should redirect to https from-to-www-redirect ¶ should redirect from www HTTP to HTTP should redirect from www HTTPS to HTTPS annotation-global-rate-limit ¶ generates correct configuration backend-protocol - GRPC ¶ should use grpc_pass in the configuration file should return OK for service with backend protocol GRPC authorization metadata should be overwritten by external auth response headers should return OK for service with backend protocol GRPCS http2-push-preload ¶ enable the http2-push-preload directive whitelist-source-range ¶ should set valid ip whitelist range Annotation - limit-connections ¶ should limit-connections limit-rate ¶ Check limit-rate annotation enable-access-log enable-rewrite-log ¶ set access_log off set rewrite_log on mirror-* ¶ should set mirror-target to http://localhost/mirror should set mirror-target to https://test.env.com/$request_uri should disable mirror-request-body modsecurity owasp ¶ should enable modsecurity should enable modsecurity with transaction ID and OWASP rules should disable modsecurity should enable modsecurity with snippet should enable modsecurity without using 'modsecurity on;' should disable modsecurity using 'modsecurity off;' should enable modsecurity with snippet and block requests should enable modsecurity globally and with modsecurity-snippet block requests should enable modsecurity when enable-owasp-modsecurity-crs is set to true should enable modsecurity through the config map should enable modsecurity through the config map but ignore snippet as disabled by admin should disable default modsecurity conf setting when modsecurity-snippet is specified preserve-trailing-slash ¶ should allow preservation of trailing slashes proxy-* ¶ should set proxy_redirect to off should set proxy_redirect to default should set proxy_redirect to hello.com goodbye.com should set proxy client-max-body-size to 8m should not set proxy client-max-body-size to incorrect value should set valid proxy timeouts should not set invalid proxy timeouts should turn on proxy-buffering should turn off proxy-request-buffering should build proxy next upstream should setup proxy cookies should change the default proxy HTTP version proxy-ssl-* ¶ should set valid proxy-ssl-secret should set valid proxy-ssl-secret, proxy-ssl-verify to on, proxy-ssl-verify-depth to 2, and proxy-ssl-server-name to on should set valid proxy-ssl-secret, proxy-ssl-ciphers to HIGH:!AES should set valid proxy-ssl-secret, proxy-ssl-protocols proxy-ssl-location-only flag should change the nginx config server part permanent-redirect permanent-redirect-code ¶ should respond with a standard redirect code should respond with a custom redirect code satisfy ¶ should configure satisfy directive correctly should allow multiple auth with satisfy any server-snippet ¶ add valid directives to server via server snippet drops server snippet if disabled by the administrator service-upstream ¶ should use the Service Cluster IP and Port should use the Service Cluster IP and Port should not use the Service Cluster IP and Port configuration-snippet ¶ ssl-ciphers ¶ should change ssl ciphers stream-snippet ¶ should add value of stream-snippet to nginx config should add stream-snippet and drop annotations per admin config upstream-hash-by-* ¶ should connect to the same pod should connect to the same subset of pods upstream-vhost ¶ set host to upstreamvhost.bar.com x-forwarded-prefix ¶ should set the X-Forwarded-Prefix to the annotation value should not add X-Forwarded-Prefix if the annotation value is empty denylist-source-range ¶ only deny explicitly denied IPs, allow all others only allow explicitly allowed IPs, deny all others affinity session-cookie-name ¶ should set sticky cookie SERVERID should change cookie name on ingress definition change should set the path to /something on the generated cookie does not set the path to / on the generated cookie if there's more than one rule referring to the same backend should set cookie with expires should set cookie with domain should not set cookie without domain annotation should work with use-regex annotation and session-cookie-path should warn user when use-regex is true and session-cookie-path is not set should not set affinity across all server locations when using separate ingresses should set sticky cookie without host should work with server-alias annotation should set secure in cookie with provided true annotation on http should not set secure in cookie with provided false annotation on http should set secure in cookie with provided false annotation on https rewrite-target use-regex enable-rewrite-log ¶ should write rewrite logs should use correct longest path match should use ~* location modifier if regex annotation is present should fail to use longest match for documented warning should allow for custom rewrite parameters backend-protocol - FastCGI ¶ should use fastcgi_pass in the configuration file should add fastcgi_index in the configuration file should add fastcgi_param in the configuration file should return OK for service with backend protocol FastCGI auth-* ¶ should return status code 200 when no authentication is configured should return status code 503 when authentication is configured with an invalid secret should return status code 401 when authentication is configured but Authorization header is not configured should return status code 401 when authentication is configured and Authorization header is sent with invalid credentials should return status code 401 and cors headers when authentication and cors is configured but Authorization header is not configured should return status code 200 when authentication is configured and Authorization header is sent should return status code 200 when authentication is configured with a map and Authorization header is sent should return status code 401 when authentication is configured with invalid content and Authorization header is sent when external auth is configured when external auth is not configured when auth-headers are set should set cache_key when external auth cache is configured user retains cookie by default user does not retain cookie if upstream returns error status code user with annotated ingress retains cookie if upstream returns error status code should return status code 200 when signed in should redirect to signin url when not signed in keeps processing new ingresses even if one of the existing ingresses is misconfigured should overwrite Foo header with auth response should not create additional upstream block when auth-keepalive is not set should not create additional upstream block when host part of auth-url contains a variable should not create additional upstream block when auth-keepalive is negative should not create additional upstream block when auth-keepalive is set with HTTP/2 should create additional upstream block when auth-keepalive is set with HTTP/1.x should return status code 200 when signed in should redirect to signin url when not signed in keeps processing new ingresses even if one of the existing ingresses is misconfigured should return status code 200 when signed in after auth backend is deleted should deny login for different location on same server should deny login for different servers should redirect to signin url when not signed in should return 503 (location was denied) should add error to the config canary-* ¶ should response with a 200 status from the mainline upstream when requests are made to the mainline ingress should return 404 status for requests to the canary if no matching ingress is found should return the correct status codes when endpoints are unavailable should route requests to the correct upstream if mainline ingress is created before the canary ingress should route requests to the correct upstream if mainline ingress is created after the canary ingress should route requests to the correct upstream if the mainline ingress is modified should route requests to the correct upstream if the canary ingress is modified should route requests to the correct upstream should route requests to the correct upstream should route requests to the correct upstream should route requests to the correct upstream should routes to mainline upstream when the given Regex causes error should route requests to the correct upstream respects always and never values should route requests only to mainline if canary weight is 0 should route requests only to canary if canary weight is 100 should route requests only to canary if canary weight is equal to canary weight total should route requests split between mainline and canary if canary weight is 50 should route requests split between mainline and canary if canary weight is 100 and weight total is 200 should not use canary as a catch-all server should not use canary with domain as a server does not crash when canary ingress has multiple paths to the same non-matching backend always routes traffic to canary if first request was affinitized to canary (default behavior) always routes traffic to canary if first request was affinitized to canary (explicit sticky behavior) routes traffic to either mainline or canary backend (legacy behavior) Debug CLI ¶ should list the backend servers should get information for a specific backend server should produce valid JSON for /dbg general [Default Backend] custom service ¶ uses custom default backend that returns 200 as status code [Default Backend] ¶ should return 404 sending requests when only a default backend is running enables access logging for default backend disables access logging for default backend [Default Backend] SSL ¶ should return a self generated SSL certificate [Default Backend] change default settings ¶ should apply the annotation to the default backend ¶ [Endpointslices] long service name ¶ should return 200 when service name has max allowed number of characters 63 [TopologyHints] topology aware routing ¶ should return 200 when service has topology hints ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ ¶ [Setting] ¶ ¶ ¶ ¶ ¶ ¶ ¶ [Shutdown] Grace period shutdown ¶ /healthz should return status code 500 during shutdown grace period [Shutdown] ingress controller ¶ should shutdown in less than 60 secons without pending connections should shutdown after waiting 60 seconds for pending connections to be closed should shutdown after waiting 150 seconds for pending connections to be closed [Shutdown] Graceful shutdown with pending request ¶ should let slow requests finish before shutting down [Ingress] DeepInspection ¶ should drop whole ingress if one path matches invalid regex single ingress - multiple hosts ¶ should set the correct $service_name NGINX variable [Ingress] [PathType] exact ¶ should choose exact location for /exact [Ingress] [PathType] mix Exact and Prefix paths ¶ should choose the correct location [Ingress] [PathType] prefix checks ¶ should return 404 when prefix /aaa does not match request /aaaccc [Ingress] definition without host ¶ should set ingress details variables for ingresses without a host should set ingress details variables for ingresses with host without IngressRuleValue, only Backend [Memory Leak] Dynamic Certificates ¶ should not leak memory from ingress SSL certificates or configuration updates [Load Balancer] load-balance ¶ should apply the configmap load-balance setting [Load Balancer] EWMA ¶ does not fail requests [Load Balancer] round-robin ¶ should evenly distribute requests with round-robin (default algorithm) [Lua] dynamic certificates ¶ picks up the certificate when we add TLS spec to existing ingress picks up the previously missing secret for a given ingress without reloading supports requests with domain with trailing dot picks up the updated certificate without reloading falls back to using default certificate when secret gets deleted without reloading picks up a non-certificate only change removes HTTPS configuration when we delete TLS spec [Lua] dynamic configuration ¶ configures balancer Lua middleware correctly handles endpoints only changes handles endpoints only changes (down scaling of replicas) handles endpoints only changes consistently (down scaling of replicas vs. empty service) handles an annotation change nginx-configuration ¶ start nginx with default configuration fails when using alias directive fails when using root directive [Security] request smuggling ¶ should not return body content from error_page [Service] backend status code 503 ¶ should return 503 when backend service does not exist should return 503 when all backend service endpoints are unavailable [Service] Type ExternalName ¶ works with external name set to incomplete fqdn should return 200 for service type=ExternalName without a port defined should return 200 for service type=ExternalName with a port defined should return status 502 for service type=ExternalName with an invalid host should return 200 for service type=ExternalName using a port name should return 200 for service type=ExternalName using FQDN with trailing dot should update the external name after a service update should sync ingress on external name service addition/deletion [Service] Nil Service Backend ¶ should return 404 when backend service is nil access-log ¶ use the default configuration use the specified configuration use the specified configuration use the specified configuration use the specified configuration Bad annotation values ¶ [BAD_ANNOTATIONS] should drop an ingress if there is an invalid character in some annotation [BAD_ANNOTATIONS] should drop an ingress if there is a forbidden word in some annotation [BAD_ANNOTATIONS] should allow an ingress if there is a default blocklist config in place [BAD_ANNOTATIONS] should drop an ingress if there is a custom blocklist config in place and allow others to pass brotli ¶ condition add-headers ¶ Add a custom header Add multiple custom headers [SSL] [Flag] default-ssl-certificate ¶ uses default ssl certificate for catch-all ingress uses default ssl certificate for host based ingress when configured certificate does not match host [Flag] disable-catch-all ¶ should ignore catch all Ingress with backend should ignore catch all Ingress with backend and rules should delete Ingress updated to catch-all should allow Ingress with rules [Flag] disable-service-external-name ¶ should ignore services of external-name type enable-real-ip ¶ trusts X-Forwarded-For header only when setting is true should not trust X-Forwarded-For header when setting is false use-forwarded-headers ¶ should trust X-Forwarded headers when setting is true should not trust X-Forwarded headers when setting is false Geoip2 ¶ should include geoip2 line in config when enabled and db file exists should only allow requests from specific countries [Security] block-* ¶ should block CIDRs defined in the ConfigMap should block User-Agents defined in the ConfigMap should block Referers defined in the ConfigMap [Security] global-auth-url ¶ should return status code 401 when request any protected service should return status code 200 when request whitelisted (via no-auth-locations) service and 401 when request protected service should return status code 200 when request whitelisted (via ingress annotation) service and 401 when request protected service should still return status code 200 after auth backend is deleted using cache should proxy_method method when global-auth-method is configured should add custom error page when global-auth-signin url is configured should add auth headers when global-auth-response-headers is configured should set request-redirect when global-auth-request-redirect is configured should set snippet when global external auth is configured user retains cookie by default user does not retain cookie if upstream returns error status code user with global-auth-always-set-cookie key in configmap retains cookie if upstream returns error status code global-options ¶ should have worker_rlimit_nofile option should have worker_rlimit_nofile option and be independent on amount of worker processes settings-global-rate-limit ¶ generates correct NGINX configuration hash size ¶ should set server_names_hash_bucket_size should set server_names_hash_max_size should set proxy-headers-hash-bucket-size should set proxy-headers-hash-max-size should set variables-hash-bucket-size should set variables-hash-max-size should set vmap-hash-bucket-size [Flag] ingress-class ¶ should ignore Ingress with a different class annotation should ignore Ingress with different controller class should accept both Ingresses with default IngressClassName and IngressClass annotation should ignore Ingress without IngressClass configuration should delete Ingress when class is removed should serve Ingress when class is added should serve Ingress when class is updated between annotation and ingressClassName should ignore Ingress with no class and accept the correctly configured Ingresses should watch Ingress with no class and ignore ingress with a different class should watch Ingress that uses the class name even if spec is different should watch Ingress with correct annotation should ignore Ingress with only IngressClassName keep-alive keep-alive-requests ¶ should set keepalive_timeout should set keepalive_requests should set keepalive connection to upstream server should set keep alive connection timeout to upstream server should set keepalive time to upstream server should set the request count to upstream server through one keep alive connection Configmap - limit-rate ¶ Check limit-rate config [Flag] custom HTTP and HTTPS ports ¶ should set X-Forwarded-Port headers accordingly when listening on a non-default HTTP port should set X-Forwarded-Port header to 443 should set the X-Forwarded-Port header to 443 log-format-* ¶ should not configure log-format escape by default should enable the log-format-escape-json should disable the log-format-escape-json should enable the log-format-escape-none should disable the log-format-escape-none log-format-escape-json enabled log-format default escape log-format-escape-none enabled [Lua] lua-shared-dicts ¶ configures lua shared dicts main-snippet ¶ should add value of main-snippet setting to nginx config [Security] modsecurity-snippet ¶ should add value of modsecurity-snippet setting to nginx config enable-multi-accept ¶ should be enabled by default should be enabled when set to true should be disabled when set to false Add no tls redirect locations ¶ Check no tls redirect locations config OCSP ¶ should enable OCSP and contain stapling information in the connection Configure OpenTracing ¶ should not exists opentracing directive should exists opentracing directive when is enabled should include opentracing_trust_incoming_span off directive when disabled should not exists opentracing_operation_name directive when is empty should exists opentracing_operation_name directive when is configured should not exists opentracing_location_operation_name directive when is empty should exists opentracing_location_operation_name directive when is configured should enable opentracing using zipkin should enable opentracing using jaeger should enable opentracing using jaeger with sampler host should propagate the w3c header when configured with jaeger should enable opentracing using jaeger with an HTTP endpoint should enable opentracing using datadog plugins ¶ should exist a x-hello-world header [Security] Pod Security Policies ¶ should be running with a Pod Security Policy [Security] Pod Security Policies with volumes ¶ should be running with a Pod Security Policy proxy-connect-timeout ¶ should set valid proxy timeouts using configmap values should not set invalid proxy timeouts using configmap values Dynamic $proxy_host ¶ should exist a proxy_host should exist a proxy_host using the upstream-vhost annotation value proxy-next-upstream ¶ should build proxy next upstream using configmap values use-proxy-protocol ¶ should respect port passed by the PROXY Protocol should respect proto passed by the PROXY Protocol server port should enable PROXY Protocol for HTTPS should enable PROXY Protocol for TCP proxy-read-timeout ¶ should set valid proxy read timeouts using configmap values should not set invalid proxy read timeouts using configmap values proxy-send-timeout ¶ should set valid proxy send timeouts using configmap values should not set invalid proxy send timeouts using configmap values reuse-port ¶ reuse port should be enabled by default reuse port should be disabled reuse port should be enabled configmap server-snippet ¶ should add value of server-snippet setting to all ingress config should add global server-snippet and drop annotations per admin config server-tokens ¶ should not exists Server header in the response should exists Server header in the response when is enabled ssl-ciphers ¶ Add ssl ciphers configmap stream-snippet ¶ should add value of stream-snippet via config map to nginx config [SSL] TLS protocols, ciphers and headers) ¶ setting cipher suite setting max-age parameter setting includeSubDomains parameter setting preload parameter overriding what's set from the upstream should not use ports during the HTTP to HTTPS redirection should not use ports or X-Forwarded-Host during the HTTP to HTTPS redirection [Flag] disable-sync-events ¶ should create sync events (default) should create sync events should not create sync events gzip ¶ should be disabled by default should be enabled with default settings should set gzip_comp_level to 4 should set gzip_disable to msie6 should set gzip_min_length to 100 should set gzip_types to application/javascript Configmap change ¶ should reload after an update in the configuration [Flag] watch namespace selector ¶ should ingore Ingress of namespace without label foo=bar and accept those of namespace with label foo=bar With enable-ssl-passthrough enabled ¶ should enable ssl-passthrough-proxy-port on a different port should pass unknown traffic to default backend and handle known traffic [Security] no-auth-locations ¶ should return status code 401 when accessing '/' unauthentication should return status code 200 when accessing '/' authentication should return status code 200 when accessing '/noauth' unauthenticated Configure Opentelemetry ¶ should not exists opentelemetry directive should exists opentelemetry directive when is enabled should include opentelemetry_trust_incoming_spans on directive when enabled should not exists opentelemetry_operation_name directive when is empty should exists opentelemetry_operation_name directive when is configured [SSL] redirect to HTTPS ¶ should redirect from HTTP to HTTPS when secret is missing [SSL] secret update ¶ should not appear references to secret updates not used in ingress rules should return the fake SSL certificate if the secret is invalid [Status] status update ¶ should update status field after client-go reconnection [TCP] tcp-services ¶ should expose a TCP service should expose an ExternalName TCP service should reload after an update in the configuration ¶ [metrics] exported prometheus metrics ¶ exclude socket request metrics are absent exclude socket request metrics are present
Remove static SSL configuration mode ¶ Table of Contents ¶ Summary Motivation Goals Non-Goals Proposal Implementation Details/Notes/Constraints Drawbacks Alternatives Summary ¶ Since release 0.19.0 is possible to configure SSL certificates without the need of NGINX reloads (thanks to lua) and after release 0.24.0 the default enabled mode is dynamic. Motivation ¶ The static configuration implies reloads, something that affects the majority of the users. Goals ¶ Deprecation of the flag --enable-dynamic-certificates. Cleanup of the codebase. Non-Goals ¶ Features related to certificate authentication are not changed in any way. Proposal ¶ Remove static SSL configuration Implementation Details/Notes/Constraints ¶ Deprecate the flag Move the directives ssl_certificate and ssl_certificate_key from each server block to the http section. These settings are required to avoid NGINX errors in the logs. Remove any action of the flag --enable-dynamic-certificates Drawbacks ¶ Alternatives ¶ Keep both implementations
Remove static SSL configuration mode ¶ Table of Contents ¶ Summary Motivation Goals Non-Goals Proposal Implementation Details/Notes/Constraints Drawbacks Alternatives Summary ¶ Since release 0.19.0 is possible to configure SSL certificates without the need of NGINX reloads (thanks to lua) and after release 0.24.0 the default enabled mode is dynamic. Motivation ¶ The static configuration implies reloads, something that affects the majority of the users. Goals ¶ Deprecation of the flag --enable-dynamic-certificates. Cleanup of the codebase. Non-Goals ¶ Features related to certificate authentication are not changed in any way. Proposal ¶ Remove static SSL configuration Implementation Details/Notes/Constraints ¶ Deprecate the flag Move the directives ssl_certificate and ssl_certificate_key from each server block to the http section. These settings are required to avoid NGINX errors in the logs. Remove any action of the flag --enable-dynamic-certificates Drawbacks ¶ Alternatives ¶ Keep both implementations
Availability zone aware routing ¶ Table of Contents ¶ Availability zone aware routing Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation History Drawbacks [optional] Summary ¶ Teach ingress-nginx about availability zones where endpoints are running in. This way ingress-nginx pod will do its best to proxy to zone-local endpoint. Motivation ¶ When users run their services across multiple availability zones they usually pay for egress traffic between zones. Providers such as GCP, and Amazon EC2 usually charge extra for this feature. ingress-nginx when picking an endpoint to route request to does not consider whether the endpoint is in a different zone or the same one. That means it's at least equally likely that it will pick an endpoint from another zone and proxy the request to it. In this situation response from the endpoint to the ingress-nginx pod is considered inter-zone traffic and usually costs extra money. At the time of this writing, GCP charges $0.01 per GB of inter-zone egress traffic according to https://cloud.google.com/compute/network-pricing. According to https://datapath.io/resources/blog/what-are-aws-data-transfer-costs-and-how-to-minimize-them/ Amazon also charges the same amount of money as GCP for cross-zone, egress traffic. This can be a lot of money depending on once's traffic. By teaching ingress-nginx about zones we can eliminate or at least decrease this cost. Arguably inter-zone network latency should also be better than cross-zone. Goals ¶ Given a regional cluster running ingress-nginx, ingress-nginx should do best-effort to pick a zone-local endpoint when proxying This should not impact canary feature ingress-nginx should be able to operate successfully if there are no zonal endpoints Non-Goals ¶ This feature inherently assumes that endpoints are distributed across zones in a way that they can handle all the traffic from ingress-nginx pod(s) in that zone This feature will be relying on https://kubernetes.io/docs/reference/kubernetes-api/labels-annotations-taints/#failure-domainbetakubernetesiozone, it is not this KEP's goal to support other cases Proposal ¶ The idea here is to have the controller part of ingress-nginx (1) detect what zone its current pod is running in and (2) detect the zone for every endpoint it knows about. After that, it will post that data as part of endpoints to Lua land. When picking an endpoint, the Lua balancer will try to pick zone-local endpoint first and if there is no zone-local endpoint then it will fall back to current behavior. Initially, this feature should be optional since it is going to make it harder to reason about the load balancing and not everyone might want that. How does controller know what zone it runs in? We can have the pod spec pass the node name using downward API as an environment variable. Upon startup, the controller can get node details from the API based on the node name. Once the node details are obtained we can extract the zone from the failure-domain.beta.kubernetes.io/zone annotation. Then we can pass that value to Lua land through Nginx configuration when loading lua_ingress.lua module in init_by_lua phase. How do we extract zones for endpoints? We can have the controller watch create and update events on nodes in the entire cluster and based on that keep the map of nodes to zones in the memory. And when we generate endpoints list, we can access node name using .subsets.addresses[i].nodeName and based on that fetch zone from the map in memory and store it as a field on the endpoint. This solution assumes failure-domain.beta.kubernetes.io/zone annotation does not change until the end of the node's life. Otherwise, we have to watch update events as well on the nodes and that'll add even more overhead. Alternatively, we can get the list of nodes only when there's no node in the memory for the given node name. This is probably a better solution because then we would avoid watching for API changes on node resources. We can eagerly fetch all the nodes and build node name to zone mapping on start. From there on, it will sync during endpoint building in the main event loop if there's no existing entry for the node of an endpoint. This means an extra API call in case cluster has expanded. How do we make sure we do our best to choose zone-local endpoint? This will be done on the Lua side. For every backend, we will initialize two balancer instances: (1) with all endpoints (2) with all endpoints corresponding to the current zone for the backend. Then given the request once we choose what backend needs to serve the request, we will first try to use a zonal balancer for that backend. If a zonal balancer does not exist (i.e. there's no zonal endpoint) then we will use a general balancer. In case of zonal outages, we assume that the readiness probe will fail and the controller will see no endpoints for the backend and therefore we will use a general balancer. We can enable the feature using a configmap setting. Doing it this way makes it easier to rollback in case of a problem. Implementation History ¶ initial version of KEP is shipped proposal and implementation details are done Drawbacks [optional] ¶ More load on the Kubernetes API server.
Availability zone aware routing ¶ Table of Contents ¶ Availability zone aware routing Table of Contents Summary Motivation Goals Non-Goals Proposal Implementation History Drawbacks [optional] Summary ¶ Teach ingress-nginx about availability zones where endpoints are running in. This way ingress-nginx pod will do its best to proxy to zone-local endpoint. Motivation ¶ When users run their services across multiple availability zones they usually pay for egress traffic between zones. Providers such as GCP, and Amazon EC2 usually charge extra for this feature. ingress-nginx when picking an endpoint to route request to does not consider whether the endpoint is in a different zone or the same one. That means it's at least equally likely that it will pick an endpoint from another zone and proxy the request to it. In this situation response from the endpoint to the ingress-nginx pod is considered inter-zone traffic and usually costs extra money. At the time of this writing, GCP charges $0.01 per GB of inter-zone egress traffic according to https://cloud.google.com/compute/network-pricing. According to https://datapath.io/resources/blog/what-are-aws-data-transfer-costs-and-how-to-minimize-them/ Amazon also charges the same amount of money as GCP for cross-zone, egress traffic. This can be a lot of money depending on once's traffic. By teaching ingress-nginx about zones we can eliminate or at least decrease this cost. Arguably inter-zone network latency should also be better than cross-zone. Goals ¶ Given a regional cluster running ingress-nginx, ingress-nginx should do best-effort to pick a zone-local endpoint when proxying This should not impact canary feature ingress-nginx should be able to operate successfully if there are no zonal endpoints Non-Goals ¶ This feature inherently assumes that endpoints are distributed across zones in a way that they can handle all the traffic from ingress-nginx pod(s) in that zone This feature will be relying on https://kubernetes.io/docs/reference/kubernetes-api/labels-annotations-taints/#failure-domainbetakubernetesiozone, it is not this KEP's goal to support other cases Proposal ¶ The idea here is to have the controller part of ingress-nginx (1) detect what zone its current pod is running in and (2) detect the zone for every endpoint it knows about. After that, it will post that data as part of endpoints to Lua land. When picking an endpoint, the Lua balancer will try to pick zone-local endpoint first and if there is no zone-local endpoint then it will fall back to current behavior. Initially, this feature should be optional since it is going to make it harder to reason about the load balancing and not everyone might want that. How does controller know what zone it runs in? We can have the pod spec pass the node name using downward API as an environment variable. Upon startup, the controller can get node details from the API based on the node name. Once the node details are obtained we can extract the zone from the failure-domain.beta.kubernetes.io/zone annotation. Then we can pass that value to Lua land through Nginx configuration when loading lua_ingress.lua module in init_by_lua phase. How do we extract zones for endpoints? We can have the controller watch create and update events on nodes in the entire cluster and based on that keep the map of nodes to zones in the memory. And when we generate endpoints list, we can access node name using .subsets.addresses[i].nodeName and based on that fetch zone from the map in memory and store it as a field on the endpoint. This solution assumes failure-domain.beta.kubernetes.io/zone annotation does not change until the end of the node's life. Otherwise, we have to watch update events as well on the nodes and that'll add even more overhead. Alternatively, we can get the list of nodes only when there's no node in the memory for the given node name. This is probably a better solution because then we would avoid watching for API changes on node resources. We can eagerly fetch all the nodes and build node name to zone mapping on start. From there on, it will sync during endpoint building in the main event loop if there's no existing entry for the node of an endpoint. This means an extra API call in case cluster has expanded. How do we make sure we do our best to choose zone-local endpoint? This will be done on the Lua side. For every backend, we will initialize two balancer instances: (1) with all endpoints (2) with all endpoints corresponding to the current zone for the backend. Then given the request once we choose what backend needs to serve the request, we will first try to use a zonal balancer for that backend. If a zonal balancer does not exist (i.e. there's no zonal endpoint) then we will use a general balancer. In case of zonal outages, we assume that the readiness probe will fail and the controller will see no endpoints for the backend and therefore we will use a general balancer. We can enable the feature using a configmap setting. Doing it this way makes it easier to rollback in case of a problem. Implementation History ¶ initial version of KEP is shipped proposal and implementation details are done Drawbacks [optional] ¶ More load on the Kubernetes API server.
Title ¶ This is the title of the KEP. Keep it simple and descriptive. A good title can help communicate what the KEP is and should be considered as part of any review. The title should be lowercased and spaces/punctuation should be replaced with -. To get started with this template: Make a copy of this template. Create a copy of this template and name it YYYYMMDD-my-title.md, where YYYYMMDD is the date the KEP was first drafted. Fill out the "overview" sections. This includes the Summary and Motivation sections. These should be easy if you've preflighted the idea of the KEP in an issue. Create a PR. Assign it to folks that are sponsoring this process. Create an issue When filing an enhancement tracking issue, please ensure to complete all fields in the template. Merge early. Avoid getting hung up on specific details and instead aim to get the goal of the KEP merged quickly. The best way to do this is to just start with the "Overview" sections and fill out details incrementally in follow on PRs. View anything marked as a provisional as a working document and subject to change. Aim for single topic PRs to keep discussions focused. If you disagree with what is already in a document, open a new PR with suggested changes. The canonical place for the latest set of instructions (and the likely source of this file) is here. The Metadata section above is intended to support the creation of tooling around the KEP process. This will be a YAML section that is fenced as a code block. See the KEP process for details on each of these items. Table of Contents ¶ A table of contents is helpful for quickly jumping to sections of a KEP and for highlighting any additional information provided beyond the standard KEP template. Ensure the TOC is wrapped with <!-- toc --&rt;<!-- /toc --&rt; tags, and then generate with hack/update-toc.sh. Summary Motivation Goals Non-Goals Proposal User Stories [optional] Story 1 Story 2 Implementation Details/Notes/Constraints [optional] Risks and Mitigations Design Details Test Plan Removing a deprecated flag Implementation History Drawbacks [optional] Alternatives [optional] Summary ¶ The Summary section is incredibly important for producing high quality user-focused documentation such as release notes or a development roadmap. It should be possible to collect this information before implementation begins in order to avoid requiring implementers to split their attention between writing release notes and implementing the feature itself. A good summary is probably at least a paragraph in length. Motivation ¶ This section is for explicitly listing the motivation, goals and non-goals of this KEP. Describe why the change is important and the benefits to users. The motivation section can optionally provide links to experience reports to demonstrate the interest in a KEP within the wider Kubernetes community. Goals ¶ List the specific goals of the KEP. How will we know that this has succeeded? Non-Goals ¶ What is out of scope for this KEP? Listing non-goals helps to focus discussion and make progress. Proposal ¶ This is where we get down to the nitty gritty of what the proposal actually is. User Stories [optional] ¶ Detail the things that people will be able to do if this KEP is implemented. Include as much detail as possible so that people can understand the "how" of the system. The goal here is to make this feel real for users without getting bogged down. Story 1 ¶ Story 2 ¶ Implementation Details/Notes/Constraints [optional] ¶ What are the caveats to the implementation? What are some important details that didn't come across above. Go in to as much detail as necessary here. This might be a good place to talk about core concepts and how they relate. Risks and Mitigations ¶ What are the risks of this proposal and how do we mitigate. Think broadly. For example, consider both security and how this will impact the larger kubernetes ecosystem. How will security be reviewed and by whom? How will UX be reviewed and by whom? Consider including folks that also work outside project. Design Details ¶ Test Plan ¶ Note: Section not required until targeted at a release. Consider the following in developing a test plan for this enhancement: Will there be e2e and integration tests, in addition to unit tests? How will it be tested in isolation vs with other components? No need to outline all of the test cases, just the general strategy. Anything that would count as tricky in the implementation and anything particularly challenging to test should be called out. All code is expected to have adequate tests (eventually with coverage expectations). Please adhere to the Kubernetes testing guidelines when drafting this test plan. Removing a deprecated flag ¶ Announce deprecation and support policy of the existing flag Two versions passed since introducing the functionality which deprecates the flag (to address version skew) Address feedback on usage/changed behavior, provided on GitHub issues Deprecate the flag Implementation History ¶ Major milestones in the life cycle of a KEP should be tracked in Implementation History. Major milestones might include the Summary and Motivation sections being merged signaling acceptance the Proposal section being merged signaling agreement on a proposed design the date implementation started the first Kubernetes release where an initial version of the KEP was available the version of Kubernetes where the KEP graduated to general availability when the KEP was retired or superseded Drawbacks [optional] ¶ Why should this KEP not be implemented. Alternatives [optional] ¶ Similar to the Drawbacks section the Alternatives section is used to highlight and record other possible approaches to delivering the value proposed by a KEP.
Title ¶ This is the title of the KEP. Keep it simple and descriptive. A good title can help communicate what the KEP is and should be considered as part of any review. The title should be lowercased and spaces/punctuation should be replaced with -. To get started with this template: Make a copy of this template. Create a copy of this template and name it YYYYMMDD-my-title.md, where YYYYMMDD is the date the KEP was first drafted. Fill out the "overview" sections. This includes the Summary and Motivation sections. These should be easy if you've preflighted the idea of the KEP in an issue. Create a PR. Assign it to folks that are sponsoring this process. Create an issue When filing an enhancement tracking issue, please ensure to complete all fields in the template. Merge early. Avoid getting hung up on specific details and instead aim to get the goal of the KEP merged quickly. The best way to do this is to just start with the "Overview" sections and fill out details incrementally in follow on PRs. View anything marked as a provisional as a working document and subject to change. Aim for single topic PRs to keep discussions focused. If you disagree with what is already in a document, open a new PR with suggested changes. The canonical place for the latest set of instructions (and the likely source of this file) is here. The Metadata section above is intended to support the creation of tooling around the KEP process. This will be a YAML section that is fenced as a code block. See the KEP process for details on each of these items. Table of Contents ¶ A table of contents is helpful for quickly jumping to sections of a KEP and for highlighting any additional information provided beyond the standard KEP template. Ensure the TOC is wrapped with <!-- toc --&rt;<!-- /toc --&rt; tags, and then generate with hack/update-toc.sh. Summary Motivation Goals Non-Goals Proposal User Stories [optional] Story 1 Story 2 Implementation Details/Notes/Constraints [optional] Risks and Mitigations Design Details Test Plan Removing a deprecated flag Implementation History Drawbacks [optional] Alternatives [optional] Summary ¶ The Summary section is incredibly important for producing high quality user-focused documentation such as release notes or a development roadmap. It should be possible to collect this information before implementation begins in order to avoid requiring implementers to split their attention between writing release notes and implementing the feature itself. A good summary is probably at least a paragraph in length. Motivation ¶ This section is for explicitly listing the motivation, goals and non-goals of this KEP. Describe why the change is important and the benefits to users. The motivation section can optionally provide links to experience reports to demonstrate the interest in a KEP within the wider Kubernetes community. Goals ¶ List the specific goals of the KEP. How will we know that this has succeeded? Non-Goals ¶ What is out of scope for this KEP? Listing non-goals helps to focus discussion and make progress. Proposal ¶ This is where we get down to the nitty gritty of what the proposal actually is. User Stories [optional] ¶ Detail the things that people will be able to do if this KEP is implemented. Include as much detail as possible so that people can understand the "how" of the system. The goal here is to make this feel real for users without getting bogged down. Story 1 ¶ Story 2 ¶ Implementation Details/Notes/Constraints [optional] ¶ What are the caveats to the implementation? What are some important details that didn't come across above. Go in to as much detail as necessary here. This might be a good place to talk about core concepts and how they relate. Risks and Mitigations ¶ What are the risks of this proposal and how do we mitigate. Think broadly. For example, consider both security and how this will impact the larger kubernetes ecosystem. How will security be reviewed and by whom? How will UX be reviewed and by whom? Consider including folks that also work outside project. Design Details ¶ Test Plan ¶ Note: Section not required until targeted at a release. Consider the following in developing a test plan for this enhancement: Will there be e2e and integration tests, in addition to unit tests? How will it be tested in isolation vs with other components? No need to outline all of the test cases, just the general strategy. Anything that would count as tricky in the implementation and anything particularly challenging to test should be called out. All code is expected to have adequate tests (eventually with coverage expectations). Please adhere to the Kubernetes testing guidelines when drafting this test plan. Removing a deprecated flag ¶ Announce deprecation and support policy of the existing flag Two versions passed since introducing the functionality which deprecates the flag (to address version skew) Address feedback on usage/changed behavior, provided on GitHub issues Deprecate the flag Implementation History ¶ Major milestones in the life cycle of a KEP should be tracked in Implementation History. Major milestones might include the Summary and Motivation sections being merged signaling acceptance the Proposal section being merged signaling agreement on a proposed design the date implementation started the first Kubernetes release where an initial version of the KEP was available the version of Kubernetes where the KEP graduated to general availability when the KEP was retired or superseded Drawbacks [optional] ¶ Why should this KEP not be implemented. Alternatives [optional] ¶ Similar to the Drawbacks section the Alternatives section is used to highlight and record other possible approaches to delivering the value proposed by a KEP.
Kubernetes Enhancement Proposals (KEPs) ¶ A Kubernetes Enhancement Proposal (KEP) is a way to propose, communicate and coordinate on new efforts for the Kubernetes project. For this reason, the ingress-nginx project is adopting it. Quick start for the KEP process ¶ Follow the process outlined in the KEP template Do I have to use the KEP process? ¶ No... but we hope that you will. Over time having a rich set of KEPs in one place will make it easier for people to track what is going on in the community and find a structured historic record. KEPs are only required when the changes are wide ranging and impact most of the project. Why would I want to use the KEP process? ¶ Our aim with KEPs is to clearly communicate new efforts to the Kubernetes contributor community. As such, we want to build a well curated set of clear proposals in a common format with useful metadata. Benefits to KEP users (in the limit): Exposure on a kubernetes blessed web site that is findable via web search engines. Cross indexing of KEPs so that users can find connections and the current status of any KEP. A clear process with approvers and reviewers for making decisions. This will lead to more structured decisions that stick as there is a discoverable record around the decisions. We are inspired by IETF RFCs, Python PEPs, and Rust RFCs.
Kubernetes Enhancement Proposals (KEPs) ¶ A Kubernetes Enhancement Proposal (KEP) is a way to propose, communicate and coordinate on new efforts for the Kubernetes project. For this reason, the ingress-nginx project is adopting it. Quick start for the KEP process ¶ Follow the process outlined in the KEP template Do I have to use the KEP process? ¶ No... but we hope that you will. Over time having a rich set of KEPs in one place will make it easier for people to track what is going on in the community and find a structured historic record. KEPs are only required when the changes are wide ranging and impact most of the project. Why would I want to use the KEP process? ¶ Our aim with KEPs is to clearly communicate new efforts to the Kubernetes contributor community. As such, we want to build a well curated set of clear proposals in a common format with useful metadata. Benefits to KEP users (in the limit): Exposure on a kubernetes blessed web site that is findable via web search engines. Cross indexing of KEPs so that users can find connections and the current status of any KEP. A clear process with approvers and reviewers for making decisions. This will lead to more structured decisions that stick as there is a discoverable record around the decisions. We are inspired by IETF RFCs, Python PEPs, and Rust RFCs.
Prerequisites ¶ Many of the examples in this directory have common prerequisites. TLS certificates ¶ Unless otherwise mentioned, the TLS secret used in examples is a 2048 bit RSA key/cert pair with an arbitrarily chosen hostname, created as follows $ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=nginxsvc/O=nginxsvc" + Prerequisites - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Prerequisites Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Prerequisites Table of contents TLS certificates Client Certificate Authentication Test HTTP Service Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents TLS certificates Client Certificate Authentication Test HTTP Service Prerequisites ¶ Many of the examples in this directory have common prerequisites. TLS certificates ¶ Unless otherwise mentioned, the TLS secret used in examples is a 2048 bit RSA key/cert pair with an arbitrarily chosen hostname, created as follows $ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=nginxsvc/O=nginxsvc" Generating a 2048 bit RSA private key ................+++ ................+++ diff --git a/examples/affinity/cookie/index.html b/examples/affinity/cookie/index.html index e32048cd3..2e403cf3d 100644 --- a/examples/affinity/cookie/index.html +++ b/examples/affinity/cookie/index.html @@ -1,4 +1,4 @@ - Sticky Sessions - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sticky Sessions Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Sticky Sessions Table of contents Deployment Validation Caveats Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Validation Caveats Sticky sessions ¶ This example demonstrates how to achieve session affinity using cookies. Deployment ¶ Session affinity can be configured using the following annotations: Name Description Value nginx.ingress.kubernetes.io/affinity Type of the affinity, set this to cookie to enable session affinity string (NGINX only supports cookie) nginx.ingress.kubernetes.io/affinity-mode The affinity mode defines how sticky a session is. Use balanced to redistribute some sessions when scaling pods or persistent for maximum stickiness. balanced (default) or persistent nginx.ingress.kubernetes.io/affinity-canary-behavior Defines session affinity behavior of canaries. By default the behavior is sticky, and canaries respect session affinity configuration. Set this to legacy to restore original canary behavior, when session affinity parameters were not respected. sticky (default) or legacy nginx.ingress.kubernetes.io/session-cookie-name Name of the cookie that will be created string (defaults to INGRESSCOOKIE) nginx.ingress.kubernetes.io/session-cookie-secure Set the cookie as secure regardless the protocol of the incoming request "true" or "false" nginx.ingress.kubernetes.io/session-cookie-path Path that will be set on the cookie (required if your Ingress paths use regular expressions) string (defaults to the currently matched path) nginx.ingress.kubernetes.io/session-cookie-domain Domain that will be set on the cookie string nginx.ingress.kubernetes.io/session-cookie-samesite SameSite attribute to apply to the cookie Browser accepted values are None, Lax, and Strict nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none Will omit SameSite=None attribute for older browsers which reject the more-recently defined SameSite=None value "true" or "false" nginx.ingress.kubernetes.io/session-cookie-max-age Time until the cookie expires, corresponds to the Max-Age cookie directive number of seconds nginx.ingress.kubernetes.io/session-cookie-expires Legacy version of the previous annotation for compatibility with older browsers, generates an Expires cookie directive by adding the seconds to the current date number of seconds nginx.ingress.kubernetes.io/session-cookie-change-on-failure When set to false nginx ingress will send request to upstream pointed by sticky cookie even if previous attempt failed. When set to true and previous attempt failed, sticky cookie will be changed to point to another upstream. true or false (defaults to false) You can create the session affinity example Ingress to test this: kubectl create -f ingress.yaml + Sticky Sessions - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sticky Sessions Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Sticky Sessions Table of contents Deployment Validation Caveats Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Validation Caveats Sticky sessions ¶ This example demonstrates how to achieve session affinity using cookies. Deployment ¶ Session affinity can be configured using the following annotations: Name Description Value nginx.ingress.kubernetes.io/affinity Type of the affinity, set this to cookie to enable session affinity string (NGINX only supports cookie) nginx.ingress.kubernetes.io/affinity-mode The affinity mode defines how sticky a session is. Use balanced to redistribute some sessions when scaling pods or persistent for maximum stickiness. balanced (default) or persistent nginx.ingress.kubernetes.io/affinity-canary-behavior Defines session affinity behavior of canaries. By default the behavior is sticky, and canaries respect session affinity configuration. Set this to legacy to restore original canary behavior, when session affinity parameters were not respected. sticky (default) or legacy nginx.ingress.kubernetes.io/session-cookie-name Name of the cookie that will be created string (defaults to INGRESSCOOKIE) nginx.ingress.kubernetes.io/session-cookie-secure Set the cookie as secure regardless the protocol of the incoming request "true" or "false" nginx.ingress.kubernetes.io/session-cookie-path Path that will be set on the cookie (required if your Ingress paths use regular expressions) string (defaults to the currently matched path) nginx.ingress.kubernetes.io/session-cookie-domain Domain that will be set on the cookie string nginx.ingress.kubernetes.io/session-cookie-samesite SameSite attribute to apply to the cookie Browser accepted values are None, Lax, and Strict nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none Will omit SameSite=None attribute for older browsers which reject the more-recently defined SameSite=None value "true" or "false" nginx.ingress.kubernetes.io/session-cookie-max-age Time until the cookie expires, corresponds to the Max-Age cookie directive number of seconds nginx.ingress.kubernetes.io/session-cookie-expires Legacy version of the previous annotation for compatibility with older browsers, generates an Expires cookie directive by adding the seconds to the current date number of seconds nginx.ingress.kubernetes.io/session-cookie-change-on-failure When set to false nginx ingress will send request to upstream pointed by sticky cookie even if previous attempt failed. When set to true and previous attempt failed, sticky cookie will be changed to point to another upstream. true or false (defaults to false) You can create the session affinity example Ingress to test this: kubectl create -f ingress.yaml Validation ¶ You can confirm that the Ingress works: $ kubectl describe ing nginx-test Name: nginx-test Namespace: default @@ -31,7 +31,7 @@ Last-Modified: Tue, 24 Jan 2017 14:02:19 GMT ETag: "58875e6b-264" Accept-Ranges: bytes - In the example above, you can see that the response contains a Set-Cookie header with the settings we have defined. This cookie is created by the NGINX Ingress Controller, it contains a randomly generated key corresponding to the upstream used for that request (selected using consistent hashing) and has an Expires directive. If a client sends a cookie that doesn't correspond to an upstream, NGINX selects an upstream and creates a corresponding cookie. If the backend pool grows NGINX will keep sending the requests through the same server of the first request, even if it's overloaded. When the backend server is removed, the requests are re-routed to another upstream server. This does not require the cookie to be updated because the key's consistent hash will change. Caveats ¶ When you have a Service pointing to more than one Ingress, with only one containing affinity configuration, the first created Ingress will be used. This means that you can face the situation that you've configured session affinity on one Ingress and it doesn't work because the Service is pointing to another Ingress that doesn't configure this. Skip to content NGINX Ingress Controller Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Basic Authentication Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Basic Authentication ¶ This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with htpasswd. It's important the file generated is named auth (actually - that the secret has a key data.auth), otherwise the ingress-controller returns a 503. Create htpasswd file ¶ $ htpasswd -c auth foo + Basic Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Basic Authentication Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Basic Authentication ¶ This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with htpasswd. It's important the file generated is named auth (actually - that the secret has a key data.auth), otherwise the ingress-controller returns a 503. Create htpasswd file ¶ $ htpasswd -c auth foo New password: <bar> New password: Re-type new password: diff --git a/examples/auth/client-certs/index.html b/examples/auth/client-certs/index.html index 8b7f00ce4..fbf4a96af 100644 --- a/examples/auth/client-certs/index.html +++ b/examples/auth/client-certs/index.html @@ -1,4 +1,4 @@ - Client Certificate Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller Client Certificate Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication Client Certificate Authentication Table of contents Creating Certificate Secrets Setup Instructions External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Creating Certificate Secrets Setup Instructions Client Certificate Authentication ¶ It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource. Before getting started you must have the following Certificates configured: CA certificate and Key (Intermediate Certs need to be in CA) Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use) Client Certificate (Signed by CA) and Key For more details on the generation process, checkout the Prerequisite docs. You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following: openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem + Client Certificate Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Client Certificate Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication Client Certificate Authentication Table of contents Creating Certificate Secrets Setup Instructions External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Creating Certificate Secrets Setup Instructions Client Certificate Authentication ¶ It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource. Before getting started you must have the following Certificates configured: CA certificate and Key (Intermediate Certs need to be in CA) Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use) Client Certificate (Signed by CA) and Key For more details on the generation process, checkout the Prerequisite docs. You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following: openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem Then, you can concatenate them all into one file, named 'ca.crt' with the following: cat certificate1.crt certificate2.crt certificate3.crt >> ca.crt Note: Make sure that the Key Size is greater than 1024 and Hashing Algorithm (Digest) is something better than md5 for each certificate generated. Otherwise you will receive an error. Creating Certificate Secrets ¶ There are many different ways of configuring your secrets to enable Client-Certificate Authentication to work properly. You can create a secret containing just the CA certificate and another Secret containing the Server Certificate which is Signed by the CA. kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt kubectl create secret generic tls-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key diff --git a/examples/auth/external-auth/index.html b/examples/auth/external-auth/index.html index 11e3532f8..92246dfe9 100644 --- a/examples/auth/external-auth/index.html +++ b/examples/auth/external-auth/index.html @@ -1,4 +1,4 @@ - External Basic Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml + External Basic Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml ingress "external-auth" created $ kubectl get ing external-auth diff --git a/examples/auth/oauth-external-auth/index.html b/examples/auth/oauth-external-auth/index.html index b8f965b29..49db55e3b 100644 --- a/examples/auth/oauth-external-auth/index.html +++ b/examples/auth/oauth-external-auth/index.html @@ -1,4 +1,4 @@ - External OAUTH Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... + External OAUTH Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... metadata: name: application annotations: diff --git a/examples/customization/configuration-snippets/index.html b/examples/customization/configuration-snippets/index.html index 5f11f913a..45c6ffd1e 100644 --- a/examples/customization/configuration-snippets/index.html +++ b/examples/customization/configuration-snippets/index.html @@ -1,4 +1,4 @@ - Configuration Snippets - NGINX Ingress Controller Skip to content NGINX Ingress Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml + Configuration Snippets - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml Test ¶ Check if the contents of the annotation are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml + Custom Configuration - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml apiVersion: v1 data: proxy-connect-timeout: "10" diff --git a/examples/customization/custom-errors/index.html b/examples/customization/custom-errors/index.html index cae969aeb..2b1b16f7d 100644 --- a/examples/customization/custom-errors/index.html +++ b/examples/customization/custom-errors/index.html @@ -1,4 +1,4 @@ - Custom Errors - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml + Custom Errors - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml service "nginx-errors" created deployment.apps "nginx-errors" created This should have created a Deployment and a Service with the name nginx-errors. $ kubectl get deploy,svc @@ -7,7 +7,7 @@ deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s - Ingress controller configuration ¶ If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the NGINX Ingress controller Service. $ kubectl get svc ingress-nginx + Ingress controller configuration ¶ If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the Ingress-Nginx Controller Service. $ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example. Testing error pages ¶ Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/ diff --git a/examples/customization/custom-headers/index.html b/examples/customization/custom-headers/index.html index ddd97dc36..ca6c12c4a 100644 --- a/examples/customization/custom-headers/index.html +++ b/examples/customization/custom-headers/index.html @@ -1,6 +1,6 @@ - Custom Headers - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Prerequisites ¶ Many of the examples in this directory have common prerequisites. TLS certificates ¶ Unless otherwise mentioned, the TLS secret used in examples is a 2048 bit RSA key/cert pair with an arbitrarily chosen hostname, created as follows $ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=nginxsvc/O=nginxsvc" Generating a 2048 bit RSA private key ................+++ ................+++ diff --git a/examples/affinity/cookie/index.html b/examples/affinity/cookie/index.html index e32048cd3..2e403cf3d 100644 --- a/examples/affinity/cookie/index.html +++ b/examples/affinity/cookie/index.html @@ -1,4 +1,4 @@ - Sticky Sessions - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sticky Sessions Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Sticky Sessions Table of contents Deployment Validation Caveats Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Validation Caveats Sticky sessions ¶ This example demonstrates how to achieve session affinity using cookies. Deployment ¶ Session affinity can be configured using the following annotations: Name Description Value nginx.ingress.kubernetes.io/affinity Type of the affinity, set this to cookie to enable session affinity string (NGINX only supports cookie) nginx.ingress.kubernetes.io/affinity-mode The affinity mode defines how sticky a session is. Use balanced to redistribute some sessions when scaling pods or persistent for maximum stickiness. balanced (default) or persistent nginx.ingress.kubernetes.io/affinity-canary-behavior Defines session affinity behavior of canaries. By default the behavior is sticky, and canaries respect session affinity configuration. Set this to legacy to restore original canary behavior, when session affinity parameters were not respected. sticky (default) or legacy nginx.ingress.kubernetes.io/session-cookie-name Name of the cookie that will be created string (defaults to INGRESSCOOKIE) nginx.ingress.kubernetes.io/session-cookie-secure Set the cookie as secure regardless the protocol of the incoming request "true" or "false" nginx.ingress.kubernetes.io/session-cookie-path Path that will be set on the cookie (required if your Ingress paths use regular expressions) string (defaults to the currently matched path) nginx.ingress.kubernetes.io/session-cookie-domain Domain that will be set on the cookie string nginx.ingress.kubernetes.io/session-cookie-samesite SameSite attribute to apply to the cookie Browser accepted values are None, Lax, and Strict nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none Will omit SameSite=None attribute for older browsers which reject the more-recently defined SameSite=None value "true" or "false" nginx.ingress.kubernetes.io/session-cookie-max-age Time until the cookie expires, corresponds to the Max-Age cookie directive number of seconds nginx.ingress.kubernetes.io/session-cookie-expires Legacy version of the previous annotation for compatibility with older browsers, generates an Expires cookie directive by adding the seconds to the current date number of seconds nginx.ingress.kubernetes.io/session-cookie-change-on-failure When set to false nginx ingress will send request to upstream pointed by sticky cookie even if previous attempt failed. When set to true and previous attempt failed, sticky cookie will be changed to point to another upstream. true or false (defaults to false) You can create the session affinity example Ingress to test this: kubectl create -f ingress.yaml + Sticky Sessions - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sticky Sessions Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Sticky Sessions Table of contents Deployment Validation Caveats Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Validation Caveats Sticky sessions ¶ This example demonstrates how to achieve session affinity using cookies. Deployment ¶ Session affinity can be configured using the following annotations: Name Description Value nginx.ingress.kubernetes.io/affinity Type of the affinity, set this to cookie to enable session affinity string (NGINX only supports cookie) nginx.ingress.kubernetes.io/affinity-mode The affinity mode defines how sticky a session is. Use balanced to redistribute some sessions when scaling pods or persistent for maximum stickiness. balanced (default) or persistent nginx.ingress.kubernetes.io/affinity-canary-behavior Defines session affinity behavior of canaries. By default the behavior is sticky, and canaries respect session affinity configuration. Set this to legacy to restore original canary behavior, when session affinity parameters were not respected. sticky (default) or legacy nginx.ingress.kubernetes.io/session-cookie-name Name of the cookie that will be created string (defaults to INGRESSCOOKIE) nginx.ingress.kubernetes.io/session-cookie-secure Set the cookie as secure regardless the protocol of the incoming request "true" or "false" nginx.ingress.kubernetes.io/session-cookie-path Path that will be set on the cookie (required if your Ingress paths use regular expressions) string (defaults to the currently matched path) nginx.ingress.kubernetes.io/session-cookie-domain Domain that will be set on the cookie string nginx.ingress.kubernetes.io/session-cookie-samesite SameSite attribute to apply to the cookie Browser accepted values are None, Lax, and Strict nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none Will omit SameSite=None attribute for older browsers which reject the more-recently defined SameSite=None value "true" or "false" nginx.ingress.kubernetes.io/session-cookie-max-age Time until the cookie expires, corresponds to the Max-Age cookie directive number of seconds nginx.ingress.kubernetes.io/session-cookie-expires Legacy version of the previous annotation for compatibility with older browsers, generates an Expires cookie directive by adding the seconds to the current date number of seconds nginx.ingress.kubernetes.io/session-cookie-change-on-failure When set to false nginx ingress will send request to upstream pointed by sticky cookie even if previous attempt failed. When set to true and previous attempt failed, sticky cookie will be changed to point to another upstream. true or false (defaults to false) You can create the session affinity example Ingress to test this: kubectl create -f ingress.yaml Validation ¶ You can confirm that the Ingress works: $ kubectl describe ing nginx-test Name: nginx-test Namespace: default @@ -31,7 +31,7 @@ Last-Modified: Tue, 24 Jan 2017 14:02:19 GMT ETag: "58875e6b-264" Accept-Ranges: bytes - In the example above, you can see that the response contains a Set-Cookie header with the settings we have defined. This cookie is created by the NGINX Ingress Controller, it contains a randomly generated key corresponding to the upstream used for that request (selected using consistent hashing) and has an Expires directive. If a client sends a cookie that doesn't correspond to an upstream, NGINX selects an upstream and creates a corresponding cookie. If the backend pool grows NGINX will keep sending the requests through the same server of the first request, even if it's overloaded. When the backend server is removed, the requests are re-routed to another upstream server. This does not require the cookie to be updated because the key's consistent hash will change. Caveats ¶ When you have a Service pointing to more than one Ingress, with only one containing affinity configuration, the first created Ingress will be used. This means that you can face the situation that you've configured session affinity on one Ingress and it doesn't work because the Service is pointing to another Ingress that doesn't configure this. Skip to content NGINX Ingress Controller Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Basic Authentication Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Basic Authentication ¶ This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with htpasswd. It's important the file generated is named auth (actually - that the secret has a key data.auth), otherwise the ingress-controller returns a 503. Create htpasswd file ¶ $ htpasswd -c auth foo + Basic Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Basic Authentication Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Basic Authentication ¶ This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with htpasswd. It's important the file generated is named auth (actually - that the secret has a key data.auth), otherwise the ingress-controller returns a 503. Create htpasswd file ¶ $ htpasswd -c auth foo New password: <bar> New password: Re-type new password: diff --git a/examples/auth/client-certs/index.html b/examples/auth/client-certs/index.html index 8b7f00ce4..fbf4a96af 100644 --- a/examples/auth/client-certs/index.html +++ b/examples/auth/client-certs/index.html @@ -1,4 +1,4 @@ - Client Certificate Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller Client Certificate Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication Client Certificate Authentication Table of contents Creating Certificate Secrets Setup Instructions External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Creating Certificate Secrets Setup Instructions Client Certificate Authentication ¶ It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource. Before getting started you must have the following Certificates configured: CA certificate and Key (Intermediate Certs need to be in CA) Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use) Client Certificate (Signed by CA) and Key For more details on the generation process, checkout the Prerequisite docs. You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following: openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem + Client Certificate Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Client Certificate Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication Client Certificate Authentication Table of contents Creating Certificate Secrets Setup Instructions External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Creating Certificate Secrets Setup Instructions Client Certificate Authentication ¶ It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource. Before getting started you must have the following Certificates configured: CA certificate and Key (Intermediate Certs need to be in CA) Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use) Client Certificate (Signed by CA) and Key For more details on the generation process, checkout the Prerequisite docs. You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following: openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem Then, you can concatenate them all into one file, named 'ca.crt' with the following: cat certificate1.crt certificate2.crt certificate3.crt >> ca.crt Note: Make sure that the Key Size is greater than 1024 and Hashing Algorithm (Digest) is something better than md5 for each certificate generated. Otherwise you will receive an error. Creating Certificate Secrets ¶ There are many different ways of configuring your secrets to enable Client-Certificate Authentication to work properly. You can create a secret containing just the CA certificate and another Secret containing the Server Certificate which is Signed by the CA. kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt kubectl create secret generic tls-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key diff --git a/examples/auth/external-auth/index.html b/examples/auth/external-auth/index.html index 11e3532f8..92246dfe9 100644 --- a/examples/auth/external-auth/index.html +++ b/examples/auth/external-auth/index.html @@ -1,4 +1,4 @@ - External Basic Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml + External Basic Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml ingress "external-auth" created $ kubectl get ing external-auth diff --git a/examples/auth/oauth-external-auth/index.html b/examples/auth/oauth-external-auth/index.html index b8f965b29..49db55e3b 100644 --- a/examples/auth/oauth-external-auth/index.html +++ b/examples/auth/oauth-external-auth/index.html @@ -1,4 +1,4 @@ - External OAUTH Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... + External OAUTH Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... metadata: name: application annotations: diff --git a/examples/customization/configuration-snippets/index.html b/examples/customization/configuration-snippets/index.html index 5f11f913a..45c6ffd1e 100644 --- a/examples/customization/configuration-snippets/index.html +++ b/examples/customization/configuration-snippets/index.html @@ -1,4 +1,4 @@ - Configuration Snippets - NGINX Ingress Controller Skip to content NGINX Ingress Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml + Configuration Snippets - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml Test ¶ Check if the contents of the annotation are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml + Custom Configuration - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml apiVersion: v1 data: proxy-connect-timeout: "10" diff --git a/examples/customization/custom-errors/index.html b/examples/customization/custom-errors/index.html index cae969aeb..2b1b16f7d 100644 --- a/examples/customization/custom-errors/index.html +++ b/examples/customization/custom-errors/index.html @@ -1,4 +1,4 @@ - Custom Errors - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml + Custom Errors - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml service "nginx-errors" created deployment.apps "nginx-errors" created This should have created a Deployment and a Service with the name nginx-errors. $ kubectl get deploy,svc @@ -7,7 +7,7 @@ deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s - Ingress controller configuration ¶ If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the NGINX Ingress controller Service. $ kubectl get svc ingress-nginx + Ingress controller configuration ¶ If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the Ingress-Nginx Controller Service. $ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example. Testing error pages ¶ Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/ diff --git a/examples/customization/custom-headers/index.html b/examples/customization/custom-headers/index.html index ddd97dc36..ca6c12c4a 100644 --- a/examples/customization/custom-headers/index.html +++ b/examples/customization/custom-headers/index.html @@ -1,6 +1,6 @@ - Custom Headers - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Sticky sessions ¶ This example demonstrates how to achieve session affinity using cookies. Deployment ¶ Session affinity can be configured using the following annotations: Name Description Value nginx.ingress.kubernetes.io/affinity Type of the affinity, set this to cookie to enable session affinity string (NGINX only supports cookie) nginx.ingress.kubernetes.io/affinity-mode The affinity mode defines how sticky a session is. Use balanced to redistribute some sessions when scaling pods or persistent for maximum stickiness. balanced (default) or persistent nginx.ingress.kubernetes.io/affinity-canary-behavior Defines session affinity behavior of canaries. By default the behavior is sticky, and canaries respect session affinity configuration. Set this to legacy to restore original canary behavior, when session affinity parameters were not respected. sticky (default) or legacy nginx.ingress.kubernetes.io/session-cookie-name Name of the cookie that will be created string (defaults to INGRESSCOOKIE) nginx.ingress.kubernetes.io/session-cookie-secure Set the cookie as secure regardless the protocol of the incoming request "true" or "false" nginx.ingress.kubernetes.io/session-cookie-path Path that will be set on the cookie (required if your Ingress paths use regular expressions) string (defaults to the currently matched path) nginx.ingress.kubernetes.io/session-cookie-domain Domain that will be set on the cookie string nginx.ingress.kubernetes.io/session-cookie-samesite SameSite attribute to apply to the cookie Browser accepted values are None, Lax, and Strict nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none Will omit SameSite=None attribute for older browsers which reject the more-recently defined SameSite=None value "true" or "false" nginx.ingress.kubernetes.io/session-cookie-max-age Time until the cookie expires, corresponds to the Max-Age cookie directive number of seconds nginx.ingress.kubernetes.io/session-cookie-expires Legacy version of the previous annotation for compatibility with older browsers, generates an Expires cookie directive by adding the seconds to the current date number of seconds nginx.ingress.kubernetes.io/session-cookie-change-on-failure When set to false nginx ingress will send request to upstream pointed by sticky cookie even if previous attempt failed. When set to true and previous attempt failed, sticky cookie will be changed to point to another upstream. true or false (defaults to false) You can create the session affinity example Ingress to test this: kubectl create -f ingress.yaml + Sticky Sessions - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sticky Sessions Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Sticky Sessions Table of contents Deployment Validation Caveats Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Validation Caveats Sticky sessions ¶ This example demonstrates how to achieve session affinity using cookies. Deployment ¶ Session affinity can be configured using the following annotations: Name Description Value nginx.ingress.kubernetes.io/affinity Type of the affinity, set this to cookie to enable session affinity string (NGINX only supports cookie) nginx.ingress.kubernetes.io/affinity-mode The affinity mode defines how sticky a session is. Use balanced to redistribute some sessions when scaling pods or persistent for maximum stickiness. balanced (default) or persistent nginx.ingress.kubernetes.io/affinity-canary-behavior Defines session affinity behavior of canaries. By default the behavior is sticky, and canaries respect session affinity configuration. Set this to legacy to restore original canary behavior, when session affinity parameters were not respected. sticky (default) or legacy nginx.ingress.kubernetes.io/session-cookie-name Name of the cookie that will be created string (defaults to INGRESSCOOKIE) nginx.ingress.kubernetes.io/session-cookie-secure Set the cookie as secure regardless the protocol of the incoming request "true" or "false" nginx.ingress.kubernetes.io/session-cookie-path Path that will be set on the cookie (required if your Ingress paths use regular expressions) string (defaults to the currently matched path) nginx.ingress.kubernetes.io/session-cookie-domain Domain that will be set on the cookie string nginx.ingress.kubernetes.io/session-cookie-samesite SameSite attribute to apply to the cookie Browser accepted values are None, Lax, and Strict nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none Will omit SameSite=None attribute for older browsers which reject the more-recently defined SameSite=None value "true" or "false" nginx.ingress.kubernetes.io/session-cookie-max-age Time until the cookie expires, corresponds to the Max-Age cookie directive number of seconds nginx.ingress.kubernetes.io/session-cookie-expires Legacy version of the previous annotation for compatibility with older browsers, generates an Expires cookie directive by adding the seconds to the current date number of seconds nginx.ingress.kubernetes.io/session-cookie-change-on-failure When set to false nginx ingress will send request to upstream pointed by sticky cookie even if previous attempt failed. When set to true and previous attempt failed, sticky cookie will be changed to point to another upstream. true or false (defaults to false) You can create the session affinity example Ingress to test this: kubectl create -f ingress.yaml Validation ¶ You can confirm that the Ingress works: $ kubectl describe ing nginx-test Name: nginx-test Namespace: default @@ -31,7 +31,7 @@ Last-Modified: Tue, 24 Jan 2017 14:02:19 GMT ETag: "58875e6b-264" Accept-Ranges: bytes - In the example above, you can see that the response contains a Set-Cookie header with the settings we have defined. This cookie is created by the NGINX Ingress Controller, it contains a randomly generated key corresponding to the upstream used for that request (selected using consistent hashing) and has an Expires directive. If a client sends a cookie that doesn't correspond to an upstream, NGINX selects an upstream and creates a corresponding cookie. If the backend pool grows NGINX will keep sending the requests through the same server of the first request, even if it's overloaded. When the backend server is removed, the requests are re-routed to another upstream server. This does not require the cookie to be updated because the key's consistent hash will change. Caveats ¶ When you have a Service pointing to more than one Ingress, with only one containing affinity configuration, the first created Ingress will be used. This means that you can face the situation that you've configured session affinity on one Ingress and it doesn't work because the Service is pointing to another Ingress that doesn't configure this. Skip to content NGINX Ingress Controller Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Basic Authentication Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Basic Authentication ¶ This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with htpasswd. It's important the file generated is named auth (actually - that the secret has a key data.auth), otherwise the ingress-controller returns a 503. Create htpasswd file ¶ $ htpasswd -c auth foo + Basic Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Basic Authentication Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Basic Authentication ¶ This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with htpasswd. It's important the file generated is named auth (actually - that the secret has a key data.auth), otherwise the ingress-controller returns a 503. Create htpasswd file ¶ $ htpasswd -c auth foo New password: <bar> New password: Re-type new password: diff --git a/examples/auth/client-certs/index.html b/examples/auth/client-certs/index.html index 8b7f00ce4..fbf4a96af 100644 --- a/examples/auth/client-certs/index.html +++ b/examples/auth/client-certs/index.html @@ -1,4 +1,4 @@ - Client Certificate Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller Client Certificate Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication Client Certificate Authentication Table of contents Creating Certificate Secrets Setup Instructions External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Creating Certificate Secrets Setup Instructions Client Certificate Authentication ¶ It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource. Before getting started you must have the following Certificates configured: CA certificate and Key (Intermediate Certs need to be in CA) Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use) Client Certificate (Signed by CA) and Key For more details on the generation process, checkout the Prerequisite docs. You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following: openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem + Client Certificate Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Client Certificate Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication Client Certificate Authentication Table of contents Creating Certificate Secrets Setup Instructions External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Creating Certificate Secrets Setup Instructions Client Certificate Authentication ¶ It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource. Before getting started you must have the following Certificates configured: CA certificate and Key (Intermediate Certs need to be in CA) Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use) Client Certificate (Signed by CA) and Key For more details on the generation process, checkout the Prerequisite docs. You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following: openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem Then, you can concatenate them all into one file, named 'ca.crt' with the following: cat certificate1.crt certificate2.crt certificate3.crt >> ca.crt Note: Make sure that the Key Size is greater than 1024 and Hashing Algorithm (Digest) is something better than md5 for each certificate generated. Otherwise you will receive an error. Creating Certificate Secrets ¶ There are many different ways of configuring your secrets to enable Client-Certificate Authentication to work properly. You can create a secret containing just the CA certificate and another Secret containing the Server Certificate which is Signed by the CA. kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt kubectl create secret generic tls-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key diff --git a/examples/auth/external-auth/index.html b/examples/auth/external-auth/index.html index 11e3532f8..92246dfe9 100644 --- a/examples/auth/external-auth/index.html +++ b/examples/auth/external-auth/index.html @@ -1,4 +1,4 @@ - External Basic Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml + External Basic Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml ingress "external-auth" created $ kubectl get ing external-auth diff --git a/examples/auth/oauth-external-auth/index.html b/examples/auth/oauth-external-auth/index.html index b8f965b29..49db55e3b 100644 --- a/examples/auth/oauth-external-auth/index.html +++ b/examples/auth/oauth-external-auth/index.html @@ -1,4 +1,4 @@ - External OAUTH Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... + External OAUTH Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... metadata: name: application annotations: diff --git a/examples/customization/configuration-snippets/index.html b/examples/customization/configuration-snippets/index.html index 5f11f913a..45c6ffd1e 100644 --- a/examples/customization/configuration-snippets/index.html +++ b/examples/customization/configuration-snippets/index.html @@ -1,4 +1,4 @@ - Configuration Snippets - NGINX Ingress Controller Skip to content NGINX Ingress Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml + Configuration Snippets - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml Test ¶ Check if the contents of the annotation are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml + Custom Configuration - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml apiVersion: v1 data: proxy-connect-timeout: "10" diff --git a/examples/customization/custom-errors/index.html b/examples/customization/custom-errors/index.html index cae969aeb..2b1b16f7d 100644 --- a/examples/customization/custom-errors/index.html +++ b/examples/customization/custom-errors/index.html @@ -1,4 +1,4 @@ - Custom Errors - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml + Custom Errors - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml service "nginx-errors" created deployment.apps "nginx-errors" created This should have created a Deployment and a Service with the name nginx-errors. $ kubectl get deploy,svc @@ -7,7 +7,7 @@ deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s - Ingress controller configuration ¶ If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the NGINX Ingress controller Service. $ kubectl get svc ingress-nginx + Ingress controller configuration ¶ If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the Ingress-Nginx Controller Service. $ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example. Testing error pages ¶ Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/ diff --git a/examples/customization/custom-headers/index.html b/examples/customization/custom-headers/index.html index ddd97dc36..ca6c12c4a 100644 --- a/examples/customization/custom-headers/index.html +++ b/examples/customization/custom-headers/index.html @@ -1,6 +1,6 @@ - Custom Headers - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Sticky sessions ¶ This example demonstrates how to achieve session affinity using cookies. Deployment ¶ Session affinity can be configured using the following annotations: Name Description Value nginx.ingress.kubernetes.io/affinity Type of the affinity, set this to cookie to enable session affinity string (NGINX only supports cookie) nginx.ingress.kubernetes.io/affinity-mode The affinity mode defines how sticky a session is. Use balanced to redistribute some sessions when scaling pods or persistent for maximum stickiness. balanced (default) or persistent nginx.ingress.kubernetes.io/affinity-canary-behavior Defines session affinity behavior of canaries. By default the behavior is sticky, and canaries respect session affinity configuration. Set this to legacy to restore original canary behavior, when session affinity parameters were not respected. sticky (default) or legacy nginx.ingress.kubernetes.io/session-cookie-name Name of the cookie that will be created string (defaults to INGRESSCOOKIE) nginx.ingress.kubernetes.io/session-cookie-secure Set the cookie as secure regardless the protocol of the incoming request "true" or "false" nginx.ingress.kubernetes.io/session-cookie-path Path that will be set on the cookie (required if your Ingress paths use regular expressions) string (defaults to the currently matched path) nginx.ingress.kubernetes.io/session-cookie-domain Domain that will be set on the cookie string nginx.ingress.kubernetes.io/session-cookie-samesite SameSite attribute to apply to the cookie Browser accepted values are None, Lax, and Strict nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none Will omit SameSite=None attribute for older browsers which reject the more-recently defined SameSite=None value "true" or "false" nginx.ingress.kubernetes.io/session-cookie-max-age Time until the cookie expires, corresponds to the Max-Age cookie directive number of seconds nginx.ingress.kubernetes.io/session-cookie-expires Legacy version of the previous annotation for compatibility with older browsers, generates an Expires cookie directive by adding the seconds to the current date number of seconds nginx.ingress.kubernetes.io/session-cookie-change-on-failure When set to false nginx ingress will send request to upstream pointed by sticky cookie even if previous attempt failed. When set to true and previous attempt failed, sticky cookie will be changed to point to another upstream. true or false (defaults to false) You can create the session affinity example Ingress to test this: kubectl create -f ingress.yaml Validation ¶ You can confirm that the Ingress works: $ kubectl describe ing nginx-test Name: nginx-test Namespace: default @@ -31,7 +31,7 @@ Last-Modified: Tue, 24 Jan 2017 14:02:19 GMT ETag: "58875e6b-264" Accept-Ranges: bytes - In the example above, you can see that the response contains a Set-Cookie header with the settings we have defined. This cookie is created by the NGINX Ingress Controller, it contains a randomly generated key corresponding to the upstream used for that request (selected using consistent hashing) and has an Expires directive. If a client sends a cookie that doesn't correspond to an upstream, NGINX selects an upstream and creates a corresponding cookie. If the backend pool grows NGINX will keep sending the requests through the same server of the first request, even if it's overloaded. When the backend server is removed, the requests are re-routed to another upstream server. This does not require the cookie to be updated because the key's consistent hash will change. Caveats ¶ When you have a Service pointing to more than one Ingress, with only one containing affinity configuration, the first created Ingress will be used. This means that you can face the situation that you've configured session affinity on one Ingress and it doesn't work because the Service is pointing to another Ingress that doesn't configure this.
Basic Authentication ¶ This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with htpasswd. It's important the file generated is named auth (actually - that the secret has a key data.auth), otherwise the ingress-controller returns a 503. Create htpasswd file ¶ $ htpasswd -c auth foo + Basic Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Basic Authentication Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Create htpasswd file Convert htpasswd into a secret Examine secret Using kubectl, create an ingress tied to the basic-auth secret Use curl to confirm authorization is required by the ingress Use curl with the correct credentials to connect to the ingress Basic Authentication ¶ This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with htpasswd. It's important the file generated is named auth (actually - that the secret has a key data.auth), otherwise the ingress-controller returns a 503. Create htpasswd file ¶ $ htpasswd -c auth foo New password: <bar> New password: Re-type new password: diff --git a/examples/auth/client-certs/index.html b/examples/auth/client-certs/index.html index 8b7f00ce4..fbf4a96af 100644 --- a/examples/auth/client-certs/index.html +++ b/examples/auth/client-certs/index.html @@ -1,4 +1,4 @@ - Client Certificate Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller Client Certificate Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication Client Certificate Authentication Table of contents Creating Certificate Secrets Setup Instructions External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Creating Certificate Secrets Setup Instructions Client Certificate Authentication ¶ It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource. Before getting started you must have the following Certificates configured: CA certificate and Key (Intermediate Certs need to be in CA) Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use) Client Certificate (Signed by CA) and Key For more details on the generation process, checkout the Prerequisite docs. You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following: openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem + Client Certificate Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Client Certificate Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication Client Certificate Authentication Table of contents Creating Certificate Secrets Setup Instructions External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Creating Certificate Secrets Setup Instructions Client Certificate Authentication ¶ It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource. Before getting started you must have the following Certificates configured: CA certificate and Key (Intermediate Certs need to be in CA) Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use) Client Certificate (Signed by CA) and Key For more details on the generation process, checkout the Prerequisite docs. You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following: openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem Then, you can concatenate them all into one file, named 'ca.crt' with the following: cat certificate1.crt certificate2.crt certificate3.crt >> ca.crt Note: Make sure that the Key Size is greater than 1024 and Hashing Algorithm (Digest) is something better than md5 for each certificate generated. Otherwise you will receive an error. Creating Certificate Secrets ¶ There are many different ways of configuring your secrets to enable Client-Certificate Authentication to work properly. You can create a secret containing just the CA certificate and another Secret containing the Server Certificate which is Signed by the CA. kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt kubectl create secret generic tls-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key diff --git a/examples/auth/external-auth/index.html b/examples/auth/external-auth/index.html index 11e3532f8..92246dfe9 100644 --- a/examples/auth/external-auth/index.html +++ b/examples/auth/external-auth/index.html @@ -1,4 +1,4 @@ - External Basic Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml + External Basic Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml ingress "external-auth" created $ kubectl get ing external-auth diff --git a/examples/auth/oauth-external-auth/index.html b/examples/auth/oauth-external-auth/index.html index b8f965b29..49db55e3b 100644 --- a/examples/auth/oauth-external-auth/index.html +++ b/examples/auth/oauth-external-auth/index.html @@ -1,4 +1,4 @@ - External OAUTH Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... + External OAUTH Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... metadata: name: application annotations: diff --git a/examples/customization/configuration-snippets/index.html b/examples/customization/configuration-snippets/index.html index 5f11f913a..45c6ffd1e 100644 --- a/examples/customization/configuration-snippets/index.html +++ b/examples/customization/configuration-snippets/index.html @@ -1,4 +1,4 @@ - Configuration Snippets - NGINX Ingress Controller Skip to content NGINX Ingress Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml + Configuration Snippets - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml Test ¶ Check if the contents of the annotation are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml + Custom Configuration - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml apiVersion: v1 data: proxy-connect-timeout: "10" diff --git a/examples/customization/custom-errors/index.html b/examples/customization/custom-errors/index.html index cae969aeb..2b1b16f7d 100644 --- a/examples/customization/custom-errors/index.html +++ b/examples/customization/custom-errors/index.html @@ -1,4 +1,4 @@ - Custom Errors - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml + Custom Errors - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml service "nginx-errors" created deployment.apps "nginx-errors" created This should have created a Deployment and a Service with the name nginx-errors. $ kubectl get deploy,svc @@ -7,7 +7,7 @@ deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s - Ingress controller configuration ¶ If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the NGINX Ingress controller Service. $ kubectl get svc ingress-nginx + Ingress controller configuration ¶ If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the Ingress-Nginx Controller Service. $ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example. Testing error pages ¶ Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/ diff --git a/examples/customization/custom-headers/index.html b/examples/customization/custom-headers/index.html index ddd97dc36..ca6c12c4a 100644 --- a/examples/customization/custom-headers/index.html +++ b/examples/customization/custom-headers/index.html @@ -1,6 +1,6 @@ - Custom Headers - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Basic Authentication ¶ This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with htpasswd. It's important the file generated is named auth (actually - that the secret has a key data.auth), otherwise the ingress-controller returns a 503. Create htpasswd file ¶ $ htpasswd -c auth foo New password: <bar> New password: Re-type new password: diff --git a/examples/auth/client-certs/index.html b/examples/auth/client-certs/index.html index 8b7f00ce4..fbf4a96af 100644 --- a/examples/auth/client-certs/index.html +++ b/examples/auth/client-certs/index.html @@ -1,4 +1,4 @@ - Client Certificate Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller Client Certificate Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication Client Certificate Authentication Table of contents Creating Certificate Secrets Setup Instructions External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Creating Certificate Secrets Setup Instructions Client Certificate Authentication ¶ It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource. Before getting started you must have the following Certificates configured: CA certificate and Key (Intermediate Certs need to be in CA) Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use) Client Certificate (Signed by CA) and Key For more details on the generation process, checkout the Prerequisite docs. You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following: openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem + Client Certificate Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Client Certificate Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication Client Certificate Authentication Table of contents Creating Certificate Secrets Setup Instructions External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Creating Certificate Secrets Setup Instructions Client Certificate Authentication ¶ It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource. Before getting started you must have the following Certificates configured: CA certificate and Key (Intermediate Certs need to be in CA) Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use) Client Certificate (Signed by CA) and Key For more details on the generation process, checkout the Prerequisite docs. You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following: openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem Then, you can concatenate them all into one file, named 'ca.crt' with the following: cat certificate1.crt certificate2.crt certificate3.crt >> ca.crt Note: Make sure that the Key Size is greater than 1024 and Hashing Algorithm (Digest) is something better than md5 for each certificate generated. Otherwise you will receive an error. Creating Certificate Secrets ¶ There are many different ways of configuring your secrets to enable Client-Certificate Authentication to work properly. You can create a secret containing just the CA certificate and another Secret containing the Server Certificate which is Signed by the CA. kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt kubectl create secret generic tls-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key diff --git a/examples/auth/external-auth/index.html b/examples/auth/external-auth/index.html index 11e3532f8..92246dfe9 100644 --- a/examples/auth/external-auth/index.html +++ b/examples/auth/external-auth/index.html @@ -1,4 +1,4 @@ - External Basic Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml + External Basic Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml ingress "external-auth" created $ kubectl get ing external-auth diff --git a/examples/auth/oauth-external-auth/index.html b/examples/auth/oauth-external-auth/index.html index b8f965b29..49db55e3b 100644 --- a/examples/auth/oauth-external-auth/index.html +++ b/examples/auth/oauth-external-auth/index.html @@ -1,4 +1,4 @@ - External OAUTH Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... + External OAUTH Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... metadata: name: application annotations: diff --git a/examples/customization/configuration-snippets/index.html b/examples/customization/configuration-snippets/index.html index 5f11f913a..45c6ffd1e 100644 --- a/examples/customization/configuration-snippets/index.html +++ b/examples/customization/configuration-snippets/index.html @@ -1,4 +1,4 @@ - Configuration Snippets - NGINX Ingress Controller Skip to content NGINX Ingress Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml + Configuration Snippets - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml Test ¶ Check if the contents of the annotation are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml + Custom Configuration - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml apiVersion: v1 data: proxy-connect-timeout: "10" diff --git a/examples/customization/custom-errors/index.html b/examples/customization/custom-errors/index.html index cae969aeb..2b1b16f7d 100644 --- a/examples/customization/custom-errors/index.html +++ b/examples/customization/custom-errors/index.html @@ -1,4 +1,4 @@ - Custom Errors - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml + Custom Errors - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml service "nginx-errors" created deployment.apps "nginx-errors" created This should have created a Deployment and a Service with the name nginx-errors. $ kubectl get deploy,svc @@ -7,7 +7,7 @@ deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s - Ingress controller configuration ¶ If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the NGINX Ingress controller Service. $ kubectl get svc ingress-nginx + Ingress controller configuration ¶ If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the Ingress-Nginx Controller Service. $ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example. Testing error pages ¶ Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/ diff --git a/examples/customization/custom-headers/index.html b/examples/customization/custom-headers/index.html index ddd97dc36..ca6c12c4a 100644 --- a/examples/customization/custom-headers/index.html +++ b/examples/customization/custom-headers/index.html @@ -1,6 +1,6 @@ - Custom Headers - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Client Certificate Authentication ¶ It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource. Before getting started you must have the following Certificates configured: CA certificate and Key (Intermediate Certs need to be in CA) Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use) Client Certificate (Signed by CA) and Key For more details on the generation process, checkout the Prerequisite docs. You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following: openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem + Client Certificate Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Client Certificate Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication Client Certificate Authentication Table of contents Creating Certificate Secrets Setup Instructions External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Creating Certificate Secrets Setup Instructions Client Certificate Authentication ¶ It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource. Before getting started you must have the following Certificates configured: CA certificate and Key (Intermediate Certs need to be in CA) Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use) Client Certificate (Signed by CA) and Key For more details on the generation process, checkout the Prerequisite docs. You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following: openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem Then, you can concatenate them all into one file, named 'ca.crt' with the following: cat certificate1.crt certificate2.crt certificate3.crt >> ca.crt Note: Make sure that the Key Size is greater than 1024 and Hashing Algorithm (Digest) is something better than md5 for each certificate generated. Otherwise you will receive an error. Creating Certificate Secrets ¶ There are many different ways of configuring your secrets to enable Client-Certificate Authentication to work properly. You can create a secret containing just the CA certificate and another Secret containing the Server Certificate which is Signed by the CA. kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt kubectl create secret generic tls-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key diff --git a/examples/auth/external-auth/index.html b/examples/auth/external-auth/index.html index 11e3532f8..92246dfe9 100644 --- a/examples/auth/external-auth/index.html +++ b/examples/auth/external-auth/index.html @@ -1,4 +1,4 @@ - External Basic Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml + External Basic Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml ingress "external-auth" created $ kubectl get ing external-auth diff --git a/examples/auth/oauth-external-auth/index.html b/examples/auth/oauth-external-auth/index.html index b8f965b29..49db55e3b 100644 --- a/examples/auth/oauth-external-auth/index.html +++ b/examples/auth/oauth-external-auth/index.html @@ -1,4 +1,4 @@ - External OAUTH Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... + External OAUTH Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... metadata: name: application annotations: diff --git a/examples/customization/configuration-snippets/index.html b/examples/customization/configuration-snippets/index.html index 5f11f913a..45c6ffd1e 100644 --- a/examples/customization/configuration-snippets/index.html +++ b/examples/customization/configuration-snippets/index.html @@ -1,4 +1,4 @@ - Configuration Snippets - NGINX Ingress Controller Skip to content NGINX Ingress Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml + Configuration Snippets - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml Test ¶ Check if the contents of the annotation are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml + Custom Configuration - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml apiVersion: v1 data: proxy-connect-timeout: "10" diff --git a/examples/customization/custom-errors/index.html b/examples/customization/custom-errors/index.html index cae969aeb..2b1b16f7d 100644 --- a/examples/customization/custom-errors/index.html +++ b/examples/customization/custom-errors/index.html @@ -1,4 +1,4 @@ - Custom Errors - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml + Custom Errors - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml service "nginx-errors" created deployment.apps "nginx-errors" created This should have created a Deployment and a Service with the name nginx-errors. $ kubectl get deploy,svc @@ -7,7 +7,7 @@ deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s - Ingress controller configuration ¶ If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the NGINX Ingress controller Service. $ kubectl get svc ingress-nginx + Ingress controller configuration ¶ If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the Ingress-Nginx Controller Service. $ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example. Testing error pages ¶ Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/ diff --git a/examples/customization/custom-headers/index.html b/examples/customization/custom-headers/index.html index ddd97dc36..ca6c12c4a 100644 --- a/examples/customization/custom-headers/index.html +++ b/examples/customization/custom-headers/index.html @@ -1,6 +1,6 @@ - Custom Headers - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Client Certificate Authentication ¶ It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource. Before getting started you must have the following Certificates configured: CA certificate and Key (Intermediate Certs need to be in CA) Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use) Client Certificate (Signed by CA) and Key For more details on the generation process, checkout the Prerequisite docs. You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following: openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem Then, you can concatenate them all into one file, named 'ca.crt' with the following: cat certificate1.crt certificate2.crt certificate3.crt >> ca.crt Note: Make sure that the Key Size is greater than 1024 and Hashing Algorithm (Digest) is something better than md5 for each certificate generated. Otherwise you will receive an error. Creating Certificate Secrets ¶ There are many different ways of configuring your secrets to enable Client-Certificate Authentication to work properly. You can create a secret containing just the CA certificate and another Secret containing the Server Certificate which is Signed by the CA. kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt kubectl create secret generic tls-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key diff --git a/examples/auth/external-auth/index.html b/examples/auth/external-auth/index.html index 11e3532f8..92246dfe9 100644 --- a/examples/auth/external-auth/index.html +++ b/examples/auth/external-auth/index.html @@ -1,4 +1,4 @@ - External Basic Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml + External Basic Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml ingress "external-auth" created $ kubectl get ing external-auth diff --git a/examples/auth/oauth-external-auth/index.html b/examples/auth/oauth-external-auth/index.html index b8f965b29..49db55e3b 100644 --- a/examples/auth/oauth-external-auth/index.html +++ b/examples/auth/oauth-external-auth/index.html @@ -1,4 +1,4 @@ - External OAUTH Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... + External OAUTH Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... metadata: name: application annotations: diff --git a/examples/customization/configuration-snippets/index.html b/examples/customization/configuration-snippets/index.html index 5f11f913a..45c6ffd1e 100644 --- a/examples/customization/configuration-snippets/index.html +++ b/examples/customization/configuration-snippets/index.html @@ -1,4 +1,4 @@ - Configuration Snippets - NGINX Ingress Controller Skip to content NGINX Ingress Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml + Configuration Snippets - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml Test ¶ Check if the contents of the annotation are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml + Custom Configuration - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml apiVersion: v1 data: proxy-connect-timeout: "10" diff --git a/examples/customization/custom-errors/index.html b/examples/customization/custom-errors/index.html index cae969aeb..2b1b16f7d 100644 --- a/examples/customization/custom-errors/index.html +++ b/examples/customization/custom-errors/index.html @@ -1,4 +1,4 @@ - Custom Errors - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml + Custom Errors - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml service "nginx-errors" created deployment.apps "nginx-errors" created This should have created a Deployment and a Service with the name nginx-errors. $ kubectl get deploy,svc @@ -7,7 +7,7 @@ deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s - Ingress controller configuration ¶ If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the NGINX Ingress controller Service. $ kubectl get svc ingress-nginx + Ingress controller configuration ¶ If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the Ingress-Nginx Controller Service. $ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example. Testing error pages ¶ Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/ diff --git a/examples/customization/custom-headers/index.html b/examples/customization/custom-headers/index.html index ddd97dc36..ca6c12c4a 100644 --- a/examples/customization/custom-headers/index.html +++ b/examples/customization/custom-headers/index.html @@ -1,6 +1,6 @@ - Custom Headers - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml + External Basic Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External Basic Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External Basic Authentication Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Example 1 Test 1: no username/password (expect code 401) Test 2: valid username/password (expect code 200) Test 3: invalid username/password (expect code 401) External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml ingress "external-auth" created $ kubectl get ing external-auth diff --git a/examples/auth/oauth-external-auth/index.html b/examples/auth/oauth-external-auth/index.html index b8f965b29..49db55e3b 100644 --- a/examples/auth/oauth-external-auth/index.html +++ b/examples/auth/oauth-external-auth/index.html @@ -1,4 +1,4 @@ - External OAUTH Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... + External OAUTH Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... metadata: name: application annotations: diff --git a/examples/customization/configuration-snippets/index.html b/examples/customization/configuration-snippets/index.html index 5f11f913a..45c6ffd1e 100644 --- a/examples/customization/configuration-snippets/index.html +++ b/examples/customization/configuration-snippets/index.html @@ -1,4 +1,4 @@ - Configuration Snippets - NGINX Ingress Controller Skip to content NGINX Ingress Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml + Configuration Snippets - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml Test ¶ Check if the contents of the annotation are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml + Custom Configuration - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml apiVersion: v1 data: proxy-connect-timeout: "10" diff --git a/examples/customization/custom-errors/index.html b/examples/customization/custom-errors/index.html index cae969aeb..2b1b16f7d 100644 --- a/examples/customization/custom-errors/index.html +++ b/examples/customization/custom-errors/index.html @@ -1,4 +1,4 @@ - Custom Errors - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml + Custom Errors - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml service "nginx-errors" created deployment.apps "nginx-errors" created This should have created a Deployment and a Service with the name nginx-errors. $ kubectl get deploy,svc @@ -7,7 +7,7 @@ deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s - Ingress controller configuration ¶ If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the NGINX Ingress controller Service. $ kubectl get svc ingress-nginx + Ingress controller configuration ¶ If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the Ingress-Nginx Controller Service. $ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example. Testing error pages ¶ Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/ diff --git a/examples/customization/custom-headers/index.html b/examples/customization/custom-headers/index.html index ddd97dc36..ca6c12c4a 100644 --- a/examples/customization/custom-headers/index.html +++ b/examples/customization/custom-headers/index.html @@ -1,6 +1,6 @@ - Custom Headers - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
External Basic Authentication ¶ Example 1 ¶ Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml ingress "external-auth" created $ kubectl get ing external-auth diff --git a/examples/auth/oauth-external-auth/index.html b/examples/auth/oauth-external-auth/index.html index b8f965b29..49db55e3b 100644 --- a/examples/auth/oauth-external-auth/index.html +++ b/examples/auth/oauth-external-auth/index.html @@ -1,4 +1,4 @@ - External OAUTH Authentication - NGINX Ingress Controller Skip to content NGINX Ingress Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... + External OAUTH Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... metadata: name: application annotations: diff --git a/examples/customization/configuration-snippets/index.html b/examples/customization/configuration-snippets/index.html index 5f11f913a..45c6ffd1e 100644 --- a/examples/customization/configuration-snippets/index.html +++ b/examples/customization/configuration-snippets/index.html @@ -1,4 +1,4 @@ - Configuration Snippets - NGINX Ingress Controller Skip to content NGINX Ingress Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml + Configuration Snippets - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml Test ¶ Check if the contents of the annotation are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml + Custom Configuration - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml apiVersion: v1 data: proxy-connect-timeout: "10" diff --git a/examples/customization/custom-errors/index.html b/examples/customization/custom-errors/index.html index cae969aeb..2b1b16f7d 100644 --- a/examples/customization/custom-errors/index.html +++ b/examples/customization/custom-errors/index.html @@ -1,4 +1,4 @@ - Custom Errors - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml + Custom Errors - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml service "nginx-errors" created deployment.apps "nginx-errors" created This should have created a Deployment and a Service with the name nginx-errors. $ kubectl get deploy,svc @@ -7,7 +7,7 @@ deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s - Ingress controller configuration ¶ If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the NGINX Ingress controller Service. $ kubectl get svc ingress-nginx + Ingress controller configuration ¶ If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the Ingress-Nginx Controller Service. $ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example. Testing error pages ¶ Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/ diff --git a/examples/customization/custom-headers/index.html b/examples/customization/custom-headers/index.html index ddd97dc36..ca6c12c4a 100644 --- a/examples/customization/custom-headers/index.html +++ b/examples/customization/custom-headers/index.html @@ -1,6 +1,6 @@ - Custom Headers - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... + External OAUTH Authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External OAUTH Authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication External OAUTH Authentication Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Overview Key Detail Example: OAuth2 Proxy + Kubernetes-Dashboard Prepare Test External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... metadata: name: application annotations: diff --git a/examples/customization/configuration-snippets/index.html b/examples/customization/configuration-snippets/index.html index 5f11f913a..45c6ffd1e 100644 --- a/examples/customization/configuration-snippets/index.html +++ b/examples/customization/configuration-snippets/index.html @@ -1,4 +1,4 @@ - Configuration Snippets - NGINX Ingress Controller Skip to content NGINX Ingress Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml + Configuration Snippets - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml Test ¶ Check if the contents of the annotation are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml + Custom Configuration - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml apiVersion: v1 data: proxy-connect-timeout: "10" diff --git a/examples/customization/custom-errors/index.html b/examples/customization/custom-errors/index.html index cae969aeb..2b1b16f7d 100644 --- a/examples/customization/custom-errors/index.html +++ b/examples/customization/custom-errors/index.html @@ -1,4 +1,4 @@ - Custom Errors - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml + Custom Errors - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml service "nginx-errors" created deployment.apps "nginx-errors" created This should have created a Deployment and a Service with the name nginx-errors. $ kubectl get deploy,svc @@ -7,7 +7,7 @@ deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s - Ingress controller configuration ¶ If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the NGINX Ingress controller Service. $ kubectl get svc ingress-nginx + Ingress controller configuration ¶ If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the Ingress-Nginx Controller Service. $ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example. Testing error pages ¶ Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/ diff --git a/examples/customization/custom-headers/index.html b/examples/customization/custom-headers/index.html index ddd97dc36..ca6c12c4a 100644 --- a/examples/customization/custom-headers/index.html +++ b/examples/customization/custom-headers/index.html @@ -1,6 +1,6 @@ - Custom Headers - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
External OAUTH Authentication ¶ Overview ¶ The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources. Important This annotation requires ingress-nginx-controller v0.9.0 or greater. Key Detail ¶ This functionality is enabled by deploying multiple Ingress objects for a single host. One 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 authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint. Sample: ... metadata: name: application annotations: diff --git a/examples/customization/configuration-snippets/index.html b/examples/customization/configuration-snippets/index.html index 5f11f913a..45c6ffd1e 100644 --- a/examples/customization/configuration-snippets/index.html +++ b/examples/customization/configuration-snippets/index.html @@ -1,4 +1,4 @@ - Configuration Snippets - NGINX Ingress Controller Skip to content NGINX Ingress Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml + Configuration Snippets - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml Test ¶ Check if the contents of the annotation are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml + Custom Configuration - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml apiVersion: v1 data: proxy-connect-timeout: "10" diff --git a/examples/customization/custom-errors/index.html b/examples/customization/custom-errors/index.html index cae969aeb..2b1b16f7d 100644 --- a/examples/customization/custom-errors/index.html +++ b/examples/customization/custom-errors/index.html @@ -1,4 +1,4 @@ - Custom Errors - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml + Custom Errors - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml service "nginx-errors" created deployment.apps "nginx-errors" created This should have created a Deployment and a Service with the name nginx-errors. $ kubectl get deploy,svc @@ -7,7 +7,7 @@ deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s - Ingress controller configuration ¶ If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the NGINX Ingress controller Service. $ kubectl get svc ingress-nginx + Ingress controller configuration ¶ If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the Ingress-Nginx Controller Service. $ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example. Testing error pages ¶ Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/ diff --git a/examples/customization/custom-headers/index.html b/examples/customization/custom-headers/index.html index ddd97dc36..ca6c12c4a 100644 --- a/examples/customization/custom-headers/index.html +++ b/examples/customization/custom-headers/index.html @@ -1,6 +1,6 @@ - Custom Headers - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml + Configuration Snippets - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Configuration Snippets Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Configuration Snippets Table of contents Ingress Test Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Ingress Test Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml Test ¶ Check if the contents of the annotation are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml + Custom Configuration - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml apiVersion: v1 data: proxy-connect-timeout: "10" diff --git a/examples/customization/custom-errors/index.html b/examples/customization/custom-errors/index.html index cae969aeb..2b1b16f7d 100644 --- a/examples/customization/custom-errors/index.html +++ b/examples/customization/custom-errors/index.html @@ -1,4 +1,4 @@ - Custom Errors - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml + Custom Errors - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml service "nginx-errors" created deployment.apps "nginx-errors" created This should have created a Deployment and a Service with the name nginx-errors. $ kubectl get deploy,svc @@ -7,7 +7,7 @@ deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s - Ingress controller configuration ¶ If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the NGINX Ingress controller Service. $ kubectl get svc ingress-nginx + Ingress controller configuration ¶ If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the Ingress-Nginx Controller Service. $ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example. Testing error pages ¶ Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/ diff --git a/examples/customization/custom-headers/index.html b/examples/customization/custom-headers/index.html index ddd97dc36..ca6c12c4a 100644 --- a/examples/customization/custom-headers/index.html +++ b/examples/customization/custom-headers/index.html @@ -1,6 +1,6 @@ - Custom Headers - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Configuration Snippets ¶ Ingress ¶ The 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 an example of specifying custom headers. kubectl apply -f ingress.yaml Test ¶ Check if the contents of the annotation are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf
Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml + Custom Configuration - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Configuration Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml apiVersion: v1 data: proxy-connect-timeout: "10" diff --git a/examples/customization/custom-errors/index.html b/examples/customization/custom-errors/index.html index cae969aeb..2b1b16f7d 100644 --- a/examples/customization/custom-errors/index.html +++ b/examples/customization/custom-errors/index.html @@ -1,4 +1,4 @@ - Custom Errors - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml + Custom Errors - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml service "nginx-errors" created deployment.apps "nginx-errors" created This should have created a Deployment and a Service with the name nginx-errors. $ kubectl get deploy,svc @@ -7,7 +7,7 @@ deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s - Ingress controller configuration ¶ If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the NGINX Ingress controller Service. $ kubectl get svc ingress-nginx + Ingress controller configuration ¶ If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the Ingress-Nginx Controller Service. $ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example. Testing error pages ¶ Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/ diff --git a/examples/customization/custom-headers/index.html b/examples/customization/custom-headers/index.html index ddd97dc36..ca6c12c4a 100644 --- a/examples/customization/custom-headers/index.html +++ b/examples/customization/custom-headers/index.html @@ -1,6 +1,6 @@ - Custom Headers - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Custom Configuration ¶ Using a ConfigMap is possible to customize the NGINX configuration For example, if we want to change the timeouts we need to create a ConfigMap: $ cat configmap.yaml apiVersion: v1 data: proxy-connect-timeout: "10" diff --git a/examples/customization/custom-errors/index.html b/examples/customization/custom-errors/index.html index cae969aeb..2b1b16f7d 100644 --- a/examples/customization/custom-errors/index.html +++ b/examples/customization/custom-errors/index.html @@ -1,4 +1,4 @@ - Custom Errors - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml + Custom Errors - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml service "nginx-errors" created deployment.apps "nginx-errors" created This should have created a Deployment and a Service with the name nginx-errors. $ kubectl get deploy,svc @@ -7,7 +7,7 @@ deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s - Ingress controller configuration ¶ If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the NGINX Ingress controller Service. $ kubectl get svc ingress-nginx + Ingress controller configuration ¶ If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the Ingress-Nginx Controller Service. $ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example. Testing error pages ¶ Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/ diff --git a/examples/customization/custom-headers/index.html b/examples/customization/custom-headers/index.html index ddd97dc36..ca6c12c4a 100644 --- a/examples/customization/custom-headers/index.html +++ b/examples/customization/custom-headers/index.html @@ -1,6 +1,6 @@ - Custom Headers - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml + Custom Errors - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Errors Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Errors Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Customized default backend Ingress controller configuration Testing error pages Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml service "nginx-errors" created deployment.apps "nginx-errors" created This should have created a Deployment and a Service with the name nginx-errors. $ kubectl get deploy,svc @@ -7,7 +7,7 @@ deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s - Ingress controller configuration ¶ If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the NGINX Ingress controller Service. $ kubectl get svc ingress-nginx + Ingress controller configuration ¶ If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the Ingress-Nginx Controller Service. $ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example. Testing error pages ¶ Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/ diff --git a/examples/customization/custom-headers/index.html b/examples/customization/custom-headers/index.html index ddd97dc36..ca6c12c4a 100644 --- a/examples/customization/custom-headers/index.html +++ b/examples/customization/custom-headers/index.html @@ -1,6 +1,6 @@ - Custom Headers - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Custom Errors ¶ This example demonstrates how to use a custom backend to render custom error pages. If you are using Helm Chart, look at example values and don't forget to add configMap to your deployment, otherwise continue with Customized default backend manual deployment. Customized default backend ¶ First, create the custom default-backend. It will be used by the Ingress controller later on. To do that, you can take a look at the example manifest in this project's GitHub repository. $ kubectl create -f custom-default-backend.yaml service "nginx-errors" created deployment.apps "nginx-errors" created This should have created a Deployment and a Service with the name nginx-errors. $ kubectl get deploy,svc @@ -7,7 +7,7 @@ deployment.apps/nginx-errors 1 1 1 10s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/nginx-errors ClusterIP 10.0.0.12 <none> 80/TCP 10s - Ingress controller configuration ¶ If you do not already have an instance of the NGINX Ingress controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the NGINX Ingress controller Service. $ kubectl get svc ingress-nginx + Ingress controller configuration ¶ If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the deployment guide, then follow these steps: Edit the ingress-nginx-controller Deployment and set the value of the --default-backend-service flag to the name of the newly created error backend. Edit the ingress-nginx-controller ConfigMap and create the key custom-http-errors with a value of 404,503. Take note of the IP address assigned to the Ingress-Nginx Controller Service. $ kubectl get svc ingress-nginx NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx ClusterIP 10.0.0.13 <none> 80/TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example. Testing error pages ¶ Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/ diff --git a/examples/customization/custom-headers/index.html b/examples/customization/custom-headers/index.html index ddd97dc36..ca6c12c4a 100644 --- a/examples/customization/custom-headers/index.html +++ b/examples/customization/custom-headers/index.html @@ -1,6 +1,6 @@ - Custom Headers - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the nginx ingress controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml + Custom Headers - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom Headers Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers Custom Headers Table of contents Caveats Workaround Example Test External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Caveats Workaround Example Test Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf Skip to content NGINX Ingress Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Custom Headers ¶ Caveats ¶ Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers. Workaround ¶ To work around this limitation, perform a rolling restart of the deployment. Example ¶ This example demonstrates configuration of the Ingress-Nginx Controller via a ConfigMap to pass a custom list of headers to the upstream server. custom-headers.yaml defines a ConfigMap in the ingress-nginx namespace named custom-headers, holding several custom X-prefixed HTTP headers. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/custom-headers.yaml configmap.yaml defines a ConfigMap in the ingress-nginx namespace named ingress-nginx-controller. This controls the global configuration of the ingress controller, and already exists in a standard installation. The key proxy-set-headers is set to cite the previously-created ingress-nginx/custom-headers ConfigMap. kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap.yaml - The nginx ingress controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml + The Ingress-Nginx Controller will read the ingress-nginx/ingress-nginx-controller ConfigMap, find the proxy-set-headers key, read HTTP headers from the ingress-nginx/custom-headers ConfigMap, and include those HTTP headers in all requests flowing from nginx to the backends. The above example was for passing a custom list of headers to the upstream server. To pass the custom headers before sending response traffic to the client, use the add-headers key: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/custom-headers/configmap-client-response.yaml Test ¶ Check the contents of the ConfigMaps are present in the nginx.conf file using: kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf
External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ + External authentication - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller External authentication Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication External authentication Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Test 1: public service with no auth header Test 2: secure service with no auth header Test 3: public service with valid auth header Test 4: secure service with valid auth header External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
External authentication, authentication service response headers propagation ¶ This example demonstrates propagation of selected authentication service response headers to a backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as follows: $ kubectl create -f deploy/ deployment "demo-auth-service" created service "demo-auth-service" created ingress "demo-auth-service" created diff --git a/examples/customization/jwt/index.html b/examples/customization/jwt/index.html index 48e07f20a..a628c5713 100644 --- a/examples/customization/jwt/index.html +++ b/examples/customization/jwt/index.html @@ -1,4 +1,4 @@ - Accommodation for JWT - NGINX Ingress Controller Skip to content NGINX Ingress Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... + Accommodation for JWT - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Accommodation for JWT Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Symptoms Increase buffer size for headers Using helm Manually in kubernetes config files Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Accommodation for JWT ¶ JWT (short for Json Web Token) is an authentication method widely used. Basically an authentication server generates a JWT and you then use this token in every request you make to a backend service. The JWT can be quite big and is present in every http headers. This means you may have to adapt the max-header size of your nginx-ingress in order to support it. Symptoms ¶ If you use JWT and you get http 502 error from your ingress, it may be a sign that the buffer size is not big enough. To be 100% sure look at the logs of the ingress-nginx-controller pod, you should see something like this: upstream sent too big header while reading response header from upstream... Increase buffer size for headers ¶ In nginx, we want to modify the property proxy-buffer-size. The size is arbitrary. It depends on your needs. Be aware that a high value can lower the performance of your ingress proxy. In general a value of 16k should get you covered. Using helm ¶ If you're using helm you can simply use the config properties. # -- Will add custom configuration options to Nginx https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ config: proxy-buffer-size: 16k diff --git a/examples/customization/ssl-dh-param/index.html b/examples/customization/ssl-dh-param/index.html index 75873abcc..7cb7c7754 100644 --- a/examples/customization/ssl-dh-param/index.html +++ b/examples/customization/ssl-dh-param/index.html @@ -1,4 +1,4 @@ - Custom DH parameters for perfect forward secrecy - NGINX Ingress Controller Skip to content NGINX Ingress Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test 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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
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 a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml + Custom DH parameters for perfect forward secrecy - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Custom DH parameters for perfect forward secrecy Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Custom DH parameters for perfect forward secrecy Table of contents Custom configuration Custom DH parameters secret Test Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Custom configuration Custom DH parameters secret Test Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Custom DH parameters for perfect forward secrecy ¶ This example aims to demonstrate the deployment of an Ingress-Nginx Controller and use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with "Perfect Forward Secrecy". Custom configuration ¶ $ cat configmap.yaml apiVersion: v1 data: ssl-dh-param: "ingress-nginx/lb-dhparam" diff --git a/examples/customization/sysctl/index.html b/examples/customization/sysctl/index.html index ded3fe636..1ae8da85c 100644 --- a/examples/customization/sysctl/index.html +++ b/examples/customization/sysctl/index.html @@ -1,4 +1,4 @@ - Sysctl tuning - NGINX Ingress Controller Skip to content NGINX Ingress Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ + Sysctl tuning - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Sysctl tuning Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes. Skip to content NGINX Ingress Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide NGINX Ingress Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment Without TLS With TLS Testing gRPC Multi TLS certificate termination Rewrite Static IPs TLS termination Pod Security Policy (PSP) Developer Guide Developer Guide Getting Started Code Overview Table of contents Deployment Without TLS With TLS Testing Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment
Sysctl tuning ¶ This example aims to demonstrate the use of an Init Container to adjust sysctl default values using kubectl patch. kubectl patch deployment -n ingress-nginx ingress-nginx-controller \ --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/customization/sysctl/patch.json)" Changes: Backlog Queue setting net.core.somaxconn from 128 to 32768 Ephemeral Ports setting net.ipv4.ip_local_port_range from 32768 60999 to 1024 65000 In a post from the NGINX blog, it is possible to see an explanation for the changes.
Docker registry ¶ This example demonstrates how to deploy a docker registry in the cluster and configure Ingress to enable access from the Internet. Deployment ¶ First we deploy the docker registry in the cluster: kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/docker-registry/deployment.yaml + Docker registry - Ingress-Nginx Controller Skip to content Ingress-Nginx Controller Docker registry Initializing search kubernetes/ingress-nginx Welcome Deployment User guide Examples Developer Guide Ingress-Nginx Controller kubernetes/ingress-nginx Welcome Welcome Welcome How it works Troubleshooting kubectl plugin Deployment Deployment Installation Guide Bare-metal considerations Role Based Access Control (RBAC) Upgrade Hardening guide User guide User guide NGINX Configuration NGINX Configuration Introduction Basic usage Annotations ConfigMap Custom NGINX template Log format Command line arguments Custom errors Default backend Exposing TCP and UDP services Exposing FCGI services Regular expressions in paths External Articles Miscellaneous Prometheus and Grafana installation Multiple Ingress controllers TLS/HTTPS Third party addons Third party addons ModSecurity Web Application Firewall OpenTracing OpenTelemetry Examples Examples Introduction Prerequisites Sticky Sessions Auth Auth Basic Authentication Client Certificate Authentication External Basic Authentication External OAUTH Authentication Customization Customization Configuration Snippets Custom Configuration Custom Errors Custom Headers External authentication Custom DH parameters for perfect forward secrecy Sysctl tuning Docker registry Docker registry Table of contents Deployment