DevFW-CICD/ingress-nginx-helm
16
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Deploy GitHub Pages

Browse source
This commit is contained in:
Travis Bot 2018-09-27 01:20:39 +00:00
parent 7356ddd980
commit 7e487c12b5
38 changed files with 1815 additions and 276 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

153
deploy/baremetal/index.html
View file

@ -1216,16 +1216,32 @@ by a DHCP server.</p>
<p class="admonition-title">Example</p>
<p>Given the following 3-node Kubernetes cluster (the external IP is added as an example, in most bare-metal
environments this value is &lt;None>)</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl describe node
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl describe node
<span class="go">NAME STATUS ROLES EXTERNAL-IP</span>
<span class="go">host-1 Ready master 203.0.113.1</span>
<span class="go">host-2 Ready node 203.0.113.2</span>
<span class="go">host-3 Ready node 203.0.113.3</span>
</pre></div>
</td></tr></table>
<p>After creating the following ConfigMap, MetalLB takes ownership of one of the IP addresses in the pool and updates
the <em>loadBalancer</em> IP field of the <code class="codehilite">ingress-nginx</code> Service accordingly.</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">apiVersion</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">v1</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">apiVersion</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">v1</span>
<span class="l l-Scalar l-Scalar-Plain">kind</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">ConfigMap</span>
<span class="l l-Scalar l-Scalar-Plain">metadata</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">namespace</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">metallb-system</span>
@ -1238,21 +1254,29 @@ the <em>loadBalancer</em> IP field of the <code class="codehilite">ingress-nginx
<span class="no">addresses:</span>
<span class="no">- 203.0.113.2-203.0.113.3</span>
</pre></div>
</td></tr></table>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl -n ingress-nginx get svc
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl -n ingress-nginx get svc
<span class="go">NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S)</span>
<span class="go">default-http-backend ClusterIP 10.0.64.249 &lt;none&gt; 80/TCP</span>
<span class="go">ingress-nginx LoadBalancer 10.0.220.217 203.0.113.3 80:30100/TCP,443:30101/TCP</span>
</pre></div>
</td></tr></table>
</div>
<p>As soon as MetalLB sets the external IP address of the <code class="codehilite">ingress-nginx</code> LoadBalancer Service, the corresponding entries
are created in the iptables NAT table and the node with the selected IP address starts responding to HTTP requests on
the ports configured in the LoadBalancer Service:</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> curl -D- http://203.0.113.3 -H <span class="s1">&#39;Host: myapp.example.com&#39;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> curl -D- http://203.0.113.3 -H <span class="s1">&#39;Host: myapp.example.com&#39;</span>
<span class="go">HTTP/1.1 200 OK</span>
<span class="go">Server: nginx/1.15.2</span>
</pre></div>
</td></tr></table>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
@ -1277,20 +1301,29 @@ requests.</p>
<div class="admonition example">
<p class="admonition-title">Example</p>
<p>Given the NodePort <code class="codehilite">30100</code> allocated to the <code class="codehilite">ingress-nginx</code> Service</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl -n ingress-nginx get svc
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl -n ingress-nginx get svc
<span class="go">NAME TYPE CLUSTER-IP PORT(S)</span>
<span class="go">default-http-backend ClusterIP 10.0.64.249 80/TCP</span>
<span class="go">ingress-nginx NodePort 10.0.220.217 80:30100/TCP,443:30101/TCP</span>
</pre></div>
</td></tr></table>
<p>and a Kubernetes node with the public IP address <code class="codehilite">203.0.113.2</code> (the external IP is added as an example, in most
bare-metal environments this value is &lt;None>)</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl describe node
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl describe node
<span class="go">NAME STATUS ROLES EXTERNAL-IP</span>
<span class="go">host-1 Ready master 203.0.113.1</span>
<span class="go">host-2 Ready node 203.0.113.2</span>
<span class="go">host-3 Ready node 203.0.113.3</span>
</pre></div>
</td></tr></table>
<p>a client would reach an Ingress with <code class="codehilite"><span class="n">host</span><span class="o">:</span> <span class="n">myapp</span><span class="o">.</span><span class="na">example</span><span class="o">.</span><span class="na">com</span></code> at <code class="codehilite">http://myapp.example.com:30100</code>, where the
myapp.example.com subdomain resolves to the 203.0.113.2 IP address.</p>
@ -1322,20 +1355,30 @@ the NGINX Ingress controller should be scheduled or not scheduled.</p>
<p class="admonition-title">Example</p>
<p>In a Kubernetes cluster composed of 3 nodes (the external IP is added as an example, in most bare-metal environments
this value is &lt;None>)</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl describe node
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl describe node
<span class="go">NAME STATUS ROLES EXTERNAL-IP</span>
<span class="go">host-1 Ready master 203.0.113.1</span>
<span class="go">host-2 Ready node 203.0.113.2</span>
<span class="go">host-3 Ready node 203.0.113.3</span>
</pre></div>
</td></tr></table>
<p>with a <code class="codehilite">nginx-ingress-controller</code> Deployment composed of 2 replicas</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl -n ingress-nginx get pod -o wide
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl -n ingress-nginx get pod -o wide
<span class="go">NAME READY STATUS IP NODE</span>
<span class="go">default-http-backend-7c5bc89cc9-p86md 1/1 Running 172.17.1.1 host-2</span>
<span class="go">nginx-ingress-controller-cf9ff8c96-8vvf8 1/1 Running 172.17.0.3 host-3</span>
<span class="go">nginx-ingress-controller-cf9ff8c96-pxsds 1/1 Running 172.17.1.4 host-2</span>
</pre></div>
</td></tr></table>
<p>Requests sent to <code class="codehilite">host-2</code> and <code class="codehilite">host-3</code> would be forwarded to NGINX and original client's IP would be preserved,
while requests to <code class="codehilite">host-1</code> would get dropped because there is no NGINX replica running on that node.</p>
@ -1345,10 +1388,13 @@ while requests to <code class="codehilite">host-1</code> would get dropped becau
</ul>
<p>Because NodePort Services do not get a LoadBalancerIP assigned by definition, the NGINX Ingress controller <strong>does not
update the status of Ingress objects it manages</strong>.</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get ingress
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get ingress
<span class="go">NAME HOSTS ADDRESS PORTS</span>
<span class="go">test-ingress myapp.example.com 80</span>
</pre></div>
</td></tr></table>
<p>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 <code class="codehilite">externalIPs</code> field of the <code class="codehilite">ingress-nginx</code>
@ -1363,26 +1409,39 @@ documentation as well as the section about <a href="#external-ips">External IPs<
<p class="admonition-title">Example</p>
<p>Given the following 3-node Kubernetes cluster (the external IP is added as an example, in most bare-metal
environments this value is &lt;None>)</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl describe node
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl describe node
<span class="go">NAME STATUS ROLES EXTERNAL-IP</span>
<span class="go">host-1 Ready master 203.0.113.1</span>
<span class="go">host-2 Ready node 203.0.113.2</span>
<span class="go">host-3 Ready node 203.0.113.3</span>
</pre></div>
</td></tr></table>
<p>one could edit the <code class="codehilite">ingress-nginx</code> Service and add the following field to the object spec</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">spec</span><span class="p p-Indicator">:</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">spec</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">externalIPs</span><span class="p p-Indicator">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">203.0.113.1</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">203.0.113.2</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">203.0.113.3</span>
</pre></div>
</td></tr></table>
<p>which would in turn be reflected on Ingress objects as follows:</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get ingress -o wide
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get ingress -o wide
<span class="go">NAME HOSTS ADDRESS PORTS</span>
<span class="go">test-ingress myapp.example.com 203.0.113.1,203.0.113.2,203.0.113.3 80</span>
</pre></div>
</td></tr></table>
</div>
<ul>
@ -1394,11 +1453,15 @@ for generating redirect URLs that take into account the URL used by external cli
<p class="admonition-title">Example</p>
<p>Redirects generated by NGINX, for instance HTTP to HTTPS or <code class="codehilite">domain</code> to <code class="codehilite">www.domain</code>, are generated without
NodePort:</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> curl -D- http://myapp.example.com:30100<span class="sb">`</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> curl -D- http://myapp.example.com:30100<span class="sb">`</span>
<span class="go">HTTP/1.1 308 Permanent Redirect</span>
<span class="go">Server: nginx/1.15.2</span>
<span class="go">Location: https://myapp.example.com/ #-&gt; missing NodePort in HTTPS redirect</span>
</pre></div>
</td></tr></table>
</div>
<h2 id="via-the-host-network">Via the host network<a class="headerlink" href="#via-the-host-network" title="Permanent link">&para;</a></h2>
@ -1412,10 +1475,13 @@ interfaces, without the extra network translation imposed by NodePort Services.<
Service exists in the target cluster, it is <strong>recommended to delete it</strong>.</p>
</div>
<p>This can be achieved by enabling the <code class="codehilite">hostNetwork</code> option in the Pods' spec.</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">template</span><span class="p p-Indicator">:</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">template</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">spec</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">hostNetwork</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">true</span>
</pre></div>
</td></tr></table>
<div class="admonition danger">
<p class="admonition-title">Security considerations</p>
@ -1426,24 +1492,35 @@ including the host's loopback. Please evaluate the impact this may have on the s
<p class="admonition-title">Example</p>
<p>Consider this <code class="codehilite">nginx-ingress-controller</code> Deployment composed of 2 replicas, NGINX Pods inherit from the IP address
of their host instead of an internal Pod IP.</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl -n ingress-nginx get pod -o wide
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl -n ingress-nginx get pod -o wide
<span class="go">NAME READY STATUS IP NODE</span>
<span class="go">default-http-backend-7c5bc89cc9-p86md 1/1 Running 172.17.1.1 host-2</span>
<span class="go">nginx-ingress-controller-5b4cf5fc6-7lg6c 1/1 Running 203.0.113.3 host-3</span>
<span class="go">nginx-ingress-controller-5b4cf5fc6-lzrls 1/1 Running 203.0.113.2 host-2</span>
</pre></div>
</td></tr></table>
</div>
<p>One major limitation of this deployment approach is that only <strong>a single NGINX Ingress controller Pod</strong> 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:</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl -n ingress-nginx describe pod &lt;unschedulable-nginx-ingress-controller-pod&gt;
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl -n ingress-nginx describe pod &lt;unschedulable-nginx-ingress-controller-pod&gt;
<span class="go">...</span>
<span class="go">Events:</span>
<span class="go"> Type Reason From Message</span>
<span class="go"> ---- ------ ---- -------</span>
<span class="go"> Warning FailedScheduling default-scheduler 0/3 nodes are available: 3 node(s) didn&#39;t have free ports for the requested pod ports.</span>
</pre></div>
</td></tr></table>
<p>One way to ensure only schedulable Pods are created is to deploy the NGINX Ingress controller as a <em>DaemonSet</em> instead
of a traditional Deployment.</p>
@ -1468,10 +1545,13 @@ expected to resolve internal names for any reason.</p>
<p>Because there is no Service exposing the NGINX Ingress controller in a configuration using the host network, the default
<code class="codehilite">--publish-service</code> flag used in standard cloud setups <strong>does not apply</strong> and the status of all Ingress objects remains
blank.</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get ingress
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get ingress
<span class="go">NAME HOSTS ADDRESS PORTS</span>
<span class="go">test-ingress myapp.example.com 80</span>
</pre></div>
</td></tr></table>
<p>Instead, and because bare-metal nodes usually don't have an ExternalIP, one has to enable the
<a href="../../user-guide/cli-arguments/"><code class="codehilite">--report-node-internal-ip-address</code></a> flag, which sets the status of all Ingress objects to the internal IP
@ -1479,18 +1559,26 @@ address of all nodes running the NGINX Ingress controller.</p>
<div class="admonition example">
<p class="admonition-title">Example</p>
<p>Given a <code class="codehilite">nginx-ingress-controller</code> DaemonSet composed of 2 replicas</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl -n ingress-nginx get pod -o wide
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl -n ingress-nginx get pod -o wide
<span class="go">NAME READY STATUS IP NODE</span>
<span class="go">default-http-backend-7c5bc89cc9-p86md 1/1 Running 172.17.1.1 host-2</span>
<span class="go">nginx-ingress-controller-5b4cf5fc6-7lg6c 1/1 Running 203.0.113.3 host-3</span>
<span class="go">nginx-ingress-controller-5b4cf5fc6-lzrls 1/1 Running 203.0.113.2 host-2</span>
</pre></div>
</td></tr></table>
<p>the controller sets the status of all Ingress objects it manages to the following value:</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get ingress -o wide
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get ingress -o wide
<span class="go">NAME HOSTS ADDRESS PORTS</span>
<span class="go">test-ingress myapp.example.com 203.0.113.2,203.0.113.3 80</span>
</pre></div>
</td></tr></table>
</div>
<div class="admonition note">
@ -1523,28 +1611,46 @@ Service. These IP addresses <strong>must belong to the target node</strong>.</p>
<p class="admonition-title">Example</p>
<p>Given the following 3-node Kubernetes cluster (the external IP is added as an example, in most bare-metal
environments this value is &lt;None>)</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl describe node
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl describe node
<span class="go">NAME STATUS ROLES EXTERNAL-IP</span>
<span class="go">host-1 Ready master 203.0.113.1</span>
<span class="go">host-2 Ready node 203.0.113.2</span>
<span class="go">host-3 Ready node 203.0.113.3</span>
</pre></div>
</td></tr></table>
<p>and the following <code class="codehilite">ingress-nginx</code> NodePort Service</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl -n ingress-nginx get svc
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl -n ingress-nginx get svc
<span class="go">NAME TYPE CLUSTER-IP PORT(S)</span>
<span class="go">ingress-nginx NodePort 10.0.220.217 80:30100/TCP,443:30101/TCP</span>
</pre></div>
</td></tr></table>
<p>One could set the following external IPs in the Service spec, and NGINX would become available on both the NodePort
and the Service port:</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">spec</span><span class="p p-Indicator">:</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">spec</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">externalIPs</span><span class="p p-Indicator">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">203.0.113.2</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">203.0.113.3</span>
</pre></div>
</td></tr></table>
<div class="codehilite"><pre><span></span><span class="gp">$</span> curl -D- http://myapp.example.com:30100
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6
7</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> curl -D- http://myapp.example.com:30100
<span class="go">HTTP/1.1 200 OK</span>
<span class="go">Server: nginx/1.15.2</span>
@ -1552,6 +1658,7 @@ and the Service port:</p>
<span class="go">HTTP/1.1 200 OK</span>
<span class="go">Server: nginx/1.15.2</span>
</pre></div>
</td></tr></table>
<p>We assume the myapp.example.com subdomain above resolves to both 203.0.113.2 and 203.0.113.3 IP addresses.</p>
</div>

56
deploy/index.html
View file

