DevFW-CICD/ingress-nginx-helm
6
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ingress-nginx-helm/search/search_index.json
Travis Bot a078100980 Deploy GitHub Pages
2018-05-02 21:47:54 +00:00

1704 lines
No EOL
378 KiB
JSON
Raw Blame History

{
"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<IMAGE-NAME>:<TAG>\n\n\nimagePullPolicy\n:\n \nIfNotPresent\n\n\nname\n:\n \nnginx-ingress-controller\n\n\n\n\n\n\n\n\nConfirm the \nnginx-ingress-controller\n deployment exists:\n\n\n\n\n$\n kubectl get pods -n ingress-nginx \n\nNAME READY STATUS RESTARTS AGE\n\n\ndefault-http-backend-66b447d9cf-rrlf9 1/1 Running 0 12s\n\n\nnginx-ingress-controller-fdcdcd6dd-vvpgs 1/1 Running 0 11s\n\n\n\n\n\n\nAWS\n\u00b6\n\n\nIn AWS we use an Elastic Load Balancer (ELB) to expose the NGINX Ingress controller behind a Service of \nType=LoadBalancer\n.\nSince Kubernetes v1.9.0 it is possible to use a classic load balancer (ELB) or network load balancer (NLB)\nPlease check the \nelastic load balancing AWS details page\n\n\nElastic Load Balancer - ELB\n\u00b6\n\n\nThis setup requires to choose in which layer (L4 or L7) we want to configure the ELB:\n\n\n\n\nLayer 4\n: use TCP as the listener protocol for ports 80 and 443.\n\n\nLayer 7\n: use HTTP as the listener protocol for port 80 and terminate TLS in the ELB\n\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\nFor L4:\n\n\nkubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/service-l4.yaml\n\n\nkubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/patch-configmap-l4.yaml\n\n\n\n\n\n\nFor L7:\n\n\nChange line of the file \nprovider/aws/service-l7.yaml\n replacing the dummy id with a valid one \n\"arn:aws:acm:us-west-2:XXXXXXXX:certificate/XXXXXX-XXXXXXX-XXXXXXX-XXXXXXXX\"\n\nThen execute:\n\n\nkubectl apply -f provider/aws/service-l7.yaml\n\n\nkubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/patch-configmap-l7.yaml\n\n\n\n\n\n\nThis example creates an ELB with just two listeners, one in port 80 and another in port 443\n\n\n\n\nIf the ingress controller uses RBAC run:\n\n\nkubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml\n\n\n\n\n\n\nIf not run:\n\n\nkubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml\n\n\n\n\n\n\nNetwork Load Balancer (NLB)\n\u00b6\n\n\nThis type of load balancer is supported since v1.10.0 as an ALPHA feature.\n\n\nkubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/service-nlb.yaml\n\n\n\n\n\n\nIf the ingress controller uses RBAC run:\n\n\nkubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml\n\n\n\n\n\n\nIf not run:\n\n\nkubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml\n\n\n\n\n\n\nGCE - GKE\n\u00b6\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\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/gce-gke/service.yaml \\\n\n\n | kubectl apply -f -\n\n\n\n\n\n\nIf the ingress controller uses RBAC run:\n\n\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml | kubectl apply -f -\n\n\n\n\n\n\nIf not run:\n\n\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml | kubectl apply -f -\n\n\n\n\n\n\nImportant Note:\n proxy protocol is not supported in GCE/GKE\n\n\nAzure\n\u00b6\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\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/azure/service.yaml \\\n\n\n | kubectl apply -f -\n\n\n\n\n\n\nIf the ingress controller uses RBAC run:\n\n\nkubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml\n\n\n\n\n\n\nIf not run:\n\n\nkubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml\n\n\n\n\n\n\nImportant Note:\n proxy protocol is not supported in GCE/GKE\n\n\nBaremetal\n\u00b6\n\n\nUsing \nNodePort\n:\n\n\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/baremetal/service-nodeport.yaml \\\n\n\n | kubectl apply -f -\n\n\n\n\n\n\nUsing Helm\n\u00b6\n\n\nNGINX Ingress controller can be installed via \nHelm\n using the chart \nstable/nginx\n from the official charts repository. \nTo install the chart with the release name \nmy-nginx\n:\n\n\nhelm install stable/nginx-ingress --name my-nginx\n\n\n\n\n\n\nIf the kubernetes cluster has RBAC enabled, then run:\n\n\nhelm install stable/nginx-ingress --name my-nginx --set rbac.create=true\n\n\n\n\n\n\nVerify installation\n\u00b6\n\n\nTo check if the ingress controller pods have started, run the following command:\n\n\nkubectl get pods --all-namespaces -l app=ingress-nginx --watch\n\n\n\n\n\n\nOnce the operator pods are running, you can cancel the above command by typing \nCtrl+C\n.\nNow, you are ready to create your first ingress.\n\n\nDetect installed version\n\u00b6\n\n\nTo detect which version of the ingress controller is running, exec into the pod and run \nnginx-ingress-controller version\n command.\n\n\nPOD_NAMESPACE=ingress-nginx\n\n\nPOD_NAME=$(kubectl get pods -n $POD_NAMESPACE -l app=ingress-nginx -o jsonpath={.items[0].metadata.name})\n\n\nkubectl exec -it $POD_NAME -n $POD_NAMESPACE -- /nginx-ingress-controller --version\n\n\n\n\n\n\nDeploying the config-map\n\u00b6\n\n\nA config map can be used to configure system components for the nginx-controller. In order to begin using a config-map\nmake sure it has been created and is being used in the deployment.\n\n\nIt is created as seen in the \nMandatory Commands\n section above.\n\n\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/configmap.yaml \\\n\n\n | kubectl apply -f -\n\n\n\n\n\n\nand is setup to be used in the deployment \nwithout-rbac\n or \nwith-rbac\n with the following line:\n\n\n-\n \n--configmap=$(POD_NAMESPACE)/nginx-configuration\n\n\n\n\n\n\nFor information on using the config-map, see its \nuser-guide\n.",
"title": "Installation Guide"
},
{
"location": "/deploy/#installation-guide",
"text": "",
"title": "Installation Guide"
},
{
"location": "/deploy/#contents",
"text": "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",
"title": "Contents"
},
{
"location": "/deploy/#generic-deployment",
"text": "The following resources are required for a generic deployment.",
"title": "Generic Deployment"
},
{
"location": "/deploy/#mandatory-commands",
"text": "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 -",
"title": "Mandatory commands"
},
{
"location": "/deploy/#install-without-rbac-roles",
"text": "curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/without-rbac.yaml \\ | kubectl apply -f -",
"title": "Install without RBAC roles"
},
{
"location": "/deploy/#install-with-rbac-roles",
"text": "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 -",
"title": "Install with RBAC roles"
},
{
"location": "/deploy/#custom-service-provider-deployment",
"text": "There are cloud provider specific yaml files.",
"title": "Custom Service Provider Deployment"
},
{
"location": "/deploy/#docker-for-mac",
"text": "Kubernetes is available for Docker for Mac's Edge channel. Switch to the Edge\nchannel 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 -",
"title": "Docker for Mac"
},
{
"location": "/deploy/#minikube",
"text": "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-controller deployment without RBAC roles or with RBAC roles Edit the nginx-ingress-controller deployment to use your custom image. Local images can be seen by performing docker 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-controller deployment 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",
"title": "minikube"
},
{
"location": "/deploy/#aws",
"text": "In AWS we use an Elastic Load Balancer (ELB) to expose the NGINX Ingress controller behind a Service of Type=LoadBalancer .\nSince Kubernetes v1.9.0 it is possible to use a classic load balancer (ELB) or network load balancer (NLB)\nPlease check the elastic load balancing AWS details page",
"title": "AWS"
},
{
"location": "/deploy/#elastic-load-balancer-elb",
"text": "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\" \nThen 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",
"title": "Elastic Load Balancer - ELB"
},
{
"location": "/deploy/#network-load-balancer-nlb",
"text": "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",
"title": "Network Load Balancer (NLB)"
},
{
"location": "/deploy/#gce-gke",
"text": "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",
"title": "GCE - GKE"
},
{
"location": "/deploy/#azure",
"text": "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",
"title": "Azure"
},
{
"location": "/deploy/#baremetal",
"text": "Using NodePort : curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/baremetal/service-nodeport.yaml \\ | kubectl apply -f -",
"title": "Baremetal"
},
{
"location": "/deploy/#using-helm",
"text": "NGINX Ingress controller can be installed via Helm using the chart stable/nginx from the official charts repository. \nTo 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",
"title": "Using Helm"
},
{
"location": "/deploy/#verify-installation",
"text": "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 .\nNow, you are ready to create your first ingress.",
"title": "Verify installation"
},
{
"location": "/deploy/#detect-installed-version",
"text": "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",
"title": "Detect installed version"
},
{
"location": "/deploy/#deploying-the-config-map",
"text": "A config map can be used to configure system components for the nginx-controller. In order to begin using a config-map\nmake 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 .",
"title": "Deploying the config-map"
},
{
"location": "/deploy/rbac/",
"text": "Role Based Access Control (RBAC)\n\u00b6\n\n\nOverview\n\u00b6\n\n\nThis example applies to nginx-ingress-controllers being deployed in an environment with RBAC enabled.\n\n\nRole Based Access Control is comprised of four layers:\n\n\n\n\nClusterRole\n - permissions assigned to a role that apply to an entire cluster\n\n\nClusterRoleBinding\n - binding a ClusterRole to a specific account\n\n\nRole\n - permissions assigned to a role that apply to a specific namespace\n\n\nRoleBinding\n - binding a Role to a specific account\n\n\n\n\nIn order for RBAC to be applied to an nginx-ingress-controller, that controller\nshould be assigned to a \nServiceAccount\n. That \nServiceAccount\n should be\nbound to the \nRole\ns and \nClusterRole\ns defined for the nginx-ingress-controller.\n\n\nService Accounts created in this example\n\u00b6\n\n\nOne ServiceAccount is created in this example, \nnginx-ingress-serviceaccount\n.\n\n\nPermissions Granted in this example\n\u00b6\n\n\nThere are two sets of permissions defined in this example. Cluster-wide\npermissions defined by the \nClusterRole\n named \nnginx-ingress-clusterrole\n, and\nnamespace specific permissions defined by the \nRole\n named \nnginx-ingress-role\n.\n\n\nCluster Permissions\n\u00b6\n\n\nThese permissions are granted in order for the nginx-ingress-controller to be\nable to function as an ingress across the cluster. These permissions are\ngranted to the ClusterRole named \nnginx-ingress-clusterrole\n\n\n\n\nconfigmaps\n, \nendpoints\n, \nnodes\n, \npods\n, \nsecrets\n: list, watch\n\n\nnodes\n: get\n\n\nservices\n, \ningresses\n: get, list, watch\n\n\nevents\n: create, patch\n\n\ningresses/status\n: update\n\n\n\n\nNamespace Permissions\n\u00b6\n\n\nThese permissions are granted specific to the nginx-ingress namespace. These\npermissions are granted to the Role named \nnginx-ingress-role\n\n\n\n\nconfigmaps\n, \npods\n, \nsecrets\n: get\n\n\nendpoints\n: get\n\n\n\n\nFurthermore to support leader-election, the nginx-ingress-controller needs to\nhave access to a \nconfigmap\n using the resourceName \ningress-controller-leader-nginx\n\n\n\n\nNote that resourceNames can NOT be used to limit requests using the \u201ccreate\u201d\nverb because authorizers only have access to information that can be obtained\nfrom the request URL, method, and headers (resource names in a \u201ccreate\u201d request\nare part of the request body).\n\n\n\n\n\n\nconfigmaps\n: get, update (for resourceName \ningress-controller-leader-nginx\n)\n\n\nconfigmaps\n: create\n\n\n\n\nThis resourceName is the concatenation of the \nelection-id\n and the\n\ningress-class\n as defined by the ingress-controller, which defaults to:\n\n\n\n\nelection-id\n: \ningress-controller-leader\n\n\ningress-class\n: \nnginx\n\n\nresourceName\n : \n<election-id>-<ingress-class>\n\n\n\n\nPlease adapt accordingly if you overwrite either parameter when launching the\nnginx-ingress-controller.\n\n\nBindings\n\u00b6\n\n\nThe ServiceAccount \nnginx-ingress-serviceaccount\n is bound to the Role\n\nnginx-ingress-role\n and the ClusterRole \nnginx-ingress-clusterrole\n.\n\n\nThe serviceAccountName associated with the containers in the deployment must\nmatch the serviceAccount. The namespace references in the Deployment metadata, \ncontainer arguments, and POD_NAMESPACE should be in the nginx-ingress namespace.",
"title": "Role Based Access Control (RBAC)"
},
{
"location": "/deploy/rbac/#role-based-access-control-rbac",
"text": "",
"title": "Role Based Access Control (RBAC)"
},
{
"location": "/deploy/rbac/#overview",
"text": "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\nshould be assigned to a ServiceAccount . That ServiceAccount should be\nbound to the Role s and ClusterRole s defined for the nginx-ingress-controller.",
"title": "Overview"
},
{
"location": "/deploy/rbac/#service-accounts-created-in-this-example",
"text": "One ServiceAccount is created in this example, nginx-ingress-serviceaccount .",
"title": "Service Accounts created in this example"
},
{
"location": "/deploy/rbac/#permissions-granted-in-this-example",
"text": "There are two sets of permissions defined in this example. Cluster-wide\npermissions defined by the ClusterRole named nginx-ingress-clusterrole , and\nnamespace specific permissions defined by the Role named nginx-ingress-role .",
"title": "Permissions Granted in this example"
},
{
"location": "/deploy/rbac/#cluster-permissions",
"text": "These permissions are granted in order for the nginx-ingress-controller to be\nable to function as an ingress across the cluster. These permissions are\ngranted 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",
"title": "Cluster Permissions"
},
{
"location": "/deploy/rbac/#namespace-permissions",
"text": "These permissions are granted specific to the nginx-ingress namespace. These\npermissions 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\nhave access to a configmap using the resourceName ingress-controller-leader-nginx Note that resourceNames can NOT be used to limit requests using the \u201ccreate\u201d\nverb because authorizers only have access to information that can be obtained\nfrom the request URL, method, and headers (resource names in a \u201ccreate\u201d request\nare part of the request body). configmaps : get, update (for resourceName ingress-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\nnginx-ingress-controller.",
"title": "Namespace Permissions"
},
{
"location": "/deploy/rbac/#bindings",
"text": "The ServiceAccount nginx-ingress-serviceaccount is bound to the Role nginx-ingress-role and the ClusterRole nginx-ingress-clusterrole . The serviceAccountName associated with the containers in the deployment must\nmatch the serviceAccount. The namespace references in the Deployment metadata, \ncontainer arguments, and POD_NAMESPACE should be in the nginx-ingress namespace.",
"title": "Bindings"
},
{
"location": "/user-guide/nginx-configuration/",
"text": "NGINX Configuration\n\u00b6\n\n\nThere are three ways to customize NGINX:\n\n\n\n\nConfigMap\n: using a Configmap to set global configurations in NGINX.\n\n\nAnnotations\n: use this if you want a specific configuration for a particular Ingress rule.\n\n\nCustom template\n: when more specific settings are required, like \nopen_file_cache\n, adjust \nlisten\n options as \nrcvbuf\n or when is not possible to change the configuration through the ConfigMap.",
"title": "NGINX Configuration"
},
{
"location": "/user-guide/nginx-configuration/#nginx-configuration",
"text": "There are three ways to customize NGINX: ConfigMap : using a Configmap to set global configurations in NGINX. Annotations : use this if you want a specific configuration for a particular Ingress rule. Custom template : when more specific settings are required, like open_file_cache , adjust listen options as rcvbuf or when is not possible to change the configuration through the ConfigMap.",
"title": "NGINX Configuration"
},
{
"location": "/user-guide/nginx-configuration/annotations/",
"text": "Annotations\n\u00b6\n\n\nYou can add these Kubernetes annotations to specific Ingress objects to customize their behavior.\n\n\n\n\nTip\n\n\nAnnotation keys and values can only be strings.\nOther types, such as boolean or numeric values must be quoted,\ni.e. \n\"true\"\n, \n\"false\"\n, \n\"100\"\n.\n\n\n\n\n\n\n\n\n\n\nName\n\n\ntype\n\n\n\n\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/add-base-url\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/app-root\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/affinity\n\n\ncookie\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-realm\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-secret\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-type\n\n\nbasic or digest\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-tls-secret\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-tls-verify-depth\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-tls-verify-client\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-tls-error-page\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/auth-url\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/base-url-scheme\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/client-body-buffer-size\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/configuration-snippet\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/default-backend\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/enable-cors\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-origin\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-methods\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-headers\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-credentials\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/cors-max-age\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/force-ssl-redirect\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/from-to-www-redirect\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/grpc-backend\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/limit-connections\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/limit-rps\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/permanent-redirect\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-body-size\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-connect-timeout\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-send-timeout\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-read-timeout\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-next-upstream\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-next-upstream-tries\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-request-buffering\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-redirect-from\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-redirect-to\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/rewrite-log\n\n\nURI\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/rewrite-target\n\n\nURI\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/secure-backends\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/secure-verify-ca-secret\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/server-alias\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/server-snippet\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/service-upstream\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/session-cookie-name\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/session-cookie-hash\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/ssl-redirect\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/ssl-passthrough\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/upstream-max-fails\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/upstream-fail-timeout\n\n\nnumber\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/upstream-hash-by\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/load-balance\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/upstream-vhost\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/whitelist-source-range\n\n\nCIDR\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-buffering\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/ssl-ciphers\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/connection-proxy-header\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/enable-access-log\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf-debug\n\n\n\"true\" or \"false\"\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf-extra-rules\n\n\nstring\n\n\n\n\n\n\n\n\nRewrite\n\u00b6\n\n\nIn some scenarios the exposed URL in the backend service differs from the specified path in the Ingress rule. Without a rewrite any request will return 404.\nSet the annotation \nnginx.ingress.kubernetes.io/rewrite-target\n to the path expected by the service.\n\n\nIf the application contains relative links it is possible to add an additional annotation \nnginx.ingress.kubernetes.io/add-base-url\n that will prepend a \nbase\n tag\n in the header of the returned HTML from the backend.\n\n\nIf the scheme of \nbase\n tag\n need to be specific, set the annotation \nnginx.ingress.kubernetes.io/base-url-scheme\n to the scheme such as \nhttp\n and \nhttps\n.\n\n\nIf the Application Root is exposed in a different path and needs to be redirected, set the annotation \nnginx.ingress.kubernetes.io/app-root\n to redirect requests for \n/\n.\n\n\nPlease check the \nrewrite\n example.\n\n\nSession Affinity\n\u00b6\n\n\nThe annotation \nnginx.ingress.kubernetes.io/affinity\n enables and sets the affinity type in all Upstreams of an Ingress. This way, a request will always be directed to the same upstream server.\nThe only affinity type available for NGINX is \ncookie\n.\n\n\nPlease check the \naffinity\n example.\n\n\nAuthentication\n\u00b6\n\n\nIs possible to add authentication adding additional annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords inside the key \nauth\n.\n\n\nThe annotations are:\n\n\nnginx.ingress.kubernetes.io/auth-type: [basic|digest]\n\n\n\n\n\nIndicates the \nHTTP Authentication Type: Basic or Digest Access Authentication\n.\n\n\nnginx.ingress.kubernetes.io/auth-secret: secretName\n\n\n\n\n\nThe name of the Secret that contains the usernames and passwords which are granted access to the \npath\ns defined in the Ingress rules.\nThis annotation also accepts the alternative form \"namespace/secretName\", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace.\n\n\nnginx.ingress.kubernetes.io/auth-realm: \"realm string\"\n\n\n\n\n\nPlease check the \nauth\n example.\n\n\nCustom NGINX upstream checks\n\u00b6\n\n\nNGINX exposes some flags in the \nupstream configuration\n that enable the configuration of each server in the upstream. The Ingress controller allows custom \nmax_fails\n and \nfail_timeout\n parameters in a global context using \nupstream-max-fails\n and \nupstream-fail-timeout\n in the NGINX ConfigMap or in a particular Ingress rule. \nupstream-max-fails\n defaults to 0. This means NGINX will respect the container's \nreadinessProbe\n if it is defined. If there is no probe and no values for \nupstream-max-fails\n NGINX will continue to send traffic to the container.\n\n\n\n\nTip\n\n\nWith the default configuration NGINX will not health check your backends. Whenever the endpoints controller notices a readiness probe failure, that pod's IP will be removed from the list of endpoints. This will trigger the NGINX controller to also remove it from the upstreams.**\n\n\n\n\nTo use custom values in an Ingress rule define these annotations:\n\n\nnginx.ingress.kubernetes.io/upstream-max-fails\n: number of unsuccessful attempts to communicate with the server that should occur in the duration set by the \nupstream-fail-timeout\n parameter to consider the server unavailable.\n\n\nnginx.ingress.kubernetes.io/upstream-fail-timeout\n: time in seconds during which the specified number of unsuccessful attempts to communicate with the server should occur to consider the server unavailable. This is also the period of time the server will be considered unavailable.\n\n\nIn NGINX, backend server pools are called \"\nupstreams\n\". Each upstream contains the endpoints for a service. An upstream is created for each service that has Ingress rules defined.\n\n\n\n\nImportant\n\n\nAll Ingress rules using the same service will use the same upstream. Only one of the Ingress rules should define annotations to configure the upstream servers.\n\n\n\n\nPlease check the \ncustom upstream check\n example.\n\n\nCustom NGINX upstream hashing\n\u00b6\n\n\nNGINX supports load balancing by client-server mapping based on \nconsistent hashing\n for a given key. The key can contain text, variables or any combination thereof. This feature allows for request stickiness other than client IP or cookies. The \nketama\n consistent hashing method will be used which ensures only a few keys would be remapped to different servers on upstream group changes.\n\n\nTo enable consistent hashing for a backend:\n\n\nnginx.ingress.kubernetes.io/upstream-hash-by\n: the nginx variable, text value or any combination thereof to use for consistent hashing. For example \nnginx.ingress.kubernetes.io/upstream-hash-by: \"$request_uri\"\n to consistently hash upstream requests by the current request URI.\n\n\nCustom NGINX load balancing\n\u00b6\n\n\nThis is similar to (https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/nginx-configuration/configmap.md#load-balance) but configures load balancing algorithm per ingress.\n\n\n\n\nNote that \nnginx.ingress.kubernetes.io/upstream-hash-by\n takes preference over this. If this and \nnginx.ingress.kubernetes.io/upstream-hash-by\n are not set then we fallback to using globally configured load balancing algorithm.\n\n\n\n\nCustom NGINX upstream vhost\n\u00b6\n\n\nThis configuration setting allows you to control the value for host in the following statement: \nproxy_set_header Host $host\n, which forms part of the location block. This is useful if you need to call the upstream server by something other than \n$host\n.\n\n\nClient Certificate Authentication\n\u00b6\n\n\nIt is possible to enable Client Certificate Authentication using additional annotations in Ingress Rule.\n\n\nThe annotations are:\n\n\nnginx.ingress.kubernetes.io/auth-tls-secret: secretName\n\n\n\n\n\nThe name of the Secret that contains the full Certificate Authority chain \nca.crt\n that is enabled to authenticate against this Ingress.\nThis annotation also accepts the alternative form \"namespace/secretName\", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace.\n\n\nnginx.ingress.kubernetes.io/auth-tls-verify-depth\n\n\n\n\n\nThe validation depth between the provided client certificate and the Certification Authority chain.\n\n\nnginx.ingress.kubernetes.io/auth-tls-verify-client\n\n\n\n\n\nEnables verification of client certificates.\n\n\nnginx.ingress.kubernetes.io/auth-tls-error-page\n\n\n\n\n\nThe URL/Page that user should be redirected in case of a Certificate Authentication Error\n\n\nnginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream\n\n\n\n\n\nIndicates if the received certificates should be passed or not to the upstream server.\nBy default this is disabled.\n\n\nPlease check the \nclient-certs\n example.\n\n\n\n\nImportant\n\n\nTLS with Client Authentication is NOT possible in Cloudflare as is not allowed it and might result in unexpected behavior.\n\n\nCloudflare only allows Authenticated Origin Pulls and is required to use their own certificate: \nhttps://blog.cloudflare.com/protecting-the-origin-with-tls-authenticated-origin-pulls/\n\n\nOnly Authenticated Origin Pulls are allowed and can be configured by following their tutorial: \nhttps://support.cloudflare.com/hc/en-us/articles/204494148-Setting-up-NGINX-to-use-TLS-Authenticated-Origin-Pulls\n\n\n\n\nConfiguration snippet\n\u00b6\n\n\nUsing this annotation you can add additional configuration to the NGINX location. For example:\n\n\nnginx.ingress.kubernetes.io/configuration-snippet\n:\n \n|\n\n \nmore_set_headers \"Request-Id: $req_id\";\n\n\n\n\n\n\nDefault Backend\n\u00b6\n\n\nThe ingress controller requires a default backend. This service handles the response when the service in the Ingress rule does not have endpoints.\nThis is a global configuration for the ingress controller. In some cases could be required to return a custom content or format. In this scenario we can use the annotation \nnginx.ingress.kubernetes.io/default-backend: <svc name>\n to specify a custom default backend.\n\n\nEnable CORS\n\u00b6\n\n\nTo enable Cross-Origin Resource Sharing (CORS) in an Ingress rule add the annotation \nnginx.ingress.kubernetes.io/enable-cors: \"true\"\n. This will add a section in the server location enabling this functionality.\n\n\nCORS can be controlled with the following annotations:\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-methods\n controls which methods are accepted. This is a multi-valued field, separated by ',' and accepts only letters (upper and lower case).\n\n\n\n\nExample: \nnginx.ingress.kubernetes.io/cors-allow-methods: \"PUT, GET, POST, OPTIONS\"\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-headers\n controls which headers are accepted. This is a multi-valued field, separated by ',' and accepts letters, numbers, _ and -.\n\n\n\n\nExample: \nnginx.ingress.kubernetes.io/cors-allow-headers: \"X-Forwarded-For, X-app123-XPTO\"\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-origin\n controls what's the accepted Origin for CORS and defaults to '*'. This is a single field value, with the following format: http(s)://origin-site.com or http(s)://origin-site.com:port\n\n\n\n\nExample: \nnginx.ingress.kubernetes.io/cors-allow-origin: \"https://origin-site.com:4443\"\n\n\n\n\nnginx.ingress.kubernetes.io/cors-allow-credentials\n controls if credentials can be passed during CORS operations.\n\n\n\n\nExample: \nnginx.ingress.kubernetes.io/cors-allow-credentials: \"true\"\n\n\n\n\nnginx.ingress.kubernetes.io/cors-max-age\n controls how long preflight requests can be cached.\n\n\n\n\nExample: \nnginx.ingress.kubernetes.io/cors-max-age: 600\n\n\nFor more information please see \nhttps://enable-cors.org\n\n\nServer Alias\n\u00b6\n\n\nTo add Server Aliases to an Ingress rule add the annotation \nnginx.ingress.kubernetes.io/server-alias: \"<alias>\"\n.\nThis will create a server with the same configuration, but a different server_name as the provided host.\n\n\n\n\nNote\n\n\nA server-alias name cannot conflict with the hostname of an existing server. If it does the server-alias annotation will be ignored. If a server-alias is created and later a new server with the same hostname is created the new server configuration will take place over the alias configuration.\n\n\n\n\nFor more information please see \nhttp://nginx.org\n\n\nServer snippet\n\u00b6\n\n\nUsing the annotation \nnginx.ingress.kubernetes.io/server-snippet\n it is possible to add custom configuration in the server configuration block.\n\n\napiVersion\n:\n \nextensions/v1beta1\n\n\nkind\n:\n \nIngress\n\n\nmetadata\n:\n\n \nannotations\n:\n\n \nnginx.ingress.kubernetes.io/server-snippet\n:\n \n|\n\n\nset $agentflag 0;\n\n\n\nif ($http_user_agent ~* \"(Mobile)\" ){\n\n \nset $agentflag 1;\n\n\n}\n\n\n\nif ( $agentflag = 1 ) {\n\n \nreturn 301 https://m.example.com;\n\n\n}\n\n\n\n\n\n\n\n\nImportant\n\n\nThis annotation can be used only once per host\n\n\n\n\nClient Body Buffer Size\n\u00b6\n\n\nSets buffer size for reading client request body per location. In case the request body is larger than the buffer,\nthe whole body or only its part is written to a temporary file. By default, buffer size is equal to two memory pages.\nThis is 8K on x86, other 32-bit platforms, and x86-64. It is usually 16K on other 64-bit platforms. This annotation is\napplied to each location provided in the ingress rule.\n\n\nNote:\n The annotation value must be given in a valid format otherwise the\nFor example to set the client-body-buffer-size the following can be done:\n\n\n\n\nnginx.ingress.kubernetes.io/client-body-buffer-size: \"1000\"\n # 1000 bytes\n\n\nnginx.ingress.kubernetes.io/client-body-buffer-size: 1k\n # 1 kilobyte\n\n\nnginx.ingress.kubernetes.io/client-body-buffer-size: 1K\n # 1 kilobyte\n\n\nnginx.ingress.kubernetes.io/client-body-buffer-size: 1m\n # 1 megabyte\n\n\nnginx.ingress.kubernetes.io/client-body-buffer-size: 1M\n # 1 megabyte\n\n\n\n\nFor more information please see \nhttp://nginx.org\n\n\nExternal Authentication\n\u00b6\n\n\nTo use an existing service that provides authentication the Ingress rule can be annotated with \nnginx.ingress.kubernetes.io/auth-url\n to indicate the URL where the HTTP request should be sent.\n\n\nnginx.ingress.kubernetes.io/auth-url\n:\n \n\"URL\n \nto\n \nthe\n \nauthentication\n \nservice\"\n\n\n\n\n\n\nAdditionally it is possible to set:\n\n\nnginx.ingress.kubernetes.io/auth-method\n: \n<Method>\n to specify the HTTP method to use.\n\n\nnginx.ingress.kubernetes.io/auth-signin\n: \n<SignIn_URL>\n to specify the location of the error page.\n\n\nnginx.ingress.kubernetes.io/auth-response-headers\n: \n<Response_Header_1, ..., Response_Header_n>\n to specify headers to pass to backend once authorization request completes.\n\n\nnginx.ingress.kubernetes.io/auth-request-redirect\n: \n<Request_Redirect_URL>\n to specify the X-Auth-Request-Redirect header value.\n\n\nPlease check the \nexternal-auth\n example.\n\n\nRate limiting\n\u00b6\n\n\nThe annotations \nnginx.ingress.kubernetes.io/limit-connections\n, \nnginx.ingress.kubernetes.io/limit-rps\n, and \nnginx.ingress.kubernetes.io/limit-rpm\n define a limit on the connections that can be opened by a single client IP address. This can be used to mitigate \nDDoS Attacks\n.\n\n\nnginx.ingress.kubernetes.io/limit-connections\n: number of concurrent connections allowed from a single IP address.\n\n\nnginx.ingress.kubernetes.io/limit-rps\n: number of connections that may be accepted from a given IP each second.\n\n\nnginx.ingress.kubernetes.io/limit-rpm\n: number of connections that may be accepted from a given IP each minute.\n\n\nYou can specify the client IP source ranges to be excluded from rate-limiting through the \nnginx.ingress.kubernetes.io/limit-whitelist\n annotation. The value is a comma separated list of CIDRs.\n\n\nIf you specify multiple annotations in a single Ingress rule, \nlimit-rpm\n, and then \nlimit-rps\n takes precedence.\n\n\nThe annotation \nnginx.ingress.kubernetes.io/limit-rate\n, \nnginx.ingress.kubernetes.io/limit-rate-after\n define a limit the rate of response transmission to a client. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit.\n\n\nnginx.ingress.kubernetes.io/limit-rate-after\n: sets the initial amount after which the further transmission of a response to a client will be rate limited.\n\n\nnginx.ingress.kubernetes.io/limit-rate\n: rate of request that accepted from a client each second.\n\n\nTo configure this setting globally for all Ingress rules, the \nlimit-rate-after\n and \nlimit-rate\n value may be set in the NGINX ConfigMap. if you set the value in ingress annotation will cover global setting.\n\n\nPermanent Redirect\n\u00b6\n\n\nThis annotation allows to return a permanent redirect instead of sending data to the upstream. For example \nnginx.ingress.kubernetes.io/permanent-redirect: https://www.google.com\n would redirect everything to Google.\n\n\nSSL Passthrough\n\u00b6\n\n\nThe annotation \nnginx.ingress.kubernetes.io/ssl-passthrough\n allows to configure TLS termination in the pod and not in NGINX.\n\n\n\n\nImportant\n\n\n\n\n\n\nUsing the annotation \nnginx.ingress.kubernetes.io/ssl-passthrough\n invalidates all the other available annotations. This is because SSL Passthrough works in L4 (TCP).\n\n\n\n\n\n\nThe use of this annotation requires Proxy Protocol to be enabled in the load-balancer. For example enabling Proxy Protocol for AWS ELB is described \nhere\n. If you're using ingress-controller without load balancer then the flag \n--enable-ssl-passthrough\n is required (by default it is disabled).\n\n\n\n\n\n\n\n\nSecure backends\n\u00b6\n\n\nBy default NGINX uses \nhttp\n to reach the services. Adding the annotation \nnginx.ingress.kubernetes.io/secure-backends: \"true\"\n in the Ingress rule changes the protocol to \nhttps\n.\nIf you want to validate the upstream against a specific certificate, you can create a secret with it and reference the secret with the annotation \nnginx.ingress.kubernetes.io/secure-verify-ca-secret\n.\n\n\n\n\nNote that if an invalid or non-existent secret is given, the NGINX ingress controller will ignore the \nsecure-backends\n annotation.\n\n\n\n\nService Upstream\n\u00b6\n\n\nBy default the NGINX ingress controller uses a list of all endpoints (Pod IP/port) in the NGINX upstream configuration. This annotation disables that behavior and instead uses a single upstream in NGINX, the service's Cluster IP and port. This can be desirable for things like zero-downtime deployments as it reduces the need to reload NGINX configuration when Pods come up and down. See issue \n#257\n.\n\n\nKnown Issues\n\u00b6\n\n\nIf the \nservice-upstream\n annotation is specified the following things should be taken into consideration:\n\n\n\n\nSticky Sessions will not work as only round-robin load balancing is supported.\n\n\nThe \nproxy_next_upstream\n directive will not have any effect meaning on error the request will not be dispatched to another upstream.\n\n\n\n\nServer-side HTTPS enforcement through redirect\n\u00b6\n\n\nBy default the controller redirects (301) to \nHTTPS\n if TLS is enabled for that ingress. If you want to disable that behavior globally, you can use \nssl-redirect: \"false\"\n in the NGINX config map.\n\n\nTo configure this feature for specific ingress resources, you can use the \nnginx.ingress.kubernetes.io/ssl-redirect: \"false\"\n annotation in the particular resource.\n\n\nWhen using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to \nHTTPS\n even when there is not TLS cert available. This can be achieved by using the \nnginx.ingress.kubernetes.io/force-ssl-redirect: \"true\"\n annotation in the particular resource.\n\n\nRedirect from to www\n\u00b6\n\n\nIn some scenarios is required to redirect from \nwww.domain.com\n to \ndomain.com\n or viceversa.\nTo enable this feature use the annotation \nnginx.ingress.kubernetes.io/from-to-www-redirect: \"true\"\n\n\n\n\nImportant\n\n\nIf at some point a new Ingress is created with a host equal to one of the options (like \ndomain.com\n) the annotation will be omitted.\n\n\n\n\nWhitelist source range\n\u00b6\n\n\nYou can specify the allowed client IP source ranges through the \nnginx.ingress.kubernetes.io/whitelist-source-range\n annotation. The value is a comma separated list of \nCIDRs\n, e.g. \n10.0.0.0/24,172.10.0.1\n.\n\n\nTo configure this setting globally for all Ingress rules, the \nwhitelist-source-range\n value may be set in the NGINX ConfigMap.\n\n\nNote:\n Adding an annotation to an Ingress rule overrides any global restriction.\n\n\nCookie affinity\n\u00b6\n\n\nIf you use the \ncookie\n type you can also specify the name of the cookie that will be used to route the requests with the annotation \nnginx.ingress.kubernetes.io/session-cookie-name\n. The default is to create a cookie named 'INGRESSCOOKIE'.\n\n\nIn case of NGINX the annotation \nnginx.ingress.kubernetes.io/session-cookie-hash\n defines which algorithm will be used to 'hash' the used upstream. Default value is \nmd5\n and possible values are \nmd5\n, \nsha1\n and \nindex\n.\nThe \nindex\n option is not hashed, an in-memory index is used instead, it's quicker and the overhead is shorter Warning: the matching against upstream servers list is inconsistent. So, at reload, if upstreams servers has changed, index values are not guaranteed to correspond to the same server as before! \nUSE IT WITH CAUTION\n and only if you need to!\n\n\nIn NGINX this feature is implemented by the third party module \nnginx-sticky-module-ng\n. The workflow used to define which upstream server will be used is explained \nhere\n\n\nCustom timeouts\n\u00b6\n\n\nUsing the configuration configmap it is possible to set the default global timeout for connections to the upstream servers.\nIn some scenarios is required to have different values. To allow this we provide annotations that allows this customization:\n\n\n\n\nnginx.ingress.kubernetes.io/proxy-connect-timeout\n\n\nnginx.ingress.kubernetes.io/proxy-send-timeout\n\n\nnginx.ingress.kubernetes.io/proxy-read-timeout\n\n\nnginx.ingress.kubernetes.io/proxy-next-upstream\n\n\nnginx.ingress.kubernetes.io/proxy-next-upstream-tries\n\n\nnginx.ingress.kubernetes.io/proxy-request-buffering\n\n\n\n\nProxy redirect\n\u00b6\n\n\nWith the annotations \nnginx.ingress.kubernetes.io/proxy-redirect-from\n and \nnginx.ingress.kubernetes.io/proxy-redirect-to\n it is possible to set the text that should be changed in the \nLocation\n and \nRefresh\n header fields of a proxied server response (http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect)\nSetting \"off\" or \"default\" in the annotation \nnginx.ingress.kubernetes.io/proxy-redirect-from\n disables \nnginx.ingress.kubernetes.io/proxy-redirect-to\n\nBoth annotations will be used in any other case\nBy default the value is \"off\".\n\n\nCustom max body size\n\u00b6\n\n\nFor NGINX, 413 error will be returned to the client when the size in a request exceeds the maximum allowed size of the client request body. This size can be configured by the parameter \nclient_max_body_size\n.\n\n\nTo configure this setting globally for all Ingress rules, the \nproxy-body-size\n value may be set in the NGINX ConfigMap.\nTo use custom values in an Ingress rule define these annotation:\n\n\nnginx.ingress.kubernetes.io/proxy-body-size\n:\n \n8m\n\n\n\n\n\n\nProxy buffering\n\u00b6\n\n\nEnable or disable proxy buffering \nproxy_buffering\n.\nBy default proxy buffering is disabled in the nginx config.\n\n\nTo configure this setting globally for all Ingress rules, the \nproxy-buffering\n value may be set in the NGINX ConfigMap.\nTo use custom values in an Ingress rule define these annotation:\n\n\nnginx.ingress.kubernetes.io/proxy-buffering\n:\n \n\"on\"\n\n\n\n\n\n\nSSL ciphers\n\u00b6\n\n\nSpecifies the \nenabled ciphers\n.\n\n\nUsing this annotation will set the \nssl_ciphers\n directive at the server level. This configuration is active for all the paths in the host.\n\n\nnginx.ingress.kubernetes.io/ssl-ciphers\n:\n \n\"ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP\"\n\n\n\n\n\n\nConnection proxy header\n\u00b6\n\n\nUsing this annotation will override the default connection header set by nginx. To use custom values in an Ingress rule, define the annotation:\n\n\nnginx.ingress.kubernetes.io/connection-proxy-header\n:\n \n\"keep-alive\"\n\n\n\n\n\n\nEnable Access Log\n\u00b6\n\n\nIn some scenarios could be required to disable NGINX access logs. To enable this feature use the annotation:\n\n\nnginx.ingress.kubernetes.io/enable-access-log\n:\n \n\"false\"\n\n\n\n\n\n\nEnable Rewrite Log\n\u00b6\n\n\nIn some scenarios it could be required to enable NGINX rewrite logs. Note that rewrite logs are sent to the error_log file at the notice level. To enable this feature use the annotation:\n\n\nnginx.ingress.kubernetes.io/enable-rewrite-log\n:\n \n\"true\"\n\n\n\n\n\n\nLua Resty WAF\n\u00b6\n\n\nUsing \nlua-resty-waf-*\n annotations we can enable and control \nlua-resty-waf\n per location.\nFollowing configuration will enable WAF for the paths defined in the corresponding ingress:\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf\n:\n \n\"active\"\n\n\n\n\n\n\nIn order to run it in debugging mode you can set \nnginx.ingress.kubernetes.io/lua-resty-waf-debug\n to \n\"true\"\n in addition to the above configuration.\nThe other possible values for \nnginx.ingress.kubernetes.io/lua-resty-waf\n are \ninactive\n and \nsimulate\n. In \ninactive\n mode WAF won't do anything, whereas\nin \nsimulate\n mode it will log a warning message if there's a matching WAF rule for given request. This is useful to debug a rule and eliminate possible false positives before fully deploying it.\n\n\nlua-resty-waf\n comes with predefined set of rules \nhttps://github.com/p0pr0ck5/lua-resty-waf/tree/84b4f40362500dd0cb98b9e71b5875cb1a40f1ad/rules\n that covers ModSecurity CRS.\nYou can use \nnginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets\n to ignore subset of those rulesets. For an example:\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets\n:\n \n\"41000_sqli,\n \n42000_xss\"\n\n\n\n\n\n\nwill ignore the two mentioned rulesets.\n\n\nIt is also possible to configure custom WAF rules per ingress using \nnginx.ingress.kubernetes.io/lua-resty-waf-extra-rules\n annotation. For an example the following snippet will\nconfigure a WAF rule to deny requests with query string value that contains word \nfoo\n:\n\n\nnginx.ingress.kubernetes.io/lua-resty-waf-extra-rules\n:\n \n'[=[\n \n{\n \n\"access\":\n \n[\n \n{\n \n\"actions\":\n \n{\n \n\"disrupt\"\n \n:\n \n\"DENY\"\n \n},\n \n\"id\":\n \n10001,\n \n\"msg\":\n \n\"my\n \ncustom\n \nrule\",\n \n\"operator\":\n \n\"STR_CONTAINS\",\n \n\"pattern\":\n \n\"foo\",\n \n\"vars\":\n \n[\n \n{\n \n\"parse\":\n \n[\n \n\"values\",\n \n1\n \n],\n \n\"type\":\n \n\"REQUEST_ARGS\"\n \n}\n \n]\n \n}\n \n],\n \n\"body_filter\":\n \n[],\n \n\"header_filter\":[]\n \n}\n \n]=]'\n\n\n\n\n\n\nFor details on how to write WAF rules, please refer to \nhttps://github.com/p0pr0ck5/lua-resty-waf\n.\n\n\ngRPC backend\n\u00b6\n\n\nSince NGINX 1.13.10 it is possible to expose \ngRPC services natively\n\n\nYou only need to add the annotation \nnginx.ingress.kubernetes.io/grpc-backend: \"true\"\n to enable this feature. Additionally, if the gRPC service requires TLS \nnginx.ingress.kubernetes.io/secure-backends: \"true\"\n\n\n\n\nImportant\n\n\nThis feature requires HTTP2 to work which means we need to expose this service using HTTPS.\n\n\n\n\nExposing a gRPC service using HTTP is not supported.",
"title": "Annotations"
},
{
"location": "/user-guide/nginx-configuration/annotations/#annotations",
"text": "You can add these Kubernetes annotations to specific Ingress objects to customize their behavior. Tip Annotation keys and values can only be strings.\nOther types, such as boolean or numeric values must be quoted,\ni.e. \"true\" , \"false\" , \"100\" . Name type nginx.ingress.kubernetes.io/add-base-url \"true\" or \"false\" nginx.ingress.kubernetes.io/app-root string nginx.ingress.kubernetes.io/affinity cookie nginx.ingress.kubernetes.io/auth-realm string nginx.ingress.kubernetes.io/auth-secret string nginx.ingress.kubernetes.io/auth-type basic or digest nginx.ingress.kubernetes.io/auth-tls-secret string nginx.ingress.kubernetes.io/auth-tls-verify-depth number nginx.ingress.kubernetes.io/auth-tls-verify-client string nginx.ingress.kubernetes.io/auth-tls-error-page string nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream \"true\" or \"false\" nginx.ingress.kubernetes.io/auth-url string nginx.ingress.kubernetes.io/base-url-scheme string nginx.ingress.kubernetes.io/client-body-buffer-size string nginx.ingress.kubernetes.io/configuration-snippet string nginx.ingress.kubernetes.io/default-backend string nginx.ingress.kubernetes.io/enable-cors \"true\" or \"false\" nginx.ingress.kubernetes.io/cors-allow-origin string nginx.ingress.kubernetes.io/cors-allow-methods string nginx.ingress.kubernetes.io/cors-allow-headers string nginx.ingress.kubernetes.io/cors-allow-credentials \"true\" or \"false\" nginx.ingress.kubernetes.io/cors-max-age number nginx.ingress.kubernetes.io/force-ssl-redirect \"true\" or \"false\" nginx.ingress.kubernetes.io/from-to-www-redirect \"true\" or \"false\" nginx.ingress.kubernetes.io/grpc-backend \"true\" or \"false\" nginx.ingress.kubernetes.io/limit-connections number nginx.ingress.kubernetes.io/limit-rps number nginx.ingress.kubernetes.io/permanent-redirect string nginx.ingress.kubernetes.io/proxy-body-size string nginx.ingress.kubernetes.io/proxy-connect-timeout number nginx.ingress.kubernetes.io/proxy-send-timeout number nginx.ingress.kubernetes.io/proxy-read-timeout number nginx.ingress.kubernetes.io/proxy-next-upstream string nginx.ingress.kubernetes.io/proxy-next-upstream-tries number nginx.ingress.kubernetes.io/proxy-request-buffering string nginx.ingress.kubernetes.io/proxy-redirect-from string nginx.ingress.kubernetes.io/proxy-redirect-to string nginx.ingress.kubernetes.io/rewrite-log URI nginx.ingress.kubernetes.io/rewrite-target URI nginx.ingress.kubernetes.io/secure-backends \"true\" or \"false\" nginx.ingress.kubernetes.io/secure-verify-ca-secret string nginx.ingress.kubernetes.io/server-alias string nginx.ingress.kubernetes.io/server-snippet string nginx.ingress.kubernetes.io/service-upstream \"true\" or \"false\" nginx.ingress.kubernetes.io/session-cookie-name string nginx.ingress.kubernetes.io/session-cookie-hash string nginx.ingress.kubernetes.io/ssl-redirect \"true\" or \"false\" nginx.ingress.kubernetes.io/ssl-passthrough \"true\" or \"false\" nginx.ingress.kubernetes.io/upstream-max-fails number nginx.ingress.kubernetes.io/upstream-fail-timeout number nginx.ingress.kubernetes.io/upstream-hash-by string nginx.ingress.kubernetes.io/load-balance string nginx.ingress.kubernetes.io/upstream-vhost string nginx.ingress.kubernetes.io/whitelist-source-range CIDR nginx.ingress.kubernetes.io/proxy-buffering string nginx.ingress.kubernetes.io/ssl-ciphers string nginx.ingress.kubernetes.io/connection-proxy-header string nginx.ingress.kubernetes.io/enable-access-log \"true\" or \"false\" nginx.ingress.kubernetes.io/lua-resty-waf string nginx.ingress.kubernetes.io/lua-resty-waf-debug \"true\" or \"false\" nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets string nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules string",
"title": "Annotations"
},
{
"location": "/user-guide/nginx-configuration/annotations/#rewrite",
"text": "In some scenarios the exposed URL in the backend service differs from the specified path in the Ingress rule. Without a rewrite any request will return 404.\nSet the annotation nginx.ingress.kubernetes.io/rewrite-target to the path expected by the service. If the application contains relative links it is possible to add an additional annotation nginx.ingress.kubernetes.io/add-base-url that will prepend a base tag in the header of the returned HTML from the backend. If the scheme of base tag need to be specific, set the annotation nginx.ingress.kubernetes.io/base-url-scheme to the scheme such as http and https . If the Application Root is exposed in a different path and needs to be redirected, set the annotation nginx.ingress.kubernetes.io/app-root to redirect requests for / . Please check the rewrite example.",
"title": "Rewrite"
},
{
"location": "/user-guide/nginx-configuration/annotations/#session-affinity",
"text": "The annotation nginx.ingress.kubernetes.io/affinity enables and sets the affinity type in all Upstreams of an Ingress. This way, a request will always be directed to the same upstream server.\nThe only affinity type available for NGINX is cookie . Please check the affinity example.",
"title": "Session Affinity"
},
{
"location": "/user-guide/nginx-configuration/annotations/#authentication",
"text": "Is possible to add authentication adding additional annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords inside the key auth . The annotations are: nginx.ingress.kubernetes.io/auth-type: [basic|digest] Indicates the HTTP Authentication Type: Basic or Digest Access Authentication . nginx.ingress.kubernetes.io/auth-secret: secretName The name of the Secret that contains the usernames and passwords which are granted access to the path s defined in the Ingress rules.\nThis annotation also accepts the alternative form \"namespace/secretName\", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace. nginx.ingress.kubernetes.io/auth-realm: \"realm string\" Please check the auth example.",
"title": "Authentication"
},
{
"location": "/user-guide/nginx-configuration/annotations/#custom-nginx-upstream-checks",
"text": "NGINX exposes some flags in the upstream configuration that enable the configuration of each server in the upstream. The Ingress controller allows custom max_fails and fail_timeout parameters in a global context using upstream-max-fails and upstream-fail-timeout in the NGINX ConfigMap or in a particular Ingress rule. upstream-max-fails defaults to 0. This means NGINX will respect the container's readinessProbe if it is defined. If there is no probe and no values for upstream-max-fails NGINX will continue to send traffic to the container. Tip With the default configuration NGINX will not health check your backends. Whenever the endpoints controller notices a readiness probe failure, that pod's IP will be removed from the list of endpoints. This will trigger the NGINX controller to also remove it from the upstreams.** To use custom values in an Ingress rule define these annotations: nginx.ingress.kubernetes.io/upstream-max-fails : number of unsuccessful attempts to communicate with the server that should occur in the duration set by the upstream-fail-timeout parameter to consider the server unavailable. nginx.ingress.kubernetes.io/upstream-fail-timeout : time in seconds during which the specified number of unsuccessful attempts to communicate with the server should occur to consider the server unavailable. This is also the period of time the server will be considered unavailable. In NGINX, backend server pools are called \" upstreams \". Each upstream contains the endpoints for a service. An upstream is created for each service that has Ingress rules defined. Important All Ingress rules using the same service will use the same upstream. Only one of the Ingress rules should define annotations to configure the upstream servers. Please check the custom upstream check example.",
"title": "Custom NGINX upstream checks"
},
{
"location": "/user-guide/nginx-configuration/annotations/#custom-nginx-upstream-hashing",
"text": "NGINX supports load balancing by client-server mapping based on consistent hashing for a given key. The key can contain text, variables or any combination thereof. This feature allows for request stickiness other than client IP or cookies. The ketama consistent hashing method will be used which ensures only a few keys would be remapped to different servers on upstream group changes. To enable consistent hashing for a backend: nginx.ingress.kubernetes.io/upstream-hash-by : the nginx variable, text value or any combination thereof to use for consistent hashing. For example nginx.ingress.kubernetes.io/upstream-hash-by: \"$request_uri\" to consistently hash upstream requests by the current request URI.",
"title": "Custom NGINX upstream hashing"
},
{
"location": "/user-guide/nginx-configuration/annotations/#custom-nginx-load-balancing",
"text": "This is similar to (https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/nginx-configuration/configmap.md#load-balance) but configures load balancing algorithm per ingress. Note that nginx.ingress.kubernetes.io/upstream-hash-by takes preference over this. If this and nginx.ingress.kubernetes.io/upstream-hash-by are not set then we fallback to using globally configured load balancing algorithm.",
"title": "Custom NGINX load balancing"
},
{
"location": "/user-guide/nginx-configuration/annotations/#custom-nginx-upstream-vhost",
"text": "This configuration setting allows you to control the value for host in the following statement: proxy_set_header Host $host , which forms part of the location block. This is useful if you need to call the upstream server by something other than $host .",
"title": "Custom NGINX upstream vhost"
},
{
"location": "/user-guide/nginx-configuration/annotations/#client-certificate-authentication",
"text": "It is possible to enable Client Certificate Authentication using additional annotations in Ingress Rule. The annotations are: nginx.ingress.kubernetes.io/auth-tls-secret: secretName The name of the Secret that contains the full Certificate Authority chain ca.crt that is enabled to authenticate against this Ingress.\nThis annotation also accepts the alternative form \"namespace/secretName\", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace. nginx.ingress.kubernetes.io/auth-tls-verify-depth The validation depth between the provided client certificate and the Certification Authority chain. nginx.ingress.kubernetes.io/auth-tls-verify-client Enables verification of client certificates. nginx.ingress.kubernetes.io/auth-tls-error-page The URL/Page that user should be redirected in case of a Certificate Authentication Error nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream Indicates if the received certificates should be passed or not to the upstream server.\nBy default this is disabled. Please check the client-certs example. Important TLS with Client Authentication is NOT possible in Cloudflare as is not allowed it and might result in unexpected behavior. Cloudflare only allows Authenticated Origin Pulls and is required to use their own certificate: https://blog.cloudflare.com/protecting-the-origin-with-tls-authenticated-origin-pulls/ Only Authenticated Origin Pulls are allowed and can be configured by following their tutorial: https://support.cloudflare.com/hc/en-us/articles/204494148-Setting-up-NGINX-to-use-TLS-Authenticated-Origin-Pulls",
"title": "Client Certificate Authentication"
},
{
"location": "/user-guide/nginx-configuration/annotations/#configuration-snippet",
"text": "Using this annotation you can add additional configuration to the NGINX location. For example: nginx.ingress.kubernetes.io/configuration-snippet : | \n more_set_headers \"Request-Id: $req_id\";",
"title": "Configuration snippet"
},
{
"location": "/user-guide/nginx-configuration/annotations/#default-backend",
"text": "The ingress controller requires a default backend. This service handles the response when the service in the Ingress rule does not have endpoints.\nThis is a global configuration for the ingress controller. In some cases could be required to return a custom content or format. In this scenario we can use the annotation nginx.ingress.kubernetes.io/default-backend: <svc name> to specify a custom default backend.",
"title": "Default Backend"
},
{
"location": "/user-guide/nginx-configuration/annotations/#enable-cors",
"text": "To enable Cross-Origin Resource Sharing (CORS) in an Ingress rule add the annotation nginx.ingress.kubernetes.io/enable-cors: \"true\" . This will add a section in the server location enabling this functionality. CORS can be controlled with the following annotations: nginx.ingress.kubernetes.io/cors-allow-methods controls which methods are accepted. This is a multi-valued field, separated by ',' and accepts only letters (upper and lower case). Example: nginx.ingress.kubernetes.io/cors-allow-methods: \"PUT, GET, POST, OPTIONS\" nginx.ingress.kubernetes.io/cors-allow-headers controls which headers are accepted. This is a multi-valued field, separated by ',' and accepts letters, numbers, _ and -. Example: nginx.ingress.kubernetes.io/cors-allow-headers: \"X-Forwarded-For, X-app123-XPTO\" nginx.ingress.kubernetes.io/cors-allow-origin controls what's the accepted Origin for CORS and defaults to '*'. This is a single field value, with the following format: http(s)://origin-site.com or http(s)://origin-site.com:port Example: nginx.ingress.kubernetes.io/cors-allow-origin: \"https://origin-site.com:4443\" nginx.ingress.kubernetes.io/cors-allow-credentials controls if credentials can be passed during CORS operations. Example: nginx.ingress.kubernetes.io/cors-allow-credentials: \"true\" nginx.ingress.kubernetes.io/cors-max-age controls how long preflight requests can be cached. Example: nginx.ingress.kubernetes.io/cors-max-age: 600 For more information please see https://enable-cors.org",
"title": "Enable CORS"
},
{
"location": "/user-guide/nginx-configuration/annotations/#server-alias",
"text": "To add Server Aliases to an Ingress rule add the annotation nginx.ingress.kubernetes.io/server-alias: \"<alias>\" .\nThis will create a server with the same configuration, but a different server_name as the provided host. Note A server-alias name cannot conflict with the hostname of an existing server. If it does the server-alias annotation will be ignored. If a server-alias is created and later a new server with the same hostname is created the new server configuration will take place over the alias configuration. For more information please see http://nginx.org",
"title": "Server Alias"
},
{
"location": "/user-guide/nginx-configuration/annotations/#server-snippet",
"text": "Using the annotation nginx.ingress.kubernetes.io/server-snippet it is possible to add custom configuration in the server configuration block. apiVersion : extensions/v1beta1 kind : Ingress metadata : \n annotations : \n nginx.ingress.kubernetes.io/server-snippet : | set $agentflag 0; if ($http_user_agent ~* \"(Mobile)\" ){ \n set $agentflag 1; } if ( $agentflag = 1 ) { \n return 301 https://m.example.com; } Important This annotation can be used only once per host",
"title": "Server snippet"
},
{
"location": "/user-guide/nginx-configuration/annotations/#client-body-buffer-size",
"text": "Sets buffer size for reading client request body per location. In case the request body is larger than the buffer,\nthe whole body or only its part is written to a temporary file. By default, buffer size is equal to two memory pages.\nThis is 8K on x86, other 32-bit platforms, and x86-64. It is usually 16K on other 64-bit platforms. This annotation is\napplied to each location provided in the ingress rule. Note: The annotation value must be given in a valid format otherwise the\nFor example to set the client-body-buffer-size the following can be done: nginx.ingress.kubernetes.io/client-body-buffer-size: \"1000\" # 1000 bytes nginx.ingress.kubernetes.io/client-body-buffer-size: 1k # 1 kilobyte nginx.ingress.kubernetes.io/client-body-buffer-size: 1K # 1 kilobyte nginx.ingress.kubernetes.io/client-body-buffer-size: 1m # 1 megabyte nginx.ingress.kubernetes.io/client-body-buffer-size: 1M # 1 megabyte For more information please see http://nginx.org",
"title": "Client Body Buffer Size"
},
{
"location": "/user-guide/nginx-configuration/annotations/#external-authentication",
"text": "To use an existing service that provides authentication the Ingress rule can be annotated with nginx.ingress.kubernetes.io/auth-url to indicate the URL where the HTTP request should be sent. nginx.ingress.kubernetes.io/auth-url : \"URL to the authentication service\" Additionally it is possible to set: nginx.ingress.kubernetes.io/auth-method : <Method> to specify the HTTP method to use. nginx.ingress.kubernetes.io/auth-signin : <SignIn_URL> to specify the location of the error page. nginx.ingress.kubernetes.io/auth-response-headers : <Response_Header_1, ..., Response_Header_n> to specify headers to pass to backend once authorization request completes. nginx.ingress.kubernetes.io/auth-request-redirect : <Request_Redirect_URL> to specify the X-Auth-Request-Redirect header value. Please check the external-auth example.",
"title": "External Authentication"
},
{
"location": "/user-guide/nginx-configuration/annotations/#rate-limiting",
"text": "The annotations nginx.ingress.kubernetes.io/limit-connections , nginx.ingress.kubernetes.io/limit-rps , and nginx.ingress.kubernetes.io/limit-rpm define a limit on the connections that can be opened by a single client IP address. This can be used to mitigate DDoS Attacks . nginx.ingress.kubernetes.io/limit-connections : number of concurrent connections allowed from a single IP address. nginx.ingress.kubernetes.io/limit-rps : number of connections that may be accepted from a given IP each second. nginx.ingress.kubernetes.io/limit-rpm : number of connections that may be accepted from a given IP each minute. You can specify the client IP source ranges to be excluded from rate-limiting through the nginx.ingress.kubernetes.io/limit-whitelist annotation. The value is a comma separated list of CIDRs. If you specify multiple annotations in a single Ingress rule, limit-rpm , and then limit-rps takes precedence. The annotation nginx.ingress.kubernetes.io/limit-rate , nginx.ingress.kubernetes.io/limit-rate-after define a limit the rate of response transmission to a client. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit. nginx.ingress.kubernetes.io/limit-rate-after : sets the initial amount after which the further transmission of a response to a client will be rate limited. nginx.ingress.kubernetes.io/limit-rate : rate of request that accepted from a client each second. To configure this setting globally for all Ingress rules, the limit-rate-after and limit-rate value may be set in the NGINX ConfigMap. if you set the value in ingress annotation will cover global setting.",
"title": "Rate limiting"
},
{
"location": "/user-guide/nginx-configuration/annotations/#permanent-redirect",
"text": "This annotation allows to return a permanent redirect instead of sending data to the upstream. For example nginx.ingress.kubernetes.io/permanent-redirect: https://www.google.com would redirect everything to Google.",
"title": "Permanent Redirect"
},
{
"location": "/user-guide/nginx-configuration/annotations/#ssl-passthrough",
"text": "The annotation nginx.ingress.kubernetes.io/ssl-passthrough allows to configure TLS termination in the pod and not in NGINX. Important Using the annotation nginx.ingress.kubernetes.io/ssl-passthrough invalidates all the other available annotations. This is because SSL Passthrough works in L4 (TCP). The use of this annotation requires Proxy Protocol to be enabled in the load-balancer. For example enabling Proxy Protocol for AWS ELB is described here . If you're using ingress-controller without load balancer then the flag --enable-ssl-passthrough is required (by default it is disabled).",
"title": "SSL Passthrough"
},
{
"location": "/user-guide/nginx-configuration/annotations/#secure-backends",
"text": "By default NGINX uses http to reach the services. Adding the annotation nginx.ingress.kubernetes.io/secure-backends: \"true\" in the Ingress rule changes the protocol to https .\nIf you want to validate the upstream against a specific certificate, you can create a secret with it and reference the secret with the annotation nginx.ingress.kubernetes.io/secure-verify-ca-secret . Note that if an invalid or non-existent secret is given, the NGINX ingress controller will ignore the secure-backends annotation.",
"title": "Secure backends"
},
{
"location": "/user-guide/nginx-configuration/annotations/#service-upstream",
"text": "By default the NGINX ingress controller uses a list of all endpoints (Pod IP/port) in the NGINX upstream configuration. This annotation disables that behavior and instead uses a single upstream in NGINX, the service's Cluster IP and port. This can be desirable for things like zero-downtime deployments as it reduces the need to reload NGINX configuration when Pods come up and down. See issue #257 .",
"title": "Service Upstream"
},
{
"location": "/user-guide/nginx-configuration/annotations/#known-issues",
"text": "If the service-upstream annotation is specified the following things should be taken into consideration: Sticky Sessions will not work as only round-robin load balancing is supported. The proxy_next_upstream directive will not have any effect meaning on error the request will not be dispatched to another upstream.",
"title": "Known Issues"
},
{
"location": "/user-guide/nginx-configuration/annotations/#server-side-https-enforcement-through-redirect",
"text": "By default the controller redirects (301) to HTTPS if TLS is enabled for that ingress. If you want to disable that behavior globally, you can use ssl-redirect: \"false\" in the NGINX config map. To configure this feature for specific ingress resources, you can use the nginx.ingress.kubernetes.io/ssl-redirect: \"false\" annotation in the particular resource. When using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to HTTPS even when there is not TLS cert available. This can be achieved by using the nginx.ingress.kubernetes.io/force-ssl-redirect: \"true\" annotation in the particular resource.",
"title": "Server-side HTTPS enforcement through redirect"
},
{
"location": "/user-guide/nginx-configuration/annotations/#redirect-from-to-www",
"text": "In some scenarios is required to redirect from www.domain.com to domain.com or viceversa.\nTo enable this feature use the annotation nginx.ingress.kubernetes.io/from-to-www-redirect: \"true\" Important If at some point a new Ingress is created with a host equal to one of the options (like domain.com ) the annotation will be omitted.",
"title": "Redirect from to www"
},
{
"location": "/user-guide/nginx-configuration/annotations/#whitelist-source-range",
"text": "You can specify the allowed client IP source ranges through the nginx.ingress.kubernetes.io/whitelist-source-range annotation. The value is a comma separated list of CIDRs , e.g. 10.0.0.0/24,172.10.0.1 . To configure this setting globally for all Ingress rules, the whitelist-source-range value may be set in the NGINX ConfigMap. Note: Adding an annotation to an Ingress rule overrides any global restriction.",
"title": "Whitelist source range"
},
{
"location": "/user-guide/nginx-configuration/annotations/#cookie-affinity",
"text": "If you use the cookie type you can also specify the name of the cookie that will be used to route the requests with the annotation nginx.ingress.kubernetes.io/session-cookie-name . The default is to create a cookie named 'INGRESSCOOKIE'. In case of NGINX the annotation nginx.ingress.kubernetes.io/session-cookie-hash defines which algorithm will be used to 'hash' the used upstream. Default value is md5 and possible values are md5 , sha1 and index .\nThe index option is not hashed, an in-memory index is used instead, it's quicker and the overhead is shorter Warning: the matching against upstream servers list is inconsistent. So, at reload, if upstreams servers has changed, index values are not guaranteed to correspond to the same server as before! USE IT WITH CAUTION and only if you need to! In NGINX this feature is implemented by the third party module nginx-sticky-module-ng . The workflow used to define which upstream server will be used is explained here",
"title": "Cookie affinity"
},
{
"location": "/user-guide/nginx-configuration/annotations/#custom-timeouts",
"text": "Using the configuration configmap it is possible to set the default global timeout for connections to the upstream servers.\nIn some scenarios is required to have different values. To allow this we provide annotations that allows this customization: nginx.ingress.kubernetes.io/proxy-connect-timeout nginx.ingress.kubernetes.io/proxy-send-timeout nginx.ingress.kubernetes.io/proxy-read-timeout nginx.ingress.kubernetes.io/proxy-next-upstream nginx.ingress.kubernetes.io/proxy-next-upstream-tries nginx.ingress.kubernetes.io/proxy-request-buffering",
"title": "Custom timeouts"
},
{
"location": "/user-guide/nginx-configuration/annotations/#proxy-redirect",
"text": "With the annotations nginx.ingress.kubernetes.io/proxy-redirect-from and nginx.ingress.kubernetes.io/proxy-redirect-to it is possible to set the text that should be changed in the Location and Refresh header fields of a proxied server response (http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect)\nSetting \"off\" or \"default\" in the annotation nginx.ingress.kubernetes.io/proxy-redirect-from disables nginx.ingress.kubernetes.io/proxy-redirect-to \nBoth annotations will be used in any other case\nBy default the value is \"off\".",
"title": "Proxy redirect"
},
{
"location": "/user-guide/nginx-configuration/annotations/#custom-max-body-size",
"text": "For NGINX, 413 error will be returned to the client when the size in a request exceeds the maximum allowed size of the client request body. This size can be configured by the parameter client_max_body_size . To configure this setting globally for all Ingress rules, the proxy-body-size value may be set in the NGINX ConfigMap.\nTo use custom values in an Ingress rule define these annotation: nginx.ingress.kubernetes.io/proxy-body-size : 8m",
"title": "Custom max body size"
},
{
"location": "/user-guide/nginx-configuration/annotations/#proxy-buffering",
"text": "Enable or disable proxy buffering proxy_buffering .\nBy default proxy buffering is disabled in the nginx config. To configure this setting globally for all Ingress rules, the proxy-buffering value may be set in the NGINX ConfigMap.\nTo use custom values in an Ingress rule define these annotation: nginx.ingress.kubernetes.io/proxy-buffering : \"on\"",
"title": "Proxy buffering"
},
{
"location": "/user-guide/nginx-configuration/annotations/#ssl-ciphers",
"text": "Specifies the enabled ciphers . Using this annotation will set the ssl_ciphers directive at the server level. This configuration is active for all the paths in the host. nginx.ingress.kubernetes.io/ssl-ciphers : \"ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP\"",
"title": "SSL ciphers"
},
{
"location": "/user-guide/nginx-configuration/annotations/#connection-proxy-header",
"text": "Using this annotation will override the default connection header set by nginx. To use custom values in an Ingress rule, define the annotation: nginx.ingress.kubernetes.io/connection-proxy-header : \"keep-alive\"",
"title": "Connection proxy header"
},
{
"location": "/user-guide/nginx-configuration/annotations/#enable-access-log",
"text": "In some scenarios could be required to disable NGINX access logs. To enable this feature use the annotation: nginx.ingress.kubernetes.io/enable-access-log : \"false\"",
"title": "Enable Access Log"
},
{
"location": "/user-guide/nginx-configuration/annotations/#enable-rewrite-log",
"text": "In some scenarios it could be required to enable NGINX rewrite logs. Note that rewrite logs are sent to the error_log file at the notice level. To enable this feature use the annotation: nginx.ingress.kubernetes.io/enable-rewrite-log : \"true\"",
"title": "Enable Rewrite Log"
},
{
"location": "/user-guide/nginx-configuration/annotations/#lua-resty-waf",
"text": "Using lua-resty-waf-* annotations we can enable and control lua-resty-waf per location.\nFollowing configuration will enable WAF for the paths defined in the corresponding ingress: nginx.ingress.kubernetes.io/lua-resty-waf : \"active\" In order to run it in debugging mode you can set nginx.ingress.kubernetes.io/lua-resty-waf-debug to \"true\" in addition to the above configuration.\nThe other possible values for nginx.ingress.kubernetes.io/lua-resty-waf are inactive and simulate . In inactive mode WAF won't do anything, whereas\nin simulate mode it will log a warning message if there's a matching WAF rule for given request. This is useful to debug a rule and eliminate possible false positives before fully deploying it. lua-resty-waf comes with predefined set of rules https://github.com/p0pr0ck5/lua-resty-waf/tree/84b4f40362500dd0cb98b9e71b5875cb1a40f1ad/rules that covers ModSecurity CRS.\nYou can use nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets to ignore subset of those rulesets. For an example: nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets : \"41000_sqli, 42000_xss\" will ignore the two mentioned rulesets. It is also possible to configure custom WAF rules per ingress using nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules annotation. For an example the following snippet will\nconfigure a WAF rule to deny requests with query string value that contains word foo : nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules : '[=[ { \"access\": [ { \"actions\": { \"disrupt\" : \"DENY\" }, \"id\": 10001, \"msg\": \"my custom rule\", \"operator\": \"STR_CONTAINS\", \"pattern\": \"foo\", \"vars\": [ { \"parse\": [ \"values\", 1 ], \"type\": \"REQUEST_ARGS\" } ] } ], \"body_filter\": [], \"header_filter\":[] } ]=]' For details on how to write WAF rules, please refer to https://github.com/p0pr0ck5/lua-resty-waf .",
"title": "Lua Resty WAF"
},
{
"location": "/user-guide/nginx-configuration/annotations/#grpc-backend",
"text": "Since NGINX 1.13.10 it is possible to expose gRPC services natively You only need to add the annotation nginx.ingress.kubernetes.io/grpc-backend: \"true\" to enable this feature. Additionally, if the gRPC service requires TLS nginx.ingress.kubernetes.io/secure-backends: \"true\" Important This feature requires HTTP2 to work which means we need to expose this service using HTTPS. Exposing a gRPC service using HTTP is not supported.",
"title": "gRPC backend"
},
{
"location": "/user-guide/nginx-configuration/configmap/",
"text": "ConfigMaps\n\u00b6\n\n\nConfigMaps allow you to decouple configuration artifacts from image content to keep containerized applications portable.\n\n\nThe ConfigMap API resource stores configuration data as key-value pairs. The data provides the configurations for system\ncomponents for the nginx-controller. Before you can begin using a config-map it must be \ndeployed\n.\n\n\nIn order to overwrite nginx-controller configuration values as seen in \nconfig.go\n,\nyou can add key-value pairs to the data section of the config-map. For Example:\n\n\ndata\n:\n\n \nmap-hash-bucket-size\n:\n \n\"128\"\n\n \nssl-protocols\n:\n \nSSLv2\n\n\n\n\n\n\n\n\nImportant\n\n\nThe key and values in a ConfigMap can only be strings.\nThis means that we want a value with boolean values we need to quote the values, like \"true\" or \"false\".\nSame for numbers, like \"100\".\n\n\n\"Slice\" types (defined below as \n[]string\n or \n[]int\n can be provided as a comma-delimited string.\n\n\n\n\nConfiguration options\n\u00b6\n\n\nThe following table shows a configuration option's name, type, and the default value:\n\n\n\n\n\n\n\n\nname\n\n\ntype\n\n\ndefault\n\n\n\n\n\n\n\n\n\n\nadd-headers\n\n\nstring\n\n\n\"\"\n\n\n\n\n\n\nallow-backend-server-header\n\n\nbool\n\n\n\"false\"\n\n\n\n\n\n\nhide-headers\n\n\nstring array\n\n\nempty\n\n\n\n\n\n\naccess-log-path\n\n\nstring\n\n\n\"/var/log/nginx/access.log\"\n\n\n\n\n\n\nerror-log-path\n\n\nstring\n\n\n\"/var/log/nginx/error.log\"\n\n\n\n\n\n\nenable-dynamic-tls-records\n\n\nbool\n\n\n\"true\"\n\n\n\n\n\n\nenable-modsecurity\n\n\nbool\n\n\n\"false\"\n\n\n\n\n\n\nenable-owasp-modsecurity-crs\n\n\nbool\n\n\n\"false\"\n\n\n\n\n\n\nclient-header-buffer-size\n\n\nstring\n\n\n\"1k\"\n\n\n\n\n\n\nclient-header-timeout\n\n\nint\n\n\n60\n\n\n\n\n\n\nclient-body-buffer-size\n\n\nstring\n\n\n\"8k\"\n\n\n\n\n\n\nclient-body-timeout\n\n\nint\n\n\n60\n\n\n\n\n\n\ndisable-access-log\n\n\nbool\n\n\nfalse\n\n\n\n\n\n\ndisable-ipv6\n\n\nbool\n\n\nfalse\n\n\n\n\n\n\ndisable-ipv6-dns\n\n\nbool\n\n\nfalse\n\n\n\n\n\n\nenable-underscores-in-headers\n\n\nbool\n\n\nfalse\n\n\n\n\n\n\nignore-invalid-headers\n\n\nbool\n\n\ntrue\n\n\n\n\n\n\nenable-vts-status\n\n\nbool\n\n\nfalse\n\n\n\n\n\n\nvts-status-zone-size\n\n\nstring\n\n\n\"10m\"\n\n\n\n\n\n\nvts-sum-key\n\n\nstring\n\n\n\"*\"\n\n\n\n\n\n\nvts-default-filter-key\n\n\nstring\n\n\n\"$geoip_country_code country::*\"\n\n\n\n\n\n\nretry-non-idempotent\n\n\nbool\n\n\n\"false\"\n\n\n\n\n\n\nerror-log-level\n\n\nstring\n\n\n\"notice\"\n\n\n\n\n\n\nhttp2-max-field-size\n\n\nstring\n\n\n\"4k\"\n\n\n\n\n\n\nhttp2-max-header-size\n\n\nstring\n\n\n\"16k\"\n\n\n\n\n\n\nhsts\n\n\nbool\n\n\n\"true\"\n\n\n\n\n\n\nhsts-include-subdomains\n\n\nbool\n\n\n\"true\"\n\n\n\n\n\n\nhsts-max-age\n\n\nstring\n\n\n\"15724800\"\n\n\n\n\n\n\nhsts-preload\n\n\nbool\n\n\n\"false\"\n\n\n\n\n\n\nkeep-alive\n\n\nint\n\n\n75\n\n\n\n\n\n\nkeep-alive-requests\n\n\nint\n\n\n100\n\n\n\n\n\n\nlarge-client-header-buffers\n\n\nstring\n\n\n\"4 8k\"\n\n\n\n\n\n\nlog-format-escape-json\n\n\nbool\n\n\n\"false\"\n\n\n\n\n\n\nlog-format-upstream\n\n\nstring\n\n\n%v\n \n-\n \n[\n$the_real_ip\n]\n \n-\n \n$remote_user\n \n[\n$time_local\n]\n \n\"$request\"\n \n$status\n \n$body_bytes_sent\n \n\"$http_referer\"\n \n\"$http_user_agent\"\n \n$request_length\n \n$request_time\n \n[\n$proxy_upstream_name\n]\n \n$upstream_addr\n \n$upstream_response_length\n \n$upstream_response_time\n \n$upstream_status\n\n\n\n\n\n\nlog-format-stream\n\n\nstring\n\n\n[$time_local] $protocol $status $bytes_sent $bytes_received $session_time\n\n\n\n\n\n\nmax-worker-connections\n\n\nint\n\n\n16384\n\n\n\n\n\n\nmap-hash-bucket-size\n\n\nint\n\n\n64\n\n\n\n\n\n\nnginx-status-ipv4-whitelist\n\n\n[]string\n\n\n\"127.0.0.1\"\n\n\n\n\n\n\nnginx-status-ipv6-whitelist\n\n\n[]string\n\n\n\"::1\"\n\n\n\n\n\n\nproxy-real-ip-cidr\n\n\n[]string\n\n\n\"0.0.0.0/0\"\n\n\n\n\n\n\nproxy-set-headers\n\n\nstring\n\n\n\"\"\n\n\n\n\n\n\nserver-name-hash-max-size\n\n\nint\n\n\n1024\n\n\n\n\n\n\nserver-name-hash-bucket-size\n\n\nint\n\n\n<size of the processor\u2019s cache line>\n\n\n\n\n\n\nproxy-headers-hash-max-size\n\n\nint\n\n\n512\n\n\n\n\n\n\nproxy-headers-hash-bucket-size\n\n\nint\n\n\n64\n\n\n\n\n\n\nserver-tokens\n\n\nbool\n\n\n\"true\"\n\n\n\n\n\n\nssl-ciphers\n\n\nstring\n\n\n\"ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256\"\n\n\n\n\n\n\nssl-ecdh-curve\n\n\nstring\n\n\n\"auto\"\n\n\n\n\n\n\nssl-dh-param\n\n\nstring\n\n\n\"\"\n\n\n\n\n\n\nssl-protocols\n\n\nstring\n\n\n\"TLSv1.2\"\n\n\n\n\n\n\nssl-session-cache\n\n\nbool\n\n\n\"true\"\n\n\n\n\n\n\nssl-session-cache-size\n\n\nstring\n\n\n\"10m\"\n\n\n\n\n\n\nssl-session-tickets\n\n\nbool\n\n\n\"true\"\n\n\n\n\n\n\nssl-session-ticket-key\n\n\nstring\n\n\n<Randomly Generated>\n\n\n\n\n\n\nssl-session-timeout\n\n\nstring\n\n\n\"10m\"\n\n\n\n\n\n\nssl-buffer-size\n\n\nstring\n\n\n\"4k\"\n\n\n\n\n\n\nuse-proxy-protocol\n\n\nbool\n\n\n\"false\"\n\n\n\n\n\n\nuse-gzip\n\n\nbool\n\n\n\"true\"\n\n\n\n\n\n\nuse-geoip\n\n\nbool\n\n\n\"true\"\n\n\n\n\n\n\nenable-brotli\n\n\nbool\n\n\n\"true\"\n\n\n\n\n\n\nbrotli-level\n\n\nint\n\n\n4\n\n\n\n\n\n\nbrotli-types\n\n\nstring\n\n\n\"application/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component\"\n\n\n\n\n\n\nuse-http2\n\n\nbool\n\n\n\"true\"\n\n\n\n\n\n\ngzip-types\n\n\nstring\n\n\n\"application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component\"\n\n\n\n\n\n\nworker-processes\n\n\nstring\n\n\n<Number of CPUs>\n\n\n\n\n\n\nworker-cpu-affinity\n\n\nstring\n\n\n\"\"\n\n\n\n\n\n\nworker-shutdown-timeout\n\n\nstring\n\n\n\"10s\"\n\n\n\n\n\n\nload-balance\n\n\nstring\n\n\n\"least_conn\"\n\n\n\n\n\n\nvariables-hash-bucket-size\n\n\nint\n\n\n128\n\n\n\n\n\n\nvariables-hash-max-size\n\n\nint\n\n\n2048\n\n\n\n\n\n\nupstream-keepalive-connections\n\n\nint\n\n\n32\n\n\n\n\n\n\nlimit-conn-zone-variable\n\n\nstring\n\n\n\"$binary_remote_addr\"\n\n\n\n\n\n\nproxy-stream-timeout\n\n\nstring\n\n\n\"600s\"\n\n\n\n\n\n\nproxy-stream-responses\n\n\nint\n\n\n1\n\n\n\n\n\n\nbind-address-ipv4\n\n\n[]string\n\n\n\"\"\n\n\n\n\n\n\nbind-address-ipv6\n\n\n[]string\n\n\n\"\"\n\n\n\n\n\n\nforwarded-for-header\n\n\nstring\n\n\n\"X-Forwarded-For\"\n\n\n\n\n\n\ncompute-full-forwarded-for\n\n\nbool\n\n\n\"false\"\n\n\n\n\n\n\nproxy-add-original-uri-header\n\n\nbool\n\n\n\"true\"\n\n\n\n\n\n\nenable-opentracing\n\n\nbool\n\n\n\"false\"\n\n\n\n\n\n\nzipkin-collector-host\n\n\nstring\n\n\n\"\"\n\n\n\n\n\n\nzipkin-collector-port\n\n\nint\n\n\n9411\n\n\n\n\n\n\nzipkin-service-name\n\n\nstring\n\n\n\"nginx\"\n\n\n\n\n\n\njaeger-collector-host\n\n\nstring\n\n\n\"\"\n\n\n\n\n\n\njaeger-collector-port\n\n\nint\n\n\n6831\n\n\n\n\n\n\njaeger-service-name\n\n\nstring\n\n\n\"nginx\"\n\n\n\n\n\n\njaeger-sampler-type\n\n\nstring\n\n\n\"const\"\n\n\n\n\n\n\njaeger-sampler-param\n\n\nstring\n\n\n\"1\"\n\n\n\n\n\n\nhttp-snippet\n\n\nstring\n\n\n\"\"\n\n\n\n\n\n\nserver-snippet\n\n\nstring\n\n\n\"\"\n\n\n\n\n\n\nlocation-snippet\n\n\nstring\n\n\n\"\"\n\n\n\n\n\n\ncustom-http-errors\n\n\n[]int]\n\n\n[]int{}\n\n\n\n\n\n\nproxy-body-size\n\n\nstring\n\n\n\"1m\"\n\n\n\n\n\n\nproxy-connect-timeout\n\n\nint\n\n\n5\n\n\n\n\n\n\nproxy-read-timeout\n\n\nint\n\n\n60\n\n\n\n\n\n\nproxy-send-timeout\n\n\nint\n\n\n60\n\n\n\n\n\n\nproxy-buffer-size\n\n\nstring\n\n\n\"4k\"\n\n\n\n\n\n\nproxy-cookie-path\n\n\nstring\n\n\n\"off\"\n\n\n\n\n\n\nproxy-cookie-domain\n\n\nstring\n\n\n\"off\"\n\n\n\n\n\n\nproxy-next-upstream\n\n\nstring\n\n\n\"error timeout invalid_header http_502 http_503 http_504\"\n\n\n\n\n\n\nproxy-next-upstream-tries\n\n\nint\n\n\n0\n\n\n\n\n\n\nproxy-redirect-from\n\n\nstring\n\n\n\"off\"\n\n\n\n\n\n\nproxy-request-buffering\n\n\nstring\n\n\n\"on\"\n\n\n\n\n\n\nssl-redirect\n\n\nbool\n\n\n\"true\"\n\n\n\n\n\n\nwhitelist-source-range\n\n\n[]string\n\n\n[]string{}\n\n\n\n\n\n\nskip-access-log-urls\n\n\n[]string\n\n\n[]string{}\n\n\n\n\n\n\nlimit-rate\n\n\nint\n\n\n0\n\n\n\n\n\n\nlimit-rate-after\n\n\nint\n\n\n0\n\n\n\n\n\n\nhttp-redirect-code\n\n\nint\n\n\n308\n\n\n\n\n\n\nproxy-buffering\n\n\nstring\n\n\n\"off\"\n\n\n\n\n\n\nlimit-req-status-code\n\n\nint\n\n\n503\n\n\n\n\n\n\nno-tls-redirect-locations\n\n\nstring\n\n\n\"/.well-known/acme-challenge\"\n\n\n\n\n\n\nno-auth-locations\n\n\nstring\n\n\n\"/.well-known/acme-challenge\"\n\n\n\n\n\n\n\n\nadd-headers\n\u00b6\n\n\nSets custom headers from named configmap before sending traffic to the client. See \nproxy-set-headers\n. \nexample\n\n\nallow-backend-server-header\n\u00b6\n\n\nEnables the return of the header Server from the backend instead of the generic nginx string. \ndefault:\n is disabled\n\n\nhide-headers\n\u00b6\n\n\nSets additional header that will not be passed from the upstream server to the client response.\n\ndefault:\n empty\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_hide_header\n\n\naccess-log-path\n\u00b6\n\n\nAccess log path. Goes to \n/var/log/nginx/access.log\n by default.\n\n\nNote:\n the file \n/var/log/nginx/access.log\n is a symlink to \n/dev/stdout\n\n\nerror-log-path\n\u00b6\n\n\nError log path. Goes to \n/var/log/nginx/error.log\n by default.\n\n\nNote:\n the file \n/var/log/nginx/error.log\n is a symlink to \n/dev/stderr\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/ngx_core_module.html#error_log\n\n\nenable-dynamic-tls-records\n\u00b6\n\n\nEnables dynamically sized TLS records to improve time-to-first-byte. \ndefault:\n is enabled\n\n\nReferences:\n\n\nhttps://blog.cloudflare.com/optimizing-tls-over-tcp-to-reduce-latency\n\n\nenable-modsecurity\n\u00b6\n\n\nEnables the modsecurity module for NGINX. \ndefault:\n is disabled\n\n\nenable-owasp-modsecurity-crs\n\u00b6\n\n\nEnables the OWASP ModSecurity Core Rule Set (CRS). \ndefault:\n is disabled\n\n\nclient-header-buffer-size\n\u00b6\n\n\nAllows to configure a custom buffer size for reading client request header.\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/http/ngx_http_core_module.html#client_header_buffer_size\n\n\nclient-header-timeout\n\u00b6\n\n\nDefines a timeout for reading client request header, in seconds.\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/http/ngx_http_core_module.html#client_header_timeout\n\n\nclient-body-buffer-size\n\u00b6\n\n\nSets buffer size for reading client request body.\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size\n\n\nclient-body-timeout\n\u00b6\n\n\nDefines a timeout for reading client request body, in seconds.\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_timeout\n\n\ndisable-access-log\n\u00b6\n\n\nDisables the Access Log from the entire Ingress Controller. \ndefault:\n '\"false\"'\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/http/ngx_http_log_module.html#access_log\n\n\ndisable-ipv6\n\u00b6\n\n\nDisable listening on IPV6. \ndefault:\n is disabled\n\n\ndisable-ipv6-dns\n\u00b6\n\n\nDisable IPV6 for nginx DNS resolver. \ndefault:\n is disabled\n\n\nenable-underscores-in-headers\n\u00b6\n\n\nEnables underscores in header names. \ndefault:\n is disabled\n\n\nignore-invalid-headers\n\u00b6\n\n\nSet if header fields with invalid names should be ignored.\n\ndefault:\n is enabled\n\n\nenable-vts-status\n\u00b6\n\n\nAllows the replacement of the default status page with a third party module named \nnginx-module-vts\n.\n\ndefault:\n is disabled\n\n\nvts-status-zone-size\n\u00b6\n\n\nVts config on http level sets parameters for a shared memory zone that will keep states for various keys. The cache is shared between all worker processes. \ndefault:\n 10m\n\n\nReferences:\n\n\nhttps://github.com/vozlt/nginx-module-vts#vhost_traffic_status_zone\n\n\nvts-default-filter-key\n\u00b6\n\n\nVts config on http level enables the keys by user defined variable. The key is a key string to calculate traffic. The name is a group string to calculate traffic. The key and name can contain variables such as $host, $server_name. The name's group belongs to filterZones if specified. The key's group belongs to serverZones if not specified second argument name. \ndefault:\n $geoip_country_code country::*\n\n\nReferences:\n\n\nhttps://github.com/vozlt/nginx-module-vts#vhost_traffic_status_filter_by_set_key\n\n\nvts-sum-key\n\u00b6\n\n\nFor metrics keyed (or when using Prometheus, labeled) by server zone, this value is used to indicate metrics for all server zones combined. \ndefault:\n *\n\n\nReferences:\n\n\nhttps://github.com/vozlt/nginx-module-vts#vhost_traffic_status_display_sum_key\n\n\nretry-non-idempotent\n\u00b6\n\n\nSince 1.9.13 NGINX will not retry non-idempotent requests (POST, LOCK, PATCH) in case of an error in the upstream server. The previous behavior can be restored using the value \"true\".\n\n\nerror-log-level\n\u00b6\n\n\nConfigures the logging level of errors. Log levels above are listed in the order of increasing severity.\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/ngx_core_module.html#error_log\n\n\nhttp2-max-field-size\n\u00b6\n\n\nLimits the maximum size of an HPACK-compressed request header field.\n\n\nReferences:\n\n\nhttps://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_field_size\n\n\nhttp2-max-header-size\n\u00b6\n\n\nLimits the maximum size of the entire request header list after HPACK decompression.\n\n\nReferences:\n\n\nhttps://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_header_size\n\n\nhsts\n\u00b6\n\n\nEnables or disables the header HSTS in servers running SSL.\nHTTP Strict Transport Security (often abbreviated as HSTS) is a security feature (HTTP header) that tell browsers that it should only be communicated with using HTTPS, instead of using HTTP. It provides protection against protocol downgrade attacks and cookie theft.\n\n\nReferences:\n\n\n\n\nhttps://developer.mozilla.org/en-US/docs/Web/Security/HTTP_strict_transport_security\n\n\nhttps://blog.qualys.com/securitylabs/2016/03/28/the-importance-of-a-proper-http-strict-transport-security-implementation-on-your-web-server\n\n\n\n\nhsts-include-subdomains\n\u00b6\n\n\nEnables or disables the use of HSTS in all the subdomains of the server-name.\n\n\nhsts-max-age\n\u00b6\n\n\nSets the time, in seconds, that the browser should remember that this site is only to be accessed using HTTPS.\n\n\nhsts-preload\n\u00b6\n\n\nEnables or disables the preload attribute in the HSTS feature (when it is enabled) dd\n\n\nkeep-alive\n\u00b6\n\n\nSets the time during which a keep-alive client connection will stay open on the server side. The zero value disables keep-alive client connections.\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_timeout\n\n\nkeep-alive-requests\n\u00b6\n\n\nSets the maximum number of requests that can be served through one keep-alive connection.\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_requests\n\n\nlarge-client-header-buffers\n\u00b6\n\n\nSets the maximum number and size of buffers used for reading large client request header. \ndefault:\n 4 8k\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers\n\n\nlog-format-escape-json\n\u00b6\n\n\nSets if the escape parameter allows JSON (\"true\") or default characters escaping in variables (\"false\") Sets the nginx \nlog format\n.\n\n\nlog-format-upstream\n\u00b6\n\n\nSets the nginx \nlog format\n.\nExample for json output:\n\n\nconsolelog-format-upstream: '{ \"time\": \"$time_iso8601\", \"remote_addr\": \"$proxy_protocol_addr\",\"x-forward-for\": \"$proxy_add_x_forwarded_for\", \"request_id\": \"$req_id\", \"remote_user\":\"$remote_user\", \"bytes_sent\": $bytes_sent, \"request_time\": $request_time, \"status\":$status, \"vhost\": \"$host\", \"request_proto\": \"$server_protocol\", \"path\": \"$uri\",\"request_query\": \"$args\", \"request_length\": $request_length, \"duration\": $request_time,\"method\": \"$request_method\", \"http_referrer\": \"$http_referer\", \"http_user_agent\":\"$http_user_agent\" }'\n\n\nPlease check the \nlog-format\n for definition of each field.\n\n\nlog-format-stream\n\u00b6\n\n\nSets the nginx \nstream format\n.\n\n\nmax-worker-connections\n\u00b6\n\n\nSets the maximum number of simultaneous connections that can be opened by each \nworker process\n\n\nmap-hash-bucket-size\n\u00b6\n\n\nSets the bucket size for the \nmap variables hash tables\n. The details of setting up hash tables are provided in a separate \ndocument\n.\n\n\nproxy-real-ip-cidr\n\u00b6\n\n\nIf use-proxy-protocol is enabled, proxy-real-ip-cidr defines the default the IP/network address of your external load balancer.\n\n\nproxy-set-headers\n\u00b6\n\n\nSets custom headers from named configmap before sending traffic to backends. The value format is namespace/name. See \nexample\n\n\nserver-name-hash-max-size\n\u00b6\n\n\nSets the maximum size of the \nserver names hash tables\n used in server names,map directive\u2019s values, MIME types, names of request header strings, etc.\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/hash.html\n\n\nserver-name-hash-bucket-size\n\u00b6\n\n\nSets the size of the bucket for the server names hash tables.\n\n\nReferences:\n\n\n\n\nhttp://nginx.org/en/docs/hash.html\n\n\nhttp://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size\n\n\n\n\nproxy-headers-hash-max-size\n\u00b6\n\n\nSets the maximum size of the proxy headers hash tables.\n\n\nReferences:\n\n\n\n\nhttp://nginx.org/en/docs/hash.html\n\n\nhttps://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_max_size\n\n\n\n\nproxy-headers-hash-bucket-size\n\u00b6\n\n\nSets the size of the bucket for the proxy headers hash tables.\n\n\nReferences:\n\n\n\n\nhttp://nginx.org/en/docs/hash.html\n\n\nhttps://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_bucket_size\n\n\n\n\nserver-tokens\n\u00b6\n\n\nSend NGINX Server header in responses and display NGINX version in error pages. \ndefault:\n is enabled\n\n\nssl-ciphers\n\u00b6\n\n\nSets the \nciphers\n list to enable. The ciphers are specified in the format understood by the OpenSSL library.\n\n\nThe default cipher list is:\n \nECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256\n.\n\n\nThe ordering of a ciphersuite is very important because it decides which algorithms are going to be selected in priority. The recommendation above prioritizes algorithms that provide perfect \nforward secrecy\n.\n\n\nPlease check the \nMozilla SSL Configuration Generator\n.\n\n\nssl-ecdh-curve\n\u00b6\n\n\nSpecifies a curve for ECDHE ciphers.\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ecdh_curve\n\n\nssl-dh-param\n\u00b6\n\n\nSets the name of the secret that contains Diffie-Hellman key to help with \"Perfect Forward Secrecy\".\n\n\nReferences:\n\n\n\n\nhttps://wiki.openssl.org/index.php/Diffie-Hellman_parameters\n\n\nhttps://wiki.mozilla.org/Security/Server_Side_TLS#DHE_handshake_and_dhparam\n\n\nhttp://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam\n\n\n\n\nssl-protocols\n\u00b6\n\n\nSets the \nSSL protocols\n to use. The default is: \nTLSv1.2\n.\n\n\nPlease check the result of the configuration using \nhttps://ssllabs.com/ssltest/analyze.html\n or \nhttps://testssl.sh\n.\n\n\nssl-session-cache\n\u00b6\n\n\nEnables or disables the use of shared \nSSL cache\n among worker processes.\n\n\nssl-session-cache-size\n\u00b6\n\n\nSets the size of the \nSSL shared session cache\n between all worker processes.\n\n\nssl-session-tickets\n\u00b6\n\n\nEnables or disables session resumption through \nTLS session tickets\n.\n\n\nssl-session-ticket-key\n\u00b6\n\n\nSets the secret key used to encrypt and decrypt TLS session tickets. The value must be a valid base64 string.\n\n\nTLS session ticket-key\n, by default, a randomly generated key is used. To create a ticket: \nopenssl rand 80 | base64 -w0\n\n\nssl-session-timeout\n\u00b6\n\n\nSets the time during which a client may \nreuse the session\n parameters stored in a cache.\n\n\nssl-buffer-size\n\u00b6\n\n\nSets the size of the \nSSL buffer\n used for sending data. The default of 4k helps NGINX to improve TLS Time To First Byte (TTTFB).\n\n\nReferences:\n\n\nhttps://www.igvita.com/2013/12/16/optimizing-nginx-tls-time-to-first-byte/\n\n\nuse-proxy-protocol\n\u00b6\n\n\nEnables or disables the \nPROXY protocol\n to receive client connection (real IP address) information passed through proxy servers and load balancers such as HAProxy and Amazon Elastic Load Balancer (ELB).\n\n\nuse-gzip\n\u00b6\n\n\nEnables or disables compression of HTTP responses using the \n\"gzip\" module\n.\nThe default mime type list to compress is: \napplication/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component\n.\n\n\nuse-geoip\n\u00b6\n\n\nEnables or disables \n\"geoip\" module\n that creates variables with values depending on the client IP address, using the precompiled MaxMind databases.\n\ndefault:\n true\n\n\nenable-brotli\n\u00b6\n\n\nEnables or disables compression of HTTP responses using the \n\"brotli\" module\n.\nThe default mime type list to compress is: \napplication/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component\n. \ndefault:\n is disabled\n\n\n\n\nNote:\n Brotli does not works in Safari < 11. For more information see \nhttps://caniuse.com/#feat=brotli\n\n\n\n\nbrotli-level\n\u00b6\n\n\nSets the Brotli Compression Level that will be used. \ndefault:\n 4\n\n\nbrotli-types\n\u00b6\n\n\nSets the MIME Types that will be compressed on-the-fly by brotli.\n\ndefault:\n \napplication/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component\n\n\nuse-http2\n\u00b6\n\n\nEnables or disables \nHTTP/2\n support in secure connections.\n\n\ngzip-types\n\u00b6\n\n\nSets the MIME types in addition to \"text/html\" to compress. The special value \"*\" matches any MIME type. Responses with the \"text/html\" type are always compressed if \nuse-gzip\n is enabled.\n\n\nworker-processes\n\u00b6\n\n\nSets the number of \nworker processes\n.\nThe default of \"auto\" means number of available CPU cores.\n\n\nworker-cpu-affinity\n\u00b6\n\n\nBinds worker processes to the sets of CPUs. \nworker_cpu_affinity\n.\nBy default worker processes are not bound to any specific CPUs. The value can be:\n\n\n\n\n\"\": empty string indicate no affinity is applied.\n\n\ncpumask: e.g. \n0001 0010 0100 1000\n to bind processes to specific cpus.\n\n\nauto: binding worker processes automatically to available CPUs.\n\n\n\n\nworker-shutdown-timeout\n\u00b6\n\n\nSets a timeout for Nginx to \nwait for worker to gracefully shutdown\n. \ndefault:\n \"10s\"\n\n\nload-balance\n\u00b6\n\n\nSets the algorithm to use for load balancing.\nThe value can either be:\n\n\n\n\nround_robin: to use the default round robin loadbalancer\n\n\nleast_conn: to use the least connected method\n\n\nip_hash: to use a hash of the server for routing.\n\n\newma: to use the peak ewma method for routing (only available with \nenable-dynamic-configuration\n flag) \n\n\n\n\nThe default is least_conn.\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/http/load_balancing.html\n\n\nvariables-hash-bucket-size\n\u00b6\n\n\nSets the bucket size for the variables hash table.\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/http/ngx_http_map_module.html#variables_hash_bucket_size\n\n\nvariables-hash-max-size\n\u00b6\n\n\nSets the maximum size of the variables hash table.\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/http/ngx_http_map_module.html#variables_hash_max_size\n\n\nupstream-keepalive-connections\n\u00b6\n\n\nActivates the cache for connections to upstream servers. The connections parameter sets the maximum number of idle keepalive connections to upstream servers that are preserved in the cache of each worker process. When this\nnumber is exceeded, the least recently used connections are closed. \ndefault:\n 32\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive\n\n\nlimit-conn-zone-variable\n\u00b6\n\n\nSets parameters for a shared memory zone that will keep states for various keys of \nlimit_conn_zone\n. The default of \"$binary_remote_addr\" variable\u2019s size is always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses.\n\n\nproxy-stream-timeout\n\u00b6\n\n\nSets the timeout between two successive read or write operations on client or proxied server connections. If no data is transmitted within this time, the connection is closed.\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_timeout\n\n\nproxy-stream-responses\n\u00b6\n\n\nSets the number of datagrams expected from the proxied server in response to the client request if the UDP protocol is used.\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_responses\n\n\nbind-address-ipv4\n\u00b6\n\n\nSets the addresses on which the server will accept requests instead of *. It should be noted that these addresses must exist in the runtime environment or the controller will crash loop.\n\n\nbind-address-ipv6\n\u00b6\n\n\nSets the addresses on which the server will accept requests instead of *. It should be noted that these addresses must exist in the runtime environment or the controller will crash loop.\n\n\nforwarded-for-header\n\u00b6\n\n\nSets the header field for identifying the originating IP address of a client. \ndefault:\n X-Forwarded-For\n\n\ncompute-full-forwarded-for\n\u00b6\n\n\nAppend the remote address to the X-Forwarded-For header instead of replacing it. When this option is enabled, the upstream application is responsible for extracting the client IP based on its own list of trusted proxies.\n\n\nproxy-add-original-uri-header\n\u00b6\n\n\nAdds an X-Original-Uri header with the original request URI to the backend request\n\n\nenable-opentracing\n\u00b6\n\n\nEnables the nginx Opentracing extension. \ndefault:\n is disabled\n\n\nReferences:\n\n\nhttps://github.com/opentracing-contrib/nginx-opentracing\n\n\nzipkin-collector-host\n\u00b6\n\n\nSpecifies the host to use when uploading traces. It must be a valid URL.\n\n\nzipkin-collector-port\n\u00b6\n\n\nSpecifies the port to use when uploading traces. \ndefault:\n 9411\n\n\nzipkin-service-name\n\u00b6\n\n\nSpecifies the service name to use for any traces created. \ndefault:\n nginx\n\n\njaeger-collector-host\n\u00b6\n\n\nSpecifies the host to use when uploading traces. It must be a valid URL.\n\n\njaeger-collector-port\n\u00b6\n\n\nSpecifies the port to use when uploading traces. \ndefault:\n 6831\n\n\njaeger-service-name\n\u00b6\n\n\nSpecifies the service name to use for any traces created. \ndefault:\n nginx\n\n\njaeger-sampler-type\n\u00b6\n\n\nSpecifies the sampler to be used when sampling traces. The available samplers are: const, probabilistic, ratelimiting, remote. \ndefault:\n const\n\n\njaeger-sampler-param\n\u00b6\n\n\nSpecifies the argument to be passed to the sampler constructor. Must be a number.\nFor const this should be 0 to never sample and 1 to always sample. \ndefault:\n 1\n\n\nhttp-snippet\n\u00b6\n\n\nAdds custom configuration to the http section of the nginx configuration.\n\ndefault:\n \"\"\n\n\nserver-snippet\n\u00b6\n\n\nAdds custom configuration to all the servers in the nginx configuration.\n\ndefault:\n \"\"\n\n\nlocation-snippet\n\u00b6\n\n\nAdds custom configuration to all the locations in the nginx configuration.\n\ndefault:\n \"\"\n\n\ncustom-http-errors\n\u00b6\n\n\nEnables which HTTP codes should be passed for processing with the \nerror_page directive\n\n\nSetting at least one code also enables \nproxy_intercept_errors\n which are required to process error_page.\n\n\nExample usage: \ncustom-http-errors: 404,415\n\n\nproxy-body-size\n\u00b6\n\n\nSets the maximum allowed size of the client request body.\nSee NGINX \nclient_max_body_size\n.\n\n\nproxy-connect-timeout\n\u00b6\n\n\nSets the timeout for \nestablishing a connection with a proxied server\n. It should be noted that this timeout cannot usually exceed 75 seconds.\n\n\nproxy-read-timeout\n\u00b6\n\n\nSets the timeout in seconds for \nreading a response from the proxied server\n. The timeout is set only between two successive read operations, not for the transmission of the whole response.\n\n\nproxy-send-timeout\n\u00b6\n\n\nSets the timeout in seconds for \ntransmitting a request to the proxied server\n. The timeout is set only between two successive write operations, not for the transmission of the whole request.\n\n\nproxy-buffer-size\n\u00b6\n\n\nSets the size of the buffer used for \nreading the first part of the response\n received from the proxied server. This part usually contains a small response header.\n\n\nproxy-cookie-path\n\u00b6\n\n\nSets a text that \nshould be changed in the path attribute\n of the \u201cSet-Cookie\u201d header fields of a proxied server response.\n\n\nproxy-cookie-domain\n\u00b6\n\n\nSets a text that \nshould be changed in the domain attribute\n of the \u201cSet-Cookie\u201d header fields of a proxied server response.\n\n\nproxy-next-upstream\n\u00b6\n\n\nSpecifies in \nwhich cases\n a request should be passed to the next server.\n\n\nproxy-next-upstream-tries\n\u00b6\n\n\nLimit the number of \npossible tries\n a request should be passed to the next server.\n\n\nproxy-redirect-from\n\u00b6\n\n\nSets the original text that should be changed in the \"Location\" and \"Refresh\" header fields of a proxied server response. \ndefault:\n off\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect\n\n\nproxy-request-buffering\n\u00b6\n\n\nEnables or disables \nbuffering of a client request body\n.\n\n\nssl-redirect\n\u00b6\n\n\nSets the global value of redirects (301) to HTTPS if the server has a TLS certificate (defined in an Ingress rule).\n\ndefault:\n \"true\"\n\n\nwhitelist-source-range\n\u00b6\n\n\nSets the default whitelisted IPs for each \nserver\n block. This can be overwritten by an annotation on an Ingress rule.\nSee \nngx_http_access_module\n.\n\n\nskip-access-log-urls\n\u00b6\n\n\nSets a list of URLs that should not appear in the NGINX access log. This is useful with urls like \n/health\n or \nhealth-check\n that make \"complex\" reading the logs. \ndefault:\n is empty\n\n\nlimit-rate\n\u00b6\n\n\nLimits the rate of response transmission to a client. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit.\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/http/ngx_http_core_module.html#limit_rate\n\n\nlimit-rate-after\n\u00b6\n\n\nSets the initial amount after which the further transmission of a response to a client will be rate limited.\n\n\nReferences:\n\n\nhttp://nginx.org/en/docs/http/ngx_http_core_module.html#limit_rate_after\n\n\nhttp-redirect-code\n\u00b6\n\n\nSets the HTTP status code to be used in redirects.\nSupported codes are \n301\n,\n302\n,\n307\n and \n308\n\n\ndefault:\n 308\n\n\n\n\nWhy the default code is 308?\n\n\nRFC 7238\n was created to define the 308 (Permanent Redirect) status code that is similar to 301 (Moved Permanently) but it keeps the payload in the redirect. This is important if the we send a redirect in methods like POST.\n\n\n\n\nproxy-buffering\n\u00b6\n\n\nEnables or disables \nbuffering of responses from the proxied server\n.\n\n\nlimit-req-status-code\n\u00b6\n\n\nSets the \nstatus code to return in response to rejected requests\n. \ndefault:\n 503\n\n\nno-tls-redirect-locations\n\u00b6\n\n\nA comma-separated list of locations on which http requests will never get redirected to their https counterpart.\n\ndefault:\n \"/.well-known/acme-challenge\"\n\n\nno-auth-locations\n\u00b6\n\n\nA comma-separated list of locations that should not get authenticated.\n\ndefault:\n \"/.well-known/acme-challenge\"",
"title": "ConfigMaps"
},
{
"location": "/user-guide/nginx-configuration/configmap/#configmaps",
"text": "ConfigMaps allow you to decouple configuration artifacts from image content to keep containerized applications portable. The ConfigMap API resource stores configuration data as key-value pairs. The data provides the configurations for system\ncomponents for the nginx-controller. Before you can begin using a config-map it must be deployed . In order to overwrite nginx-controller configuration values as seen in config.go ,\nyou can add key-value pairs to the data section of the config-map. For Example: data : \n map-hash-bucket-size : \"128\" \n ssl-protocols : SSLv2 Important The key and values in a ConfigMap can only be strings.\nThis means that we want a value with boolean values we need to quote the values, like \"true\" or \"false\".\nSame for numbers, like \"100\". \"Slice\" types (defined below as []string or []int can be provided as a comma-delimited string.",
"title": "ConfigMaps"
},
{
"location": "/user-guide/nginx-configuration/configmap/#configuration-options",
"text": "The following table shows a configuration option's name, type, and the default value: name type default add-headers string \"\" allow-backend-server-header bool \"false\" hide-headers string array empty access-log-path string \"/var/log/nginx/access.log\" error-log-path string \"/var/log/nginx/error.log\" enable-dynamic-tls-records bool \"true\" enable-modsecurity bool \"false\" enable-owasp-modsecurity-crs bool \"false\" client-header-buffer-size string \"1k\" client-header-timeout int 60 client-body-buffer-size string \"8k\" client-body-timeout int 60 disable-access-log bool false disable-ipv6 bool false disable-ipv6-dns bool false enable-underscores-in-headers bool false ignore-invalid-headers bool true enable-vts-status bool false vts-status-zone-size string \"10m\" vts-sum-key string \"*\" vts-default-filter-key string \"$geoip_country_code country::*\" retry-non-idempotent bool \"false\" error-log-level string \"notice\" http2-max-field-size string \"4k\" http2-max-header-size string \"16k\" hsts bool \"true\" hsts-include-subdomains bool \"true\" hsts-max-age string \"15724800\" hsts-preload bool \"false\" keep-alive int 75 keep-alive-requests int 100 large-client-header-buffers string \"4 8k\" log-format-escape-json bool \"false\" log-format-upstream string %v - [ $the_real_ip ] - $remote_user [ $time_local ] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" $request_length $request_time [ $proxy_upstream_name ] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status log-format-stream string [$time_local] $protocol $status $bytes_sent $bytes_received $session_time max-worker-connections int 16384 map-hash-bucket-size int 64 nginx-status-ipv4-whitelist []string \"127.0.0.1\" nginx-status-ipv6-whitelist []string \"::1\" proxy-real-ip-cidr []string \"0.0.0.0/0\" proxy-set-headers string \"\" server-name-hash-max-size int 1024 server-name-hash-bucket-size int <size of the processor\u2019s cache line> proxy-headers-hash-max-size int 512 proxy-headers-hash-bucket-size int 64 server-tokens bool \"true\" ssl-ciphers string \"ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256\" ssl-ecdh-curve string \"auto\" ssl-dh-param string \"\" ssl-protocols string \"TLSv1.2\" ssl-session-cache bool \"true\" ssl-session-cache-size string \"10m\" ssl-session-tickets bool \"true\" ssl-session-ticket-key string <Randomly Generated> ssl-session-timeout string \"10m\" ssl-buffer-size string \"4k\" use-proxy-protocol bool \"false\" use-gzip bool \"true\" use-geoip bool \"true\" enable-brotli bool \"true\" brotli-level int 4 brotli-types string \"application/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component\" use-http2 bool \"true\" gzip-types string \"application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component\" worker-processes string <Number of CPUs> worker-cpu-affinity string \"\" worker-shutdown-timeout string \"10s\" load-balance string \"least_conn\" variables-hash-bucket-size int 128 variables-hash-max-size int 2048 upstream-keepalive-connections int 32 limit-conn-zone-variable string \"$binary_remote_addr\" proxy-stream-timeout string \"600s\" proxy-stream-responses int 1 bind-address-ipv4 []string \"\" bind-address-ipv6 []string \"\" forwarded-for-header string \"X-Forwarded-For\" compute-full-forwarded-for bool \"false\" proxy-add-original-uri-header bool \"true\" enable-opentracing bool \"false\" zipkin-collector-host string \"\" zipkin-collector-port int 9411 zipkin-service-name string \"nginx\" jaeger-collector-host string \"\" jaeger-collector-port int 6831 jaeger-service-name string \"nginx\" jaeger-sampler-type string \"const\" jaeger-sampler-param string \"1\" http-snippet string \"\" server-snippet string \"\" location-snippet string \"\" custom-http-errors []int] []int{} proxy-body-size string \"1m\" proxy-connect-timeout int 5 proxy-read-timeout int 60 proxy-send-timeout int 60 proxy-buffer-size string \"4k\" proxy-cookie-path string \"off\" proxy-cookie-domain string \"off\" proxy-next-upstream string \"error timeout invalid_header http_502 http_503 http_504\" proxy-next-upstream-tries int 0 proxy-redirect-from string \"off\" proxy-request-buffering string \"on\" ssl-redirect bool \"true\" whitelist-source-range []string []string{} skip-access-log-urls []string []string{} limit-rate int 0 limit-rate-after int 0 http-redirect-code int 308 proxy-buffering string \"off\" limit-req-status-code int 503 no-tls-redirect-locations string \"/.well-known/acme-challenge\" no-auth-locations string \"/.well-known/acme-challenge\"",
"title": "Configuration options"
},
{
"location": "/user-guide/nginx-configuration/configmap/#add-headers",
"text": "Sets custom headers from named configmap before sending traffic to the client. See proxy-set-headers . example",
"title": "add-headers"
},
{
"location": "/user-guide/nginx-configuration/configmap/#allow-backend-server-header",
"text": "Enables the return of the header Server from the backend instead of the generic nginx string. default: is disabled",
"title": "allow-backend-server-header"
},
{
"location": "/user-guide/nginx-configuration/configmap/#hide-headers",
"text": "Sets additional header that will not be passed from the upstream server to the client response. default: empty References: http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_hide_header",
"title": "hide-headers"
},
{
"location": "/user-guide/nginx-configuration/configmap/#access-log-path",
"text": "Access log path. Goes to /var/log/nginx/access.log by default. Note: the file /var/log/nginx/access.log is a symlink to /dev/stdout",
"title": "access-log-path"
},
{
"location": "/user-guide/nginx-configuration/configmap/#error-log-path",
"text": "Error log path. Goes to /var/log/nginx/error.log by default. Note: the file /var/log/nginx/error.log is a symlink to /dev/stderr References: http://nginx.org/en/docs/ngx_core_module.html#error_log",
"title": "error-log-path"
},
{
"location": "/user-guide/nginx-configuration/configmap/#enable-dynamic-tls-records",
"text": "Enables dynamically sized TLS records to improve time-to-first-byte. default: is enabled References: https://blog.cloudflare.com/optimizing-tls-over-tcp-to-reduce-latency",
"title": "enable-dynamic-tls-records"
},
{
"location": "/user-guide/nginx-configuration/configmap/#enable-modsecurity",
"text": "Enables the modsecurity module for NGINX. default: is disabled",
"title": "enable-modsecurity"
},
{
"location": "/user-guide/nginx-configuration/configmap/#enable-owasp-modsecurity-crs",
"text": "Enables the OWASP ModSecurity Core Rule Set (CRS). default: is disabled",
"title": "enable-owasp-modsecurity-crs"
},
{
"location": "/user-guide/nginx-configuration/configmap/#client-header-buffer-size",
"text": "Allows to configure a custom buffer size for reading client request header. References: http://nginx.org/en/docs/http/ngx_http_core_module.html#client_header_buffer_size",
"title": "client-header-buffer-size"
},
{
"location": "/user-guide/nginx-configuration/configmap/#client-header-timeout",
"text": "Defines a timeout for reading client request header, in seconds. References: http://nginx.org/en/docs/http/ngx_http_core_module.html#client_header_timeout",
"title": "client-header-timeout"
},
{
"location": "/user-guide/nginx-configuration/configmap/#client-body-buffer-size",
"text": "Sets buffer size for reading client request body. References: http://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size",
"title": "client-body-buffer-size"
},
{
"location": "/user-guide/nginx-configuration/configmap/#client-body-timeout",
"text": "Defines a timeout for reading client request body, in seconds. References: http://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_timeout",
"title": "client-body-timeout"
},
{
"location": "/user-guide/nginx-configuration/configmap/#disable-access-log",
"text": "Disables the Access Log from the entire Ingress Controller. default: '\"false\"' References: http://nginx.org/en/docs/http/ngx_http_log_module.html#access_log",
"title": "disable-access-log"
},
{
"location": "/user-guide/nginx-configuration/configmap/#disable-ipv6",
"text": "Disable listening on IPV6. default: is disabled",
"title": "disable-ipv6"
},
{
"location": "/user-guide/nginx-configuration/configmap/#disable-ipv6-dns",
"text": "Disable IPV6 for nginx DNS resolver. default: is disabled",
"title": "disable-ipv6-dns"
},
{
"location": "/user-guide/nginx-configuration/configmap/#enable-underscores-in-headers",
"text": "Enables underscores in header names. default: is disabled",
"title": "enable-underscores-in-headers"
},
{
"location": "/user-guide/nginx-configuration/configmap/#ignore-invalid-headers",
"text": "Set if header fields with invalid names should be ignored. default: is enabled",
"title": "ignore-invalid-headers"
},
{
"location": "/user-guide/nginx-configuration/configmap/#enable-vts-status",
"text": "Allows the replacement of the default status page with a third party module named nginx-module-vts . default: is disabled",
"title": "enable-vts-status"
},
{
"location": "/user-guide/nginx-configuration/configmap/#vts-status-zone-size",
"text": "Vts config on http level sets parameters for a shared memory zone that will keep states for various keys. The cache is shared between all worker processes. default: 10m References: https://github.com/vozlt/nginx-module-vts#vhost_traffic_status_zone",
"title": "vts-status-zone-size"
},
{
"location": "/user-guide/nginx-configuration/configmap/#vts-default-filter-key",
"text": "Vts config on http level enables the keys by user defined variable. The key is a key string to calculate traffic. The name is a group string to calculate traffic. The key and name can contain variables such as $host, $server_name. The name's group belongs to filterZones if specified. The key's group belongs to serverZones if not specified second argument name. default: $geoip_country_code country::* References: https://github.com/vozlt/nginx-module-vts#vhost_traffic_status_filter_by_set_key",
"title": "vts-default-filter-key"
},
{
"location": "/user-guide/nginx-configuration/configmap/#vts-sum-key",
"text": "For metrics keyed (or when using Prometheus, labeled) by server zone, this value is used to indicate metrics for all server zones combined. default: * References: https://github.com/vozlt/nginx-module-vts#vhost_traffic_status_display_sum_key",
"title": "vts-sum-key"
},
{
"location": "/user-guide/nginx-configuration/configmap/#retry-non-idempotent",
"text": "Since 1.9.13 NGINX will not retry non-idempotent requests (POST, LOCK, PATCH) in case of an error in the upstream server. The previous behavior can be restored using the value \"true\".",
"title": "retry-non-idempotent"
},
{
"location": "/user-guide/nginx-configuration/configmap/#error-log-level",
"text": "Configures the logging level of errors. Log levels above are listed in the order of increasing severity. References: http://nginx.org/en/docs/ngx_core_module.html#error_log",
"title": "error-log-level"
},
{
"location": "/user-guide/nginx-configuration/configmap/#http2-max-field-size",
"text": "Limits the maximum size of an HPACK-compressed request header field. References: https://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_field_size",
"title": "http2-max-field-size"
},
{
"location": "/user-guide/nginx-configuration/configmap/#http2-max-header-size",
"text": "Limits the maximum size of the entire request header list after HPACK decompression. References: https://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_header_size",
"title": "http2-max-header-size"
},
{
"location": "/user-guide/nginx-configuration/configmap/#hsts",
"text": "Enables or disables the header HSTS in servers running SSL.\nHTTP Strict Transport Security (often abbreviated as HSTS) is a security feature (HTTP header) that tell browsers that it should only be communicated with using HTTPS, instead of using HTTP. It provides protection against protocol downgrade attacks and cookie theft. References: https://developer.mozilla.org/en-US/docs/Web/Security/HTTP_strict_transport_security https://blog.qualys.com/securitylabs/2016/03/28/the-importance-of-a-proper-http-strict-transport-security-implementation-on-your-web-server",
"title": "hsts"
},
{
"location": "/user-guide/nginx-configuration/configmap/#hsts-include-subdomains",
"text": "Enables or disables the use of HSTS in all the subdomains of the server-name.",
"title": "hsts-include-subdomains"
},
{
"location": "/user-guide/nginx-configuration/configmap/#hsts-max-age",
"text": "Sets the time, in seconds, that the browser should remember that this site is only to be accessed using HTTPS.",
"title": "hsts-max-age"
},
{
"location": "/user-guide/nginx-configuration/configmap/#hsts-preload",
"text": "Enables or disables the preload attribute in the HSTS feature (when it is enabled) dd",
"title": "hsts-preload"
},
{
"location": "/user-guide/nginx-configuration/configmap/#keep-alive",
"text": "Sets the time during which a keep-alive client connection will stay open on the server side. The zero value disables keep-alive client connections. References: http://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_timeout",
"title": "keep-alive"
},
{
"location": "/user-guide/nginx-configuration/configmap/#keep-alive-requests",
"text": "Sets the maximum number of requests that can be served through one keep-alive connection. References: http://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_requests",
"title": "keep-alive-requests"
},
{
"location": "/user-guide/nginx-configuration/configmap/#large-client-header-buffers",
"text": "Sets the maximum number and size of buffers used for reading large client request header. default: 4 8k References: http://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers",
"title": "large-client-header-buffers"
},
{
"location": "/user-guide/nginx-configuration/configmap/#log-format-escape-json",
"text": "Sets if the escape parameter allows JSON (\"true\") or default characters escaping in variables (\"false\") Sets the nginx log format .",
"title": "log-format-escape-json"
},
{
"location": "/user-guide/nginx-configuration/configmap/#log-format-upstream",
"text": "Sets the nginx log format .\nExample for json output: consolelog-format-upstream: '{ \"time\": \"$time_iso8601\", \"remote_addr\": \"$proxy_protocol_addr\",\"x-forward-for\": \"$proxy_add_x_forwarded_for\", \"request_id\": \"$req_id\", \"remote_user\":\"$remote_user\", \"bytes_sent\": $bytes_sent, \"request_time\": $request_time, \"status\":$status, \"vhost\": \"$host\", \"request_proto\": \"$server_protocol\", \"path\": \"$uri\",\"request_query\": \"$args\", \"request_length\": $request_length, \"duration\": $request_time,\"method\": \"$request_method\", \"http_referrer\": \"$http_referer\", \"http_user_agent\":\"$http_user_agent\" }' Please check the log-format for definition of each field.",
"title": "log-format-upstream"
},
{
"location": "/user-guide/nginx-configuration/configmap/#log-format-stream",
"text": "Sets the nginx stream format .",
"title": "log-format-stream"
},
{
"location": "/user-guide/nginx-configuration/configmap/#max-worker-connections",
"text": "Sets the maximum number of simultaneous connections that can be opened by each worker process",
"title": "max-worker-connections"
},
{
"location": "/user-guide/nginx-configuration/configmap/#map-hash-bucket-size",
"text": "Sets the bucket size for the map variables hash tables . The details of setting up hash tables are provided in a separate document .",
"title": "map-hash-bucket-size"
},
{
"location": "/user-guide/nginx-configuration/configmap/#proxy-real-ip-cidr",
"text": "If use-proxy-protocol is enabled, proxy-real-ip-cidr defines the default the IP/network address of your external load balancer.",
"title": "proxy-real-ip-cidr"
},
{
"location": "/user-guide/nginx-configuration/configmap/#proxy-set-headers",
"text": "Sets custom headers from named configmap before sending traffic to backends. The value format is namespace/name. See example",
"title": "proxy-set-headers"
},
{
"location": "/user-guide/nginx-configuration/configmap/#server-name-hash-max-size",
"text": "Sets the maximum size of the server names hash tables used in server names,map directive\u2019s values, MIME types, names of request header strings, etc. References: http://nginx.org/en/docs/hash.html",
"title": "server-name-hash-max-size"
},
{
"location": "/user-guide/nginx-configuration/configmap/#server-name-hash-bucket-size",
"text": "Sets the size of the bucket for the server names hash tables. References: http://nginx.org/en/docs/hash.html http://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size",
"title": "server-name-hash-bucket-size"
},
{
"location": "/user-guide/nginx-configuration/configmap/#proxy-headers-hash-max-size",
"text": "Sets the maximum size of the proxy headers hash tables. References: http://nginx.org/en/docs/hash.html https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_max_size",
"title": "proxy-headers-hash-max-size"
},
{
"location": "/user-guide/nginx-configuration/configmap/#proxy-headers-hash-bucket-size",
"text": "Sets the size of the bucket for the proxy headers hash tables. References: http://nginx.org/en/docs/hash.html https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_headers_hash_bucket_size",
"title": "proxy-headers-hash-bucket-size"
},
{
"location": "/user-guide/nginx-configuration/configmap/#server-tokens",
"text": "Send NGINX Server header in responses and display NGINX version in error pages. default: is enabled",
"title": "server-tokens"
},
{
"location": "/user-guide/nginx-configuration/configmap/#ssl-ciphers",
"text": "Sets the ciphers list to enable. The ciphers are specified in the format understood by the OpenSSL library. The default cipher list is:\n ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256 . The ordering of a ciphersuite is very important because it decides which algorithms are going to be selected in priority. The recommendation above prioritizes algorithms that provide perfect forward secrecy . Please check the Mozilla SSL Configuration Generator .",
"title": "ssl-ciphers"
},
{
"location": "/user-guide/nginx-configuration/configmap/#ssl-ecdh-curve",
"text": "Specifies a curve for ECDHE ciphers. References: http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ecdh_curve",
"title": "ssl-ecdh-curve"
},
{
"location": "/user-guide/nginx-configuration/configmap/#ssl-dh-param",
"text": "Sets the name of the secret that contains Diffie-Hellman key to help with \"Perfect Forward Secrecy\". References: https://wiki.openssl.org/index.php/Diffie-Hellman_parameters https://wiki.mozilla.org/Security/Server_Side_TLS#DHE_handshake_and_dhparam http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam",
"title": "ssl-dh-param"
},
{
"location": "/user-guide/nginx-configuration/configmap/#ssl-protocols",
"text": "Sets the SSL protocols to use. The default is: TLSv1.2 . Please check the result of the configuration using https://ssllabs.com/ssltest/analyze.html or https://testssl.sh .",
"title": "ssl-protocols"
},
{
"location": "/user-guide/nginx-configuration/configmap/#ssl-session-cache",
"text": "Enables or disables the use of shared SSL cache among worker processes.",
"title": "ssl-session-cache"
},
{
"location": "/user-guide/nginx-configuration/configmap/#ssl-session-cache-size",
"text": "Sets the size of the SSL shared session cache between all worker processes.",
"title": "ssl-session-cache-size"
},
{
"location": "/user-guide/nginx-configuration/configmap/#ssl-session-tickets",
"text": "Enables or disables session resumption through TLS session tickets .",
"title": "ssl-session-tickets"
},
{
"location": "/user-guide/nginx-configuration/configmap/#ssl-session-ticket-key",
"text": "Sets the secret key used to encrypt and decrypt TLS session tickets. The value must be a valid base64 string. TLS session ticket-key , by default, a randomly generated key is used. To create a ticket: openssl rand 80 | base64 -w0",
"title": "ssl-session-ticket-key"
},
{
"location": "/user-guide/nginx-configuration/configmap/#ssl-session-timeout",
"text": "Sets the time during which a client may reuse the session parameters stored in a cache.",
"title": "ssl-session-timeout"
},
{
"location": "/user-guide/nginx-configuration/configmap/#ssl-buffer-size",
"text": "Sets the size of the SSL buffer used for sending data. The default of 4k helps NGINX to improve TLS Time To First Byte (TTTFB). References: https://www.igvita.com/2013/12/16/optimizing-nginx-tls-time-to-first-byte/",
"title": "ssl-buffer-size"
},
{
"location": "/user-guide/nginx-configuration/configmap/#use-proxy-protocol",
"text": "Enables or disables the PROXY protocol to receive client connection (real IP address) information passed through proxy servers and load balancers such as HAProxy and Amazon Elastic Load Balancer (ELB).",
"title": "use-proxy-protocol"
},
{
"location": "/user-guide/nginx-configuration/configmap/#use-gzip",
"text": "Enables or disables compression of HTTP responses using the \"gzip\" module .\nThe default mime type list to compress is: application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component .",
"title": "use-gzip"
},
{
"location": "/user-guide/nginx-configuration/configmap/#use-geoip",
"text": "Enables or disables \"geoip\" module that creates variables with values depending on the client IP address, using the precompiled MaxMind databases. default: true",
"title": "use-geoip"
},
{
"location": "/user-guide/nginx-configuration/configmap/#enable-brotli",
"text": "Enables or disables compression of HTTP responses using the \"brotli\" module .\nThe default mime type list to compress is: application/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component . default: is disabled Note: Brotli does not works in Safari < 11. For more information see https://caniuse.com/#feat=brotli",
"title": "enable-brotli"
},
{
"location": "/user-guide/nginx-configuration/configmap/#brotli-level",
"text": "Sets the Brotli Compression Level that will be used. default: 4",
"title": "brotli-level"
},
{
"location": "/user-guide/nginx-configuration/configmap/#brotli-types",
"text": "Sets the MIME Types that will be compressed on-the-fly by brotli. default: application/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component",
"title": "brotli-types"
},
{
"location": "/user-guide/nginx-configuration/configmap/#use-http2",
"text": "Enables or disables HTTP/2 support in secure connections.",
"title": "use-http2"
},
{
"location": "/user-guide/nginx-configuration/configmap/#gzip-types",
"text": "Sets the MIME types in addition to \"text/html\" to compress. The special value \"*\" matches any MIME type. Responses with the \"text/html\" type are always compressed if use-gzip is enabled.",
"title": "gzip-types"
},
{
"location": "/user-guide/nginx-configuration/configmap/#worker-processes",
"text": "Sets the number of worker processes .\nThe default of \"auto\" means number of available CPU cores.",
"title": "worker-processes"
},
{
"location": "/user-guide/nginx-configuration/configmap/#worker-cpu-affinity",
"text": "Binds worker processes to the sets of CPUs. worker_cpu_affinity .\nBy default worker processes are not bound to any specific CPUs. The value can be: \"\": empty string indicate no affinity is applied. cpumask: e.g. 0001 0010 0100 1000 to bind processes to specific cpus. auto: binding worker processes automatically to available CPUs.",
"title": "worker-cpu-affinity"
},
{
"location": "/user-guide/nginx-configuration/configmap/#worker-shutdown-timeout",
"text": "Sets a timeout for Nginx to wait for worker to gracefully shutdown . default: \"10s\"",
"title": "worker-shutdown-timeout"
},
{
"location": "/user-guide/nginx-configuration/configmap/#load-balance",
"text": "Sets the algorithm to use for load balancing.\nThe value can either be: round_robin: to use the default round robin loadbalancer least_conn: to use the least connected method ip_hash: to use a hash of the server for routing. ewma: to use the peak ewma method for routing (only available with enable-dynamic-configuration flag) The default is least_conn. References: http://nginx.org/en/docs/http/load_balancing.html",
"title": "load-balance"
},
{
"location": "/user-guide/nginx-configuration/configmap/#variables-hash-bucket-size",
"text": "Sets the bucket size for the variables hash table. References: http://nginx.org/en/docs/http/ngx_http_map_module.html#variables_hash_bucket_size",
"title": "variables-hash-bucket-size"
},
{
"location": "/user-guide/nginx-configuration/configmap/#variables-hash-max-size",
"text": "Sets the maximum size of the variables hash table. References: http://nginx.org/en/docs/http/ngx_http_map_module.html#variables_hash_max_size",
"title": "variables-hash-max-size"
},
{
"location": "/user-guide/nginx-configuration/configmap/#upstream-keepalive-connections",
"text": "Activates the cache for connections to upstream servers. The connections parameter sets the maximum number of idle keepalive connections to upstream servers that are preserved in the cache of each worker process. When this\nnumber is exceeded, the least recently used connections are closed. default: 32 References: http://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive",
"title": "upstream-keepalive-connections"
},
{
"location": "/user-guide/nginx-configuration/configmap/#limit-conn-zone-variable",
"text": "Sets parameters for a shared memory zone that will keep states for various keys of limit_conn_zone . The default of \"$binary_remote_addr\" variable\u2019s size is always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses.",
"title": "limit-conn-zone-variable"
},
{
"location": "/user-guide/nginx-configuration/configmap/#proxy-stream-timeout",
"text": "Sets the timeout between two successive read or write operations on client or proxied server connections. If no data is transmitted within this time, the connection is closed. References: http://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_timeout",
"title": "proxy-stream-timeout"
},
{
"location": "/user-guide/nginx-configuration/configmap/#proxy-stream-responses",
"text": "Sets the number of datagrams expected from the proxied server in response to the client request if the UDP protocol is used. References: http://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_responses",
"title": "proxy-stream-responses"
},
{
"location": "/user-guide/nginx-configuration/configmap/#bind-address-ipv4",
"text": "Sets the addresses on which the server will accept requests instead of *. It should be noted that these addresses must exist in the runtime environment or the controller will crash loop.",
"title": "bind-address-ipv4"
},
{
"location": "/user-guide/nginx-configuration/configmap/#bind-address-ipv6",
"text": "Sets the addresses on which the server will accept requests instead of *. It should be noted that these addresses must exist in the runtime environment or the controller will crash loop.",
"title": "bind-address-ipv6"
},
{
"location": "/user-guide/nginx-configuration/configmap/#forwarded-for-header",
"text": "Sets the header field for identifying the originating IP address of a client. default: X-Forwarded-For",
"title": "forwarded-for-header"
},
{
"location": "/user-guide/nginx-configuration/configmap/#compute-full-forwarded-for",
"text": "Append the remote address to the X-Forwarded-For header instead of replacing it. When this option is enabled, the upstream application is responsible for extracting the client IP based on its own list of trusted proxies.",
"title": "compute-full-forwarded-for"
},
{
"location": "/user-guide/nginx-configuration/configmap/#proxy-add-original-uri-header",
"text": "Adds an X-Original-Uri header with the original request URI to the backend request",
"title": "proxy-add-original-uri-header"
},
{
"location": "/user-guide/nginx-configuration/configmap/#enable-opentracing",
"text": "Enables the nginx Opentracing extension. default: is disabled References: https://github.com/opentracing-contrib/nginx-opentracing",
"title": "enable-opentracing"
},
{
"location": "/user-guide/nginx-configuration/configmap/#zipkin-collector-host",
"text": "Specifies the host to use when uploading traces. It must be a valid URL.",
"title": "zipkin-collector-host"
},
{
"location": "/user-guide/nginx-configuration/configmap/#zipkin-collector-port",
"text": "Specifies the port to use when uploading traces. default: 9411",
"title": "zipkin-collector-port"
},
{
"location": "/user-guide/nginx-configuration/configmap/#zipkin-service-name",
"text": "Specifies the service name to use for any traces created. default: nginx",
"title": "zipkin-service-name"
},
{
"location": "/user-guide/nginx-configuration/configmap/#jaeger-collector-host",
"text": "Specifies the host to use when uploading traces. It must be a valid URL.",
"title": "jaeger-collector-host"
},
{
"location": "/user-guide/nginx-configuration/configmap/#jaeger-collector-port",
"text": "Specifies the port to use when uploading traces. default: 6831",
"title": "jaeger-collector-port"
},
{
"location": "/user-guide/nginx-configuration/configmap/#jaeger-service-name",
"text": "Specifies the service name to use for any traces created. default: nginx",
"title": "jaeger-service-name"
},
{
"location": "/user-guide/nginx-configuration/configmap/#jaeger-sampler-type",
"text": "Specifies the sampler to be used when sampling traces. The available samplers are: const, probabilistic, ratelimiting, remote. default: const",
"title": "jaeger-sampler-type"
},
{
"location": "/user-guide/nginx-configuration/configmap/#jaeger-sampler-param",
"text": "Specifies the argument to be passed to the sampler constructor. Must be a number.\nFor const this should be 0 to never sample and 1 to always sample. default: 1",
"title": "jaeger-sampler-param"
},
{
"location": "/user-guide/nginx-configuration/configmap/#http-snippet",
"text": "Adds custom configuration to the http section of the nginx configuration. default: \"\"",
"title": "http-snippet"
},
{
"location": "/user-guide/nginx-configuration/configmap/#server-snippet",
"text": "Adds custom configuration to all the servers in the nginx configuration. default: \"\"",
"title": "server-snippet"
},
{
"location": "/user-guide/nginx-configuration/configmap/#location-snippet",
"text": "Adds custom configuration to all the locations in the nginx configuration. default: \"\"",
"title": "location-snippet"
},
{
"location": "/user-guide/nginx-configuration/configmap/#custom-http-errors",
"text": "Enables which HTTP codes should be passed for processing with the error_page directive Setting at least one code also enables proxy_intercept_errors which are required to process error_page. Example usage: custom-http-errors: 404,415",
"title": "custom-http-errors"
},
{
"location": "/user-guide/nginx-configuration/configmap/#proxy-body-size",
"text": "Sets the maximum allowed size of the client request body.\nSee NGINX client_max_body_size .",
"title": "proxy-body-size"
},
{
"location": "/user-guide/nginx-configuration/configmap/#proxy-connect-timeout",
"text": "Sets the timeout for establishing a connection with a proxied server . It should be noted that this timeout cannot usually exceed 75 seconds.",
"title": "proxy-connect-timeout"
},
{
"location": "/user-guide/nginx-configuration/configmap/#proxy-read-timeout",
"text": "Sets the timeout in seconds for reading a response from the proxied server . The timeout is set only between two successive read operations, not for the transmission of the whole response.",
"title": "proxy-read-timeout"
},
{
"location": "/user-guide/nginx-configuration/configmap/#proxy-send-timeout",
"text": "Sets the timeout in seconds for transmitting a request to the proxied server . The timeout is set only between two successive write operations, not for the transmission of the whole request.",
"title": "proxy-send-timeout"
},
{
"location": "/user-guide/nginx-configuration/configmap/#proxy-buffer-size",
"text": "Sets the size of the buffer used for reading the first part of the response received from the proxied server. This part usually contains a small response header.",
"title": "proxy-buffer-size"
},
{
"location": "/user-guide/nginx-configuration/configmap/#proxy-cookie-path",
"text": "Sets a text that should be changed in the path attribute of the \u201cSet-Cookie\u201d header fields of a proxied server response.",
"title": "proxy-cookie-path"
},
{
"location": "/user-guide/nginx-configuration/configmap/#proxy-cookie-domain",
"text": "Sets a text that should be changed in the domain attribute of the \u201cSet-Cookie\u201d header fields of a proxied server response.",
"title": "proxy-cookie-domain"
},
{
"location": "/user-guide/nginx-configuration/configmap/#proxy-next-upstream",
"text": "Specifies in which cases a request should be passed to the next server.",
"title": "proxy-next-upstream"
},
{
"location": "/user-guide/nginx-configuration/configmap/#proxy-next-upstream-tries",
"text": "Limit the number of possible tries a request should be passed to the next server.",
"title": "proxy-next-upstream-tries"
},
{
"location": "/user-guide/nginx-configuration/configmap/#proxy-redirect-from",
"text": "Sets the original text that should be changed in the \"Location\" and \"Refresh\" header fields of a proxied server response. default: off References: http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect",
"title": "proxy-redirect-from"
},
{
"location": "/user-guide/nginx-configuration/configmap/#proxy-request-buffering",
"text": "Enables or disables buffering of a client request body .",
"title": "proxy-request-buffering"
},
{
"location": "/user-guide/nginx-configuration/configmap/#ssl-redirect",
"text": "Sets the global value of redirects (301) to HTTPS if the server has a TLS certificate (defined in an Ingress rule). default: \"true\"",
"title": "ssl-redirect"
},
{
"location": "/user-guide/nginx-configuration/configmap/#whitelist-source-range",
"text": "Sets the default whitelisted IPs for each server block. This can be overwritten by an annotation on an Ingress rule.\nSee ngx_http_access_module .",
"title": "whitelist-source-range"
},
{
"location": "/user-guide/nginx-configuration/configmap/#skip-access-log-urls",
"text": "Sets a list of URLs that should not appear in the NGINX access log. This is useful with urls like /health or health-check that make \"complex\" reading the logs. default: is empty",
"title": "skip-access-log-urls"
},
{
"location": "/user-guide/nginx-configuration/configmap/#limit-rate",
"text": "Limits the rate of response transmission to a client. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit. References: http://nginx.org/en/docs/http/ngx_http_core_module.html#limit_rate",
"title": "limit-rate"
},
{
"location": "/user-guide/nginx-configuration/configmap/#limit-rate-after",
"text": "Sets the initial amount after which the further transmission of a response to a client will be rate limited. References: http://nginx.org/en/docs/http/ngx_http_core_module.html#limit_rate_after",
"title": "limit-rate-after"
},
{
"location": "/user-guide/nginx-configuration/configmap/#http-redirect-code",
"text": "Sets the HTTP status code to be used in redirects.\nSupported codes are 301 , 302 , 307 and 308 default: 308 Why the default code is 308? RFC 7238 was created to define the 308 (Permanent Redirect) status code that is similar to 301 (Moved Permanently) but it keeps the payload in the redirect. This is important if the we send a redirect in methods like POST.",
"title": "http-redirect-code"
},
{
"location": "/user-guide/nginx-configuration/configmap/#proxy-buffering",
"text": "Enables or disables buffering of responses from the proxied server .",
"title": "proxy-buffering"
},
{
"location": "/user-guide/nginx-configuration/configmap/#limit-req-status-code",
"text": "Sets the status code to return in response to rejected requests . default: 503",
"title": "limit-req-status-code"
},
{
"location": "/user-guide/nginx-configuration/configmap/#no-tls-redirect-locations",
"text": "A comma-separated list of locations on which http requests will never get redirected to their https counterpart. default: \"/.well-known/acme-challenge\"",
"title": "no-tls-redirect-locations"
},
{
"location": "/user-guide/nginx-configuration/configmap/#no-auth-locations",
"text": "A comma-separated list of locations that should not get authenticated. default: \"/.well-known/acme-challenge\"",
"title": "no-auth-locations"
},
{
"location": "/user-guide/nginx-configuration/custom-template/",
"text": "Custom NGINX template\n\u00b6\n\n\nThe NGINX template is located in the file \n/etc/nginx/template/nginx.tmpl\n.\n\n\nUsing a \nVolume\n it is possible to use a custom template. \nThis includes using a \nConfigmap\n as source of the template\n\n\n \nvolumeMounts\n:\n\n \n-\n \nmountPath\n:\n \n/etc/nginx/template\n\n \nname\n:\n \nnginx-template-volume\n\n \nreadOnly\n:\n \ntrue\n\n \n \nvolumes\n:\n\n \n-\n \nname\n:\n \nnginx-template-volume\n\n \nconfigMap\n:\n\n \nname\n:\n \nnginx-template\n\n \nitems\n:\n\n \n-\n \nkey\n:\n \nnginx.tmpl\n\n \npath\n:\n \nnginx.tmpl\n\n\n\n\n\n\nPlease note the template is tied to the Go code. Do not change names in the variable \n$cfg\n.\n\n\nFor more information about the template syntax please check the \nGo template package\n.\nIn addition to the built-in functions provided by the Go package the following functions are also available:\n\n\n\n\nempty: returns true if the specified parameter (string) is empty\n\n\ncontains: \nstrings.Contains\n\n\nhasPrefix: \nstrings.HasPrefix\n\n\nhasSuffix: \nstrings.HasSuffix\n\n\ntoUpper: \nstrings.ToUpper\n\n\ntoLower: \nstrings.ToLower\n\n\nbuildLocation: helps to build the NGINX Location section in each server\n\n\nbuildProxyPass: builds the reverse proxy configuration\n\n\nbuildRateLimit: helps to build a limit zone inside a location if contains a rate limit annotation\n\n\n\n\nTODO:\n\n\n\n\nbuildAuthLocation:\n\n\nbuildAuthResponseHeaders:\n\n\nbuildResolvers:\n\n\nbuildLogFormatUpstream:\n\n\nbuildDenyVariable:\n\n\nbuildUpstreamName:\n\n\nbuildForwardedFor:\n\n\nbuildAuthSignURL:\n\n\nbuildNextUpstream:\n\n\nfilterRateLimits:\n\n\nformatIP:\n\n\ngetenv:\n\n\ngetIngressInformation:\n\n\nserverConfig:\n\n\nisLocationAllowed:\n\n\nisValidClientBodyBufferSize:",
"title": "Custom NGINX template"
},
{
"location": "/user-guide/nginx-configuration/custom-template/#custom-nginx-template",
"text": "The NGINX template is located in the file /etc/nginx/template/nginx.tmpl . Using a Volume it is possible to use a custom template. \nThis includes using a Configmap as source of the template volumeMounts : \n - mountPath : /etc/nginx/template \n name : nginx-template-volume \n readOnly : true \n volumes : \n - name : nginx-template-volume \n configMap : \n name : nginx-template \n items : \n - key : nginx.tmpl \n path : nginx.tmpl Please note the template is tied to the Go code. Do not change names in the variable $cfg . For more information about the template syntax please check the Go template package .\nIn addition to the built-in functions provided by the Go package the following functions are also available: empty: returns true if the specified parameter (string) is empty contains: strings.Contains hasPrefix: strings.HasPrefix hasSuffix: strings.HasSuffix toUpper: strings.ToUpper toLower: strings.ToLower buildLocation: helps to build the NGINX Location section in each server buildProxyPass: builds the reverse proxy configuration buildRateLimit: helps to build a limit zone inside a location if contains a rate limit annotation TODO: buildAuthLocation: buildAuthResponseHeaders: buildResolvers: buildLogFormatUpstream: buildDenyVariable: buildUpstreamName: buildForwardedFor: buildAuthSignURL: buildNextUpstream: filterRateLimits: formatIP: getenv: getIngressInformation: serverConfig: isLocationAllowed: isValidClientBodyBufferSize:",
"title": "Custom NGINX template"
},
{
"location": "/user-guide/nginx-configuration/log-format/",
"text": "Log format\n\u00b6\n\n\nThe default configuration uses a custom logging format to add additional information about upstreams, response time and status\n\n\n log_format upstreaminfo '\n{{\n \nif\n \n$\ncfg.useProxyProtocol\n \n}}\n$proxy_protocol_addr\n{{\n \nelse\n \n}}\n$remote_addr\n{{\n \nend\n \n}}\n - '\n\n\n '[$the_real_ip] - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" '\n\n\n '$request_length $request_time [$proxy_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status';\n\n\n\n\n\n\nSources:\n\n\n\n\nupstream variables\n\n\nembedded variables\n\n\n\n\nDescription:\n\n\n\n\n$proxy_protocol_addr\n: if PROXY protocol is enabled\n\n\n$remote_addr\n: if PROXY protocol is disabled (default)\n\n\n$the_real_ip\n: the source IP address of the client\n\n\n$remote_user\n: user name supplied with the Basic authentication\n\n\n$time_local\n: local time in the Common Log Format\n\n\n$request\n: full original request line\n\n\n$status\n: response status\n\n\n$body_bytes_sent\n: number of bytes sent to a client, not counting the response header\n\n\n$http_referer\n: value of the Referer header\n\n\n$http_user_agent\n: value of User-Agent header\n\n\n$request_length\n: request length (including request line, header, and request body)\n\n\n$request_time\n: time elapsed since the first bytes were read from the client\n\n\n$proxy_upstream_name\n: name of the upstream. The format is \nupstream-<namespace>-<service name>-<service port>\n\n\n$upstream_addr\n: keeps the IP address and port, or the path to the UNIX-domain socket of the upstream server. If several servers were contacted during request processing, their addresses are separated by commas\n\n\n$upstream_response_length\n: keeps the length of the response obtained from the upstream server\n\n\n$upstream_response_time\n: keeps time spent on receiving the response from the upstream server; the time is kept in seconds with millisecond resolution\n\n\n$upstream_status\n: keeps status code of the response obtained from the upstream server",
"title": "Log format"
},
{
"location": "/user-guide/nginx-configuration/log-format/#log-format",
"text": "The default configuration uses a custom logging format to add additional information about upstreams, response time and status log_format upstreaminfo ' {{ if $ cfg.useProxyProtocol }} $proxy_protocol_addr {{ else }} $remote_addr {{ end }} - ' '[$the_real_ip] - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" ' '$request_length $request_time [$proxy_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status'; Sources: upstream variables embedded variables Description: $proxy_protocol_addr : if PROXY protocol is enabled $remote_addr : if PROXY protocol is disabled (default) $the_real_ip : the source IP address of the client $remote_user : user name supplied with the Basic authentication $time_local : local time in the Common Log Format $request : full original request line $status : response status $body_bytes_sent : number of bytes sent to a client, not counting the response header $http_referer : value of the Referer header $http_user_agent : value of User-Agent header $request_length : request length (including request line, header, and request body) $request_time : time elapsed since the first bytes were read from the client $proxy_upstream_name : name of the upstream. The format is upstream-<namespace>-<service name>-<service port> $upstream_addr : keeps the IP address and port, or the path to the UNIX-domain socket of the upstream server. If several servers were contacted during request processing, their addresses are separated by commas $upstream_response_length : keeps the length of the response obtained from the upstream server $upstream_response_time : keeps time spent on receiving the response from the upstream server; the time is kept in seconds with millisecond resolution $upstream_status : keeps status code of the response obtained from the upstream server",
"title": "Log format"
},
{
"location": "/user-guide/cli-arguments/",
"text": "Command line arguments\n\u00b6\n\n\nThe following command line arguments are accepted by the main controller executable.\n\n\nThey are set in the container spec of the \nnginx-ingress-controller\n Deployment object (see \ndeploy/with-rbac.yaml\n or \ndeploy/without-rbac.yaml\n).\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n--alsologtostderr\n\n\nlog to standard error as well as files\n\n\n\n\n\n\n--annotations-prefix string\n\n\nPrefix of the ingress annotations. (default \"nginx.ingress.kubernetes.io\")\n\n\n\n\n\n\n--apiserver-host string\n\n\nThe address of the Kubernetes Apiserver to connect to in the format of protocol://address:port, e.g., http://localhost:8080. If not specified, the assumption is that the binary runs inside a Kubernetes cluster and local discovery is attempted.\n\n\n\n\n\n\n--configmap string\n\n\nName of the ConfigMap that contains the custom configuration to use\n\n\n\n\n\n\n--default-backend-service string\n\n\nService used to serve a 404 page for the default backend. Takes the form namespace/name. The controller uses the first node port of this Service for the default backend.\n\n\n\n\n\n\n--default-server-port int\n\n\nDefault port to use for exposing the default server (catch all) (default 8181)\n\n\n\n\n\n\n--default-ssl-certificate string\n\n\nName of the secret that contains a SSL certificate to be used as default for a HTTPS catch-all server. Takes the form \n/\n.\n\n\n\n\n\n\n--election-id string\n\n\nElection id to use for status update. (default \"ingress-controller-leader\")\n\n\n\n\n\n\n--enable-dynamic-configuration\n\n\nWhen enabled controller will try to avoid Nginx reloads as much as possible by using Lua. Disabled by default.\n\n\n\n\n\n\n--enable-ssl-chain-completion\n\n\nDefines if the nginx ingress controller should check the secrets for missing intermediate CA certificates. If the certificate contain issues chain issues is not possible to enable OCSP. Default is true. (default true)\n\n\n\n\n\n\n--enable-ssl-passthrough\n\n\nEnable SSL passthrough feature. Default is disabled\n\n\n\n\n\n\n--force-namespace-isolation\n\n\nForce namespace isolation. This flag is required to avoid the reference of secrets or configmaps located in a different namespace than the specified in the flag --watch-namespace.\n\n\n\n\n\n\n--health-check-path string\n\n\nDefines the URL to be used as health check inside in the default server in NGINX. (default \"/healthz\")\n\n\n\n\n\n\n--healthz-port int\n\n\nport for healthz endpoint. (default 10254)\n\n\n\n\n\n\n--http-port int\n\n\nIndicates the port to use for HTTP traffic (default 80)\n\n\n\n\n\n\n--https-port int\n\n\nIndicates the port to use for HTTPS traffic (default 443)\n\n\n\n\n\n\n--ingress-class string\n\n\nName of the ingress class to route through this controller.\n\n\n\n\n\n\n--kubeconfig string\n\n\nPath to kubeconfig file with authorization and master location information.\n\n\n\n\n\n\n--log_backtrace_at traceLocation\n\n\nwhen logging hits line file:N, emit a stack trace (default :0)\n\n\n\n\n\n\n--log_dir string\n\n\nIf non-empty, write log files in this directory\n\n\n\n\n\n\n--logtostderr\n\n\nlog to standard error instead of files (default true)\n\n\n\n\n\n\n--profiling\n\n\nEnable profiling via web interface host:port/debug/pprof/ (default true)\n\n\n\n\n\n\n--publish-service string\n\n\nService fronting the ingress controllers. Takes the form namespace/name. The controller will set the endpoint records on the ingress objects to reflect those on the service.\n\n\n\n\n\n\n--publish-status-address string\n\n\nUser customized address to be set in the status of ingress resources. The controller will set the endpoint records on the ingress using this address.\n\n\n\n\n\n\n--report-node-internal-ip-address\n\n\nDefines if the nodes IP address to be returned in the ingress status should be the internal instead of the external IP address\n\n\n\n\n\n\n--sort-backends\n\n\nDefines if backends and its endpoints should be sorted\n\n\n\n\n\n\n--ssl-passtrough-proxy-port int\n\n\nDefault port to use internally for SSL when SSL Passthgough is enabled (default 442)\n\n\n\n\n\n\n--status-port int\n\n\nIndicates the TCP port to use for exposing the nginx status page (default 18080)\n\n\n\n\n\n\n--stderrthreshold severity\n\n\nlogs at or above this threshold go to stderr (default 2)\n\n\n\n\n\n\n--sync-period duration\n\n\nRelist and confirm cloud resources this often. Default is 10 minutes (default 10m0s)\n\n\n\n\n\n\n--sync-rate-limit float32\n\n\nDefine the sync frequency upper limit (default 0.3)\n\n\n\n\n\n\n--tcp-services-configmap string\n\n\nName of the ConfigMap that contains the definition of the TCP services to expose. The key in the map indicates the external port to be used. The value is the name of the service with the format namespace/serviceName and the port of the service could be a number of the name of the port. The ports 80 and 443 are not allowed as external ports. This ports are reserved for the backend\n\n\n\n\n\n\n--udp-services-configmap string\n\n\nName of the ConfigMap that contains the definition of the UDP services to expose. The key in the map indicates the external port to be used. The value is the name of the service with the format namespace/serviceName and the port of the service could be a number of the name of the port.\n\n\n\n\n\n\n--update-status\n\n\nIndicates if the ingress controller should update the Ingress status IP/hostname. Default is true (default true)\n\n\n\n\n\n\n--update-status-on-shutdown\n\n\nIndicates if the ingress controller should update the Ingress status IP/hostname when the controller is being stopped. Default is true (default true)\n\n\n\n\n\n\n-v\n, \n--v Level\n\n\nlog level for V logs\n\n\n\n\n\n\n--version\n\n\nShows release information about the NGINX Ingress controller\n\n\n\n\n\n\n--vmodule moduleSpec\n\n\ncomma-separated list of pattern=N settings for file-filtered logging\n\n\n\n\n\n\n--watch-namespace string\n\n\nNamespace to watch for Ingress. Default is to watch all namespaces",
"title": "Command line arguments"
},
{
"location": "/user-guide/cli-arguments/#command-line-arguments",
"text": "The following command line arguments are accepted by the main controller executable. They are set in the container spec of the nginx-ingress-controller Deployment object (see deploy/with-rbac.yaml or deploy/without-rbac.yaml ). Argument Description --alsologtostderr log to standard error as well as files --annotations-prefix string Prefix of the ingress annotations. (default \"nginx.ingress.kubernetes.io\") --apiserver-host string The address of the Kubernetes Apiserver to connect to in the format of protocol://address:port, e.g., http://localhost:8080. If not specified, the assumption is that the binary runs inside a Kubernetes cluster and local discovery is attempted. --configmap string Name of the ConfigMap that contains the custom configuration to use --default-backend-service string Service used to serve a 404 page for the default backend. Takes the form namespace/name. The controller uses the first node port of this Service for the default backend. --default-server-port int Default port to use for exposing the default server (catch all) (default 8181) --default-ssl-certificate string Name of the secret that contains a SSL certificate to be used as default for a HTTPS catch-all server. Takes the form / . --election-id string Election id to use for status update. (default \"ingress-controller-leader\") --enable-dynamic-configuration When enabled controller will try to avoid Nginx reloads as much as possible by using Lua. Disabled by default. --enable-ssl-chain-completion Defines if the nginx ingress controller should check the secrets for missing intermediate CA certificates. If the certificate contain issues chain issues is not possible to enable OCSP. Default is true. (default true) --enable-ssl-passthrough Enable SSL passthrough feature. Default is disabled --force-namespace-isolation Force namespace isolation. This flag is required to avoid the reference of secrets or configmaps located in a different namespace than the specified in the flag --watch-namespace. --health-check-path string Defines the URL to be used as health check inside in the default server in NGINX. (default \"/healthz\") --healthz-port int port for healthz endpoint. (default 10254) --http-port int Indicates the port to use for HTTP traffic (default 80) --https-port int Indicates the port to use for HTTPS traffic (default 443) --ingress-class string Name of the ingress class to route through this controller. --kubeconfig string Path to kubeconfig file with authorization and master location information. --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) --log_dir string If non-empty, write log files in this directory --logtostderr log to standard error instead of files (default true) --profiling Enable profiling via web interface host:port/debug/pprof/ (default true) --publish-service string Service fronting the ingress controllers. Takes the form namespace/name. The controller will set the endpoint records on the ingress objects to reflect those on the service. --publish-status-address string User customized address to be set in the status of ingress resources. The controller will set the endpoint records on the ingress using this address. --report-node-internal-ip-address Defines if the nodes IP address to be returned in the ingress status should be the internal instead of the external IP address --sort-backends Defines if backends and its endpoints should be sorted --ssl-passtrough-proxy-port int Default port to use internally for SSL when SSL Passthgough is enabled (default 442) --status-port int Indicates the TCP port to use for exposing the nginx status page (default 18080) --stderrthreshold severity logs at or above this threshold go to stderr (default 2) --sync-period duration Relist and confirm cloud resources this often. Default is 10 minutes (default 10m0s) --sync-rate-limit float32 Define the sync frequency upper limit (default 0.3) --tcp-services-configmap string Name of the ConfigMap that contains the definition of the TCP services to expose. The key in the map indicates the external port to be used. The value is the name of the service with the format namespace/serviceName and the port of the service could be a number of the name of the port. The ports 80 and 443 are not allowed as external ports. This ports are reserved for the backend --udp-services-configmap string Name of the ConfigMap that contains the definition of the UDP services to expose. The key in the map indicates the external port to be used. The value is the name of the service with the format namespace/serviceName and the port of the service could be a number of the name of the port. --update-status Indicates if the ingress controller should update the Ingress status IP/hostname. Default is true (default true) --update-status-on-shutdown Indicates if the ingress controller should update the Ingress status IP/hostname when the controller is being stopped. Default is true (default true) -v , --v Level log level for V logs --version Shows release information about the NGINX Ingress controller --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging --watch-namespace string Namespace to watch for Ingress. Default is to watch all namespaces",
"title": "Command line arguments"
},
{
"location": "/user-guide/custom-errors/",
"text": "Custom errors\n\u00b6\n\n\nIn case of an error in a request the body of the response is obtained from the \ndefault backend\n.\nEach request to the default backend includes two headers:\n\n\n\n\nX-Code\n indicates the HTTP code to be returned to the client.\n\n\nX-Format\n the value of the \nAccept\n header.\n\n\n\n\n\n\nImportant\n\n\nThe custom backend must return the correct HTTP status code to be returned. NGINX does not change the response from the custom default backend.\n\n\n\n\nUsing these two headers it's possible to use a custom backend service like \nthis one\n that inspects each request and returns a custom error page with the format expected by the client. Please check the example \ncustom-errors\n.\n\n\nNGINX sends additional headers that can be used to build custom response:\n\n\n\n\nX-Original-URI\n\n\nX-Namespace\n\n\nX-Ingress-Name\n\n\nX-Service-Name",
"title": "Custom errors"
},
{
"location": "/user-guide/custom-errors/#custom-errors",
"text": "In case of an error in a request the body of the response is obtained from the default backend .\nEach request to the default backend includes two headers: X-Code indicates the HTTP code to be returned to the client. X-Format the value of the Accept header. Important The custom backend must return the correct HTTP status code to be returned. NGINX does not change the response from the custom default backend. Using these two headers it's possible to use a custom backend service like this one that inspects each request and returns a custom error page with the format expected by the client. Please check the example custom-errors . NGINX sends additional headers that can be used to build custom response: X-Original-URI X-Namespace X-Ingress-Name X-Service-Name",
"title": "Custom errors"
},
{
"location": "/user-guide/exposing-tcp-udp-services/",
"text": "Exposing TCP and UDP services\n\u00b6\n\n\nIngress does not support TCP or UDP services. For this reason this Ingress controller uses the flags \n--tcp-services-configmap\n and \n--udp-services-configmap\n to point to an existing config map where the key is the external port to use and the value indicates the service to expose using the format:\n\n<namespace/service name>:<service port>:[PROXY]:[PROXY]\n\n\nIt is also possible to use a number or the name of the port. The two last fields are optional.\nAdding \nPROXY\n in either or both of the two last fields we can use Proxy Protocol decoding (listen) and/or encoding (proxy_pass) in a TCP service (https://www.nginx.com/resources/admin-guide/proxy-protocol/).\n\n\nThe next example shows how to expose the service \nexample-go\n running in the namespace \ndefault\n in the port \n8080\n using the port \n9000\n\n\napiVersion\n:\n \nv1\n\n\nkind\n:\n \nConfigMap\n\n\nmetadata\n:\n\n \nname\n:\n \ntcp-configmap-example\n\n\ndata\n:\n\n \n9000\n:\n \n\"default/example-go:8080\"\n\n\n\n\n\n\nSince 1.9.13 NGINX provides \nUDP Load Balancing\n.\nThe next example shows how to expose the service \nkube-dns\n running in the namespace \nkube-system\n in the port \n53\n using the port \n53\n\n\napiVersion\n:\n \nv1\n\n\nkind\n:\n \nConfigMap\n\n\nmetadata\n:\n\n \nname\n:\n \nudp-configmap-example\n\n\ndata\n:\n\n\n \u00a0\n53\n:\n \n\"kube-system/kube-dns:53\"",
"title": "Exposing TCP and UDP services"
},
{
"location": "/user-guide/exposing-tcp-udp-services/#exposing-tcp-and-udp-services",
"text": "Ingress does not support TCP or UDP services. For this reason this Ingress controller uses the flags --tcp-services-configmap and --udp-services-configmap to point to an existing config map where the key is the external port to use and the value indicates the service to expose using the format: <namespace/service name>:<service port>:[PROXY]:[PROXY] It is also possible to use a number or the name of the port. The two last fields are optional.\nAdding PROXY in either or both of the two last fields we can use Proxy Protocol decoding (listen) and/or encoding (proxy_pass) in a TCP service (https://www.nginx.com/resources/admin-guide/proxy-protocol/). The next example shows how to expose the service example-go running in the namespace default in the port 8080 using the port 9000 apiVersion : v1 kind : ConfigMap metadata : \n name : tcp-configmap-example data : \n 9000 : \"default/example-go:8080\" Since 1.9.13 NGINX provides UDP Load Balancing .\nThe next example shows how to expose the service kube-dns running in the namespace kube-system in the port 53 using the port 53 apiVersion : v1 kind : ConfigMap metadata : \n name : udp-configmap-example data : \u00a0 53 : \"kube-system/kube-dns:53\"",
"title": "Exposing TCP and UDP services"
},
{
"location": "/user-guide/external-articles/",
"text": "External Articles\n\u00b6\n\n\n\n\nPain(less) NGINX Ingress\n\n\nAccessing Kubernetes Pods from Outside of the Cluster\n\n\nKubernetes - Redirect HTTP to HTTPS with ELB and the nginx ingress controller\n\n\nConfigure Nginx Ingress Controller for TLS termination on Kubernetes on Azure",
"title": "External Articles"
},
{
"location": "/user-guide/external-articles/#external-articles",
"text": "Pain(less) NGINX Ingress Accessing Kubernetes Pods from Outside of the Cluster Kubernetes - Redirect HTTP to HTTPS with ELB and the nginx ingress controller Configure Nginx Ingress Controller for TLS termination on Kubernetes on Azure",
"title": "External Articles"
},
{
"location": "/user-guide/miscellaneous/",
"text": "Miscellaneous\n\u00b6\n\n\nConventions\n\u00b6\n\n\nAnytime we reference a tls secret, we mean (x509, pem encoded, RSA 2048, etc). You can generate such a certificate with:\n\nopenssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout \n${\nKEY_FILE\n}\n -out \n${\nCERT_FILE\n}\n -subj \"/CN=\n${\nHOST\n}\n/O=\n${\nHOST\n}\n\"\n\nand create the secret via \nkubectl create secret tls \n${\nCERT_NAME\n}\n --key \n${\nKEY_FILE\n}\n --cert \n${\nCERT_FILE\n}\n\n\nRequirements\n\u00b6\n\n\nThe default backend is a service which handles all url paths and hosts the nginx controller doesn't understand (i.e., all the requests that are not mapped with an Ingress).\nBasically a default backend exposes two URLs:\n\n\n\n\n/healthz\n that returns 200\n\n\n/\n that returns 404\n\n\n\n\nThe sub-directory \n/images/404-server\n provides a service which satisfies the requirements for a default backend. The sub-directory \n/images/custom-error-pages\n provides an additional service for the purpose of customizing the error pages served via the default backend.\n\n\nSource IP address\n\u00b6\n\n\nBy default NGINX uses the content of the header \nX-Forwarded-For\n as the source of truth to get information about the client IP address. This works without issues in L7 \nif we configure the setting \nproxy-real-ip-cidr\n with the correct information of the IP/network address of trusted external load balancer.\n\n\nIf the ingress controller is running in AWS we need to use the VPC IPv4 CIDR.\n\n\nAnother option is to enable proxy protocol using \nuse-proxy-protocol: \"true\"\n.\n\n\nIn this mode NGINX does not use the content of the header to get the source IP address of the connection.\n\n\nProxy Protocol\n\u00b6\n\n\nIf you are using a L4 proxy to forward the traffic to the NGINX pods and terminate HTTP/HTTPS there, you will lose the remote endpoint's IP address. To prevent this you could use the \nProxy Protocol\n for forwarding traffic, this will send the connection details before forwarding the actual TCP connection itself.\n\n\nAmongst others \nELBs in AWS\n and \nHAProxy\n support Proxy Protocol.\n\n\nWebsockets\n\u00b6\n\n\nSupport for websockets is provided by NGINX out of the box. No special configuration required.\n\n\nThe only requirement to avoid the close of connections is the increase of the values of \nproxy-read-timeout\n and \nproxy-send-timeout\n.\n\n\nThe default value of this settings is \n60 seconds\n.\n\n\nA more adequate value to support websockets is a value higher than one hour (\n3600\n).\n\n\n\n\nImportant\n\n\nIf the NGINX ingress controller is exposed with a service \ntype=LoadBalancer\n make sure the protocol between the loadbalancer and NGINX is TCP.\n\n\n\n\nOptimizing TLS Time To First Byte (TTTFB)\n\u00b6\n\n\nNGINX provides the configuration option \nssl_buffer_size\n to allow the optimization of the TLS record size.\n\n\nThis improves the \nTLS Time To First Byte\n (TTTFB).\nThe default value in the Ingress controller is \n4k\n (NGINX default is \n16k\n).\n\n\nRetries in non-idempotent methods\n\u00b6\n\n\nSince 1.9.13 NGINX will not retry non-idempotent requests (POST, LOCK, PATCH) in case of an error.\nThe previous behavior can be restored using \nretry-non-idempotent=true\n in the configuration ConfigMap.\n\n\nLimitations\n\u00b6\n\n\n\n\nIngress rules for TLS require the definition of the field \nhost\n\n\n\n\nWhy endpoints and not services\n\u00b6\n\n\nThe NGINX ingress controller does not use \nServices\n to route traffic to the pods. Instead it uses the Endpoints API in order to bypass \nkube-proxy\n to allow NGINX features like session affinity and custom load balancing algorithms. It also removes some overhead, such as conntrack entries for iptables DNAT.",
"title": "Miscellaneous"
},
{
"location": "/user-guide/miscellaneous/#miscellaneous",
"text": "",
"title": "Miscellaneous"
},
{
"location": "/user-guide/miscellaneous/#conventions",
"text": "Anytime we reference a tls secret, we mean (x509, pem encoded, RSA 2048, etc). You can generate such a certificate with: openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ${ KEY_FILE } -out ${ CERT_FILE } -subj \"/CN= ${ HOST } /O= ${ HOST } \" \nand create the secret via kubectl create secret tls ${ CERT_NAME } --key ${ KEY_FILE } --cert ${ CERT_FILE }",
"title": "Conventions"
},
{
"location": "/user-guide/miscellaneous/#requirements",
"text": "The default backend is a service which handles all url paths and hosts the nginx controller doesn't understand (i.e., all the requests that are not mapped with an Ingress).\nBasically a default backend exposes two URLs: /healthz that returns 200 / that returns 404 The sub-directory /images/404-server provides a service which satisfies the requirements for a default backend. The sub-directory /images/custom-error-pages provides an additional service for the purpose of customizing the error pages served via the default backend.",
"title": "Requirements"
},
{
"location": "/user-guide/miscellaneous/#source-ip-address",
"text": "By default NGINX uses the content of the header X-Forwarded-For as the source of truth to get information about the client IP address. This works without issues in L7 if we configure the setting proxy-real-ip-cidr with the correct information of the IP/network address of trusted external load balancer. If the ingress controller is running in AWS we need to use the VPC IPv4 CIDR. Another option is to enable proxy protocol using use-proxy-protocol: \"true\" . In this mode NGINX does not use the content of the header to get the source IP address of the connection.",
"title": "Source IP address"
},
{
"location": "/user-guide/miscellaneous/#proxy-protocol",
"text": "If you are using a L4 proxy to forward the traffic to the NGINX pods and terminate HTTP/HTTPS there, you will lose the remote endpoint's IP address. To prevent this you could use the Proxy Protocol for forwarding traffic, this will send the connection details before forwarding the actual TCP connection itself. Amongst others ELBs in AWS and HAProxy support Proxy Protocol.",
"title": "Proxy Protocol"
},
{
"location": "/user-guide/miscellaneous/#websockets",
"text": "Support for websockets is provided by NGINX out of the box. No special configuration required. The only requirement to avoid the close of connections is the increase of the values of proxy-read-timeout and proxy-send-timeout . The default value of this settings is 60 seconds . A more adequate value to support websockets is a value higher than one hour ( 3600 ). Important If the NGINX ingress controller is exposed with a service type=LoadBalancer make sure the protocol between the loadbalancer and NGINX is TCP.",
"title": "Websockets"
},
{
"location": "/user-guide/miscellaneous/#optimizing-tls-time-to-first-byte-tttfb",
"text": "NGINX provides the configuration option ssl_buffer_size to allow the optimization of the TLS record size. This improves the TLS Time To First Byte (TTTFB).\nThe default value in the Ingress controller is 4k (NGINX default is 16k ).",
"title": "Optimizing TLS Time To First Byte (TTTFB)"
},
{
"location": "/user-guide/miscellaneous/#retries-in-non-idempotent-methods",
"text": "Since 1.9.13 NGINX will not retry non-idempotent requests (POST, LOCK, PATCH) in case of an error.\nThe previous behavior can be restored using retry-non-idempotent=true in the configuration ConfigMap.",
"title": "Retries in non-idempotent methods"
},
{
"location": "/user-guide/miscellaneous/#limitations",
"text": "Ingress rules for TLS require the definition of the field host",
"title": "Limitations"
},
{
"location": "/user-guide/miscellaneous/#why-endpoints-and-not-services",
"text": "The NGINX ingress controller does not use Services to route traffic to the pods. Instead it uses the Endpoints API in order to bypass kube-proxy to allow NGINX features like session affinity and custom load balancing algorithms. It also removes some overhead, such as conntrack entries for iptables DNAT.",
"title": "Why endpoints and not services"
},
{
"location": "/user-guide/multiple-ingress/",
"text": "Multiple ingress controllers\n\u00b6\n\n\nRunning multiple ingress controllers\n\u00b6\n\n\nIf you're running multiple ingress controllers, or running on a cloud provider that natively handles ingress, you need to specify the annotation \nkubernetes.io/ingress.class: \"nginx\"\n in all ingresses that you would like this controller to claim.\n\n\nThis mechanism also provides users the ability to run \nmultiple\n NGINX ingress controllers (e.g. one which serves public traffic, one which serves \"internal\" traffic). When utilizing this functionality the option \n--ingress-class\n should be changed to a value unique for the cluster within the definition of the replication controller. Here is a partial example:\n\n\nspec\n:\n\n \ntemplate\n:\n\n \nspec\n:\n\n \ncontainers\n:\n\n \n-\n \nname\n:\n \nnginx\n-\ningress\n-\ninternal\n-\ncontroller\n\n \nargs\n:\n\n \n-\n \n/\nnginx\n-\ningress\n-\ncontroller\n\n \n-\n \n'--default-backend-service=ingress/nginx-ingress-default-backend'\n\n \n-\n \n'--election-id=ingress-controller-leader-internal'\n\n \n-\n \n'--ingress-class=nginx-internal'\n\n \n-\n \n'--configmap=ingress/nginx-ingress-internal-controller'\n\n\n\n\n\n\nAnnotation ingress.class\n\u00b6\n\n\nIf you have multiple Ingress controllers in a single cluster, you can pick one by specifying the \ningress.class\n \nannotation, eg creating an Ingress with an annotation like\n\n\nmetadata\n:\n\n \nname\n:\n \nfoo\n\n \nannotations\n:\n\n \nkubernetes.io/ingress.class\n:\n \n\"gce\"\n\n\n\n\n\n\nwill target the GCE controller, forcing the nginx controller to ignore it, while an annotation like\n\n\nmetadata\n:\n\n \nname\n:\n \nfoo\n\n \nannotations\n:\n\n \nkubernetes.io/ingress.class\n:\n \n\"nginx\"\n\n\n\n\n\n\nwill target the nginx controller, forcing the GCE controller to ignore it.\n\n\nNote\n: Deploying multiple ingress controller and not specifying the annotation will result in both controllers fighting to satisfy the Ingress.\n\n\nDisabling NGINX ingress controller\n\u00b6\n\n\nSetting the annotation \nkubernetes.io/ingress.class\n to any other value which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress. If you are only running a single NGINX ingress controller, this can be achieved by setting this to any value except \"nginx\" or an empty string.\n\n\nDo this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller.",
"title": "Multiple ingress controllers"
},
{
"location": "/user-guide/multiple-ingress/#multiple-ingress-controllers",
"text": "",
"title": "Multiple ingress controllers"
},
{
"location": "/user-guide/multiple-ingress/#running-multiple-ingress-controllers",
"text": "If you're running multiple ingress controllers, or running on a cloud provider that natively handles ingress, you need to specify the annotation kubernetes.io/ingress.class: \"nginx\" in all ingresses that you would like this controller to claim. This mechanism also provides users the ability to run multiple NGINX ingress controllers (e.g. one which serves public traffic, one which serves \"internal\" traffic). When utilizing this functionality the option --ingress-class should be changed to a value unique for the cluster within the definition of the replication controller. Here is a partial example: spec : \n template : \n spec : \n containers : \n - name : nginx - ingress - internal - controller \n args : \n - / nginx - ingress - controller \n - '--default-backend-service=ingress/nginx-ingress-default-backend' \n - '--election-id=ingress-controller-leader-internal' \n - '--ingress-class=nginx-internal' \n - '--configmap=ingress/nginx-ingress-internal-controller'",
"title": "Running multiple ingress controllers"
},
{
"location": "/user-guide/multiple-ingress/#annotation-ingressclass",
"text": "If you have multiple Ingress controllers in a single cluster, you can pick one by specifying the ingress.class \nannotation, eg creating an Ingress with an annotation like metadata : \n name : foo \n annotations : \n kubernetes.io/ingress.class : \"gce\" will target the GCE controller, forcing the nginx controller to ignore it, while an annotation like metadata : \n name : foo \n annotations : \n kubernetes.io/ingress.class : \"nginx\" will target the nginx controller, forcing the GCE controller to ignore it. Note : Deploying multiple ingress controller and not specifying the annotation will result in both controllers fighting to satisfy the Ingress.",
"title": "Annotation ingress.class"
},
{
"location": "/user-guide/multiple-ingress/#disabling-nginx-ingress-controller",
"text": "Setting the annotation kubernetes.io/ingress.class to any other value which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress. If you are only running a single NGINX ingress controller, this can be achieved by setting this to any value except \"nginx\" or an empty string. Do this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller.",
"title": "Disabling NGINX ingress controller"
},
{
"location": "/user-guide/nginx-status-page/",
"text": "NGINX status page\n\u00b6\n\n\nThe \nngx_http_stub_status_module\n module provides access to basic status information.\nThis is the default module active in the url \n/nginx_status\n in the status port (default is 18080).\n\n\nThis controller provides an alternative to this module using the \nnginx-module-vts\n module.\nTo use this module just set in the configuration configmap \nenable-vts-status: \"true\"\n.\n\n\n\n\nTo extract the information in JSON format the module provides a custom URL: \n/nginx_status/format/json",
"title": "NGINX status page"
},
{
"location": "/user-guide/nginx-status-page/#nginx-status-page",
"text": "The ngx_http_stub_status_module module provides access to basic status information.\nThis is the default module active in the url /nginx_status in the status port (default is 18080). This controller provides an alternative to this module using the nginx-module-vts module.\nTo use this module just set in the configuration configmap enable-vts-status: \"true\" . To extract the information in JSON format the module provides a custom URL: /nginx_status/format/json",
"title": "NGINX status page"
},
{
"location": "/user-guide/tls/",
"text": "TLS\n\u00b6\n\n\n\n\nDefault SSL Certificate\n\n\nSSL Passthrough\n\n\nHTTPS enforcement\n\n\nHSTS\n\n\nServer-side HTTPS enforcement through redirect\n \n\n\nKube-Lego\n\n\nDefault TLS Version and Ciphers\n\n\nLegacy TLS\n\n\n\n\nDefault SSL Certificate\n\u00b6\n\n\nNGINX provides the option to configure a server as a catch-all with \nserver_name\n for requests that do not match any of the configured server names. This configuration works without issues for HTTP traffic.\nIn case of HTTPS, NGINX requires a certificate.\nFor this reason the Ingress controller provides the flag \n--default-ssl-certificate\n. The secret behind this flag contains the default certificate to be used in the mentioned scenario. If this flag is not provided NGINX will use a self signed certificate.\n\n\nRunning without the flag \n--default-ssl-certificate\n:\n\n\n$\n curl -v https://10.2.78.7:443 -k\n\n* Rebuilt URL to: https://10.2.78.7:443/\n\n\n* Trying 10.2.78.4...\n\n\n* Connected to 10.2.78.7 (10.2.78.7) port 443 (#0)\n\n\n* ALPN, offering http/1.1\n\n\n* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH\n\n\n* successfully set certificate verify locations:\n\n\n* CAfile: /etc/ssl/certs/ca-certificates.crt\n\n\n CApath: /etc/ssl/certs\n\n\n* TLSv1.2 (OUT), TLS header, Certificate Status (22):\n\n\n* TLSv1.2 (OUT), TLS handshake, Client hello (1):\n\n\n* TLSv1.2 (IN), TLS handshake, Server hello (2):\n\n\n* TLSv1.2 (IN), TLS handshake, Certificate (11):\n\n\n* TLSv1.2 (IN), TLS handshake, Server key exchange (12):\n\n\n* TLSv1.2 (IN), TLS handshake, Server finished (14):\n\n\n* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):\n\n\n* TLSv1.2 (OUT), TLS change cipher, Client hello (1):\n\n\n* TLSv1.2 (OUT), TLS handshake, Finished (20):\n\n\n* TLSv1.2 (IN), TLS change cipher, Client hello (1):\n\n\n* TLSv1.2 (IN), TLS handshake, Finished (20):\n\n\n* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256\n\n\n* ALPN, server accepted to use http/1.1\n\n\n* Server certificate:\n\n\n* subject: CN=foo.bar.com\n\n\n* start date: Apr 13 00:50:56 2016 GMT\n\n\n* expire date: Apr 13 00:50:56 2017 GMT\n\n\n* issuer: CN=foo.bar.com\n\n\n* SSL certificate verify result: self signed certificate (18), continuing anyway.\n\n\n>\n GET / HTTP/1.1\n\n>\n Host: \n10\n.2.78.7\n\n>\n User-Agent: curl/7.47.1\n\n>\n Accept: */*\n\n>\n\n\n< HTTP/1.1 404 Not Found\n\n\n< Server: nginx/1.11.1\n\n\n< Date: Thu, 21 Jul 2016 15:38:46 GMT\n\n\n< Content-Type: text/html\n\n\n< Transfer-Encoding: chunked\n\n\n< Connection: keep-alive\n\n\n< Strict-Transport-Security: max-age=15724800; includeSubDomains; preload\n\n\n<\n\n\n<span>The page you're looking for could not be found.</span>\n\n\n\n* Connection #0 to host 10.2.78.7 left intact\n\n\n\n\n\n\nSpecifying \n--default-ssl-certificate=default/foo-tls\n:\n\n\ncore@localhost ~ $\n curl -v https://10.2.78.7:443 -k\n\n* Rebuilt URL to: https://10.2.78.7:443/\n\n\n* Trying 10.2.78.7...\n\n\n* Connected to 10.2.78.7 (10.2.78.7) port 443 (#0)\n\n\n* ALPN, offering http/1.1\n\n\n* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH\n\n\n* successfully set certificate verify locations:\n\n\n* CAfile: /etc/ssl/certs/ca-certificates.crt\n\n\n CApath: /etc/ssl/certs\n\n\n* TLSv1.2 (OUT), TLS header, Certificate Status (22):\n\n\n* TLSv1.2 (OUT), TLS handshake, Client hello (1):\n\n\n* TLSv1.2 (IN), TLS handshake, Server hello (2):\n\n\n* TLSv1.2 (IN), TLS handshake, Certificate (11):\n\n\n* TLSv1.2 (IN), TLS handshake, Server key exchange (12):\n\n\n* TLSv1.2 (IN), TLS handshake, Server finished (14):\n\n\n* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):\n\n\n* TLSv1.2 (OUT), TLS change cipher, Client hello (1):\n\n\n* TLSv1.2 (OUT), TLS handshake, Finished (20):\n\n\n* TLSv1.2 (IN), TLS change cipher, Client hello (1):\n\n\n* TLSv1.2 (IN), TLS handshake, Finished (20):\n\n\n* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256\n\n\n* ALPN, server accepted to use http/1.1\n\n\n* Server certificate:\n\n\n* subject: CN=foo.bar.com\n\n\n* start date: Apr 13 00:50:56 2016 GMT\n\n\n* expire date: Apr 13 00:50:56 2017 GMT\n\n\n* issuer: CN=foo.bar.com\n\n\n* SSL certificate verify result: self signed certificate (18), continuing anyway.\n\n\n>\n GET / HTTP/1.1\n\n>\n Host: \n10\n.2.78.7\n\n>\n User-Agent: curl/7.47.1\n\n>\n Accept: */*\n\n>\n\n\n< HTTP/1.1 404 Not Found\n\n\n< Server: nginx/1.11.1\n\n\n< Date: Mon, 18 Jul 2016 21:02:59 GMT\n\n\n< Content-Type: text/html\n\n\n< Transfer-Encoding: chunked\n\n\n< Connection: keep-alive\n\n\n< Strict-Transport-Security: max-age=15724800; includeSubDomains; preload\n\n\n<\n\n\n<span>The page you're looking for could not be found.</span>\n\n\n\n* Connection #0 to host 10.2.78.7 left intact\n\n\n\n\n\n\nSSL Passthrough\n\u00b6\n\n\nThe flag \n--enable-ssl-passthrough\n enables SSL passthrough feature.\nBy default this feature is disabled\n\n\nHTTP Strict Transport Security\n\u00b6\n\n\nHTTP Strict Transport Security (HSTS) is an opt-in security enhancement specified through the use of a special response header. Once a supported browser receives this header that browser will prevent any communications from being sent over HTTP to the specified domain and will instead send all communications over HTTPS.\n\n\nBy default the controller redirects (301) to HTTPS if there is a TLS Ingress rule.\n\n\nTo disable this behavior use \nhsts: \"false\"\n in the configuration ConfigMap.\n\n\nServer-side HTTPS enforcement through redirect\n\u00b6\n\n\nBy default the controller redirects (301) to \nHTTPS\n if TLS is enabled for that ingress. If you want to disable that behavior globally, you can use \nssl-redirect: \"false\"\n in the NGINX config map.\n\n\nTo configure this feature for specific ingress resources, you can use the \nnginx.ingress.kubernetes.io/ssl-redirect: \"false\"\n annotation in the particular resource.\n\n\nWhen using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to \nHTTPS\n even when there is not TLS cert available. This can be achieved by using the \nnginx.ingress.kubernetes.io/force-ssl-redirect: \"true\"\n annotation in the particular resource.\n\n\nAutomated Certificate Management with Kube-Lego\n\u00b6\n\n\nKube-Lego\n automatically requests missing or expired certificates from \nLet's Encrypt\n by monitoring ingress resources and their referenced secrets. To enable this for an ingress resource you have to add an annotation:\n\n\nkubectl annotate ing ingress-demo kubernetes.io/tls-acme=\"true\"\n\n\n\n\n\n\nTo setup Kube-Lego you can take a look at this \nfull example\n. The first\nversion to fully support Kube-Lego is nginx Ingress controller 0.8.\n\n\nDefault TLS Version and Ciphers\n\u00b6\n\n\nTo provide the most secure baseline configuration possible, nginx-ingress defaults to using TLS 1.2 and a \nsecure set of TLS ciphers\n\n\nLegacy TLS\n\u00b6\n\n\nThe default configuration, though secure, does not support some older browsers and operating systems. For instance, 20% of Android phones in use today are not compatible with nginx-ingress's default configuration. To change this default behavior, use a \nConfigMap\n.\n\n\nA sample ConfigMap to allow these older clients connect could look something like the following:\n\n\nkind\n:\n \nConfigMap\n\n\napiVersion\n:\n \nv1\n\n\nmetadata\n:\n\n \nname\n:\n \nnginx\n-\nconfig\n\n\ndata\n:\n\n \nssl\n-\nciphers\n:\n \n\"ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA\"\n\n \nssl\n-\nprotocols\n:\n \n\"TLSv1 TLSv1.1 TLSv1.2\"",
"title": "TLS"
},
{
"location": "/user-guide/tls/#tls",
"text": "Default SSL Certificate SSL Passthrough HTTPS enforcement HSTS Server-side HTTPS enforcement through redirect Kube-Lego Default TLS Version and Ciphers Legacy TLS",
"title": "TLS"
},
{
"location": "/user-guide/tls/#default-ssl-certificate",
"text": "NGINX provides the option to configure a server as a catch-all with server_name for requests that do not match any of the configured server names. This configuration works without issues for HTTP traffic.\nIn case of HTTPS, NGINX requires a certificate.\nFor this reason the Ingress controller provides the flag --default-ssl-certificate . The secret behind this flag contains the default certificate to be used in the mentioned scenario. If this flag is not provided NGINX will use a self signed certificate. Running without the flag --default-ssl-certificate : $ curl -v https://10.2.78.7:443 -k * Rebuilt URL to: https://10.2.78.7:443/ * Trying 10.2.78.4... * Connected to 10.2.78.7 (10.2.78.7) port 443 (#0) * ALPN, offering http/1.1 * Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH * successfully set certificate verify locations: * CAfile: /etc/ssl/certs/ca-certificates.crt CApath: /etc/ssl/certs * TLSv1.2 (OUT), TLS header, Certificate Status (22): * TLSv1.2 (OUT), TLS handshake, Client hello (1): * TLSv1.2 (IN), TLS handshake, Server hello (2): * TLSv1.2 (IN), TLS handshake, Certificate (11): * TLSv1.2 (IN), TLS handshake, Server key exchange (12): * TLSv1.2 (IN), TLS handshake, Server finished (14): * TLSv1.2 (OUT), TLS handshake, Client key exchange (16): * TLSv1.2 (OUT), TLS change cipher, Client hello (1): * TLSv1.2 (OUT), TLS handshake, Finished (20): * TLSv1.2 (IN), TLS change cipher, Client hello (1): * TLSv1.2 (IN), TLS handshake, Finished (20): * SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256 * ALPN, server accepted to use http/1.1 * Server certificate: * subject: CN=foo.bar.com * start date: Apr 13 00:50:56 2016 GMT * expire date: Apr 13 00:50:56 2017 GMT * issuer: CN=foo.bar.com * SSL certificate verify result: self signed certificate (18), continuing anyway. > GET / HTTP/1.1 > Host: 10 .2.78.7 > User-Agent: curl/7.47.1 > Accept: */* > < HTTP/1.1 404 Not Found < Server: nginx/1.11.1 < Date: Thu, 21 Jul 2016 15:38:46 GMT < Content-Type: text/html < Transfer-Encoding: chunked < Connection: keep-alive < Strict-Transport-Security: max-age=15724800; includeSubDomains; preload < <span>The page you're looking for could not be found.</span> * Connection #0 to host 10.2.78.7 left intact Specifying --default-ssl-certificate=default/foo-tls : core@localhost ~ $ curl -v https://10.2.78.7:443 -k * Rebuilt URL to: https://10.2.78.7:443/ * Trying 10.2.78.7... * Connected to 10.2.78.7 (10.2.78.7) port 443 (#0) * ALPN, offering http/1.1 * Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH * successfully set certificate verify locations: * CAfile: /etc/ssl/certs/ca-certificates.crt CApath: /etc/ssl/certs * TLSv1.2 (OUT), TLS header, Certificate Status (22): * TLSv1.2 (OUT), TLS handshake, Client hello (1): * TLSv1.2 (IN), TLS handshake, Server hello (2): * TLSv1.2 (IN), TLS handshake, Certificate (11): * TLSv1.2 (IN), TLS handshake, Server key exchange (12): * TLSv1.2 (IN), TLS handshake, Server finished (14): * TLSv1.2 (OUT), TLS handshake, Client key exchange (16): * TLSv1.2 (OUT), TLS change cipher, Client hello (1): * TLSv1.2 (OUT), TLS handshake, Finished (20): * TLSv1.2 (IN), TLS change cipher, Client hello (1): * TLSv1.2 (IN), TLS handshake, Finished (20): * SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256 * ALPN, server accepted to use http/1.1 * Server certificate: * subject: CN=foo.bar.com * start date: Apr 13 00:50:56 2016 GMT * expire date: Apr 13 00:50:56 2017 GMT * issuer: CN=foo.bar.com * SSL certificate verify result: self signed certificate (18), continuing anyway. > GET / HTTP/1.1 > Host: 10 .2.78.7 > User-Agent: curl/7.47.1 > Accept: */* > < HTTP/1.1 404 Not Found < Server: nginx/1.11.1 < Date: Mon, 18 Jul 2016 21:02:59 GMT < Content-Type: text/html < Transfer-Encoding: chunked < Connection: keep-alive < Strict-Transport-Security: max-age=15724800; includeSubDomains; preload < <span>The page you're looking for could not be found.</span> * Connection #0 to host 10.2.78.7 left intact",
"title": "Default SSL Certificate"
},
{
"location": "/user-guide/tls/#ssl-passthrough",
"text": "The flag --enable-ssl-passthrough enables SSL passthrough feature.\nBy default this feature is disabled",
"title": "SSL Passthrough"
},
{
"location": "/user-guide/tls/#http-strict-transport-security",
"text": "HTTP Strict Transport Security (HSTS) is an opt-in security enhancement specified through the use of a special response header. Once a supported browser receives this header that browser will prevent any communications from being sent over HTTP to the specified domain and will instead send all communications over HTTPS. By default the controller redirects (301) to HTTPS if there is a TLS Ingress rule. To disable this behavior use hsts: \"false\" in the configuration ConfigMap.",
"title": "HTTP Strict Transport Security"
},
{
"location": "/user-guide/tls/#server-side-https-enforcement-through-redirect",
"text": "By default the controller redirects (301) to HTTPS if TLS is enabled for that ingress. If you want to disable that behavior globally, you can use ssl-redirect: \"false\" in the NGINX config map. To configure this feature for specific ingress resources, you can use the nginx.ingress.kubernetes.io/ssl-redirect: \"false\" annotation in the particular resource. When using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to HTTPS even when there is not TLS cert available. This can be achieved by using the nginx.ingress.kubernetes.io/force-ssl-redirect: \"true\" annotation in the particular resource.",
"title": "Server-side HTTPS enforcement through redirect"
},
{
"location": "/user-guide/tls/#automated-certificate-management-with-kube-lego",
"text": "Kube-Lego automatically requests missing or expired certificates from Let's Encrypt by monitoring ingress resources and their referenced secrets. To enable this for an ingress resource you have to add an annotation: kubectl annotate ing ingress-demo kubernetes.io/tls-acme=\"true\" To setup Kube-Lego you can take a look at this full example . The first\nversion to fully support Kube-Lego is nginx Ingress controller 0.8.",
"title": "Automated Certificate Management with Kube-Lego"
},
{
"location": "/user-guide/tls/#default-tls-version-and-ciphers",
"text": "To provide the most secure baseline configuration possible, nginx-ingress defaults to using TLS 1.2 and a secure set of TLS ciphers",
"title": "Default TLS Version and Ciphers"
},
{
"location": "/user-guide/tls/#legacy-tls",
"text": "The default configuration, though secure, does not support some older browsers and operating systems. For instance, 20% of Android phones in use today are not compatible with nginx-ingress's default configuration. To change this default behavior, use a ConfigMap . A sample ConfigMap to allow these older clients connect could look something like the following: kind : ConfigMap apiVersion : v1 metadata : \n name : nginx - config data : \n ssl - ciphers : \"ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA\" \n ssl - protocols : \"TLSv1 TLSv1.1 TLSv1.2\"",
"title": "Legacy TLS"
},
{
"location": "/user-guide/third-party-addons/modsecurity/",
"text": "ModSecurity Web Application Firewall\n\u00b6\n\n\nModSecurity is an open source, cross platform web application firewall (WAF) engine for Apache, IIS and Nginx that is developed by Trustwave's SpiderLabs. It has a robust event-based programming language which provides protection from a range of attacks against web applications and allows for HTTP traffic monitoring, logging and real-time analysis - \nhttps://www.modsecurity.org\n\n\nThe \nModSecurity-nginx\n connector is the connection point between NGINX and libmodsecurity (ModSecurity v3).\n\n\nThe default ModSecurity configuration file is located in \n/etc/nginx/modsecurity/modsecurity.conf\n. This is the only file located in this directory and contains the default recommended configuration. Using a volume we can replace this file with the desired configuration.\nTo enable the ModSecurity feature we need to specify \nenable-modsecurity: \"true\"\n in the configuration configmap.\n\n\n\n\nNote:\n the default configuration use detection only, because that minimises the chances of post-installation disruption.\nThe file \n/var/log/modsec_audit.log\n contains the log of ModSecurity.\n\n\n\n\nThe OWASP ModSecurity Core Rule Set (CRS) is a set of generic attack detection rules for use with ModSecurity or compatible web application firewalls. The CRS aims to protect web applications from a wide range of attacks, including the OWASP Top Ten, with a minimum of false alerts.\nThe directory \n/etc/nginx/owasp-modsecurity-crs\n contains the \nhttps://github.com/SpiderLabs/owasp-modsecurity-crs repository\n.\nUsing \nenable-owasp-modsecurity-crs: \"true\"\n we enable the use of the rules.",
"title": "ModSecurity Web Application Firewall"
},
{
"location": "/user-guide/third-party-addons/modsecurity/#modsecurity-web-application-firewall",
"text": "ModSecurity is an open source, cross platform web application firewall (WAF) engine for Apache, IIS and Nginx that is developed by Trustwave's SpiderLabs. It has a robust event-based programming language which provides protection from a range of attacks against web applications and allows for HTTP traffic monitoring, logging and real-time analysis - https://www.modsecurity.org The ModSecurity-nginx connector is the connection point between NGINX and libmodsecurity (ModSecurity v3). The default ModSecurity configuration file is located in /etc/nginx/modsecurity/modsecurity.conf . This is the only file located in this directory and contains the default recommended configuration. Using a volume we can replace this file with the desired configuration.\nTo enable the ModSecurity feature we need to specify enable-modsecurity: \"true\" in the configuration configmap. Note: the default configuration use detection only, because that minimises the chances of post-installation disruption.\nThe file /var/log/modsec_audit.log contains the log of ModSecurity. The OWASP ModSecurity Core Rule Set (CRS) is a set of generic attack detection rules for use with ModSecurity or compatible web application firewalls. The CRS aims to protect web applications from a wide range of attacks, including the OWASP Top Ten, with a minimum of false alerts.\nThe directory /etc/nginx/owasp-modsecurity-crs contains the https://github.com/SpiderLabs/owasp-modsecurity-crs repository .\nUsing enable-owasp-modsecurity-crs: \"true\" we enable the use of the rules.",
"title": "ModSecurity Web Application Firewall"
},
{
"location": "/user-guide/third-party-addons/opentracing/",
"text": "OpenTracing\n\u00b6\n\n\nUsing the third party module \nopentracing-contrib/nginx-opentracing\n the NGINX ingress controller can configure NGINX to enable \nOpenTracing\n instrumentation.\nBy default this feature is disabled.\n\n\nTo enable the instrumentation we just need to enable the instrumentation in the configuration configmap and set the host where we should send the traces.\n\n\nIn the \nrnburn/zipkin-date-server\n\ngithub repository is an example of a dockerized date service. To install the example and zipkin collector run:\n\n\nkubectl create -f https://raw.githubusercontent.com/rnburn/zipkin-date-server/master/kubernetes/zipkin.yaml\nkubectl create -f https://raw.githubusercontent.com/rnburn/zipkin-date-server/master/kubernetes/deployment.yaml\n\n\n\n\n\nAlso we need to configure the NGINX controller configmap with the required values:\n\n\n$ \necho\n \n'\n\n\napiVersion: v1\n\n\nkind: ConfigMap\n\n\ndata:\n\n\n enable-opentracing: \"true\"\n\n\n zipkin-collector-host: zipkin.default.svc.cluster.local\n\n\nmetadata:\n\n\n name: nginx-configuration\n\n\n namespace: ingress-nginx\n\n\n labels:\n\n\n app: ingress-nginx\n\n\n'\n \n|\n kubectl replace -f -\n\n\n\n\n\nUsing curl we can generate some traces:\n\n\n$\n curl -v http://\n$(\nminikube ip\n)\n\n\n$\n curl -v http://\n$(\nminikube ip\n)\n\n\n\n\n\n\nIn the zipkin interface we can see the details:",
"title": "OpenTracing"
},
{
"location": "/user-guide/third-party-addons/opentracing/#opentracing",
"text": "Using the third party module opentracing-contrib/nginx-opentracing the NGINX ingress controller can configure NGINX to enable OpenTracing instrumentation.\nBy default this feature is disabled. To enable the instrumentation we just need to enable the instrumentation in the configuration configmap and set the host where we should send the traces. In the rnburn/zipkin-date-server \ngithub repository is an example of a dockerized date service. To install the example and zipkin collector run: kubectl create -f https://raw.githubusercontent.com/rnburn/zipkin-date-server/master/kubernetes/zipkin.yaml\nkubectl create -f https://raw.githubusercontent.com/rnburn/zipkin-date-server/master/kubernetes/deployment.yaml Also we need to configure the NGINX controller configmap with the required values: $ echo ' apiVersion: v1 kind: ConfigMap data: enable-opentracing: \"true\" zipkin-collector-host: zipkin.default.svc.cluster.local metadata: name: nginx-configuration namespace: ingress-nginx labels: app: ingress-nginx ' | kubectl replace -f - Using curl we can generate some traces: $ curl -v http:// $( minikube ip ) $ curl -v http:// $( minikube ip ) In the zipkin interface we can see the details:",
"title": "OpenTracing"
},
{
"location": "/examples/PREREQUISITES/",
"text": "Prerequisites\n\u00b6\n\n\nMany of the examples in this directory have common prerequisites.\n\n\nTLS certificates\n\u00b6\n\n\nUnless otherwise mentioned, the TLS secret used in examples is a 2048 bit RSA\nkey/cert pair with an arbitrarily chosen hostname, created as follows\n\n\n$\n openssl req -x509 -nodes -days \n365\n -newkey rsa:2048 -keyout tls.key -out tls.crt -subj \n\"/CN=nginxsvc/O=nginxsvc\"\n\n\nGenerating a 2048 bit RSA private key\n\n\n................+++\n\n\n................+++\n\n\nwriting new private key to 'tls.key'\n\n\n-----\n\n\n\n$\n kubectl create secret tls tls-secret --key tls.key --cert tls.crt\n\nsecret \"tls-secret\" created\n\n\n\n\n\n\nCA Authentication\n\u00b6\n\n\nYou can act as your very own CA, or use an existing one. As an exercise / learning, we're going to generate our\nown CA, and also generate a client certificate.\n\n\nThese instructions are based on CoreOS OpenSSL. \nSee live doc.\n\n\nGenerating a CA\n\u00b6\n\n\nFirst of all, you've to generate a CA. This is going to be the one who will sign your client certificates.\nIn real production world, you may face CAs with intermediate certificates, as the following:\n\n\n$\n openssl s_client -connect www.google.com:443\n\n[...]\n\n\n---\n\n\nCertificate chain\n\n\n 0 s:/C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com\n\n\n i:/C=US/O=Google Inc/CN=Google Internet Authority G2\n\n\n 1 s:/C=US/O=Google Inc/CN=Google Internet Authority G2\n\n\n i:/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA\n\n\n 2 s:/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA\n\n\n i:/C=US/O=Equifax/OU=Equifax Secure Certificate Authority\n\n\n\n\n\n\nTo generate our CA Certificate, we've to run the following commands:\n\n\n$\n openssl genrsa -out ca.key \n2048\n\n\n$\n openssl req -x509 -new -nodes -key ca.key -days \n10000\n -out ca.crt -subj \n\"/CN=example-ca\"\n\n\n\n\n\n\nThis will generate two files: A private key (ca.key) and a public key (ca.crt). This CA is valid for 10000 days.\nThe ca.crt can be used later in the step of creation of CA authentication secret.\n\n\nGenerating the client certificate\n\u00b6\n\n\nThe following steps generate a client certificate signed by the CA generated above. This client can be\nused to authenticate in a tls-auth configured ingress.\n\n\nFirst, we need to generate an 'openssl.cnf' file that will be used while signing the keys:\n\n\n[req]\n\n\nreq_extensions = v3_req\n\n\ndistinguished_name = req_distinguished_name\n\n\n[req_distinguished_name]\n\n\n[ v3_req ]\n\n\nbasicConstraints = CA:FALSE\n\n\nkeyUsage = nonRepudiation, digitalSignature, keyEncipherment\n\n\n\n\n\n\nThen, a user generates his very own private key (that he needs to keep secret)\nand a CSR (Certificate Signing Request) that will be sent to the CA to sign and generate a certificate.\n\n\n$\n openssl genrsa -out client1.key \n2048\n\n\n$\n openssl req -new -key client1.key -out client1.csr -subj \n\"/CN=client1\"\n -config openssl.cnf\n\n\n\n\n\nAs the CA receives the generated 'client1.csr' file, it signs it and generates a client.crt certificate:\n\n\n$\n openssl x509 -req -in client1.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client1.crt -days \n365\n -extensions v3_req -extfile openssl.cnf\n\n\n\n\n\nThen, you'll have 3 files: the client.key (user's private key), client.crt (user's public key) and client.csr (disposable CSR).\n\n\nCreating the CA Authentication secret\n\u00b6\n\n\nIf you're using the CA Authentication feature, you need to generate a secret containing \nall the authorized CAs. You must download them from your CA site in PEM format (like the following):\n\n\n-----BEGIN CERTIFICATE-----\n[....]\n-----END CERTIFICATE-----\n\n\n\n\n\nYou can have as many certificates as you want. If they're in the binary DER format, \nyou can convert them as the following:\n\n\n$\n openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem\n\n\n\n\n\nThen, you've to concatenate them all in only one file, named 'ca.crt' as the following:\n\n\n$\n cat certificate1.crt certificate2.crt certificate3.crt >> ca.crt\n\n\n\n\n\nThe final step is to create a secret with the content of this file. This secret is going to be used in \nthe TLS Auth directive:\n\n\n$\n kubectl create secret generic caingress --namespace\n=\ndefault --from-file\n=\nca.crt\n=\n<ca.crt>\n\n\n\n\n\nNote:\n You can also generate the CA Authentication Secret along with the TLS Secret by using:\n\n\n$\n kubectl create secret generic caingress --namespace\n=\ndefault --from-file\n=\nca.crt\n=\n<ca.crt> --from-file\n=\ntls.crt\n=\n<tls.crt> --from-file\n=\ntls.key\n=\n<tls.key>\n\n\n\n\n\nTest HTTP Service\n\u00b6\n\n\nAll examples that require a test HTTP Service use the standard http-svc pod,\nwhich you can deploy as follows\n\n\n$\n kubectl create -f http-svc.yaml\n\nservice \"http-svc\" created\n\n\nreplicationcontroller \"http-svc\" created\n\n\n\n$\n kubectl get po\n\nNAME READY STATUS RESTARTS AGE\n\n\nhttp-svc-p1t3t 1/1 Running 0 1d\n\n\n\n$\n kubectl get svc\n\nNAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE\n\n\nhttp-svc 10.0.122.116 <pending> 80:30301/TCP 1d\n\n\n\n\n\n\nYou can test that the HTTP Service works by exposing it temporarily\n\n\n$\n kubectl patch svc http-svc -p \n'{\"spec\":{\"type\": \"LoadBalancer\"}}'\n\n\n\"http-svc\" patched\n\n\n\n$\n kubectl get svc http-svc\n\nNAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE\n\n\nhttp-svc 10.0.122.116 <pending> 80:30301/TCP 1d\n\n\n\n$\n kubectl describe svc http-svc\n\nName: http-svc\n\n\nNamespace: default\n\n\nLabels: app=http-svc\n\n\nSelector: app=http-svc\n\n\nType: LoadBalancer\n\n\nIP: 10.0.122.116\n\n\nLoadBalancer Ingress: 108.59.87.136\n\n\nPort: http 80/TCP\n\n\nNodePort: http 30301/TCP\n\n\nEndpoints: 10.180.1.6:8080\n\n\nSession Affinity: None\n\n\nEvents:\n\n\n FirstSeen LastSeen Count From SubObjectPath Type Reason Message\n\n\n --------- -------- ----- ---- ------------- -------- ------ -------\n\n\n 1m 1m 1 {service-controller } Normal Type ClusterIP -> LoadBalancer\n\n\n 1m 1m 1 {service-controller } Normal CreatingLoadBalancer Creating load balancer\n\n\n 16s 16s 1 {service-controller } Normal CreatedLoadBalancer Created load balancer\n\n\n\n$\n curl \n108\n.59.87.126\n\nCLIENT VALUES:\n\n\nclient_address=10.240.0.3\n\n\ncommand=GET\n\n\nreal path=/\n\n\nquery=nil\n\n\nrequest_version=1.1\n\n\nrequest_uri=http://108.59.87.136:8080/\n\n\n\nSERVER VALUES:\n\n\nserver_version=nginx: 1.9.11 - lua: 10001\n\n\n\nHEADERS RECEIVED:\n\n\naccept=*/*\n\n\nhost=108.59.87.136\n\n\nuser-agent=curl/7.46.0\n\n\nBODY:\n\n\n-no body in request-\n\n\n\n$\n kubectl patch svc http-svc -p \n'{\"spec\":{\"type\": \"NodePort\"}}'\n\n\n\"http-svc\" patched",
"title": "Prerequisites"
},
{
"location": "/examples/PREREQUISITES/#prerequisites",
"text": "Many of the examples in this directory have common prerequisites.",
"title": "Prerequisites"
},
{
"location": "/examples/PREREQUISITES/#tls-certificates",
"text": "Unless otherwise mentioned, the TLS secret used in examples is a 2048 bit RSA\nkey/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",
"title": "TLS certificates"
},
{
"location": "/examples/PREREQUISITES/#ca-authentication",
"text": "You can act as your very own CA, or use an existing one. As an exercise / learning, we're going to generate our\nown CA, and also generate a client certificate. These instructions are based on CoreOS OpenSSL. See live doc.",
"title": "CA Authentication"
},
{
"location": "/examples/PREREQUISITES/#generating-a-ca",
"text": "First of all, you've to generate a CA. This is going to be the one who will sign your client certificates.\nIn real production world, you may face CAs with intermediate certificates, as the following: $ 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.\nThe ca.crt can be used later in the step of creation of CA authentication secret.",
"title": "Generating a CA"
},
{
"location": "/examples/PREREQUISITES/#generating-the-client-certificate",
"text": "The following steps generate a client certificate signed by the CA generated above. This client can be\nused to authenticate in a tls-auth configured ingress. 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)\nand 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).",
"title": "Generating the client certificate"
},
{
"location": "/examples/PREREQUISITES/#creating-the-ca-authentication-secret",
"text": "If you're using the CA Authentication feature, you need to generate a secret containing \nall the authorized CAs. You must download them from your CA site in PEM format (like the following): -----BEGIN CERTIFICATE-----\n[....]\n-----END CERTIFICATE----- You can have as many certificates as you want. If they're in the binary DER format, \nyou 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 \nthe 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>",
"title": "Creating the CA Authentication secret"
},
{
"location": "/examples/PREREQUISITES/#test-http-service",
"text": "All examples that require a test HTTP Service use the standard http-svc pod,\nwhich you can deploy as follows $ kubectl create -f http-svc.yaml service \"http-svc\" created replicationcontroller \"http-svc\" created $ kubectl get po NAME READY STATUS RESTARTS AGE http-svc-p1t3t 1/1 Running 0 1d $ kubectl get svc NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE http-svc 10.0.122.116 <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",
"title": "Test HTTP Service"
},
{
"location": "/examples/README/",
"text": "Ingress examples\n\u00b6\n\n\nThis directory contains a catalog of examples on how to run, configure and\nscale Ingress. Please review the \nprerequisites\n before\ntrying them.\n\n\nScaling\n\u00b6\n\n\n\n\n\n\n\n\nName\n\n\nDescription\n\n\nComplexity Level\n\n\n\n\n\n\n\n\n\n\nStatic-ip\n\n\na single ingress gets a single static ip\n\n\nIntermediate\n\n\n\n\n\n\n\n\nAlgorithms\n\u00b6\n\n\n\n\n\n\n\n\nName\n\n\nDescription\n\n\nComplexity Level\n\n\n\n\n\n\n\n\n\n\nSession stickyness\n\n\nroute requests consistently to the same endpoint\n\n\nAdvanced\n\n\n\n\n\n\n\n\nAuth\n\u00b6\n\n\n\n\n\n\n\n\nName\n\n\nDescription\n\n\nComplexity Level\n\n\n\n\n\n\n\n\n\n\nBasic auth\n\n\npassword protect your website\n\n\nnginx\n\n\n\n\n\n\nClient certificate authentication\n\n\nsecure your website with client certificate authentication\n\n\nnginx\n\n\n\n\n\n\nExternal auth plugin\n\n\ndefer to an external auth service\n\n\nIntermediate\n\n\n\n\n\n\n\n\nCustomization\n\u00b6\n\n\n\n\n\n\n\n\nName\n\n\nDescription\n\n\nComplexity Level\n\n\n\n\n\n\n\n\n\n\nconfiguration-snippets\n\n\ncustomize nginx location configuration using annotations\n\n\nAdvanced\n\n\n\n\n\n\ncustom-headers\n\n\nset custom headers before send traffic to backends\n\n\nAdvanced",
"title": "Ingress examples"
},
{
"location": "/examples/README/#ingress-examples",
"text": "This directory contains a catalog of examples on how to run, configure and\nscale Ingress. Please review the prerequisites before\ntrying them.",
"title": "Ingress examples"
},
{
"location": "/examples/README/#scaling",
"text": "Name Description Complexity Level Static-ip a single ingress gets a single static ip Intermediate",
"title": "Scaling"
},
{
"location": "/examples/README/#algorithms",
"text": "Name Description Complexity Level Session stickyness route requests consistently to the same endpoint Advanced",
"title": "Algorithms"
},
{
"location": "/examples/README/#auth",
"text": "Name Description Complexity Level Basic auth password protect your website nginx Client certificate authentication secure your website with client certificate authentication nginx External auth plugin defer to an external auth service Intermediate",
"title": "Auth"
},
{
"location": "/examples/README/#customization",
"text": "Name Description Complexity Level configuration-snippets customize nginx location configuration using annotations Advanced custom-headers set custom headers before send traffic to backends Advanced",
"title": "Customization"
},
{
"location": "/examples/affinity/cookie/README/",
"text": "Sticky Session\n\u00b6\n\n\nThis example demonstrates how to achieve session affinity using cookies\n\n\nDeployment\n\u00b6\n\n\nSession stickiness is achieved through 3 annotations on the Ingress, as shown in the \nexample\n.\n\n\n\n\n\n\n\n\nName\n\n\nDescription\n\n\nValues\n\n\n\n\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/affinity\n\n\nSets the affinity type\n\n\nstring (in NGINX only \ncookie\n is possible\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/session-cookie-name\n\n\nName of the cookie that will be used\n\n\nstring (default to INGRESSCOOKIE)\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/session-cookie-hash\n\n\nType of hash that will be used in cookie value\n\n\nsha1/md5/index\n\n\n\n\n\n\n\n\nYou can create the ingress to test this\n\n\nkubectl create -f ingress.yaml\n\n\n\n\n\n\nValidation\n\u00b6\n\n\nYou can confirm that the Ingress works.\n\n\n$\n kubectl describe ing nginx-test\n\nName: nginx-test\n\n\nNamespace: default\n\n\nAddress: \n\n\nDefault backend: default-http-backend:80 (10.180.0.4:8080,10.240.0.2:8080)\n\n\nRules:\n\n\n Host Path Backends\n\n\n ---- ---- --------\n\n\n stickyingress.example.com \n\n\n / nginx-service:80 (<none>)\n\n\nAnnotations:\n\n\n affinity: cookie\n\n\n session-cookie-hash: sha1\n\n\n session-cookie-name: INGRESSCOOKIE\n\n\nEvents:\n\n\n FirstSeen LastSeen Count From SubObjectPath Type Reason Message\n\n\n --------- -------- ----- ---- ------------- -------- ------ -------\n\n\n 7s 7s 1 {nginx-ingress-controller } Normal CREATE default/nginx-test\n\n\n\n\n$\n curl -I http://stickyingress.example.com\n\nHTTP/1.1 200 OK\n\n\nServer: nginx/1.11.9\n\n\nDate: Fri, 10 Feb 2017 14:11:12 GMT\n\n\nContent-Type: text/html\n\n\nContent-Length: 612\n\n\nConnection: keep-alive\n\n\nSet-Cookie: INGRESSCOOKIE=a9907b79b248140b56bb13723f72b67697baac3d; Path=/; HttpOnly\n\n\nLast-Modified: Tue, 24 Jan 2017 14:02:19 GMT\n\n\nETag: \"58875e6b-264\"\n\n\nAccept-Ranges: bytes\n\n\n\n\n\n\nIn the example above, you can see a line containing the 'Set-Cookie: INGRESSCOOKIE' setting the right defined stickiness cookie.\nThis cookie is created by NGINX containing the hash of the used upstream in that request. \nIf the user changes this cookie, NGINX creates a new one and redirect the user to another upstream.\n\n\nIf the backend pool grows up NGINX will keep sending the requests through the same server of the first request, even if it's overloaded.\n\n\nWhen the backend server is removed, the requests are then re-routed to another upstream server and NGINX creates a new cookie, as the previous hash became invalid.\n\n\nWhen you have more than one Ingress Object pointing to the same Service, but one containing affinity configuration and other don't, the first created Ingress will be used. \nThis means that you can face the situation that you've configured Session Affinity in one Ingress and it doesn't reflects in NGINX configuration, because there is another Ingress Object pointing to the same service that doesn't configure this.",
"title": "Sticky Session"
},
{
"location": "/examples/affinity/cookie/README/#sticky-session",
"text": "This example demonstrates how to achieve session affinity using cookies",
"title": "Sticky Session"
},
{
"location": "/examples/affinity/cookie/README/#deployment",
"text": "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",
"title": "Deployment"
},
{
"location": "/examples/affinity/cookie/README/#validation",
"text": "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.\nThis cookie is created by NGINX containing the hash of the used upstream in that request. \nIf the user changes this cookie, NGINX creates a new one and redirect the user to another upstream. 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. \nThis means that you can face the situation that you've configured Session Affinity in one Ingress and it doesn't reflects in NGINX configuration, because there is another Ingress Object pointing to the same service that doesn't configure this.",
"title": "Validation"
},
{
"location": "/examples/auth/basic/README/",
"text": "Basic Authentication\n\u00b6\n\n\nThis example shows how to add authentication in a Ingress rule using a secret that contains a file generated with \nhtpasswd\n.\n\n\n$\n htpasswd -c auth foo\n\nNew password: <bar>\n\n\nNew password:\n\n\nRe-type new password:\n\n\nAdding password for user foo\n\n\n\n\n\n\n$\n kubectl create secret generic basic-auth --from-file\n=\nauth\n\nsecret \"basic-auth\" created\n\n\n\n\n\n\n$\n kubectl get secret basic-auth -o yaml\n\napiVersion: v1\n\n\ndata:\n\n\n auth: Zm9vOiRhcHIxJE9GRzNYeWJwJGNrTDBGSERBa29YWUlsSDkuY3lzVDAK\n\n\nkind: Secret\n\n\nmetadata:\n\n\n name: basic-auth\n\n\n namespace: default\n\n\ntype: Opaque\n\n\n\n\n\n\necho \"\n\n\napiVersion: extensions/v1beta1\n\n\nkind: Ingress\n\n\nmetadata:\n\n\n name: ingress-with-auth\n\n\n annotations:\n\n\n #\n \ntype\n of authentication\n\n nginx.ingress.kubernetes.io/auth-type: basic\n\n\n #\n name of the secret that contains the user/password definitions\n\n nginx.ingress.kubernetes.io/auth-secret: basic-auth\n\n\n #\n message to display with an appropriate context why the authentication is required\n\n nginx.ingress.kubernetes.io/auth-realm: \"Authentication Required - foo\"\n\n\nspec:\n\n\n rules:\n\n\n - host: foo.bar.com\n\n\n http:\n\n\n paths:\n\n\n - path: /\n\n\n backend:\n\n\n serviceName: http-svc\n\n\n servicePort: 80\n\n\n\" | kubectl create -f -\n\n\n\n\n\n\n$ curl -v http://10.2.29.4/ -H 'Host: foo.bar.com'\n* Trying 10.2.29.4...\n* Connected to 10.2.29.4 (10.2.29.4) port 80 (#0)\n> GET / HTTP/1.1\n> Host: foo.bar.com\n> User-Agent: curl/7.43.0\n> Accept: */*\n>\n\n< HTTP\n/1.1\n \n401\n \nUnauthorized\n\n\n<\n \nServer:\n \nnginx/1.10.0\n\n\n<\n \nDate:\n \nWed,\n \n11\n \nMay\n \n2016\n \n05:27:23\n \nGMT\n\n\n<\n \nContent-Type:\n \ntext/html\n\n\n<\n \nContent-Length:\n \n195\n\n\n<\n \nConnection:\n \nkeep-alive\n\n\n<\n \nWWW-Authenticate:\n \nBasic\n \nrealm=\n\"Authentication Required - foo\"\n\n\n<\n\n\n<html\n>\n\n\n<head><title>\n401 Authorization Required\n</title></head>\n\n\n<body\n \nbgcolor=\n\"white\"\n>\n\n\n<center><h1>\n401 Authorization Required\n</h1></center>\n\n\n<hr><center>\nnginx/1.10.0\n</center>\n\n\n</body>\n\n\n</html>\n\n* Connection #0 to host 10.2.29.4 left intact\n\n\n\n\n\n$ curl -v http://10.2.29.4/ -H \n'Host: foo.bar.com'\n -u \n'foo:bar'\n\n* Trying \n10\n.2.29.4...\n* Connected to \n10\n.2.29.4 \n(\n10\n.2.29.4\n)\n port \n80\n \n(\n#0)\n\n* Server auth using Basic with user \n'foo'\n\n> GET / HTTP/1.1\n> Host: foo.bar.com\n> Authorization: Basic \nZm9vOmJhcg\n==\n\n> User-Agent: curl/7.43.0\n> Accept: */*\n>\n< HTTP/1.1 \n200\n OK\n< Server: nginx/1.10.0\n< Date: Wed, \n11\n May \n2016\n \n06\n:05:26 GMT\n< Content-Type: text/plain\n< Transfer-Encoding: chunked\n< Connection: keep-alive\n< Vary: Accept-Encoding\n<\nCLIENT VALUES:\n\nclient_address\n=\n10\n.2.29.4\n\ncommand\n=\nGET\nreal \npath\n=\n/\n\nquery\n=\nnil\n\nrequest_version\n=\n1\n.1\n\nrequest_uri\n=\nhttp://foo.bar.com:8080/\n\nSERVER VALUES:\n\nserver_version\n=\nnginx: \n1\n.9.11 - lua: \n10001\n\n\nHEADERS RECEIVED:\n\naccept\n=\n*/*\n\nauthorization\n=\nBasic \nZm9vOmJhcg\n==\n\n\nconnection\n=\nclose\n\nhost\n=\nfoo.bar.com\nuser-agent\n=\ncurl/7.43.0\nx-forwarded-for\n=\n10\n.2.29.1\nx-forwarded-host\n=\nfoo.bar.com\nx-forwarded-port\n=\n80\n\nx-forwarded-proto\n=\nhttp\nx-real-ip\n=\n10\n.2.29.1\nBODY:\n* Connection \n#0 to host 10.2.29.4 left intact\n\n-no body in request-",
"title": "Basic Authentication"
},
{
"location": "/examples/auth/basic/README/#basic-authentication",
"text": "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'\n* Trying 10.2.29.4...\n* Connected to 10.2.29.4 (10.2.29.4) port 80 (#0)\n> GET / HTTP/1.1\n> Host: foo.bar.com\n> User-Agent: curl/7.43.0\n> Accept: */*\n> < 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> \n* 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' \n* Trying 10 .2.29.4...\n* Connected to 10 .2.29.4 ( 10 .2.29.4 ) port 80 ( #0) \n* Server auth using Basic with user 'foo' \n> GET / HTTP/1.1\n> Host: foo.bar.com\n> Authorization: Basic Zm9vOmJhcg == \n> User-Agent: curl/7.43.0\n> Accept: */*\n>\n< HTTP/1.1 200 OK\n< Server: nginx/1.10.0\n< Date: Wed, 11 May 2016 06 :05:26 GMT\n< Content-Type: text/plain\n< Transfer-Encoding: chunked\n< Connection: keep-alive\n< Vary: Accept-Encoding\n<\nCLIENT VALUES: client_address = 10 .2.29.4 command = GET\nreal path = / query = nil request_version = 1 .1 request_uri = http://foo.bar.com:8080/\n\nSERVER VALUES: server_version = nginx: 1 .9.11 - lua: 10001 \n\nHEADERS RECEIVED: accept = */* authorization = Basic Zm9vOmJhcg == connection = close host = foo.bar.com\nuser-agent = curl/7.43.0\nx-forwarded-for = 10 .2.29.1\nx-forwarded-host = foo.bar.com\nx-forwarded-port = 80 \nx-forwarded-proto = http\nx-real-ip = 10 .2.29.1\nBODY:\n* Connection #0 to host 10.2.29.4 left intact \n-no body in request-",
"title": "Basic Authentication"
},
{
"location": "/examples/auth/client-certs/README/",
"text": "Client Certificate Authentication\n\u00b6\n\n\nIt is possible to enable Client Certificate Authentication using additional annotations in the Ingress.\n\n\nSetup instructions\n\u00b6\n\n\n\n\n\n\nCreate a file named \nca.crt\n containing the trusted certificate authority chain (all ca certificates in PEM format) to verify client certificates. \n\n\n\n\n\n\nCreate a secret from this file:\n\nkubectl create secret generic auth-tls-chain --from-file=ca.crt --namespace=default\n\n\n\n\n\n\nAdd the annotations as provided in the \ningress.yaml\n example to your ingress object.",
"title": "Client Certificate Authentication"
},
{
"location": "/examples/auth/client-certs/README/#client-certificate-authentication",
"text": "It is possible to enable Client Certificate Authentication using additional annotations in the Ingress.",
"title": "Client Certificate Authentication"
},
{
"location": "/examples/auth/client-certs/README/#setup-instructions",
"text": "Create a file named ca.crt containing 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.",
"title": "Setup instructions"
},
{
"location": "/examples/auth/external-auth/README/",
"text": "External authentication\n\u00b6\n\n\nExample 1:\n\u00b6\n\n\nUse an external service (Basic Auth) located in \nhttps://httpbin.org\n \n\n\n$ kubectl create -f ingress.yaml\ningress \n\"external-auth\"\n created\n\n$ kubectl get ing external-auth\nNAME HOSTS ADDRESS PORTS AGE\nexternal-auth external-auth-01.sample.com \n172\n.17.4.99 \n80\n 13s\n\n$ kubectl get ing external-auth -o yaml\napiVersion: extensions/v1beta1\nkind: Ingress\nmetadata:\n annotations:\n nginx.ingress.kubernetes.io/auth-url: https://httpbin.org/basic-auth/user/passwd\n creationTimestamp: \n2016\n-10-03T13:50:35Z\n generation: \n1\n\n name: external-auth\n namespace: default\n resourceVersion: \n\"2068378\"\n\n selfLink: /apis/extensions/v1beta1/namespaces/default/ingresses/external-auth\n uid: 5c388f1d-8970-11e6-9004-080027d2dc94\nspec:\n rules:\n - host: external-auth-01.sample.com\n http:\n paths:\n - backend:\n serviceName: http-svc\n servicePort: \n80\n\n path: /\nstatus:\n loadBalancer:\n ingress:\n - ip: \n172\n.17.4.99\n$\n\n\n\n\n\nTest 1: no username/password (expect code 401)\n\n\n$\n curl -k http://172.17.4.99 -v -H \n'Host: external-auth-01.sample.com'\n\n\n* Rebuilt URL to: http://172.17.4.99/\n\n\n* Trying 172.17.4.99...\n\n\n* Connected to 172.17.4.99 (172.17.4.99) port 80 (#0)\n\n\n>\n GET / HTTP/1.1\n\n>\n Host: external-auth-01.sample.com\n\n>\n User-Agent: curl/7.50.1\n\n>\n Accept: */*\n\n>\n\n\n< HTTP/1.1 401 Unauthorized\n\n\n< Server: nginx/1.11.3\n\n\n< Date: Mon, 03 Oct 2016 14:52:08 GMT\n\n\n< Content-Type: text/html\n\n\n< Content-Length: 195\n\n\n< Connection: keep-alive\n\n\n< WWW-Authenticate: Basic realm=\"Fake Realm\"\n\n\n<\n\n\n<html>\n\n\n<head><title>401 Authorization Required</title></head>\n\n\n<body bgcolor=\"white\">\n\n\n<center><h1>401 Authorization Required</h1></center>\n\n\n<hr><center>nginx/1.11.3</center>\n\n\n</body>\n\n\n</html>\n\n\n* Connection #0 to host 172.17.4.99 left intact\n\n\n\n\n\n\nTest 2: valid username/password (expect code 200)\n\n\n$ curl -k http://172.17.4.99 -v -H \n'Host: external-auth-01.sample.com'\n -u \n'user:passwd'\n\n* Rebuilt URL to: http://172.17.4.99/\n* Trying \n172\n.17.4.99...\n* Connected to \n172\n.17.4.99 \n(\n172\n.17.4.99\n)\n port \n80\n \n(\n#0)\n\n* Server auth using Basic with user \n'user'\n\n> GET / HTTP/1.1\n> Host: external-auth-01.sample.com\n> Authorization: Basic \ndXNlcjpwYXNzd2Q\n=\n\n> User-Agent: curl/7.50.1\n> Accept: */*\n>\n< HTTP/1.1 \n200\n OK\n< Server: nginx/1.11.3\n< Date: Mon, \n03\n Oct \n2016\n \n14\n:52:50 GMT\n< Content-Type: text/plain\n< Transfer-Encoding: chunked\n< Connection: keep-alive\n<\nCLIENT VALUES:\n\nclient_address\n=\n10\n.2.60.2\n\ncommand\n=\nGET\nreal \npath\n=\n/\n\nquery\n=\nnil\n\nrequest_version\n=\n1\n.1\n\nrequest_uri\n=\nhttp://external-auth-01.sample.com:8080/\n\nSERVER VALUES:\n\nserver_version\n=\nnginx: \n1\n.9.11 - lua: \n10001\n\n\nHEADERS RECEIVED:\n\naccept\n=\n*/*\n\nauthorization\n=\nBasic \ndXNlcjpwYXNzd2Q\n=\n\n\nconnection\n=\nclose\n\nhost\n=\nexternal-auth-01.sample.com\nuser-agent\n=\ncurl/7.50.1\nx-forwarded-for\n=\n10\n.2.60.1\nx-forwarded-host\n=\nexternal-auth-01.sample.com\nx-forwarded-port\n=\n80\n\nx-forwarded-proto\n=\nhttp\nx-real-ip\n=\n10\n.2.60.1\nBODY:\n* Connection \n#0 to host 172.17.4.99 left intact\n\n-no body in request-\n\n\n\n\n\nTest 3: invalid username/password (expect code 401)\n\n\ncurl -k http://172.17.4.99 -v -H 'Host: external-auth-01.sample.com' -u 'user:user'\n* Rebuilt URL to: http://172.17.4.99/\n* Trying 172.17.4.99...\n* Connected to 172.17.4.99 (172.17.4.99) port 80 (#0)\n* Server auth using Basic with user 'user'\n> GET / HTTP/1.1\n> Host: external-auth-01.sample.com\n> Authorization: Basic dXNlcjp1c2Vy\n> User-Agent: curl/7.50.1\n> Accept: */*\n>\n\n< HTTP\n/1.1\n \n401\n \nUnauthorized\n\n\n<\n \nServer:\n \nnginx/1.11.3\n\n\n<\n \nDate:\n \nMon,\n \n03\n \nOct\n \n2016\n \n14:53:04\n \nGMT\n\n\n<\n \nContent-Type:\n \ntext/html\n\n\n<\n \nContent-Length:\n \n195\n\n\n<\n \nConnection:\n \nkeep-alive\n\n\n*\n \nAuthentication\n \nproblem.\n \nIgnoring\n \nthis.\n\n\n<\n \nWWW-Authenticate:\n \nBasic\n \nrealm=\n\"Fake Realm\"\n\n\n<\n\n\n<html\n>\n\n\n<head><title>\n401 Authorization Required\n</title></head>\n\n\n<body\n \nbgcolor=\n\"white\"\n>\n\n\n<center><h1>\n401 Authorization Required\n</h1></center>\n\n\n<hr><center>\nnginx/1.11.3\n</center>\n\n\n</body>\n\n\n</html>\n\n* Connection #0 to host 172.17.4.99 left intact",
"title": "External authentication"
},
{
"location": "/examples/auth/external-auth/README/#external-authentication",
"text": "",
"title": "External authentication"
},
{
"location": "/examples/auth/external-auth/README/#example-1",
"text": "Use an external service (Basic Auth) located in https://httpbin.org $ kubectl create -f ingress.yaml\ningress \"external-auth\" created\n\n$ kubectl get ing external-auth\nNAME HOSTS ADDRESS PORTS AGE\nexternal-auth external-auth-01.sample.com 172 .17.4.99 80 13s\n\n$ kubectl get ing external-auth -o yaml\napiVersion: extensions/v1beta1\nkind: Ingress\nmetadata:\n annotations:\n nginx.ingress.kubernetes.io/auth-url: https://httpbin.org/basic-auth/user/passwd\n creationTimestamp: 2016 -10-03T13:50:35Z\n generation: 1 \n name: external-auth\n namespace: default\n resourceVersion: \"2068378\" \n selfLink: /apis/extensions/v1beta1/namespaces/default/ingresses/external-auth\n uid: 5c388f1d-8970-11e6-9004-080027d2dc94\nspec:\n rules:\n - host: external-auth-01.sample.com\n http:\n paths:\n - backend:\n serviceName: http-svc\n servicePort: 80 \n path: /\nstatus:\n loadBalancer:\n ingress:\n - ip: 172 .17.4.99\n$ Test 1: no username/password (expect code 401) $ curl -k http://172.17.4.99 -v -H 'Host: external-auth-01.sample.com' * Rebuilt URL to: http://172.17.4.99/ * Trying 172.17.4.99... * Connected to 172.17.4.99 (172.17.4.99) port 80 (#0) > GET / HTTP/1.1 > Host: external-auth-01.sample.com > User-Agent: curl/7.50.1 > Accept: */* > < HTTP/1.1 401 Unauthorized < Server: nginx/1.11.3 < Date: Mon, 03 Oct 2016 14:52:08 GMT < Content-Type: text/html < Content-Length: 195 < Connection: keep-alive < WWW-Authenticate: Basic realm=\"Fake Realm\" < <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' \n* Rebuilt URL to: http://172.17.4.99/\n* Trying 172 .17.4.99...\n* Connected to 172 .17.4.99 ( 172 .17.4.99 ) port 80 ( #0) \n* Server auth using Basic with user 'user' \n> GET / HTTP/1.1\n> Host: external-auth-01.sample.com\n> Authorization: Basic dXNlcjpwYXNzd2Q = \n> User-Agent: curl/7.50.1\n> Accept: */*\n>\n< HTTP/1.1 200 OK\n< Server: nginx/1.11.3\n< Date: Mon, 03 Oct 2016 14 :52:50 GMT\n< Content-Type: text/plain\n< Transfer-Encoding: chunked\n< Connection: keep-alive\n<\nCLIENT VALUES: client_address = 10 .2.60.2 command = GET\nreal path = / query = nil request_version = 1 .1 request_uri = http://external-auth-01.sample.com:8080/\n\nSERVER VALUES: server_version = nginx: 1 .9.11 - lua: 10001 \n\nHEADERS RECEIVED: accept = */* authorization = Basic dXNlcjpwYXNzd2Q = connection = close host = external-auth-01.sample.com\nuser-agent = curl/7.50.1\nx-forwarded-for = 10 .2.60.1\nx-forwarded-host = external-auth-01.sample.com\nx-forwarded-port = 80 \nx-forwarded-proto = http\nx-real-ip = 10 .2.60.1\nBODY:\n* Connection #0 to host 172.17.4.99 left intact \n-no body in request- Test 3: invalid username/password (expect code 401) curl -k http://172.17.4.99 -v -H 'Host: external-auth-01.sample.com' -u 'user:user'\n* Rebuilt URL to: http://172.17.4.99/\n* Trying 172.17.4.99...\n* Connected to 172.17.4.99 (172.17.4.99) port 80 (#0)\n* Server auth using Basic with user 'user'\n> GET / HTTP/1.1\n> Host: external-auth-01.sample.com\n> Authorization: Basic dXNlcjp1c2Vy\n> User-Agent: curl/7.50.1\n> Accept: */*\n> < HTTP /1.1 401 Unauthorized < Server: nginx/1.11.3 < Date: Mon, 03 Oct 2016 14:53:04 GMT < Content-Type: text/html < Content-Length: 195 < Connection: keep-alive * Authentication problem. Ignoring this. < WWW-Authenticate: Basic realm= \"Fake Realm\" < <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> \n* Connection #0 to host 172.17.4.99 left intact",
"title": "Example 1:"
},
{
"location": "/examples/customization/configuration-snippets/README/",
"text": "Configuration Snippets\n\u00b6\n\n\nIngress\n\u00b6\n\n\nThe Ingress in this example adds a custom header to Nginx configuration that only applies to that specific Ingress. If you want to add headers that apply globally to all Ingresses, please have a look at \nthis example\n.\n\n\n$\n kubectl apply -f ingress.yaml\n\n\n\n\n\nTest\n\u00b6\n\n\nCheck if the contents of the annotation are present in the nginx.conf file using:\n\nkubectl exec nginx-ingress-controller-873061567-4n3k2 -n kube-system cat /etc/nginx/nginx.conf",
"title": "Configuration Snippets"
},
{
"location": "/examples/customization/configuration-snippets/README/#configuration-snippets",
"text": "",
"title": "Configuration Snippets"
},
{
"location": "/examples/customization/configuration-snippets/README/#ingress",
"text": "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",
"title": "Ingress"
},
{
"location": "/examples/customization/configuration-snippets/README/#test",
"text": "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",
"title": "Test"
},
{
"location": "/examples/customization/custom-configuration/README/",
"text": "Custom Configuration\n\u00b6\n\n\nUsing a \nConfigMap\n is possible to customize the NGINX configuration\n\n\nFor example, if we want to change the timeouts we need to create a ConfigMap:\n\n\n$ cat configmap.yaml\napiVersion: v1\ndata:\n proxy-connect-timeout: \n\"10\"\n\n proxy-read-timeout: \n\"120\"\n\n proxy-send-timeout: \n\"120\"\n\nkind: ConfigMap\nmetadata:\n name: nginx-load-balancer-conf\n\n\n\n\n\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/customization/custom-configuration/configmap.yaml \\\n | kubectl apply -f -\n\n\n\n\n\nIf the Configmap it is updated, NGINX will be reloaded with the new configuration.",
"title": "Custom Configuration"
},
{
"location": "/examples/customization/custom-configuration/README/#custom-configuration",
"text": "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\napiVersion: v1\ndata:\n proxy-connect-timeout: \"10\" \n proxy-read-timeout: \"120\" \n proxy-send-timeout: \"120\" \nkind: ConfigMap\nmetadata:\n name: nginx-load-balancer-conf curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/customization/custom-configuration/configmap.yaml \\\n | kubectl apply -f - If the Configmap it is updated, NGINX will be reloaded with the new configuration.",
"title": "Custom Configuration"
},
{
"location": "/examples/customization/custom-errors/README/",
"text": "Custom Errors\n\u00b6\n\n\nThis example shows how is possible to use a custom backend to render custom error pages. The code of this example is located here \ncustom-error-pages\n\n\nThe idea is to use the headers \nX-Code\n and \nX-Format\n that NGINX pass to the backend in case of an error to find out the best existent representation of the response to be returned. i.e. if the request contains an \nAccept\n header of type \njson\n the error should be in that format and not in \nhtml\n (the default in NGINX).\n\n\nFirst create the custom backend to use in the Ingress controller\n\n\n$ kubectl create -f custom-default-backend.yaml\nservice \n\"nginx-errors\"\n created\nreplicationcontroller \n\"nginx-errors\"\n created\n\n\n\n\n\n$ kubectl get svc\nNAME CLUSTER-IP EXTERNAL-IP PORT\n(\nS\n)\n AGE\nechoheaders \n10\n.3.0.7 nodes \n80\n/TCP 23d\nkubernetes \n10\n.3.0.1 <none> \n443\n/TCP 34d\nnginx-errors \n10\n.3.0.102 <none> \n80\n/TCP 11s\n\n\n\n\n\n$ kubectl get rc\nCONTROLLER REPLICAS AGE\nechoheaders \n1\n 19d\nnginx-errors \n1\n 19s\n\n\n\n\n\nNext create the Ingress controller executing\n\n\n$ kubectl create -f rc-custom-errors.yaml\n\n\n\n\n\nNow to check if this is working we use curl:\n\n\n$ curl -v http://172.17.4.99/\n* Trying 172.17.4.99...\n* Connected to 172.17.4.99 (172.17.4.99) port 80 (#0)\n> GET / HTTP/1.1\n> Host: 172.17.4.99\n> User-Agent: curl/7.43.0\n> Accept: */*\n>\n\n< HTTP\n/1.1\n \n404\n \nNot\n \nFound\n\n\n<\n \nServer:\n \nnginx/1.10.0\n\n\n<\n \nDate:\n \nWed,\n \n04\n \nMay\n \n2016\n \n02:53:45\n \nGMT\n\n\n<\n \nContent-Type:\n \ntext/html\n\n\n<\n \nTransfer-Encoding:\n \nchunked\n\n\n<\n \nConnection:\n \nkeep-alive\n\n\n<\n \nVary:\n \nAccept-Encoding\n\n\n<\n\n\n<span\n>\nThe page you're looking for could not be found.\n</span>\n\n\n* Connection #0 to host 172.17.4.99 left intact\n\n\n\n\n\nSpecifying json as expected format:\n\n\n$ curl -v http://172.17.4.99/ -H \n'Accept: application/json'\n\n* Trying \n172\n.17.4.99...\n* Connected to \n172\n.17.4.99 \n(\n172\n.17.4.99\n)\n port \n80\n \n(\n#0)\n\n> GET / HTTP/1.1\n> Host: \n172\n.17.4.99\n> User-Agent: curl/7.43.0\n> Accept: application/json\n>\n< HTTP/1.1 \n404\n Not Found\n< Server: nginx/1.10.0\n< Date: Wed, \n04\n May \n2016\n \n02\n:54:00 GMT\n< Content-Type: text/html\n< Transfer-Encoding: chunked\n< Connection: keep-alive\n< Vary: Accept-Encoding\n<\n\n{\n \n\"message\"\n: \n\"The page you're looking for could not be found\"\n \n}\n\n\n* Connection \n#0 to host 172.17.4.99 left intact",
"title": "Custom Errors"
},
{
"location": "/examples/customization/custom-errors/README/#custom-errors",
"text": "This example shows how is possible to use a custom backend to render custom error pages. The code of this example is located here custom-error-pages The idea is to use the headers X-Code and X-Format that NGINX pass to the backend in case of an error to find out the best existent representation of the response to be returned. i.e. if the request contains an Accept header of type json the error should be in that format and not in html (the default in NGINX). First create the custom backend to use in the Ingress controller $ kubectl create -f custom-default-backend.yaml\nservice \"nginx-errors\" created\nreplicationcontroller \"nginx-errors\" created $ kubectl get svc\nNAME CLUSTER-IP EXTERNAL-IP PORT ( S ) AGE\nechoheaders 10 .3.0.7 nodes 80 /TCP 23d\nkubernetes 10 .3.0.1 <none> 443 /TCP 34d\nnginx-errors 10 .3.0.102 <none> 80 /TCP 11s $ kubectl get rc\nCONTROLLER REPLICAS AGE\nechoheaders 1 19d\nnginx-errors 1 19s Next create the Ingress controller executing $ kubectl create -f rc-custom-errors.yaml Now to check if this is working we use curl: $ curl -v http://172.17.4.99/\n* Trying 172.17.4.99...\n* Connected to 172.17.4.99 (172.17.4.99) port 80 (#0)\n> GET / HTTP/1.1\n> Host: 172.17.4.99\n> User-Agent: curl/7.43.0\n> Accept: */*\n> < HTTP /1.1 404 Not Found < Server: nginx/1.10.0 < Date: Wed, 04 May 2016 02:53:45 GMT < Content-Type: text/html < Transfer-Encoding: chunked < Connection: keep-alive < Vary: Accept-Encoding < <span > The page you're looking for could not be found. </span> \n\n* Connection #0 to host 172.17.4.99 left intact Specifying json as expected format: $ curl -v http://172.17.4.99/ -H 'Accept: application/json' \n* Trying 172 .17.4.99...\n* Connected to 172 .17.4.99 ( 172 .17.4.99 ) port 80 ( #0) \n> GET / HTTP/1.1\n> Host: 172 .17.4.99\n> User-Agent: curl/7.43.0\n> Accept: application/json\n>\n< HTTP/1.1 404 Not Found\n< Server: nginx/1.10.0\n< Date: Wed, 04 May 2016 02 :54:00 GMT\n< Content-Type: text/html\n< Transfer-Encoding: chunked\n< Connection: keep-alive\n< Vary: Accept-Encoding\n< { \"message\" : \"The page you're looking for could not be found\" } \n\n* Connection #0 to host 172.17.4.99 left intact",
"title": "Custom Errors"
},
{
"location": "/examples/customization/custom-headers/README/",
"text": "Custom Headers\n\u00b6\n\n\nThis example aims to demonstrate the deployment of an nginx ingress controller and\nuse a ConfigMap to configure a custom list of headers to be passed to the upstream\nserver\n\n\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/customization/custom-headers/configmap.yaml \\\n\n\n | kubectl apply -f -\n\n\n\ncurl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/customization/custom-headers/custom-headers.yaml \\\n\n\n | kubectl apply -f -\n\n\n\n\n\n\nTest\n\u00b6\n\n\nCheck the contents of the configmap is present in the nginx.conf file using:\n\nkubectl exec nginx-ingress-controller-873061567-4n3k2 -n kube-system cat /etc/nginx/nginx.conf",
"title": "Custom Headers"
},
{
"location": "/examples/customization/custom-headers/README/#custom-headers",
"text": "This example aims to demonstrate the deployment of an nginx ingress controller and\nuse a ConfigMap to configure a custom list of headers to be passed to the upstream\nserver 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 -",
"title": "Custom Headers"
},
{
"location": "/examples/customization/custom-headers/README/#test",
"text": "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",
"title": "Test"
},
{
"location": "/examples/customization/custom-upstream-check/README/",
"text": "Custom Upstream server checks\n\u00b6\n\n\nThis example shows how is possible to create a custom configuration for a particular upstream associated with an Ingress rule.\n\n\necho \"\napiVersion: extensions/v1beta1\nkind: Ingress\nmetadata:\n name: http-svc\n annotations:\n nginx.ingress.kubernetes.io/upstream-fail-timeout: \"30\"\nspec:\n rules:\n - host: foo.bar.com\n http:\n paths:\n - path: /\n backend:\n serviceName: http-svc\n servicePort: 80\n\" | kubectl create -f -\n\n\n\n\n\nCheck the annotation is present in the Ingress rule:\n\n\nkubectl get ingress http-svc -o yaml\n\n\n\n\n\nCheck the NGINX configuration is updated using kubectl or the status page:\n\n\n$ kubectl \nexec\n nginx-ingress-controller-v1ppm cat /etc/nginx/nginx.conf\n\n\n\n\n\n....\n\n \nupstream\n \ndefault-http-svc-x-80\n \n{\n\n \nleast_conn\n;\n\n \nserver\n \n10.2.92.2:8080\n \nmax_fails=5\n \nfail_timeout=30\n;\n\n\n \n}\n\n\n....",
"title": "Custom Upstream server checks"
},
{
"location": "/examples/customization/custom-upstream-check/README/#custom-upstream-server-checks",
"text": "This example shows how is possible to create a custom configuration for a particular upstream associated with an Ingress rule. echo \"\napiVersion: extensions/v1beta1\nkind: Ingress\nmetadata:\n name: http-svc\n annotations:\n nginx.ingress.kubernetes.io/upstream-fail-timeout: \"30\"\nspec:\n rules:\n - host: foo.bar.com\n http:\n paths:\n - path: /\n backend:\n serviceName: http-svc\n servicePort: 80\n\" | 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 .... \n upstream default-http-svc-x-80 { \n least_conn ; \n server 10.2.92.2:8080 max_fails=5 fail_timeout=30 ; \n\n } ....",
"title": "Custom Upstream server checks"
},
{
"location": "/examples/customization/custom-vts-metrics-prometheus/README/",
"text": "Deploying the Nginx Ingress controller\n\u00b6\n\n\nThis example aims to demonstrate the deployment of an nginx ingress controller and use a ConfigMap to enable \nnginx vts module\n to export metrics in prometheus format. \n\n\nvts-metrics\n\u00b6\n\n\nVts-metrics export NGINX metrics. To deploy all the files simply run \nkubectl apply -f nginx\n. A deployment and service will be\ncreated which already has a \nprometheus.io/scrape: 'true'\n annotation and if you added\nthe recommended Prometheus service-endpoint scraping \nconfiguration\n,\nPrometheus will scrape it automatically and you start using the generated metrics right away.\n\n\nCustom configuration\n\u00b6\n\n\napiVersion: v1\n\n\ndata:\n\n\n enable-vts-status: \"true\"\n\n\nkind: ConfigMap\n\n\nmetadata:\n\n\n name: nginx-configuration\n\n\n namespace: ingress-nginx\n\n\n labels:\n\n\n app: ingress-nginx\n\n\n\n\n\n\n$\n kubectl apply -f nginx-vts-metrics-conf.yaml\n\n\n\n\n\nResult\n\u00b6\n\n\nCheck whether the ingress controller successfully generated the NGINX vts status:\n\n\n$\n kubectl \nexec\n nginx-ingress-controller-873061567-4n3k2 -n ingress-nginx cat /etc/nginx/nginx.conf\n|\ngrep vhost_traffic_status_display\n\n vhost_traffic_status_display;\n\n\n vhost_traffic_status_display_format html;\n\n\n\n\n\n\nNGINX vts dashboard\n\u00b6\n\n\nThe vts dashboard provides real time metrics. \n\n\n\n\nBecause the vts port it's not yet exposed, you should forward the controller port to see it.\n\n\n$\n kubectl port-forward \n$(\nkubectl get pods --selector\n=\nk8s-app\n=\nnginx-ingress-controller -n ingress-nginx --output\n=\njsonpath\n={\n.items..metadata.name\n}\n)\n -n ingress-nginx \n18080\n\n\n\n\n\n\nNow open the url \nhttp://localhost:18080/nginx_status\n in your browser.\n\n\nPrometheus metrics output\n\u00b6\n\n\nNGINX Ingress controller already has a parser to convert vts metrics to Prometheus format. It exports prometheus metrics to the address \n:10254/metrics\n.\n\n\n$\n kubectl \nexec\n -ti -n ingress-nginx \n$(\nkubectl get pods --selector\n=\nk8s-app\n=\nnginx-ingress-controller -n kube-system --output\n=\njsonpath\n={\n.items..metadata.name\n}\n)\n curl localhost:10254/metrics\n\ningress_controller_ssl_expire_time_seconds{host=\"foo.bar.com\"} -6.21355968e+10\n\n\n#\n HELP ingress_controller_success Cumulative number of Ingress controller reload operations\n\n#\n TYPE ingress_controller_success counter\n\ningress_controller_success{count=\"reloads\"} 3\n\n\n#\n HELP nginx_bytes_total Nginx bytes count\n\n#\n TYPE nginx_bytes_total counter\n\nnginx_bytes_total{direction=\"in\",ingress_class=\"nginx\",namespace=\"\",server_zone=\"*\"} 3708\n\n\nnginx_bytes_total{direction=\"in\",ingress_class=\"nginx\",namespace=\"\",server_zone=\"_\"} 3708\n\n\nnginx_bytes_total{direction=\"out\",ingress_class=\"nginx\",namespace=\"\",server_zone=\"*\"} 5256\n\n\nnginx_bytes_total{direction=\"out\",ingress_class=\"nginx\",namespace=\"\",server_zone=\"_\"} 5256\n\n\n\n\n\n\nCustomize metrics\n\u00b6\n\n\nThe default \nvts vhost key\n is \n$geoip_country_code country::*\n that expose metrics grouped by server and country code. The example below show how to have metrics grouped by server and server path.\n\n\n\n\nNGINX custom configuration ( http level )\n\u00b6\n\n\n apiVersion: v1\n kind: ConfigMap\n data:\n enable-vts-status: \"true\"\n vts-default-filter-key: \"$server_name\"\n...\n\n\n\n\n\nCustomize ingress\n\u00b6\n\n\n apiVersion: extensions/v1beta1\n kind: Ingress\n metadata:\n annotations:\n nginx.ingress.kubernetes.io/vts-filter-key: $uri $server_name\n name: ingress\n\n\n\n\n\nResult\n\u00b6",
"title": "Deploying the Nginx Ingress controller"
},
{
"location": "/examples/customization/custom-vts-metrics-prometheus/README/#deploying-the-nginx-ingress-controller",
"text": "This example aims to demonstrate the deployment of an nginx ingress controller and use a ConfigMap to enable nginx vts module to export metrics in prometheus format.",
"title": "Deploying the Nginx Ingress controller"
},
{
"location": "/examples/customization/custom-vts-metrics-prometheus/README/#vts-metrics",
"text": "Vts-metrics export NGINX metrics. To deploy all the files simply run kubectl apply -f nginx . A deployment and service will be\ncreated which already has a prometheus.io/scrape: 'true' annotation and if you added\nthe recommended Prometheus service-endpoint scraping configuration ,\nPrometheus will scrape it automatically and you start using the generated metrics right away.",
"title": "vts-metrics"
},
{
"location": "/examples/customization/custom-vts-metrics-prometheus/README/#custom-configuration",
"text": "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",
"title": "Custom configuration"
},
{
"location": "/examples/customization/custom-vts-metrics-prometheus/README/#result",
"text": "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;",
"title": "Result"
},
{
"location": "/examples/customization/custom-vts-metrics-prometheus/README/#nginx-vts-dashboard",
"text": "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.",
"title": "NGINX vts dashboard"
},
{
"location": "/examples/customization/custom-vts-metrics-prometheus/README/#prometheus-metrics-output",
"text": "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",
"title": "Prometheus metrics output"
},
{
"location": "/examples/customization/custom-vts-metrics-prometheus/README/#customize-metrics",
"text": "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.",
"title": "Customize metrics"
},
{
"location": "/examples/customization/custom-vts-metrics-prometheus/README/#nginx-custom-configuration-http-level",
"text": "apiVersion: v1\n kind: ConfigMap\n data:\n enable-vts-status: \"true\"\n vts-default-filter-key: \"$server_name\"\n...",
"title": "NGINX custom configuration ( http level )"
},
{
"location": "/examples/customization/custom-vts-metrics-prometheus/README/#customize-ingress",
"text": "apiVersion: extensions/v1beta1\n kind: Ingress\n metadata:\n annotations:\n nginx.ingress.kubernetes.io/vts-filter-key: $uri $server_name\n name: ingress",
"title": "Customize ingress"
},
{
"location": "/examples/customization/custom-vts-metrics-prometheus/README/#result_1",
"text": "",
"title": "Result"
},
{
"location": "/examples/customization/external-auth-headers/README/",
"text": "External authentication, authentication service response headers propagation\n\u00b6\n\n\nThis example demonstrates propagation of selected authentication service response headers\nto backend service.\n\n\nSample configuration includes:\n\n\n\n\nSample authentication service producing several response headers\n\n\nAuthentication logic is based on HTTP header: requests with header \nUser\n containing string \ninternal\n are considered authenticated\n\n\nAfter successful authentication service generates response headers \nUserID\n and \nUserRole\n\n\nSample echo service displaying header information\n\n\nTwo ingress objects pointing to echo service\n\n\nPublic, which allows access from unauthenticated users\n\n\nPrivate, which allows access from authenticated users only\n\n\n\n\nYou can deploy the controller as\nfollows:\n\n\n$\n kubectl create -f deploy/\n\ndeployment \"demo-auth-service\" created\n\n\nservice \"demo-auth-service\" created\n\n\ningress \"demo-auth-service\" created\n\n\ndeployment \"demo-echo-service\" created\n\n\nservice \"demo-echo-service\" created\n\n\ningress \"public-demo-echo-service\" created\n\n\ningress \"secure-demo-echo-service\" created\n\n\n\n$\n kubectl get po\n\nNAME READY STATUS RESTARTS AGE\n\n\nNAME READY STATUS RESTARTS AGE\n\n\ndemo-auth-service-2769076528-7g9mh 1/1 Running 0 30s\n\n\ndemo-echo-service-3636052215-3vw8c 1/1 Running 0 29s\n\n\n\nkubectl get ing\n\n\nNAME HOSTS ADDRESS PORTS AGE\n\n\npublic-demo-echo-service public-demo-echo-service.kube.local 80 1m\n\n\nsecure-demo-echo-service secure-demo-echo-service.kube.local 80 1m\n\n\n\n\n\n\nTest 1: public service with no auth header\n\n\n$\n curl -H \n'Host: public-demo-echo-service.kube.local'\n -v \n192\n.168.99.100\n\n* Rebuilt URL to: 192.168.99.100/\n\n\n* Trying 192.168.99.100...\n\n\n* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0)\n\n\n>\n GET / HTTP/1.1\n\n>\n Host: public-demo-echo-service.kube.local\n\n>\n User-Agent: curl/7.43.0\n\n>\n Accept: */*\n\n>\n\n\n< HTTP/1.1 200 OK\n\n\n< Server: nginx/1.11.10\n\n\n< Date: Mon, 13 Mar 2017 20:19:21 GMT\n\n\n< Content-Type: text/plain; charset=utf-8\n\n\n< Content-Length: 20\n\n\n< Connection: keep-alive\n\n\n<\n\n\n* Connection #0 to host 192.168.99.100 left intact\n\n\nUserID: , UserRole:\n\n\n\n\n\n\nTest 2: secure service with no auth header\n\n\n$\n curl -H \n'Host: secure-demo-echo-service.kube.local'\n -v \n192\n.168.99.100\n\n* Rebuilt URL to: 192.168.99.100/\n\n\n* Trying 192.168.99.100...\n\n\n* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0)\n\n\n>\n GET / HTTP/1.1\n\n>\n Host: secure-demo-echo-service.kube.local\n\n>\n User-Agent: curl/7.43.0\n\n>\n Accept: */*\n\n>\n\n\n< HTTP/1.1 403 Forbidden\n\n\n< Server: nginx/1.11.10\n\n\n< Date: Mon, 13 Mar 2017 20:18:48 GMT\n\n\n< Content-Type: text/html\n\n\n< Content-Length: 170\n\n\n< Connection: keep-alive\n\n\n<\n\n\n<html>\n\n\n<head><title>403 Forbidden</title></head>\n\n\n<body bgcolor=\"white\">\n\n\n<center><h1>403 Forbidden</h1></center>\n\n\n<hr><center>nginx/1.11.10</center>\n\n\n</body>\n\n\n</html>\n\n\n* Connection #0 to host 192.168.99.100 left intact\n\n\n\n\n\n\nTest 3: public service with valid auth header\n\n\n$\n curl -H \n'Host: public-demo-echo-service.kube.local'\n -H \n'User:internal'\n -v \n192\n.168.99.100\n\n* Rebuilt URL to: 192.168.99.100/\n\n\n* Trying 192.168.99.100...\n\n\n* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0)\n\n\n>\n GET / HTTP/1.1\n\n>\n Host: public-demo-echo-service.kube.local\n\n>\n User-Agent: curl/7.43.0\n\n>\n Accept: */*\n\n>\n User:internal\n\n>\n\n\n< HTTP/1.1 200 OK\n\n\n< Server: nginx/1.11.10\n\n\n< Date: Mon, 13 Mar 2017 20:19:59 GMT\n\n\n< Content-Type: text/plain; charset=utf-8\n\n\n< Content-Length: 44\n\n\n< Connection: keep-alive\n\n\n<\n\n\n* Connection #0 to host 192.168.99.100 left intact\n\n\nUserID: 1443635317331776148, UserRole: admin\n\n\n\n\n\n\nTest 4: public service with valid auth header\n\n\n$\n curl -H \n'Host: secure-demo-echo-service.kube.local'\n -H \n'User:internal'\n -v \n192\n.168.99.100\n\n* Rebuilt URL to: 192.168.99.100/\n\n\n* Trying 192.168.99.100...\n\n\n* Connected to 192.168.99.100 (192.168.99.100) port 80 (#0)\n\n\n>\n GET / HTTP/1.1\n\n>\n Host: secure-demo-echo-service.kube.local\n\n>\n User-Agent: curl/7.43.0\n\n>\n Accept: */*\n\n>\n User:internal\n\n>\n\n\n< HTTP/1.1 200 OK\n\n\n< Server: nginx/1.11.10\n\n\n< Date: Mon, 13 Mar 2017 20:17:23 GMT\n\n\n< Content-Type: text/plain; charset=utf-8\n\n\n< Content-Length: 43\n\n\n< Connection: keep-alive\n\n\n<\n\n\n* Connection #0 to host 192.168.99.100 left intact\n\n\nUserID: 605394647632969758, UserRole: admin",
"title": "External authentication, authentication service response headers propagation"
},
{
"location": "/examples/customization/external-auth-headers/README/#external-authentication-authentication-service-response-headers-propagation",
"text": "This example demonstrates propagation of selected authentication service response headers\nto backend service. Sample configuration includes: Sample authentication service producing several response headers Authentication logic is based on HTTP header: requests with header User containing string internal are considered authenticated After successful authentication service generates response headers UserID and UserRole Sample echo service displaying header information Two ingress objects pointing to echo service Public, which allows access from unauthenticated users Private, which allows access from authenticated users only You can deploy the controller as\nfollows: $ 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",
"title": "External authentication, authentication service response headers propagation"
},
{
"location": "/examples/customization/ssl-dh-param/README/",
"text": "Deploying the Nginx Ingress controller\n\u00b6\n\n\nThis example aims to demonstrate the deployment of an nginx ingress controller and\nuse a ConfigMap to configure custom Diffie-Hellman parameters file to help with\n\"Perfect Forward Secrecy\".\n\n\nCustom configuration\n\u00b6\n\n\n$\n cat configmap.yaml\n\napiVersion: v1\n\n\ndata:\n\n\n ssl-dh-param: \"ingress-nginx/lb-dhparam\"\n\n\nkind: ConfigMap\n\n\nmetadata:\n\n\n name: nginx-configuration\n\n\n namespace: ingress-nginx\n\n\n labels:\n\n\n app: ingress-nginx\n\n\n\n\n\n\n$\n kubectl create -f configmap.yaml\n\n\n\n\n\nCustom DH parameters secret\n\u00b6\n\n\n$\n> openssl dhparam \n1024\n \n2\n> /dev/null \n|\n base64\n\nLS0tLS1CRUdJTiBESCBQQVJBTUVURVJ...\n\n\n\n\n\n\n$\n cat ssl-dh-param.yaml\n\napiVersion: v1\n\n\ndata:\n\n\n dhparam.pem: \"LS0tLS1CRUdJTiBESCBQQVJBTUVURVJ...\"\n\n\nkind: ConfigMap\n\n\nmetadata:\n\n\n name: nginx-configuration\n\n\n namespace: ingress-nginx\n\n\n labels:\n\n\n app: ingress-nginx\n\n\n\n\n\n\n$\n kubectl create -f ssl-dh-param.yaml\n\n\n\n\n\nTest\n\u00b6\n\n\nCheck the contents of the configmap is present in the nginx.conf file using:\n\nkubectl exec nginx-ingress-controller-873061567-4n3k2 -n kube-system cat /etc/nginx/nginx.conf",
"title": "Deploying the Nginx Ingress controller"
},
{
"location": "/examples/customization/ssl-dh-param/README/#deploying-the-nginx-ingress-controller",
"text": "This example aims to demonstrate the deployment of an nginx ingress controller and\nuse a ConfigMap to configure custom Diffie-Hellman parameters file to help with\n\"Perfect Forward Secrecy\".",
"title": "Deploying the Nginx Ingress controller"
},
{
"location": "/examples/customization/ssl-dh-param/README/#custom-configuration",
"text": "$ 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",
"title": "Custom configuration"
},
{
"location": "/examples/customization/ssl-dh-param/README/#custom-dh-parameters-secret",
"text": "$ > 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",
"title": "Custom DH parameters secret"
},
{
"location": "/examples/customization/ssl-dh-param/README/#test",
"text": "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",
"title": "Test"
},
{
"location": "/examples/customization/sysctl/README/",
"text": "Sysctl tuning\n\u00b6\n\n\nThis example aims to demonstrate the use of an Init Container to adjust sysctl default values\nusing \nkubectl patch\n\n\nkubectl patch deployment -n ingress-nginx nginx-ingress-controller --patch=\"$(cat patch.json)\"",
"title": "Sysctl tuning"
},
{
"location": "/examples/customization/sysctl/README/#sysctl-tuning",
"text": "This example aims to demonstrate the use of an Init Container to adjust sysctl default values\nusing kubectl patch kubectl patch deployment -n ingress-nginx nginx-ingress-controller --patch=\"$(cat patch.json)\"",
"title": "Sysctl tuning"
},
{
"location": "/examples/docker-registry/README/",
"text": "Docker registry\n\u00b6\n\n\nThis example demonstrates how to deploy a \ndocker registry\n in the cluster and configure Ingress enable access from Internet\n\n\nDeployment\n\u00b6\n\n\nFirst we deploy the docker registry in the cluster:\n\n\nkubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/docker-registry/deployment.yaml\n\n\n\n\n\n\n\n\nImportant\n\n\nDO NOT RUN THIS IN PRODUCTION\n\n\nThis deployment uses \nemptyDir\n in the \nvolumeMount\n which means the contents of the registry will be deleted when the pod dies.\n\n\n\n\nThe next required step is creation of the ingress rules. To do this we have two options: with and without TLS\n\n\nWithout TLS\n\u00b6\n\n\nDownload and edit the yaml deployment replacing \nregistry.<your domain>\n with a valid DNS name pointing to the ingress controller:\n\n\nwget https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/docker-registry/ingress-without-tls.yaml\n\n\n\n\n\n\n\n\nImportant\n\n\nRunning a docker registry without TLS requires we configure our local docker daemon with the insecure registry flag.\n\n\nPlease check \ndeploy a plain http registry\n\n\n\n\nWith TLS\n\u00b6\n\n\nDownload and edit the yaml deployment replacing \nregistry.<your domain>\n with a valid DNS name pointing to the ingress controller:\n\n\nwget https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/docs/examples/docker-registry/ingress-with-tls.yaml\n\n\n\n\n\n\nDeploy \nkube lego\n use \nLet's Encrypt\n certificates or edit the ingress rule to use a secret with an existing SSL certificate.\n\n\nTesting\n\u00b6\n\n\nTo test the registry is working correctly we download a known image from \ndocker hub\n, create a tag pointing to the new registry and upload the image:\n\n\ndocker pull ubuntu:16.04\n\n\ndocker tag ubuntu:16.04 `registry.<your domain>/ubuntu:16.04`\n\n\ndocker push `registry.<your domain>/ubuntu:16.04`\n\n\n\n\n\n\nPlease replace \nregistry.<your domain>\n with your domain.",
"title": "Docker registry"
},
{
"location": "/examples/docker-registry/README/#docker-registry",
"text": "This example demonstrates how to deploy a docker registry in the cluster and configure Ingress enable access from Internet",
"title": "Docker registry"
},
{
"location": "/examples/docker-registry/README/#deployment",
"text": "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",
"title": "Deployment"
},
{
"location": "/examples/docker-registry/README/#without-tls",
"text": "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",
"title": "Without TLS"
},
{
"location": "/examples/docker-registry/README/#with-tls",
"text": "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.",
"title": "With TLS"
},
{
"location": "/examples/docker-registry/README/#testing",
"text": "To test the registry is working correctly we download a known image from docker hub , create a tag pointing to the new registry and upload the image: docker pull ubuntu:16.04 docker tag ubuntu:16.04 `registry.<your domain>/ubuntu:16.04` docker push `registry.<your domain>/ubuntu:16.04` Please replace registry.<your domain> with your domain.",
"title": "Testing"
},
{
"location": "/examples/external-auth/README/",
"text": "External Authentication\n\u00b6\n\n\nOverview\n\u00b6\n\n\nThe \nauth-url\n and \nauth-signin\n annotations allow you to use an external\nauthentication provider to protect your Ingress resources.\n\n\n\n\nImportant\n\n\nthis annotation requires \nnginx-ingress-controller v0.9.0\n or greater.)\n\n\n\n\nKey Detail\n\u00b6\n\n\nThis functionality is enabled by deploying multiple Ingress objects for a single host.\nOne Ingress object has no special annotations and handles authentication.\n\n\nOther Ingress objects can then be annotated in such a way that require the user to\nauthenticate against the first Ingress's endpoint, and can redirect \n401\ns to the\nsame endpoint.\n\n\nSample:\n\n\n...\n\n\nmetadata\n:\n\n \nname\n:\n \napplication\n\n \nannotations\n:\n\n \n\"nginx.ingress.kubernetes.io/auth-url\"\n:\n \n\"https://$host/oauth2/auth\"\n\n \n\"nginx.ingress.kubernetes.io/auth-signin\"\n:\n \n\"https://$host/oauth2/sign_in\"\n\n\n...\n\n\n\n\n\n\nExample: OAuth2 Proxy + Kubernetes-Dashboard\n\u00b6\n\n\nThis example will show you how to deploy \noauth2_proxy\n\ninto a Kubernetes cluster and use it to protect the Kubernetes Dashboard using github as oAuth2 provider\n\n\nPrepare\n\u00b6\n\n\n\n\nInstall the kubernetes dashboard\n\n\n\n\nkubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.5.0.yaml\n\n\n\n\n\n\n\n\nCreate a \ncustom Github OAuth application\n\n\n\n\n\n\n\n\nHomepage URL is the FQDN in the Ingress rule, like \nhttps://foo.bar.com\n\n\nAuthorization callback URL is the same as the base FQDN plus \n/oauth2\n, like \nhttps://foo.bar.com/oauth2\n\n\n\n\n\n\n\n\n\n\nConfigure oauth2_proxy values in the file oauth2-proxy.yaml with the values:\n\n\n\n\n\n\nOAUTH2_PROXY_CLIENT_ID with the github \n<Client ID>\n\n\n\n\nOAUTH2_PROXY_CLIENT_SECRET with the github \n<Client Secret>\n\n\n\n\nOAUTH2_PROXY_COOKIE_SECRET with value of \npython\n \n-\nc\n \n'import os,base64; print base64.b64encode(os.urandom(16))'\n \n\n\n\n\n\n\nCustomize the contents of the file dashboard-ingress.yaml:\n\n\n\n\n\n\nReplace \n__INGRESS_HOST__\n with a valid FQDN and \n__INGRESS_SECRET__\n with a Secret with a valid SSL certificate.\n\n\n\n\nDeploy the oauth2 proxy and the ingress rules running:\n\n\n\n\n$\n kubectl create -f oauth2-proxy.yaml,dashboard-ingress.yaml\n\n\n\n\n\nTest the oauth integration accessing the configured URL, like \nhttps://foo.bar.com",
"title": "External Authentication"
},
{
"location": "/examples/external-auth/README/#external-authentication",
"text": "",
"title": "External Authentication"
},
{
"location": "/examples/external-auth/README/#overview",
"text": "The auth-url and auth-signin annotations allow you to use an external\nauthentication provider to protect your Ingress resources. Important this annotation requires nginx-ingress-controller v0.9.0 or greater.)",
"title": "Overview"
},
{
"location": "/examples/external-auth/README/#key-detail",
"text": "This functionality is enabled by deploying multiple Ingress objects for a single host.\nOne Ingress object has no special annotations and handles authentication. Other Ingress objects can then be annotated in such a way that require the user to\nauthenticate against the first Ingress's endpoint, and can redirect 401 s to the\nsame endpoint. Sample: ... metadata : \n name : application \n annotations : \n \"nginx.ingress.kubernetes.io/auth-url\" : \"https://$host/oauth2/auth\" \n \"nginx.ingress.kubernetes.io/auth-signin\" : \"https://$host/oauth2/sign_in\" ...",
"title": "Key Detail"
},
{
"location": "/examples/external-auth/README/#example-oauth2-proxy-kubernetes-dashboard",
"text": "This example will show you how to deploy oauth2_proxy \ninto a Kubernetes cluster and use it to protect the Kubernetes Dashboard using github as oAuth2 provider",
"title": "Example: OAuth2 Proxy + Kubernetes-Dashboard"
},
{
"location": "/examples/external-auth/README/#prepare",
"text": "Install the kubernetes dashboard kubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.5.0.yaml Create a custom Github OAuth application Homepage URL is the FQDN in the Ingress rule, like https://foo.bar.com Authorization callback URL is the same as the base FQDN plus /oauth2 , like https://foo.bar.com/oauth2 Configure oauth2_proxy values in the file oauth2-proxy.yaml with the values: OAUTH2_PROXY_CLIENT_ID with the github <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",
"title": "Prepare"
},
{
"location": "/examples/multi-tls/README/",
"text": "Multi TLS certificate termination\n\u00b6\n\n\nThis example uses 2 different certificates to terminate SSL for 2 hostnames.\n\n\n\n\nDeploy the controller by creating the rc in the parent dir\n\n\nCreate tls secrets for foo.bar.com and bar.baz.com as indicated in the yaml\n\n\nCreate multi-tls.yaml\n\n\n\n\nThis should generate a segment like:\n\n\n$\n kubectl \nexec\n -it nginx-ingress-controller-6vwd1 -- cat /etc/nginx/nginx.conf \n|\n grep \n\"foo.bar.com\"\n -B \n7\n -A \n35\n\n\n server {\n\n\n listen 80;\n\n\n listen 443 ssl http2;\n\n\n ssl_certificate /etc/nginx-ssl/default-foobar.pem;\n\n\n ssl_certificate_key /etc/nginx-ssl/default-foobar.pem;\n\n\n\n\n server_name foo.bar.com;\n\n\n\n\n if ($scheme = http) {\n\n\n return 301 https://$host$request_uri;\n\n\n }\n\n\n\n\n\n location / {\n\n\n proxy_set_header Host $host;\n\n\n\n #\n Pass Real IP\n\n proxy_set_header X-Real-IP $remote_addr;\n\n\n\n #\n Allow websocket connections\n\n proxy_set_header Upgrade $http_upgrade;\n\n\n proxy_set_header Connection $connection_upgrade;\n\n\n\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n\n\n proxy_set_header X-Forwarded-Host $host;\n\n\n proxy_set_header X-Forwarded-Proto $pass_access_scheme;\n\n\n\n proxy_connect_timeout 5s;\n\n\n proxy_send_timeout 60s;\n\n\n proxy_read_timeout 60s;\n\n\n\n proxy_redirect off;\n\n\n proxy_buffering off;\n\n\n\n proxy_http_version 1.1;\n\n\n\n proxy_pass http://default-http-svc-80;\n\n\n }\n\n\n\n\n\n\nAnd you should be able to reach your nginx service or http-svc service using a hostname switch:\n\n\n$\n kubectl get ing\n\nNAME RULE BACKEND ADDRESS AGE\n\n\nfoo-tls - 104.154.30.67 13m\n\n\n foo.bar.com\n\n\n / http-svc:80\n\n\n bar.baz.com\n\n\n / nginx:80\n\n\n\n$\n curl https://104.154.30.67 -H \n'Host:foo.bar.com'\n -k\n\nCLIENT VALUES:\n\n\nclient_address=10.245.0.6\n\n\ncommand=GET\n\n\nreal path=/\n\n\nquery=nil\n\n\nrequest_version=1.1\n\n\nrequest_uri=http://foo.bar.com:8080/\n\n\n\nSERVER VALUES:\n\n\nserver_version=nginx: 1.9.11 - lua: 10001\n\n\n\nHEADERS RECEIVED:\n\n\naccept=*/*\n\n\nconnection=close\n\n\nhost=foo.bar.com\n\n\nuser-agent=curl/7.35.0\n\n\nx-forwarded-for=10.245.0.1\n\n\nx-forwarded-host=foo.bar.com\n\n\nx-forwarded-proto=https\n\n\n\n$\n curl https://104.154.30.67 -H \n'Host:bar.baz.com'\n -k\n\n<!DOCTYPE html>\n\n\n<html>\n\n\n<head>\n\n\n<title>Welcome to nginx on Debian!</title>\n\n\n\n$\n curl \n104\n.154.30.67\n\ndefault backend - 404",
"title": "Multi TLS certificate termination"
},
{
"location": "/examples/multi-tls/README/#multi-tls-certificate-termination",
"text": "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",
"title": "Multi TLS certificate termination"
},
{
"location": "/examples/rewrite/README/",
"text": "Rewrite\n\u00b6\n\n\nThis example demonstrates how to use the Rewrite annotations\n\n\nPrerequisites\n\u00b6\n\n\nYou will need to make sure your Ingress targets exactly one Ingress\ncontroller by specifying the \ningress.class annotation\n,\nand that you have an ingress controller \nrunning\n in your cluster.\n\n\nDeployment\n\u00b6\n\n\nRewriting can be controlled using the following annotations:\n\n\n\n\n\n\n\n\nName\n\n\nDescription\n\n\nValues\n\n\n\n\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/rewrite-target\n\n\nTarget URI where the traffic must be redirected\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/add-base-url\n\n\nindicates if is required to add a base tag in the head of the responses from the upstream servers\n\n\nbool\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/base-url-scheme\n\n\nOverride for the scheme passed to the base tag\n\n\nstring\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/ssl-redirect\n\n\nIndicates if the location section is accessible SSL only (defaults to True when Ingress contains a Certificate)\n\n\nbool\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/force-ssl-redirect\n\n\nForces the redirection to HTTPS even if the Ingress is not TLS Enabled\n\n\nbool\n\n\n\n\n\n\nnginx.ingress.kubernetes.io/app-root\n\n\nDefines the Application Root that the Controller must redirect if it's in '/' context\n\n\nstring\n\n\n\n\n\n\n\n\nValidation\n\u00b6\n\n\nRewrite Target\n\u00b6\n\n\nCreate an Ingress rule with a rewrite annotation:\n\n\n$\n \necho\n \n\"\n\n\napiVersion: extensions/v1beta1\n\n\nkind: Ingress\n\n\nmetadata:\n\n\n annotations:\n\n\n nginx.ingress.kubernetes.io/rewrite-target: /\n\n\n name: rewrite\n\n\n namespace: default\n\n\nspec:\n\n\n rules:\n\n\n - host: rewrite.bar.com\n\n\n http:\n\n\n paths:\n\n\n - backend:\n\n\n serviceName: http-svc\n\n\n servicePort: 80\n\n\n path: /something\n\n\n\" | kubectl create -f -\n\n\n\n\n\n\nCheck the rewrite is working\n\n\n$ curl -v http://172.17.4.99/something -H \n'Host: rewrite.bar.com'\n\n* Trying \n172\n.17.4.99...\n* Connected to \n172\n.17.4.99 \n(\n172\n.17.4.99\n)\n port \n80\n \n(\n#0)\n\n> GET /something HTTP/1.1\n> Host: rewrite.bar.com\n> User-Agent: curl/7.43.0\n> Accept: */*\n>\n< HTTP/1.1 \n200\n OK\n< Server: nginx/1.11.0\n< Date: Tue, \n31\n May \n2016\n \n16\n:07:31 GMT\n< Content-Type: text/plain\n< Transfer-Encoding: chunked\n< Connection: keep-alive\n<\nCLIENT VALUES:\n\nclient_address\n=\n10\n.2.56.9\n\ncommand\n=\nGET\nreal \npath\n=\n/\n\nquery\n=\nnil\n\nrequest_version\n=\n1\n.1\n\nrequest_uri\n=\nhttp://rewrite.bar.com:8080/\n\nSERVER VALUES:\n\nserver_version\n=\nnginx: \n1\n.9.11 - lua: \n10001\n\n\nHEADERS RECEIVED:\n\naccept\n=\n*/*\n\nconnection\n=\nclose\n\nhost\n=\nrewrite.bar.com\nuser-agent\n=\ncurl/7.43.0\nx-forwarded-for\n=\n10\n.2.56.1\nx-forwarded-host\n=\nrewrite.bar.com\nx-forwarded-port\n=\n80\n\nx-forwarded-proto\n=\nhttp\nx-real-ip\n=\n10\n.2.56.1\nBODY:\n* Connection \n#0 to host 172.17.4.99 left intact\n\n-no body in request-\n\n\n\n\n\nApp Root\n\u00b6\n\n\nCreate an Ingress rule with a app-root annotation:\n\n\n$ \necho\n \n\"\n\n\napiVersion: extensions/v1beta1\n\n\nkind: Ingress\n\n\nmetadata:\n\n\n annotations:\n\n\n nginx.ingress.kubernetes.io/app-root: /app1\n\n\n name: approot\n\n\n namespace: default\n\n\nspec:\n\n\n rules:\n\n\n - host: approot.bar.com\n\n\n http:\n\n\n paths:\n\n\n - backend:\n\n\n serviceName: http-svc\n\n\n servicePort: 80\n\n\n path: /\n\n\n\"\n \n|\n kubectl create -f -\n\n\n\n\n\nCheck the rewrite is working\n\n\n$ curl -I -k http://approot.bar.com/\nHTTP/1.1 \n302\n Moved Temporarily\nServer: nginx/1.11.10\nDate: Mon, \n13\n Mar \n2017\n \n14\n:57:15 GMT\nContent-Type: text/html\nContent-Length: \n162\n\nLocation: http://stickyingress.example.com/app1\nConnection: keep-alive",
"title": "Rewrite"
},
{
"location": "/examples/rewrite/README/#rewrite",
"text": "This example demonstrates how to use the Rewrite annotations",
"title": "Rewrite"
},
{
"location": "/examples/rewrite/README/#prerequisites",
"text": "You will need to make sure your Ingress targets exactly one Ingress\ncontroller by specifying the ingress.class annotation ,\nand that you have an ingress controller running in your cluster.",
"title": "Prerequisites"
},
{
"location": "/examples/rewrite/README/#deployment",
"text": "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",
"title": "Deployment"
},
{
"location": "/examples/rewrite/README/#validation",
"text": "",
"title": "Validation"
},
{
"location": "/examples/rewrite/README/#rewrite-target",
"text": "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' \n* Trying 172 .17.4.99...\n* Connected to 172 .17.4.99 ( 172 .17.4.99 ) port 80 ( #0) \n> GET /something HTTP/1.1\n> Host: rewrite.bar.com\n> User-Agent: curl/7.43.0\n> Accept: */*\n>\n< HTTP/1.1 200 OK\n< Server: nginx/1.11.0\n< Date: Tue, 31 May 2016 16 :07:31 GMT\n< Content-Type: text/plain\n< Transfer-Encoding: chunked\n< Connection: keep-alive\n<\nCLIENT VALUES: client_address = 10 .2.56.9 command = GET\nreal path = / query = nil request_version = 1 .1 request_uri = http://rewrite.bar.com:8080/\n\nSERVER VALUES: server_version = nginx: 1 .9.11 - lua: 10001 \n\nHEADERS RECEIVED: accept = */* connection = close host = rewrite.bar.com\nuser-agent = curl/7.43.0\nx-forwarded-for = 10 .2.56.1\nx-forwarded-host = rewrite.bar.com\nx-forwarded-port = 80 \nx-forwarded-proto = http\nx-real-ip = 10 .2.56.1\nBODY:\n* Connection #0 to host 172.17.4.99 left intact \n-no body in request-",
"title": "Rewrite Target"
},
{
"location": "/examples/rewrite/README/#app-root",
"text": "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/\nHTTP/1.1 302 Moved Temporarily\nServer: nginx/1.11.10\nDate: Mon, 13 Mar 2017 14 :57:15 GMT\nContent-Type: text/html\nContent-Length: 162 \nLocation: http://stickyingress.example.com/app1\nConnection: keep-alive",
"title": "App Root"
},
{
"location": "/examples/static-ip/README/",
"text": "Static IPs\n\u00b6\n\n\nThis example demonstrates how to assign a static-ip to an Ingress on through the Nginx controller.\n\n\nPrerequisites\n\u00b6\n\n\nYou need a \nTLS cert\n and a \ntest HTTP service\n for this example.\nYou will also need to make sure your Ingress targets exactly one Ingress\ncontroller by specifying the \ningress.class annotation\n,\nand that you have an ingress controller \nrunning\n in your cluster.\n\n\nAcquiring an IP\n\u00b6\n\n\nSince instances of the nginx controller actually run on nodes in your cluster,\nby default nginx Ingresses will only get static IPs if your cloudprovider\nsupports static IP assignments to nodes. On GKE/GCE for example, even though\nnodes get static IPs, the IPs are not retained across upgrade.\n\n\nTo acquire a static IP for the nginx ingress controller, simply put it\nbehind a Service of \nType=LoadBalancer\n.\n\n\nFirst, create a loadbalancer Service and wait for it to acquire an IP\n\n\n$\n kubectl create -f static-ip-svc.yaml\n\nservice \"nginx-ingress-lb\" created\n\n\n\n$\n kubectl get svc nginx-ingress-lb\n\nNAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE\n\n\nnginx-ingress-lb 10.0.138.113 104.154.109.191 80:31457/TCP,443:32240/TCP 15m\n\n\n\n\n\n\nthen, update the ingress controller so it adopts the static IP of the Service\nby passing the \n--publish-service\n flag (the example yaml used in the next step\nalready has it set to \"nginx-ingress-lb\").\n\n\n$\n kubectl create -f nginx-ingress-controller.yaml\n\ndeployment \"nginx-ingress-controller\" created\n\n\n\n\n\n\nAssigning the IP to an Ingress\n\u00b6\n\n\nFrom here on every Ingress created with the \ningress.class\n annotation set to\n\nnginx\n will get the IP allocated in the previous step\n\n\n$\n kubectl create -f nginx-ingress.yaml\n\ningress \"nginx-ingress\" created\n\n\n\n$\n kubectl get ing nginx-ingress\n\nNAME HOSTS ADDRESS PORTS AGE\n\n\nnginx-ingress * 104.154.109.191 80, 443 13m\n\n\n\n$\n curl \n104\n.154.109.191 -kL\n\nCLIENT VALUES:\n\n\nclient_address=10.180.1.25\n\n\ncommand=GET\n\n\nreal path=/\n\n\nquery=nil\n\n\nrequest_version=1.1\n\n\nrequest_uri=http://104.154.109.191:8080/\n\n\n...\n\n\n\n\n\n\nRetaining the IP\n\u00b6\n\n\nYou can test retention by deleting the Ingress\n\n\n$\n kubectl delete ing nginx-ingress\n\ningress \"nginx-ingress\" deleted\n\n\n\n$\n kubectl create -f nginx-ingress.yaml\n\ningress \"nginx-ingress\" created\n\n\n\n$\n kubectl get ing nginx-ingress\n\nNAME HOSTS ADDRESS PORTS AGE\n\n\nnginx-ingress * 104.154.109.191 80, 443 13m\n\n\n\n\n\n\n\n\nNote that unlike the GCE Ingress, the same loadbalancer IP is shared amongst all\nIngresses, because all requests are proxied through the same set of nginx\ncontrollers.\n\n\n\n\nPromote ephemeral to static IP\n\u00b6\n\n\nTo promote the allocated IP to static, you can update the Service manifest\n\n\n$\n kubectl patch svc nginx-ingress-lb -p \n'{\"spec\": {\"loadBalancerIP\": \"104.154.109.191\"}}'\n\n\n\"nginx-ingress-lb\" patched\n\n\n\n\n\n\nand promote the IP to static (promotion works differently for cloudproviders,\nprovided example is for GKE/GCE)\n`\n\n\n$\n gcloud compute addresses create nginx-ingress-lb --addresses \n104\n.154.109.191 --region us-central1\n\nCreated [https://www.googleapis.com/compute/v1/projects/kubernetesdev/regions/us-central1/addresses/nginx-ingress-lb].\n\n\n---\n\n\naddress: 104.154.109.191\n\n\ncreationTimestamp: '2017-01-31T16:34:50.089-08:00'\n\n\ndescription: ''\n\n\nid: '5208037144487826373'\n\n\nkind: compute#address\n\n\nname: nginx-ingress-lb\n\n\nregion: us-central1\n\n\nselfLink: https://www.googleapis.com/compute/v1/projects/kubernetesdev/regions/us-central1/addresses/nginx-ingress-lb\n\n\nstatus: IN_USE\n\n\nusers:\n\n\n- us-central1/forwardingRules/a09f6913ae80e11e6a8c542010af0000\n\n\n\n\n\n\nNow even if the Service is deleted, the IP will persist, so you can recreate the\nService with \nspec.loadBalancerIP\n set to \n104.154.109.191\n.",
"title": "Static IPs"
},
{
"location": "/examples/static-ip/README/#static-ips",
"text": "This example demonstrates how to assign a static-ip to an Ingress on through the Nginx controller.",
"title": "Static IPs"
},
{
"location": "/examples/static-ip/README/#prerequisites",
"text": "You need a TLS cert and a test HTTP service for this example.\nYou will also need to make sure your Ingress targets exactly one Ingress\ncontroller by specifying the ingress.class annotation ,\nand that you have an ingress controller running in your cluster.",
"title": "Prerequisites"
},
{
"location": "/examples/static-ip/README/#acquiring-an-ip",
"text": "Since instances of the nginx controller actually run on nodes in your cluster,\nby default nginx Ingresses will only get static IPs if your cloudprovider\nsupports static IP assignments to nodes. On GKE/GCE for example, even though\nnodes get static IPs, the IPs are not retained across upgrade. To acquire a static IP for the nginx ingress controller, simply put it\nbehind 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\nby passing the --publish-service flag (the example yaml used in the next step\nalready has it set to \"nginx-ingress-lb\"). $ kubectl create -f nginx-ingress-controller.yaml deployment \"nginx-ingress-controller\" created",
"title": "Acquiring an IP"
},
{
"location": "/examples/static-ip/README/#assigning-the-ip-to-an-ingress",
"text": "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/ ...",
"title": "Assigning the IP to an Ingress"
},
{
"location": "/examples/static-ip/README/#retaining-the-ip",
"text": "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\nIngresses, because all requests are proxied through the same set of nginx\ncontrollers.",
"title": "Retaining the IP"
},
{
"location": "/examples/static-ip/README/#promote-ephemeral-to-static-ip",
"text": "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,\nprovided example is for GKE/GCE)\n` $ 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\nService with spec.loadBalancerIP set to 104.154.109.191 .",
"title": "Promote ephemeral to static IP"
},
{
"location": "/examples/tls-termination/README/",
"text": "TLS termination\n\u00b6\n\n\nThis example demonstrates how to terminate TLS through the nginx Ingress controller.\n\n\nPrerequisites\n\u00b6\n\n\nYou need a \nTLS cert\n and a \ntest HTTP service\n for this example.\n\n\nDeployment\n\u00b6\n\n\nThe following command instructs the controller to terminate traffic using the provided \nTLS cert, and forward un-encrypted HTTP traffic to the test HTTP service.\n\n\nkubectl apply -f ingress.yaml\n\n\n\n\n\n\nValidation\n\u00b6\n\n\nYou can confirm that the Ingress works.\n\n\n$\n kubectl describe ing nginx-test\n\nName: nginx-test\n\n\nNamespace: default\n\n\nAddress: 104.198.183.6\n\n\nDefault backend: default-http-backend:80 (10.180.0.4:8080,10.240.0.2:8080)\n\n\nTLS:\n\n\n tls-secret terminates\n\n\nRules:\n\n\n Host Path Backends\n\n\n ---- ---- --------\n\n\n *\n\n\n http-svc:80 (<none>)\n\n\nAnnotations:\n\n\nEvents:\n\n\n FirstSeen LastSeen Count From SubObjectPath Type Reason Message\n\n\n --------- -------- ----- ---- ------------- -------- ------ -------\n\n\n 7s 7s 1 {nginx-ingress-controller } Normal CREATE default/nginx-test\n\n\n 7s 7s 1 {nginx-ingress-controller } Normal UPDATE default/nginx-test\n\n\n 7s 7s 1 {nginx-ingress-controller } Normal CREATE ip: 104.198.183.6\n\n\n 7s 7s 1 {nginx-ingress-controller } Warning MAPPING Ingress rule 'default/nginx-test' contains no path definition. Assuming /\n\n\n\n$\n curl \n104\n.198.183.6 -L\n\ncurl: (60) SSL certificate problem: self signed certificate\n\n\nMore details here: http://curl.haxx.se/docs/sslcerts.html\n\n\n\n$\n curl \n104\n.198.183.6 -Lk\n\nCLIENT VALUES:\n\n\nclient_address=10.240.0.4\n\n\ncommand=GET\n\n\nreal path=/\n\n\nquery=nil\n\n\nrequest_version=1.1\n\n\nrequest_uri=http://35.186.221.137:8080/\n\n\n\nSERVER VALUES:\n\n\nserver_version=nginx: 1.9.11 - lua: 10001\n\n\n\nHEADERS RECEIVED:\n\n\naccept=*/*\n\n\nconnection=Keep-Alive\n\n\nhost=35.186.221.137\n\n\nuser-agent=curl/7.46.0\n\n\nvia=1.1 google\n\n\nx-cloud-trace-context=f708ea7e369d4514fc90d51d7e27e91d/13322322294276298106\n\n\nx-forwarded-for=104.132.0.80, 35.186.221.137\n\n\nx-forwarded-proto=https\n\n\nBODY:",
"title": "TLS termination"
},
{
"location": "/examples/tls-termination/README/#tls-termination",
"text": "This example demonstrates how to terminate TLS through the nginx Ingress controller.",
"title": "TLS termination"
},
{
"location": "/examples/tls-termination/README/#prerequisites",
"text": "You need a TLS cert and a test HTTP service for this example.",
"title": "Prerequisites"
},
{
"location": "/examples/tls-termination/README/#deployment",
"text": "The following command instructs the controller to terminate traffic using the provided \nTLS cert, and forward un-encrypted HTTP traffic to the test HTTP service. kubectl apply -f ingress.yaml",
"title": "Deployment"
},
{
"location": "/examples/tls-termination/README/#validation",
"text": "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:",
"title": "Validation"
},
{
"location": "/development/",
"text": "Developing for NGINX Ingress Controller\n\u00b6\n\n\nThis document explains how to get started with developing for NGINX Ingress controller.\nIt includes how to build, test, and release ingress controllers.\n\n\nQuick Start\n\u00b6\n\n\nGetting the code\n\u00b6\n\n\nThe code must be checked out as a subdirectory of k8s.io, and not github.com.\n\n\nmkdir -p $GOPATH/src/k8s.io\ncd $GOPATH/src/k8s.io\n# Replace \"$YOUR_GITHUB_USERNAME\" below with your github username\ngit clone https://github.com/$YOUR_GITHUB_USERNAME/ingress-nginx.git\ncd ingress-nginx\n\n\n\n\n\nInitial developer environment build\n\u00b6\n\n\n\n\nPrequisites\n: Minikube must be installed.\nSee \nreleases\n for installation instructions. \n\n\n\n\nIf you are using \nMacOS\n and deploying to \nminikube\n, 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 \ningress-nginx\n:\n\n\n$ make dev-env\n\n\n\n\n\nUpdating the deployment\n\u00b6\n\n\nThe nginx controller container image can be rebuilt using:\n\n\n$ \nARCH\n=\namd64 \nTAG\n=\ndev \nREGISTRY\n=\n$USER\n/ingress-controller make build container\n\n\n\n\n\nThe image will only be used by pods created after the rebuild. To delete old pods which will cause new ones to spin up:\n\n\n$ kubectl get pods -n ingress-nginx\n$ kubectl delete pod -n ingress-nginx nginx-ingress-controller-<unique-pod-id>\n\n\n\n\n\nDependencies\n\u00b6\n\n\nThe build uses dependencies in the \nvendor\n directory, which\nmust be installed before building a binary/image. Occasionally, you\nmight need to update the dependencies.\n\n\nThis guide requires you to install the \ndep\n dependency tool.\n\n\nCheck the version of \ndep\n you are using and make sure it is up to date.\n\n\n$\n dep version\n\ndep:\n\n\n version : devel\n\n\n build date : \n\n\n git hash : \n\n\n go version : go1.9\n\n\n go compiler : gc\n\n\n platform : linux/amd64\n\n\n\n\n\n\nIf you have an older version of \ndep\n, you can update it as follows:\n\n\n$\n go get -u github.com/golang/dep\n\n\n\n\n\nThis will automatically save the dependencies to the \nvendor/\n directory.\n\n\n$\n \ncd\n \n$GOPATH\n/src/k8s.io/ingress-nginx\n\n$\n dep ensure\n\n$\n dep ensure -update\n\n$\n dep prune\n\n\n\n\n\nBuilding\n\u00b6\n\n\nAll ingress controllers are built through a Makefile. Depending on your\nrequirements you can build a raw server binary, a local container image,\nor push an image to a remote repository.\n\n\nIn order to use your local Docker, you may need to set the following environment variables:\n\n\n#\n \n\"gcloud docker\"\n \n(\ndefault\n)\n or \n\"docker\"\n\n\n$\n \nexport\n \nDOCKER\n=\n<docker>\n\n\n#\n \n\"quay.io/kubernetes-ingress-controller\"\n \n(\ndefault\n)\n, \n\"index.docker.io\"\n, or your own registry\n\n$\n \nexport\n \nREGISTRY\n=\n<your-docker-registry>\n\n\n\n\n\nTo find the registry simply run: \ndocker system info | grep Registry\n\n\nNginx Controller\n\u00b6\n\n\nBuild a raw server binary\n\n\n$\n make build\n\n\n\n\n\nTODO\n: add more specific instructions needed for raw server binary.\n\n\nBuild a local container image\n\n\n$\n \nTAG\n=\n<tag> \nREGISTRY\n=\n$USER\n/ingress-controller make docker-build\n\n\n\n\n\nPush the container image to a remote repository\n\n\n$\n \nTAG\n=\n<tag> \nREGISTRY\n=\n$USER\n/ingress-controller make docker-push\n\n\n\n\n\nDeploying\n\u00b6\n\n\nThere are several ways to deploy the ingress controller onto a cluster.\nPlease check the \ndeployment guide\n\n\nTesting\n\u00b6\n\n\nTo run unit-tests, just run\n\n\n$\n \ncd\n \n$GOPATH\n/src/k8s.io/ingress-nginx\n\n$\n make \ntest\n\n\n\n\n\n\nIf you have access to a Kubernetes cluster, you can also run e2e tests using ginkgo.\n\n\n$\n \ncd\n \n$GOPATH\n/src/k8s.io/ingress-nginx\n\n$\n make e2e-test\n\n\n\n\n\nTo run unit-tests for lua code locally, run:\n\n\n$\n \ncd\n \n$GOPATH\n/src/k8s.io/ingress-nginx\n\n$\n ./rootfs/etc/nginx/lua/test/up.sh\n\n$\n make lua-test\n\n\n\n\n\nLua tests are located in \n$GOPATH/src/k8s.io/ingress-nginx/rootfs/etc/nginx/lua/test\n. When creating a new test file it must follow the naming convention \n<mytest>_test.lua\n or it will be ignored. \n\n\nReleasing\n\u00b6\n\n\nAll Makefiles will produce a release binary, as shown above. To publish this\nto a wider Kubernetes user base, push the image to a container registry, like\n\ngcr.io\n. All release images are hosted under \ngcr.io/google_containers\n and\ntagged according to a \nsemver\n scheme.\n\n\nAn example release might look like:\n\n\n$ make release\n\n\n\n\n\nPlease follow these guidelines to cut a release:\n\n\n\n\nUpdate the \nrelease\n\npage with a short description of the major changes that correspond to a given\nimage tag.\n\n\nCut a release branch, if appropriate. Release branches follow the format of\n\ncontroller-release-version\n. Typically, pre-releases are cut from HEAD.\nAll major feature work is done in HEAD. Specific bug fixes are\ncherry-picked into a release branch.\n\n\nIf you're not confident about the stability of the code,\n\ntag\n it as alpha or beta.\nTypically, a release branch should have stable code.",
"title": "Developing for NGINX Ingress Controller"
},
{
"location": "/development/#developing-for-nginx-ingress-controller",
"text": "This document explains how to get started with developing for NGINX Ingress controller.\nIt includes how to build, test, and release ingress controllers.",
"title": "Developing for NGINX Ingress Controller"
},
{
"location": "/development/#quick-start",
"text": "",
"title": "Quick Start"
},
{
"location": "/development/#getting-the-code",
"text": "The code must be checked out as a subdirectory of k8s.io, and not github.com. mkdir -p $GOPATH/src/k8s.io\ncd $GOPATH/src/k8s.io\n# Replace \"$YOUR_GITHUB_USERNAME\" below with your github username\ngit clone https://github.com/$YOUR_GITHUB_USERNAME/ingress-nginx.git\ncd ingress-nginx",
"title": "Getting the code"
},
{
"location": "/development/#initial-developer-environment-build",
"text": "Prequisites : Minikube must be installed.\nSee 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",
"title": "Initial developer environment build"
},
{
"location": "/development/#updating-the-deployment",
"text": "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\n$ kubectl delete pod -n ingress-nginx nginx-ingress-controller-<unique-pod-id>",
"title": "Updating the deployment"
},
{
"location": "/development/#dependencies",
"text": "The build uses dependencies in the vendor directory, which\nmust be installed before building a binary/image. Occasionally, you\nmight 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",
"title": "Dependencies"
},
{
"location": "/development/#building",
"text": "All ingress controllers are built through a Makefile. Depending on your\nrequirements you can build a raw server binary, a local container image,\nor 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",
"title": "Building"
},
{
"location": "/development/#nginx-controller",
"text": "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",
"title": "Nginx Controller"
},
{
"location": "/development/#deploying",
"text": "There are several ways to deploy the ingress controller onto a cluster.\nPlease check the deployment guide",
"title": "Deploying"
},
{
"location": "/development/#testing",
"text": "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.",
"title": "Testing"
},
{
"location": "/development/#releasing",
"text": "All Makefiles will produce a release binary, as shown above. To publish this\nto 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\ntagged according to a semver scheme. An example release might look like: $ make release Please follow these guidelines to cut a release: Update the release \npage with a short description of the major changes that correspond to a given\nimage tag. Cut a release branch, if appropriate. Release branches follow the format of controller-release-version . Typically, pre-releases are cut from HEAD.\nAll major feature work is done in HEAD. Specific bug fixes are\ncherry-picked into a release branch. If you're not confident about the stability of the code, tag it as alpha or beta.\nTypically, a release branch should have stable code.",
"title": "Releasing"
},
{
"location": "/ingress-controller-catalog/",
"text": "Ingress Controller Catalog\n\u00b6\n\n\nThis is a non-comprehensive list of existing ingress controllers.\n\n\n\n\nDummy controller backend\n\n\nHAProxy Ingress controller\n\n\nLinkerd\n\n\ntraefik\n\n\nAWS Application Load Balancer Ingress Controller\n\n\nkube-ingress-aws-controller\n\n\nVoyager: HAProxy Ingress Controller\n\n\nExternal Nginx Ingress Controller\n\n\nHeptio Contour controller\n\n\nLemonLDAP::NG kubernetes controller\n adds WebSSO, Access Management and Identity Federation to NGINX Ingress Controller",
"title": "Ingress Controller Catalog"
},
{
"location": "/ingress-controller-catalog/#ingress-controller-catalog",
"text": "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",
"title": "Ingress Controller Catalog"
},
{
"location": "/troubleshooting/",
"text": "Debug & Troubleshooting\n\u00b6\n\n\nDebug\n\u00b6\n\n\nUsing the flag \n--v=XX\n it is possible to increase the level of logging.\nIn particular:\n\n\n\n\n--v=2\n shows details using \ndiff\n about the changes in the configuration in nginx\n\n\n\n\nI0316 12:24:37.581267 1 utils.go:148] NGINX configuration diff a//etc/nginx/nginx.conf b//etc/nginx/nginx.conf\n\n\nI0316 12:24:37.581356 1 utils.go:149] --- /tmp/922554809 2016-03-16 12:24:37.000000000 +0000\n\n\n+++ /tmp/079811012 2016-03-16 12:24:37.000000000 +0000\n\n\n@@ -235,7 +235,6 @@\n\n\n\n upstream default-http-svcx {\n\n\n least_conn;\n\n\n- server 10.2.112.124:5000;\n\n\n server 10.2.208.50:5000;\n\n\n\n }\n\n\nI0316 12:24:37.610073 1 command.go:69] change in configuration detected. Reloading...\n\n\n\n\n\n\n\n\n--v=3\n shows details about the service, Ingress rule, endpoint changes and it dumps the nginx configuration in JSON format\n\n\n--v=5\n configures NGINX in \ndebug mode\n\n\n\n\nTroubleshooting\n\u00b6\n\n\nAuthentication to the Kubernetes API Server\n\u00b6\n\n\nA number of components are involved in the authentication process and the first step is to narrow\ndown the source of the problem, namely whether it is a problem with service authentication or with the kubeconfig file.\nBoth authentications must work:\n\n\n+-------------+ service +------------+\n| | authentication | |\n+ apiserver +<-------------------+ ingress |\n| | | controller |\n+-------------+ +------------+\n\n\n\n\n\nService authentication\n\n\nThe Ingress controller needs information from apiserver. Therefore, authentication is required, which can be achieved in two different ways:\n\n\n\n\n\n\nService Account:\n This is recommended, because nothing has to be configured. The Ingress controller will use information provided by the system to communicate with the API server. See 'Service Account' section for details.\n\n\n\n\n\n\nKubeconfig file:\n In some Kubernetes environments service accounts are not available. In this case a manual configuration is required. The Ingress controller binary can be started with the \n--kubeconfig\n flag. The value of the flag is a path to a file specifying how to connect to the API server. Using the \n--kubeconfig\n does not requires the flag \n--apiserver-host\n.\nThe format of the file is identical to \n~/.kube/config\n which is used by kubectl to connect to the API server. See 'kubeconfig' section for details.\n\n\n\n\n\n\nUsing the flag \n--apiserver-host\n:\n Using this flag \n--apiserver-host=http://localhost:8080\n it is possible to specify an unsecured API server or reach a remote kubernetes cluster using \nkubectl proxy\n.\nPlease do not use this approach in production.\n\n\n\n\n\n\nIn the diagram below you can see the full authentication flow with all options, starting with the browser\non the lower left hand side.\n\n\nKubernetes Workstation\n+---------------------------------------------------+ +------------------+\n| | | |\n| +-----------+ apiserver +------------+ | | +------------+ |\n| | | proxy | | | | | | |\n| | apiserver | | ingress | | | | ingress | |\n| | | | controller | | | | controller | |\n| | | | | | | | | |\n| | | | | | | | | |\n| | | service account/ | | | | | | |\n| | | kubeconfig | | | | | | |\n| | +<-------------------+ | | | | | |\n| | | | | | | | | |\n| +------+----+ kubeconfig +------+-----+ | | +------+-----+ |\n| |<--------------------------------------------------------| |\n| | | |\n+---------------------------------------------------+ +------------------+\n\n\n\n\n\nService Account\n\u00b6\n\n\nIf using a service account to connect to the API server, Dashboard expects the file\n\n/var/run/secrets/kubernetes.io/serviceaccount/token\n to be present. It provides a secret\ntoken that is required to authenticate with the API server.\n\n\nVerify with the following commands:\n\n\n# start a container that contains curl\n\n$ kubectl run \ntest\n --image\n=\ntutum/curl -- sleep \n10000\n\n\n\n# check that container is running\n\n$ kubectl get pods\nNAME READY STATUS RESTARTS AGE\ntest-701078429-s5kca \n1\n/1 Running \n0\n 16s\n\n\n# check if secret exists\n\n$ kubectl \nexec\n test-701078429-s5kca ls /var/run/secrets/kubernetes.io/serviceaccount/\nca.crt\nnamespace\ntoken\n\n\n# get service IP of master\n\n$ kubectl get services\nNAME CLUSTER-IP EXTERNAL-IP PORT\n(\nS\n)\n AGE\nkubernetes \n10\n.0.0.1 <none> \n443\n/TCP 1d\n\n\n# check base connectivity from cluster inside\n\n$ kubectl \nexec\n test-701078429-s5kca -- curl -k https://10.0.0.1\nUnauthorized\n\n\n# connect using tokens\n\n$ \nTOKEN_VALUE\n=\n$(\nkubectl \nexec\n test-701078429-s5kca -- cat /var/run/secrets/kubernetes.io/serviceaccount/token\n)\n\n$ \necho\n \n$TOKEN_VALUE\n\neyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3Mi....9A\n$ kubectl \nexec\n test-701078429-s5kca -- curl --cacert /var/run/secrets/kubernetes.io/serviceaccount/ca.crt -H \n\"Authorization: Bearer \n$TOKEN_VALUE\n\"\n https://10.0.0.1\n\n{\n\n \n\"paths\"\n: \n[\n\n \n\"/api\"\n,\n \n\"/api/v1\"\n,\n \n\"/apis\"\n,\n \n\"/apis/apps\"\n,\n \n\"/apis/apps/v1alpha1\"\n,\n \n\"/apis/authentication.k8s.io\"\n,\n \n\"/apis/authentication.k8s.io/v1beta1\"\n,\n \n\"/apis/authorization.k8s.io\"\n,\n \n\"/apis/authorization.k8s.io/v1beta1\"\n,\n \n\"/apis/autoscaling\"\n,\n \n\"/apis/autoscaling/v1\"\n,\n \n\"/apis/batch\"\n,\n \n\"/apis/batch/v1\"\n,\n \n\"/apis/batch/v2alpha1\"\n,\n \n\"/apis/certificates.k8s.io\"\n,\n \n\"/apis/certificates.k8s.io/v1alpha1\"\n,\n \n\"/apis/extensions\"\n,\n \n\"/apis/extensions/v1beta1\"\n,\n \n\"/apis/policy\"\n,\n \n\"/apis/policy/v1alpha1\"\n,\n \n\"/apis/rbac.authorization.k8s.io\"\n,\n \n\"/apis/rbac.authorization.k8s.io/v1alpha1\"\n,\n \n\"/apis/storage.k8s.io\"\n,\n \n\"/apis/storage.k8s.io/v1beta1\"\n,\n \n\"/healthz\"\n,\n \n\"/healthz/ping\"\n,\n \n\"/logs\"\n,\n \n\"/metrics\"\n,\n \n\"/swaggerapi/\"\n,\n \n\"/ui/\"\n,\n \n\"/version\"\n\n \n]\n\n\n}\n\n\n\n\n\n\nIf it is not working, there are two possible reasons:\n\n\n\n\n\n\nThe contents of the tokens are invalid. Find the secret name with \nkubectl get secrets | grep service-account\n and\ndelete it with \nkubectl delete secret <name>\n. It will automatically be recreated.\n\n\n\n\n\n\nYou have a non-standard Kubernetes installation and the file containing the token may not be present.\nThe API server will mount a volume containing this file, but only if the API server is configured to use\nthe ServiceAccount admission controller.\nIf you experience this error, verify that your API server is using the ServiceAccount admission controller.\nIf you are configuring the API server by hand, you can set this with the \n--admission-control\n parameter.\n\n\n\n\nNote that you should use other admission controllers as well. Before configuring this option, you should read about admission controllers.\n\n\n\n\n\n\n\n\nMore information:\n\n\n\n\nUser Guide: Service Accounts\n\n\nCluster Administrator Guide: Managing Service Accounts\n\n\n\n\nKubeconfig\n\u00b6\n\n\nIf you want to use a kubeconfig file for authentication, follow the deploy procedure and \nadd the flag \n--kubeconfig=/etc/kubernetes/kubeconfig.yaml\n to the deployment",
"title": "Debug & Troubleshooting"
},
{
"location": "/troubleshooting/#debug-troubleshooting",
"text": "",
"title": "Debug &amp; Troubleshooting"
},
{
"location": "/troubleshooting/#debug",
"text": "Using the flag --v=XX it is possible to increase the level of logging.\nIn particular: --v=2 shows details using diff about the changes in the configuration in nginx I0316 12:24:37.581267 1 utils.go:148] NGINX configuration diff a//etc/nginx/nginx.conf b//etc/nginx/nginx.conf I0316 12:24:37.581356 1 utils.go:149] --- /tmp/922554809 2016-03-16 12:24:37.000000000 +0000 +++ /tmp/079811012 2016-03-16 12:24:37.000000000 +0000 @@ -235,7 +235,6 @@ upstream default-http-svcx { least_conn; - server 10.2.112.124:5000; server 10.2.208.50:5000; } I0316 12:24:37.610073 1 command.go:69] change in configuration detected. Reloading... --v=3 shows details about the service, Ingress rule, endpoint changes and it dumps the nginx configuration in JSON format --v=5 configures NGINX in debug mode",
"title": "Debug"
},
{
"location": "/troubleshooting/#troubleshooting",
"text": "",
"title": "Troubleshooting"
},
{
"location": "/troubleshooting/#authentication-to-the-kubernetes-api-server",
"text": "A number of components are involved in the authentication process and the first step is to narrow\ndown the source of the problem, namely whether it is a problem with service authentication or with the kubeconfig file.\nBoth authentications must work: +-------------+ service +------------+\n| | authentication | |\n+ apiserver +<-------------------+ ingress |\n| | | controller |\n+-------------+ +------------+ Service authentication The Ingress controller needs information from apiserver. Therefore, authentication is required, which can be achieved in two different ways: Service Account: This is recommended, because nothing has to be configured. The Ingress controller will use information provided by the system to communicate with the API server. See 'Service Account' section for details. Kubeconfig file: In some Kubernetes environments service accounts are not available. In this case a manual configuration is required. The Ingress controller binary can be started with the --kubeconfig flag. The value of the flag is a path to a file specifying how to connect to the API server. Using the --kubeconfig does not requires the flag --apiserver-host .\nThe format of the file is identical to ~/.kube/config which is used by kubectl to connect to the API server. See 'kubeconfig' section for details. Using the flag --apiserver-host : Using this flag --apiserver-host=http://localhost:8080 it is possible to specify an unsecured API server or reach a remote kubernetes cluster using kubectl proxy .\nPlease do not use this approach in production. In the diagram below you can see the full authentication flow with all options, starting with the browser\non the lower left hand side. Kubernetes Workstation\n+---------------------------------------------------+ +------------------+\n| | | |\n| +-----------+ apiserver +------------+ | | +------------+ |\n| | | proxy | | | | | | |\n| | apiserver | | ingress | | | | ingress | |\n| | | | controller | | | | controller | |\n| | | | | | | | | |\n| | | | | | | | | |\n| | | service account/ | | | | | | |\n| | | kubeconfig | | | | | | |\n| | +<-------------------+ | | | | | |\n| | | | | | | | | |\n| +------+----+ kubeconfig +------+-----+ | | +------+-----+ |\n| |<--------------------------------------------------------| |\n| | | |\n+---------------------------------------------------+ +------------------+",
"title": "Authentication to the Kubernetes API Server"
},
{
"location": "/troubleshooting/#service-account",
"text": "If using a service account to connect to the API server, Dashboard expects the file /var/run/secrets/kubernetes.io/serviceaccount/token to be present. It provides a secret\ntoken that is required to authenticate with the API server. Verify with the following commands: # start a container that contains curl \n$ kubectl run test --image = tutum/curl -- sleep 10000 # check that container is running \n$ kubectl get pods\nNAME READY STATUS RESTARTS AGE\ntest-701078429-s5kca 1 /1 Running 0 16s # check if secret exists \n$ kubectl exec test-701078429-s5kca ls /var/run/secrets/kubernetes.io/serviceaccount/\nca.crt\nnamespace\ntoken # get service IP of master \n$ kubectl get services\nNAME CLUSTER-IP EXTERNAL-IP PORT ( S ) AGE\nkubernetes 10 .0.0.1 <none> 443 /TCP 1d # check base connectivity from cluster inside \n$ kubectl exec test-701078429-s5kca -- curl -k https://10.0.0.1\nUnauthorized # connect using tokens \n$ TOKEN_VALUE = $( kubectl exec test-701078429-s5kca -- cat /var/run/secrets/kubernetes.io/serviceaccount/token ) \n$ echo $TOKEN_VALUE \neyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3Mi....9A\n$ kubectl exec test-701078429-s5kca -- curl --cacert /var/run/secrets/kubernetes.io/serviceaccount/ca.crt -H \"Authorization: Bearer $TOKEN_VALUE \" https://10.0.0.1 { \n \"paths\" : [ \n \"/api\" ,\n \"/api/v1\" ,\n \"/apis\" ,\n \"/apis/apps\" ,\n \"/apis/apps/v1alpha1\" ,\n \"/apis/authentication.k8s.io\" ,\n \"/apis/authentication.k8s.io/v1beta1\" ,\n \"/apis/authorization.k8s.io\" ,\n \"/apis/authorization.k8s.io/v1beta1\" ,\n \"/apis/autoscaling\" ,\n \"/apis/autoscaling/v1\" ,\n \"/apis/batch\" ,\n \"/apis/batch/v1\" ,\n \"/apis/batch/v2alpha1\" ,\n \"/apis/certificates.k8s.io\" ,\n \"/apis/certificates.k8s.io/v1alpha1\" ,\n \"/apis/extensions\" ,\n \"/apis/extensions/v1beta1\" ,\n \"/apis/policy\" ,\n \"/apis/policy/v1alpha1\" ,\n \"/apis/rbac.authorization.k8s.io\" ,\n \"/apis/rbac.authorization.k8s.io/v1alpha1\" ,\n \"/apis/storage.k8s.io\" ,\n \"/apis/storage.k8s.io/v1beta1\" ,\n \"/healthz\" ,\n \"/healthz/ping\" ,\n \"/logs\" ,\n \"/metrics\" ,\n \"/swaggerapi/\" ,\n \"/ui/\" ,\n \"/version\" \n ] } If it is not working, there are two possible reasons: The contents of the tokens are invalid. Find the secret name with kubectl get secrets | grep service-account and\ndelete it with kubectl delete secret <name> . It will automatically be recreated. You have a non-standard Kubernetes installation and the file containing the token may not be present.\nThe API server will mount a volume containing this file, but only if the API server is configured to use\nthe ServiceAccount admission controller.\nIf you experience this error, verify that your API server is using the ServiceAccount admission controller.\nIf you are configuring the API server by hand, you can set this with the --admission-control parameter. Note that you should use other admission controllers as well. Before configuring this option, you should read about admission controllers. More information: User Guide: Service Accounts Cluster Administrator Guide: Managing Service Accounts",
"title": "Service Account"
},
{
"location": "/troubleshooting/#kubeconfig",
"text": "If you want to use a kubeconfig file for authentication, follow the deploy procedure and \nadd the flag --kubeconfig=/etc/kubernetes/kubeconfig.yaml to the deployment",
"title": "Kubeconfig"
}
]
}
Reference in a new issue View git blame Copy permalink