Deploy GitHub Pages
This commit is contained in:
Travis Bot
parent
1554e74281
commit
0a662654ae
6 changed files with 214 additions and 145 deletions
|
|
@ -831,10 +831,53 @@
|
|||
|
||||
|
||||
|
||||
<label class="md-nav__link md-nav__link--active" for="toc">
|
||||
Custom Errors
|
||||
</label>
|
||||
|
||||
<a href="./" title="Custom Errors" class="md-nav__link md-nav__link--active">
|
||||
Custom Errors
|
||||
</a>
|
||||
|
||||
|
||||
<nav class="md-nav md-nav--secondary">
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<label class="md-nav__title" for="toc">Table of contents</label>
|
||||
<ul class="md-nav__list" data-md-scrollfix>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#customized-default-backend" title="Customized default backend" class="md-nav__link">
|
||||
Customized default backend
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#ingress-controller-configuration" title="Ingress controller configuration" class="md-nav__link">
|
||||
Ingress controller configuration
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#testing-error-pages" title="Testing error pages" class="md-nav__link">
|
||||
Testing error pages
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</ul>
|
||||
|
||||
</nav>
|
||||
|
||||
</li>
|
||||
|
||||
|
||||
|
|
@ -1057,6 +1100,36 @@
|
|||
|
||||
|
||||
|
||||
<label class="md-nav__title" for="toc">Table of contents</label>
|
||||
<ul class="md-nav__list" data-md-scrollfix>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#customized-default-backend" title="Customized default backend" class="md-nav__link">
|
||||
Customized default backend
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#ingress-controller-configuration" title="Ingress controller configuration" class="md-nav__link">
|
||||
Ingress controller configuration
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#testing-error-pages" title="Testing error pages" class="md-nav__link">
|
||||
Testing error pages
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</ul>
|
||||
|
||||
</nav>
|
||||
</div>
|
||||
</div>
|
||||
|
|
@ -1071,79 +1144,77 @@
|
|||
|
||||
|
||||
<h1 id="custom-errors">Custom Errors<a class="headerlink" href="#custom-errors" title="Permanent link">¶</a></h1>
|
||||
<p>This example shows how is possible to use a custom backend to render custom error pages. The code of this example is located here <a href="https://github.com/kubernetes/ingress-nginx/tree/master/docs/examples/customization/custom-errors">custom-error-pages</a></p>
|
||||
<p>The idea is to use the headers <code class="codehilite">X-Code</code> and <code class="codehilite">X-Format</code> that NGINX pass to the backend in case of an error to find out the best existent representation of the response to be returned. i.e. if the request contains an <code class="codehilite">Accept</code> header of type <code class="codehilite">json</code> the error should be in that format and not in <code class="codehilite">html</code> (the default in NGINX).</p>
|
||||
<p>First create the custom backend to use in the Ingress controller</p>
|
||||
<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">¶</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
|
||||
service <span class="s2">"nginx-errors"</span> created
|
||||
replicationcontroller <span class="s2">"nginx-errors"</span> created
|
||||
deployment.apps <span class="s2">"nginx-errors"</span> created
|
||||
</pre></div>
|
||||
|
||||
|
||||
<div class="codehilite"><pre><span></span>$ kubectl get svc
|
||||
NAME CLUSTER-IP EXTERNAL-IP PORT<span class="o">(</span>S<span class="o">)</span> AGE
|
||||
echoheaders <span class="m">10</span>.3.0.7 nodes <span class="m">80</span>/TCP 23d
|
||||
kubernetes <span class="m">10</span>.3.0.1 <none> <span class="m">443</span>/TCP 34d
|
||||
nginx-errors <span class="m">10</span>.3.0.102 <none> <span class="m">80</span>/TCP 11s
|
||||
<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
|
||||
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 <none> <span class="m">80</span>/TCP 10s
|
||||
</pre></div>
|
||||
|
||||
|
||||
<div class="codehilite"><pre><span></span>$ kubectl get rc
|
||||
CONTROLLER REPLICAS AGE
|
||||
echoheaders <span class="m">1</span> 19d
|
||||
nginx-errors <span class="m">1</span> 19s
|
||||
<h2 id="ingress-controller-configuration">Ingress controller configuration<a class="headerlink" href="#ingress-controller-configuration" title="Permanent link">¶</a></h2>
|
||||
<p>If you do not already have an instance of the the NGINX Ingress controller running, deploy it according to the
|
||||
<a href="../../../../deploy/">deployment guide</a>, then follow these steps:</p>
|
||||
<ol>
|
||||
<li>
|
||||
<p>Edit the <code class="codehilite">nginx-ingress-controller</code> Deployment and set the value of the <code class="codehilite">--default-backend</code> flag to the name of the
|
||||
newly created error backend.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Edit the <code class="codehilite">nginx-configuration</code> ConfigMap and create the key <code class="codehilite">custom-http-errors</code> with a value of <code class="codehilite">404,503</code>.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Take note of the IP address assigned to the NGINX Ingress controller Service.
|
||||
<code class="codehilite">$ kubectl get svc ingress-nginxNAME TYPE CLUSTER-IP EXTERNAL-IP PORT<span class="o">(</span>S<span class="o">)</span> AGEingress-nginx ClusterIP <span class="m">10</span>.0.0.13 <none> <span class="m">80</span>/TCP,443/TCP 10m</code></p>
|
||||
</li>
|
||||
</ol>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>The <code class="codehilite">ingress-nginx</code> Service is of type <code class="codehilite">ClusterIP</code> in this example. This may vary depending on your environment.
|
||||
Make sure you can use the Service to reach NGINX before proceeding with the rest of this example.</p>
|
||||
</div>
|
||||
<h2 id="testing-error-pages">Testing error pages<a class="headerlink" href="#testing-error-pages" title="Permanent link">¶</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/
|
||||
HTTP/1.1 404 Not Found
|
||||
Server: nginx/1.13.12
|
||||
Date: Tue, 12 Jun 2018 19:11:24 GMT
|
||||
Content-Type: */*
|
||||
Transfer-Encoding: chunked
|
||||
Connection: keep-alive
|
||||
|
||||
<span class="nt"><span></span>The page you're looking for could not be found.<span class="nt"></span></span>
|
||||
</pre></div>
|
||||
|
||||
|
||||
<p>Next create the Ingress controller executing</p>
|
||||
<div class="codehilite"><pre><span></span>$ kubectl create -f rc-custom-errors.yaml
|
||||
</pre></div>
|
||||
<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">'Accept: application/json'</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
|
||||
Content-Type: application/json
|
||||
Transfer-Encoding: chunked
|
||||
Connection: keep-alive
|
||||
Vary: Accept-Encoding
|
||||
|
||||
|
||||
<p>Now to check if this is working we use curl:</p>
|
||||
<div class="codehilite"><pre><span></span>$ curl -v http://172.17.4.99/
|
||||
* Trying 172.17.4.99...
|
||||
* Connected to 172.17.4.99 (172.17.4.99) port 80 (#0)
|
||||
> GET / HTTP/1.1
|
||||
> Host: 172.17.4.99
|
||||
> User-Agent: curl/7.43.0
|
||||
> Accept: */*
|
||||
>
|
||||
<span class="nt">< HTTP</span><span class="err">/1.1</span> <span class="err">404</span> <span class="err">Not</span> <span class="err">Found</span>
|
||||
<span class="err"><</span> <span class="err">Server:</span> <span class="err">nginx/1.10.0</span>
|
||||
<span class="err"><</span> <span class="err">Date:</span> <span class="err">Wed,</span> <span class="err">04</span> <span class="err">May</span> <span class="err">2016</span> <span class="err">02:53:45</span> <span class="err">GMT</span>
|
||||
<span class="err"><</span> <span class="err">Content-Type:</span> <span class="err">text/html</span>
|
||||
<span class="err"><</span> <span class="err">Transfer-Encoding:</span> <span class="err">chunked</span>
|
||||
<span class="err"><</span> <span class="err">Connection:</span> <span class="err">keep-alive</span>
|
||||
<span class="err"><</span> <span class="err">Vary:</span> <span class="err">Accept-Encoding</span>
|
||||
<span class="err"><</span>
|
||||
<span class="err"><span</span><span class="nt">></span>The page you're looking for could not be found.<span class="nt"></span></span>
|
||||
|
||||
* Connection #0 to host 172.17.4.99 left intact
|
||||
</pre></div>
|
||||
|
||||
|
||||
<p>Specifying json as expected format:</p>
|
||||
<div class="codehilite"><pre><span></span>$ curl -v http://172.17.4.99/ -H <span class="s1">'Accept: application/json'</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>
|
||||
> GET / HTTP/1.1
|
||||
> Host: <span class="m">172</span>.17.4.99
|
||||
> User-Agent: curl/7.43.0
|
||||
> Accept: application/json
|
||||
>
|
||||
< HTTP/1.1 <span class="m">404</span> Not Found
|
||||
< Server: nginx/1.10.0
|
||||
< Date: Wed, <span class="m">04</span> May <span class="m">2016</span> <span class="m">02</span>:54:00 GMT
|
||||
< Content-Type: text/html
|
||||
< Transfer-Encoding: chunked
|
||||
< Connection: keep-alive
|
||||
< Vary: Accept-Encoding
|
||||
<
|
||||
<span class="o">{</span> <span class="s2">"message"</span>: <span class="s2">"The page you're looking for could not be found"</span> <span class="o">}</span>
|
||||
|
||||
* Connection <span class="c1">#0 to host 172.17.4.99 left intact</span>
|
||||
</pre></div>
|
||||
|
||||
|
||||
<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>
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
---
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
|
|
@ -5,27 +6,30 @@ metadata:
|
|||
labels:
|
||||
app: nginx-errors
|
||||
spec:
|
||||
ports:
|
||||
- port: 80
|
||||
targetPort: 80
|
||||
protocol: TCP
|
||||
name: http
|
||||
selector:
|
||||
app: nginx-errors
|
||||
ports:
|
||||
- port: 80
|
||||
targetPort: 8080
|
||||
name: http
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: ReplicationController
|
||||
apiVersion: apps/v1beta2
|
||||
kind: Deployment
|
||||
apiVersion: apps/v1beta2
|
||||
metadata:
|
||||
name: nginx-errors
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: nginx-errors
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: nginx-errors
|
||||
spec:
|
||||
containers:
|
||||
- name: nginx-errors
|
||||
image: aledbf/nginx-error-server:0.1
|
||||
- name: nginx-error-server
|
||||
image: quay.io/kubernetes-ingress-controller/custom-error-pages-amd64:0.2
|
||||
ports:
|
||||
- containerPort: 80
|
||||
- containerPort: 8080
|
||||
|
|
|
|||
|
|
@ -1,53 +0,0 @@
|
|||
apiVersion: v1
|
||||
kind: ReplicationController
|
||||
metadata:
|
||||
name: nginx-ingress-controller
|
||||
labels:
|
||||
k8s-app: nginx-ingress-lb
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
k8s-app: nginx-ingress-lb
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
k8s-app: nginx-ingress-lb
|
||||
name: nginx-ingress-lb
|
||||
spec:
|
||||
terminationGracePeriodSeconds: 60
|
||||
containers:
|
||||
- image: quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.15.0
|
||||
name: nginx-ingress-lb
|
||||
imagePullPolicy: Always
|
||||
readinessProbe:
|
||||
httpGet:
|
||||
path: /healthz
|
||||
port: 10254
|
||||
scheme: HTTP
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
path: /healthz
|
||||
port: 10254
|
||||
scheme: HTTP
|
||||
initialDelaySeconds: 10
|
||||
timeoutSeconds: 1
|
||||
# use downward API
|
||||
env:
|
||||
- name: POD_NAME
|
||||
valueFrom:
|
||||
fieldRef:
|
||||
fieldPath: metadata.name
|
||||
- name: POD_NAMESPACE
|
||||
valueFrom:
|
||||
fieldRef:
|
||||
fieldPath: metadata.namespace
|
||||
ports:
|
||||
- containerPort: 80
|
||||
hostPort: 80
|
||||
- containerPort: 443
|
||||
hostPort: 443
|
||||
args:
|
||||
- /nginx-ingress-controller
|
||||
- --default-backend-service=$(POD_NAMESPACE)/nginx-errors
|
||||
securityContext:
|
||||
runAsNonRoot: false
|
||||
|
|
@ -1132,8 +1132,8 @@ Please review the <a href="PREREQUISITES/">prerequisites</a> before trying them.
|
|||
<tr>
|
||||
<td>Customization</td>
|
||||
<td><a href="customization/custom-errors/README/">Custom errors</a></td>
|
||||
<td>TODO</td>
|
||||
<td>TODO</td>
|
||||
<td>serve custom error pages from the default backend</td>
|
||||
<td>Intermediate</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Customization</td>
|
||||
|
|
|
|||
|
|
@ -972,12 +972,12 @@
|
|||
},
|
||||
{
|
||||
"location": "/user-guide/custom-errors/",
|
||||
"text": "Custom errors\n\u00b6\n\n\nIn case of an error in a request the body of the response is obtained from the \ndefault backend\n.\nEach request to the default backend includes two headers:\n\n\n\n\nX-Code\n indicates the HTTP code to be returned to the client.\n\n\nX-Format\n the value of the \nAccept\n header.\n\n\n\n\n\n\nImportant\n\n\nThe custom backend must return the correct HTTP status code to be returned. NGINX does not change the response from the custom default backend.\n\n\n\n\nUsing these two headers it's possible to use a custom backend service like \nthis one\n that inspects each request and returns a custom error page with the format expected by the client. Please check the example \ncustom-errors\n.\n\n\nNGINX sends additional headers that can be used to build custom response:\n\n\n\n\nX-Original-URI\n\n\nX-Namespace\n\n\nX-Ingress-Name\n\n\nX-Service-Name",
|
||||
"text": "Custom errors\n\u00b6\n\n\nWhen the \ncustom-http-errors\n option is enabled, the Ingress controller configures NGINX so\nthat it passes several HTTP headers down to its \ndefault-backend\n in case of error:\n\n\n\n\n\n\n\n\nHeader\n\n\nValue\n\n\n\n\n\n\n\n\n\n\nX-Code\n\n\nHTTP status code retuned by the request\n\n\n\n\n\n\nX-Format\n\n\nValue of the \nAccept\n header sent by the client\n\n\n\n\n\n\nX-Original-URI\n\n\nURI that caused the error\n\n\n\n\n\n\nX-Namespace\n\n\nNamespace where the backend Service is located\n\n\n\n\n\n\nX-Ingress-Name\n\n\nName of the Ingress where the backend is defined\n\n\n\n\n\n\nX-Service-Name\n\n\nName of the Service backing the backend\n\n\n\n\n\n\nX-Service-Port\n\n\nPort number of the Service backing the backend\n\n\n\n\n\n\n\n\nA custom error backend can use this information to return the best possible representation of an error page. For\nexample, if the value of the \nAccept\n header send by the client was \napplication/json\n, a carefully crafted backend\ncould decide to return the error payload as a JSON document instead of HTML.\n\n\n\n\nImportant\n\n\nThe custom backend is expected to return the correct HTTP status code instead of \n200\n. NGINX does not change\nthe response from the custom default backend.\n\n\n\n\nAn example of such custom backend is available inside the source repository at \nimages/custom-error-pages\n.\n\n\nSee also the \nCustom errors\n example.",
|
||||
"title": "Custom errors"
|
||||
},
|
||||
{
|
||||
"location": "/user-guide/custom-errors/#custom-errors",
|
||||
"text": "In case of an error in a request the body of the response is obtained from the default backend .\nEach request to the default backend includes two headers: X-Code indicates the HTTP code to be returned to the client. X-Format the value of the Accept header. Important The custom backend must return the correct HTTP status code to be returned. NGINX does not change the response from the custom default backend. Using these two headers it's possible to use a custom backend service like this one that inspects each request and returns a custom error page with the format expected by the client. Please check the example custom-errors . NGINX sends additional headers that can be used to build custom response: X-Original-URI X-Namespace X-Ingress-Name X-Service-Name",
|
||||
"text": "When the custom-http-errors option is enabled, the Ingress controller configures NGINX so\nthat it passes several HTTP headers down to its default-backend in case of error: Header Value X-Code HTTP status code retuned by the request X-Format Value of the Accept header sent by the client X-Original-URI URI that caused the error X-Namespace Namespace where the backend Service is located X-Ingress-Name Name of the Ingress where the backend is defined X-Service-Name Name of the Service backing the backend X-Service-Port Port number of the Service backing the backend A custom error backend can use this information to return the best possible representation of an error page. For\nexample, if the value of the Accept header send by the client was application/json , a carefully crafted backend\ncould decide to return the error payload as a JSON document instead of HTML. Important The custom backend is expected to return the correct HTTP status code instead of 200 . NGINX does not change\nthe response from the custom default backend. An example of such custom backend is available inside the source repository at images/custom-error-pages . See also the Custom errors example.",
|
||||
"title": "Custom errors"
|
||||
},
|
||||
{
|
||||
|
|
@ -1157,12 +1157,12 @@
|
|||
},
|
||||
{
|
||||
"location": "/examples/",
|
||||
"text": "Ingress examples\n\u00b6\n\n\nThis directory contains a catalog of examples on how to run, configure and scale Ingress.\n\nPlease review the \nprerequisites\n before trying them.\n\n\n\n\n\n\n\n\nCategory\n\n\nName\n\n\nDescription\n\n\nComplexity Level\n\n\n\n\n\n\n\n\n\n\nApps\n\n\nDocker Registry\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nAuth\n\n\nBasic authentication\n\n\npassword protect your website\n\n\nIntermediate\n\n\n\n\n\n\nAuth\n\n\nClient certificate authentication\n\n\nsecure your website with client certificate authentication\n\n\nIntermediate\n\n\n\n\n\n\nAuth\n\n\nExternal authentication plugin\n\n\ndefer to an external authentication service\n\n\nIntermediate\n\n\n\n\n\n\nAuth\n\n\nOAuth external auth\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nConfiguration snippets\n\n\ncustomize nginx location configuration using annotations\n\n\nAdvanced\n\n\n\n\n\n\nCustomization\n\n\nCustom configuration\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nCustom DH parameters for perfect forward secrecy\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nCustom errors\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nCustom headers\n\n\nset custom headers before sending traffic to backends\n\n\nAdvanced\n\n\n\n\n\n\nCustomization\n\n\nCustom upstream check\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nCustom VTS metrics with Prometheus\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nExternal authentication with response header propagation\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nSysctl tuning\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nFeatures\n\n\nRewrite\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nFeatures\n\n\nSession stickiness\n\n\nroute requests consistently to the same endpoint\n\n\nAdvanced\n\n\n\n\n\n\nScaling\n\n\nStatic IP\n\n\na single ingress gets a single static IP\n\n\nIntermediate\n\n\n\n\n\n\nTLS\n\n\nMulti TLS certificate termination\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nTLS\n\n\nTLS termination\n\n\nTODO\n\n\nTODO",
|
||||
"text": "Ingress examples\n\u00b6\n\n\nThis directory contains a catalog of examples on how to run, configure and scale Ingress.\n\nPlease review the \nprerequisites\n before trying them.\n\n\n\n\n\n\n\n\nCategory\n\n\nName\n\n\nDescription\n\n\nComplexity Level\n\n\n\n\n\n\n\n\n\n\nApps\n\n\nDocker Registry\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nAuth\n\n\nBasic authentication\n\n\npassword protect your website\n\n\nIntermediate\n\n\n\n\n\n\nAuth\n\n\nClient certificate authentication\n\n\nsecure your website with client certificate authentication\n\n\nIntermediate\n\n\n\n\n\n\nAuth\n\n\nExternal authentication plugin\n\n\ndefer to an external authentication service\n\n\nIntermediate\n\n\n\n\n\n\nAuth\n\n\nOAuth external auth\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nConfiguration snippets\n\n\ncustomize nginx location configuration using annotations\n\n\nAdvanced\n\n\n\n\n\n\nCustomization\n\n\nCustom configuration\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nCustom DH parameters for perfect forward secrecy\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nCustom errors\n\n\nserve custom error pages from the default backend\n\n\nIntermediate\n\n\n\n\n\n\nCustomization\n\n\nCustom headers\n\n\nset custom headers before sending traffic to backends\n\n\nAdvanced\n\n\n\n\n\n\nCustomization\n\n\nCustom upstream check\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nCustom VTS metrics with Prometheus\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nExternal authentication with response header propagation\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nCustomization\n\n\nSysctl tuning\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nFeatures\n\n\nRewrite\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nFeatures\n\n\nSession stickiness\n\n\nroute requests consistently to the same endpoint\n\n\nAdvanced\n\n\n\n\n\n\nScaling\n\n\nStatic IP\n\n\na single ingress gets a single static IP\n\n\nIntermediate\n\n\n\n\n\n\nTLS\n\n\nMulti TLS certificate termination\n\n\nTODO\n\n\nTODO\n\n\n\n\n\n\nTLS\n\n\nTLS termination\n\n\nTODO\n\n\nTODO",
|
||||
"title": "Ingress examples"
|
||||
},
|
||||
{
|
||||
"location": "/examples/#ingress-examples",
|
||||
"text": "This directory contains a catalog of examples on how to run, configure and scale Ingress. \nPlease review the prerequisites before trying them. Category Name Description Complexity Level Apps Docker Registry TODO TODO Auth Basic authentication password protect your website Intermediate Auth Client certificate authentication secure your website with client certificate authentication Intermediate Auth External authentication plugin defer to an external authentication service Intermediate Auth OAuth external auth TODO TODO Customization Configuration snippets customize nginx location configuration using annotations Advanced Customization Custom configuration TODO TODO Customization Custom DH parameters for perfect forward secrecy TODO TODO Customization Custom errors TODO TODO Customization Custom headers set custom headers before sending traffic to backends Advanced Customization Custom upstream check TODO TODO Customization Custom VTS metrics with Prometheus TODO TODO Customization External authentication with response header propagation TODO TODO Customization Sysctl tuning TODO TODO Features Rewrite TODO TODO Features Session stickiness route requests consistently to the same endpoint Advanced Scaling Static IP a single ingress gets a single static IP Intermediate TLS Multi TLS certificate termination TODO TODO TLS TLS termination TODO TODO",
|
||||
"text": "This directory contains a catalog of examples on how to run, configure and scale Ingress. \nPlease review the prerequisites before trying them. Category Name Description Complexity Level Apps Docker Registry TODO TODO Auth Basic authentication password protect your website Intermediate Auth Client certificate authentication secure your website with client certificate authentication Intermediate Auth External authentication plugin defer to an external authentication service Intermediate Auth OAuth external auth TODO TODO Customization Configuration snippets customize nginx location configuration using annotations Advanced Customization Custom configuration TODO TODO Customization Custom DH parameters for perfect forward secrecy TODO TODO Customization Custom errors serve custom error pages from the default backend Intermediate Customization Custom headers set custom headers before sending traffic to backends Advanced Customization Custom upstream check TODO TODO Customization Custom VTS metrics with Prometheus TODO TODO Customization External authentication with response header propagation TODO TODO Customization Sysctl tuning TODO TODO Features Rewrite TODO TODO Features Session stickiness route requests consistently to the same endpoint Advanced Scaling Static IP a single ingress gets a single static IP Intermediate TLS Multi TLS certificate termination TODO TODO TLS TLS termination TODO TODO",
|
||||
"title": "Ingress examples"
|
||||
},
|
||||
{
|
||||
|
|
@ -1327,14 +1327,29 @@
|
|||
},
|
||||
{
|
||||
"location": "/examples/customization/custom-errors/README/",
|
||||
"text": "Custom Errors\n\u00b6\n\n\nThis example shows how is possible to use a custom backend to render custom error pages. The code of this example is located here \ncustom-error-pages\n\n\nThe idea is to use the headers \nX-Code\n and \nX-Format\n that NGINX pass to the backend in case of an error to find out the best existent representation of the response to be returned. i.e. if the request contains an \nAccept\n header of type \njson\n the error should be in that format and not in \nhtml\n (the default in NGINX).\n\n\nFirst create the custom backend to use in the Ingress controller\n\n\n$ kubectl create -f custom-default-backend.yaml\nservice \n\"nginx-errors\"\n created\nreplicationcontroller \n\"nginx-errors\"\n created\n\n\n\n\n\n$ kubectl get svc\nNAME CLUSTER-IP EXTERNAL-IP PORT\n(\nS\n)\n AGE\nechoheaders \n10\n.3.0.7 nodes \n80\n/TCP 23d\nkubernetes \n10\n.3.0.1 <none> \n443\n/TCP 34d\nnginx-errors \n10\n.3.0.102 <none> \n80\n/TCP 11s\n\n\n\n\n\n$ kubectl get rc\nCONTROLLER REPLICAS AGE\nechoheaders \n1\n 19d\nnginx-errors \n1\n 19s\n\n\n\n\n\nNext create the Ingress controller executing\n\n\n$ kubectl create -f rc-custom-errors.yaml\n\n\n\n\n\nNow to check if this is working we use curl:\n\n\n$ curl -v http://172.17.4.99/\n* Trying 172.17.4.99...\n* Connected to 172.17.4.99 (172.17.4.99) port 80 (#0)\n> GET / HTTP/1.1\n> Host: 172.17.4.99\n> User-Agent: curl/7.43.0\n> Accept: */*\n>\n\n< HTTP\n/1.1\n \n404\n \nNot\n \nFound\n\n\n<\n \nServer:\n \nnginx/1.10.0\n\n\n<\n \nDate:\n \nWed,\n \n04\n \nMay\n \n2016\n \n02:53:45\n \nGMT\n\n\n<\n \nContent-Type:\n \ntext/html\n\n\n<\n \nTransfer-Encoding:\n \nchunked\n\n\n<\n \nConnection:\n \nkeep-alive\n\n\n<\n \nVary:\n \nAccept-Encoding\n\n\n<\n\n\n<span\n>\nThe page you're looking for could not be found.\n</span>\n\n\n* Connection #0 to host 172.17.4.99 left intact\n\n\n\n\n\nSpecifying json as expected format:\n\n\n$ curl -v http://172.17.4.99/ -H \n'Accept: application/json'\n\n* Trying \n172\n.17.4.99...\n* Connected to \n172\n.17.4.99 \n(\n172\n.17.4.99\n)\n port \n80\n \n(\n#0)\n\n> GET / HTTP/1.1\n> Host: \n172\n.17.4.99\n> User-Agent: curl/7.43.0\n> Accept: application/json\n>\n< HTTP/1.1 \n404\n Not Found\n< Server: nginx/1.10.0\n< Date: Wed, \n04\n May \n2016\n \n02\n:54:00 GMT\n< Content-Type: text/html\n< Transfer-Encoding: chunked\n< Connection: keep-alive\n< Vary: Accept-Encoding\n<\n\n{\n \n\"message\"\n: \n\"The page you're looking for could not be found\"\n \n}\n\n\n* Connection \n#0 to host 172.17.4.99 left intact",
|
||||
"text": "Custom Errors\n\u00b6\n\n\nThis example demonstrates how to use a custom backend to render custom error pages.\n\n\nCustomized default backend\n\u00b6\n\n\nFirst, create the custom \ndefault-backend\n. It will be used by the Ingress controller later on.\n\n\n$ kubectl create -f custom-default-backend.yaml\nservice \n\"nginx-errors\"\n created\ndeployment.apps \n\"nginx-errors\"\n created\n\n\n\n\n\nThis should have created a Deployment and a Service with the name \nnginx-errors\n.\n\n\n$ kubectl get deploy,svc\nNAME DESIRED CURRENT READY AGE\ndeployment.apps/nginx-errors \n1\n \n1\n \n1\n 10s\n\nNAME TYPE CLUSTER-IP EXTERNAL-IP PORT\n(\nS\n)\n AGE\nservice/nginx-errors ClusterIP \n10\n.0.0.12 <none> \n80\n/TCP 10s\n\n\n\n\n\nIngress controller configuration\n\u00b6\n\n\nIf you do not already have an instance of the the NGINX Ingress controller running, deploy it according to the\n\ndeployment guide\n, then follow these steps:\n\n\n\n\n\n\nEdit the \nnginx-ingress-controller\n Deployment and set the value of the \n--default-backend\n flag to the name of the\n newly created error backend.\n\n\n\n\n\n\nEdit the \nnginx-configuration\n ConfigMap and create the key \ncustom-http-errors\n with a value of \n404,503\n.\n\n\n\n\n\n\nTake note of the IP address assigned to the NGINX Ingress controller Service.\n \n$ kubectl get svc ingress-nginxNAME TYPE CLUSTER-IP EXTERNAL-IP PORT\n(\nS\n)\n AGEingress-nginx ClusterIP \n10\n.0.0.13 <none> \n80\n/TCP,443/TCP 10m\n\n\n\n\n\n\n\n\nNote\n\n\nThe \ningress-nginx\n Service is of type \nClusterIP\n in this example. This may vary depending on your environment.\nMake sure you can use the Service to reach NGINX before proceeding with the rest of this example.\n\n\n\n\nTesting error pages\n\u00b6\n\n\nLet us send a couple of HTTP requests using cURL and validate everything is working as expected.\n\n\nA request to the default backend returns a 404 error with a custom message:\n\n\n$ curl -D- http://10.0.0.13/\nHTTP/1.1 404 Not Found\nServer: nginx/1.13.12\nDate: Tue, 12 Jun 2018 19:11:24 GMT\nContent-Type: */*\nTransfer-Encoding: chunked\nConnection: keep-alive\n\n\n<span>\nThe page you're looking for could not be found.\n</span>\n\n\n\n\n\n\nA request with a custom \nAccept\n header returns the corresponding document type (JSON):\n\n\n$ curl -D- -H \n'Accept: application/json'\n http://10.0.0.13/\nHTTP/1.1 \n404\n Not Found\nServer: nginx/1.13.12\nDate: Tue, \n12\n Jun \n2018\n \n19\n:12:36 GMT\nContent-Type: application/json\nTransfer-Encoding: chunked\nConnection: keep-alive\nVary: Accept-Encoding\n\n\n{\n \n\"message\"\n: \n\"The page you're looking for could not be found\"\n \n}\n\n\n\n\n\n\nTo go further with this example, feel free to deploy your own applications and Ingress objects, and validate that the\nresponses are still in the correct format when a backend returns 503 (eg. if you scale a Deployment down to 0 replica).",
|
||||
"title": "Custom Errors"
|
||||
},
|
||||
{
|
||||
"location": "/examples/customization/custom-errors/README/#custom-errors",
|
||||
"text": "This example shows how is possible to use a custom backend to render custom error pages. The code of this example is located here custom-error-pages The idea is to use the headers X-Code and X-Format that NGINX pass to the backend in case of an error to find out the best existent representation of the response to be returned. i.e. if the request contains an Accept header of type json the error should be in that format and not in html (the default in NGINX). First create the custom backend to use in the Ingress controller $ kubectl create -f custom-default-backend.yaml\nservice \"nginx-errors\" created\nreplicationcontroller \"nginx-errors\" created $ kubectl get svc\nNAME CLUSTER-IP EXTERNAL-IP PORT ( S ) AGE\nechoheaders 10 .3.0.7 nodes 80 /TCP 23d\nkubernetes 10 .3.0.1 <none> 443 /TCP 34d\nnginx-errors 10 .3.0.102 <none> 80 /TCP 11s $ kubectl get rc\nCONTROLLER REPLICAS AGE\nechoheaders 1 19d\nnginx-errors 1 19s Next create the Ingress controller executing $ kubectl create -f rc-custom-errors.yaml Now to check if this is working we use curl: $ curl -v http://172.17.4.99/\n* Trying 172.17.4.99...\n* Connected to 172.17.4.99 (172.17.4.99) port 80 (#0)\n> GET / HTTP/1.1\n> Host: 172.17.4.99\n> User-Agent: curl/7.43.0\n> Accept: */*\n> < HTTP /1.1 404 Not Found < Server: nginx/1.10.0 < Date: Wed, 04 May 2016 02:53:45 GMT < Content-Type: text/html < Transfer-Encoding: chunked < Connection: keep-alive < Vary: Accept-Encoding < <span > The page you're looking for could not be found. </span> \n\n* Connection #0 to host 172.17.4.99 left intact Specifying json as expected format: $ curl -v http://172.17.4.99/ -H 'Accept: application/json' \n* Trying 172 .17.4.99...\n* Connected to 172 .17.4.99 ( 172 .17.4.99 ) port 80 ( #0) \n> GET / HTTP/1.1\n> Host: 172 .17.4.99\n> User-Agent: curl/7.43.0\n> Accept: application/json\n>\n< HTTP/1.1 404 Not Found\n< Server: nginx/1.10.0\n< Date: Wed, 04 May 2016 02 :54:00 GMT\n< Content-Type: text/html\n< Transfer-Encoding: chunked\n< Connection: keep-alive\n< Vary: Accept-Encoding\n< { \"message\" : \"The page you're looking for could not be found\" } \n\n* Connection #0 to host 172.17.4.99 left intact",
|
||||
"text": "This example demonstrates how to use a custom backend to render custom error pages.",
|
||||
"title": "Custom Errors"
|
||||
},
|
||||
{
|
||||
"location": "/examples/customization/custom-errors/README/#customized-default-backend",
|
||||
"text": "First, create the custom default-backend . It will be used by the Ingress controller later on. $ kubectl create -f custom-default-backend.yaml\nservice \"nginx-errors\" created\ndeployment.apps \"nginx-errors\" created This should have created a Deployment and a Service with the name nginx-errors . $ kubectl get deploy,svc\nNAME DESIRED CURRENT READY AGE\ndeployment.apps/nginx-errors 1 1 1 10s\n\nNAME TYPE CLUSTER-IP EXTERNAL-IP PORT ( S ) AGE\nservice/nginx-errors ClusterIP 10 .0.0.12 <none> 80 /TCP 10s",
|
||||
"title": "Customized default backend"
|
||||
},
|
||||
{
|
||||
"location": "/examples/customization/custom-errors/README/#ingress-controller-configuration",
|
||||
"text": "If you do not already have an instance of the the NGINX Ingress controller running, deploy it according to the deployment guide , then follow these steps: Edit the nginx-ingress-controller Deployment and set the value of the --default-backend flag to the name of the\n newly created error backend. Edit the nginx-configuration ConfigMap and create the key custom-http-errors with a value of 404,503 . Take note of the IP address assigned to the NGINX Ingress controller Service.\n $ kubectl get svc ingress-nginxNAME TYPE CLUSTER-IP EXTERNAL-IP PORT ( S ) AGEingress-nginx ClusterIP 10 .0.0.13 <none> 80 /TCP,443/TCP 10m Note The ingress-nginx Service is of type ClusterIP in this example. This may vary depending on your environment.\nMake sure you can use the Service to reach NGINX before proceeding with the rest of this example.",
|
||||
"title": "Ingress controller configuration"
|
||||
},
|
||||
{
|
||||
"location": "/examples/customization/custom-errors/README/#testing-error-pages",
|
||||
"text": "Let us send a couple of HTTP requests using cURL and validate everything is working as expected. A request to the default backend returns a 404 error with a custom message: $ curl -D- http://10.0.0.13/\nHTTP/1.1 404 Not Found\nServer: nginx/1.13.12\nDate: Tue, 12 Jun 2018 19:11:24 GMT\nContent-Type: */*\nTransfer-Encoding: chunked\nConnection: keep-alive <span> The page you're looking for could not be found. </span> A request with a custom Accept header returns the corresponding document type (JSON): $ curl -D- -H 'Accept: application/json' http://10.0.0.13/\nHTTP/1.1 404 Not Found\nServer: nginx/1.13.12\nDate: Tue, 12 Jun 2018 19 :12:36 GMT\nContent-Type: application/json\nTransfer-Encoding: chunked\nConnection: keep-alive\nVary: Accept-Encoding { \"message\" : \"The page you're looking for could not be found\" } To go further with this example, feel free to deploy your own applications and Ingress objects, and validate that the\nresponses are still in the correct format when a backend returns 503 (eg. if you scale a Deployment down to 0 replica).",
|
||||
"title": "Testing error pages"
|
||||
},
|
||||
{
|
||||
"location": "/examples/customization/custom-headers/README/",
|
||||
"text": "Custom Headers\n\u00b6\n\n\nThis example aims to demonstrate the deployment of an nginx ingress controller and\nuse a ConfigMap to configure a custom list of headers to be passed to the upstream\nserver\n\n\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/customization/custom-headers/configmap.yaml \\\n\n\n | kubectl apply -f -\n\n\n\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/customization/custom-headers/custom-headers.yaml \\\n\n\n | kubectl apply -f -\n\n\n\n\n\n\nTest\n\u00b6\n\n\nCheck the contents of the configmap is present in the nginx.conf file using:\n\nkubectl exec nginx-ingress-controller-873061567-4n3k2 -n kube-system cat /etc/nginx/nginx.conf",
|
||||
|
|
|
|||
|
|
@ -1069,24 +1069,56 @@
|
|||
|
||||
|
||||
<h1 id="custom-errors">Custom errors<a class="headerlink" href="#custom-errors" title="Permanent link">¶</a></h1>
|
||||
<p>In case of an error in a request the body of the response is obtained from the <code class="codehilite">default backend</code>.
|
||||
Each request to the default backend includes two headers:</p>
|
||||
<ul>
|
||||
<li><code class="codehilite">X-Code</code> indicates the HTTP code to be returned to the client.</li>
|
||||
<li><code class="codehilite">X-Format</code> the value of the <code class="codehilite">Accept</code> header.</li>
|
||||
</ul>
|
||||
<p>When the <a href="../nginx-configuration/configmap/#custom-http-errors"><code class="codehilite">custom-http-errors</code></a> option is enabled, the Ingress controller configures NGINX so
|
||||
that it passes several HTTP headers down to its <code class="codehilite">default-backend</code> in case of error:</p>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Header</th>
|
||||
<th>Value</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code class="codehilite">X-Code</code></td>
|
||||
<td>HTTP status code retuned by the request</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code class="codehilite">X-Format</code></td>
|
||||
<td>Value of the <code class="codehilite">Accept</code> header sent by the client</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code class="codehilite">X-Original-URI</code></td>
|
||||
<td>URI that caused the error</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code class="codehilite">X-Namespace</code></td>
|
||||
<td>Namespace where the backend Service is located</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code class="codehilite">X-Ingress-Name</code></td>
|
||||
<td>Name of the Ingress where the backend is defined</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code class="codehilite">X-Service-Name</code></td>
|
||||
<td>Name of the Service backing the backend</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code class="codehilite">X-Service-Port</code></td>
|
||||
<td>Port number of the Service backing the backend</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>A custom error backend can use this information to return the best possible representation of an error page. For
|
||||
example, if the value of the <code class="codehilite">Accept</code> header send by the client was <code class="codehilite">application/json</code>, a carefully crafted backend
|
||||
could decide to return the error payload as a JSON document instead of HTML.</p>
|
||||
<div class="admonition important">
|
||||
<p class="admonition-title">Important</p>
|
||||
<p>The custom backend must return the correct HTTP status code to be returned. NGINX does not change the response from the custom default backend.</p>
|
||||
<p>The custom backend is expected to return the correct HTTP status code instead of <code class="codehilite">200</code>. NGINX does not change
|
||||
the response from the custom default backend.</p>
|
||||
</div>
|
||||
<p>Using these two headers it's possible to use a custom backend service like <a href="https://github.com/kubernetes/ingress-nginx/tree/master/images/custom-error-pages">this one</a> that inspects each request and returns a custom error page with the format expected by the client. Please check the example <a href="https://github.com/kubernetes/ingress-nginx/tree/master/docs/examples/customization/custom-errors">custom-errors</a>.</p>
|
||||
<p>NGINX sends additional headers that can be used to build custom response:</p>
|
||||
<ul>
|
||||
<li>X-Original-URI</li>
|
||||
<li>X-Namespace</li>
|
||||
<li>X-Ingress-Name</li>
|
||||
<li>X-Service-Name</li>
|
||||
</ul>
|
||||
<p>An example of such custom backend is available inside the source repository at <a href="https://github.com/kubernetes/ingress-nginx/tree/master/images/custom-error-pages">images/custom-error-pages</a>.</p>
|
||||
<p>See also the <a href="../../examples/customization/custom-errors">Custom errors</a> example.</p>
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue