By default, the controller watches Ingress objects from all namespaces. If you want to change this behavior, use the flag --watch-namespace or check the Helm chart value controller.scope to limit the controller to a single namespace.
The controller uses an admission webhook to validate Ingress definitions. Make sure that you don't have Network policies or additional firewalls preventing connections from the API server to the ingress-nginx-controller-admission service.
This example applies to nginx-ingress-controllers being deployed in an environment with RBAC enabled.
Role Based Access Control is comprised of four layers:
ClusterRole - permissions assigned to a role that apply to an entire cluster
ClusterRoleBinding - binding a ClusterRole to a specific account
Role - permissions assigned to a role that apply to a specific namespace
RoleBinding - binding a Role to a specific account
In order for RBAC to be applied to an nginx-ingress-controller, that controller should be assigned to a ServiceAccount. That ServiceAccount should be bound to the Roles and ClusterRoles defined for the nginx-ingress-controller.
There are two sets of permissions defined in this example. Cluster-wide permissions defined by the ClusterRole named nginx-ingress-clusterrole, and namespace specific permissions defined by the Role named nginx-ingress-role.
These permissions are granted in order for the nginx-ingress-controller to be able to function as an ingress across the cluster. These permissions are granted to the ClusterRole named nginx-ingress-clusterrole
These permissions are granted specific to the nginx-ingress namespace. These permissions are granted to the Role named nginx-ingress-role
configmaps, pods, secrets: get
endpoints: get
Furthermore to support leader-election, the nginx-ingress-controller needs to have access to a configmap using the resourceName ingress-controller-leader-nginx
Note that resourceNames can NOT be used to limit requests using the “create” verb because authorizers only have access to information that can be obtained from the request URL, method, and headers (resource names in a “create” request are part of the request body).
The ServiceAccount nginx-ingress-serviceaccount is bound to the Role nginx-ingress-role and the ClusterRole nginx-ingress-clusterrole.
The serviceAccountName associated with the containers in the deployment must match the serviceAccount. The namespace references in the Deployment metadata, container arguments, and POD_NAMESPACE should be in the nginx-ingress namespace.
This example applies to ingress-nginx-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 ingress-nginx-controller, that controller should be assigned to a ServiceAccount. That ServiceAccount should be bound to the Roles and ClusterRoles defined for the ingress-nginx-controller.
There are two sets of permissions defined in this example. Cluster-wide permissions defined by the ClusterRole named ingress-nginx, and namespace specific permissions defined by the Role named ingress-nginx.
These permissions are granted in order for the ingress-nginx-controller to be able to function as an ingress across the cluster. These permissions are granted to the ClusterRole named ingress-nginx
These permissions are granted specific to the ingress-nginx namespace. These permissions are granted to the Role named ingress-nginx
configmaps, pods, secrets: get
endpoints: get
Furthermore to support leader-election, the ingress-nginx-controller needs to have access to a configmap using the resourceName ingress-controller-leader-nginx
Note that resourceNames can NOT be used to limit requests using the “create” verb because authorizers only have access to information that can be obtained from the request URL, method, and headers (resource names in a “create” request are part of the request body).
The ServiceAccount ingress-nginx is bound to the Role ingress-nginx and the ClusterRole ingress-nginx.
The serviceAccountName associated with the containers in the deployment must match the serviceAccount. The namespace references in the Deployment metadata, container arguments, and POD_NAMESPACE should be in the ingress-nginx namespace.
No matter the method you use for upgrading, if you use template overrides, make sure your templates are compatible with the new version of ingress-nginx.
simply change the 0.34.0 tag to the version you wish to upgrade to. The easiest way to do this is e.g. (do note you may need to change the name parameter according to your installation):
kubectl set image deployment/nginx-ingress-controller \
- nginx-ingress-controller=k8s.gcr.io/ingress-nginx/controller:v0.34.1@sha256:0e072dddd1f7f8fc8909a2ca6f65e76c5f0d2fcfb8be47935ae3457e8bbceb20 \
+
simply change the v1.0.4 tag to the version you wish to upgrade to. The easiest way to do this is e.g. (do note you may need to change the name parameter according to your installation):
This functionality is enabled by deploying multiple Ingress objects for a single host. One Ingress object has no special annotations and handles authentication.
Other Ingress objects can then be annotated in such a way that require the user to authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint.
This functionality is enabled by deploying multiple Ingress objects for a single host. One Ingress object has no special annotations and handles authentication.
Other Ingress objects can then be annotated in such a way that require the user to authenticate against the first Ingress's endpoint, and can redirect 401s to the same endpoint.
You're also responsible for provisioning an SSL certificate for the ingress. So you need to have a valid SSL certificate, deployed as a Kubernetes secret of type tls, in the same namespace as the gRPC application.
Step 1: Create a Kubernetes Deployment for gRPC app ¶
Make sure your gRPC application pod is running and listening for connections. For example you can try a kubectl command like this below:
$ kubectl get po -A -o wide | grep go-grpc-greeter-server
+ gRPC - NGINX Ingress Controller
You're also responsible for provisioning an SSL certificate for the ingress. So you need to have a valid SSL certificate, deployed as a Kubernetes secret of type tls, in the same namespace as the gRPC application.
Step 1: Create a Kubernetes Deployment for gRPC app ¶
Make sure your gRPC application pod is running and listening for connections. For example you can try a kubectl command like this below:
$ kubectl get po -A -o wide | grep go-grpc-greeter-server
If you have a gRPC app deployed in your cluster, then skip further notes in this Step 1, and continue from Step 2 below.
To create a container image for this app, you can use this Dockerfile.
If you use the Dockerfile mentioned above, to create a image, then given below is an example of a Kubernetes manifest, to create a deployment resource, that uses that image. If needed, then edit this manifest to suit your needs. Assuming the name of this yaml file is deployment.go-grpc-greeter-server.yaml ;
If you are developing public gRPC endpoints, check out https://proto.stack.build, a protocol buffer / gRPC build service that can use to help make it easier for your users to consume your API.
See also the specific GRPC settings of NGINX: https://nginx.org/en/docs/http/ngx_http_grpc_module.html
If your server does only response streaming and you expect a stream to be open longer than 60 seconds, you will have to change the grpc_read_timeout to accommodate for this.
If your service does only request streaming and you expect a stream to be open longer than 60 seconds, you have to change the grpc_send_timeout and the client_body_timeout.
If you do both response and request streaming with an open stream longer than 60 seconds, you have to change all three timeouts: grpc_read_timeout, grpc_send_timeout and client_body_timeout.
Values for the timeouts must be specified as e.g. "1200s".
On the most recent versions of nginx-ingress, changing these timeouts requires using the nginx.ingress.kubernetes.io/server-snippet annotation. There are plans for future releases to allow using the Kubernetes annotations to define each timeout separately.
You need a TLS cert and a test HTTP service for this example. You will also need to make sure your Ingress targets exactly one Ingress controller by specifying the ingress.class annotation, and that you have an ingress controller running in your cluster.
Since instances of the nginx controller actually run on nodes in your cluster, by default nginx Ingresses will only get static IPs if your cloudprovider supports static IP assignments to nodes. On GKE/GCE for example, even though nodes get static IPs, the IPs are not retained across upgrade.
To acquire a static IP for the nginx ingress controller, simply put it behind a Service of Type=LoadBalancer.
First, create a loadbalancer Service and wait for it to acquire an IP
You need a TLS cert and a test HTTP service for this example. You will also need to make sure your Ingress targets exactly one Ingress controller by specifying the ingress.class annotation, and that you have an ingress controller running in your cluster.
Since instances of the nginx controller actually run on nodes in your cluster, by default nginx Ingresses will only get static IPs if your cloudprovider supports static IP assignments to nodes. On GKE/GCE for example, even though nodes get static IPs, the IPs are not retained across upgrade.
To acquire a static IP for the ingress-nginx-controller, simply put it behind a Service of Type=LoadBalancer.
First, create a loadbalancer Service and wait for it to acquire an IP
$ kubectl create -f static-ip-svc.yaml
+service "ingress-nginx-lb" created
-$ kubectl get svc nginx-ingress-lb
+$ kubectl get svc ingress-nginx-lb
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
-nginx-ingress-lb 10.0.138.113 104.154.109.191 80:31457/TCP,443:32240/TCP 15m
-
then, update the ingress controller so it adopts the static IP of the Service by passing the --publish-service flag (the example yaml used in the next step already has it set to "nginx-ingress-lb").
$ kubectl create -f nginx-ingress-controller.yaml
-deployment "nginx-ingress-controller" created
-
then, update the ingress controller so it adopts the static IP of the Service by passing the --publish-service flag (the example yaml used in the next step already has it set to "ingress-nginx-lb").
$ kubectl create -f ingress-nginx-controller.yaml
+deployment "ingress-nginx-controller" created
+
$ kubectl delete ing ingress-nginx
+ingress "ingress-nginx" deleted
-$ kubectl create -f nginx-ingress.yaml
-ingress "nginx-ingress" created
+$ kubectl create -f ingress-nginx.yaml
+ingress "ingress-nginx" created
-$ kubectl get ing nginx-ingress
+$ kubectl get ing ingress-nginx
NAME HOSTS ADDRESS PORTS AGE
-nginx-ingress * 104.154.109.191 80, 443 13m
-
Note that unlike the GCE Ingress, the same loadbalancer IP is shared amongst all Ingresses, because all requests are proxied through the same set of nginx controllers.
Note that unlike the GCE Ingress, the same loadbalancer IP is shared amongst all Ingresses, because all requests are proxied through the same set of nginx controllers.
and promote the IP to static (promotion works differently for cloudproviders, provided example is for GKE/GCE) `
$ gcloud compute addresses create ingress-nginx-lb --addresses 104.154.109.191 --region us-central1
+Created [https://www.googleapis.com/compute/v1/projects/kubernetesdev/regions/us-central1/addresses/ingress-nginx-lb].---address: 104.154.109.191creationTimestamp: '2017-01-31T16:34:50.089-08:00'description: ''id: '5208037144487826373'kind: compute#address
-name: nginx-ingress-lb
+name: ingress-nginx-lbregion: us-central1
-selfLink: https://www.googleapis.com/compute/v1/projects/kubernetesdev/regions/us-central1/addresses/nginx-ingress-lb
+selfLink: https://www.googleapis.com/compute/v1/projects/kubernetesdev/regions/us-central1/addresses/ingress-nginx-lbstatus: IN_USEusers:- us-central1/forwardingRules/a09f6913ae80e11e6a8c542010af0000
diff --git a/examples/static-ip/nginx-ingress-controller.yaml b/examples/static-ip/nginx-ingress-controller.yaml
index 30885ec54..61c3a8f7f 100644
--- a/examples/static-ip/nginx-ingress-controller.yaml
+++ b/examples/static-ip/nginx-ingress-controller.yaml
@@ -1,7 +1,7 @@
apiVersion: apps/v1
kind: Deployment
metadata:
- name: nginx-ingress-controller
+ name: ingress-nginx-controller
labels:
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
@@ -18,14 +18,14 @@ spec:
app.kubernetes.io/part-of: ingress-nginx
spec:
# hostNetwork makes it possible to use ipv6 and to preserve the source IP correctly regardless of docker configuration
- # however, it is not a hard dependency of the nginx-ingress-controller itself and it may cause issues if port 10254 already is taken on the host
+ # however, it is not a hard dependency of the ingress-nginx-controller itself and it may cause issues if port 10254 already is taken on the host
# that said, since hostPort is broken on CNI (https://github.com/kubernetes/kubernetes/issues/31307) we have to use hostNetwork where CNI is used
# like with kubeadm
# hostNetwork: true
terminationGracePeriodSeconds: 60
containers:
- - image: quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.33.0
- name: nginx-ingress-controller
+ - image: k8s.gcr.io/ingress-nginx/controller:v1.0.5
+ name: controller
readinessProbe:
httpGet:
path: /healthz
@@ -54,4 +54,4 @@ spec:
fieldPath: metadata.namespace
args:
- /nginx-ingress-controller
- - --publish-service=$(POD_NAMESPACE)/nginx-ingress-lb
+ - --publish-service=$(POD_NAMESPACE)/ingress-nginx-lb
diff --git a/examples/static-ip/static-ip-svc.yaml b/examples/static-ip/static-ip-svc.yaml
index b64cf96cb..ee803951f 100644
--- a/examples/static-ip/static-ip-svc.yaml
+++ b/examples/static-ip/static-ip-svc.yaml
@@ -2,7 +2,7 @@
apiVersion: v1
kind: Service
metadata:
- name: nginx-ingress-lb
+ name: ingress-nginx-lb
labels:
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
@@ -18,6 +18,6 @@ spec:
name: https
targetPort: 443
selector:
- # Selects nginx-ingress-controller pods
+ # Selects ingress-nginx-controller pods
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
diff --git a/examples/tls-termination/index.html b/examples/tls-termination/index.html
index 35ec158b0..d1a80cbbb 100644
--- a/examples/tls-termination/index.html
+++ b/examples/tls-termination/index.html
@@ -39,10 +39,10 @@
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 /
+ 7s 7s 1 {ingress-nginx-controller } Normal CREATE default/nginx-test
+ 7s 7s 1 {ingress-nginx-controller } Normal UPDATE default/nginx-test
+ 7s 7s 1 {ingress-nginx-controller } Normal CREATE ip: 104.198.183.6
+ 7s 7s 1 {ingress-nginx-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
diff --git a/kubectl-plugin/index.html b/kubectl-plugin/index.html
index 616a90a34..0ce56f460 100644
--- a/kubectl-plugin/index.html
+++ b/kubectl-plugin/index.html
@@ -44,7 +44,7 @@ Do not move it without providing redirects.
--user string The name of the kubeconfig user to useUse "ingress-nginx [command] --help" for more information about a command.
-
Every subcommand supports the basic kubectl configuration flags like --namespace, --context, --client-key and so on.
Subcommands that act on a particular ingress-nginx pod (backends, certs, conf, exec, general, logs, ssh), support the --deployment <deployment> and --pod <pod> flags to select either a pod from a deployment with the given name, or a pod with the given name. The --deployment flag defaults to nginx-ingress-controller.
Subcommands that inspect resources (ingresses, lint) support the --all-namespaces flag, which causes them to inspect resources in every namespace.
Every subcommand supports the basic kubectl configuration flags like --namespace, --context, --client-key and so on.
Subcommands that act on a particular ingress-nginx pod (backends, certs, conf, exec, general, logs, ssh), support the --deployment <deployment> and --pod <pod> flags to select either a pod from a deployment with the given name, or a pod with the given name. The --deployment flag defaults to ingress-nginx-controller.
Subcommands that inspect resources (ingresses, lint) support the --all-namespaces flag, which causes them to inspect resources in every namespace.
kubectl ingress-nginx ssh is exactly the same as kubectl ingress-nginx exec -it -- /bin/bash. Use it when you want to quickly be dropped into a shell inside a running ingress-nginx container.