diff --git a/404.html b/404.html index 43d06f881..c079904ee 100644 --- a/404.html +++ b/404.html @@ -911,6 +911,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/deploy/index.html b/deploy/index.html index fd6d0f175..d737e0b1f 100644 --- a/deploy/index.html +++ b/deploy/index.html @@ -1094,6 +1094,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/deploy/rbac/index.html b/deploy/rbac/index.html index 6b588f8d6..236606f84 100644 --- a/deploy/rbac/index.html +++ b/deploy/rbac/index.html @@ -998,6 +998,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/deploy/upgrade/index.html b/deploy/upgrade/index.html index 892a9f50c..9bb7c1d84 100644 --- a/deploy/upgrade/index.html +++ b/deploy/upgrade/index.html @@ -964,6 +964,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/development/index.html b/development/index.html index 6d03de6a8..59bc82962 100644 --- a/development/index.html +++ b/development/index.html @@ -915,6 +915,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/examples/PREREQUISITES/index.html b/examples/PREREQUISITES/index.html index c5bfff8c3..e79183481 100644 --- a/examples/PREREQUISITES/index.html +++ b/examples/PREREQUISITES/index.html @@ -998,6 +998,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/examples/affinity/cookie/README/index.html b/examples/affinity/cookie/README/index.html index 860bf5de2..14c271507 100644 --- a/examples/affinity/cookie/README/index.html +++ b/examples/affinity/cookie/README/index.html @@ -964,6 +964,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/examples/auth/basic/README/index.html b/examples/auth/basic/README/index.html index 9a9646212..cd265c7d5 100644 --- a/examples/auth/basic/README/index.html +++ b/examples/auth/basic/README/index.html @@ -930,6 +930,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/examples/auth/client-certs/README/index.html b/examples/auth/client-certs/README/index.html index 950d16d19..1b8a63fad 100644 --- a/examples/auth/client-certs/README/index.html +++ b/examples/auth/client-certs/README/index.html @@ -959,6 +959,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/examples/auth/external-auth/README/index.html b/examples/auth/external-auth/README/index.html index e9d91213c..1bb5922ca 100644 --- a/examples/auth/external-auth/README/index.html +++ b/examples/auth/external-auth/README/index.html @@ -959,6 +959,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/examples/auth/oauth-external-auth/README/index.html b/examples/auth/oauth-external-auth/README/index.html index b6b0a011f..6fb981630 100644 --- a/examples/auth/oauth-external-auth/README/index.html +++ b/examples/auth/oauth-external-auth/README/index.html @@ -986,6 +986,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/examples/customization/configuration-snippets/README/index.html b/examples/customization/configuration-snippets/README/index.html index 9ae48879b..27853b3a8 100644 --- a/examples/customization/configuration-snippets/README/index.html +++ b/examples/customization/configuration-snippets/README/index.html @@ -966,6 +966,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/examples/customization/custom-configuration/README/index.html b/examples/customization/custom-configuration/README/index.html index 225dd91bb..e4b8af111 100644 --- a/examples/customization/custom-configuration/README/index.html +++ b/examples/customization/custom-configuration/README/index.html @@ -930,6 +930,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/examples/customization/custom-errors/README/index.html b/examples/customization/custom-errors/README/index.html index 1721dfa3d..c7ea694f7 100644 --- a/examples/customization/custom-errors/README/index.html +++ b/examples/customization/custom-errors/README/index.html @@ -930,6 +930,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/examples/customization/custom-headers/README/index.html b/examples/customization/custom-headers/README/index.html index d652e1a11..c47d2435d 100644 --- a/examples/customization/custom-headers/README/index.html +++ b/examples/customization/custom-headers/README/index.html @@ -959,6 +959,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/examples/customization/custom-upstream-check/README/index.html b/examples/customization/custom-upstream-check/README/index.html index 60b0fde9a..ed5593e80 100644 --- a/examples/customization/custom-upstream-check/README/index.html +++ b/examples/customization/custom-upstream-check/README/index.html @@ -930,6 +930,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/examples/customization/custom-vts-metrics-prometheus/README/index.html b/examples/customization/custom-vts-metrics-prometheus/README/index.html index 1fec28c8e..0378d517f 100644 --- a/examples/customization/custom-vts-metrics-prometheus/README/index.html +++ b/examples/customization/custom-vts-metrics-prometheus/README/index.html @@ -1021,6 +1021,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/examples/customization/external-auth-headers/README/index.html b/examples/customization/external-auth-headers/README/index.html index 61021fcf5..35dfebfde 100644 --- a/examples/customization/external-auth-headers/README/index.html +++ b/examples/customization/external-auth-headers/README/index.html @@ -930,6 +930,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/examples/customization/ssl-dh-param/README/index.html b/examples/customization/ssl-dh-param/README/index.html index df2e00344..4b809a74e 100644 --- a/examples/customization/ssl-dh-param/README/index.html +++ b/examples/customization/ssl-dh-param/README/index.html @@ -973,6 +973,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/examples/customization/sysctl/README/index.html b/examples/customization/sysctl/README/index.html index 935cb5766..fc2b3bcab 100644 --- a/examples/customization/sysctl/README/index.html +++ b/examples/customization/sysctl/README/index.html @@ -930,6 +930,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/examples/docker-registry/README/index.html b/examples/docker-registry/README/index.html index 7135d6dce..c2e23da91 100644 --- a/examples/docker-registry/README/index.html +++ b/examples/docker-registry/README/index.html @@ -984,6 +984,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination @@ -1217,13 +1229,13 @@ -
    + Skip to content + + + +
    + +
    + +
    + + + + + + + + + + +
    +
    + + +
    +
    +
    + +
    +
    +
    + + +
    +
    +
    + + +
    +
    +
    + + +
    +
    + + + + + +

    gRPC

    +

    This example demonstrates how to route traffic to a gRPC service through the +nginx controller.

    +

    Prerequisites

    +
      +
    1. You have a kubernetes cluster running.
      2. +
    2. You have a domain name such as example.com that is configured to route + traffic to the ingress controller. Replace references to + fortune-teller.stack.build (the domain name used in this example) to your + own domain name (you're also responsible for provisioning an SSL certificate + for the ingress).
      3. +
    3. You have the nginx-ingress controller installed in typical fashion (must be + at least + quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.13.0 + for grpc support.
      4. +
    4. You have a backend application running a gRPC server and listening for TCP + traffic. If you prefer, you can use the + fortune-teller + application provided here as an example.
      5. +
    +

    Step 1: kubernetes Deployment

    +
    $ kubectl create -f app.yaml
+
    + + +

    This is a standard kubernetes deployment object. It is running a grpc service +listening on port 50051.

    +

    The sample application +fortune-teller-app +is a grpc server implemented in go. Here's the stripped-down implementation:

    +
    func main() {
+    grpcServer := grpc.NewServer()
+    fortune.RegisterFortuneTellerServer(grpcServer, &FortuneTeller{})
+    lis, _ := net.Listen("tcp", ":50051")
+    grpcServer.Serve(lis)
+}
+
    + + +

    The takeaway is that we are not doing any TLS configuration on the server (as we +are terminating TLS at the ingress level, grpc traffic will travel unencrypted +inside the cluster and arrive "insecure").

    +

    For your own application you may or may not want to do this. If you prefer to +forward encrypted traffic to your POD and terminate TLS at the gRPC server +itself, add the ingress annotation nginx.ingress.kubernetes.io/secure-backends:"true".

    +

    Step 2: the kubernetes Service

    +
    $ kubectl create -f svc.yaml
+
    + + +

    Here we have a typical service. Nothing special, just routing traffic to the +backend application on port 50051.

    +

    Step 3: the kubernetes Ingress

    +
    $ kubectl create -f ingress.yaml
+
    + + +

    A few things to note:

    +
      +
    1. We've tagged the ingress with the annotation + nginx.ingress.kubernetes.io/grpc-backend: "true". This is the magic + ingredient that sets up the appropriate nginx configuration to route http/2 + traffic to our service.
      2. +
    2. We're terminating TLS at the ingress and have configured an SSL certificate + fortune-teller.stack.build. The ingress matches traffic arriving as + https://fortune-teller.stack.build:443 and routes unencrypted messages to + our kubernetes service.
      3. +
    +

    Step 4: test the connection

    +

    Once we've applied our configuration to kubernetes, it's time to test that we +can actually talk to the backend. To do this, we'll use the +grpcurl utility:

    +
    $ grpcurl fortune-teller.stack.build:443 build.stack.fortune.FortuneTeller/Predict
+{
+  "message": "Let us endeavor so to live that when we come to die even the undertaker will be sorry.\n\t\t-- Mark Twain, \"Pudd'nhead Wilson's Calendar\""
+}
+
    + + +

    Debugging Hints

    +
      +
    1. Obviously, watch the logs on your app.
      2. +
    2. Watch the logs for the nginx-ingress-controller (increasing verbosity as + needed).
      3. +
    3. Double-check your address and ports.
      4. +
    4. Set the GODEBUG=http2debug=2 environment variable to get detailed http/2 + logging on the client and/or server.
      5. +
    5. Study RFC 7540 (http/2) https://tools.ietf.org/html/rfc7540.
      6. +
    +
    +

    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.

    +
    + + + + + + + + + +
    +
    +
    +
    + + + + +
    + + + + + + + + + + + + + \ No newline at end of file diff --git a/examples/grpc/app.yaml b/examples/grpc/app.yaml new file mode 100644 index 000000000..04f1932d7 --- /dev/null +++ b/examples/grpc/app.yaml @@ -0,0 +1,20 @@ +apiVersion: extensions/v1beta1 +kind: Deployment +metadata: + name: fortune-teller-app + labels: + k8s-app: fortune-teller-app + namespace: default +spec: + replicas: 1 + template: + metadata: + labels: + k8s-app: fortune-teller-app + spec: + containers: + - name: fortune-teller-app + image: quay.io/kubernetes-ingress-controller/grpc-fortune-teller:0.1 + ports: + - containerPort: 50051 + name: grpc diff --git a/examples/grpc/cert.yaml b/examples/grpc/cert.yaml new file mode 100644 index 000000000..562c30313 --- /dev/null +++ b/examples/grpc/cert.yaml @@ -0,0 +1,7 @@ +apiVersion: "stable.k8s.psg.io/v1" +kind: "Certificate" +metadata: + name: fortune-teller.stack.build + namespace: default +spec: + domain: "fortune-teller.stack.build" diff --git a/examples/grpc/ingress.yaml b/examples/grpc/ingress.yaml new file mode 100644 index 000000000..f03559883 --- /dev/null +++ b/examples/grpc/ingress.yaml @@ -0,0 +1,21 @@ +apiVersion: extensions/v1beta1 +kind: Ingress +metadata: + annotations: + kubernetes.io/ingress.class: "nginx" + nginx.ingress.kubernetes.io/ssl-redirect: "true" + nginx.ingress.kubernetes.io/grpc-backend: "true" + name: fortune-ingress + namespace: default +spec: + rules: + - host: fortune-teller.stack.build + http: + paths: + - backend: + serviceName: fortune-teller-service + servicePort: grpc + tls: + - secretName: fortune-teller.stack.build + hosts: + - fortune-teller.stack.build diff --git a/examples/grpc/svc.yaml b/examples/grpc/svc.yaml new file mode 100644 index 000000000..7bfa789fd --- /dev/null +++ b/examples/grpc/svc.yaml @@ -0,0 +1,12 @@ +apiVersion: v1 +kind: Service +metadata: + name: fortune-teller-service + namespace: default +spec: + selector: + k8s-app: fortune-teller-app + ports: + - port: 50051 + targetPort: 50051 + name: grpc diff --git a/examples/index.html b/examples/index.html index 5a033e1df..61b9b23a8 100644 --- a/examples/index.html +++ b/examples/index.html @@ -928,6 +928,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/examples/multi-tls/README/index.html b/examples/multi-tls/README/index.html index df567b8e5..b1c28de2c 100644 --- a/examples/multi-tls/README/index.html +++ b/examples/multi-tls/README/index.html @@ -918,6 +918,18 @@ + +
  • + + gRPC + +
    • + + + + + + @@ -1154,7 +1166,7 @@
    diff --git a/examples/rewrite/README/index.html b/examples/rewrite/README/index.html index e088a24d4..ab049ba07 100644 --- a/examples/rewrite/README/index.html +++ b/examples/rewrite/README/index.html @@ -919,6 +919,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/examples/static-ip/README/index.html b/examples/static-ip/README/index.html index abdd7aebc..9a80789ab 100644 --- a/examples/static-ip/README/index.html +++ b/examples/static-ip/README/index.html @@ -919,6 +919,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/examples/tls-termination/README/index.html b/examples/tls-termination/README/index.html index b362a21ea..c9d8c2051 100644 --- a/examples/tls-termination/README/index.html +++ b/examples/tls-termination/README/index.html @@ -919,6 +919,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/index.html b/index.html index 76e584405..9da90da31 100644 --- a/index.html +++ b/index.html @@ -953,6 +953,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/ingress-controller-catalog/index.html b/ingress-controller-catalog/index.html index dd1445fa7..b900eba5c 100644 --- a/ingress-controller-catalog/index.html +++ b/ingress-controller-catalog/index.html @@ -915,6 +915,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/search/search_index.json b/search/search_index.json index 3ff63d8b6..df0b5b3db 100644 --- a/search/search_index.json +++ b/search/search_index.json @@ -1057,12 +1057,12 @@ }, { "location": "/user-guide/multiple-ingress/", - "text": "Multiple Ingress controllers\n\u00b6\n\n\nIf you're running multiple ingress controllers, or running on a cloud provider that natively handles ingress such as GKE,\nyou need to specify the annotation \nkubernetes.io/ingress.class: \"nginx\"\n in all ingresses that you would like the ingress-nginx controller to claim.\n\n\nFor instance,\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\nTo reiterate, setting the annotation to any value which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress.\nIf you are only running a single NGINX ingress controller, this can be achieved by setting the annotation 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.\n\n\n\n\nImportant\n\n\nDeploying multiple Ingress controllers and not specifying a class annotation will\nresult in both or all controllers fighting to satisfy the Ingress, and all of them\nupdating the Ingress status field in confusing ways.\n\n\n\n\nMultiple ingress-nginx controllers\n\u00b6\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).\nTo do this, the option \n--ingress-class\n must be changed to a value unique for the cluster within the definition of the replication controller.\nHere 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-ingress-internal-controller\n\n \nargs\n:\n\n \n-\n \n/nginx-ingress-controller\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'", + "text": "Multiple Ingress controllers\n\u00b6\n\n\nIf you're running multiple ingress controllers, or running on a cloud provider that natively handles ingress such as GKE,\nyou need to specify the annotation \nkubernetes.io/ingress.class: \"nginx\"\n in all ingresses that you would like the ingress-nginx controller to claim.\n\n\nFor instance,\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\nTo reiterate, setting the annotation to any value which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress.\nIf you are only running a single NGINX ingress controller, this can be achieved by setting the annotation 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.\n\n\nMultiple ingress-nginx controllers\n\u00b6\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).\nTo do this, the option \n--ingress-class\n must be changed to a value unique for the cluster within the definition of the replication controller.\nHere 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-ingress-internal-controller\n\n \nargs\n:\n\n \n-\n \n/nginx-ingress-controller\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\n!!! important\n\u00b6\n\n\nDeploying multiple Ingress controllers, of different types (e.g., \ningress-nginx\n & \ngce\n), and not specifying a class annotation will\nresult in both or all controllers fighting to satisfy the Ingress, and all of them racing to update Ingress status field in confusing ways.\n\n\nWhen running multiple ingress-nginx controllers, it will only process an unset class annotation if one of the controllers uses the default\n \n--ingress-class\n value (see \nIsValid\n method in \ninternal/ingress/annotations/class/main.go\n), otherwise the class annotation become required.", "title": "Multiple Ingress controllers" }, { "location": "/user-guide/multiple-ingress/#multiple-ingress-controllers", - "text": "If you're running multiple ingress controllers, or running on a cloud provider that natively handles ingress such as GKE,\nyou need to specify the annotation kubernetes.io/ingress.class: \"nginx\" in all ingresses that you would like the ingress-nginx controller to claim. For instance, 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. To reiterate, setting the annotation to any value which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress.\nIf you are only running a single NGINX ingress controller, this can be achieved by setting the annotation 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. Important Deploying multiple Ingress controllers and not specifying a class annotation will\nresult in both or all controllers fighting to satisfy the Ingress, and all of them\nupdating the Ingress status field in confusing ways.", + "text": "If you're running multiple ingress controllers, or running on a cloud provider that natively handles ingress such as GKE,\nyou need to specify the annotation kubernetes.io/ingress.class: \"nginx\" in all ingresses that you would like the ingress-nginx controller to claim. For instance, 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. To reiterate, setting the annotation to any value which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress.\nIf you are only running a single NGINX ingress controller, this can be achieved by setting the annotation 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": "Multiple Ingress controllers" }, { @@ -1070,6 +1070,11 @@ "text": "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).\nTo do this, the option --ingress-class must be changed to a value unique for the cluster within the definition of the replication controller.\nHere 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": "Multiple ingress-nginx controllers" }, + { + "location": "/user-guide/multiple-ingress/#important", + "text": "Deploying multiple Ingress controllers, of different types (e.g., ingress-nginx & gce ), and not specifying a class annotation will\nresult in both or all controllers fighting to satisfy the Ingress, and all of them racing to update Ingress status field in confusing ways. When running multiple ingress-nginx controllers, it will only process an unset class annotation if one of the controllers uses the default\n --ingress-class value (see IsValid method in internal/ingress/annotations/class/main.go ), otherwise the class annotation become required.", + "title": "!!! important" + }, { "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", @@ -1485,6 +1490,46 @@ "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./ubuntu:16.04` docker push `registry./ubuntu:16.04` Please replace registry. with your domain.", "title": "Testing" }, + { + "location": "/examples/grpc/README/", + "text": "gRPC\n\u00b6\n\n\nThis example demonstrates how to route traffic to a gRPC service through the\nnginx controller.\n\n\nPrerequisites\n\u00b6\n\n\n\n\nYou have a kubernetes cluster running.\n\n\nYou have a domain name such as \nexample.com\n that is configured to route\n traffic to the ingress controller. Replace references to\n \nfortune-teller.stack.build\n (the domain name used in this example) to your\n own domain name (you're also responsible for provisioning an SSL certificate\n for the ingress).\n\n\nYou have the nginx-ingress controller installed in typical fashion (must be\n at least\n \nquay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.13.0\n\n for grpc support.\n\n\nYou have a backend application running a gRPC server and listening for TCP\n traffic. If you prefer, you can use the\n \nfortune-teller\n\n application provided here as an example. \n\n\n\n\nStep 1: kubernetes \nDeployment\n\u00b6\n\n\n$ kubectl create -f app.yaml\n\n\n\n\n\nThis is a standard kubernetes deployment object. It is running a grpc service\nlistening on port \n50051\n.\n\n\nThe sample application\n\nfortune-teller-app\n\nis a grpc server implemented in go. Here's the stripped-down implementation:\n\n\nfunc\n \nmain\n()\n \n{\n\n \ngrpcServer\n \n:=\n \ngrpc\n.\nNewServer\n()\n\n \nfortune\n.\nRegisterFortuneTellerServer\n(\ngrpcServer\n,\n \n&\nFortuneTeller\n{})\n\n \nlis\n,\n \n_\n \n:=\n \nnet\n.\nListen\n(\n\"tcp\"\n,\n \n\":50051\"\n)\n\n \ngrpcServer\n.\nServe\n(\nlis\n)\n\n\n}\n\n\n\n\n\n\nThe takeaway is that we are not doing any TLS configuration on the server (as we\nare terminating TLS at the ingress level, grpc traffic will travel unencrypted\ninside the cluster and arrive \"insecure\").\n\n\nFor your own application you may or may not want to do this. If you prefer to\nforward encrypted traffic to your POD and terminate TLS at the gRPC server\nitself, add the ingress annotation \nnginx.ingress.kubernetes.io/secure-backends:\"true\"\n.\n\n\nStep 2: the kubernetes \nService\n\u00b6\n\n\n$ kubectl create -f svc.yaml\n\n\n\n\n\nHere we have a typical service. Nothing special, just routing traffic to the\nbackend application on port \n50051\n.\n\n\nStep 3: the kubernetes \nIngress\n\u00b6\n\n\n$ kubectl create -f ingress.yaml\n\n\n\n\n\nA few things to note:\n\n\n\n\nWe've tagged the ingress with the annotation\n \nnginx.ingress.kubernetes.io/grpc-backend: \"true\"\n. This is the magic\n ingredient that sets up the appropriate nginx configuration to route http/2\n traffic to our service.\n\n\nWe're terminating TLS at the ingress and have configured an SSL certificate\n \nfortune-teller.stack.build\n. The ingress matches traffic arriving as\n \nhttps://fortune-teller.stack.build:443\n and routes unencrypted messages to\n our kubernetes service.\n\n\n\n\nStep 4: test the connection\n\u00b6\n\n\nOnce we've applied our configuration to kubernetes, it's time to test that we\ncan actually talk to the backend. To do this, we'll use the\n\ngrpcurl\n utility:\n\n\n$ grpcurl fortune-teller.stack.build:443 build.stack.fortune.FortuneTeller/Predict\n\n{\n\n \n\"message\"\n: \n\"Let us endeavor so to live that when we come to die even the undertaker will be sorry.\\n\\t\\t-- Mark Twain, \\\"Pudd'nhead Wilson's Calendar\\\"\"\n\n\n}\n\n\n\n\n\n\nDebugging Hints\n\u00b6\n\n\n\n\nObviously, watch the logs on your app.\n\n\nWatch the logs for the nginx-ingress-controller (increasing verbosity as\n needed).\n\n\nDouble-check your address and ports.\n\n\nSet the \nGODEBUG=http2debug=2\n environment variable to get detailed http/2\n logging on the client and/or server.\n\n\nStudy RFC 7540 (http/2) \nhttps://tools.ietf.org/html/rfc7540\n.\n\n\n\n\n\n\nIf you are developing public gRPC endpoints, check out\nhttps://proto.stack.build, a protocol buffer / gRPC build service that can use\nto help make it easier for your users to consume your API.", + "title": "gRPC" + }, + { + "location": "/examples/grpc/README/#grpc", + "text": "This example demonstrates how to route traffic to a gRPC service through the\nnginx controller.", + "title": "gRPC" + }, + { + "location": "/examples/grpc/README/#prerequisites", + "text": "You have a kubernetes cluster running. You have a domain name such as example.com that is configured to route\n traffic to the ingress controller. Replace references to\n fortune-teller.stack.build (the domain name used in this example) to your\n own domain name (you're also responsible for provisioning an SSL certificate\n for the ingress). You have the nginx-ingress controller installed in typical fashion (must be\n at least\n quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.13.0 \n for grpc support. You have a backend application running a gRPC server and listening for TCP\n traffic. If you prefer, you can use the\n fortune-teller \n application provided here as an example.", + "title": "Prerequisites" + }, + { + "location": "/examples/grpc/README/#step-1-kubernetes-deployment", + "text": "$ kubectl create -f app.yaml This is a standard kubernetes deployment object. It is running a grpc service\nlistening on port 50051 . The sample application fortune-teller-app \nis a grpc server implemented in go. Here's the stripped-down implementation: func main () { \n grpcServer := grpc . NewServer () \n fortune . RegisterFortuneTellerServer ( grpcServer , & FortuneTeller {}) \n lis , _ := net . Listen ( \"tcp\" , \":50051\" ) \n grpcServer . Serve ( lis ) } The takeaway is that we are not doing any TLS configuration on the server (as we\nare terminating TLS at the ingress level, grpc traffic will travel unencrypted\ninside the cluster and arrive \"insecure\"). For your own application you may or may not want to do this. If you prefer to\nforward encrypted traffic to your POD and terminate TLS at the gRPC server\nitself, add the ingress annotation nginx.ingress.kubernetes.io/secure-backends:\"true\" .", + "title": "Step 1: kubernetes Deployment" + }, + { + "location": "/examples/grpc/README/#step-2-the-kubernetes-service", + "text": "$ kubectl create -f svc.yaml Here we have a typical service. Nothing special, just routing traffic to the\nbackend application on port 50051 .", + "title": "Step 2: the kubernetes Service" + }, + { + "location": "/examples/grpc/README/#step-3-the-kubernetes-ingress", + "text": "$ kubectl create -f ingress.yaml A few things to note: We've tagged the ingress with the annotation\n nginx.ingress.kubernetes.io/grpc-backend: \"true\" . This is the magic\n ingredient that sets up the appropriate nginx configuration to route http/2\n traffic to our service. We're terminating TLS at the ingress and have configured an SSL certificate\n fortune-teller.stack.build . The ingress matches traffic arriving as\n https://fortune-teller.stack.build:443 and routes unencrypted messages to\n our kubernetes service.", + "title": "Step 3: the kubernetes Ingress" + }, + { + "location": "/examples/grpc/README/#step-4-test-the-connection", + "text": "Once we've applied our configuration to kubernetes, it's time to test that we\ncan actually talk to the backend. To do this, we'll use the grpcurl utility: $ grpcurl fortune-teller.stack.build:443 build.stack.fortune.FortuneTeller/Predict { \n \"message\" : \"Let us endeavor so to live that when we come to die even the undertaker will be sorry.\\n\\t\\t-- Mark Twain, \\\"Pudd'nhead Wilson's Calendar\\\"\" }", + "title": "Step 4: test the connection" + }, + { + "location": "/examples/grpc/README/#debugging-hints", + "text": "Obviously, watch the logs on your app. Watch the logs for the nginx-ingress-controller (increasing verbosity as\n needed). Double-check your address and ports. Set the GODEBUG=http2debug=2 environment variable to get detailed http/2\n logging on the client and/or server. Study RFC 7540 (http/2) https://tools.ietf.org/html/rfc7540 . If you are developing public gRPC endpoints, check out\nhttps://proto.stack.build, a protocol buffer / gRPC build service that can use\nto help make it easier for your users to consume your API.", + "title": "Debugging Hints" + }, { "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\n\n\n\n\n\n\n\n\nWelcome to nginx on Debian!\n\n\n\n$\n curl \n104\n.154.30.67\n\ndefault backend - 404", diff --git a/sitemap.xml b/sitemap.xml index 53e521c8b..7b16fe2b9 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -4,7 +4,7 @@ / - 2018-05-03 + 2018-05-12 daily @@ -13,19 +13,19 @@ /deploy/ - 2018-05-03 + 2018-05-12 daily /deploy/rbac/ - 2018-05-03 + 2018-05-12 daily /deploy/upgrade/ - 2018-05-03 + 2018-05-12 daily @@ -41,55 +41,55 @@ /user-guide/cli-arguments/ - 2018-05-03 + 2018-05-12 daily /user-guide/custom-errors/ - 2018-05-03 + 2018-05-12 daily /user-guide/default-backend/ - 2018-05-03 + 2018-05-12 daily /user-guide/exposing-tcp-udp-services/ - 2018-05-03 + 2018-05-12 daily /user-guide/external-articles/ - 2018-05-03 + 2018-05-12 daily /user-guide/miscellaneous/ - 2018-05-03 + 2018-05-12 daily /user-guide/multiple-ingress/ - 2018-05-03 + 2018-05-12 daily /user-guide/nginx-status-page/ - 2018-05-03 + 2018-05-12 daily /user-guide/tls/ - 2018-05-03 + 2018-05-12 daily @@ -105,19 +105,19 @@ /examples/ - 2018-05-03 + 2018-05-12 daily /examples/PREREQUISITES/ - 2018-05-03 + 2018-05-12 daily /examples/affinity/cookie/README/ - 2018-05-03 + 2018-05-12 daily @@ -135,31 +135,37 @@ /examples/docker-registry/README/ - 2018-05-03 + 2018-05-12 + daily + + + + /examples/grpc/README/ + 2018-05-12 daily /examples/multi-tls/README/ - 2018-05-03 + 2018-05-12 daily /examples/rewrite/README/ - 2018-05-03 + 2018-05-12 daily /examples/static-ip/README/ - 2018-05-03 + 2018-05-12 daily /examples/tls-termination/README/ - 2018-05-03 + 2018-05-12 daily @@ -168,7 +174,7 @@ /development/ - 2018-05-03 + 2018-05-12 daily @@ -176,7 +182,7 @@ /ingress-controller-catalog/ - 2018-05-03 + 2018-05-12 daily @@ -184,7 +190,7 @@ /troubleshooting/ - 2018-05-03 + 2018-05-12 daily diff --git a/troubleshooting/index.html b/troubleshooting/index.html index f1bf35036..032ec1ead 100644 --- a/troubleshooting/index.html +++ b/troubleshooting/index.html @@ -915,6 +915,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/user-guide/cli-arguments/index.html b/user-guide/cli-arguments/index.html index 180b91a6c..6164a533e 100644 --- a/user-guide/cli-arguments/index.html +++ b/user-guide/cli-arguments/index.html @@ -928,6 +928,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/user-guide/custom-errors/index.html b/user-guide/custom-errors/index.html index 566617b9d..3d41908d3 100644 --- a/user-guide/custom-errors/index.html +++ b/user-guide/custom-errors/index.html @@ -928,6 +928,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/user-guide/default-backend/index.html b/user-guide/default-backend/index.html index 7f053b00e..cef1fa832 100644 --- a/user-guide/default-backend/index.html +++ b/user-guide/default-backend/index.html @@ -928,6 +928,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/user-guide/exposing-tcp-udp-services/index.html b/user-guide/exposing-tcp-udp-services/index.html index ed7c40d07..44d86f07b 100644 --- a/user-guide/exposing-tcp-udp-services/index.html +++ b/user-guide/exposing-tcp-udp-services/index.html @@ -928,6 +928,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/user-guide/external-articles/index.html b/user-guide/external-articles/index.html index adea47810..4f65aefc3 100644 --- a/user-guide/external-articles/index.html +++ b/user-guide/external-articles/index.html @@ -928,6 +928,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/user-guide/miscellaneous/index.html b/user-guide/miscellaneous/index.html index a47936ae0..3d07e9f72 100644 --- a/user-guide/miscellaneous/index.html +++ b/user-guide/miscellaneous/index.html @@ -999,6 +999,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/user-guide/multiple-ingress/index.html b/user-guide/multiple-ingress/index.html index 03958252e..cc9481a8e 100644 --- a/user-guide/multiple-ingress/index.html +++ b/user-guide/multiple-ingress/index.html @@ -593,6 +593,13 @@
    • +
  • + + !!! important + + +
    • + @@ -957,6 +964,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination @@ -1068,6 +1087,13 @@
    • +
  • + + !!! important + + +
    • + @@ -1110,12 +1136,6 @@ you need to specify the annotation kubernetes.io/ingres

    To reiterate, setting the annotation to any value which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress. If you are only running a single NGINX ingress controller, this can be achieved by setting the annotation 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.

    -
    -

    Important

    -

    Deploying multiple Ingress controllers and not specifying a class annotation will -result in both or all controllers fighting to satisfy the Ingress, and all of them -updating the Ingress status field in confusing ways.

    -

    Multiple ingress-nginx controllers

    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). To do this, the option --ingress-class must be changed to a value unique for the cluster within the definition of the replication controller. @@ -1132,6 +1152,13 @@ Here is a partial example:

    - '--ingress-class=nginx-internal' - '--configmap=ingress/nginx-ingress-internal-controller' + + +

    !!! important

    +

    Deploying multiple Ingress controllers, of different types (e.g., ingress-nginx & gce), and not specifying a class annotation will +result in both or all controllers fighting to satisfy the Ingress, and all of them racing to update Ingress status field in confusing ways.

    +

    When running multiple ingress-nginx controllers, it will only process an unset class annotation if one of the controllers uses the default + --ingress-class value (see IsValid method in internal/ingress/annotations/class/main.go), otherwise the class annotation become required.

    diff --git a/user-guide/nginx-configuration/annotations/index.html b/user-guide/nginx-configuration/annotations/index.html index 05fe73dc5..2ffb25aa1 100644 --- a/user-guide/nginx-configuration/annotations/index.html +++ b/user-guide/nginx-configuration/annotations/index.html @@ -1209,6 +1209,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/user-guide/nginx-configuration/configmap/index.html b/user-guide/nginx-configuration/configmap/index.html index 9b1105de7..b2bbf5e9b 100644 --- a/user-guide/nginx-configuration/configmap/index.html +++ b/user-guide/nginx-configuration/configmap/index.html @@ -1736,6 +1736,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/user-guide/nginx-configuration/custom-template/index.html b/user-guide/nginx-configuration/custom-template/index.html index 600b87049..8587b8e6f 100644 --- a/user-guide/nginx-configuration/custom-template/index.html +++ b/user-guide/nginx-configuration/custom-template/index.html @@ -930,6 +930,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/user-guide/nginx-configuration/index.html b/user-guide/nginx-configuration/index.html index 0789c4edb..eeff1e749 100644 --- a/user-guide/nginx-configuration/index.html +++ b/user-guide/nginx-configuration/index.html @@ -930,6 +930,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/user-guide/nginx-configuration/log-format/index.html b/user-guide/nginx-configuration/log-format/index.html index 7c7981671..a8e6a400c 100644 --- a/user-guide/nginx-configuration/log-format/index.html +++ b/user-guide/nginx-configuration/log-format/index.html @@ -930,6 +930,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/user-guide/nginx-status-page/index.html b/user-guide/nginx-status-page/index.html index fdc8353e7..36436165a 100644 --- a/user-guide/nginx-status-page/index.html +++ b/user-guide/nginx-status-page/index.html @@ -928,6 +928,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/user-guide/third-party-addons/modsecurity/index.html b/user-guide/third-party-addons/modsecurity/index.html index 23ed1ccbb..3d5bc531a 100644 --- a/user-guide/third-party-addons/modsecurity/index.html +++ b/user-guide/third-party-addons/modsecurity/index.html @@ -930,6 +930,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/user-guide/third-party-addons/opentracing/index.html b/user-guide/third-party-addons/opentracing/index.html index b88ecc577..7090ecd04 100644 --- a/user-guide/third-party-addons/opentracing/index.html +++ b/user-guide/third-party-addons/opentracing/index.html @@ -930,6 +930,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination diff --git a/user-guide/tls/index.html b/user-guide/tls/index.html index 919acf37c..1aec7c0b1 100644 --- a/user-guide/tls/index.html +++ b/user-guide/tls/index.html @@ -1012,6 +1012,18 @@ +
  • + + gRPC + +
    • + + + + + + +
  • Multi TLS certificate termination