@ -1392,8 +1392,9 @@
<h2 id="generic-deployment">Generic Deployment<a class="headerlink" href="#generic-deployment" title="Permanent link">&para;</a></h2>
<p>The following resources are required for a generic deployment.</p>
<h3 id="mandatory-command">Mandatory command<a class="headerlink" href="#mandatory-command" title="Permanent link">&para;</a></h3>
<div class="codehilite"><pre><span></span><span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/mandatory.yaml</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/mandatory.yaml</span>
</pre></div>
</td></tr></table>
<div class="admonition attention">
<p class="admonition-title">Attention</p>
@ -1409,30 +1410,37 @@ To change this behavior use the flag <code class="codehilite">--watch-namespace<
<h4 id="docker-for-mac">Docker for Mac<a class="headerlink" href="#docker-for-mac" title="Permanent link">&para;</a></h4>
<p>Kubernetes is available in Docker for Mac (from <a href="https://docs.docker.com/docker-for-mac/release-notes/#stable-releases-of-2018">version 18.06.0-ce</a>)</p>
<p>Create a service</p>
<div class="codehilite"><pre><span></span><span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/cloud-generic.yaml</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/cloud-generic.yaml</span>
</pre></div>
</td></tr></table>
<h4 id="minikube">minikube<a class="headerlink" href="#minikube" title="Permanent link">&para;</a></h4>
<p>For standard usage:</p>
<div class="codehilite"><pre><span></span><span class="go">minikube addons enable ingress</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">minikube addons enable ingress</span>
</pre></div>
</td></tr></table>
<p>For development:</p>
<ol>
<li>Disable the ingress addon:</li>
</ol>
<div class="codehilite"><pre><span></span><span class="gp">$</span> minikube addons disable ingress
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> minikube addons disable ingress
</pre></div>
</td></tr></table>
<ol>
<li>Execute <code class="codehilite">make dev-env</code></li>
<li>Confirm the <code class="codehilite">nginx-ingress-controller</code> deployment exists:</li>
</ol>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get pods -n ingress-nginx
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get pods -n ingress-nginx
<span class="go">NAME READY STATUS RESTARTS AGE</span>
<span class="go">default-http-backend-66b447d9cf-rrlf9 1/1 Running 0 12s</span>
<span class="go">nginx-ingress-controller-fdcdcd6dd-vvpgs 1/1 Running 0 11s</span>
</pre></div>
</td></tr></table>
<h4 id="aws">AWS<a class="headerlink" href="#aws" title="Permanent link">&para;</a></h4>
<p>In AWS we use an Elastic Load Balancer (ELB) to expose the NGINX Ingress controller behind a Service of <code class="codehilite">Type=LoadBalancer</code>.
@ -1447,17 +1455,21 @@ Please check the <a href="https://aws.amazon.com/elasticloadbalancing/details/">
<p>For L4:</p>
<p>Check that no change is necessary with regards to the ELB idle timeout. In some scenarios, users may want to modify the ELB idle timeout, so please check the <a href="#elb-idle-timeouts">ELB Idle Timeouts section</a> for additional information. If a change is required, users will need to update the value of <code class="codehilite">service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout</code> in <code class="codehilite">provider/aws/service-l4.yaml</code></p>
<p>Then execute:</p>
<div class="codehilite"><pre><span></span><span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/service-l4.yaml</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/service-l4.yaml</span>
<span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/patch-configmap-l4.yaml</span>
</pre></div>
</td></tr></table>
<p>For L7:</p>
<p>Change line of the file <code class="codehilite">provider/aws/service-l7.yaml</code> replacing the dummy id with a valid one <code class="codehilite">&quot;arn:aws:acm:us-west-2:XXXXXXXX:certificate/XXXXXX-XXXXXXX-XXXXXXX-XXXXXXXX&quot;</code></p>
<p>Check that no change is necessary with regards to the ELB idle timeout. In some scenarios, users may want to modify the ELB idle timeout, so please check the <a href="#elb-idle-timeouts">ELB Idle Timeouts section</a> for additional information. If a change is required, users will need to update the value of <code class="codehilite">service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout</code> in <code class="codehilite">provider/aws/service-l7.yaml</code></p>
<p>Then execute:</p>
<div class="codehilite"><pre><span></span><span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/service-l7.yaml</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/service-l7.yaml</span>
<span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/patch-configmap-l7.yaml</span>
</pre></div>
</td></tr></table>
<p>This example creates an ELB with just two listeners, one in port 80 and another in port 443</p>
<p><img alt="Listeners" src="../images/elb-l7-listener.png" /></p>
@ -1468,22 +1480,26 @@ Please check the <a href="https://aws.amazon.com/elasticloadbalancing/details/">
<p>More information with regards to idle timeouts for your Load Balancer can be found in the <a href="https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/config-idle-timeout.html">official AWS documentation</a>.</p>
<h5 id="network-load-balancer-nlb">Network Load Balancer (NLB)<a class="headerlink" href="#network-load-balancer-nlb" title="Permanent link">&para;</a></h5>
<p>This type of load balancer is supported since v1.10.0 as an ALPHA feature.</p>
<div class="codehilite"><pre><span></span><span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/service-nlb.yaml</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/service-nlb.yaml</span>
</pre></div>
</td></tr></table>
<h4 id="gce-gke">GCE - GKE<a class="headerlink" href="#gce-gke" title="Permanent link">&para;</a></h4>
<div class="codehilite"><pre><span></span><span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/cloud-generic.yaml</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/cloud-generic.yaml</span>
</pre></div>
</td></tr></table>
<p><strong>Important Note:</strong> proxy protocol is not supported in GCE/GKE</p>
<h4 id="azure">Azure<a class="headerlink" href="#azure" title="Permanent link">&para;</a></h4>
<div class="codehilite"><pre><span></span><span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/cloud-generic.yaml</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/cloud-generic.yaml</span>
</pre></div>
</td></tr></table>
<h4 id="bare-metal">Bare-metal<a class="headerlink" href="#bare-metal" title="Permanent link">&para;</a></h4>
<p>Using <a href="https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport">NodePort</a>:</p>
<div class="codehilite"><pre><span></span><span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/baremetal/service-nodeport.yaml</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/baremetal/service-nodeport.yaml</span>
</pre></div>
</td></tr></table>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
@ -1491,32 +1507,40 @@ Please check the <a href="https://aws.amazon.com/elasticloadbalancing/details/">
</div>
<h3 id="verify-installation">Verify installation<a class="headerlink" href="#verify-installation" title="Permanent link">&para;</a></h3>
<p>To check if the ingress controller pods have started, run the following command:</p>
<div class="codehilite"><pre><span></span><span class="go">kubectl get pods --all-namespaces -l app.kubernetes.io/name=ingress-nginx --watch</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl get pods --all-namespaces -l app.kubernetes.io/name=ingress-nginx --watch</span>
</pre></div>
</td></tr></table>
<p>Once the operator pods are running, you can cancel the above command by typing <code class="codehilite">Ctrl+C</code>.
Now, you are ready to create your first ingress.</p>
<h3 id="detect-installed-version">Detect installed version<a class="headerlink" href="#detect-installed-version" title="Permanent link">&para;</a></h3>
<p>To detect which version of the ingress controller is running, exec into the pod and run <code class="codehilite">nginx-ingress-controller version</code> command.</p>
<div class="codehilite"><pre><span></span><span class="go">POD_NAMESPACE=ingress-nginx</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">POD_NAMESPACE=ingress-nginx</span>
<span class="go">POD_NAME=$(kubectl get pods -n $POD_NAMESPACE -l app.kubernetes.io/name=ingress-nginx -o jsonpath=&#39;{.items[0].metadata.name}&#39;)</span>
<span class="go">kubectl exec -it $POD_NAME -n $POD_NAMESPACE -- /nginx-ingress-controller --version</span>
</pre></div>
</td></tr></table>
<h2 id="using-helm">Using Helm<a class="headerlink" href="#using-helm" title="Permanent link">&para;</a></h2>
<p>NGINX Ingress controller can be installed via <a href="https://helm.sh/">Helm</a> using the chart <a href="https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress">stable/nginx-ingress</a> from the official charts repository.
To install the chart with the release name <code class="codehilite">my-nginx</code>:</p>
<div class="codehilite"><pre><span></span><span class="go">helm install stable/nginx-ingress --name my-nginx</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">helm install stable/nginx-ingress --name my-nginx</span>
</pre></div>
</td></tr></table>
<p>If the kubernetes cluster has RBAC enabled, then run:</p>
<div class="codehilite"><pre><span></span><span class="go">helm install stable/nginx-ingress --name my-nginx --set rbac.create=true</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">helm install stable/nginx-ingress --name my-nginx --set rbac.create=true</span>
</pre></div>
</td></tr></table>
<p>Detect installed version:</p>
<div class="codehilite"><pre><span></span><span class="go">POD_NAME=$(kubectl get pods -l app.kubernetes.io/name=ingress-nginx -o jsonpath=&#39;{.items[0].metadata.name}&#39;)</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">POD_NAME=$(kubectl get pods -l app.kubernetes.io/name=ingress-nginx -o jsonpath=&#39;{.items[0].metadata.name}&#39;)</span>
<span class="go">kubectl exec -it $POD_NAME -- /nginx-ingress-controller --version</span>
</pre></div>
</td></tr></table>

23
deploy/upgrade/index.html
View file

@ -1149,7 +1149,20 @@ make sure your templates are compatible with the new version of ingress-nginx</e
<p>To upgrade your ingress-nginx installation, it should be enough to change the version of the image
in the controller Deployment.</p>
<p>I.e. if your deployment resource looks like (partial example):</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">kind</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">Deployment</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">kind</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">Deployment</span>
<span class="l l-Scalar l-Scalar-Plain">metadata</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">nginx-ingress-controller</span>
<span class="l l-Scalar l-Scalar-Plain">namespace</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">ingress-nginx</span>
@ -1164,19 +1177,23 @@ in the controller Deployment.</p>
<span class="l l-Scalar l-Scalar-Plain">image</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.9.0</span>
<span class="l l-Scalar l-Scalar-Plain">args</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">...</span>
</pre></div>
</td></tr></table>
<p>simply change the <code class="codehilite">0.9.0</code> tag to the version you wish to upgrade to.
The easiest way to do this is e.g. (do note you may need to change the name parameter according to your installation):</p>
<div class="codehilite"><pre><span></span>kubectl set image deployment/nginx-ingress-controller \
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>kubectl set image deployment/nginx-ingress-controller \
nginx-ingress-controller=nginx:quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.18.0
</pre></div>
</td></tr></table>
<p>For interactive editing, use <code class="codehilite">kubectl edit deployment nginx-ingress-controller</code>.</p>
<h2 id="with-helm">With Helm<a class="headerlink" href="#with-helm" title="Permanent link">&para;</a></h2>
<p>If you installed ingress-nginx using the Helm command in the deployment docs so its name is <code class="codehilite">ngx-ingress</code>,
you should be able to upgrade using</p>
<div class="codehilite"><pre><span></span>helm upgrade --reuse-values ngx-ingress stable/nginx-ingress
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>helm upgrade --reuse-values ngx-ingress stable/nginx-ingress
</pre></div>
</td></tr></table>

76
development/index.html
View file

@ -1281,12 +1281,17 @@ It includes how to build, test, and release ingress controllers.</p>
<h2 id="quick-start">Quick Start<a class="headerlink" href="#quick-start" title="Permanent link">&para;</a></h2>
<h3 id="getting-the-code">Getting the code<a class="headerlink" href="#getting-the-code" title="Permanent link">&para;</a></h3>
<p>The code must be checked out as a subdirectory of k8s.io, and not github.com.</p>
<div class="codehilite"><pre><span></span>mkdir -p $GOPATH/src/k8s.io
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>mkdir -p $GOPATH/src/k8s.io
cd $GOPATH/src/k8s.io
# Replace &quot;$YOUR_GITHUB_USERNAME&quot; below with your github username
git clone https://github.com/$YOUR_GITHUB_USERNAME/ingress-nginx.git
cd ingress-nginx
</pre></div>
</td></tr></table>
<h3 id="initial-developer-environment-build">Initial developer environment build<a class="headerlink" href="#initial-developer-environment-build" title="Permanent link">&para;</a></h3>
<blockquote>
@ -1294,24 +1299,35 @@ cd ingress-nginx
See <a href="https://github.com/kubernetes/minikube/releases">releases</a> for installation instructions. </p>
</blockquote>
<p>If you are using <strong>MacOS</strong> and deploying to <strong>minikube</strong>, the following command will build the local nginx controller container image and deploy the ingress controller onto a minikube cluster with RBAC enabled in the namespace <code class="codehilite">ingress-nginx</code>:</p>
<div class="codehilite"><pre><span></span>$ make dev-env
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ make dev-env
</pre></div>
</td></tr></table>
<h3 id="updating-the-deployment">Updating the deployment<a class="headerlink" href="#updating-the-deployment" title="Permanent link">&para;</a></h3>
<p>The nginx controller container image can be rebuilt using:
<div class="codehilite"><pre><span></span>$ <span class="nv">ARCH</span><span class="o">=</span>amd64 <span class="nv">TAG</span><span class="o">=</span>dev <span class="nv">REGISTRY</span><span class="o">=</span><span class="nv">$USER</span>/ingress-controller make build container
</pre></div></p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ <span class="nv">ARCH</span><span class="o">=</span>amd64 <span class="nv">TAG</span><span class="o">=</span>dev <span class="nv">REGISTRY</span><span class="o">=</span><span class="nv">$USER</span>/ingress-controller make build container
</pre></div>
</td></tr></table></p>
<p>The image will only be used by pods created after the rebuild. To delete old pods which will cause new ones to spin up:
<div class="codehilite"><pre><span></span>$ kubectl get pods -n ingress-nginx
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ kubectl get pods -n ingress-nginx
$ kubectl delete pod -n ingress-nginx nginx-ingress-controller-&lt;unique-pod-id&gt;
</pre></div></p>
</pre></div>
</td></tr></table></p>
<h2 id="dependencies">Dependencies<a class="headerlink" href="#dependencies" title="Permanent link">&para;</a></h2>
<p>The build uses dependencies in the <code class="codehilite">vendor</code> directory, which
must be installed before building a binary/image. Occasionally, you
might need to update the dependencies.</p>
<p>This guide requires you to install the <a href="https://github.com/golang/dep">dep</a> dependency tool.</p>
<p>Check the version of <code class="codehilite">dep</code> you are using and make sure it is up to date.</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> dep version
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6
7
8</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> dep version
<span class="go">dep:</span>
<span class="go"> version : devel</span>
<span class="go"> build date : </span>
@ -1320,63 +1336,84 @@ might need to update the dependencies.</p>
<span class="go"> go compiler : gc</span>
<span class="go"> platform : linux/amd64</span>
</pre></div>
</td></tr></table>
<p>If you have an older version of <code class="codehilite">dep</code>, you can update it as follows:</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> go get -u github.com/golang/dep
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> go get -u github.com/golang/dep
</pre></div>
</td></tr></table>
<p>This will automatically save the dependencies to the <code class="codehilite">vendor/</code> directory.</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> <span class="nb">cd</span> <span class="nv">$GOPATH</span>/src/k8s.io/ingress-nginx
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> <span class="nb">cd</span> <span class="nv">$GOPATH</span>/src/k8s.io/ingress-nginx
<span class="gp">$</span> dep ensure
<span class="gp">$</span> dep ensure -update
<span class="gp">$</span> dep prune
</pre></div>
</td></tr></table>
<h2 id="building">Building<a class="headerlink" href="#building" title="Permanent link">&para;</a></h2>
<p>All ingress controllers are built through a Makefile. Depending on your
requirements you can build a raw server binary, a local container image,
or push an image to a remote repository.</p>
<p>In order to use your local Docker, you may need to set the following environment variables:</p>
<div class="codehilite"><pre><span></span><span class="gp">#</span> <span class="s2">&quot;gcloud docker&quot;</span> <span class="o">(</span>default<span class="o">)</span> or <span class="s2">&quot;docker&quot;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">#</span> <span class="s2">&quot;gcloud docker&quot;</span> <span class="o">(</span>default<span class="o">)</span> or <span class="s2">&quot;docker&quot;</span>
<span class="gp">$</span> <span class="nb">export</span> <span class="nv">DOCKER</span><span class="o">=</span>&lt;docker&gt;
<span class="gp">#</span> <span class="s2">&quot;quay.io/kubernetes-ingress-controller&quot;</span> <span class="o">(</span>default<span class="o">)</span>, <span class="s2">&quot;index.docker.io&quot;</span>, or your own registry
<span class="gp">$</span> <span class="nb">export</span> <span class="nv">REGISTRY</span><span class="o">=</span>&lt;your-docker-registry&gt;
</pre></div>
</td></tr></table>
<p>To find the registry simply run: <code class="codehilite">docker system info | grep Registry</code></p>
<h3 id="nginx-controller">Nginx Controller<a class="headerlink" href="#nginx-controller" title="Permanent link">&para;</a></h3>
<p>Build a raw server binary
<div class="codehilite"><pre><span></span><span class="gp">$</span> make build
</pre></div></p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> make build
</pre></div>
</td></tr></table></p>
<p><a href="https://github.com/kubernetes/ingress-nginx/issues/387">TODO</a>: add more specific instructions needed for raw server binary.</p>
<p>Build a local container image</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> <span class="nv">TAG</span><span class="o">=</span>&lt;tag&gt; <span class="nv">REGISTRY</span><span class="o">=</span><span class="nv">$USER</span>/ingress-controller make docker-build
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> <span class="nv">TAG</span><span class="o">=</span>&lt;tag&gt; <span class="nv">REGISTRY</span><span class="o">=</span><span class="nv">$USER</span>/ingress-controller make docker-build
</pre></div>
</td></tr></table>
<p>Push the container image to a remote repository</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> <span class="nv">TAG</span><span class="o">=</span>&lt;tag&gt; <span class="nv">REGISTRY</span><span class="o">=</span><span class="nv">$USER</span>/ingress-controller make docker-push
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> <span class="nv">TAG</span><span class="o">=</span>&lt;tag&gt; <span class="nv">REGISTRY</span><span class="o">=</span><span class="nv">$USER</span>/ingress-controller make docker-push
</pre></div>
</td></tr></table>
<h2 id="deploying">Deploying<a class="headerlink" href="#deploying" title="Permanent link">&para;</a></h2>
<p>There are several ways to deploy the ingress controller onto a cluster.
Please check the <a href="./deploy">deployment guide</a></p>
<h2 id="testing">Testing<a class="headerlink" href="#testing" title="Permanent link">&para;</a></h2>
<p>To run unit-tests, just run</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> <span class="nb">cd</span> <span class="nv">$GOPATH</span>/src/k8s.io/ingress-nginx
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> <span class="nb">cd</span> <span class="nv">$GOPATH</span>/src/k8s.io/ingress-nginx
<span class="gp">$</span> make <span class="nb">test</span>
</pre></div>
</td></tr></table>
<p>If you have access to a Kubernetes cluster, you can also run e2e tests using ginkgo.</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> <span class="nb">cd</span> <span class="nv">$GOPATH</span>/src/k8s.io/ingress-nginx
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> <span class="nb">cd</span> <span class="nv">$GOPATH</span>/src/k8s.io/ingress-nginx
<span class="gp">$</span> make e2e-test
</pre></div>
</td></tr></table>
<p>To run unit-tests for lua code locally, run:</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> <span class="nb">cd</span> <span class="nv">$GOPATH</span>/src/k8s.io/ingress-nginx
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> <span class="nb">cd</span> <span class="nv">$GOPATH</span>/src/k8s.io/ingress-nginx
<span class="gp">$</span> ./rootfs/etc/nginx/lua/test/up.sh
<span class="gp">$</span> make lua-test
</pre></div>
</td></tr></table>
<p>Lua tests are located in <code class="codehilite">$GOPATH/src/k8s.io/ingress-nginx/rootfs/etc/nginx/lua/test</code>. When creating a new test file it must follow the naming convention <code class="codehilite">&lt;mytest&gt;_test.lua</code> or it will be ignored. </p>
<h2 id="releasing">Releasing<a class="headerlink" href="#releasing" title="Permanent link">&para;</a></h2>
@ -1385,8 +1422,9 @@ to a wider Kubernetes user base, push the image to a container registry, like
<a href="https://cloud.google.com/container-registry/">gcr.io</a>. All release images are hosted under <code class="codehilite">gcr.io/google_containers</code> and
tagged according to a <a href="http://semver.org/">semver</a> scheme.</p>
<p>An example release might look like:
<div class="codehilite"><pre><span></span>$ make release
</pre></div></p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ make release
</pre></div>
</td></tr></table></p>
<p>Please follow these guidelines to cut a release:</p>
<ul>
<li>Update the <a href="https://help.github.com/articles/creating-releases/">release</a>

124
examples/PREREQUISITES/index.html
View file

@ -1212,7 +1212,15 @@
<h2 id="tls-certificates">TLS certificates<a class="headerlink" href="#tls-certificates" title="Permanent link">&para;</a></h2>
<p>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</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> openssl req -x509 -nodes -days <span class="m">365</span> -newkey rsa:2048 -keyout tls.key -out tls.crt -subj <span class="s2">&quot;/CN=nginxsvc/O=nginxsvc&quot;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6
7
8
9</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> openssl req -x509 -nodes -days <span class="m">365</span> -newkey rsa:2048 -keyout tls.key -out tls.crt -subj <span class="s2">&quot;/CN=nginxsvc/O=nginxsvc&quot;</span>
<span class="go">Generating a 2048 bit RSA private key</span>
<span class="go">................+++</span>
<span class="go">................+++</span>
@ -1222,6 +1230,7 @@ key/cert pair with an arbitrarily chosen hostname, created as follows</p>
<span class="gp">$</span> kubectl create secret tls tls-secret --key tls.key --cert tls.crt
<span class="go">secret &quot;tls-secret&quot; created</span>
</pre></div>
</td></tr></table>
<h2 id="ca-authentication">CA Authentication<a class="headerlink" href="#ca-authentication" title="Permanent link">&para;</a></h2>
<p>You can act as your very own CA, or use an existing one. As an exercise / learning, we're going to generate our
@ -1230,7 +1239,16 @@ own CA, and also generate a client certificate.</p>
<h3 id="generating-a-ca">Generating a CA<a class="headerlink" href="#generating-a-ca" title="Permanent link">&para;</a></h3>
<p>First of all, you've to generate a CA. This is going to be the one who will sign your client certificates.
In real production world, you may face CAs with intermediate certificates, as the following:</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> openssl s_client -connect www.google.com:443
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> openssl s_client -connect www.google.com:443
<span class="go">[...]</span>
<span class="go">---</span>
<span class="go">Certificate chain</span>
@ -1241,11 +1259,14 @@ In real production world, you may face CAs with intermediate certificates, as th
<span class="go"> 2 s:/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA</span>
<span class="go"> i:/C=US/O=Equifax/OU=Equifax Secure Certificate Authority</span>
</pre></div>
</td></tr></table>
<p>To generate our CA Certificate, we've to run the following commands:</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> openssl genrsa -out ca.key <span class="m">2048</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> openssl genrsa -out ca.key <span class="m">2048</span>
<span class="gp">$</span> openssl req -x509 -new -nodes -key ca.key -days <span class="m">10000</span> -out ca.crt -subj <span class="s2">&quot;/CN=example-ca&quot;</span>
</pre></div>
</td></tr></table>
<p>This will generate two files: A private key (ca.key) and a public key (ca.crt). This CA is valid for 10000 days.
The ca.crt can be used later in the step of creation of CA authentication secret.</p>
@ -1253,7 +1274,13 @@ The ca.crt can be used later in the step of creation of CA authentication secret
<p>The following steps generate a client certificate signed by the CA generated above. This client can be
used to authenticate in a tls-auth configured ingress.</p>
<p>First, we need to generate an 'openssl.cnf' file that will be used while signing the keys:</p>
<div class="codehilite"><pre><span></span><span class="go">[req]</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6
7</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">[req]</span>
<span class="go">req_extensions = v3_req</span>
<span class="go">distinguished_name = req_distinguished_name</span>
<span class="go">[req_distinguished_name]</span>
@ -1261,47 +1288,68 @@ used to authenticate in a tls-auth configured ingress.</p>
<span class="go">basicConstraints = CA:FALSE</span>
<span class="go">keyUsage = nonRepudiation, digitalSignature, keyEncipherment</span>
</pre></div>
</td></tr></table>
<p>Then, a user generates his very own private key (that he needs to keep secret)
and a CSR (Certificate Signing Request) that will be sent to the CA to sign and generate a certificate.</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> openssl genrsa -out client1.key <span class="m">2048</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> openssl genrsa -out client1.key <span class="m">2048</span>
<span class="gp">$</span> openssl req -new -key client1.key -out client1.csr -subj <span class="s2">&quot;/CN=client1&quot;</span> -config openssl.cnf
</pre></div>
</td></tr></table>
<p>As the CA receives the generated 'client1.csr' file, it signs it and generates a client.crt certificate:</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> openssl x509 -req -in client1.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client1.crt -days <span class="m">365</span> -extensions v3_req -extfile openssl.cnf
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> openssl x509 -req -in client1.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client1.crt -days <span class="m">365</span> -extensions v3_req -extfile openssl.cnf
</pre></div>
</td></tr></table>
<p>Then, you'll have 3 files: the client.key (user's private key), client.crt (user's public key) and client.csr (disposable CSR).</p>
<h3 id="creating-the-ca-authentication-secret">Creating the CA Authentication secret<a class="headerlink" href="#creating-the-ca-authentication-secret" title="Permanent link">&para;</a></h3>
<p>If you're using the CA Authentication feature, you need to generate a secret containing
all the authorized CAs. You must download them from your CA site in PEM format (like the following):</p>
<div class="codehilite"><pre><span></span>-----BEGIN CERTIFICATE-----
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>-----BEGIN CERTIFICATE-----
[....]
-----END CERTIFICATE-----
</pre></div>
</td></tr></table>
<p>You can have as many certificates as you want. If they're in the binary DER format,
you can convert them as the following:</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem
</pre></div>
</td></tr></table>
<p>Then, you've to concatenate them all in only one file, named 'ca.crt' as the following:</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> cat certificate1.crt certificate2.crt certificate3.crt &gt;&gt; ca.crt
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> cat certificate1.crt certificate2.crt certificate3.crt &gt;&gt; ca.crt
</pre></div>
</td></tr></table>
<p>The final step is to create a secret with the content of this file. This secret is going to be used in
the TLS Auth directive:</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create secret generic caingress --namespace<span class="o">=</span>default --from-file<span class="o">=</span>ca.crt<span class="o">=</span>&lt;ca.crt&gt;
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create secret generic caingress --namespace<span class="o">=</span>default --from-file<span class="o">=</span>ca.crt<span class="o">=</span>&lt;ca.crt&gt;
</pre></div>
</td></tr></table>
<p><strong>Note:</strong> You can also generate the CA Authentication Secret along with the TLS Secret by using:
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create secret generic caingress --namespace<span class="o">=</span>default --from-file<span class="o">=</span>ca.crt<span class="o">=</span>&lt;ca.crt&gt; --from-file<span class="o">=</span>tls.crt<span class="o">=</span>&lt;tls.crt&gt; --from-file<span class="o">=</span>tls.key<span class="o">=</span>&lt;tls.key&gt;
</pre></div></p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create secret generic caingress --namespace<span class="o">=</span>default --from-file<span class="o">=</span>ca.crt<span class="o">=</span>&lt;ca.crt&gt; --from-file<span class="o">=</span>tls.crt<span class="o">=</span>&lt;tls.crt&gt; --from-file<span class="o">=</span>tls.key<span class="o">=</span>&lt;tls.key&gt;
</pre></div>
</td></tr></table></p>
<h2 id="test-http-service">Test HTTP Service<a class="headerlink" href="#test-http-service" title="Permanent link">&para;</a></h2>
<p>All examples that require a test HTTP Service use the standard http-svc pod,
which you can deploy as follows</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create -f http-svc.yaml
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create -f http-svc.yaml
<span class="go">service &quot;http-svc&quot; created</span>
<span class="go">replicationcontroller &quot;http-svc&quot; created</span>
@ -1313,9 +1361,56 @@ which you can deploy as follows</p>
<span class="go">NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE</span>
<span class="go">http-svc 10.0.122.116 &lt;pending&gt; 80:30301/TCP 1d</span>
</pre></div>
</td></tr></table>
<p>You can test that the HTTP Service works by exposing it temporarily</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl patch svc http-svc -p <span class="s1">&#39;{&quot;spec&quot;:{&quot;type&quot;: &quot;LoadBalancer&quot;}}&#39;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl patch svc http-svc -p <span class="s1">&#39;{&quot;spec&quot;:{&quot;type&quot;: &quot;LoadBalancer&quot;}}&#39;</span>
<span class="go">&quot;http-svc&quot; patched</span>
<span class="gp">$</span> kubectl get svc http-svc
@ -1363,6 +1458,7 @@ which you can deploy as follows</p>
<span class="gp">$</span> kubectl patch svc http-svc -p <span class="s1">&#39;{&quot;spec&quot;:{&quot;type&quot;: &quot;NodePort&quot;}}&#39;</span>
<span class="go">&quot;http-svc&quot; patched</span>
</pre></div>
</td></tr></table>

36
examples/affinity/cookie/index.html
View file

@ -1170,12 +1170,43 @@
</tbody>
</table>
<p>You can create the ingress to test this</p>
<div class="codehilite"><pre><span></span><span class="go">kubectl create -f ingress.yaml</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl create -f ingress.yaml</span>
</pre></div>
</td></tr></table>
<h2 id="validation">Validation<a class="headerlink" href="#validation" title="Permanent link">&para;</a></h2>
<p>You can confirm that the Ingress works.</p>
<p><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl describe ing nginx-test
<p><table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl describe ing nginx-test
<span class="go">Name: nginx-test</span>
<span class="go">Namespace: default</span>
<span class="go">Address: </span>
@ -1207,6 +1238,7 @@
<span class="go">ETag: &quot;58875e6b-264&quot;</span>
<span class="go">Accept-Ranges: bytes</span>
</pre></div>
</td></tr></table>
In the example above, you can see a line containing the 'Set-Cookie: INGRESSCOOKIE' setting the right defined stickiness cookie.
This cookie is created by NGINX containing the hash of the used upstream in that request.
If the user changes this cookie, NGINX creates a new one and redirect the user to another upstream.</p>

117
examples/auth/basic/index.html
View file

@ -1085,18 +1085,33 @@
<h1 id="basic-authentication">Basic Authentication<a class="headerlink" href="#basic-authentication" title="Permanent link">&para;</a></h1>
<p>This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with <code class="codehilite">htpasswd</code>.
It's important the file generated is named <code class="codehilite">auth</code> (actually - that the secret has a key <code class="codehilite">data.auth</code>), otherwise the ingress-controller returns a 503.</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> htpasswd -c auth foo
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> htpasswd -c auth foo
<span class="go">New password: &lt;bar&gt;</span>
<span class="go">New password:</span>
<span class="go">Re-type new password:</span>
<span class="go">Adding password for user foo</span>
</pre></div>
</td></tr></table>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create secret generic basic-auth --from-file<span class="o">=</span>auth
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create secret generic basic-auth --from-file<span class="o">=</span>auth
<span class="go">secret &quot;basic-auth&quot; created</span>
</pre></div>
</td></tr></table>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get secret basic-auth -o yaml
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6
7
8
9</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get secret basic-auth -o yaml
<span class="go">apiVersion: v1</span>
<span class="go">data:</span>
<span class="go"> auth: Zm9vOiRhcHIxJE9GRzNYeWJwJGNrTDBGSERBa29YWUlsSDkuY3lzVDAK</span>
@ -1106,8 +1121,30 @@ It's important the file generated is named <code class="codehilite">auth</code>
<span class="go"> namespace: default</span>
<span class="go">type: Opaque</span>
</pre></div>
</td></tr></table>
<div class="codehilite"><pre><span></span><span class="go">echo &quot;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">echo &quot;</span>
<span class="go">apiVersion: extensions/v1beta1</span>
<span class="go">kind: Ingress</span>
<span class="go">metadata:</span>
@ -1130,8 +1167,32 @@ It's important the file generated is named <code class="codehilite">auth</code>
<span class="go"> servicePort: 80</span>
<span class="go">&quot; | kubectl create -f -</span>
</pre></div>
</td></tr></table>
<div class="codehilite"><pre><span></span>$ curl -v http://10.2.29.4/ -H &#39;Host: foo.bar.com&#39;
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ curl -v http://10.2.29.4/ -H &#39;Host: foo.bar.com&#39;
* Trying 10.2.29.4...
* Connected to 10.2.29.4 (10.2.29.4) port 80 (#0)
&gt; GET / HTTP/1.1
@ -1156,8 +1217,51 @@ It's important the file generated is named <code class="codehilite">auth</code>
<span class="nt">&lt;/html&gt;</span>
* Connection #0 to host 10.2.29.4 left intact
</pre></div>
</td></tr></table>
<div class="codehilite"><pre><span></span>$ curl -v http://10.2.29.4/ -H <span class="s1">&#39;Host: foo.bar.com&#39;</span> -u <span class="s1">&#39;foo:bar&#39;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ curl -v http://10.2.29.4/ -H <span class="s1">&#39;Host: foo.bar.com&#39;</span> -u <span class="s1">&#39;foo:bar&#39;</span>
* Trying <span class="m">10</span>.2.29.4...
* Connected to <span class="m">10</span>.2.29.4 <span class="o">(</span><span class="m">10</span>.2.29.4<span class="o">)</span> port <span class="m">80</span> <span class="o">(</span><span class="c1">#0)</span>
* Server auth using Basic with user <span class="s1">&#39;foo&#39;</span>
@ -1201,6 +1305,7 @@ BODY:
* Connection <span class="c1">#0 to host 10.2.29.4 left intact</span>
-no body in request-
</pre></div>
</td></tr></table>

142
examples/auth/external-auth/index.html
View file

@ -1130,7 +1130,40 @@
<h1 id="external-basic-authentication">External Basic Authentication<a class="headerlink" href="#external-basic-authentication" title="Permanent link">&para;</a></h1>
<h3 id="example-1">Example 1:<a class="headerlink" href="#example-1" title="Permanent link">&para;</a></h3>
<p>Use an external service (Basic Auth) located in <code class="codehilite">https://httpbin.org</code> </p>
<div class="codehilite"><pre><span></span>$ kubectl create -f ingress.yaml
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ kubectl create -f ingress.yaml
ingress <span class="s2">&quot;external-auth&quot;</span> created
$ kubectl get ing external-auth
@ -1165,9 +1198,34 @@ status:
- ip: <span class="m">172</span>.17.4.99
$
</pre></div>
</td></tr></table>
<p>Test 1: no username/password (expect code 401)</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> curl -k http://172.17.4.99 -v -H <span class="s1">&#39;Host: external-auth-01.sample.com&#39;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> curl -k http://172.17.4.99 -v -H <span class="s1">&#39;Host: external-auth-01.sample.com&#39;</span>
<span class="go">* Rebuilt URL to: http://172.17.4.99/</span>
<span class="go">* Trying 172.17.4.99...</span>
<span class="go">* Connected to 172.17.4.99 (172.17.4.99) port 80 (#0)</span>
@ -1193,9 +1251,52 @@ $
<span class="go">&lt;/html&gt;</span>
<span class="go">* Connection #0 to host 172.17.4.99 left intact</span>
</pre></div>
</td></tr></table>
<p>Test 2: valid username/password (expect code 200)
<div class="codehilite"><pre><span></span>$ curl -k http://172.17.4.99 -v -H <span class="s1">&#39;Host: external-auth-01.sample.com&#39;</span> -u <span class="s1">&#39;user:passwd&#39;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ curl -k http://172.17.4.99 -v -H <span class="s1">&#39;Host: external-auth-01.sample.com&#39;</span> -u <span class="s1">&#39;user:passwd&#39;</span>
* Rebuilt URL to: http://172.17.4.99/
* Trying <span class="m">172</span>.17.4.99...
* Connected to <span class="m">172</span>.17.4.99 <span class="o">(</span><span class="m">172</span>.17.4.99<span class="o">)</span> port <span class="m">80</span> <span class="o">(</span><span class="c1">#0)</span>
@ -1238,9 +1339,37 @@ x-real-ip<span class="o">=</span><span class="m">10</span>.2.60.1
BODY:
* Connection <span class="c1">#0 to host 172.17.4.99 left intact</span>
-no body in request-
</pre></div></p>
</pre></div>
</td></tr></table></p>
<p>Test 3: invalid username/password (expect code 401)
<div class="codehilite"><pre><span></span>curl -k http://172.17.4.99 -v -H &#39;Host: external-auth-01.sample.com&#39; -u &#39;user:user&#39;
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>curl -k http://172.17.4.99 -v -H &#39;Host: external-auth-01.sample.com&#39; -u &#39;user:user&#39;
* Rebuilt URL to: http://172.17.4.99/
* Trying 172.17.4.99...
* Connected to 172.17.4.99 (172.17.4.99) port 80 (#0)
@ -1268,7 +1397,8 @@ BODY:
<span class="nt">&lt;/body&gt;</span>
<span class="nt">&lt;/html&gt;</span>
* Connection #0 to host 172.17.4.99 left intact
</pre></div></p>
</pre></div>
</td></tr></table></p>

15
examples/auth/oauth-external-auth/index.html
View file

@ -1196,7 +1196,13 @@ One Ingress object has no special annotations and handles authentication.</p>
authenticate against the first Ingress's endpoint, and can redirect <code class="codehilite">401</code>s to the
same endpoint.</p>
<p>Sample:</p>
<div class="codehilite"><pre><span></span><span class="nn">...</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6
7</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="nn">...</span>
<span class="l l-Scalar l-Scalar-Plain">metadata</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">application</span>
<span class="l l-Scalar l-Scalar-Plain">annotations</span><span class="p p-Indicator">:</span>
@ -1204,6 +1210,7 @@ same endpoint.</p>
<span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/auth-signin</span><span class="p p-Indicator">:</span> <span class="s">&quot;https://$host/oauth2/start?rd=$escaped_request_uri&quot;</span>
<span class="nn">...</span>
</pre></div>
</td></tr></table>
<h3 id="example-oauth2-proxy-kubernetes-dashboard">Example: OAuth2 Proxy + Kubernetes-Dashboard<a class="headerlink" href="#example-oauth2-proxy-kubernetes-dashboard" title="Permanent link">&para;</a></h3>
<p>This example will show you how to deploy <a href="https://github.com/bitly/oauth2_proxy"><code class="codehilite">oauth2_proxy</code></a>
@ -1212,8 +1219,9 @@ into a Kubernetes cluster and use it to protect the Kubernetes Dashboard using g
<ol>
<li>Install the kubernetes dashboard</li>
</ol>
<div class="codehilite"><pre><span></span><span class="go">kubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.5.0.yaml</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.5.0.yaml</span>
</pre></div>
</td></tr></table>
<ol>
<li>Create a <a href="https://github.com/settings/applications/new">custom Github OAuth application</a></li>
@ -1243,8 +1251,9 @@ into a Kubernetes cluster and use it to protect the Kubernetes Dashboard using g
<ol>
<li>Deploy the oauth2 proxy and the ingress rules running:</li>
</ol>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create -f oauth2-proxy.yaml,dashboard-ingress.yaml
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create -f oauth2-proxy.yaml,dashboard-ingress.yaml
</pre></div>
</td></tr></table>
<p>Test the oauth integration accessing the configured URL, like <code class="codehilite">https://foo.bar.com</code></p>
<p><img alt="Register OAuth2 Application" src="images/github-auth.png" /></p>

3
examples/customization/configuration-snippets/index.html
View file

@ -1144,8 +1144,9 @@
<h1 id="configuration-snippets">Configuration Snippets<a class="headerlink" href="#configuration-snippets" title="Permanent link">&para;</a></h1>
<h2 id="ingress">Ingress<a class="headerlink" href="#ingress" title="Permanent link">&para;</a></h2>
<p>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 <a href="/examples/customization/custom-headers/README">this example</a>.</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl apply -f ingress.yaml
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl apply -f ingress.yaml
</pre></div>
</td></tr></table>
<h2 id="test">Test<a class="headerlink" href="#test" title="Permanent link">&para;</a></h2>
<p>Check if the contents of the annotation are present in the nginx.conf file using:

15
examples/customization/custom-configuration/index.html
View file

@ -1085,7 +1085,15 @@
<h1 id="custom-configuration">Custom Configuration<a class="headerlink" href="#custom-configuration" title="Permanent link">&para;</a></h1>
<p>Using a <a href="https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/">ConfigMap</a> is possible to customize the NGINX configuration</p>
<p>For example, if we want to change the timeouts we need to create a ConfigMap:</p>
<div class="codehilite"><pre><span></span>$ cat configmap.yaml
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6
7
8
9</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ cat configmap.yaml
apiVersion: v1
data:
proxy-connect-timeout: <span class="s2">&quot;10&quot;</span>
@ -1095,10 +1103,13 @@ kind: ConfigMap
metadata:
name: nginx-load-balancer-conf
</pre></div>
</td></tr></table>
<div class="codehilite"><pre><span></span>curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/customization/custom-configuration/configmap.yaml \
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/customization/custom-configuration/configmap.yaml \
| kubectl apply -f -
</pre></div>
</td></tr></table>
<p>If the Configmap it is updated, NGINX will be reloaded with the new configuration.</p>

43
examples/customization/custom-errors/index.html
View file

@ -1159,19 +1159,28 @@
<p>This example demonstrates how to use a custom backend to render custom error pages.</p>
<h2 id="customized-default-backend">Customized default backend<a class="headerlink" href="#customized-default-backend" title="Permanent link">&para;</a></h2>
<p>First, create the custom <code class="codehilite">default-backend</code>. It will be used by the Ingress controller later on.</p>
<div class="codehilite"><pre><span></span>$ kubectl create -f custom-default-backend.yaml
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ kubectl create -f custom-default-backend.yaml
service <span class="s2">&quot;nginx-errors&quot;</span> created
deployment.apps <span class="s2">&quot;nginx-errors&quot;</span> created
</pre></div>
</td></tr></table>
<p>This should have created a Deployment and a Service with the name <code class="codehilite">nginx-errors</code>.</p>
<div class="codehilite"><pre><span></span>$ kubectl get deploy,svc
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ kubectl get deploy,svc
NAME DESIRED CURRENT READY AGE
deployment.apps/nginx-errors <span class="m">1</span> <span class="m">1</span> <span class="m">1</span> 10s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT<span class="o">(</span>S<span class="o">)</span> AGE
service/nginx-errors ClusterIP <span class="m">10</span>.0.0.12 &lt;none&gt; <span class="m">80</span>/TCP 10s
</pre></div>
</td></tr></table>
<h2 id="ingress-controller-configuration">Ingress controller configuration<a class="headerlink" href="#ingress-controller-configuration" title="Permanent link">&para;</a></h2>
<p>If you do not already have an instance of the the NGINX Ingress controller running, deploy it according to the
@ -1186,10 +1195,13 @@ service/nginx-errors ClusterIP <span class="m">10</span>.0.0.12 &lt;none&g
</li>
<li>
<p>Take note of the IP address assigned to the NGINX Ingress controller Service.
<div class="codehilite"><pre><span></span>$ kubectl get svc ingress-nginx
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ kubectl get svc ingress-nginx
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT<span class="o">(</span>S<span class="o">)</span> AGE
ingress-nginx ClusterIP <span class="m">10</span>.0.0.13 &lt;none&gt; <span class="m">80</span>/TCP,443/TCP 10m
</pre></div></p>
</pre></div>
</td></tr></table></p>
</li>
</ol>
<div class="admonition note">
@ -1200,7 +1212,15 @@ Make sure you can use the Service to reach NGINX before proceeding with the rest
<h2 id="testing-error-pages">Testing error pages<a class="headerlink" href="#testing-error-pages" title="Permanent link">&para;</a></h2>
<p>Let us send a couple of HTTP requests using cURL and validate everything is working as expected.</p>
<p>A request to the default backend returns a 404 error with a custom message:</p>
<div class="codehilite"><pre><span></span>$ curl -D- http://10.0.0.13/
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6
7
8
9</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ curl -D- http://10.0.0.13/
HTTP/1.1 404 Not Found
Server: nginx/1.13.12
Date: Tue, 12 Jun 2018 19:11:24 GMT
@ -1210,9 +1230,19 @@ Connection: keep-alive
<span class="nt">&lt;span&gt;</span>The page you&#39;re looking for could not be found.<span class="nt">&lt;/span&gt;</span>
</pre></div>
</td></tr></table>
<p>A request with a custom <code class="codehilite">Accept</code> header returns the corresponding document type (JSON):</p>
<div class="codehilite"><pre><span></span>$ curl -D- -H <span class="s1">&#39;Accept: application/json&#39;</span> http://10.0.0.13/
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ curl -D- -H <span class="s1">&#39;Accept: application/json&#39;</span> http://10.0.0.13/
HTTP/1.1 <span class="m">404</span> Not Found
Server: nginx/1.13.12
Date: Tue, <span class="m">12</span> Jun <span class="m">2018</span> <span class="m">19</span>:12:36 GMT
@ -1223,6 +1253,7 @@ Vary: Accept-Encoding
<span class="o">{</span> <span class="s2">&quot;message&quot;</span>: <span class="s2">&quot;The page you&#39;re looking for could not be found&quot;</span> <span class="o">}</span>
</pre></div>
</td></tr></table>
<p>To go further with this example, feel free to deploy your own applications and Ingress objects, and validate that the
responses are still in the correct format when a backend returns 503 (eg. if you scale a Deployment down to 0 replica).</p>

7
examples/customization/custom-headers/index.html
View file

@ -1131,12 +1131,17 @@
<p>This example aims to demonstrate the deployment of an nginx ingress controller and
use a ConfigMap to configure a custom list of headers to be passed to the upstream
server</p>
<div class="codehilite"><pre><span></span><span class="go">curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/customization/custom-headers/configmap.yaml \</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/customization/custom-headers/configmap.yaml \</span>
<span class="go"> | kubectl apply -f -</span>
<span class="go">curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/customization/custom-headers/custom-headers.yaml \</span>
<span class="go"> | kubectl apply -f -</span>
</pre></div>
</td></tr></table>
<h2 id="test">Test<a class="headerlink" href="#test" title="Permanent link">&para;</a></h2>
<p>Check the contents of the configmap is present in the nginx.conf file using:

38
examples/customization/custom-upstream-check/index.html
View file

@ -1084,7 +1084,23 @@
<h1 id="custom-upstream-server-checks">Custom Upstream server checks<a class="headerlink" href="#custom-upstream-server-checks" title="Permanent link">&para;</a></h1>
<p>This example shows how is possible to create a custom configuration for a particular upstream associated with an Ingress rule.</p>
<div class="codehilite"><pre><span></span>echo &quot;
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>echo &quot;
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
@ -1102,15 +1118,24 @@ spec:
servicePort: 80
&quot; | kubectl create -f -
</pre></div>
</td></tr></table>
<p>Check the annotation is present in the Ingress rule:
<div class="codehilite"><pre><span></span>kubectl get ingress http-svc -o yaml
</pre></div></p>
<p>Check the NGINX configuration is updated using kubectl or the status page:</p>
<div class="codehilite"><pre><span></span>$ kubectl <span class="nb">exec</span> nginx-ingress-controller-v1ppm cat /etc/nginx/nginx.conf
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>kubectl get ingress http-svc -o yaml
</pre></div>
</td></tr></table></p>
<p>Check the NGINX configuration is updated using kubectl or the status page:</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ kubectl <span class="nb">exec</span> nginx-ingress-controller-v1ppm cat /etc/nginx/nginx.conf
</pre></div>
</td></tr></table>
<div class="codehilite"><pre><span></span><span class="o">....</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6
7</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="o">....</span>
<span class="nt">upstream</span> <span class="nt">default-http-svc-x-80</span> <span class="p">{</span>
<span class="err">least_conn</span><span class="p">;</span>
<span class="err">server</span> <span class="err">10.2.92.2:8080</span> <span class="err">max_fails=5</span> <span class="err">fail_timeout=30</span><span class="p">;</span>
@ -1118,6 +1143,7 @@ spec:
<span class="p">}</span>
<span class="o">....</span>
</pre></div>
</td></tr></table>

109
examples/customization/external-auth-headers/index.html
View file

@ -1097,7 +1097,25 @@ to backend service.</p>
</ul>
<p>You can deploy the controller as
follows:</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create -f deploy/
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create -f deploy/
<span class="go">deployment &quot;demo-auth-service&quot; created</span>
<span class="go">service &quot;demo-auth-service&quot; created</span>
<span class="go">ingress &quot;demo-auth-service&quot; created</span>
@ -1117,9 +1135,27 @@ follows:</p>
<span class="go">public-demo-echo-service public-demo-echo-service.kube.local 80 1m</span>
<span class="go">secure-demo-echo-service secure-demo-echo-service.kube.local 80 1m</span>
</pre></div>
</td></tr></table>
<p>Test 1: public service with no auth header</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> curl -H <span class="s1">&#39;Host: public-demo-echo-service.kube.local&#39;</span> -v <span class="m">192</span>.168.99.100
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> curl -H <span class="s1">&#39;Host: public-demo-echo-service.kube.local&#39;</span> -v <span class="m">192</span>.168.99.100
<span class="go">* Rebuilt URL to: 192.168.99.100/</span>
<span class="go">* Trying 192.168.99.100...</span>
<span class="go">* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0)</span>
@ -1138,9 +1174,33 @@ follows:</p>
<span class="go">* Connection #0 to host 192.168.99.100 left intact</span>
<span class="go">UserID: , UserRole:</span>
</pre></div>
</td></tr></table>
<p>Test 2: secure service with no auth header</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> curl -H <span class="s1">&#39;Host: secure-demo-echo-service.kube.local&#39;</span> -v <span class="m">192</span>.168.99.100
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> curl -H <span class="s1">&#39;Host: secure-demo-echo-service.kube.local&#39;</span> -v <span class="m">192</span>.168.99.100
<span class="go">* Rebuilt URL to: 192.168.99.100/</span>
<span class="go">* Trying 192.168.99.100...</span>
<span class="go">* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0)</span>
@ -1165,9 +1225,28 @@ follows:</p>
<span class="go">&lt;/html&gt;</span>
<span class="go">* Connection #0 to host 192.168.99.100 left intact</span>
</pre></div>
</td></tr></table>
<p>Test 3: public service with valid auth header</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> curl -H <span class="s1">&#39;Host: public-demo-echo-service.kube.local&#39;</span> -H <span class="s1">&#39;User:internal&#39;</span> -v <span class="m">192</span>.168.99.100
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> curl -H <span class="s1">&#39;Host: public-demo-echo-service.kube.local&#39;</span> -H <span class="s1">&#39;User:internal&#39;</span> -v <span class="m">192</span>.168.99.100
<span class="go">* Rebuilt URL to: 192.168.99.100/</span>
<span class="go">* Trying 192.168.99.100...</span>
<span class="go">* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0)</span>
@ -1187,9 +1266,28 @@ follows:</p>
<span class="go">* Connection #0 to host 192.168.99.100 left intact</span>
<span class="go">UserID: 1443635317331776148, UserRole: admin</span>
</pre></div>
</td></tr></table>
<p>Test 4: public service with valid auth header</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> curl -H <span class="s1">&#39;Host: secure-demo-echo-service.kube.local&#39;</span> -H <span class="s1">&#39;User:internal&#39;</span> -v <span class="m">192</span>.168.99.100
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> curl -H <span class="s1">&#39;Host: secure-demo-echo-service.kube.local&#39;</span> -H <span class="s1">&#39;User:internal&#39;</span> -v <span class="m">192</span>.168.99.100
<span class="go">* Rebuilt URL to: 192.168.99.100/</span>
<span class="go">* Trying 192.168.99.100...</span>
<span class="go">* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0)</span>
@ -1209,6 +1307,7 @@ follows:</p>
<span class="go">* Connection #0 to host 192.168.99.100 left intact</span>
<span class="go">UserID: 605394647632969758, UserRole: admin</span>
</pre></div>
</td></tr></table>

36
examples/customization/ssl-dh-param/index.html
View file

@ -1160,7 +1160,17 @@
use a ConfigMap to configure custom Diffie-Hellman parameters file to help with
"Perfect Forward Secrecy".</p>
<h2 id="custom-configuration">Custom configuration<a class="headerlink" href="#custom-configuration" title="Permanent link">&para;</a></h2>
<div class="codehilite"><pre><span></span><span class="gp">$</span> cat configmap.yaml
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> cat configmap.yaml
<span class="go">apiVersion: v1</span>
<span class="go">data:</span>
<span class="go"> ssl-dh-param: &quot;ingress-nginx/lb-dhparam&quot;</span>
@ -1172,16 +1182,30 @@ use a ConfigMap to configure custom Diffie-Hellman parameters file to help with
<span class="go"> app.kubernetes.io/name: ingress-nginx</span>
<span class="go"> app.kubernetes.io/part-of: ingress-nginx</span>
</pre></div>
</td></tr></table>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create -f configmap.yaml
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create -f configmap.yaml
</pre></div>
</td></tr></table>
<h2 id="custom-dh-parameters-secret">Custom DH parameters secret<a class="headerlink" href="#custom-dh-parameters-secret" title="Permanent link">&para;</a></h2>
<div class="codehilite"><pre><span></span><span class="gp">$</span>&gt; openssl dhparam <span class="m">1024</span> <span class="m">2</span>&gt; /dev/null <span class="p">|</span> base64
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span>&gt; openssl dhparam <span class="m">1024</span> <span class="m">2</span>&gt; /dev/null <span class="p">|</span> base64
<span class="go">LS0tLS1CRUdJTiBESCBQQVJBTUVURVJ...</span>
</pre></div>
</td></tr></table>
<div class="codehilite"><pre><span></span><span class="gp">$</span> cat ssl-dh-param.yaml
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> cat ssl-dh-param.yaml
<span class="go">apiVersion: v1</span>
<span class="go">data:</span>
<span class="go"> dhparam.pem: &quot;LS0tLS1CRUdJTiBESCBQQVJBTUVURVJ...&quot;</span>
@ -1193,9 +1217,11 @@ use a ConfigMap to configure custom Diffie-Hellman parameters file to help with
<span class="go"> app.kubernetes.io/name: ingress-nginx</span>
<span class="go"> app.kubernetes.io/part-of: ingress-nginx</span>
</pre></div>
</td></tr></table>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create -f ssl-dh-param.yaml
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create -f ssl-dh-param.yaml
</pre></div>
</td></tr></table>
<h2 id="test">Test<a class="headerlink" href="#test" title="Permanent link">&para;</a></h2>
<p>Check the contents of the configmap is present in the nginx.conf file using:

3
examples/customization/sysctl/index.html
View file

@ -1085,8 +1085,9 @@
<h1 id="sysctl-tuning">Sysctl tuning<a class="headerlink" href="#sysctl-tuning" title="Permanent link">&para;</a></h1>
<p>This example aims to demonstrate the use of an Init Container to adjust sysctl default values
using <code class="codehilite">kubectl patch</code></p>
<div class="codehilite"><pre><span></span><span class="go">kubectl patch deployment -n ingress-nginx nginx-ingress-controller --patch=&quot;$(cat patch.json)&quot;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl patch deployment -n ingress-nginx nginx-ingress-controller --patch=&quot;$(cat patch.json)&quot;</span>
</pre></div>
</td></tr></table>

14
examples/docker-registry/index.html
View file

@ -1183,8 +1183,9 @@
<p>This example demonstrates how to deploy a <a href="https://github.com/docker/distribution">docker registry</a> in the cluster and configure Ingress enable access from Internet</p>
<h2 id="deployment">Deployment<a class="headerlink" href="#deployment" title="Permanent link">&para;</a></h2>
<p>First we deploy the docker registry in the cluster:</p>
<div class="codehilite"><pre><span></span><span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/docker-registry/deployment.yaml</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/docker-registry/deployment.yaml</span>
</pre></div>
</td></tr></table>
<div class="admonition important">
<p class="admonition-title">Important</p>
@ -1194,8 +1195,9 @@
<p>The next required step is creation of the ingress rules. To do this we have two options: with and without TLS</p>
<h3 id="without-tls">Without TLS<a class="headerlink" href="#without-tls" title="Permanent link">&para;</a></h3>
<p>Download and edit the yaml deployment replacing <code class="codehilite">registry.&lt;your domain&gt;</code> with a valid DNS name pointing to the ingress controller:</p>
<div class="codehilite"><pre><span></span><span class="go">wget https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/docker-registry/ingress-without-tls.yaml</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">wget https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/docker-registry/ingress-without-tls.yaml</span>
</pre></div>
</td></tr></table>
<div class="admonition important">
<p class="admonition-title">Important</p>
@ -1204,16 +1206,20 @@
<p>Please check <a href="https://docs.docker.com/registry/insecure/#deploy-a-plain-http-registry">deploy a plain http registry</a></p>
<h3 id="with-tls">With TLS<a class="headerlink" href="#with-tls" title="Permanent link">&para;</a></h3>
<p>Download and edit the yaml deployment replacing <code class="codehilite">registry.&lt;your domain&gt;</code> with a valid DNS name pointing to the ingress controller:</p>
<div class="codehilite"><pre><span></span><span class="go">wget https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/docker-registry/ingress-with-tls.yaml</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">wget https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/docker-registry/ingress-with-tls.yaml</span>
</pre></div>
</td></tr></table>
<p>Deploy <a href="https://github.com/jetstack/kube-lego">kube lego</a> use <a href="https://letsencrypt.org/">Let's Encrypt</a> certificates or edit the ingress rule to use a secret with an existing SSL certificate.</p>
<h3 id="testing">Testing<a class="headerlink" href="#testing" title="Permanent link">&para;</a></h3>
<p>To test the registry is working correctly we download a known image from <a href="https://hub.docker.com">docker hub</a>, create a tag pointing to the new registry and upload the image:</p>
<div class="codehilite"><pre><span></span><span class="go">docker pull ubuntu:16.04</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">docker pull ubuntu:16.04</span>
<span class="go">docker tag ubuntu:16.04 `registry.&lt;your domain&gt;/ubuntu:16.04`</span>
<span class="go">docker push `registry.&lt;your domain&gt;/ubuntu:16.04`</span>
</pre></div>
</td></tr></table>
<p>Please replace <code class="codehilite">registry.&lt;your domain&gt;</code> with your domain.</p>

23
examples/grpc/index.html
View file

@ -1228,21 +1228,28 @@ nginx controller.</p>
application provided here as an example. </li>
</ol>
<h3 id="step-1-kubernetes-deployment">Step 1: kubernetes <code class="codehilite">Deployment</code><a class="headerlink" href="#step-1-kubernetes-deployment" title="Permanent link">&para;</a></h3>
<div class="codehilite"><pre><span></span>$ kubectl create -f app.yaml
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ kubectl create -f app.yaml
</pre></div>
</td></tr></table>
<p>This is a standard kubernetes deployment object. It is running a grpc service
listening on port <code class="codehilite">50051</code>.</p>
<p>The sample application
<a href="https://github.com/kubernetes/ingress-nginx/images/grpc-fortune-teller">fortune-teller-app</a>
is a grpc server implemented in go. Here's the stripped-down implementation:</p>
<div class="codehilite"><pre><span></span><span class="kd">func</span> <span class="nx">main</span><span class="p">()</span> <span class="p">{</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="kd">func</span> <span class="nx">main</span><span class="p">()</span> <span class="p">{</span>
<span class="nx">grpcServer</span> <span class="o">:=</span> <span class="nx">grpc</span><span class="p">.</span><span class="nx">NewServer</span><span class="p">()</span>
<span class="nx">fortune</span><span class="p">.</span><span class="nx">RegisterFortuneTellerServer</span><span class="p">(</span><span class="nx">grpcServer</span><span class="p">,</span> <span class="o">&amp;</span><span class="nx">FortuneTeller</span><span class="p">{})</span>
<span class="nx">lis</span><span class="p">,</span> <span class="nx">_</span> <span class="o">:=</span> <span class="nx">net</span><span class="p">.</span><span class="nx">Listen</span><span class="p">(</span><span class="s">&quot;tcp&quot;</span><span class="p">,</span> <span class="s">&quot;:50051&quot;</span><span class="p">)</span>
<span class="nx">grpcServer</span><span class="p">.</span><span class="nx">Serve</span><span class="p">(</span><span class="nx">lis</span><span class="p">)</span>
<span class="p">}</span>
</pre></div>
</td></tr></table>
<p>The takeaway is that we are not doing any TLS configuration on the server (as we
are terminating TLS at the ingress level, grpc traffic will travel unencrypted
@ -1251,14 +1258,16 @@ inside the cluster and arrive "insecure").</p>
forward encrypted traffic to your POD and terminate TLS at the gRPC server
itself, add the ingress annotation <code class="codehilite">nginx.ingress.kubernetes.io/secure-backends:&quot;true&quot;</code>.</p>
<h3 id="step-2-the-kubernetes-service">Step 2: the kubernetes <code class="codehilite">Service</code><a class="headerlink" href="#step-2-the-kubernetes-service" title="Permanent link">&para;</a></h3>
<div class="codehilite"><pre><span></span>$ kubectl create -f svc.yaml
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ kubectl create -f svc.yaml
</pre></div>
</td></tr></table>
<p>Here we have a typical service. Nothing special, just routing traffic to the
backend application on port <code class="codehilite">50051</code>.</p>
<h3 id="step-3-the-kubernetes-ingress">Step 3: the kubernetes <code class="codehilite">Ingress</code><a class="headerlink" href="#step-3-the-kubernetes-ingress" title="Permanent link">&para;</a></h3>
<div class="codehilite"><pre><span></span>$ kubectl create -f ingress.yaml
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ kubectl create -f ingress.yaml
</pre></div>
</td></tr></table>
<p>A few things to note:</p>
<ol>
@ -1275,11 +1284,15 @@ backend application on port <code class="codehilite">50051</code>.</p>
<p>Once we've applied our configuration to kubernetes, it's time to test that we
can actually talk to the backend. To do this, we'll use the
<a href="https://github.com/fullstorydev/grpcurl">grpcurl</a> utility:</p>
<div class="codehilite"><pre><span></span>$ grpcurl fortune-teller.stack.build:443 build.stack.fortune.FortuneTeller/Predict
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ grpcurl fortune-teller.stack.build:443 build.stack.fortune.FortuneTeller/Predict
<span class="o">{</span>
<span class="s2">&quot;message&quot;</span>: <span class="s2">&quot;Let us endeavor so to live that when we come to die even the undertaker will be sorry.\n\t\t-- Mark Twain, \&quot;Pudd&#39;nhead Wilson&#39;s Calendar\&quot;&quot;</span>
<span class="o">}</span>
</pre></div>
</td></tr></table>
<h3 id="debugging-hints">Debugging Hints<a class="headerlink" href="#debugging-hints" title="Permanent link">&para;</a></h3>
<ol>

89
examples/multi-tls/index.html
View file

@ -1085,10 +1085,51 @@
<ol>
<li>Deploy the controller by creating the rc in the parent dir</li>
<li>Create tls secrets for foo.bar.com and bar.baz.com as indicated in the yaml</li>
<li>Create multi-tls.yaml</li>
<li>Create <a href="multi-tls.yaml">multi-tls.yaml</a></li>
</ol>
<p>This should generate a segment like:
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl <span class="nb">exec</span> -it nginx-ingress-controller-6vwd1 -- cat /etc/nginx/nginx.conf <span class="p">|</span> grep <span class="s2">&quot;foo.bar.com&quot;</span> -B <span class="m">7</span> -A <span class="m">35</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl <span class="nb">exec</span> -it nginx-ingress-controller-6vwd1 -- cat /etc/nginx/nginx.conf <span class="p">|</span> grep <span class="s2">&quot;foo.bar.com&quot;</span> -B <span class="m">7</span> -A <span class="m">35</span>
<span class="go"> server {</span>
<span class="go"> listen 80;</span>
<span class="go"> listen 443 ssl http2;</span>
@ -1130,9 +1171,46 @@
<span class="go"> proxy_pass http://default-http-svc-80;</span>
<span class="go"> }</span>
</pre></div></p>
</pre></div>
</td></tr></table></p>
<p>And you should be able to reach your nginx service or http-svc service using a hostname switch:
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get ing
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get ing
<span class="go">NAME RULE BACKEND ADDRESS AGE</span>
<span class="go">foo-tls - 104.154.30.67 13m</span>
<span class="go"> foo.bar.com</span>
@ -1169,7 +1247,8 @@
<span class="gp">$</span> curl <span class="m">104</span>.154.30.67
<span class="go">default backend - 404</span>
</pre></div></p>
</pre></div>
</td></tr></table></p>

93
examples/rewrite/index.html
View file

@ -1245,7 +1245,24 @@ and that you have an ingress controller <a href="../../deploy">running</a> in yo
<h2 id="validation">Validation<a class="headerlink" href="#validation" title="Permanent link">&para;</a></h2>
<h3 id="rewrite-target">Rewrite Target<a class="headerlink" href="#rewrite-target" title="Permanent link">&para;</a></h3>
<p>Create an Ingress rule with a rewrite annotation:</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> <span class="nb">echo</span> <span class="s2">&quot;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> <span class="nb">echo</span> <span class="s2">&quot;</span>
<span class="go">apiVersion: extensions/v1beta1</span>
<span class="go">kind: Ingress</span>
<span class="go">metadata:</span>
@ -1264,9 +1281,48 @@ and that you have an ingress controller <a href="../../deploy">running</a> in yo
<span class="go"> path: /something</span>
<span class="go">&quot; | kubectl create -f -</span>
</pre></div>
</td></tr></table>
<p>Check the rewrite is working</p>
<div class="codehilite"><pre><span></span>$ curl -v http://172.17.4.99/something -H <span class="s1">&#39;Host: rewrite.bar.com&#39;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ curl -v http://172.17.4.99/something -H <span class="s1">&#39;Host: rewrite.bar.com&#39;</span>
* Trying <span class="m">172</span>.17.4.99...
* Connected to <span class="m">172</span>.17.4.99 <span class="o">(</span><span class="m">172</span>.17.4.99<span class="o">)</span> port <span class="m">80</span> <span class="o">(</span><span class="c1">#0)</span>
&gt; GET /something HTTP/1.1
@ -1306,10 +1362,28 @@ BODY:
* Connection <span class="c1">#0 to host 172.17.4.99 left intact</span>
-no body in request-
</pre></div>
</td></tr></table>
<h3 id="app-root">App Root<a class="headerlink" href="#app-root" title="Permanent link">&para;</a></h3>
<p>Create an Ingress rule with a app-root annotation:
<div class="codehilite"><pre><span></span>$ <span class="nb">echo</span> <span class="s2">&quot;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ <span class="nb">echo</span> <span class="s2">&quot;</span>
<span class="s2">apiVersion: extensions/v1beta1</span>
<span class="s2">kind: Ingress</span>
<span class="s2">metadata:</span>
@ -1327,9 +1401,17 @@ BODY:
<span class="s2"> servicePort: 80</span>
<span class="s2"> path: /</span>
<span class="s2">&quot;</span> <span class="p">|</span> kubectl create -f -
</pre></div></p>
</pre></div>
</td></tr></table></p>
<p>Check the rewrite is working</p>
<div class="codehilite"><pre><span></span>$ curl -I -k http://approot.bar.com/
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6
7
8</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ curl -I -k http://approot.bar.com/
HTTP/1.1 <span class="m">302</span> Moved Temporarily
Server: nginx/1.11.10
Date: Mon, <span class="m">13</span> Mar <span class="m">2017</span> <span class="m">14</span>:57:15 GMT
@ -1338,6 +1420,7 @@ Content-Length: <span class="m">162</span>
Location: http://stickyingress.example.com/app1
Connection: keep-alive
</pre></div>
</td></tr></table>

63
examples/static-ip/index.html
View file

@ -1196,25 +1196,48 @@ nodes get static IPs, the IPs are not retained across upgrade.</p>
<p>To acquire a static IP for the nginx ingress controller, simply put it
behind a Service of <code class="codehilite">Type=LoadBalancer</code>.</p>
<p>First, create a loadbalancer Service and wait for it to acquire an IP</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create -f static-ip-svc.yaml
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create -f static-ip-svc.yaml
<span class="go">service &quot;nginx-ingress-lb&quot; created</span>
<span class="gp">$</span> kubectl get svc nginx-ingress-lb
<span class="go">NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE</span>
<span class="go">nginx-ingress-lb 10.0.138.113 104.154.109.191 80:31457/TCP,443:32240/TCP 15m</span>
</pre></div>
</td></tr></table>
<p>then, update the ingress controller so it adopts the static IP of the Service
by passing the <code class="codehilite">--publish-service</code> flag (the example yaml used in the next step
already has it set to "nginx-ingress-lb").</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create -f nginx-ingress-controller.yaml
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create -f nginx-ingress-controller.yaml
<span class="go">deployment &quot;nginx-ingress-controller&quot; created</span>
</pre></div>
</td></tr></table>
<h2 id="assigning-the-ip-to-an-ingress">Assigning the IP to an Ingress<a class="headerlink" href="#assigning-the-ip-to-an-ingress" title="Permanent link">&para;</a></h2>
<p>From here on every Ingress created with the <code class="codehilite">ingress.class</code> annotation set to
<code class="codehilite">nginx</code> will get the IP allocated in the previous step</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create -f nginx-ingress.yaml
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl create -f nginx-ingress.yaml
<span class="go">ingress &quot;nginx-ingress&quot; created</span>
<span class="gp">$</span> kubectl get ing nginx-ingress
@ -1231,10 +1254,19 @@ already has it set to "nginx-ingress-lb").</p>
<span class="go">request_uri=http://104.154.109.191:8080/</span>
<span class="go">...</span>
</pre></div>
</td></tr></table>
<h2 id="retaining-the-ip">Retaining the IP<a class="headerlink" href="#retaining-the-ip" title="Permanent link">&para;</a></h2>
<p>You can test retention by deleting the Ingress</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl delete ing nginx-ingress
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6
7
8
9</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl delete ing nginx-ingress
<span class="go">ingress &quot;nginx-ingress&quot; deleted</span>
<span class="gp">$</span> kubectl create -f nginx-ingress.yaml
@ -1244,6 +1276,7 @@ already has it set to "nginx-ingress-lb").</p>
<span class="go">NAME HOSTS ADDRESS PORTS AGE</span>
<span class="go">nginx-ingress * 104.154.109.191 80, 443 13m</span>
</pre></div>
</td></tr></table>
<blockquote>
<p>Note that unlike the GCE Ingress, the same loadbalancer IP is shared amongst all
@ -1252,14 +1285,29 @@ controllers.</p>
</blockquote>
<h2 id="promote-ephemeral-to-static-ip">Promote ephemeral to static IP<a class="headerlink" href="#promote-ephemeral-to-static-ip" title="Permanent link">&para;</a></h2>
<p>To promote the allocated IP to static, you can update the Service manifest</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl patch svc nginx-ingress-lb -p <span class="s1">&#39;{&quot;spec&quot;: {&quot;loadBalancerIP&quot;: &quot;104.154.109.191&quot;}}&#39;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl patch svc nginx-ingress-lb -p <span class="s1">&#39;{&quot;spec&quot;: {&quot;loadBalancerIP&quot;: &quot;104.154.109.191&quot;}}&#39;</span>
<span class="go">&quot;nginx-ingress-lb&quot; patched</span>
</pre></div>
</td></tr></table>
<p>and promote the IP to static (promotion works differently for cloudproviders,
provided example is for GKE/GCE)
`
<div class="codehilite"><pre><span></span><span class="gp">$</span> gcloud compute addresses create nginx-ingress-lb --addresses <span class="m">104</span>.154.109.191 --region us-central1
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> gcloud compute addresses create nginx-ingress-lb --addresses <span class="m">104</span>.154.109.191 --region us-central1
<span class="go">Created [https://www.googleapis.com/compute/v1/projects/kubernetesdev/regions/us-central1/addresses/nginx-ingress-lb].</span>
<span class="go">---</span>
<span class="go">address: 104.154.109.191</span>
@ -1273,7 +1321,8 @@ provided example is for GKE/GCE)
<span class="go">status: IN_USE</span>
<span class="go">users:</span>
<span class="go">- us-central1/forwardingRules/a09f6913ae80e11e6a8c542010af0000</span>
</pre></div></p>
</pre></div>
</td></tr></table></p>
<p>Now even if the Service is deleted, the IP will persist, so you can recreate the
Service with <code class="codehilite">spec.loadBalancerIP</code> set to <code class="codehilite">104.154.109.191</code>.</p>

1
examples/static-ip/nginx-ingress-controller.yaml
View file

@ -54,5 +54,4 @@ spec:
fieldPath: metadata.namespace
args:
- /nginx-ingress-controller
- --default-backend-service=$(POD_NAMESPACE)/default-http-backend
- --publish-service=$(POD_NAMESPACE)/nginx-ingress-lb

52
examples/tls-termination/index.html
View file

@ -1160,12 +1160,59 @@
<h2 id="deployment">Deployment<a class="headerlink" href="#deployment" title="Permanent link">&para;</a></h2>
<p>The following command instructs the controller to terminate traffic using the provided
TLS cert, and forward un-encrypted HTTP traffic to the test HTTP service.</p>
<div class="codehilite"><pre><span></span><span class="go">kubectl apply -f ingress.yaml</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl apply -f ingress.yaml</span>
</pre></div>
</td></tr></table>
<h2 id="validation">Validation<a class="headerlink" href="#validation" title="Permanent link">&para;</a></h2>
<p>You can confirm that the Ingress works.</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl describe ing nginx-test
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl describe ing nginx-test
<span class="go">Name: nginx-test</span>
<span class="go">Namespace: default</span>
<span class="go">Address: 104.198.183.6</span>
@ -1213,6 +1260,7 @@ TLS cert, and forward un-encrypted HTTP traffic to the test HTTP service.</p>
<span class="go">x-forwarded-proto=https</span>
<span class="go">BODY:</span>
</pre></div>
</td></tr></table>

2
search/search_index.json
View file

File diff suppressed because one or more lines are too long

90
sitemap.xml
View file

@ -2,227 +2,227 @@
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2018-09-20</lastmod>
<lastmod>2018-09-27</lastmod>
<changefreq>daily</changefreq>
</url>
</urlset>

BIN
sitemap.xml.gz
View file

Binary file not shown.

214
troubleshooting/index.html
View file

@ -1220,7 +1220,29 @@ Do not move it without providing redirects.
<p>There are many ways to troubleshoot the ingress-controller. The following are basic troubleshooting
methods to obtain more information.</p>
<p>Check the Ingress Resource Events</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get ing -n &lt;namespace-of-ingress-resource&gt;
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get ing -n &lt;namespace-of-ingress-resource&gt;
<span class="go">NAME HOSTS ADDRESS PORTS AGE</span>
<span class="go">cafe-ingress cafe.com 10.0.2.15 80 25s</span>
@ -1244,9 +1266,21 @@ methods to obtain more information.</p>
<span class="go"> Normal CREATE 1m nginx-ingress-controller Ingress default/cafe-ingress</span>
<span class="go"> Normal UPDATE 58s nginx-ingress-controller Ingress default/cafe-ingress</span>
</pre></div>
</td></tr></table>
<p>Check the Ingress Controller Logs</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get pods -n &lt;namespace-of-ingress-controller&gt;
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get pods -n &lt;namespace-of-ingress-controller&gt;
<span class="go">NAME READY STATUS RESTARTS AGE</span>
<span class="go">nginx-ingress-controller-67956bf89d-fv58j 1/1 Running 0 1m</span>
@ -1259,9 +1293,26 @@ methods to obtain more information.</p>
<span class="go">-------------------------------------------------------------------------------</span>
<span class="go">....</span>
</pre></div>
</td></tr></table>
<p>Check the Nginx Configuration</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get pods -n &lt;namespace-of-ingress-controller&gt;
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get pods -n &lt;namespace-of-ingress-controller&gt;
<span class="go">NAME READY STATUS RESTARTS AGE</span>
<span class="go">nginx-ingress-controller-67956bf89d-fv58j 1/1 Running 0 1m</span>
@ -1279,9 +1330,17 @@ methods to obtain more information.</p>
<span class="go">http {</span>
<span class="go">....</span>
</pre></div>
</td></tr></table>
<p>Check if used Services Exist</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get svc --all-namespaces
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6
7
8</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get svc --all-namespaces
<span class="go">NAMESPACE NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE</span>
<span class="go">default coffee-svc ClusterIP 10.106.154.35 &lt;none&gt; 80/TCP 18m</span>
<span class="go">default kubernetes ClusterIP 10.96.0.1 &lt;none&gt; 443/TCP 30m</span>
@ -1290,11 +1349,18 @@ methods to obtain more information.</p>
<span class="go">kube-system kube-dns ClusterIP 10.96.0.10 &lt;none&gt; 53/UDP,53/TCP 30m</span>
<span class="go">kube-system kubernetes-dashboard NodePort 10.103.128.17 &lt;none&gt; 80:30000/TCP 30m</span>
</pre></div>
</td></tr></table>
<h2 id="debug-logging">Debug Logging<a class="headerlink" href="#debug-logging" title="Permanent link">&para;</a></h2>
<p>Using the flag <code class="codehilite">--v=XX</code> it is possible to increase the level of logging. This is performed by editing
the deployment.</p>
<div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get deploy -n &lt;namespace-of-ingress-controller&gt;
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6
7</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> kubectl get deploy -n &lt;namespace-of-ingress-controller&gt;
<span class="go">NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE</span>
<span class="go">default-http-backend 1 1 1 1 35m</span>
<span class="go">nginx-ingress-controller 1 1 1 1 35m</span>
@ -1302,6 +1368,7 @@ the deployment.</p>
<span class="gp">$</span> kubectl edit deploy -n &lt;namespace-of-ingress-controller&gt; nginx-ingress-controller
<span class="gp">#</span> Add --v<span class="o">=</span>X to <span class="s2">&quot;- args&quot;</span>, where X is an integer
</pre></div>
</td></tr></table>
<ul>
<li><code class="codehilite">--v=2</code> shows details using <code class="codehilite">diff</code> about the changes in the configuration in nginx</li>
@ -1313,12 +1380,17 @@ the deployment.</p>
down the source of the problem, namely whether it is a problem with service authentication or
with the kubeconfig file.</p>
<p>Both authentications must work:</p>
<div class="codehilite"><pre><span></span>+-------------+ service +------------+
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>+-------------+ service +------------+
| | authentication | |
+ apiserver +&lt;-------------------+ ingress |
| | | controller |
+-------------+ +------------+
</pre></div>
</td></tr></table>
<p><strong>Service authentication</strong></p>
<p>The Ingress controller needs information from apiserver. Therefore, authentication is required, which can be achieved in two different ways:</p>
@ -1337,7 +1409,23 @@ with the kubeconfig file.</p>
</ol>
<p>In the diagram below you can see the full authentication flow with all options, starting with the browser
on the lower left hand side.</p>
<div class="codehilite"><pre><span></span>Kubernetes Workstation
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>Kubernetes Workstation
+---------------------------------------------------+ +------------------+
| | | |
| +-----------+ apiserver +------------+ | | +------------+ |
@ -1355,13 +1443,76 @@ on the lower left hand side.</p>
| | | |
+---------------------------------------------------+ +------------------+
</pre></div>
</td></tr></table>
<h3 id="service-account">Service Account<a class="headerlink" href="#service-account" title="Permanent link">&para;</a></h3>
<p>If using a service account to connect to the API server, Dashboard expects the file
<code class="codehilite">/var/run/secrets/kubernetes.io/serviceaccount/token</code> to be present. It provides a secret
token that is required to authenticate with the API server.</p>
<p>Verify with the following commands:</p>
<div class="codehilite"><pre><span></span><span class="gp">#</span> start a container that contains curl
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">#</span> start a container that contains curl
<span class="gp">$</span> kubectl run <span class="nb">test</span> --image<span class="o">=</span>tutum/curl -- sleep <span class="m">10000</span>
<span class="gp">#</span> check that container is running
@ -1425,6 +1576,7 @@ token that is required to authenticate with the API server.</p>
<span class="go"> ]</span>
<span class="go">}</span>
</pre></div>
</td></tr></table>
<p>If it is not working, there are two possible reasons:</p>
<ol>
@ -1458,33 +1610,46 @@ dump. This allows us to see which configuration is being used, as well as older
<ol>
<li>SSH into the worker</li>
</ol>
<div class="codehilite"><pre><span></span><span class="gp">$</span> ssh user@workerIP
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> ssh user@workerIP
</pre></div>
</td></tr></table>
<ol>
<li>Obtain the Docker Container Running nginx</li>
</ol>
<div class="codehilite"><pre><span></span><span class="gp">$</span> docker ps <span class="p">|</span> grep nginx-ingress-controller
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> docker ps <span class="p">|</span> grep nginx-ingress-controller
<span class="go">CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES</span>
<span class="go">d9e1d243156a quay.io/kubernetes-ingress-controller/nginx-ingress-controller &quot;/usr/bin/dumb-init …&quot; 19 minutes ago Up 19 minutes k8s_nginx-ingress-controller_nginx-ingress-controller-67956bf89d-mqxzt_kube-system_079f31ec-aa37-11e8-ad39-080027a227db_0</span>
</pre></div>
</td></tr></table>
<ol>
<li>Exec into the container</li>
</ol>
<div class="codehilite"><pre><span></span><span class="gp">$</span> docker <span class="nb">exec</span> -it --user<span class="o">=</span><span class="m">0</span> --privileged d9e1d243156a bash
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> docker <span class="nb">exec</span> -it --user<span class="o">=</span><span class="m">0</span> --privileged d9e1d243156a bash
</pre></div>
</td></tr></table>
<ol>
<li>Make sure nginx is running in <code class="codehilite">--with-debug</code></li>
</ol>
<div class="codehilite"><pre><span></span><span class="gp">$</span> nginx -V <span class="m">2</span>&gt;<span class="p">&amp;</span><span class="m">1</span> <span class="p">|</span> grep -- <span class="s1">&#39;--with-debug&#39;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> nginx -V <span class="m">2</span>&gt;<span class="p">&amp;</span><span class="m">1</span> <span class="p">|</span> grep -- <span class="s1">&#39;--with-debug&#39;</span>
</pre></div>
</td></tr></table>
<ol>
<li>Get list of processes running on container</li>
</ol>
<div class="codehilite"><pre><span></span><span class="gp">$</span> ps -ef
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6
7
8</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> ps -ef
<span class="go">UID PID PPID C STIME TTY TIME CMD</span>
<span class="go">root 1 0 0 20:23 ? 00:00:00 /usr/bin/dumb-init /nginx-ingres</span>
<span class="go">root 5 1 0 20:23 ? 00:00:05 /nginx-ingress-controller --defa</span>
@ -1493,22 +1658,37 @@ dump. This allows us to see which configuration is being used, as well as older
<span class="go">nobody 107 21 0 20:23 ? 00:00:00 nginx: worker process</span>
<span class="go">root 172 0 0 20:43 pts/0 00:00:00 bash</span>
</pre></div>
</td></tr></table>
<ol>
<li>Attach gdb to the nginx master process</li>
</ol>
<div class="codehilite"><pre><span></span><span class="gp">$</span> gdb -p <span class="m">21</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="gp">$</span> gdb -p <span class="m">21</span>
<span class="go">....</span>
<span class="go">Attaching to process 21</span>
<span class="go">Reading symbols from /usr/sbin/nginx...done.</span>
<span class="go">....</span>
<span class="go">(gdb)</span>
</pre></div>
</td></tr></table>
<ol>
<li>Copy and paste the following:</li>
</ol>
<div class="codehilite"><pre><span></span><span class="go">set $cd = ngx_cycle-&gt;config_dump</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6
7
8
9</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">set $cd = ngx_cycle-&gt;config_dump</span>
<span class="go">set $nelts = $cd.nelts</span>
<span class="go">set $elts = (ngx_conf_dump_t*)($cd.elts)</span>
<span class="go">while ($nelts-- &gt; 0)</span>
@ -1518,6 +1698,7 @@ dump. This allows us to see which configuration is being used, as well as older
<span class="gp"> $</span>elts<span class="o">[</span><span class="nv">$nelts</span><span class="o">]</span>-&gt;buffer.start <span class="nv">$elts</span><span class="o">[</span><span class="nv">$nelts</span><span class="o">]</span>-&gt;buffer.end
<span class="go">end</span>
</pre></div>
</td></tr></table>
<ol>
<li>
@ -1527,8 +1708,9 @@ dump. This allows us to see which configuration is being used, as well as older
<p>Open nginx_conf.txt</p>
</li>
</ol>
<div class="codehilite"><pre><span></span><span class="go">cat nginx_conf.txt</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">cat nginx_conf.txt</span>
</pre></div>
</td></tr></table>

4
user-guide/cli-arguments/index.html
View file

@ -1109,11 +1109,11 @@
</tr>
<tr>
<td><code class="codehilite">--default-backend-service string</code></td>
<td>Service used to serve HTTP requests not matching any known server name (catch-all). Takes the form "namespace/name". The controller configures NGINX to forward requests to the first port of this Service.</td>
<td>Service used to serve HTTP requests not matching any known server name (catch-all). Takes the form "namespace/name". The controller configures NGINX to forward requests to the first port of this Service. If not specified, 404 page will be returned diretly from Nginx.</td>
</tr>
<tr>
<td><code class="codehilite">--default-server-port int</code></td>
<td>Port to use for exposing the default server (catch-all). (default 8181)</td>
<td>When <code class="codehilite">default-backend-service</code> is not specified or specified service does not have any endpoint, a local endpoint with this port will be used to serve 404 page from inside Nginx.</td>
</tr>
<tr>
<td><code class="codehilite">--default-ssl-certificate string</code></td>

46
user-guide/exposing-tcp-udp-services/index.html
View file

@ -1086,7 +1086,13 @@
<p>It is also possible to use a number or the name of the port. The two last fields are optional.
Adding <code class="codehilite">PROXY</code> in either or both of the two last fields we can use Proxy Protocol decoding (listen) and/or encoding (proxy_pass) in a TCP service (https://www.nginx.com/resources/admin-guide/proxy-protocol/).</p>
<p>The next example shows how to expose the service <code class="codehilite">example-go</code> running in the namespace <code class="codehilite">default</code> in the port <code class="codehilite">8080</code> using the port <code class="codehilite">9000</code></p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">apiVersion</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">v1</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6
7</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">apiVersion</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">v1</span>
<span class="l l-Scalar l-Scalar-Plain">kind</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">ConfigMap</span>
<span class="l l-Scalar l-Scalar-Plain">metadata</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">tcp-services</span>
@ -1094,10 +1100,17 @@ Adding <code class="codehilite">PROXY</code> in either or both of the two last f
<span class="l l-Scalar l-Scalar-Plain">data</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">9000</span><span class="p p-Indicator">:</span> <span class="s">&quot;default/example-go:8080&quot;</span>
</pre></div>
</td></tr></table>
<p>Since 1.9.13 NGINX provides <a href="https://www.nginx.com/blog/announcing-udp-load-balancing/">UDP Load Balancing</a>.
The next example shows how to expose the service <code class="codehilite">kube-dns</code> running in the namespace <code class="codehilite">kube-system</code> in the port <code class="codehilite">53</code> using the port <code class="codehilite">53</code></p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">apiVersion</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">v1</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6
7</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">apiVersion</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">v1</span>
<span class="l l-Scalar l-Scalar-Plain">kind</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">ConfigMap</span>
<span class="l l-Scalar l-Scalar-Plain">metadata</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">udp-services</span>
@ -1105,9 +1118,35 @@ The next example shows how to expose the service <code class="codehilite">kube-d
<span class="l l-Scalar l-Scalar-Plain">data</span><span class="p p-Indicator">:</span>
<span class="err">  </span><span class="l l-Scalar l-Scalar-Plain">53</span><span class="p p-Indicator">:</span> <span class="s">&quot;kube-system/kube-dns:53&quot;</span>
</pre></div>
</td></tr></table>
<p>If TCP/UDP proxy support is used, then those ports need to be exposed in the Service defined for the Ingress.</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">apiVersion</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">v1</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">apiVersion</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">v1</span>
<span class="l l-Scalar l-Scalar-Plain">kind</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">Service</span>
<span class="l l-Scalar l-Scalar-Plain">metadata</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">ingress-nginx</span>
@ -1134,6 +1173,7 @@ The next example shows how to expose the service <code class="codehilite">kube-d
<span class="l l-Scalar l-Scalar-Plain">app.kubernetes.io/name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">ingress-nginx</span>
<span class="l l-Scalar l-Scalar-Plain">app.kubernetes.io/part-of</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">ingress-nginx</span>
</pre></div>
</td></tr></table>

39
user-guide/monitoring/index.html
View file

@ -1192,51 +1192,74 @@
<p>The Prometheus server must be configured so that it can discover endpoints of services. If a Prometheus server is already running in the cluster and if it is configured in a way that it can find the ingress controller pods, no extra configuration is needed.</p>
<p>If there is no existing Prometheus server running, the rest of this tutorial will guide you through the steps needed to deploy a properly configured Prometheus server.</p>
<p>Running the following command deploys the prometheus configuration in Kubernetes:</p>
<div class="codehilite"><pre><span></span><span class="go">kubectl create -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/monitoring/configuration.yaml</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl create -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/monitoring/configuration.yaml</span>
<span class="go">configmap &quot;prometheus-configuration&quot; created</span>
</pre></div>
</td></tr></table>
<p>Running the following command deploys prometheus in Kubernetes:</p>
<div class="codehilite"><pre><span></span><span class="go">kubectl create -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/monitoring/prometheus.yaml</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl create -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/monitoring/prometheus.yaml</span>
<span class="go">clusterrole &quot;prometheus-server&quot; created</span>
<span class="go">serviceaccount &quot;prometheus-server&quot; created</span>
<span class="go">clusterrolebinding &quot;prometheus-server&quot; created</span>
<span class="go">deployment &quot;prometheus-server&quot; created</span>
<span class="go">service &quot;prometheus-server&quot; created</span>
</pre></div>
</td></tr></table>
<h3 id="prometheus-dashboard">Prometheus Dashboard<a class="headerlink" href="#prometheus-dashboard" title="Permanent link">&para;</a></h3>
<p>Open Prometheus dashboard in a web browser:</p>
<div class="codehilite"><pre><span></span><span class="go">kubectl get svc -n ingress-nginx</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl get svc -n ingress-nginx</span>
<span class="go">NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE</span>
<span class="go">default-http-backend ClusterIP 10.103.59.201 &lt;none&gt; 80/TCP 3d</span>
<span class="go">ingress-nginx NodePort 10.97.44.72 &lt;none&gt; 80:30100/TCP,443:30154/TCP,10254:32049/TCP 5h</span>
<span class="go">prometheus-server NodePort 10.98.233.86 &lt;none&gt; 9090:32630/TCP 1m</span>
</pre></div>
</td></tr></table>
<p>Obtain the IP address of the nodes in the running cluster:</p>
<div class="codehilite"><pre><span></span><span class="go">kubectl get nodes -o wide</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl get nodes -o wide</span>
</pre></div>
</td></tr></table>
<p>In some cases where the node only have internal IP adresses we need to execute:</p>
<div class="codehilite"><pre><span></span><span class="go">kubectl get nodes --selector=kubernetes.io/role!=master -o jsonpath={.items[*].status.addresses[?\(@.type==\&quot;InternalIP\&quot;\)].address}</span>
<p>In some cases where the node only have internal IP addresses we need to execute:</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl get nodes --selector=kubernetes.io/role!=master -o jsonpath={.items[*].status.addresses[?\(@.type==\&quot;InternalIP\&quot;\)].address}</span>
<span class="go">10.192.0.2 10.192.0.3 10.192.0.4</span>
</pre></div>
</td></tr></table>
<p>Open your browser and visit the following URL: <em>http://{node IP address}:{prometheus-svc-nodeport}</em> to load the Prometheus Dashboard.</p>
<p>According to the above example, this URL will be http://10.192.0.3:32630</p>
<p><img alt="Dashboard" src="../../images/prometheus-dashboard.png" /></p>
<h3 id="grafana">Grafana<a class="headerlink" href="#grafana" title="Permanent link">&para;</a></h3>
<div class="codehilite"><pre><span></span><span class="go">kubectl create -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/monitoring/grafana.yaml</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl create -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/monitoring/grafana.yaml</span>
</pre></div>
</td></tr></table>
<div class="codehilite"><pre><span></span><span class="go">kubectl get svc -n ingress-nginx</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl get svc -n ingress-nginx</span>
<span class="go">NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE</span>
<span class="go">default-http-backend ClusterIP 10.103.59.201 &lt;none&gt; 80/TCP 3d</span>
<span class="go">ingress-nginx NodePort 10.97.44.72 &lt;none&gt; 80:30100/TCP,443:30154/TCP,10254:32049/TCP 5h</span>
<span class="go">prometheus-server NodePort 10.98.233.86 &lt;none&gt; 9090:32630/TCP 10m</span>
<span class="go">grafana NodePort 10.98.233.87 &lt;none&gt; 3000:31086/TCP 10m</span>
</pre></div>
</td></tr></table>
<p>Open your browser and visit the following URL: <em>http://{node IP address}:{grafana-svc-nodeport}</em> to load the Grafana Dashboard.
According to the above example, this URL will be http://10.192.0.3:31086</p>

25
user-guide/multiple-ingress/index.html
View file

@ -1129,18 +1129,26 @@
<p>If you're running multiple ingress controllers, or running on a cloud provider that natively handles ingress such as GKE,
you need to specify the annotation <code class="codehilite">kubernetes.io/ingress.class: &quot;nginx&quot;</code> in all ingresses that you would like the ingress-nginx controller to claim.</p>
<p>For instance,</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">metadata</span><span class="p p-Indicator">:</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">metadata</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">foo</span>
<span class="l l-Scalar l-Scalar-Plain">annotations</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">kubernetes.io/ingress.class</span><span class="p p-Indicator">:</span> <span class="s">&quot;gce&quot;</span>
</pre></div>
</td></tr></table>
<p>will target the GCE controller, forcing the nginx controller to ignore it, while an annotation like</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">metadata</span><span class="p p-Indicator">:</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">metadata</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">foo</span>
<span class="l l-Scalar l-Scalar-Plain">annotations</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">kubernetes.io/ingress.class</span><span class="p p-Indicator">:</span> <span class="s">&quot;nginx&quot;</span>
</pre></div>
</td></tr></table>
<p>will target the nginx controller, forcing the GCE controller to ignore it.</p>
<p>To reiterate, setting the annotation to any value which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress.
@ -1150,18 +1158,27 @@ If you are only running a single NGINX ingress controller, this can be achieved
<p>This mechanism also provides users the ability to run <em>multiple</em> NGINX ingress controllers (e.g. one which serves public traffic, one which serves "internal" traffic).
To do this, the option <code class="codehilite">--ingress-class</code> must be changed to a value unique for the cluster within the definition of the replication controller.
Here is a partial example:</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">spec</span><span class="p p-Indicator">:</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">spec</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">template</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">spec</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">containers</span><span class="p p-Indicator">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">nginx-ingress-internal-controller</span>
<span class="l l-Scalar l-Scalar-Plain">args</span><span class="p p-Indicator">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">/nginx-ingress-controller</span>
<span class="p p-Indicator">-</span> <span class="s">&#39;--default-backend-service=ingress/nginx-ingress-default-backend&#39;</span>
<span class="p p-Indicator">-</span> <span class="s">&#39;--election-id=ingress-controller-leader-internal&#39;</span>
<span class="p p-Indicator">-</span> <span class="s">&#39;--ingress-class=nginx-internal&#39;</span>
<span class="p p-Indicator">-</span> <span class="s">&#39;--configmap=ingress/nginx-ingress-internal-controller&#39;</span>
</pre></div>
</td></tr></table>
<div class="admonition important">
<p class="admonition-title">Important</p>

78
user-guide/nginx-configuration/annotations/index.html
View file

@ -2037,16 +2037,19 @@ So, at reload, if upstream servers have changed, index values are not guaranteed
<h3 id="authentication">Authentication<a class="headerlink" href="#authentication" title="Permanent link">&para;</a></h3>
<p>Is possible to add authentication adding additional annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords inside the key <code class="codehilite">auth</code>.</p>
<p>The annotations are:
<div class="codehilite"><pre><span></span>nginx.ingress.kubernetes.io/auth-type: [basic|digest]
</pre></div></p>
<p>Indicates the <a href="https://tools.ietf.org/html/rfc2617">HTTP Authentication Type: Basic or Digest Access Authentication</a>.</p>
<div class="codehilite"><pre><span></span>nginx.ingress.kubernetes.io/auth-secret: secretName
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>nginx.ingress.kubernetes.io/auth-type: [basic|digest]
</pre></div>
</td></tr></table></p>
<p>Indicates the <a href="https://tools.ietf.org/html/rfc2617">HTTP Authentication Type: Basic or Digest Access Authentication</a>.</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>nginx.ingress.kubernetes.io/auth-secret: secretName
</pre></div>
</td></tr></table>
<p>The name of the Secret that contains the usernames and passwords which are granted access to the <code class="codehilite">path</code>s defined in the Ingress rules.
This annotation also accepts the alternative form "namespace/secretName", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace.</p>
<div class="codehilite"><pre><span></span>nginx.ingress.kubernetes.io/auth-realm: &quot;realm string&quot;
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>nginx.ingress.kubernetes.io/auth-realm: &quot;realm string&quot;
</pre></div>
</td></tr></table>
<div class="admonition example">
<p class="admonition-title">Example</p>
@ -2110,9 +2113,11 @@ Only one of the Ingress rules should define annotations to configure the upstrea
</div>
<h3 id="configuration-snippet">Configuration snippet<a class="headerlink" href="#configuration-snippet" title="Permanent link">&para;</a></h3>
<p>Using this annotation you can add additional configuration to the NGINX location. For example:</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/configuration-snippet</span><span class="p p-Indicator">:</span> <span class="p p-Indicator">|</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/configuration-snippet</span><span class="p p-Indicator">:</span> <span class="p p-Indicator">|</span>
<span class="no">more_set_headers &quot;Request-Id: $req_id&quot;;</span>
</pre></div>
</td></tr></table>
<h3 id="default-backend">Default Backend<a class="headerlink" href="#default-backend" title="Permanent link">&para;</a></h3>
<p>The ingress controller requires a <a href="../../default-backend/">default backend</a>.
@ -2180,7 +2185,20 @@ the new server configuration will take place over the alias configuration.</p>
<p>For more information please see <a href="http://nginx.org/en/docs/http/ngx_http_core_module.html#server_name">the <code class="codehilite">server_name</code> documentation</a>.</p>
<h3 id="server-snippet">Server snippet<a class="headerlink" href="#server-snippet" title="Permanent link">&para;</a></h3>
<p>Using the annotation <code class="codehilite">nginx.ingress.kubernetes.io/server-snippet</code> it is possible to add custom configuration in the server configuration block.</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">apiVersion</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">extensions/v1beta1</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">apiVersion</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">extensions/v1beta1</span>
<span class="l l-Scalar l-Scalar-Plain">kind</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">Ingress</span>
<span class="l l-Scalar l-Scalar-Plain">metadata</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">annotations</span><span class="p p-Indicator">:</span>
@ -2195,6 +2213,7 @@ the new server configuration will take place over the alias configuration.</p>
<span class="l l-Scalar l-Scalar-Plain">return 301 https://m.example.com;</span>
<span class="err">}</span>
</pre></div>
</td></tr></table>
<div class="admonition attention">
<p class="admonition-title">Attention</p>
@ -2222,8 +2241,9 @@ applied to each location provided in the ingress rule.</p>
<p>For more information please see <a href="http://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size">http://nginx.org</a></p>
<h3 id="external-authentication">External Authentication<a class="headerlink" href="#external-authentication" title="Permanent link">&para;</a></h3>
<p>To use an existing service that provides authentication the Ingress rule can be annotated with <code class="codehilite">nginx.ingress.kubernetes.io/auth-url</code> to indicate the URL where the HTTP request should be sent.</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/auth-url</span><span class="p p-Indicator">:</span> <span class="s">&quot;URL</span><span class="nv"> </span><span class="s">to</span><span class="nv"> </span><span class="s">the</span><span class="nv"> </span><span class="s">authentication</span><span class="nv"> </span><span class="s">service&quot;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/auth-url</span><span class="p p-Indicator">:</span> <span class="s">&quot;URL</span><span class="nv"> </span><span class="s">to</span><span class="nv"> </span><span class="s">the</span><span class="nv"> </span><span class="s">authentication</span><span class="nv"> </span><span class="s">service&quot;</span>
</pre></div>
</td></tr></table>
<p>Additionally it is possible to set:</p>
<ul>
@ -2336,8 +2356,9 @@ otherwise, both annotations must be used in unison. Note that each annotation mu
<p>For NGINX, an 413 error will be returned to the client when the size in a request exceeds the maximum allowed size of the client request body. This size can be configured by the parameter <a href="http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size"><code class="codehilite">client_max_body_size</code></a>.</p>
<p>To configure this setting globally for all Ingress rules, the <code class="codehilite">proxy-body-size</code> value may be set in the <a href="../configmap/">NGINX ConfigMap</a>.
To use custom values in an Ingress rule define these annotation:</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/proxy-body-size</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">8m</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/proxy-body-size</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">8m</span>
</pre></div>
</td></tr></table>
<h3 id="proxy-cookie-domain">Proxy cookie domain<a class="headerlink" href="#proxy-cookie-domain" title="Permanent link">&para;</a></h3>
<p>Sets a text that <a href="http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cookie_domain">should be changed in the domain attribute</a> of the "Set-Cookie" header fields of a proxied server response.</p>
@ -2347,58 +2368,67 @@ To use custom values in an Ingress rule define these annotation:</p>
By default proxy buffering is disabled in the NGINX config.</p>
<p>To configure this setting globally for all Ingress rules, the <code class="codehilite">proxy-buffering</code> value may be set in the <a href="../configmap/">NGINX ConfigMap</a>.
To use custom values in an Ingress rule define these annotation:</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/proxy-buffering</span><span class="p p-Indicator">:</span> <span class="s">&quot;on&quot;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/proxy-buffering</span><span class="p p-Indicator">:</span> <span class="s">&quot;on&quot;</span>
</pre></div>
</td></tr></table>
<h3 id="proxy-buffer-size">Proxy buffer size<a class="headerlink" href="#proxy-buffer-size" title="Permanent link">&para;</a></h3>
<p>Sets the size of the buffer <a href="http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size"><code class="codehilite">proxy_buffer_size</code></a> used for reading the first part of the response received from the proxied server.
By default proxy buffer size is set as "4k"</p>
<p>To configure this setting globally, set <code class="codehilite">proxy-buffer-size</code> in <a href="../configmap/">NGINX ConfigMap</a>. To use custom values in an Ingress rule, define this annotation:
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/proxy-buffer-size</span><span class="p p-Indicator">:</span> <span class="s">&quot;8k&quot;</span>
</pre></div></p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/proxy-buffer-size</span><span class="p p-Indicator">:</span> <span class="s">&quot;8k&quot;</span>
</pre></div>
</td></tr></table></p>
<h3 id="ssl-ciphers">SSL ciphers<a class="headerlink" href="#ssl-ciphers" title="Permanent link">&para;</a></h3>
<p>Specifies the <a href="http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers">enabled ciphers</a>.</p>
<p>Using this annotation will set the <code class="codehilite">ssl_ciphers</code> directive at the server level. This configuration is active for all the paths in the host.</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/ssl-ciphers</span><span class="p p-Indicator">:</span> <span class="s">&quot;ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP&quot;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/ssl-ciphers</span><span class="p p-Indicator">:</span> <span class="s">&quot;ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP&quot;</span>
</pre></div>
</td></tr></table>
<h3 id="connection-proxy-header">Connection proxy header<a class="headerlink" href="#connection-proxy-header" title="Permanent link">&para;</a></h3>
<p>Using this annotation will override the default connection header set by NGINX.
To use custom values in an Ingress rule, define the annotation:</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/connection-proxy-header</span><span class="p p-Indicator">:</span> <span class="s">&quot;keep-alive&quot;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/connection-proxy-header</span><span class="p p-Indicator">:</span> <span class="s">&quot;keep-alive&quot;</span>
</pre></div>
</td></tr></table>
<h3 id="enable-access-log">Enable Access Log<a class="headerlink" href="#enable-access-log" title="Permanent link">&para;</a></h3>
<p>Access logs are enabled by default, but in some scenarios access logs might be required to be disabled for a given
ingress. To do this, use the annotation:</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/enable-access-log</span><span class="p p-Indicator">:</span> <span class="s">&quot;false&quot;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/enable-access-log</span><span class="p p-Indicator">:</span> <span class="s">&quot;false&quot;</span>
</pre></div>
</td></tr></table>
<h3 id="enable-rewrite-log">Enable Rewrite Log<a class="headerlink" href="#enable-rewrite-log" title="Permanent link">&para;</a></h3>
<p>Rewrite logs are not enabled by default. In some scenarios it could be required to enable NGINX rewrite logs.
Note that rewrite logs are sent to the error_log file at the notice level. To enable this feature use the annotation:</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/enable-rewrite-log</span><span class="p p-Indicator">:</span> <span class="s">&quot;true&quot;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/enable-rewrite-log</span><span class="p p-Indicator">:</span> <span class="s">&quot;true&quot;</span>
</pre></div>
</td></tr></table>
<h3 id="lua-resty-waf">Lua Resty WAF<a class="headerlink" href="#lua-resty-waf" title="Permanent link">&para;</a></h3>
<p>Using <code class="codehilite">lua-resty-waf-*</code> annotations we can enable and control the <a href="https://github.com/p0pr0ck5/lua-resty-waf">lua-resty-waf</a>
Web Application Firewall per location.</p>
<p>Following configuration will enable the WAF for the paths defined in the corresponding ingress:</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/lua-resty-waf</span><span class="p p-Indicator">:</span> <span class="s">&quot;active&quot;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/lua-resty-waf</span><span class="p p-Indicator">:</span> <span class="s">&quot;active&quot;</span>
</pre></div>
</td></tr></table>
<p>In order to run it in debugging mode you can set <code class="codehilite">nginx.ingress.kubernetes.io/lua-resty-waf-debug</code> to <code class="codehilite">&quot;true&quot;</code> in addition to the above configuration.
The other possible values for <code class="codehilite">nginx.ingress.kubernetes.io/lua-resty-waf</code> are <code class="codehilite">inactive</code> and <code class="codehilite">simulate</code>.
In <code class="codehilite">inactive</code> mode WAF won't do anything, whereas in <code class="codehilite">simulate</code> mode it will log a warning message if there's a matching WAF rule for given request. This is useful to debug a rule and eliminate possible false positives before fully deploying it.</p>
<p><code class="codehilite">lua-resty-waf</code> comes with predefined set of rules <a href="https://github.com/p0pr0ck5/lua-resty-waf/tree/84b4f40362500dd0cb98b9e71b5875cb1a40f1ad/rules">https://github.com/p0pr0ck5/lua-resty-waf/tree/84b4f40362500dd0cb98b9e71b5875cb1a40f1ad/rules</a> that covers ModSecurity CRS.
You can use <code class="codehilite">nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets</code> to ignore a subset of those rulesets. For an example:</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets</span><span class="p p-Indicator">:</span> <span class="s">&quot;41000_sqli,</span><span class="nv"> </span><span class="s">42000_xss&quot;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets</span><span class="p p-Indicator">:</span> <span class="s">&quot;41000_sqli,</span><span class="nv"> </span><span class="s">42000_xss&quot;</span>
</pre></div>
</td></tr></table>
<p>will ignore the two mentioned rulesets.</p>
<p>It is also possible to configure custom WAF rules per ingress using the <code class="codehilite">nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules</code> annotation. For an example the following snippet will configure a WAF rule to deny requests with query string value that contains word <code class="codehilite">foo</code>:</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules</span><span class="p p-Indicator">:</span> <span class="s">&#39;[=[</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">&quot;access&quot;:</span><span class="nv"> </span><span class="s">[</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">&quot;actions&quot;:</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">&quot;disrupt&quot;</span><span class="nv"> </span><span class="s">:</span><span class="nv"> </span><span class="s">&quot;DENY&quot;</span><span class="nv"> </span><span class="s">},</span><span class="nv"> </span><span class="s">&quot;id&quot;:</span><span class="nv"> </span><span class="s">10001,</span><span class="nv"> </span><span class="s">&quot;msg&quot;:</span><span class="nv"> </span><span class="s">&quot;my</span><span class="nv"> </span><span class="s">custom</span><span class="nv"> </span><span class="s">rule&quot;,</span><span class="nv"> </span><span class="s">&quot;operator&quot;:</span><span class="nv"> </span><span class="s">&quot;STR_CONTAINS&quot;,</span><span class="nv"> </span><span class="s">&quot;pattern&quot;:</span><span class="nv"> </span><span class="s">&quot;foo&quot;,</span><span class="nv"> </span><span class="s">&quot;vars&quot;:</span><span class="nv"> </span><span class="s">[</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">&quot;parse&quot;:</span><span class="nv"> </span><span class="s">[</span><span class="nv"> </span><span class="s">&quot;values&quot;,</span><span class="nv"> </span><span class="s">1</span><span class="nv"> </span><span class="s">],</span><span class="nv"> </span><span class="s">&quot;type&quot;:</span><span class="nv"> </span><span class="s">&quot;REQUEST_ARGS&quot;</span><span class="nv"> </span><span class="s">}</span><span class="nv"> </span><span class="s">]</span><span class="nv"> </span><span class="s">}</span><span class="nv"> </span><span class="s">],</span><span class="nv"> </span><span class="s">&quot;body_filter&quot;:</span><span class="nv"> </span><span class="s">[],</span><span class="nv"> </span><span class="s">&quot;header_filter&quot;:[]</span><span class="nv"> </span><span class="s">}</span><span class="nv"> </span><span class="s">]=]&#39;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules</span><span class="p p-Indicator">:</span> <span class="s">&#39;[=[</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">&quot;access&quot;:</span><span class="nv"> </span><span class="s">[</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">&quot;actions&quot;:</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">&quot;disrupt&quot;</span><span class="nv"> </span><span class="s">:</span><span class="nv"> </span><span class="s">&quot;DENY&quot;</span><span class="nv"> </span><span class="s">},</span><span class="nv"> </span><span class="s">&quot;id&quot;:</span><span class="nv"> </span><span class="s">10001,</span><span class="nv"> </span><span class="s">&quot;msg&quot;:</span><span class="nv"> </span><span class="s">&quot;my</span><span class="nv"> </span><span class="s">custom</span><span class="nv"> </span><span class="s">rule&quot;,</span><span class="nv"> </span><span class="s">&quot;operator&quot;:</span><span class="nv"> </span><span class="s">&quot;STR_CONTAINS&quot;,</span><span class="nv"> </span><span class="s">&quot;pattern&quot;:</span><span class="nv"> </span><span class="s">&quot;foo&quot;,</span><span class="nv"> </span><span class="s">&quot;vars&quot;:</span><span class="nv"> </span><span class="s">[</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">&quot;parse&quot;:</span><span class="nv"> </span><span class="s">[</span><span class="nv"> </span><span class="s">&quot;values&quot;,</span><span class="nv"> </span><span class="s">1</span><span class="nv"> </span><span class="s">],</span><span class="nv"> </span><span class="s">&quot;type&quot;:</span><span class="nv"> </span><span class="s">&quot;REQUEST_ARGS&quot;</span><span class="nv"> </span><span class="s">}</span><span class="nv"> </span><span class="s">]</span><span class="nv"> </span><span class="s">}</span><span class="nv"> </span><span class="s">],</span><span class="nv"> </span><span class="s">&quot;body_filter&quot;:</span><span class="nv"> </span><span class="s">[],</span><span class="nv"> </span><span class="s">&quot;header_filter&quot;:[]</span><span class="nv"> </span><span class="s">}</span><span class="nv"> </span><span class="s">]=]&#39;</span>
</pre></div>
</td></tr></table>
<p>For details on how to write WAF rules, please refer to <a href="https://github.com/p0pr0ck5/lua-resty-waf">https://github.com/p0pr0ck5/lua-resty-waf</a>.</p>
<h3 id="grpc-backend-deprecated-since-0180">gRPC backend DEPRECATED (since 0.18.0)<a class="headerlink" href="#grpc-backend-deprecated-since-0180" title="Permanent link">&para;</a></h3>
@ -2414,12 +2444,17 @@ Exposing a gRPC service using HTTP is not supported.</p>
<h3 id="influxdb">InfluxDB<a class="headerlink" href="#influxdb" title="Permanent link">&para;</a></h3>
<p>Using <code class="codehilite">influxdb-*</code> annotations we can monitor requests passing through a Location by sending them to an InfluxDB backend exposing the UDP socket
using the <a href="https://github.com/influxdata/nginx-influxdb-module/">nginx-influxdb-module</a>.</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/enable-influxdb</span><span class="p p-Indicator">:</span> <span class="s">&quot;true&quot;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/enable-influxdb</span><span class="p p-Indicator">:</span> <span class="s">&quot;true&quot;</span>
<span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/influxdb-measurement</span><span class="p p-Indicator">:</span> <span class="s">&quot;nginx-reqs&quot;</span>
<span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/influxdb-port</span><span class="p p-Indicator">:</span> <span class="s">&quot;8089&quot;</span>
<span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/influxdb-host</span><span class="p p-Indicator">:</span> <span class="s">&quot;127.0.0.1&quot;</span>
<span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/influxdb-server-name</span><span class="p p-Indicator">:</span> <span class="s">&quot;nginx-ingress&quot;</span>
</pre></div>
</td></tr></table>
<p>For the <code class="codehilite">influxdb-host</code> parameter you have two options:</p>
<ul>
@ -2435,8 +2470,9 @@ an ip address to <code class="codehilite">nginx.ingress.kubernetes.io/influxdb-h
Valid Values: HTTP, HTTPS, GRPC, GRPCS and AJP</p>
<p>By default NGINX uses <code class="codehilite">HTTP</code>.</p>
<p>Example:</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/backend-protocol</span><span class="p p-Indicator">:</span> <span class="s">&quot;HTTPS&quot;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/backend-protocol</span><span class="p p-Indicator">:</span> <span class="s">&quot;HTTPS&quot;</span>
</pre></div>
</td></tr></table>

76
user-guide/nginx-configuration/configmap/index.html
View file

@ -1361,6 +1361,27 @@
</li>
<li class="md-nav__item">
<a href="#block-cidrs" title="block-cidrs" class="md-nav__link">
block-cidrs
</a>
</li>
<li class="md-nav__item">
<a href="#block-user-agents" title="block-user-agents" class="md-nav__link">
block-user-agents
</a>
</li>
<li class="md-nav__item">
<a href="#block-referers" title="block-referers" class="md-nav__link">
block-referers
</a>
</li>
@ -2718,6 +2739,27 @@
</li>
<li class="md-nav__item">
<a href="#block-cidrs" title="block-cidrs" class="md-nav__link">
block-cidrs
</a>
</li>
<li class="md-nav__item">
<a href="#block-user-agents" title="block-user-agents" class="md-nav__link">
block-user-agents
</a>
</li>
<li class="md-nav__item">
<a href="#block-referers" title="block-referers" class="md-nav__link">
block-referers
</a>
</li>
@ -2743,10 +2785,13 @@
components for the nginx-controller.</p>
<p>In order to overwrite nginx-controller configuration values as seen in <a href="https://github.com/kubernetes/ingress-nginx/blob/master/internal/ingress/controller/config/config.go">config.go</a>,
you can add key-value pairs to the data section of the config-map. For Example:</p>
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">data</span><span class="p p-Indicator">:</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">data</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">map-hash-bucket-size</span><span class="p p-Indicator">:</span> <span class="s">&quot;128&quot;</span>
<span class="l l-Scalar l-Scalar-Plain">ssl-protocols</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">SSLv2</span>
</pre></div>
</td></tr></table>
<div class="admonition important">
<p class="admonition-title">Important</p>
@ -3351,6 +3396,21 @@ Same for numbers, like "100".</p>
<td align="left">string</td>
<td align="left">"/.well-known/acme-challenge"</td>
</tr>
<tr>
<td align="left"><a href="#block-cidrs">block-cidrs</a></td>
<td align="left">[]string</td>
<td align="left">""</td>
</tr>
<tr>
<td align="left"><a href="#block-user-agents">block-user-agents</a></td>
<td align="left">[]string</td>
<td align="left">""</td>
</tr>
<tr>
<td align="left"><a href="#block-referers">block-referers</a></td>
<td align="left">[]string</td>
<td align="left">""</td>
</tr>
</tbody>
</table>
<h2 id="add-headers">add-headers<a class="headerlink" href="#add-headers" title="Permanent link">&para;</a></h2>
@ -3723,6 +3783,20 @@ Supported codes are <a href="https://developer.mozilla.org/docs/Web/HTTP/Status/
<h2 id="no-auth-locations">no-auth-locations<a class="headerlink" href="#no-auth-locations" title="Permanent link">&para;</a></h2>
<p>A comma-separated list of locations that should not get authenticated.
<em><strong>default:</strong></em> "/.well-known/acme-challenge"</p>
<h2 id="block-cidrs">block-cidrs<a class="headerlink" href="#block-cidrs" title="Permanent link">&para;</a></h2>
<p>A comma-separated list of IP addresses (or subnets), requestst from which have to be blocked globally.</p>
<p><em>References:</em>
<a href="http://nginx.org/en/docs/http/ngx_http_access_module.html#deny">http://nginx.org/en/docs/http/ngx_http_access_module.html#deny</a></p>
<h2 id="block-user-agents">block-user-agents<a class="headerlink" href="#block-user-agents" title="Permanent link">&para;</a></h2>
<p>A comma-separated list of User-Agent, requestst from which have to be blocked globally.
It's possible to use here full strings and regular expressions. More details about valid patterns can be found at <code class="codehilite">map</code> Nginx directive documentation.</p>
<p><em>References:</em>
<a href="http://nginx.org/en/docs/http/ngx_http_map_module.html#map">http://nginx.org/en/docs/http/ngx_http_map_module.html#map</a></p>
<h2 id="block-referers">block-referers<a class="headerlink" href="#block-referers" title="Permanent link">&para;</a></h2>
<p>A comma-separated list of Referers, requestst from which have to be blocked globally.
It's possible to use here full strings and regular expressions. More details about valid patterns can be found at <code class="codehilite">map</code> Nginx directive documentation.</p>
<p><em>References:</em>
<a href="http://nginx.org/en/docs/http/ngx_http_map_module.html#map">http://nginx.org/en/docs/http/ngx_http_map_module.html#map</a></p>

13
user-guide/nginx-configuration/custom-template/index.html
View file

@ -1086,7 +1086,17 @@
<p>The NGINX template is located in the file <code class="codehilite">/etc/nginx/template/nginx.tmpl</code>.</p>
<p>Using a <a href="https://kubernetes.io/docs/concepts/storage/volumes/">Volume</a> it is possible to use a custom template.
This includes using a <a href="https://kubernetes.io/docs/concepts/storage/volumes/#example-pod-with-a-secret-a-downward-api-and-a-configmap">Configmap</a> as source of the template</p>
<div class="codehilite"><pre><span></span> <span class="l l-Scalar l-Scalar-Plain">volumeMounts</span><span class="p p-Indicator">:</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11</pre></div></td><td class="code"><div class="codehilite"><pre><span></span> <span class="l l-Scalar l-Scalar-Plain">volumeMounts</span><span class="p p-Indicator">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">mountPath</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">/etc/nginx/template</span>
<span class="l l-Scalar l-Scalar-Plain">name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">nginx-template-volume</span>
<span class="l l-Scalar l-Scalar-Plain">readOnly</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">true</span>
@ -1098,6 +1108,7 @@ This includes using a <a href="https://kubernetes.io/docs/concepts/storage/volum
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">key</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">nginx.tmpl</span>
<span class="l l-Scalar l-Scalar-Plain">path</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">nginx.tmpl</span>
</pre></div>
</td></tr></table>
<p><strong>Please note the template is tied to the Go code. Do not change names in the variable <code class="codehilite">$cfg</code>.</strong></p>
<p>For more information about the template syntax please check the <a href="https://golang.org/pkg/text/template/">Go template package</a>.

8
user-guide/nginx-configuration/log-format/index.html
View file

@ -1084,13 +1084,19 @@
<h1 id="log-format">Log format<a class="headerlink" href="#log-format" title="Permanent link">&para;</a></h1>
<p>The default configuration uses a custom logging format to add additional information about upstreams, response time and status.</p>
<div class="codehilite"><pre><span></span><span class="x">log_format upstreaminfo</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="x">log_format upstreaminfo</span>
<span class="x"> &#39;</span><span class="cp">{{</span> <span class="k">if</span> <span class="err">$</span><span class="nv">cfg.useProxyProtocol</span> <span class="cp">}}</span><span class="x">$proxy_protocol_addr</span><span class="cp">{{</span> <span class="k">else</span> <span class="cp">}}</span><span class="x">$remote_addr</span><span class="cp">{{</span> <span class="nv">end</span> <span class="cp">}}</span><span class="x"> - &#39;</span>
<span class="x"> &#39;[$the_real_ip] - $remote_user [$time_local] &quot;$request&quot; &#39;</span>
<span class="x"> &#39;$status $body_bytes_sent &quot;$http_referer&quot; &quot;$http_user_agent&quot; &#39;</span>
<span class="x"> &#39;$request_length $request_time [$proxy_upstream_name] $upstream_addr &#39;</span>
<span class="x"> &#39;$upstream_response_length $upstream_response_time $upstream_status&#39;;</span>
</pre></div>
</td></tr></table>
<table>
<thead>

147
user-guide/third-party-addons/opentracing/index.html
View file

@ -1187,18 +1187,42 @@
By default this feature is disabled.</p>
<h2 id="usage">Usage<a class="headerlink" href="#usage" title="Permanent link">&para;</a></h2>
<p>To enable the instrumentation we must enable opentracing in the configuration configmap:
<div class="codehilite"><pre><span></span><span class="n">data</span><span class="o">:</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="n">data</span><span class="o">:</span>
<span class="n">enable</span><span class="o">-</span><span class="n">opentracing</span><span class="o">:</span> <span class="s2">&quot;true&quot;</span>
</pre></div></p>
</pre></div>
</td></tr></table></p>
<p>We must also set the host to use when uploading traces:</p>
<div class="codehilite"><pre><span></span>zipkin-collector-host: zipkin.default.svc.cluster.local
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>zipkin-collector-host: zipkin.default.svc.cluster.local
jaeger-collector-host: jaeger-collector.default.svc.cluster.local
</pre></div>
</td></tr></table>
<p>Next you will need to deploy a distributed tracing system which uses OpenTracing. Both <a href="https://github.com/openzipkin/zipkin">Zipkin</a> and
<a href="https://github.com/jaegertracing/jaeger">Jaeger</a> have been tested.</p>
<p>Other optional configuration options:
<div class="codehilite"><pre><span></span># specifies the port to use when uploading traces
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21</pre></div></td><td class="code"><div class="codehilite"><pre><span></span># specifies the port to use when uploading traces
zipkin-collector-port
# specifies the service name to use for any traces created, Default: nginx
@ -1219,19 +1243,31 @@ jaeger-sampler-type
# specifies the argument to be passed to the sampler constructor, Default: 1
jaeger-sampler-param
</pre></div></p>
</pre></div>
</td></tr></table></p>
<h2 id="examples">Examples<a class="headerlink" href="#examples" title="Permanent link">&para;</a></h2>
<p>The following examples show how to deploy and test different distributed tracing systems. These example can be performed
using Minikube.</p>
<h3 id="zipkin">Zipkin<a class="headerlink" href="#zipkin" title="Permanent link">&para;</a></h3>
<p>In the <a href="https://github.com/rnburn/zipkin-date-server">rnburn/zipkin-date-server</a>
github repository is an example of a dockerized date service. To install the example and zipkin collector run:</p>
<div class="codehilite"><pre><span></span>kubectl create -f https://raw.githubusercontent.com/rnburn/zipkin-date-server/master/kubernetes/zipkin.yaml
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>kubectl create -f https://raw.githubusercontent.com/rnburn/zipkin-date-server/master/kubernetes/zipkin.yaml
kubectl create -f https://raw.githubusercontent.com/rnburn/zipkin-date-server/master/kubernetes/deployment.yaml
</pre></div>
</td></tr></table>
<p>Also we need to configure the NGINX controller configmap with the required values:</p>
<div class="codehilite"><pre><span></span>$ <span class="nb">echo</span> <span class="s1">&#39;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ <span class="nb">echo</span> <span class="s1">&#39;</span>
<span class="s1">apiVersion: v1</span>
<span class="s1">kind: ConfigMap</span>
<span class="s1">data:</span>
@ -1242,6 +1278,7 @@ kubectl create -f https://raw.githubusercontent.com/rnburn/zipkin-date-server/ma
<span class="s1"> namespace: kube-system</span>
<span class="s1">&#39;</span> <span class="p">|</span> kubectl replace -f -
</pre></div>
</td></tr></table>
<p>In the zipkin interface we can see the details:
<img alt="zipkin screenshot" src="../../../images/zipkin-demo.png" title="zipkin collector screenshot" /></p>
@ -1249,17 +1286,40 @@ kubectl create -f https://raw.githubusercontent.com/rnburn/zipkin-date-server/ma
<ol>
<li>
<p>Enable Ingress addon in minikube:
<div class="codehilite"><pre><span></span>$ minikube addons <span class="nb">enable</span> ingress
</pre></div></p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ minikube addons <span class="nb">enable</span> ingress
</pre></div>
</td></tr></table></p>
</li>
<li>
<p>Add minikube IP to /etc/hosts:
<div class="codehilite"><pre><span></span>$ <span class="nb">echo</span> <span class="s2">&quot;</span><span class="k">$(</span>minikube ip<span class="k">)</span><span class="s2"> example.com&quot;</span> <span class="p">|</span> sudo tee -a /etc/hosts
</pre></div></p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ <span class="nb">echo</span> <span class="s2">&quot;</span><span class="k">$(</span>minikube ip<span class="k">)</span><span class="s2"> example.com&quot;</span> <span class="p">|</span> sudo tee -a /etc/hosts
</pre></div>
</td></tr></table></p>
</li>
<li>
<p>Apply a Basic Service and Ingress Resource:
<div class="codehilite"><pre><span></span># Create Echoheaders Deployment
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22</pre></div></td><td class="code"><div class="codehilite"><pre><span></span># Create Echoheaders Deployment
$ kubectl run echoheaders --image=k8s.gcr.io/echoserver:1.4 --replicas=1 --port=8080
# Expose as a Cluster-IP
@ -1281,11 +1341,22 @@ $ echo &#39;
servicePort: 80
path: /echo
&#39; | kubectl apply -f -
</pre></div></p>
</pre></div>
</td></tr></table></p>
</li>
<li>
<p>Enable OpenTracing and set the zipkin-collector-host:
<div class="codehilite"><pre><span></span>$ <span class="nb">echo</span> <span class="s1">&#39;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ <span class="nb">echo</span> <span class="s1">&#39;</span>
<span class="s1"> apiVersion: v1</span>
<span class="s1"> kind: ConfigMap</span>
<span class="s1"> data:</span>
@ -1296,16 +1367,46 @@ $ echo &#39;
<span class="s1"> name: nginx-load-balancer-conf</span>
<span class="s1"> namespace: kube-system</span>
<span class="s1"> &#39;</span> <span class="p">|</span> kubectl replace -f -
</pre></div></p>
</pre></div>
</td></tr></table></p>
</li>
<li>
<p>Apply the Jaeger All-In-One Template:
<div class="codehilite"><pre><span></span>$ kubectl apply -f https://raw.githubusercontent.com/jaegertracing/jaeger-kubernetes/master/all-in-one/jaeger-all-in-one-template.yml
</pre></div></p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ kubectl apply -f https://raw.githubusercontent.com/jaegertracing/jaeger-kubernetes/master/all-in-one/jaeger-all-in-one-template.yml
</pre></div>
</td></tr></table></p>
</li>
<li>
<p>Make a few requests to the Service:
<div class="codehilite"><pre><span></span>$ curl example.com/echo -d <span class="s2">&quot;meow&quot;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ curl example.com/echo -d <span class="s2">&quot;meow&quot;</span>
CLIENT VALUES:
<span class="nv">client_address</span><span class="o">=</span><span class="m">172</span>.17.0.5
@ -1334,14 +1435,18 @@ x-real-ip<span class="o">=</span><span class="m">192</span>.168.99.1
x-scheme<span class="o">=</span>http
BODY:
meow
</pre></div></p>
</pre></div>
</td></tr></table></p>
</li>
<li>
<p>View the Jaeger UI:
<div class="codehilite"><pre><span></span>$ minikube service jaeger-query --url
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ minikube service jaeger-query --url
http://192.168.99.100:30183
</pre></div></p>
</pre></div>
</td></tr></table></p>
<p>In the jaeger interface we can see the details:
<img alt="jaeger screenshot" src="../../../images/jaeger-demo.png" title="jaeger collector screenshot" /></p>
</li>

18
user-guide/tls/index.html
View file

@ -1239,12 +1239,14 @@
<h2 id="tls-secrets">TLS Secrets<a class="headerlink" href="#tls-secrets" title="Permanent link">&para;</a></h2>
<p>Anytime we reference a TLS secret, we mean a PEM-encoded X.509, RSA (2048) secret.</p>
<p>You can generate a self-signed certificate and private key with with:</p>
<div class="codehilite"><pre><span></span>$ openssl req -x509 -nodes -days <span class="m">365</span> -newkey rsa:2048 -keyout <span class="si">${</span><span class="nv">KEY_FILE</span><span class="si">}</span> -out <span class="si">${</span><span class="nv">CERT_FILE</span><span class="si">}</span> -subj <span class="s2">&quot;/CN=</span><span class="si">${</span><span class="nv">HOST</span><span class="si">}</span><span class="s2">/O=</span><span class="si">${</span><span class="nv">HOST</span><span class="si">}</span><span class="s2">&quot;</span><span class="sb">`</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>$ openssl req -x509 -nodes -days <span class="m">365</span> -newkey rsa:2048 -keyout <span class="si">${</span><span class="nv">KEY_FILE</span><span class="si">}</span> -out <span class="si">${</span><span class="nv">CERT_FILE</span><span class="si">}</span> -subj <span class="s2">&quot;/CN=</span><span class="si">${</span><span class="nv">HOST</span><span class="si">}</span><span class="s2">/O=</span><span class="si">${</span><span class="nv">HOST</span><span class="si">}</span><span class="s2">&quot;</span><span class="sb">`</span>
</pre></div>
</td></tr></table>
<p>Then create the secret in the cluster via:</p>
<div class="codehilite"><pre><span></span>kubectl create secret tls <span class="si">${</span><span class="nv">CERT_NAME</span><span class="si">}</span> --key <span class="si">${</span><span class="nv">KEY_FILE</span><span class="si">}</span> --cert <span class="si">${</span><span class="nv">CERT_FILE</span><span class="si">}</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span>kubectl create secret tls <span class="si">${</span><span class="nv">CERT_NAME</span><span class="si">}</span> --key <span class="si">${</span><span class="nv">KEY_FILE</span><span class="si">}</span> --cert <span class="si">${</span><span class="nv">CERT_FILE</span><span class="si">}</span>
</pre></div>
</td></tr></table>
<p>The resulting secret will be of type <code class="codehilite">kubernetes.io/tls</code>.</p>
<h2 id="default-ssl-certificate">Default SSL Certificate<a class="headerlink" href="#default-ssl-certificate" title="Permanent link">&para;</a></h2>
@ -1306,8 +1308,9 @@ replaced by <a href="https://github.com/jetstack/cert-manager/">cert-manager</a>
<p><a href="https://github.com/jetstack/kube-lego">Kube-Lego</a> automatically requests missing or expired certificates from <a href="https://letsencrypt.org">Let's Encrypt</a>
by monitoring ingress resources and their referenced secrets.</p>
<p>To enable this for an ingress resource you have to add an annotation:</p>
<div class="codehilite"><pre><span></span><span class="go">kubectl annotate ing ingress-demo kubernetes.io/tls-acme=&quot;true&quot;</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="go">kubectl annotate ing ingress-demo kubernetes.io/tls-acme=&quot;true&quot;</span>
</pre></div>
</td></tr></table>
<p>To setup Kube-Lego you can take a look at this <a href="https://github.com/jetstack/kube-lego/tree/master/examples">full example</a>.
The first version to fully support Kube-Lego is Nginx Ingress controller 0.8.</p>
@ -1321,7 +1324,13 @@ May 2018, <a href="https://developer.android.com/about/dashboards/#Platform">app
are not compatible with nginx-ingress's default configuration.</p>
<p>To change this default behavior, use a <a href="../nginx-configuration/configmap/">ConfigMap</a>.</p>
<p>A sample ConfigMap fragment to allow these older clients to connect could look something like the following:</p>
<div class="codehilite"><pre><span></span><span class="n">kind</span><span class="o">:</span> <span class="n">ConfigMap</span>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span>1
2
3
4
5
6
7</pre></div></td><td class="code"><div class="codehilite"><pre><span></span><span class="n">kind</span><span class="o">:</span> <span class="n">ConfigMap</span>
<span class="n">apiVersion</span><span class="o">:</span> <span class="n">v1</span>
<span class="n">metadata</span><span class="o">:</span>
<span class="n">name</span><span class="o">:</span> <span class="n">nginx</span><span class="o">-</span><span class="n">config</span>
@ -1329,6 +1338,7 @@ are not compatible with nginx-ingress's default configuration.</p>
<span class="n">ssl</span><span class="o">-</span><span class="n">ciphers</span><span class="o">:</span> <span class="s2">&quot;ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA&quot;</span>
<span class="n">ssl</span><span class="o">-</span><span class="n">protocols</span><span class="o">:</span> <span class="s2">&quot;TLSv1 TLSv1.1 TLSv1.2&quot;</span>
</pre></div>
</td></tr></table>