+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/deploy/rbac/index.html b/deploy/rbac/index.html
new file mode 100644
index 000000000..aebd7b3a8
--- /dev/null
+++ b/deploy/rbac/index.html
@@ -0,0 +1,1290 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Installation Guide¶
+Contents¶
+-
+
- Mandatory commands +
- Install without RBAC roles +
- Install with RBAC roles +
- Custom Provider +
- Docker for Mac +
- minikube +
- AWS +
- GCE - GKE +
- Azure +
- Baremetal +
- Using Helm +
- Verify installation +
- Detect installed version +
- Deploying the config-map +
Generic Deployment¶
+The following resources are required for a generic deployment.
+Mandatory commands¶
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/namespace.yaml \ + | kubectl apply -f - + +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/default-backend.yaml \ + | kubectl apply -f - + +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/configmap.yaml \ + | kubectl apply -f - + +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/tcp-services-configmap.yaml \ + | kubectl apply -f - + +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/udp-services-configmap.yaml \ + | kubectl apply -f - +
Install without RBAC roles¶
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/without-rbac.yaml \ + | kubectl apply -f - +
Install with RBAC roles¶
+Please check the RBAC document.
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/rbac.yaml \ + | kubectl apply -f - + +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/with-rbac.yaml \ + | kubectl apply -f - +
Custom Service Provider Deployment¶
+There are cloud provider specific yaml files.
+Docker for Mac¶
+Kubernetes is available for Docker for Mac's Edge channel. Switch to the Edge +channel and enable Kubernetes.
+Patch the nginx ingress controller deployment to add the flag --publish-service
kubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \ + --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)" +
Create a service
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/docker-for-mac/service.yaml \ + | kubectl apply -f - +
minikube¶
+For standard usage:
+minikube addons enable ingress
+For development:
+-
+
- Disable the ingress addon: +
$ minikube addons disable ingress
+-
+
- Use the docker daemon +
- Build the image +
- Perform Mandatory commands +
- Install the
nginx-ingress-controllerdeployment without RBAC roles or with RBAC roles
+ - Edit the
nginx-ingress-controllerdeployment to use your custom image. Local images can be seen by performingdocker images.
+
$ kubectl edit deployment nginx-ingress-controller -n ingress-nginx
+edit the following section:
+image: <IMAGE-NAME>:<TAG> +imagePullPolicy: IfNotPresent +name: nginx-ingress-controller +
-
+
- Confirm the
nginx-ingress-controllerdeployment exists:
+
$ kubectl get pods -n ingress-nginx +NAME READY STATUS RESTARTS AGE +default-http-backend-66b447d9cf-rrlf9 1/1 Running 0 12s +nginx-ingress-controller-fdcdcd6dd-vvpgs 1/1 Running 0 11s +
AWS¶
+In AWS we use an Elastic Load Balancer (ELB) to expose the NGINX Ingress controller behind a Service of Type=LoadBalancer.
+Since Kubernetes v1.9.0 it is possible to use a classic load balancer (ELB) or network load balancer (NLB)
+Please check the elastic load balancing AWS details page
Elastic Load Balancer - ELB¶
+This setup requires to choose in which layer (L4 or L7) we want to configure the ELB:
+-
+
- Layer 4: use TCP as the listener protocol for ports 80 and 443. +
- Layer 7: use HTTP as the listener protocol for port 80 and terminate TLS in the ELB +
Patch the nginx ingress controller deployment to add the flag --publish-service
kubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \ + --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)" +
For L4:
+kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/service-l4.yaml +kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/patch-configmap-l4.yaml +
For L7:
+Change line of the file provider/aws/service-l7.yaml replacing the dummy id with a valid one "arn:aws:acm:us-west-2:XXXXXXXX:certificate/XXXXXX-XXXXXXX-XXXXXXX-XXXXXXXX"
+Then execute:
kubectl apply -f provider/aws/service-l7.yaml +kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/patch-configmap-l7.yaml +
This example creates an ELB with just two listeners, one in port 80 and another in port 443
+
If the ingress controller uses RBAC run:
+kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml
+If not run:
+kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml
+Network Load Balancer (NLB)¶
+This type of load balancer is supported since v1.10.0 as an ALPHA feature.
+kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/service-nlb.yaml
+If the ingress controller uses RBAC run:
+kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml
+If not run:
+kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml
+GCE - GKE¶
+Patch the nginx ingress controller deployment to add the flag --publish-service
kubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \ + --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)" +
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/gce-gke/service.yaml \ + | kubectl apply -f - +
If the ingress controller uses RBAC run:
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml | kubectl apply -f -
+If not run:
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml | kubectl apply -f -
+Important Note: proxy protocol is not supported in GCE/GKE
+Azure¶
+Patch the nginx ingress controller deployment to add the flag --publish-service
kubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \ + --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)" +
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/azure/service.yaml \ + | kubectl apply -f - +
If the ingress controller uses RBAC run:
+kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml
+If not run:
+kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml
+Important Note: proxy protocol is not supported in GCE/GKE
+Baremetal¶
+Using NodePort:
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/baremetal/service-nodeport.yaml \ + | kubectl apply -f - +
Using Helm¶
+NGINX Ingress controller can be installed via Helm using the chart stable/nginx from the official charts repository.
+To install the chart with the release name my-nginx:
helm install stable/nginx-ingress --name my-nginx
+If the kubernetes cluster has RBAC enabled, then run:
+helm install stable/nginx-ingress --name my-nginx --set rbac.create=true
+Verify installation¶
+To check if the ingress controller pods have started, run the following command:
+kubectl get pods --all-namespaces -l app=ingress-nginx --watch
+Once the operator pods are running, you can cancel the above command by typing Ctrl+C.
+Now, you are ready to create your first ingress.
Detect installed version¶
+To detect which version of the ingress controller is running, exec into the pod and run nginx-ingress-controller version command.
POD_NAMESPACE=ingress-nginx +POD_NAME=$(kubectl get pods -n $POD_NAMESPACE -l app=ingress-nginx -o jsonpath={.items[0].metadata.name}) +kubectl exec -it $POD_NAME -n $POD_NAMESPACE -- /nginx-ingress-controller --version +
Deploying the config-map¶
+A config map can be used to configure system components for the nginx-controller. In order to begin using a config-map +make sure it has been created and is being used in the deployment.
+It is created as seen in the Mandatory Commands section above.
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/configmap.yaml \ + | kubectl apply -f - +
and is setup to be used in the deployment without-rbac or with-rbac with the following line:
+- --configmap=$(POD_NAMESPACE)/nginx-configuration +
For information on using the config-map, see its user-guide.
+ + + + + + + + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/development/index.html b/development/index.html
new file mode 100644
index 000000000..2cee76cae
--- /dev/null
+++ b/development/index.html
@@ -0,0 +1,1407 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Role Based Access Control (RBAC)¶
+Overview¶
+This example applies to nginx-ingress-controllers being deployed in an environment with RBAC enabled.
+Role Based Access Control is comprised of four layers:
+-
+
ClusterRole- permissions assigned to a role that apply to an entire cluster
+ClusterRoleBinding- binding a ClusterRole to a specific account
+Role- permissions assigned to a role that apply to a specific namespace
+RoleBinding- binding a Role to a specific account
+
In order for RBAC to be applied to an nginx-ingress-controller, that controller
+should be assigned to a ServiceAccount. That ServiceAccount should be
+bound to the Roles and ClusterRoles defined for the nginx-ingress-controller.
Service Accounts created in this example¶
+One ServiceAccount is created in this example, nginx-ingress-serviceaccount.
Permissions Granted in this example¶
+There are two sets of permissions defined in this example. Cluster-wide
+permissions defined by the ClusterRole named nginx-ingress-clusterrole, and
+namespace specific permissions defined by the Role named nginx-ingress-role.
Cluster Permissions¶
+These permissions are granted in order for the nginx-ingress-controller to be
+able to function as an ingress across the cluster. These permissions are
+granted to the ClusterRole named nginx-ingress-clusterrole
-
+
configmaps,endpoints,nodes,pods,secrets: list, watch
+nodes: get
+services,ingresses: get, list, watch
+events: create, patch
+ingresses/status: update
+
Namespace Permissions¶
+These permissions are granted specific to the nginx-ingress namespace. These
+permissions are granted to the Role named nginx-ingress-role
-
+
configmaps,pods,secrets: get
+endpoints: get
+
Furthermore to support leader-election, the nginx-ingress-controller needs to
+have access to a configmap using the resourceName ingress-controller-leader-nginx
++Note that resourceNames can NOT be used to limit requests using the “create” +verb because authorizers only have access to information that can be obtained +from the request URL, method, and headers (resource names in a “create” request +are part of the request body).
+
-
+
configmaps: get, update (for resourceNameingress-controller-leader-nginx)
+configmaps: create
+
This resourceName is the concatenation of the election-id and the
+ingress-class as defined by the ingress-controller, which defaults to:
-
+
election-id:ingress-controller-leader
+ingress-class:nginx
+resourceName:<election-id>-<ingress-class>
+
Please adapt accordingly if you overwrite either parameter when launching the +nginx-ingress-controller.
+Bindings¶
+The ServiceAccount nginx-ingress-serviceaccount is bound to the Role
+nginx-ingress-role and the ClusterRole nginx-ingress-clusterrole.
The serviceAccountName associated with the containers in the deployment must +match the serviceAccount. The namespace references in the Deployment metadata, +container arguments, and POD_NAMESPACE should be in the nginx-ingress namespace.
+ + + + + + + + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/PREREQUISITES/index.html b/examples/PREREQUISITES/index.html
new file mode 100644
index 000000000..eebae4c80
--- /dev/null
+++ b/examples/PREREQUISITES/index.html
@@ -0,0 +1,1395 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Developing for NGINX Ingress controller¶
+This document explains how to get started with developing for NGINX Ingress controller. +It includes how to build, test, and release ingress controllers.
+Quick Start¶
+Initial developer environment build¶
+Prequisites: Minikube must be installed; See releases for installation instructions.
+If you are using MacOS and deploying to minikube, 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 ingress-nginx:
$ make dev-env +
Updating the deployment¶
+The nginx controller container image can be rebuilt using:
+$ ARCH=amd64 TAG=dev REGISTRY=$USER/ingress-controller make build container +
The image will only be used by pods created after the rebuild. To delete old pods which will cause new ones to spin up:
+$ kubectl get pods -n ingress-nginx +$ kubectl delete pod -n ingress-nginx nginx-ingress-controller-<unique-pod-id> +
Dependencies¶
+The build uses dependencies in the vendor directory, which
+must be installed before building a binary/image. Occasionally, you
+might need to update the dependencies.
This guide requires you to install the dep dependency tool.
+Check the version of dep you are using and make sure it is up to date.
$ dep version +dep: + version : devel + build date : + git hash : + go version : go1.9 + go compiler : gc + platform : linux/amd64 +
If you have an older version of dep, you can update it as follows:
$ go get -u github.com/golang/dep
+This will automatically save the dependencies to the vendor/ directory.
$ cd $GOPATH/src/k8s.io/ingress-nginx +$ dep ensure +$ dep ensure -update +$ dep prune +
Building¶
+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.
+In order to use your local Docker, you may need to set the following environment variables:
+# "gcloud docker" (default) or "docker" +$ export DOCKER=<docker> + +# "quay.io/kubernetes-ingress-controller" (default), "index.docker.io", or your own registry +$ export REGISTRY=<your-docker-registry> +
To find the registry simply run: docker system info | grep Registry
Nginx Controller¶
+Build a raw server binary
+$ make build
+TODO: add more specific instructions needed for raw server binary.
+Build a local container image
+$ TAG=<tag> REGISTRY=$USER/ingress-controller make docker-build +
Push the container image to a remote repository
+$ TAG=<tag> REGISTRY=$USER/ingress-controller make docker-push +
Deploying¶
+There are several ways to deploy the ingress controller onto a cluster. +Please check the deployment guide
+Testing¶
+To run unit-tests, just run
+$ cd $GOPATH/src/k8s.io/ingress-nginx +$ make test +
If you have access to a Kubernetes cluster, you can also run e2e tests using ginkgo.
+$ cd $GOPATH/src/k8s.io/ingress-nginx +$ make e2e-test +
To run unit-tests for lua code locally, run:
+$ cd $GOPATH/src/k8s.io/ingress-nginx +$ ./rootfs/etc/nginx/lua/test/up.sh +$ make lua-test +
Lua tests are located in $GOPATH/src/k8s.io/ingress-nginx/rootfs/etc/nginx/lua/test. When creating a new test file it must follow the naming convention <mytest>_test.lua or it will be ignored.
Releasing¶
+All Makefiles will produce a release binary, as shown above. To publish this
+to a wider Kubernetes user base, push the image to a container registry, like
+gcr.io. All release images are hosted under gcr.io/google_containers and
+tagged according to a semver scheme.
An example release might look like:
+$ make release +
Please follow these guidelines to cut a release:
+-
+
- Update the release +page with a short description of the major changes that correspond to a given +image tag. +
- Cut a release branch, if appropriate. Release branches follow the format of
+
controller-release-version. Typically, pre-releases are cut from HEAD. +All major feature work is done in HEAD. Specific bug fixes are +cherry-picked into a release branch.
+ - If you're not confident about the stability of the code, +tag it as alpha or beta. +Typically, a release branch should have stable code. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/README/index.html b/examples/README/index.html
new file mode 100644
index 000000000..de90b4d94
--- /dev/null
+++ b/examples/README/index.html
@@ -0,0 +1,1273 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Prerequisites¶
+Many of the examples in this directory have common prerequisites.
+TLS certificates¶
+Unless otherwise mentioned, the TLS secret used in examples is a 2048 bit RSA +key/cert pair with an arbitrarily chosen hostname, created as follows
+$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=nginxsvc/O=nginxsvc" +Generating a 2048 bit RSA private key +................+++ +................+++ +writing new private key to 'tls.key' +----- + +$ kubectl create secret tls tls-secret --key tls.key --cert tls.crt +secret "tls-secret" created +
CA Authentication¶
+You can act as your very own CA, or use an existing one. As an exercise / learning, we're going to generate our +own CA, and also generate a client certificate.
+These instructions are based on CoreOS OpenSSL instructions
+Generating a CA¶
+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:
+$ openssl s_client -connect www.google.com:443 +[...] +--- +Certificate chain + 0 s:/C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com + i:/C=US/O=Google Inc/CN=Google Internet Authority G2 + 1 s:/C=US/O=Google Inc/CN=Google Internet Authority G2 + i:/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA + 2 s:/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA + i:/C=US/O=Equifax/OU=Equifax Secure Certificate Authority +
To generate our CA Certificate, we've to run the following commands:
+$ openssl genrsa -out ca.key 2048 +$ openssl req -x509 -new -nodes -key ca.key -days 10000 -out ca.crt -subj "/CN=example-ca" +
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.
+Generating the client certificate¶
+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.
+First, we need to generate an 'openssl.cnf' file that will be used while signing the keys:
+[req] +req_extensions = v3_req +distinguished_name = req_distinguished_name +[req_distinguished_name] +[ v3_req ] +basicConstraints = CA:FALSE +keyUsage = nonRepudiation, digitalSignature, keyEncipherment +
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.
+$ openssl genrsa -out client1.key 2048 +$ openssl req -new -key client1.key -out client1.csr -subj "/CN=client1" -config openssl.cnf +
As the CA receives the generated 'client1.csr' file, it signs it and generates a client.crt certificate:
+$ openssl x509 -req -in client1.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client1.crt -days 365 -extensions v3_req -extfile openssl.cnf +
Then, you'll have 3 files: the client.key (user's private key), client.crt (user's public key) and client.csr (disposable CSR).
+Creating the CA Authentication secret¶
+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):
+-----BEGIN CERTIFICATE----- +[....] +-----END CERTIFICATE----- +
You can have as many certificates as you want. If they're in the binary DER format, +you can convert them as the following:
+$ openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem
+Then, you've to concatenate them all in only one file, named 'ca.crt' as the following:
+$ cat certificate1.crt certificate2.crt certificate3.crt >> ca.crt
+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:
+$ kubectl create secret generic caingress --namespace=default --from-file=ca.crt=<ca.crt> +
Note: You can also generate the CA Authentication Secret along with the TLS Secret by using:
+$ kubectl create secret generic caingress --namespace=default --from-file=ca.crt=<ca.crt> --from-file=tls.crt=<tls.crt> --from-file=tls.key=<tls.key> +
Test HTTP Service¶
+All examples that require a test HTTP Service use the standard http-svc pod, +which you can deploy as follows
+$ kubectl create -f http-svc.yaml +service "http-svc" created +replicationcontroller "http-svc" created + +$ kubectl get po +NAME READY STATUS RESTARTS AGE +http-svc-p1t3t 1/1 Running 0 1d + +$ kubectl get svc +NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE +http-svc 10.0.122.116 <pending> 80:30301/TCP 1d +
You can test that the HTTP Service works by exposing it temporarily
+$ kubectl patch svc http-svc -p '{"spec":{"type": "LoadBalancer"}}' +"http-svc" patched + +$ kubectl get svc http-svc +NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE +http-svc 10.0.122.116 <pending> 80:30301/TCP 1d + +$ kubectl describe svc http-svc +Name: http-svc +Namespace: default +Labels: app=http-svc +Selector: app=http-svc +Type: LoadBalancer +IP: 10.0.122.116 +LoadBalancer Ingress: 108.59.87.136 +Port: http 80/TCP +NodePort: http 30301/TCP +Endpoints: 10.180.1.6:8080 +Session Affinity: None +Events: + FirstSeen LastSeen Count From SubObjectPath Type Reason Message + --------- -------- ----- ---- ------------- -------- ------ ------- + 1m 1m 1 {service-controller } Normal Type ClusterIP -> LoadBalancer + 1m 1m 1 {service-controller } Normal CreatingLoadBalancer Creating load balancer + 16s 16s 1 {service-controller } Normal CreatedLoadBalancer Created load balancer + +$ curl 108.59.87.126 +CLIENT VALUES: +client_address=10.240.0.3 +command=GET +real path=/ +query=nil +request_version=1.1 +request_uri=http://108.59.87.136:8080/ + +SERVER VALUES: +server_version=nginx: 1.9.11 - lua: 10001 + +HEADERS RECEIVED: +accept=*/* +host=108.59.87.136 +user-agent=curl/7.46.0 +BODY: +-no body in request- + +$ kubectl patch svc http-svc -p '{"spec":{"type": "NodePort"}}' +"http-svc" patched +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/affinity/cookie/README/index.html b/examples/affinity/cookie/README/index.html
new file mode 100644
index 000000000..a880cdd14
--- /dev/null
+++ b/examples/affinity/cookie/README/index.html
@@ -0,0 +1,1236 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Ingress examples¶
+This directory contains a catalog of examples on how to run, configure and +scale Ingress. Please review the prerequisites before +trying them.
+Scaling¶
+| Name | +Description | +Complexity Level | +
|---|---|---|
| Static-ip | +a single ingress gets a single static ip | +Intermediate | +
Algorithms¶
+| Name | +Description | +Complexity Level | +
|---|---|---|
| Session stickyness | +route requests consistently to the same endpoint | +Advanced | +
Auth¶
+| Name | +Description | +Complexity Level | +
|---|---|---|
| Basic auth | +password protect your website | +nginx | +
| Client certificate authentication | +secure your website with client certificate authentication | +nginx | +
| External auth plugin | +defer to an external auth service | +Intermediate | +
Customization¶
+| Name | +Description | +Complexity Level | +
|---|---|---|
| configuration-snippets | +customize nginx location configuration using annotations | +Advanced | +
| custom-headers | +set custom headers before send traffic to backends | +Advanced | +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/affinity/cookie/ingress.yaml b/examples/affinity/cookie/ingress.yaml
new file mode 100644
index 000000000..b44752804
--- /dev/null
+++ b/examples/affinity/cookie/ingress.yaml
@@ -0,0 +1,18 @@
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+ name: nginx-test
+ annotations:
+ nginx.ingress.kubernetes.io/affinity: "cookie"
+ nginx.ingress.kubernetes.io/session-cookie-name: "route"
+ nginx.ingress.kubernetes.io/session-cookie-hash: "sha1"
+
+spec:
+ rules:
+ - host: stickyingress.example.com
+ http:
+ paths:
+ - backend:
+ serviceName: http-svc
+ servicePort: 80
+ path: /
diff --git a/examples/auth/basic/README/index.html b/examples/auth/basic/README/index.html
new file mode 100644
index 000000000..0e62f7583
--- /dev/null
+++ b/examples/auth/basic/README/index.html
@@ -0,0 +1,1224 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Sticky Session¶
+This example demonstrates how to achieve session affinity using cookies
+Deployment¶
+Session stickiness is achieved through 3 annotations on the Ingress, as shown in the example.
+| Name | +Description | +Values | +
|---|---|---|
| nginx.ingress.kubernetes.io/affinity | +Sets the affinity type | +string (in NGINX only cookie is possible |
+
| nginx.ingress.kubernetes.io/session-cookie-name | +Name of the cookie that will be used | +string (default to INGRESSCOOKIE) | +
| nginx.ingress.kubernetes.io/session-cookie-hash | +Type of hash that will be used in cookie value | +sha1/md5/index | +
You can create the ingress to test this
+kubectl create -f ingress.yaml
+Validation¶
+You can confirm that the Ingress works.
+$ kubectl describe ing nginx-test +Name: nginx-test +Namespace: default +Address: +Default backend: default-http-backend:80 (10.180.0.4:8080,10.240.0.2:8080) +Rules: + Host Path Backends + ---- ---- -------- + stickyingress.example.com + / nginx-service:80 (<none>) +Annotations: + affinity: cookie + session-cookie-hash: sha1 + session-cookie-name: INGRESSCOOKIE +Events: + FirstSeen LastSeen Count From SubObjectPath Type Reason Message + --------- -------- ----- ---- ------------- -------- ------ ------- + 7s 7s 1 {nginx-ingress-controller } Normal CREATE default/nginx-test + + +$ curl -I http://stickyingress.example.com +HTTP/1.1 200 OK +Server: nginx/1.11.9 +Date: Fri, 10 Feb 2017 14:11:12 GMT +Content-Type: text/html +Content-Length: 612 +Connection: keep-alive +Set-Cookie: INGRESSCOOKIE=a9907b79b248140b56bb13723f72b67697baac3d; Path=/; HttpOnly +Last-Modified: Tue, 24 Jan 2017 14:02:19 GMT +ETag: "58875e6b-264" +Accept-Ranges: bytes +
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.
+If the backend pool grows up NGINX will keep sending the requests through the same server of the first request, even if it's overloaded.
+When the backend server is removed, the requests are then re-routed to another upstream server and NGINX creates a new cookie, as the previous hash became invalid.
+When you have more than one Ingress Object pointing to the same Service, but one containing affinity configuration and other don't, the first created Ingress will be used. +This means that you can face the situation that you've configured Session Affinity in one Ingress and it doesn't reflects in NGINX configuration, because there is another Ingress Object pointing to the same service that doesn't configure this.
+ + + + + + + + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/auth/client-certs/README/index.html b/examples/auth/client-certs/README/index.html
new file mode 100644
index 000000000..747d2981e
--- /dev/null
+++ b/examples/auth/client-certs/README/index.html
@@ -0,0 +1,1161 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Basic Authentication¶
+This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with htpasswd.
$ htpasswd -c auth foo +New password: <bar> +New password: +Re-type new password: +Adding password for user foo +
$ kubectl create secret generic basic-auth --from-file=auth +secret "basic-auth" created +
$ kubectl get secret basic-auth -o yaml +apiVersion: v1 +data: + auth: Zm9vOiRhcHIxJE9GRzNYeWJwJGNrTDBGSERBa29YWUlsSDkuY3lzVDAK +kind: Secret +metadata: + name: basic-auth + namespace: default +type: Opaque +
echo " +apiVersion: extensions/v1beta1 +kind: Ingress +metadata: + name: ingress-with-auth + annotations: + # type of authentication + nginx.ingress.kubernetes.io/auth-type: basic + # name of the secret that contains the user/password definitions + nginx.ingress.kubernetes.io/auth-secret: basic-auth + # message to display with an appropriate context why the authentication is required + nginx.ingress.kubernetes.io/auth-realm: "Authentication Required - foo" +spec: + rules: + - host: foo.bar.com + http: + paths: + - path: / + backend: + serviceName: http-svc + servicePort: 80 +" | kubectl create -f - +
$ curl -v http://10.2.29.4/ -H 'Host: foo.bar.com' +* Trying 10.2.29.4... +* Connected to 10.2.29.4 (10.2.29.4) port 80 (#0) +> GET / HTTP/1.1 +> Host: foo.bar.com +> User-Agent: curl/7.43.0 +> Accept: */* +> +< HTTP/1.1 401 Unauthorized +< Server: nginx/1.10.0 +< Date: Wed, 11 May 2016 05:27:23 GMT +< Content-Type: text/html +< Content-Length: 195 +< Connection: keep-alive +< WWW-Authenticate: Basic realm="Authentication Required - foo" +< +<html> +<head><title>401 Authorization Required</title></head> +<body bgcolor="white"> +<center><h1>401 Authorization Required</h1></center> +<hr><center>nginx/1.10.0</center> +</body> +</html> +* Connection #0 to host 10.2.29.4 left intact +
$ curl -v http://10.2.29.4/ -H 'Host: foo.bar.com' -u 'foo:bar' +* Trying 10.2.29.4... +* Connected to 10.2.29.4 (10.2.29.4) port 80 (#0) +* Server auth using Basic with user 'foo' +> GET / HTTP/1.1 +> Host: foo.bar.com +> Authorization: Basic Zm9vOmJhcg== +> User-Agent: curl/7.43.0 +> Accept: */* +> +< HTTP/1.1 200 OK +< Server: nginx/1.10.0 +< Date: Wed, 11 May 2016 06:05:26 GMT +< Content-Type: text/plain +< Transfer-Encoding: chunked +< Connection: keep-alive +< Vary: Accept-Encoding +< +CLIENT VALUES: +client_address=10.2.29.4 +command=GET +real path=/ +query=nil +request_version=1.1 +request_uri=http://foo.bar.com:8080/ + +SERVER VALUES: +server_version=nginx: 1.9.11 - lua: 10001 + +HEADERS RECEIVED: +accept=*/* +authorization=Basic Zm9vOmJhcg== +connection=close +host=foo.bar.com +user-agent=curl/7.43.0 +x-forwarded-for=10.2.29.1 +x-forwarded-host=foo.bar.com +x-forwarded-port=80 +x-forwarded-proto=http +x-real-ip=10.2.29.1 +BODY: +* Connection #0 to host 10.2.29.4 left intact +-no body in request- +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/auth/client-certs/ingress.yaml b/examples/auth/client-certs/ingress.yaml
new file mode 100644
index 000000000..0d0ccd0c0
--- /dev/null
+++ b/examples/auth/client-certs/ingress.yaml
@@ -0,0 +1,30 @@
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+ annotations:
+ # Enable client certificate authentication
+ nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
+ # Create the secret containing the trusted ca certificates with `kubectl create secret generic auth-tls-chain --from-file=ca.crt --namespace=default`
+ nginx.ingress.kubernetes.io/auth-tls-secret: "default/auth-tls-chain"
+ # Specify the verification depth in the client certificates chain
+ nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
+ # Specify an error page to be redirected to on verification errors
+ nginx.ingress.kubernetes.io/auth-tls-error-page: "http://www.mysite.com/error-cert.html"
+ # Specify if certificates are be passed to upstream server
+ nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "false"
+ name: nginx-test
+ namespace: default
+spec:
+ rules:
+ - host: ingress.test.com
+ http:
+ paths:
+ - backend:
+ serviceName: http-svc:80
+ servicePort: 80
+ path: /
+ tls:
+ - hosts:
+ - ingress.test.com
+ secretName: tls-secret
+
diff --git a/examples/auth/external-auth/README/index.html b/examples/auth/external-auth/README/index.html
new file mode 100644
index 000000000..ac0da34c9
--- /dev/null
+++ b/examples/auth/external-auth/README/index.html
@@ -0,0 +1,1292 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Client Certificate Authentication¶
+It is possible to enable Client Certificate Authentication using additional annotations in the Ingress.
+Setup instructions¶
+-
+
-
+
Create a file named
+ca.crtcontaining the trusted certificate authority chain (all ca certificates in PEM format) to verify client certificates.
+ -
+
Create a secret from this file: +
+kubectl create secret generic auth-tls-chain --from-file=ca.crt --namespace=default
+ -
+
Add the annotations as provided in the ingress.yaml example to your ingress object.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/auth/external-auth/ingress.yaml b/examples/auth/external-auth/ingress.yaml
new file mode 100644
index 000000000..4cec37653
--- /dev/null
+++ b/examples/auth/external-auth/ingress.yaml
@@ -0,0 +1,15 @@
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+ annotations:
+ nginx.ingress.kubernetes.io/auth-url: "https://httpbin.org/basic-auth/user/passwd"
+ name: external-auth
+spec:
+ rules:
+ - host: external-auth-01.sample.com
+ http:
+ paths:
+ - backend:
+ serviceName: http-svc
+ servicePort: 80
+ path: /
\ No newline at end of file
diff --git a/examples/customization/configuration-snippets/README/index.html b/examples/customization/configuration-snippets/README/index.html
new file mode 100644
index 000000000..003f647d2
--- /dev/null
+++ b/examples/customization/configuration-snippets/README/index.html
@@ -0,0 +1,1170 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ External authentication¶
+Example 1:¶
+Use an external service (Basic Auth) located in https://httpbin.org
$ kubectl create -f ingress.yaml +ingress "external-auth" created + +$ kubectl get ing external-auth +NAME HOSTS ADDRESS PORTS AGE +external-auth external-auth-01.sample.com 172.17.4.99 80 13s + +$ kubectl get ing external-auth -o yaml +apiVersion: extensions/v1beta1 +kind: Ingress +metadata: + annotations: + nginx.ingress.kubernetes.io/auth-url: https://httpbin.org/basic-auth/user/passwd + creationTimestamp: 2016-10-03T13:50:35Z + generation: 1 + name: external-auth + namespace: default + resourceVersion: "2068378" + selfLink: /apis/extensions/v1beta1/namespaces/default/ingresses/external-auth + uid: 5c388f1d-8970-11e6-9004-080027d2dc94 +spec: + rules: + - host: external-auth-01.sample.com + http: + paths: + - backend: + serviceName: http-svc + servicePort: 80 + path: / +status: + loadBalancer: + ingress: + - ip: 172.17.4.99 +$ +
Test 1: no username/password (expect code 401)
+$ curl -k http://172.17.4.99 -v -H 'Host: external-auth-01.sample.com' +* Rebuilt URL to: http://172.17.4.99/ +* Trying 172.17.4.99... +* Connected to 172.17.4.99 (172.17.4.99) port 80 (#0) +> GET / HTTP/1.1 +> Host: external-auth-01.sample.com +> User-Agent: curl/7.50.1 +> Accept: */* +> +< HTTP/1.1 401 Unauthorized +< Server: nginx/1.11.3 +< Date: Mon, 03 Oct 2016 14:52:08 GMT +< Content-Type: text/html +< Content-Length: 195 +< Connection: keep-alive +< WWW-Authenticate: Basic realm="Fake Realm" +< +<html> +<head><title>401 Authorization Required</title></head> +<body bgcolor="white"> +<center><h1>401 Authorization Required</h1></center> +<hr><center>nginx/1.11.3</center> +</body> +</html> +* Connection #0 to host 172.17.4.99 left intact +
Test 2: valid username/password (expect code 200)
+$ curl -k http://172.17.4.99 -v -H 'Host: external-auth-01.sample.com' -u 'user:passwd' +* 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) +* Server auth using Basic with user 'user' +> GET / HTTP/1.1 +> Host: external-auth-01.sample.com +> Authorization: Basic dXNlcjpwYXNzd2Q= +> User-Agent: curl/7.50.1 +> Accept: */* +> +< HTTP/1.1 200 OK +< Server: nginx/1.11.3 +< Date: Mon, 03 Oct 2016 14:52:50 GMT +< Content-Type: text/plain +< Transfer-Encoding: chunked +< Connection: keep-alive +< +CLIENT VALUES: +client_address=10.2.60.2 +command=GET +real path=/ +query=nil +request_version=1.1 +request_uri=http://external-auth-01.sample.com:8080/ + +SERVER VALUES: +server_version=nginx: 1.9.11 - lua: 10001 + +HEADERS RECEIVED: +accept=*/* +authorization=Basic dXNlcjpwYXNzd2Q= +connection=close +host=external-auth-01.sample.com +user-agent=curl/7.50.1 +x-forwarded-for=10.2.60.1 +x-forwarded-host=external-auth-01.sample.com +x-forwarded-port=80 +x-forwarded-proto=http +x-real-ip=10.2.60.1 +BODY: +* Connection #0 to host 172.17.4.99 left intact +-no body in request- +
Test 3: invalid username/password (expect code 401)
+curl -k http://172.17.4.99 -v -H 'Host: external-auth-01.sample.com' -u 'user:user' +* 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) +* Server auth using Basic with user 'user' +> GET / HTTP/1.1 +> Host: external-auth-01.sample.com +> Authorization: Basic dXNlcjp1c2Vy +> User-Agent: curl/7.50.1 +> Accept: */* +> +< HTTP/1.1 401 Unauthorized +< Server: nginx/1.11.3 +< Date: Mon, 03 Oct 2016 14:53:04 GMT +< Content-Type: text/html +< Content-Length: 195 +< Connection: keep-alive +* Authentication problem. Ignoring this. +< WWW-Authenticate: Basic realm="Fake Realm" +< +<html> +<head><title>401 Authorization Required</title></head> +<body bgcolor="white"> +<center><h1>401 Authorization Required</h1></center> +<hr><center>nginx/1.11.3</center> +</body> +</html> +* Connection #0 to host 172.17.4.99 left intact +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/customization/configuration-snippets/ingress.yaml b/examples/customization/configuration-snippets/ingress.yaml
new file mode 100644
index 000000000..87ce21db2
--- /dev/null
+++ b/examples/customization/configuration-snippets/ingress.yaml
@@ -0,0 +1,17 @@
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+ name: nginx-configuration-snippet
+ annotations:
+ nginx.ingress.kubernetes.io/configuration-snippet: |
+ more_set_headers "Request-Id: $req_id";
+
+spec:
+ rules:
+ - host: custom.configuration.com
+ http:
+ paths:
+ - backend:
+ serviceName: http-svc
+ servicePort: 80
+ path: /
diff --git a/examples/customization/custom-configuration/README/index.html b/examples/customization/custom-configuration/README/index.html
new file mode 100644
index 000000000..a1f7bc2cc
--- /dev/null
+++ b/examples/customization/custom-configuration/README/index.html
@@ -0,0 +1,1122 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Configuration Snippets¶
+Ingress¶
+The Ingress in this example adds a custom header to Nginx configuration that only applies to that specific Ingress. If you want to add headers that apply globally to all Ingresses, please have a look at this example.
+$ kubectl apply -f ingress.yaml
+Test¶
+Check if the contents of the annotation are present in the nginx.conf file using:
+kubectl exec nginx-ingress-controller-873061567-4n3k2 -n kube-system cat /etc/nginx/nginx.conf
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/customization/custom-configuration/configmap.yaml b/examples/customization/custom-configuration/configmap.yaml
new file mode 100644
index 000000000..b5b5c02fd
--- /dev/null
+++ b/examples/customization/custom-configuration/configmap.yaml
@@ -0,0 +1,11 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+ name: nginx-configuration
+ namespace: ingress-nginx
+ labels:
+ app: ingress-nginx
+data:
+ proxy-connect-timeout: "10"
+ proxy-read-timeout: "120"
+ proxy-send-timeout: "120"
diff --git a/examples/customization/custom-errors/README/index.html b/examples/customization/custom-errors/README/index.html
new file mode 100644
index 000000000..ce3175fde
--- /dev/null
+++ b/examples/customization/custom-errors/README/index.html
@@ -0,0 +1,1175 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Custom Configuration¶
+Using a ConfigMap is possible to customize the NGINX configuration
+For example, if we want to change the timeouts we need to create a ConfigMap:
+$ cat configmap.yaml +apiVersion: v1 +data: + proxy-connect-timeout: "10" + proxy-read-timeout: "120" + proxy-send-timeout: "120" +kind: ConfigMap +metadata: + name: nginx-load-balancer-conf +
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/customization/custom-configuration/configmap.yaml \ + | kubectl apply -f - +
If the Configmap it is updated, NGINX will be reloaded with the new configuration.
+ + + + + + + + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/customization/custom-errors/custom-default-backend.yaml b/examples/customization/custom-errors/custom-default-backend.yaml
new file mode 100644
index 000000000..fce7c0bcb
--- /dev/null
+++ b/examples/customization/custom-errors/custom-default-backend.yaml
@@ -0,0 +1,31 @@
+apiVersion: v1
+kind: Service
+metadata:
+ name: nginx-errors
+ labels:
+ app: nginx-errors
+spec:
+ ports:
+ - port: 80
+ targetPort: 80
+ protocol: TCP
+ name: http
+ selector:
+ app: nginx-errors
+---
+apiVersion: v1
+kind: ReplicationController
+metadata:
+ name: nginx-errors
+spec:
+ replicas: 1
+ template:
+ metadata:
+ labels:
+ app: nginx-errors
+ spec:
+ containers:
+ - name: nginx-errors
+ image: aledbf/nginx-error-server:0.1
+ ports:
+ - containerPort: 80
\ No newline at end of file
diff --git a/examples/customization/custom-errors/rc-custom-errors.yaml b/examples/customization/custom-errors/rc-custom-errors.yaml
new file mode 100644
index 000000000..c400e5fee
--- /dev/null
+++ b/examples/customization/custom-errors/rc-custom-errors.yaml
@@ -0,0 +1,51 @@
+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.13.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
diff --git a/examples/customization/custom-headers/README/index.html b/examples/customization/custom-headers/README/index.html
new file mode 100644
index 000000000..9c1b04818
--- /dev/null
+++ b/examples/customization/custom-headers/README/index.html
@@ -0,0 +1,1161 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Custom Errors¶
+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 +service "nginx-errors" created +replicationcontroller "nginx-errors" created +
$ kubectl get svc +NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE +echoheaders 10.3.0.7 nodes 80/TCP 23d +kubernetes 10.3.0.1 <none> 443/TCP 34d +nginx-errors 10.3.0.102 <none> 80/TCP 11s +
$ kubectl get rc +CONTROLLER REPLICAS AGE +echoheaders 1 19d +nginx-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/ +* 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: */* +> +< 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> + +* 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' +* 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: application/json +> +< HTTP/1.1 404 Not Found +< Server: nginx/1.10.0 +< Date: Wed, 04 May 2016 02:54:00 GMT +< Content-Type: text/html +< Transfer-Encoding: chunked +< Connection: keep-alive +< Vary: Accept-Encoding +< +{ "message": "The page you're looking for could not be found" } + +* Connection #0 to host 172.17.4.99 left intact +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/customization/custom-headers/configmap.yaml b/examples/customization/custom-headers/configmap.yaml
new file mode 100644
index 000000000..27fed44c8
--- /dev/null
+++ b/examples/customization/custom-headers/configmap.yaml
@@ -0,0 +1,9 @@
+apiVersion: v1
+data:
+ proxy-set-headers: "ingress-nginx/custom-headers"
+kind: ConfigMap
+metadata:
+ name: nginx-configuration
+ namespace: ingress-nginx
+ labels:
+ app: ingress-nginx
\ No newline at end of file
diff --git a/examples/customization/custom-headers/custom-headers.yaml b/examples/customization/custom-headers/custom-headers.yaml
new file mode 100644
index 000000000..dac9f6714
--- /dev/null
+++ b/examples/customization/custom-headers/custom-headers.yaml
@@ -0,0 +1,9 @@
+apiVersion: v1
+data:
+ X-Different-Name: "true"
+ X-Request-Start: t=${msec}
+ X-Using-Nginx-Controller: "true"
+kind: ConfigMap
+metadata:
+ name: custom-headers
+ namespace: ingress-nginx
diff --git a/examples/customization/custom-upstream-check/README/index.html b/examples/customization/custom-upstream-check/README/index.html
new file mode 100644
index 000000000..49d75f937
--- /dev/null
+++ b/examples/customization/custom-upstream-check/README/index.html
@@ -0,0 +1,1144 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Custom Headers¶
+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
+curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/customization/custom-headers/configmap.yaml \ + | kubectl apply -f - + +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/customization/custom-headers/custom-headers.yaml \ + | kubectl apply -f - +
Test¶
+Check the contents of the configmap is present in the nginx.conf file using:
+kubectl exec nginx-ingress-controller-873061567-4n3k2 -n kube-system cat /etc/nginx/nginx.conf
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/customization/custom-upstream-check/custom-upstream.png b/examples/customization/custom-upstream-check/custom-upstream.png
new file mode 100644
index 000000000..30417894b
Binary files /dev/null and b/examples/customization/custom-upstream-check/custom-upstream.png differ
diff --git a/examples/customization/custom-vts-metrics-prometheus/README/index.html b/examples/customization/custom-vts-metrics-prometheus/README/index.html
new file mode 100644
index 000000000..803b23924
--- /dev/null
+++ b/examples/customization/custom-vts-metrics-prometheus/README/index.html
@@ -0,0 +1,1352 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Custom Upstream server checks¶
+This example shows how is possible to create a custom configuration for a particular upstream associated with an Ingress rule.
+echo " +apiVersion: extensions/v1beta1 +kind: Ingress +metadata: + name: http-svc + annotations: + nginx.ingress.kubernetes.io/upstream-fail-timeout: "30" +spec: + rules: + - host: foo.bar.com + http: + paths: + - path: / + backend: + serviceName: http-svc + servicePort: 80 +" | kubectl create -f - +
Check the annotation is present in the Ingress rule:
+kubectl get ingress http-svc -o yaml +
Check the NGINX configuration is updated using kubectl or the status page:
+$ kubectl exec nginx-ingress-controller-v1ppm cat /etc/nginx/nginx.conf
+.... + upstream default-http-svc-x-80 { + least_conn; + server 10.2.92.2:8080 max_fails=5 fail_timeout=30; + + } +.... +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/customization/custom-vts-metrics-prometheus/imgs/prometheus-filter-key-path.png b/examples/customization/custom-vts-metrics-prometheus/imgs/prometheus-filter-key-path.png
new file mode 100644
index 000000000..a266d4048
Binary files /dev/null and b/examples/customization/custom-vts-metrics-prometheus/imgs/prometheus-filter-key-path.png differ
diff --git a/examples/customization/custom-vts-metrics-prometheus/imgs/vts-dashboard-filter-key-path.png b/examples/customization/custom-vts-metrics-prometheus/imgs/vts-dashboard-filter-key-path.png
new file mode 100644
index 000000000..b9b3238f6
Binary files /dev/null and b/examples/customization/custom-vts-metrics-prometheus/imgs/vts-dashboard-filter-key-path.png differ
diff --git a/examples/customization/custom-vts-metrics-prometheus/imgs/vts-dashboard.png b/examples/customization/custom-vts-metrics-prometheus/imgs/vts-dashboard.png
new file mode 100644
index 000000000..0370f5ce9
Binary files /dev/null and b/examples/customization/custom-vts-metrics-prometheus/imgs/vts-dashboard.png differ
diff --git a/examples/customization/custom-vts-metrics-prometheus/nginx-vts-metrics-conf.yaml b/examples/customization/custom-vts-metrics-prometheus/nginx-vts-metrics-conf.yaml
new file mode 100644
index 000000000..6a6e795cd
--- /dev/null
+++ b/examples/customization/custom-vts-metrics-prometheus/nginx-vts-metrics-conf.yaml
@@ -0,0 +1,9 @@
+apiVersion: v1
+data:
+ enable-vts-status: "true"
+kind: ConfigMap
+metadata:
+ name: nginx-configuration
+ namespace: ingress-nginx
+ labels:
+ app: ingress-nginx
diff --git a/examples/customization/external-auth-headers/Makefile b/examples/customization/external-auth-headers/Makefile
new file mode 100644
index 000000000..1ee7e06ac
--- /dev/null
+++ b/examples/customization/external-auth-headers/Makefile
@@ -0,0 +1,23 @@
+all: push
+
+TAG=0.1
+PREFIX?=electroma/ingress-demo-
+ARCH?=amd64
+GOLANG_VERSION=1.9
+TEMP_DIR:=$(shell mktemp -d)
+
+build: clean
+ CGO_ENABLED=0 GOOS=linux GOARCH=$(ARCH) go build -o authsvc/authsvc authsvc/authsvc.go
+ CGO_ENABLED=0 GOOS=linux GOARCH=$(ARCH) go build -o echosvc/echosvc echosvc/echosvc.go
+
+container: build
+ docker build --pull -t $(PREFIX)authsvc-$(ARCH):$(TAG) authsvc
+ docker build --pull -t $(PREFIX)echosvc-$(ARCH):$(TAG) echosvc
+
+push: container
+ docker push $(PREFIX)authsvc-$(ARCH):$(TAG)
+ docker push $(PREFIX)echosvc-$(ARCH):$(TAG)
+
+clean:
+ rm -f authsvc/authsvc echosvc/echosvc
+
diff --git a/examples/customization/external-auth-headers/README/index.html b/examples/customization/external-auth-headers/README/index.html
new file mode 100644
index 000000000..8f815ec84
--- /dev/null
+++ b/examples/customization/external-auth-headers/README/index.html
@@ -0,0 +1,1232 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Deploying the Nginx Ingress controller¶
+This example aims to demonstrate the deployment of an nginx ingress controller and use a ConfigMap to enable nginx vts module to export metrics in prometheus format.
+vts-metrics¶
+Vts-metrics export NGINX metrics. To deploy all the files simply run kubectl apply -f nginx. A deployment and service will be
+created which already has a prometheus.io/scrape: 'true' annotation and if you added
+the recommended Prometheus service-endpoint scraping configuration,
+Prometheus will scrape it automatically and you start using the generated metrics right away.
Custom configuration¶
+apiVersion: v1 +data: + enable-vts-status: "true" +kind: ConfigMap +metadata: + name: nginx-configuration + namespace: ingress-nginx + labels: + app: ingress-nginx +
$ kubectl apply -f nginx-vts-metrics-conf.yaml
+Result¶
+Check whether the ingress controller successfully generated the NGINX vts status:
+$ kubectl exec nginx-ingress-controller-873061567-4n3k2 -n ingress-nginx cat /etc/nginx/nginx.conf|grep vhost_traffic_status_display + vhost_traffic_status_display; + vhost_traffic_status_display_format html; +
NGINX vts dashboard¶
+The vts dashboard provides real time metrics.
+
Because the vts port it's not yet exposed, you should forward the controller port to see it.
+$ kubectl port-forward $(kubectl get pods --selector=k8s-app=nginx-ingress-controller -n ingress-nginx --output=jsonpath={.items..metadata.name}) -n ingress-nginx 18080 +
Now open the url http://localhost:18080/nginx_status in your browser.
+Prometheus metrics output¶
+NGINX Ingress controller already has a parser to convert vts metrics to Prometheus format. It exports prometheus metrics to the address :10254/metrics.
$ kubectl exec -ti -n ingress-nginx $(kubectl get pods --selector=k8s-app=nginx-ingress-controller -n kube-system --output=jsonpath={.items..metadata.name}) curl localhost:10254/metrics +ingress_controller_ssl_expire_time_seconds{host="foo.bar.com"} -6.21355968e+10 +# HELP ingress_controller_success Cumulative number of Ingress controller reload operations +# TYPE ingress_controller_success counter +ingress_controller_success{count="reloads"} 3 +# HELP nginx_bytes_total Nginx bytes count +# TYPE nginx_bytes_total counter +nginx_bytes_total{direction="in",ingress_class="nginx",namespace="",server_zone="*"} 3708 +nginx_bytes_total{direction="in",ingress_class="nginx",namespace="",server_zone="_"} 3708 +nginx_bytes_total{direction="out",ingress_class="nginx",namespace="",server_zone="*"} 5256 +nginx_bytes_total{direction="out",ingress_class="nginx",namespace="",server_zone="_"} 5256 +
Customize metrics¶
+The default vts vhost key is $geoip_country_code country::* that expose metrics grouped by server and country code. The example below show how to have metrics grouped by server and server path.
NGINX custom configuration ( http level )¶
+apiVersion: v1 + kind: ConfigMap + data: + enable-vts-status: "true" + vts-default-filter-key: "$server_name" +... +
Customize ingress¶
+apiVersion: extensions/v1beta1 + kind: Ingress + metadata: + annotations: + nginx.ingress.kubernetes.io/vts-filter-key: $uri $server_name + name: ingress +
Result¶
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/customization/external-auth-headers/authsvc/Dockerfile b/examples/customization/external-auth-headers/authsvc/Dockerfile
new file mode 100644
index 000000000..318eab4e8
--- /dev/null
+++ b/examples/customization/external-auth-headers/authsvc/Dockerfile
@@ -0,0 +1,5 @@
+FROM alpine:3.5
+MAINTAINER Roman Safronov
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ External authentication, authentication service response headers propagation¶
+This example demonstrates propagation of selected authentication service response headers +to backend service.
+Sample configuration includes:
+-
+
- Sample authentication service producing several response headers +
- Authentication logic is based on HTTP header: requests with header
Usercontaining stringinternalare considered authenticated
+ - After successful authentication service generates response headers
UserIDandUserRole
+ - Sample echo service displaying header information +
- Two ingress objects pointing to echo service +
- Public, which allows access from unauthenticated users +
- Private, which allows access from authenticated users only +
You can deploy the controller as +follows:
+$ kubectl create -f deploy/ +deployment "demo-auth-service" created +service "demo-auth-service" created +ingress "demo-auth-service" created +deployment "demo-echo-service" created +service "demo-echo-service" created +ingress "public-demo-echo-service" created +ingress "secure-demo-echo-service" created + +$ kubectl get po +NAME READY STATUS RESTARTS AGE +NAME READY STATUS RESTARTS AGE +demo-auth-service-2769076528-7g9mh 1/1 Running 0 30s +demo-echo-service-3636052215-3vw8c 1/1 Running 0 29s + +kubectl get ing +NAME HOSTS ADDRESS PORTS AGE +public-demo-echo-service public-demo-echo-service.kube.local 80 1m +secure-demo-echo-service secure-demo-echo-service.kube.local 80 1m +
Test 1: public service with no auth header
+$ curl -H 'Host: public-demo-echo-service.kube.local' -v 192.168.99.100 +* Rebuilt URL to: 192.168.99.100/ +* Trying 192.168.99.100... +* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0) +> GET / HTTP/1.1 +> Host: public-demo-echo-service.kube.local +> User-Agent: curl/7.43.0 +> Accept: */* +> +< HTTP/1.1 200 OK +< Server: nginx/1.11.10 +< Date: Mon, 13 Mar 2017 20:19:21 GMT +< Content-Type: text/plain; charset=utf-8 +< Content-Length: 20 +< Connection: keep-alive +< +* Connection #0 to host 192.168.99.100 left intact +UserID: , UserRole: +
Test 2: secure service with no auth header
+$ curl -H 'Host: secure-demo-echo-service.kube.local' -v 192.168.99.100 +* Rebuilt URL to: 192.168.99.100/ +* Trying 192.168.99.100... +* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0) +> GET / HTTP/1.1 +> Host: secure-demo-echo-service.kube.local +> User-Agent: curl/7.43.0 +> Accept: */* +> +< HTTP/1.1 403 Forbidden +< Server: nginx/1.11.10 +< Date: Mon, 13 Mar 2017 20:18:48 GMT +< Content-Type: text/html +< Content-Length: 170 +< Connection: keep-alive +< +<html> +<head><title>403 Forbidden</title></head> +<body bgcolor="white"> +<center><h1>403 Forbidden</h1></center> +<hr><center>nginx/1.11.10</center> +</body> +</html> +* Connection #0 to host 192.168.99.100 left intact +
Test 3: public service with valid auth header
+$ curl -H 'Host: public-demo-echo-service.kube.local' -H 'User:internal' -v 192.168.99.100 +* Rebuilt URL to: 192.168.99.100/ +* Trying 192.168.99.100... +* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0) +> GET / HTTP/1.1 +> Host: public-demo-echo-service.kube.local +> User-Agent: curl/7.43.0 +> Accept: */* +> User:internal +> +< HTTP/1.1 200 OK +< Server: nginx/1.11.10 +< Date: Mon, 13 Mar 2017 20:19:59 GMT +< Content-Type: text/plain; charset=utf-8 +< Content-Length: 44 +< Connection: keep-alive +< +* Connection #0 to host 192.168.99.100 left intact +UserID: 1443635317331776148, UserRole: admin +
Test 4: public service with valid auth header
+$ curl -H 'Host: secure-demo-echo-service.kube.local' -H 'User:internal' -v 192.168.99.100 +* Rebuilt URL to: 192.168.99.100/ +* Trying 192.168.99.100... +* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0) +> GET / HTTP/1.1 +> Host: secure-demo-echo-service.kube.local +> User-Agent: curl/7.43.0 +> Accept: */* +> User:internal +> +< HTTP/1.1 200 OK +< Server: nginx/1.11.10 +< Date: Mon, 13 Mar 2017 20:17:23 GMT +< Content-Type: text/plain; charset=utf-8 +< Content-Length: 43 +< Connection: keep-alive +< +* Connection #0 to host 192.168.99.100 left intact +UserID: 605394647632969758, UserRole: admin +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/customization/ssl-dh-param/configmap.yaml b/examples/customization/ssl-dh-param/configmap.yaml
new file mode 100644
index 000000000..71dd2903c
--- /dev/null
+++ b/examples/customization/ssl-dh-param/configmap.yaml
@@ -0,0 +1,9 @@
+apiVersion: v1
+data:
+ ssl-dh-param: "ingress-nginx/lb-dhparam"
+kind: ConfigMap
+metadata:
+ name: nginx-configuration
+ namespace: ingress-nginx
+ labels:
+ app: ingress-nginx
diff --git a/examples/customization/ssl-dh-param/ssl-dh-param.yaml b/examples/customization/ssl-dh-param/ssl-dh-param.yaml
new file mode 100644
index 000000000..ba260b153
--- /dev/null
+++ b/examples/customization/ssl-dh-param/ssl-dh-param.yaml
@@ -0,0 +1,8 @@
+apiVersion: v1
+data:
+ dhparam.pem: "...base64 encoded data..."
+kind: Secret
+type: Opaque
+metadata:
+ name: lb-dhparam
+ namespace: ingress-nginx
diff --git a/examples/customization/sysctl/README/index.html b/examples/customization/sysctl/README/index.html
new file mode 100644
index 000000000..fe64fdecd
--- /dev/null
+++ b/examples/customization/sysctl/README/index.html
@@ -0,0 +1,1106 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Deploying the Nginx Ingress controller¶
+This example aims to demonstrate the deployment of an nginx ingress controller and +use a ConfigMap to configure custom Diffie-Hellman parameters file to help with +"Perfect Forward Secrecy".
+Custom configuration¶
+$ cat configmap.yaml +apiVersion: v1 +data: + ssl-dh-param: "ingress-nginx/lb-dhparam" +kind: ConfigMap +metadata: + name: nginx-configuration + namespace: ingress-nginx + labels: + app: ingress-nginx +
$ kubectl create -f configmap.yaml
+Custom DH parameters secret¶
+$> openssl dhparam 1024 2> /dev/null | base64 +LS0tLS1CRUdJTiBESCBQQVJBTUVURVJ... +
$ cat ssl-dh-param.yaml +apiVersion: v1 +data: + dhparam.pem: "LS0tLS1CRUdJTiBESCBQQVJBTUVURVJ..." +kind: ConfigMap +metadata: + name: nginx-configuration + namespace: ingress-nginx + labels: + app: ingress-nginx +
$ kubectl create -f ssl-dh-param.yaml
+Test¶
+Check the contents of the configmap is present in the nginx.conf file using:
+kubectl exec nginx-ingress-controller-873061567-4n3k2 -n kube-system cat /etc/nginx/nginx.conf
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/customization/sysctl/patch.json b/examples/customization/sysctl/patch.json
new file mode 100644
index 000000000..56482f511
--- /dev/null
+++ b/examples/customization/sysctl/patch.json
@@ -0,0 +1,16 @@
+{
+ "spec": {
+ "template": {
+ "spec": {
+ "initContainers": [{
+ "name": "sysctl",
+ "image": "alpine:3.6",
+ "securityContext": {
+ "privileged": true
+ },
+ "command": ["sh", "-c", "sysctl -w net.core.somaxconn=32768; sysctl -w net.ipv4.ip_local_port_range=1024 65535"]
+ }]
+ }
+ }
+ }
+}
\ No newline at end of file
diff --git a/examples/docker-registry/README/index.html b/examples/docker-registry/README/index.html
new file mode 100644
index 000000000..5c62a5ad1
--- /dev/null
+++ b/examples/docker-registry/README/index.html
@@ -0,0 +1,1233 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/docker-registry/deployment.yaml b/examples/docker-registry/deployment.yaml
new file mode 100644
index 000000000..c9044b488
--- /dev/null
+++ b/examples/docker-registry/deployment.yaml
@@ -0,0 +1,56 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+ name: docker-registry
+
+---
+
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+ name: docker-registry
+ namespace: docker-registry
+spec:
+ replicas: 1
+ selector:
+ matchLabels:
+ app: docker-registry
+ template:
+ metadata:
+ labels:
+ app: docker-registry
+ spec:
+ containers:
+ - name: docker-registry
+ image: registry:2.6.2
+ env:
+ - name: REGISTRY_HTTP_ADDR
+ value: ":5000"
+ - name: REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY
+ value: "/var/lib/registry"
+ ports:
+ - name: http
+ containerPort: 5000
+ volumeMounts:
+ - name: image-store
+ mountPath: "/var/lib/registry"
+ volumes:
+ - name: image-store
+ emptyDir: {}
+
+---
+
+kind: Service
+apiVersion: v1
+metadata:
+ name: docker-registry
+ namespace: docker-registry
+ labels:
+ app: docker-registry
+spec:
+ selector:
+ app: docker-registry
+ ports:
+ - name: http
+ port: 5000
+ targetPort: 5000
diff --git a/examples/docker-registry/ingress-with-tls.yaml b/examples/docker-registry/ingress-with-tls.yaml
new file mode 100644
index 000000000..817d3d85f
--- /dev/null
+++ b/examples/docker-registry/ingress-with-tls.yaml
@@ -0,0 +1,23 @@
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+ annotations:
+ nginx.ingress.kubernetes.io/proxy-body-size: "0"
+ nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
+ nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
+ kubernetes.io/tls-acme: 'true'
+ name: docker-registry
+ namespace: docker-registry
+spec:
+ tls:
+ - hosts:
+ - registry.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Docker registry¶
+This example demonstrates how to deploy a docker registry in the cluster and configure Ingress enable access from Internet
+Deployment¶
+First we deploy the docker registry in the cluster:
+kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/docker-registry/deployment.yaml
+Important: DO NOT RUN THIS IN PRODUCTION.
+This deployment uses emptyDir in the volumeMount which means the contents of the registry will be deleted when the pod dies.
The next required step is creation of the ingress rules. To do this we have two options: with and without TLS
+Without TLS¶
+Download and edit the yaml deployment replacing registry.<your domain> with a valid DNS name pointing to the ingress controller:
wget https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/docker-registry/ingress-without-tls.yaml
+Important: running a docker registry without TLS requires we configure our local docker daemon with the insecure registry flag. +Please check deploy a plain http registry
+With TLS¶
+Download and edit the yaml deployment replacing registry.<your domain> with a valid DNS name pointing to the ingress controller:
wget https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/docker-registry/ingress-with-tls.yaml
+Deploy kube lego use Let's Encrypt certificates or edit the ingress rule to use a secret with an existing SSL certificate.
+Testing¶
+To test the registry is working correctly we download a known image from docker hub, create a tag pointing to the new registry and upload the image:
+docker pull ubuntu:16.04 +docker tag ubuntu:16.04 `registry.<your domain>/ubuntu:16.04` +docker push `registry.<your domain>/ubuntu:16.04` +
Please replace registry.<your domain> with your domain.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/external-auth/dashboard-ingress.yaml b/examples/external-auth/dashboard-ingress.yaml
new file mode 100644
index 000000000..3980a76a0
--- /dev/null
+++ b/examples/external-auth/dashboard-ingress.yaml
@@ -0,0 +1,38 @@
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+ annotations:
+ nginx.ingress.kubernetes.io/auth-signin: https://$host/oauth2/start
+ nginx.ingress.kubernetes.io/auth-url: https://$host/oauth2/auth
+ name: external-auth-oauth2
+ namespace: kube-system
+spec:
+ rules:
+ - host: __INGRESS_HOST__
+ http:
+ paths:
+ - backend:
+ serviceName: kubernetes-dashboard
+ servicePort: 80
+ path: /
+
+---
+
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+ name: oauth2-proxy
+ namespace: kube-system
+spec:
+ rules:
+ - host: __INGRESS_HOST__
+ http:
+ paths:
+ - backend:
+ serviceName: oauth2-proxy
+ servicePort: 4180
+ path: /oauth2
+ tls:
+ - hosts:
+ - __INGRESS_HOST__
+ secretName: __INGRESS_SECRET__
diff --git a/examples/external-auth/images/dashboard.png b/examples/external-auth/images/dashboard.png
new file mode 100644
index 000000000..3acb7bb11
Binary files /dev/null and b/examples/external-auth/images/dashboard.png differ
diff --git a/examples/external-auth/images/github-auth.png b/examples/external-auth/images/github-auth.png
new file mode 100644
index 000000000..a7ee97d7e
Binary files /dev/null and b/examples/external-auth/images/github-auth.png differ
diff --git a/examples/external-auth/images/oauth-login.png b/examples/external-auth/images/oauth-login.png
new file mode 100644
index 000000000..c8f7f8b17
Binary files /dev/null and b/examples/external-auth/images/oauth-login.png differ
diff --git a/examples/external-auth/images/register-oauth-app-2.png b/examples/external-auth/images/register-oauth-app-2.png
new file mode 100644
index 000000000..ef69149bb
Binary files /dev/null and b/examples/external-auth/images/register-oauth-app-2.png differ
diff --git a/examples/external-auth/images/register-oauth-app.png b/examples/external-auth/images/register-oauth-app.png
new file mode 100644
index 000000000..9d6baa87e
Binary files /dev/null and b/examples/external-auth/images/register-oauth-app.png differ
diff --git a/examples/external-auth/oauth2-proxy.yaml b/examples/external-auth/oauth2-proxy.yaml
new file mode 100644
index 000000000..ed367b563
--- /dev/null
+++ b/examples/external-auth/oauth2-proxy.yaml
@@ -0,0 +1,57 @@
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+ labels:
+ k8s-app: oauth2-proxy
+ name: oauth2-proxy
+ namespace: kube-system
+spec:
+ replicas: 1
+ selector:
+ matchLabels:
+ k8s-app: oauth2-proxy
+ template:
+ metadata:
+ labels:
+ k8s-app: oauth2-proxy
+ spec:
+ containers:
+ - args:
+ - --provider=github
+ - --email-domain=*
+ - --upstream=file:///dev/null
+ - --http-address=0.0.0.0:4180
+ # Register a new application
+ # https://github.com/settings/applications/new
+ env:
+ - name: OAUTH2_PROXY_CLIENT_ID
+ value:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ External Authentication¶
+Overview¶
+The auth-url and auth-signin annotations allow you to use an external
+authentication provider to protect your Ingress resources.
(Note, this annotation requires nginx-ingress-controller v0.9.0 or greater.)
Key Detail¶
+This functionality is enabled by deploying multiple Ingress objects for a single host. +One Ingress object has no special annotations and handles authentication.
+Other Ingress objects can then be annotated in such a way that require the user to
+authenticate against the first Ingress's endpoint, and can redirect 401s to the
+same endpoint.
Sample:
+... +metadata: + name: application + annotations: + "nginx.ingress.kubernetes.io/auth-url": "https://$host/oauth2/auth" + "nginx.ingress.kubernetes.io/auth-signin": "https://$host/oauth2/sign_in" +... +
Example: OAuth2 Proxy + Kubernetes-Dashboard¶
+This example will show you how to deploy oauth2_proxy
+into a Kubernetes cluster and use it to protect the Kubernetes Dashboard using github as oAuth2 provider
Prepare¶
+-
+
- Install the kubernetes dashboard +
kubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.5.0.yaml
+-
+
- Create a custom Github OAuth application https://github.com/settings/applications/new +
-
+
- Homepage URL is the FQDN in the Ingress rule, like
https://foo.bar.com
+ - Authorization callback URL is the same as the base FQDN plus
/oauth2, likehttps://foo.bar.com/oauth2
+
-
+
-
+
Configure oauth2_proxy values in the file oauth2-proxy.yaml with the values:
+
+ -
+
OAUTH2_PROXY_CLIENT_ID with the github
+<Client ID>
+ - OAUTH2_PROXY_CLIENT_SECRET with the github
<Client Secret>
+ -
+
OAUTH2_PROXY_COOKIE_SECRET with value of
+python -c 'import os,base64; print base64.b64encode(os.urandom(16))'
+ -
+
Customize the contents of the file dashboard-ingress.yaml:
+
+
Replace __INGRESS_HOST__ with a valid FQDN and __INGRESS_SECRET__ with a Secret with a valid SSL certificate.
-
+
- Deploy the oauth2 proxy and the ingress rules running: +
$ kubectl create -f oauth2-proxy.yaml,dashboard-ingress.yaml
+Test the oauth integration accessing the configured URL, like https://foo.bar.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/multi-tls/multi-tls.yaml b/examples/multi-tls/multi-tls.yaml
new file mode 100644
index 000000000..f84ed1734
--- /dev/null
+++ b/examples/multi-tls/multi-tls.yaml
@@ -0,0 +1,116 @@
+apiVersion: v1
+kind: Service
+metadata:
+ name: nginx
+ labels:
+ app: nginx
+spec:
+ ports:
+ - port: 80
+ targetPort: 80
+ protocol: TCP
+ name: http
+ selector:
+ app: nginx
+---
+apiVersion: v1
+kind: ReplicationController
+metadata:
+ name: nginx
+spec:
+ replicas: 1
+ template:
+ metadata:
+ labels:
+ app: nginx
+ spec:
+ containers:
+ - name: nginx
+ image: gcr.io/google_containers/nginx
+ ports:
+ - containerPort: 80
+---
+apiVersion: v1
+kind: Service
+metadata:
+ name: http-svc
+ labels:
+ app: http-svc
+spec:
+ ports:
+ - port: 80
+ targetPort: 8080
+ protocol: TCP
+ name: http
+ selector:
+ app: http-svc
+---
+apiVersion: v1
+kind: ReplicationController
+metadata:
+ name: http-svc
+spec:
+ replicas: 1
+ template:
+ metadata:
+ labels:
+ app: http-svc
+ spec:
+ containers:
+ - name: http-svc
+ image: gcr.io/google_containers/echoserver:1.8
+ ports:
+ - containerPort: 8080
+ env:
+ - name: NODE_NAME
+ valueFrom:
+ fieldRef:
+ fieldPath: spec.nodeName
+ - name: POD_NAME
+ valueFrom:
+ fieldRef:
+ fieldPath: metadata.name
+ - name: POD_NAMESPACE
+ valueFrom:
+ fieldRef:
+ fieldPath: metadata.namespace
+ - name: POD_IP
+ valueFrom:
+ fieldRef:
+ fieldPath: status.podIP
+
+---
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+ name: foo-tls
+ namespace: default
+spec:
+ tls:
+ - hosts:
+ - foo.bar.com
+ # This secret must exist beforehand
+ # The cert must also contain the subj-name foo.bar.com
+ # https://github.com/kubernetes/ingress-nginx/blob/master/docs/examples/PREREQUISITES.md#tls-certificates
+ secretName: foobar
+ - hosts:
+ - bar.baz.com
+ # This secret must exist beforehand
+ # The cert must also contain the subj-name bar.baz.com
+ # https://github.com/kubernetes/ingress-nginx/blob/master/docs/examples/PREREQUISITES.md#tls-certificates
+ secretName: barbaz
+ rules:
+ - host: foo.bar.com
+ http:
+ paths:
+ - backend:
+ serviceName: http-svc
+ servicePort: 80
+ path: /
+ - host: bar.baz.com
+ http:
+ paths:
+ - backend:
+ serviceName: nginx
+ servicePort: 80
+ path: /
\ No newline at end of file
diff --git a/examples/rewrite/README/index.html b/examples/rewrite/README/index.html
new file mode 100644
index 000000000..a32689be7
--- /dev/null
+++ b/examples/rewrite/README/index.html
@@ -0,0 +1,1361 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Multi TLS certificate termination¶
+This example uses 2 different certificates to terminate SSL for 2 hostnames.
+-
+
- Deploy the controller by creating the rc in the parent dir +
- Create tls secrets for foo.bar.com and bar.baz.com as indicated in the yaml +
- Create multi-tls.yaml +
This should generate a segment like:
+$ kubectl exec -it nginx-ingress-controller-6vwd1 -- cat /etc/nginx/nginx.conf | grep "foo.bar.com" -B 7 -A 35 + server { + listen 80; + listen 443 ssl http2; + ssl_certificate /etc/nginx-ssl/default-foobar.pem; + ssl_certificate_key /etc/nginx-ssl/default-foobar.pem; + + + server_name foo.bar.com; + + + if ($scheme = http) { + return 301 https://$host$request_uri; + } + + + + location / { + proxy_set_header Host $host; + + # Pass Real IP + proxy_set_header X-Real-IP $remote_addr; + + # Allow websocket connections + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Host $host; + proxy_set_header X-Forwarded-Proto $pass_access_scheme; + + proxy_connect_timeout 5s; + proxy_send_timeout 60s; + proxy_read_timeout 60s; + + proxy_redirect off; + proxy_buffering off; + + proxy_http_version 1.1; + + proxy_pass http://default-http-svc-80; + } +
And you should be able to reach your nginx service or http-svc service using a hostname switch:
+$ kubectl get ing +NAME RULE BACKEND ADDRESS AGE +foo-tls - 104.154.30.67 13m + foo.bar.com + / http-svc:80 + bar.baz.com + / nginx:80 + +$ curl https://104.154.30.67 -H 'Host:foo.bar.com' -k +CLIENT VALUES: +client_address=10.245.0.6 +command=GET +real path=/ +query=nil +request_version=1.1 +request_uri=http://foo.bar.com:8080/ + +SERVER VALUES: +server_version=nginx: 1.9.11 - lua: 10001 + +HEADERS RECEIVED: +accept=*/* +connection=close +host=foo.bar.com +user-agent=curl/7.35.0 +x-forwarded-for=10.245.0.1 +x-forwarded-host=foo.bar.com +x-forwarded-proto=https + +$ curl https://104.154.30.67 -H 'Host:bar.baz.com' -k +<!DOCTYPE html> +<html> +<head> +<title>Welcome to nginx on Debian!</title> + +$ curl 104.154.30.67 +default backend - 404 +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/static-ip/README/index.html b/examples/static-ip/README/index.html
new file mode 100644
index 000000000..1f641c922
--- /dev/null
+++ b/examples/static-ip/README/index.html
@@ -0,0 +1,1300 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Rewrite¶
+This example demonstrates how to use the Rewrite annotations
+Prerequisites¶
+You will need to make sure your Ingress targets exactly one Ingress +controller by specifying the ingress.class annotation, +and that you have an ingress controller running in your cluster.
+Deployment¶
+Rewriting can be controlled using the following annotations:
+| Name | +Description | +Values | +
|---|---|---|
| nginx.ingress.kubernetes.io/rewrite-target | +Target URI where the traffic must be redirected | +string | +
| nginx.ingress.kubernetes.io/add-base-url | +indicates if is required to add a base tag in the head of the responses from the upstream servers | +bool | +
| nginx.ingress.kubernetes.io/base-url-scheme | +Override for the scheme passed to the base tag | +string | +
| nginx.ingress.kubernetes.io/ssl-redirect | +Indicates if the location section is accessible SSL only (defaults to True when Ingress contains a Certificate) | +bool | +
| nginx.ingress.kubernetes.io/force-ssl-redirect | +Forces the redirection to HTTPS even if the Ingress is not TLS Enabled | +bool | +
| nginx.ingress.kubernetes.io/app-root | +Defines the Application Root that the Controller must redirect if it's in '/' context | +string | +
Validation¶
+Rewrite Target¶
+Create an Ingress rule with a rewrite annotation:
+$ echo " +apiVersion: extensions/v1beta1 +kind: Ingress +metadata: + annotations: + nginx.ingress.kubernetes.io/rewrite-target: / + name: rewrite + namespace: default +spec: + rules: + - host: rewrite.bar.com + http: + paths: + - backend: + serviceName: http-svc + servicePort: 80 + path: /something +" | kubectl create -f - +
Check the rewrite is working
+$ curl -v http://172.17.4.99/something -H 'Host: rewrite.bar.com' +* Trying 172.17.4.99... +* Connected to 172.17.4.99 (172.17.4.99) port 80 (#0) +> GET /something HTTP/1.1 +> Host: rewrite.bar.com +> User-Agent: curl/7.43.0 +> Accept: */* +> +< HTTP/1.1 200 OK +< Server: nginx/1.11.0 +< Date: Tue, 31 May 2016 16:07:31 GMT +< Content-Type: text/plain +< Transfer-Encoding: chunked +< Connection: keep-alive +< +CLIENT VALUES: +client_address=10.2.56.9 +command=GET +real path=/ +query=nil +request_version=1.1 +request_uri=http://rewrite.bar.com:8080/ + +SERVER VALUES: +server_version=nginx: 1.9.11 - lua: 10001 + +HEADERS RECEIVED: +accept=*/* +connection=close +host=rewrite.bar.com +user-agent=curl/7.43.0 +x-forwarded-for=10.2.56.1 +x-forwarded-host=rewrite.bar.com +x-forwarded-port=80 +x-forwarded-proto=http +x-real-ip=10.2.56.1 +BODY: +* Connection #0 to host 172.17.4.99 left intact +-no body in request- +
App Root¶
+Create an Ingress rule with a app-root annotation:
+$ echo " +apiVersion: extensions/v1beta1 +kind: Ingress +metadata: + annotations: + nginx.ingress.kubernetes.io/app-root: /app1 + name: approot + namespace: default +spec: + rules: + - host: approot.bar.com + http: + paths: + - backend: + serviceName: http-svc + servicePort: 80 + path: / +" | kubectl create -f - +
Check the rewrite is working
+$ curl -I -k http://approot.bar.com/ +HTTP/1.1 302 Moved Temporarily +Server: nginx/1.11.10 +Date: Mon, 13 Mar 2017 14:57:15 GMT +Content-Type: text/html +Content-Length: 162 +Location: http://stickyingress.example.com/app1 +Connection: keep-alive +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/static-ip/nginx-ingress-controller.yaml b/examples/static-ip/nginx-ingress-controller.yaml
new file mode 100644
index 000000000..5b97148a3
--- /dev/null
+++ b/examples/static-ip/nginx-ingress-controller.yaml
@@ -0,0 +1,55 @@
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+ name: nginx-ingress-controller
+ labels:
+ k8s-app: nginx-ingress-controller
+spec:
+ replicas: 1
+ selector:
+ matchLabels:
+ k8s-app: nginx-ingress-controller
+ template:
+ metadata:
+ labels:
+ k8s-app: nginx-ingress-controller
+ spec:
+ # hostNetwork makes it possible to use ipv6 and to preserve the source IP correctly regardless of docker configuration
+ # however, it is not a hard dependency of the nginx-ingress-controller itself and it may cause issues if port 10254 already is taken on the host
+ # that said, since hostPort is broken on CNI (https://github.com/kubernetes/kubernetes/issues/31307) we have to use hostNetwork where CNI is used
+ # like with kubeadm
+ # hostNetwork: true
+ terminationGracePeriodSeconds: 60
+ containers:
+ - image: quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.13.0
+ name: nginx-ingress-controller
+ readinessProbe:
+ httpGet:
+ path: /healthz
+ port: 10254
+ scheme: HTTP
+ livenessProbe:
+ httpGet:
+ path: /healthz
+ port: 10254
+ scheme: HTTP
+ initialDelaySeconds: 10
+ timeoutSeconds: 1
+ ports:
+ - containerPort: 80
+ hostPort: 80
+ - containerPort: 443
+ hostPort: 443
+ env:
+ - name: POD_NAME
+ valueFrom:
+ fieldRef:
+ fieldPath: metadata.name
+ - name: POD_NAMESPACE
+ valueFrom:
+ fieldRef:
+ fieldPath: metadata.namespace
+ args:
+ - /nginx-ingress-controller
+ - --default-backend-service=$(POD_NAMESPACE)/default-http-backend
+ - --publish-service=$(POD_NAMESPACE)/nginx-ingress-lb
diff --git a/examples/static-ip/nginx-ingress.yaml b/examples/static-ip/nginx-ingress.yaml
new file mode 100644
index 000000000..1db6ee335
--- /dev/null
+++ b/examples/static-ip/nginx-ingress.yaml
@@ -0,0 +1,15 @@
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+ name: ingress-nginx
+spec:
+ tls:
+ # This assumes tls-secret exists.
+ - secretName: tls-secret
+ rules:
+ - http:
+ paths:
+ - backend:
+ # This assumes http-svc exists and routes to healthy endpoints.
+ serviceName: http-svc
+ servicePort: 80
diff --git a/examples/static-ip/static-ip-svc.yaml b/examples/static-ip/static-ip-svc.yaml
new file mode 100644
index 000000000..27de0690d
--- /dev/null
+++ b/examples/static-ip/static-ip-svc.yaml
@@ -0,0 +1,22 @@
+# This is the backend service
+apiVersion: v1
+kind: Service
+metadata:
+ name: nginx-ingress-lb
+ labels:
+ app: nginx-ingress-lb
+spec:
+ externalTrafficPolicy: Local
+ type: LoadBalancer
+ loadBalancerIP: 104.154.109.191
+ ports:
+ - port: 80
+ name: http
+ targetPort: 80
+ - port: 443
+ name: https
+ targetPort: 443
+ selector:
+ # Selects nginx-ingress-controller pods
+ k8s-app: nginx-ingress-controller
+
diff --git a/examples/tls-termination/README/index.html b/examples/tls-termination/README/index.html
new file mode 100644
index 000000000..3add061aa
--- /dev/null
+++ b/examples/tls-termination/README/index.html
@@ -0,0 +1,1233 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Static IPs¶
+This example demonstrates how to assign a static-ip to an Ingress on through the Nginx controller.
+Prerequisites¶
+You need a TLS cert and a test HTTP service for this example. +You will also need to make sure your Ingress targets exactly one Ingress +controller by specifying the ingress.class annotation, +and that you have an ingress controller running in your cluster.
+Acquiring an IP¶
+Since instances of the nginx controller actually run on nodes in your cluster, +by default nginx Ingresses will only get static IPs if your cloudprovider +supports static IP assignments to nodes. On GKE/GCE for example, even though +nodes get static IPs, the IPs are not retained across upgrade.
+To acquire a static IP for the nginx ingress controller, simply put it
+behind a Service of Type=LoadBalancer.
First, create a loadbalancer Service and wait for it to acquire an IP
+$ kubectl create -f static-ip-svc.yaml +service "nginx-ingress-lb" created + +$ kubectl get svc nginx-ingress-lb +NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE +nginx-ingress-lb 10.0.138.113 104.154.109.191 80:31457/TCP,443:32240/TCP 15m +
then, update the ingress controller so it adopts the static IP of the Service
+by passing the --publish-service flag (the example yaml used in the next step
+already has it set to "nginx-ingress-lb").
$ kubectl create -f nginx-ingress-controller.yaml +deployment "nginx-ingress-controller" created +
Assigning the IP to an Ingress¶
+From here on every Ingress created with the ingress.class annotation set to
+nginx will get the IP allocated in the previous step
$ kubectl create -f nginx-ingress.yaml +ingress "nginx-ingress" created + +$ kubectl get ing nginx-ingress +NAME HOSTS ADDRESS PORTS AGE +nginx-ingress * 104.154.109.191 80, 443 13m + +$ curl 104.154.109.191 -kL +CLIENT VALUES: +client_address=10.180.1.25 +command=GET +real path=/ +query=nil +request_version=1.1 +request_uri=http://104.154.109.191:8080/ +... +
Retaining the IP¶
+You can test retention by deleting the Ingress
+$ kubectl delete ing nginx-ingress +ingress "nginx-ingress" deleted + +$ kubectl create -f nginx-ingress.yaml +ingress "nginx-ingress" created + +$ kubectl get ing nginx-ingress +NAME HOSTS ADDRESS PORTS AGE +nginx-ingress * 104.154.109.191 80, 443 13m +
Note that unlike the GCE Ingress, the same loadbalancer IP is shared amongst all +Ingresses, because all requests are proxied through the same set of nginx +controllers.
+Promote ephemeral to static IP¶
+To promote the allocated IP to static, you can update the Service manifest
+$ kubectl patch svc nginx-ingress-lb -p '{"spec": {"loadBalancerIP": "104.154.109.191"}}' +"nginx-ingress-lb" patched +
and promote the IP to static (promotion works differently for cloudproviders, +provided example is for GKE/GCE) +`
+$ gcloud compute addresses create nginx-ingress-lb --addresses 104.154.109.191 --region us-central1 +Created [https://www.googleapis.com/compute/v1/projects/kubernetesdev/regions/us-central1/addresses/nginx-ingress-lb]. +--- +address: 104.154.109.191 +creationTimestamp: '2017-01-31T16:34:50.089-08:00' +description: '' +id: '5208037144487826373' +kind: compute#address +name: nginx-ingress-lb +region: us-central1 +selfLink: https://www.googleapis.com/compute/v1/projects/kubernetesdev/regions/us-central1/addresses/nginx-ingress-lb +status: IN_USE +users: +- us-central1/forwardingRules/a09f6913ae80e11e6a8c542010af0000 +
Now even if the Service is deleted, the IP will persist, so you can recreate the
+Service with spec.loadBalancerIP set to 104.154.109.191.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/examples/tls-termination/ingress.yaml b/examples/tls-termination/ingress.yaml
new file mode 100644
index 000000000..b5decf8f2
--- /dev/null
+++ b/examples/tls-termination/ingress.yaml
@@ -0,0 +1,20 @@
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+ name: nginx-test
+spec:
+ tls:
+ - hosts:
+ - foo.bar.com
+ # This assumes tls-secret exists and the SSL
+ # certificate contains a CN for foo.bar.com
+ secretName: tls-secret
+ rules:
+ - host: foo.bar.com
+ http:
+ paths:
+ - path: /
+ backend:
+ # This assumes http-svc exists and routes to healthy endpoints
+ serviceName: http-svc
+ servicePort: 80
diff --git a/images/elb-l7-listener.png b/images/elb-l7-listener.png
new file mode 100644
index 000000000..006c69871
Binary files /dev/null and b/images/elb-l7-listener.png differ
diff --git a/images/zipkin-demo.png b/images/zipkin-demo.png
new file mode 100644
index 000000000..8b5970b72
Binary files /dev/null and b/images/zipkin-demo.png differ
diff --git a/index.html b/index.html
new file mode 100644
index 000000000..6d7bfd552
--- /dev/null
+++ b/index.html
@@ -0,0 +1,1132 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ TLS termination¶
+This example demonstrates how to terminate TLS through the nginx Ingress controller.
+Prerequisites¶
+You need a TLS cert and a test HTTP service for this example.
+Deployment¶
+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.
+kubectl apply -f ingress.yaml
+Validation¶
+You can confirm that the Ingress works.
+$ kubectl describe ing nginx-test +Name: nginx-test +Namespace: default +Address: 104.198.183.6 +Default backend: default-http-backend:80 (10.180.0.4:8080,10.240.0.2:8080) +TLS: + tls-secret terminates +Rules: + Host Path Backends + ---- ---- -------- + * + http-svc:80 (<none>) +Annotations: +Events: + FirstSeen LastSeen Count From SubObjectPath Type Reason Message + --------- -------- ----- ---- ------------- -------- ------ ------- + 7s 7s 1 {nginx-ingress-controller } Normal CREATE default/nginx-test + 7s 7s 1 {nginx-ingress-controller } Normal UPDATE default/nginx-test + 7s 7s 1 {nginx-ingress-controller } Normal CREATE ip: 104.198.183.6 + 7s 7s 1 {nginx-ingress-controller } Warning MAPPING Ingress rule 'default/nginx-test' contains no path definition. Assuming / + +$ curl 104.198.183.6 -L +curl: (60) SSL certificate problem: self signed certificate +More details here: http://curl.haxx.se/docs/sslcerts.html + +$ curl 104.198.183.6 -Lk +CLIENT VALUES: +client_address=10.240.0.4 +command=GET +real path=/ +query=nil +request_version=1.1 +request_uri=http://35.186.221.137:8080/ + +SERVER VALUES: +server_version=nginx: 1.9.11 - lua: 10001 + +HEADERS RECEIVED: +accept=*/* +connection=Keep-Alive +host=35.186.221.137 +user-agent=curl/7.46.0 +via=1.1 google +x-cloud-trace-context=f708ea7e369d4514fc90d51d7e27e91d/13322322294276298106 +x-forwarded-for=104.132.0.80, 35.186.221.137 +x-forwarded-proto=https +BODY: +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/ingress-controller-catalog/index.html b/ingress-controller-catalog/index.html
new file mode 100644
index 000000000..f1e4e4bac
--- /dev/null
+++ b/ingress-controller-catalog/index.html
@@ -0,0 +1,1109 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Welcome¶
+This is the documentation for the NGINX Ingress Controller.
+It is built around the Kubernetes Ingress resource, using a ConfigMap to store the NGINX configuration.
+Learn more about using Ingress on k8s.io.
+Getting Started¶
+See Deployment for a whirlwind tour that will get you started.
+ + + + + + + + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/search/search_index.json b/search/search_index.json
new file mode 100644
index 000000000..a63dfd263
--- /dev/null
+++ b/search/search_index.json
@@ -0,0 +1,1689 @@
+{
+ "docs": [
+ {
+ "location": "/",
+ "text": "Welcome\n\u00b6\n\n\nThis is the documentation for the NGINX Ingress Controller.\n\n\nIt is built around the \nKubernetes Ingress resource\n, using a \nConfigMap\n to store the NGINX configuration.\n\n\nLearn more about using Ingress on \nk8s.io\n.\n\n\nGetting Started\n\u00b6\n\n\nSee \nDeployment\n for a whirlwind tour that will get you started.",
+ "title": "Welcome"
+ },
+ {
+ "location": "/#welcome",
+ "text": "This is the documentation for the NGINX Ingress Controller. It is built around the Kubernetes Ingress resource , using a ConfigMap to store the NGINX configuration. Learn more about using Ingress on k8s.io .",
+ "title": "Welcome"
+ },
+ {
+ "location": "/#getting-started",
+ "text": "See Deployment for a whirlwind tour that will get you started.",
+ "title": "Getting Started"
+ },
+ {
+ "location": "/deploy/",
+ "text": "Installation Guide\n\u00b6\n\n\nContents\n\u00b6\n\n\n\n\nMandatory commands\n\n\nInstall without RBAC roles\n\n\nInstall with RBAC roles\n\n\nCustom Provider\n\n\nDocker for Mac\n\n\nminikube\n\n\nAWS\n\n\nGCE - GKE\n\n\nAzure\n\n\nBaremetal\n\n\nUsing Helm\n\n\nVerify installation\n\n\nDetect installed version\n\n\nDeploying the config-map\n\n\n\n\nGeneric Deployment\n\u00b6\n\n\nThe following resources are required for a generic deployment.\n\n\nMandatory commands\n\u00b6\n\n\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/namespace.yaml \\\n\n\n | kubectl apply -f -\n\n\n\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/default-backend.yaml \\\n\n\n | kubectl apply -f -\n\n\n\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/configmap.yaml \\\n\n\n | kubectl apply -f -\n\n\n\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/tcp-services-configmap.yaml \\\n\n\n | kubectl apply -f -\n\n\n\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/udp-services-configmap.yaml \\\n\n\n | kubectl apply -f -\n\n\n\n\n\n\nInstall without RBAC roles\n\u00b6\n\n\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/without-rbac.yaml \\\n\n\n | kubectl apply -f -\n\n\n\n\n\n\nInstall with RBAC roles\n\u00b6\n\n\nPlease check the \nRBAC\n document.\n\n\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/rbac.yaml \\\n\n\n | kubectl apply -f -\n\n\n\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/with-rbac.yaml \\\n\n\n | kubectl apply -f -\n\n\n\n\n\n\nCustom Service Provider Deployment\n\u00b6\n\n\nThere are cloud provider specific yaml files.\n\n\nDocker for Mac\n\u00b6\n\n\nKubernetes is available for Docker for Mac's Edge channel. Switch to the \nEdge\nchannel\n and \nenable Kubernetes\n.\n\n\nPatch the nginx ingress controller deployment to add the flag \n--publish-service\n\n\nkubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \\\n\n\n --patch=\"$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)\"\n\n\n\n\n\n\nCreate a service\n\n\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/docker-for-mac/service.yaml \\\n\n\n | kubectl apply -f -\n\n\n\n\n\n\nminikube\n\u00b6\n\n\nFor standard usage:\n\n\nminikube addons enable ingress\n\n\n\n\n\n\nFor development:\n\n\n\n\nDisable the ingress addon:\n\n\n\n\n$\n minikube addons disable ingress\n\n\n\n\n\n\n\nUse the \ndocker daemon\n\n\nBuild the image\n\n\nPerform \nMandatory commands\n\n\nInstall the \nnginx-ingress-controller\n deployment \nwithout RBAC roles\n or \nwith RBAC roles\n\n\nEdit the \nnginx-ingress-controller\n deployment to use your custom image. Local images can be seen by performing \ndocker images\n.\n\n\n\n\n$\n kubectl edit deployment nginx-ingress-controller -n ingress-nginx\n\n\n\n\n\nedit the following section:\n\n\nimage\n:\n \n
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Ingress Controller Catalog¶
+This is a non-comprehensive list of existing ingress controllers.
+-
+
- Dummy controller backend +
- HAProxy Ingress controller +
- Linkerd +
- traefik +
- AWS Application Load Balancer Ingress Controller +
- kube-ingress-aws-controller +
- Voyager: HAProxy Ingress Controller +
- External Nginx Ingress Controller +
- Heptio Contour controller +
- LemonLDAP::NG kubernetes controller adds WebSSO, Access Management and Identity Federation to NGINX Ingress Controller +