From da8508011bb0bf5b8e3cd88393b5852cafec791f Mon Sep 17 00:00:00 2001 From: Jason Williams Date: Fri, 24 Feb 2023 14:27:42 -0800 Subject: [PATCH 01/25] Add NGINX Ingress controller with OSM tutorial --- docs/content/tutorials/nic-osm.md | 404 ++++++++++++++++++++++++++++++ 1 file changed, 404 insertions(+) create mode 100644 docs/content/tutorials/nic-osm.md diff --git a/docs/content/tutorials/nic-osm.md b/docs/content/tutorials/nic-osm.md new file mode 100644 index 0000000000..e3386266c2 --- /dev/null +++ b/docs/content/tutorials/nic-osm.md @@ -0,0 +1,404 @@ +## This document outlines how to integrate F5 NGINX Ingress Controller with Open Service Mesh (OSM) + +Open Service Mesh will work with both versions of [F5 NGINX Ingress controller](https://github.com/nginxinc/kubernetes-ingress): the free as well as the NGINX Plus versions. + +Below is a link to the official F5 NGINX Ingress controller documentation. +[F5 NGINX Ingress controller](https://docs.nginx.com/nginx-ingress-controller/) + +# Integrating NGINX Ingress Controller with Open Service Mesh + +There are two ways to integrate the NGINX Ingress Controller with Open Service Mesh (OSM): + +1. Using the Open Service Mesh `ingressBackend` "proxy" feature. +2. Injecting an envoy sidecar directly with NGINX Ingress Controller. + +## Using The Open Service Mesh `ingressBackend` "proxy" Feature + +Install OSM into cluster. +By running the following command, you will install OSM into the cluster with the mesh name `osm-nginx` using the `osm-system` namespace. + +```bash +osm install --mesh-name osm-nginx --osm-namespace osm-system +``` + +Once OSM has been installed, this next command will mark the NGINX Ingress Controller as part of the OSM mesh, while also disabling sidecar injection. +*NOTE*: The nginx-ingress name can be created as part of the NGINX Ingress install process, or manually. It must be created before you "add" the namespace to nginx-ingress. + +```bash +osm namespace add nginx-ingress --mesh-name osm-nginx --disable-sidecar-injection +``` + +### Install a Test Application + +To test the integration, we will use the `httpbin` sample application from the [Ingress With Kubernetes NGINX Ingress Controller](https://release-v1-2.docs.openservicemesh.io/docs/demos/ingress_k8s_nginx/) guide. + +The following three commands will create the namespace for the application, add the namespace to OSM for monitoring, then install the application. + +```bash +kubectl create ns httpbin +osm namespace add httpbin --mesh-name osm-nginx +kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm-docs/release-v1.2/manifests/samples/httpbin/httpbin.yaml -n httpbin +``` + +### mTLS Setup + +To enable mTLS for NGINX Ingress Controller and OSM, you need to configure the `IngressBackend` API to use `https` as the backend protocol as and trigger OSM to issue a certificate. NGINX will use this certificate to proxy HTTPS connections to the TLS backends. The client certificate and certificate authority (CA) certificate will be stored in a Kubernetes secret that NGINX will use for authentication."* + +To begin, edit the `osm-mesh-config` resource: + +```bash +kubectl edit meshconfig osm-mesh-config -n osm-system +``` + +You will need to update under `certificate` to look like this: + +```yaml +spec: + certificate: + ingressGateway: + secret: + name: osm-nginx-client-cert + namespace: osm-system + subjectAltNames: + - nginx-ingress.nginx-ingress.cluster.local + validityDuration: 24h +``` + +This will generate a new client certificate (osm-nginx-client-cert) that NGINX Ingress controller will use for mTLS. +The *SAN*, `subjectAltNames`, is the following form: + +```bash +..cluster.local +``` + +With the above OSM mesh config changed, that secret will be created in the `osm-system` namespace. +There will also be the `osm-ca-bundle` secret as well, which is autogenerated by OSM. + +```bash +kubectl get secrets -n osm-system +NAME TYPE DATA AGE +osm-ca-bundle Opaque 2 37m +osm-nginx-client-cert kubernetes.io/tls 3 17m +``` + +Now, we need to "export" out these certificates in order to use them with NGINX Ingress Controller. + +```bash +kubectl get secret osm-ca-bundle -n osm-system -o yaml > osm-ca-bundle-secret.yaml +kubectl get secret osm-nginx-client-cert -n osm-system -o yaml > osm-nginx-client-cert.yaml +``` + + +We need to edit the two exported out .yaml files and change a few parts. + +Edit `osm-ca-bundle-secret.yaml` +Remove the `private.key` section under `data.` +Change the `namespace` field to your nginx-ingress location +Change the `type` to `type: nginx.org/ca` + +Updated file should look like the following. +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: osm-ca-bundle + namespace: nginx-ingress +type: nginx.org/ca +data: + ca.crt: +``` + +Edit `osm-nginx-client-cert.yaml` +Remove the `ca.crt` in the `data` section +Change the namespace to the nginx-ingress namespace. + +Updated file should look like the following. + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: osm-nginx-client-cert + namespace: nginx-ingress +type: kubernetes.io/tls +data: + tls.crt: + tls.key: +``` + +Then apply these two secrets to the cluster. + +```bash +kubectl apply -f osm-ca-bundle-secret.yaml +kubectl apply -f osm-nginx-client-cert.yaml + +``` +Ensure the secrets exisit in the `nginx-ingress` namespace: + +```bash +kubectl get secrets -n nginx-ingress +NAME TYPE DATA AGE +osm-nginx-client-cert kubernetes.io/tls 2 23m +osm-ca-bundle nginx.org/ca 1 23m +``` + +We now need to create our CRDs (virtualServer and policy). +Here is the `policy` resource that holds the mTLS information. +Make sure you apply the `policy` or the mTLS connection will not work. (required for virtualServer) + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: Policy +metadata: + name: osm-mtls + namespace: nginx-ingress +spec: + egressMTLS: + tlsSecret: osm-nginx-client-cert + trustedCertSecret: osm-ca-bundle + verifyDepth: 2 + verifyServer: on + sslName: httpbin.httpbin.cluster.local +``` + +Here is an example `virtualServer` resource as well as the `ingressBackend`. + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: VirtualServer +metadata: + name: httpbin + namespace: httpbin +spec: + policies: + - name: osm-mtls + namespace: nginx-ingress + host: httpbin.example.com + tls: + secret: secret01 + upstreams: + - name: httpbin + service: httpbin + port: 14001 + tls: + enable: true + routes: + - path: / + action: + pass: httpbin +--- +kind: IngressBackend +apiVersion: policy.openservicemesh.io/v1alpha1 +metadata: + name: httpbin + namespace: httpbin +spec: + backends: + - name: httpbin + port: + number: 14001 # targetPort of httpbin service + protocol: https + tls: + skipClientCertValidation: false + sources: + - kind: Service + namespace: nginx-ingress + name: nginx-ingress + - kind: AuthenticatedPrincipal + name: nginx-ingress.nginx-ingress.cluster.local +``` + +Once these are applied, verify they are valid (virtualServer) and committed (ingressBackend): + +```bash +kubectl get vs,ingressbackend -A +NAMESPACE NAME STATE HOST IP PORTS AGE +httpbin virtualserver.k8s.nginx.org/httpbin Valid httpbin.example.com 26m + +NAMESPACE NAME STATUS +httpbin ingressbackend.policy.openservicemesh.io/httpbin committed +``` + +You can now send traffic through NGINX Ingress Controller with open service mesh. + +```bash +curl http://httpbin.example.com/get -v +* Trying 172.18.0.2:80... +* TCP_NODELAY set +* Connected to httpbin.example.com (172.18.0.2) port 80 (#0) +> GET /get HTTP/1.1 +> Host: httpbin.example.com +> User-Agent: curl/7.68.0 +> Accept: */* +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< Server: nginx/1.23.3 +< Date: Sat, 18 Feb 2023 22:41:27 GMT +< Content-Type: application/json +< Content-Length: 280 +< Connection: keep-alive +< access-control-allow-origin: * +< access-control-allow-credentials: true +< x-envoy-upstream-service-time: 1 +< +{ + "args": {}, + "headers": { + "Accept": "*/*", + "Host": "httpbin.example.com", + "User-Agent": "curl/7.68.0", + "X-Envoy-Internal": "true", + "X-Forwarded-Host": "httpbin.example.com" + }, + "origin": "172.18.0.1", + "url": "http://httpbin.example.com/get" +} +* Connection #0 to host httpbin.example.com left intact +``` + +# NGINX Ingress controller and OSM with sidecar injected + +First install OSM in the cluster + +```bash +osm install --mesh-name osm-nginx --osm-namespace osm-system +``` + +### Mark NGINX Ingress controller namespace for sidecar injection + +*NOTE:* Depending on how you install NGINX Ingress controller, you might need to create the `namespae`. For example, if you are using manifests to install NGINX Ingress controller, you can complete all of the steps on our documentation page, *EXCEPT*, actually deploying NGINX Ingress controller. This is because, when using the sidecar approach, OSM needs to "manage" the namespace so it knows what `namespaces` it needs to inject sidecars into. + +Next thing we need to do is install OSM into the `NGINX Ingress controller` namespace so that the `envoy` sidecar will be injected into NGINX Ingress controller. +First, create the `nginx-ingress` namespace: + +```bash +kubectl get ns nginx-ingress +``` +Then "mark" the `nginx-ingress` namespace for OSM to deploy a sidecar. + +```bash +osm namespace add nginx-ingress --mesh-name osm-nginx +``` + +The above command will use the mark the `nginx-ingress` namespace, where OSM will be installed (sidecar) + +### Install a Test Application +To test the integration, we will use the `httpbin` sample application from the [Ingress With Kubernetes NGINX Ingress Controller](https://release-v1-2.docs.openservicemesh.io/docs/demos/ingress_k8s_nginx/) guide. + +The following three commands will create the namespace for the application, add the namespace to OSM for monitoring, then install the application. + +```bash +kubectl create ns httpbin +osm namespace add httpbin --mesh-name osm-nginx +kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm-docs/release-v1.2/manifests/samples/httpbin/httpbin.yaml -n httpbin +``` + +### Add required annotations to NGINX Ingress Controller deployment: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-ingress + namespace: nginx-ingress +spec: + replicas: 1 + selector: + matchLabels: + app: nginx-ingress + template: + metadata: + labels: + app: nginx-ingress + annotations: + openservicemesh.io/inbound-port-exclusion-list: "80,443" +``` + +This annotation is *required* when injecting envoy sidecar into NGINX Ingress controller. + +`InboundPortExclusionList` defines a global list of ports to exclude from inbound traffic interception by the sidecar proxy. + + +### Verify that the envoy sidecar has been *injected* into NGINX Ingress + +```bash +kubectl get pods -n nginx-ingress +NAME READY STATUS RESTARTS AGE +nginx-ingress-7b9557ddc6-zw7l5 2/2 Running 1 (5m8s ago) 5m19s +``` + +2/2 shows we have two containers in the NGINX Ingress controller pod: NGINX Ingress and Envoy + + +Configure your NGINX VirtualServer yaml definitions to include the `policy` field like the following example: + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: VirtualServer +metadata: + name: httpbin + namespace: httpbin +spec: + host: httpbin.example.com + tls: + secret: secret01 + upstreams: + - name: httpbin + service: httpbin + port: 14001 + use-cluster-ip: true + routes: + - path: / + action: + proxy: + upstream: httpbin + requestHeaders: + set: + - name: Host + value: httpbin.httpbin.svc.cluster.local +``` + +Test your configuration: + +```bash + curl http://httpbin.example.com/get -v +* Trying 172.19.0.2:80... +* TCP_NODELAY set +* Connected to httpbin.example.com (172.19.0.2) port 80 (#0) +> GET /get HTTP/1.1 +> Host: httpbin.example.com +> User-Agent: curl/7.68.0 +> Accept: */* +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< Server: nginx/1.23.3 +< Date: Sun, 19 Feb 2023 19:06:47 GMT +< Content-Type: application/json +< Content-Length: 454 +< Connection: keep-alive +< access-control-allow-origin: * +< access-control-allow-credentials: true +< x-envoy-upstream-service-time: 2 +< +{ + "args": {}, + "headers": { + "Accept": "*/*", + "Host": "httpbin.httpbin.svc.cluster.local", + "Osm-Stats-Kind": "Deployment", + "Osm-Stats-Name": "httpbin", + "Osm-Stats-Namespace": "httpbin", + "Osm-Stats-Pod": "httpbin-78555f5c4b-t6qln", + "User-Agent": "curl/7.68.0", + "X-Envoy-Internal": "true", + "X-Forwarded-Host": "httpbin.example.com" + }, + "origin": "172.19.0.1", + "url": "http://httpbin.example.com/get" +} +* Connection #0 to host httpbin.example.com left intact +``` + + From c0bff636ad9cbf02fd50ef8cc8d479f28dd674ff Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 24 Feb 2023 22:32:14 +0000 Subject: [PATCH 02/25] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/content/tutorials/nic-osm.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/content/tutorials/nic-osm.md b/docs/content/tutorials/nic-osm.md index e3386266c2..476423d085 100644 --- a/docs/content/tutorials/nic-osm.md +++ b/docs/content/tutorials/nic-osm.md @@ -2,7 +2,7 @@ Open Service Mesh will work with both versions of [F5 NGINX Ingress controller](https://github.com/nginxinc/kubernetes-ingress): the free as well as the NGINX Plus versions. -Below is a link to the official F5 NGINX Ingress controller documentation. +Below is a link to the official F5 NGINX Ingress controller documentation. [F5 NGINX Ingress controller](https://docs.nginx.com/nginx-ingress-controller/) # Integrating NGINX Ingress Controller with Open Service Mesh @@ -257,7 +257,7 @@ curl http://httpbin.example.com/get -v * Connection #0 to host httpbin.example.com left intact ``` -# NGINX Ingress controller and OSM with sidecar injected +# NGINX Ingress controller and OSM with sidecar injected First install OSM in the cluster @@ -346,7 +346,7 @@ spec: upstreams: - name: httpbin service: httpbin - port: 14001 + port: 14001 use-cluster-ip: true routes: - path: / @@ -400,5 +400,3 @@ Test your configuration: } * Connection #0 to host httpbin.example.com left intact ``` - - From 33ae85e80f253a7327117c913decc856be926aae Mon Sep 17 00:00:00 2001 From: Jason Williams Date: Sun, 26 Feb 2023 19:29:09 -0800 Subject: [PATCH 03/25] Removed policy referene from sidecar method. --- docs/content/tutorials/nic-osm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/tutorials/nic-osm.md b/docs/content/tutorials/nic-osm.md index 476423d085..2e3d6a8404 100644 --- a/docs/content/tutorials/nic-osm.md +++ b/docs/content/tutorials/nic-osm.md @@ -331,7 +331,7 @@ nginx-ingress-7b9557ddc6-zw7l5 2/2 Running 1 (5m8s ago) 5m19s 2/2 shows we have two containers in the NGINX Ingress controller pod: NGINX Ingress and Envoy -Configure your NGINX VirtualServer yaml definitions to include the `policy` field like the following example: +Configure your NGINX VirtualServer yaml definitions to similar configuration below. ```yaml apiVersion: k8s.nginx.org/v1 From b3c385db572ebad57cb31b7ebe0a37671bf20a44 Mon Sep 17 00:00:00 2001 From: Jason Williams Date: Tue, 28 Feb 2023 16:25:09 -0800 Subject: [PATCH 04/25] fixed ordering of methods --- docs/content/tutorials/nic-osm.md | 293 +++++++++++++++--------------- 1 file changed, 147 insertions(+), 146 deletions(-) diff --git a/docs/content/tutorials/nic-osm.md b/docs/content/tutorials/nic-osm.md index 2e3d6a8404..de76d4d190 100644 --- a/docs/content/tutorials/nic-osm.md +++ b/docs/content/tutorials/nic-osm.md @@ -9,10 +9,154 @@ Below is a link to the official F5 NGINX Ingress controller documentation. There are two ways to integrate the NGINX Ingress Controller with Open Service Mesh (OSM): -1. Using the Open Service Mesh `ingressBackend` "proxy" feature. -2. Injecting an envoy sidecar directly with NGINX Ingress Controller. +1. Injecting an envoy sidecar directly with NGINX Ingress Controller. +2. Using the Open Service Mesh `ingressBackend` "proxy" feature. -## Using The Open Service Mesh `ingressBackend` "proxy" Feature +# NGINX Ingress controller and OSM with sidecar injected + +First install OSM in the cluster + +```bash +osm install --mesh-name osm-nginx --osm-namespace osm-system +``` + +### Mark NGINX Ingress controller namespace for sidecar injection + +*NOTE:* Depending on how you install NGINX Ingress controller, you might need to create the `namespae`. For example, if you are using manifests to install NGINX Ingress controller, you can complete all of the steps on our documentation page, *EXCEPT*, actually deploying NGINX Ingress controller. This is because, when using the sidecar approach, OSM needs to "manage" the namespace so it knows what `namespaces` it needs to inject sidecars into. + +Next thing we need to do is install OSM into the `NGINX Ingress controller` namespace so that the `envoy` sidecar will be injected into NGINX Ingress controller. +First, create the `nginx-ingress` namespace: + +```bash +kubectl get ns nginx-ingress +``` +Then "mark" the `nginx-ingress` namespace for OSM to deploy a sidecar. + +```bash +osm namespace add nginx-ingress --mesh-name osm-nginx +``` + +The above command will use the mark the `nginx-ingress` namespace, where OSM will be installed (sidecar) + +### Install a Test Application +To test the integration, we will use the `httpbin` sample application from the [Ingress With Kubernetes NGINX Ingress Controller](https://release-v1-2.docs.openservicemesh.io/docs/demos/ingress_k8s_nginx/) guide. + +The following three commands will create the namespace for the application, add the namespace to OSM for monitoring, then install the application. + +```bash +kubectl create ns httpbin +osm namespace add httpbin --mesh-name osm-nginx +kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm-docs/release-v1.2/manifests/samples/httpbin/httpbin.yaml -n httpbin +``` + +### Add required annotations to NGINX Ingress Controller deployment: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-ingress + namespace: nginx-ingress +spec: + replicas: 1 + selector: + matchLabels: + app: nginx-ingress + template: + metadata: + labels: + app: nginx-ingress + annotations: + openservicemesh.io/inbound-port-exclusion-list: "80,443" +``` + +This annotation is *required* when injecting envoy sidecar into NGINX Ingress controller. + +`InboundPortExclusionList` defines a global list of ports to exclude from inbound traffic interception by the sidecar proxy. + + +### Verify that the envoy sidecar has been *injected* into NGINX Ingress + +```bash +kubectl get pods -n nginx-ingress +NAME READY STATUS RESTARTS AGE +nginx-ingress-7b9557ddc6-zw7l5 2/2 Running 1 (5m8s ago) 5m19s +``` + +2/2 shows we have two containers in the NGINX Ingress controller pod: NGINX Ingress and Envoy + + +Configure your NGINX VirtualServer yaml definitions to similar configuration below. + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: VirtualServer +metadata: + name: httpbin + namespace: httpbin +spec: + host: httpbin.example.com + tls: + secret: secret01 + upstreams: + - name: httpbin + service: httpbin + port: 14001 + use-cluster-ip: true + routes: + - path: / + action: + proxy: + upstream: httpbin + requestHeaders: + set: + - name: Host + value: httpbin.httpbin.svc.cluster.local +``` + +Test your configuration: + +```bash + curl http://httpbin.example.com/get -v +* Trying 172.19.0.2:80... +* TCP_NODELAY set +* Connected to httpbin.example.com (172.19.0.2) port 80 (#0) +> GET /get HTTP/1.1 +> Host: httpbin.example.com +> User-Agent: curl/7.68.0 +> Accept: */* +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< Server: nginx/1.23.3 +< Date: Sun, 19 Feb 2023 19:06:47 GMT +< Content-Type: application/json +< Content-Length: 454 +< Connection: keep-alive +< access-control-allow-origin: * +< access-control-allow-credentials: true +< x-envoy-upstream-service-time: 2 +< +{ + "args": {}, + "headers": { + "Accept": "*/*", + "Host": "httpbin.httpbin.svc.cluster.local", + "Osm-Stats-Kind": "Deployment", + "Osm-Stats-Name": "httpbin", + "Osm-Stats-Namespace": "httpbin", + "Osm-Stats-Pod": "httpbin-78555f5c4b-t6qln", + "User-Agent": "curl/7.68.0", + "X-Envoy-Internal": "true", + "X-Forwarded-Host": "httpbin.example.com" + }, + "origin": "172.19.0.1", + "url": "http://httpbin.example.com/get" +} +* Connection #0 to host httpbin.example.com left intact +``` + +## Using The Open Service Mesh `IngressBackend` "proxy" Feature Install OSM into cluster. By running the following command, you will install OSM into the cluster with the mesh name `osm-nginx` using the `osm-system` namespace. @@ -257,146 +401,3 @@ curl http://httpbin.example.com/get -v * Connection #0 to host httpbin.example.com left intact ``` -# NGINX Ingress controller and OSM with sidecar injected - -First install OSM in the cluster - -```bash -osm install --mesh-name osm-nginx --osm-namespace osm-system -``` - -### Mark NGINX Ingress controller namespace for sidecar injection - -*NOTE:* Depending on how you install NGINX Ingress controller, you might need to create the `namespae`. For example, if you are using manifests to install NGINX Ingress controller, you can complete all of the steps on our documentation page, *EXCEPT*, actually deploying NGINX Ingress controller. This is because, when using the sidecar approach, OSM needs to "manage" the namespace so it knows what `namespaces` it needs to inject sidecars into. - -Next thing we need to do is install OSM into the `NGINX Ingress controller` namespace so that the `envoy` sidecar will be injected into NGINX Ingress controller. -First, create the `nginx-ingress` namespace: - -```bash -kubectl get ns nginx-ingress -``` -Then "mark" the `nginx-ingress` namespace for OSM to deploy a sidecar. - -```bash -osm namespace add nginx-ingress --mesh-name osm-nginx -``` - -The above command will use the mark the `nginx-ingress` namespace, where OSM will be installed (sidecar) - -### Install a Test Application -To test the integration, we will use the `httpbin` sample application from the [Ingress With Kubernetes NGINX Ingress Controller](https://release-v1-2.docs.openservicemesh.io/docs/demos/ingress_k8s_nginx/) guide. - -The following three commands will create the namespace for the application, add the namespace to OSM for monitoring, then install the application. - -```bash -kubectl create ns httpbin -osm namespace add httpbin --mesh-name osm-nginx -kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm-docs/release-v1.2/manifests/samples/httpbin/httpbin.yaml -n httpbin -``` - -### Add required annotations to NGINX Ingress Controller deployment: - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: nginx-ingress - namespace: nginx-ingress -spec: - replicas: 1 - selector: - matchLabels: - app: nginx-ingress - template: - metadata: - labels: - app: nginx-ingress - annotations: - openservicemesh.io/inbound-port-exclusion-list: "80,443" -``` - -This annotation is *required* when injecting envoy sidecar into NGINX Ingress controller. - -`InboundPortExclusionList` defines a global list of ports to exclude from inbound traffic interception by the sidecar proxy. - - -### Verify that the envoy sidecar has been *injected* into NGINX Ingress - -```bash -kubectl get pods -n nginx-ingress -NAME READY STATUS RESTARTS AGE -nginx-ingress-7b9557ddc6-zw7l5 2/2 Running 1 (5m8s ago) 5m19s -``` - -2/2 shows we have two containers in the NGINX Ingress controller pod: NGINX Ingress and Envoy - - -Configure your NGINX VirtualServer yaml definitions to similar configuration below. - -```yaml -apiVersion: k8s.nginx.org/v1 -kind: VirtualServer -metadata: - name: httpbin - namespace: httpbin -spec: - host: httpbin.example.com - tls: - secret: secret01 - upstreams: - - name: httpbin - service: httpbin - port: 14001 - use-cluster-ip: true - routes: - - path: / - action: - proxy: - upstream: httpbin - requestHeaders: - set: - - name: Host - value: httpbin.httpbin.svc.cluster.local -``` - -Test your configuration: - -```bash - curl http://httpbin.example.com/get -v -* Trying 172.19.0.2:80... -* TCP_NODELAY set -* Connected to httpbin.example.com (172.19.0.2) port 80 (#0) -> GET /get HTTP/1.1 -> Host: httpbin.example.com -> User-Agent: curl/7.68.0 -> Accept: */* -> -* Mark bundle as not supporting multiuse -< HTTP/1.1 200 OK -< Server: nginx/1.23.3 -< Date: Sun, 19 Feb 2023 19:06:47 GMT -< Content-Type: application/json -< Content-Length: 454 -< Connection: keep-alive -< access-control-allow-origin: * -< access-control-allow-credentials: true -< x-envoy-upstream-service-time: 2 -< -{ - "args": {}, - "headers": { - "Accept": "*/*", - "Host": "httpbin.httpbin.svc.cluster.local", - "Osm-Stats-Kind": "Deployment", - "Osm-Stats-Name": "httpbin", - "Osm-Stats-Namespace": "httpbin", - "Osm-Stats-Pod": "httpbin-78555f5c4b-t6qln", - "User-Agent": "curl/7.68.0", - "X-Envoy-Internal": "true", - "X-Forwarded-Host": "httpbin.example.com" - }, - "origin": "172.19.0.1", - "url": "http://httpbin.example.com/get" -} -* Connection #0 to host httpbin.example.com left intact -``` From b841fce344757dd6e18e0cc032aba7beaaaa5645 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 1 Mar 2023 00:25:31 +0000 Subject: [PATCH 05/25] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/content/tutorials/nic-osm.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/content/tutorials/nic-osm.md b/docs/content/tutorials/nic-osm.md index de76d4d190..4936076f62 100644 --- a/docs/content/tutorials/nic-osm.md +++ b/docs/content/tutorials/nic-osm.md @@ -400,4 +400,3 @@ curl http://httpbin.example.com/get -v } * Connection #0 to host httpbin.example.com left intact ``` - From 8c4b012e0cf5f9d5b3e2ea1e74f526ff68ce3817 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jason=20Williams=20-=20NGI=D0=98X?= Date: Fri, 17 Mar 2023 15:10:23 -0700 Subject: [PATCH 06/25] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Alan Dooley Signed-off-by: Jason Williams - NGIИX --- docs/content/tutorials/nic-osm.md | 54 +++++++++++++++---------------- 1 file changed, 26 insertions(+), 28 deletions(-) diff --git a/docs/content/tutorials/nic-osm.md b/docs/content/tutorials/nic-osm.md index 4936076f62..ddbf0b2e28 100644 --- a/docs/content/tutorials/nic-osm.md +++ b/docs/content/tutorials/nic-osm.md @@ -1,9 +1,9 @@ ## This document outlines how to integrate F5 NGINX Ingress Controller with Open Service Mesh (OSM) -Open Service Mesh will work with both versions of [F5 NGINX Ingress controller](https://github.com/nginxinc/kubernetes-ingress): the free as well as the NGINX Plus versions. +Open Service Mesh works with both the free and NGINX Plus versions of the [F5 NGINX Ingress controller](https://github.com/nginxinc/kubernetes-ingress). -Below is a link to the official F5 NGINX Ingress controller documentation. -[F5 NGINX Ingress controller](https://docs.nginx.com/nginx-ingress-controller/) +Below is a link to the official NGINX Ingress Controller documentation. +[NGINX Ingress Controller](https://docs.nginx.com/nginx-ingress-controller/) # Integrating NGINX Ingress Controller with Open Service Mesh @@ -12,19 +12,19 @@ There are two ways to integrate the NGINX Ingress Controller with Open Service M 1. Injecting an envoy sidecar directly with NGINX Ingress Controller. 2. Using the Open Service Mesh `ingressBackend` "proxy" feature. -# NGINX Ingress controller and OSM with sidecar injected +# NGINX Ingress Controller and Open Service Mesh with Sidecar Injection -First install OSM in the cluster +First, install OSM in the cluster. ```bash osm install --mesh-name osm-nginx --osm-namespace osm-system ``` -### Mark NGINX Ingress controller namespace for sidecar injection +### Mark the NGINX Ingress Controller namespace for Sidecar Injection -*NOTE:* Depending on how you install NGINX Ingress controller, you might need to create the `namespae`. For example, if you are using manifests to install NGINX Ingress controller, you can complete all of the steps on our documentation page, *EXCEPT*, actually deploying NGINX Ingress controller. This is because, when using the sidecar approach, OSM needs to "manage" the namespace so it knows what `namespaces` it needs to inject sidecars into. +*NOTE:* Depending on how you install NGINX Ingress Controller, you might need to create the `namespace`. For example, if you are using manifests to install NGINX Ingress Controller, you can complete all of the steps on [its documentation page](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/), *EXCEPT* for deploying NGINX Ingress Controller. When using the sidecar approach, OSM needs to "manage" the namespace so it knows what `namespaces` to inject sidecars into. -Next thing we need to do is install OSM into the `NGINX Ingress controller` namespace so that the `envoy` sidecar will be injected into NGINX Ingress controller. +The next step is to install OSM into the `NGINX Ingress Controller` namespace so the `envoy` sidecar will be injected into NGINX Ingress Controller. First, create the `nginx-ingress` namespace: ```bash @@ -36,7 +36,7 @@ Then "mark" the `nginx-ingress` namespace for OSM to deploy a sidecar. osm namespace add nginx-ingress --mesh-name osm-nginx ``` -The above command will use the mark the `nginx-ingress` namespace, where OSM will be installed (sidecar) +The above command will use the mark the `nginx-ingress` namespace, where OSM will be installed (sidecar). ### Install a Test Application To test the integration, we will use the `httpbin` sample application from the [Ingress With Kubernetes NGINX Ingress Controller](https://release-v1-2.docs.openservicemesh.io/docs/demos/ingress_k8s_nginx/) guide. @@ -70,7 +70,7 @@ spec: openservicemesh.io/inbound-port-exclusion-list: "80,443" ``` -This annotation is *required* when injecting envoy sidecar into NGINX Ingress controller. +This annotation is *required* when injecting envoy sidecar into NGINX Ingress Controller. `InboundPortExclusionList` defines a global list of ports to exclude from inbound traffic interception by the sidecar proxy. @@ -83,10 +83,10 @@ NAME READY STATUS RESTARTS AGE nginx-ingress-7b9557ddc6-zw7l5 2/2 Running 1 (5m8s ago) 5m19s ``` -2/2 shows we have two containers in the NGINX Ingress controller pod: NGINX Ingress and Envoy +"2/2" demonstrates there are two containers in the NGINX Ingress Controller pod: NGINX Ingress and Envoy -Configure your NGINX VirtualServer yaml definitions to similar configuration below. +Configure your NGINX VirtualServer `yaml` definitions with the adjustments below. ```yaml apiVersion: k8s.nginx.org/v1 @@ -157,8 +157,6 @@ Test your configuration: ``` ## Using The Open Service Mesh `IngressBackend` "proxy" Feature - -Install OSM into cluster. By running the following command, you will install OSM into the cluster with the mesh name `osm-nginx` using the `osm-system` namespace. ```bash @@ -166,7 +164,7 @@ osm install --mesh-name osm-nginx --osm-namespace osm-system ``` Once OSM has been installed, this next command will mark the NGINX Ingress Controller as part of the OSM mesh, while also disabling sidecar injection. -*NOTE*: The nginx-ingress name can be created as part of the NGINX Ingress install process, or manually. It must be created before you "add" the namespace to nginx-ingress. +*NOTE*: The nginx-ingress name can be created as part of the NGINX Ingress install process, or manually. It must be created **before** you "add" the namespace to nginx-ingress. ```bash osm namespace add nginx-ingress --mesh-name osm-nginx --disable-sidecar-injection @@ -186,7 +184,7 @@ kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm-docs/rele ### mTLS Setup -To enable mTLS for NGINX Ingress Controller and OSM, you need to configure the `IngressBackend` API to use `https` as the backend protocol as and trigger OSM to issue a certificate. NGINX will use this certificate to proxy HTTPS connections to the TLS backends. The client certificate and certificate authority (CA) certificate will be stored in a Kubernetes secret that NGINX will use for authentication."* +To enable mTLS for NGINX Ingress Controller and OSM, you need to configure the `IngressBackend` API to use `https` as the backend protocol and trigger OSM to issue a certificate. NGINX will use this certificate to proxy HTTPS connections to the TLS backends. The client certificate and certificate authority (CA) certificate will be stored in a Kubernetes secret that NGINX will use for authentication."* To begin, edit the `osm-mesh-config` resource: @@ -194,7 +192,7 @@ To begin, edit the `osm-mesh-config` resource: kubectl edit meshconfig osm-mesh-config -n osm-system ``` -You will need to update under `certificate` to look like this: +The certificate configuration must then be updated as below: ```yaml spec: @@ -208,14 +206,14 @@ spec: validityDuration: 24h ``` -This will generate a new client certificate (osm-nginx-client-cert) that NGINX Ingress controller will use for mTLS. +This will generate a new client certificate (osm-nginx-client-cert) that NGINX Ingress Controller will use for mTLS. The *SAN*, `subjectAltNames`, is the following form: ```bash ..cluster.local ``` -With the above OSM mesh config changed, that secret will be created in the `osm-system` namespace. +When the OSM mesh configuration changes, the secret will be created in the `osm-system` namespace. There will also be the `osm-ca-bundle` secret as well, which is autogenerated by OSM. ```bash @@ -225,7 +223,7 @@ osm-ca-bundle Opaque 2 37m osm-nginx-client-cert kubernetes.io/tls 3 17m ``` -Now, we need to "export" out these certificates in order to use them with NGINX Ingress Controller. +The certificates must then be exported in order to use them with NGINX Ingress Controller. ```bash kubectl get secret osm-ca-bundle -n osm-system -o yaml > osm-ca-bundle-secret.yaml @@ -233,14 +231,14 @@ kubectl get secret osm-nginx-client-cert -n osm-system -o yaml > osm-nginx-clien ``` -We need to edit the two exported out .yaml files and change a few parts. +The two exported .yaml files will now require changes: Edit `osm-ca-bundle-secret.yaml` Remove the `private.key` section under `data.` Change the `namespace` field to your nginx-ingress location Change the `type` to `type: nginx.org/ca` -Updated file should look like the following. +The updated file should look like the below example: ```yaml apiVersion: v1 kind: Secret @@ -256,7 +254,7 @@ Edit `osm-nginx-client-cert.yaml` Remove the `ca.crt` in the `data` section Change the namespace to the nginx-ingress namespace. -Updated file should look like the following. +The updated file should look like the below example: ```yaml apiVersion: v1 @@ -270,14 +268,14 @@ data: tls.key: ``` -Then apply these two secrets to the cluster. +Once these two files have been edited, they will need to be applied to the cluster: ```bash kubectl apply -f osm-ca-bundle-secret.yaml kubectl apply -f osm-nginx-client-cert.yaml ``` -Ensure the secrets exisit in the `nginx-ingress` namespace: +Ensure the secrets exist in the `nginx-ingress` namespace: ```bash kubectl get secrets -n nginx-ingress @@ -286,9 +284,9 @@ osm-nginx-client-cert kubernetes.io/tls 2 23m osm-ca-bundle nginx.org/ca 1 23m ``` -We now need to create our CRDs (virtualServer and policy). +The CRDs (virtualServer and policy) must now be created. Here is the `policy` resource that holds the mTLS information. -Make sure you apply the `policy` or the mTLS connection will not work. (required for virtualServer) +It is required for virtualServer, and the `policy` must be applied or the mTLS connection will not work. ```yaml apiVersion: k8s.nginx.org/v1 @@ -363,7 +361,7 @@ NAMESPACE NAME STATUS httpbin ingressbackend.policy.openservicemesh.io/httpbin committed ``` -You can now send traffic through NGINX Ingress Controller with open service mesh. +You can now send traffic through NGINX Ingress Controller with Open Service Mesh. ```bash curl http://httpbin.example.com/get -v From bf9f9f736a1da640fdf0b6fb83e022f612120426 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 17 Mar 2023 22:10:41 +0000 Subject: [PATCH 07/25] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/content/tutorials/nic-osm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/tutorials/nic-osm.md b/docs/content/tutorials/nic-osm.md index ddbf0b2e28..57be9d763e 100644 --- a/docs/content/tutorials/nic-osm.md +++ b/docs/content/tutorials/nic-osm.md @@ -286,7 +286,7 @@ osm-ca-bundle nginx.org/ca 1 23m The CRDs (virtualServer and policy) must now be created. Here is the `policy` resource that holds the mTLS information. -It is required for virtualServer, and the `policy` must be applied or the mTLS connection will not work. +It is required for virtualServer, and the `policy` must be applied or the mTLS connection will not work. ```yaml apiVersion: k8s.nginx.org/v1 From 87b1bc09f25dc70907a6ffe4fb117bab1d93611e Mon Sep 17 00:00:00 2001 From: Jason Williams Date: Tue, 28 Feb 2023 16:25:09 -0800 Subject: [PATCH 08/25] fixed ordering of methods --- docs/content/tutorials/nic-osm.md | 316 ++++++++++++++++-------------- 1 file changed, 170 insertions(+), 146 deletions(-) diff --git a/docs/content/tutorials/nic-osm.md b/docs/content/tutorials/nic-osm.md index 2e3d6a8404..93448e3867 100644 --- a/docs/content/tutorials/nic-osm.md +++ b/docs/content/tutorials/nic-osm.md @@ -9,10 +9,177 @@ Below is a link to the official F5 NGINX Ingress controller documentation. There are two ways to integrate the NGINX Ingress Controller with Open Service Mesh (OSM): -1. Using the Open Service Mesh `ingressBackend` "proxy" feature. -2. Injecting an envoy sidecar directly with NGINX Ingress Controller. +1. Injecting an envoy sidecar directly with NGINX Ingress Controller. +2. Using the Open Service Mesh `ingressBackend` "proxy" feature. -## Using The Open Service Mesh `ingressBackend` "proxy" Feature +# First, install NGINX Ingress Controller into your cluster. + + +When using NGINX Ingress controller with thes sidecar method, you will want to ensure you are providing the correct annotation to your deployment. + +[Using Helm to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) +[Using manifests to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) + + +If you are using `helm`, make sure you pass in the correct `annotation` in this example: + +```yaml + annotations: { openservicemesh.io/inbound-port-exclusion-list: "80, 443" } +``` + +If you are using `manifests`, add the following line to the the deploment file: + +```yaml +annotations: + openservicemesh.io/inbound-port-exclusion-list: "80,443" +``` + + +# NGINX Ingress controller and OSM with sidecar injected + +First install OSM in the cluster + +```bash +osm install --mesh-name osm-nginx --osm-namespace osm-system +``` + +### Mark NGINX Ingress controller namespace for sidecar injection + +*NOTE:* Depending on how you install NGINX Ingress controller, you might need to create the `namespae`. For example, if you are using manifests to install NGINX Ingress controller, you can complete all of the steps on our documentation page, *EXCEPT*, actually deploying NGINX Ingress controller. This is because, when using the sidecar approach, OSM needs to "manage" the namespace so it knows what `namespaces` it needs to inject sidecars into. + +Next thing we need to do is install OSM into the `NGINX Ingress controller` namespace so that the `envoy` sidecar will be injected into NGINX Ingress controller. +First, create the `nginx-ingress` namespace: + +```bash +kubectl get ns nginx-ingress +``` +Then "mark" the `nginx-ingress` namespace for OSM to deploy a sidecar. + +```bash +osm namespace add nginx-ingress --mesh-name osm-nginx +``` + +The above command will use the mark the `nginx-ingress` namespace, where OSM will be installed (sidecar) + +### Install a Test Application +To test the integration, we will use the `httpbin` sample application from the [Ingress With Kubernetes NGINX Ingress Controller](https://release-v1-2.docs.openservicemesh.io/docs/demos/ingress_k8s_nginx/) guide. + +The following three commands will create the namespace for the application, add the namespace to OSM for monitoring, then install the application. + +```bash +kubectl create ns httpbin +osm namespace add httpbin --mesh-name osm-nginx +kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm-docs/release-v1.2/manifests/samples/httpbin/httpbin.yaml -n httpbin +``` + +### Add required annotations to NGINX Ingress Controller deployment: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-ingress + namespace: nginx-ingress +spec: + replicas: 1 + selector: + matchLabels: + app: nginx-ingress + template: + metadata: + labels: + app: nginx-ingress + annotations: + openservicemesh.io/inbound-port-exclusion-list: "80,443" +``` + +This annotation is *required* when injecting envoy sidecar into NGINX Ingress controller. + +`InboundPortExclusionList` defines a global list of ports to exclude from inbound traffic interception by the sidecar proxy. + + +### Verify that the envoy sidecar has been *injected* into NGINX Ingress + +```bash +kubectl get pods -n nginx-ingress +NAME READY STATUS RESTARTS AGE +nginx-ingress-7b9557ddc6-zw7l5 2/2 Running 1 (5m8s ago) 5m19s +``` + +2/2 shows we have two containers in the NGINX Ingress controller pod: NGINX Ingress and Envoy + + +Configure your NGINX VirtualServer yaml definitions to similar configuration below. + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: VirtualServer +metadata: + name: httpbin + namespace: httpbin +spec: + host: httpbin.example.com + tls: + secret: secret01 + upstreams: + - name: httpbin + service: httpbin + port: 14001 + use-cluster-ip: true + routes: + - path: / + action: + proxy: + upstream: httpbin + requestHeaders: + set: + - name: Host + value: httpbin.httpbin.svc.cluster.local +``` + +Test your configuration: + +```bash + curl http://httpbin.example.com/get -v +* Trying 172.19.0.2:80... +* TCP_NODELAY set +* Connected to httpbin.example.com (172.19.0.2) port 80 (#0) +> GET /get HTTP/1.1 +> Host: httpbin.example.com +> User-Agent: curl/7.68.0 +> Accept: */* +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< Server: nginx/1.23.3 +< Date: Sun, 19 Feb 2023 19:06:47 GMT +< Content-Type: application/json +< Content-Length: 454 +< Connection: keep-alive +< access-control-allow-origin: * +< access-control-allow-credentials: true +< x-envoy-upstream-service-time: 2 +< +{ + "args": {}, + "headers": { + "Accept": "*/*", + "Host": "httpbin.httpbin.svc.cluster.local", + "Osm-Stats-Kind": "Deployment", + "Osm-Stats-Name": "httpbin", + "Osm-Stats-Namespace": "httpbin", + "Osm-Stats-Pod": "httpbin-78555f5c4b-t6qln", + "User-Agent": "curl/7.68.0", + "X-Envoy-Internal": "true", + "X-Forwarded-Host": "httpbin.example.com" + }, + "origin": "172.19.0.1", + "url": "http://httpbin.example.com/get" +} +* Connection #0 to host httpbin.example.com left intact +``` + +## Using The Open Service Mesh `IngressBackend` "proxy" Feature Install OSM into cluster. By running the following command, you will install OSM into the cluster with the mesh name `osm-nginx` using the `osm-system` namespace. @@ -257,146 +424,3 @@ curl http://httpbin.example.com/get -v * Connection #0 to host httpbin.example.com left intact ``` -# NGINX Ingress controller and OSM with sidecar injected - -First install OSM in the cluster - -```bash -osm install --mesh-name osm-nginx --osm-namespace osm-system -``` - -### Mark NGINX Ingress controller namespace for sidecar injection - -*NOTE:* Depending on how you install NGINX Ingress controller, you might need to create the `namespae`. For example, if you are using manifests to install NGINX Ingress controller, you can complete all of the steps on our documentation page, *EXCEPT*, actually deploying NGINX Ingress controller. This is because, when using the sidecar approach, OSM needs to "manage" the namespace so it knows what `namespaces` it needs to inject sidecars into. - -Next thing we need to do is install OSM into the `NGINX Ingress controller` namespace so that the `envoy` sidecar will be injected into NGINX Ingress controller. -First, create the `nginx-ingress` namespace: - -```bash -kubectl get ns nginx-ingress -``` -Then "mark" the `nginx-ingress` namespace for OSM to deploy a sidecar. - -```bash -osm namespace add nginx-ingress --mesh-name osm-nginx -``` - -The above command will use the mark the `nginx-ingress` namespace, where OSM will be installed (sidecar) - -### Install a Test Application -To test the integration, we will use the `httpbin` sample application from the [Ingress With Kubernetes NGINX Ingress Controller](https://release-v1-2.docs.openservicemesh.io/docs/demos/ingress_k8s_nginx/) guide. - -The following three commands will create the namespace for the application, add the namespace to OSM for monitoring, then install the application. - -```bash -kubectl create ns httpbin -osm namespace add httpbin --mesh-name osm-nginx -kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm-docs/release-v1.2/manifests/samples/httpbin/httpbin.yaml -n httpbin -``` - -### Add required annotations to NGINX Ingress Controller deployment: - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: nginx-ingress - namespace: nginx-ingress -spec: - replicas: 1 - selector: - matchLabels: - app: nginx-ingress - template: - metadata: - labels: - app: nginx-ingress - annotations: - openservicemesh.io/inbound-port-exclusion-list: "80,443" -``` - -This annotation is *required* when injecting envoy sidecar into NGINX Ingress controller. - -`InboundPortExclusionList` defines a global list of ports to exclude from inbound traffic interception by the sidecar proxy. - - -### Verify that the envoy sidecar has been *injected* into NGINX Ingress - -```bash -kubectl get pods -n nginx-ingress -NAME READY STATUS RESTARTS AGE -nginx-ingress-7b9557ddc6-zw7l5 2/2 Running 1 (5m8s ago) 5m19s -``` - -2/2 shows we have two containers in the NGINX Ingress controller pod: NGINX Ingress and Envoy - - -Configure your NGINX VirtualServer yaml definitions to similar configuration below. - -```yaml -apiVersion: k8s.nginx.org/v1 -kind: VirtualServer -metadata: - name: httpbin - namespace: httpbin -spec: - host: httpbin.example.com - tls: - secret: secret01 - upstreams: - - name: httpbin - service: httpbin - port: 14001 - use-cluster-ip: true - routes: - - path: / - action: - proxy: - upstream: httpbin - requestHeaders: - set: - - name: Host - value: httpbin.httpbin.svc.cluster.local -``` - -Test your configuration: - -```bash - curl http://httpbin.example.com/get -v -* Trying 172.19.0.2:80... -* TCP_NODELAY set -* Connected to httpbin.example.com (172.19.0.2) port 80 (#0) -> GET /get HTTP/1.1 -> Host: httpbin.example.com -> User-Agent: curl/7.68.0 -> Accept: */* -> -* Mark bundle as not supporting multiuse -< HTTP/1.1 200 OK -< Server: nginx/1.23.3 -< Date: Sun, 19 Feb 2023 19:06:47 GMT -< Content-Type: application/json -< Content-Length: 454 -< Connection: keep-alive -< access-control-allow-origin: * -< access-control-allow-credentials: true -< x-envoy-upstream-service-time: 2 -< -{ - "args": {}, - "headers": { - "Accept": "*/*", - "Host": "httpbin.httpbin.svc.cluster.local", - "Osm-Stats-Kind": "Deployment", - "Osm-Stats-Name": "httpbin", - "Osm-Stats-Namespace": "httpbin", - "Osm-Stats-Pod": "httpbin-78555f5c4b-t6qln", - "User-Agent": "curl/7.68.0", - "X-Envoy-Internal": "true", - "X-Forwarded-Host": "httpbin.example.com" - }, - "origin": "172.19.0.1", - "url": "http://httpbin.example.com/get" -} -* Connection #0 to host httpbin.example.com left intact -``` From c48db92a69ad767cfd4b66e850b27968fd57c19b Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 21 Mar 2023 23:50:00 +0000 Subject: [PATCH 09/25] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/content/tutorials/nic-osm.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/content/tutorials/nic-osm.md b/docs/content/tutorials/nic-osm.md index dd744e2f5d..4db762a512 100644 --- a/docs/content/tutorials/nic-osm.md +++ b/docs/content/tutorials/nic-osm.md @@ -12,13 +12,13 @@ There are two ways to integrate the NGINX Ingress Controller with Open Service M 1. Injecting an envoy sidecar directly with NGINX Ingress Controller. 2. Using the Open Service Mesh `ingressBackend` "proxy" feature. -# First, install NGINX Ingress Controller into your cluster. +# First, install NGINX Ingress Controller into your cluster. -When using NGINX Ingress controller with thes sidecar method, you will want to ensure you are providing the correct annotation to your deployment. +When using NGINX Ingress controller with thes sidecar method, you will want to ensure you are providing the correct annotation to your deployment. -[Using Helm to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) -[Using manifests to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) +[Using Helm to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) +[Using manifests to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) If you are using `helm`, make sure you pass in the correct `annotation` in this example: From df9709fef76b19f56b5a6dc88d1680e4683fa9fd Mon Sep 17 00:00:00 2001 From: Jason Williams Date: Tue, 21 Mar 2023 17:01:23 -0700 Subject: [PATCH 10/25] Added NIC install with annotations --- .../tutorials/f5_nginx_ingress_controller.md | 429 ++++++++++++++++++ 1 file changed, 429 insertions(+) create mode 100644 docs/content/tutorials/f5_nginx_ingress_controller.md diff --git a/docs/content/tutorials/f5_nginx_ingress_controller.md b/docs/content/tutorials/f5_nginx_ingress_controller.md new file mode 100644 index 0000000000..91943aef62 --- /dev/null +++ b/docs/content/tutorials/f5_nginx_ingress_controller.md @@ -0,0 +1,429 @@ +## This document outlines how to integrate F5 NGINX Ingress Controller with Open Service Mesh (OSM) + +Open Service Mesh will work with both versions of [F5 NGINX Ingress controller](https://github.com/nginxinc/kubernetes-ingress): the free as well as the NGINX Plus versions. + +Below is a link to the official F5 NGINX Ingress controller documentation. +[F5 NGINX Ingress controller](https://docs.nginx.com/nginx-ingress-controller/) + +# Integrating NGINX Ingress Controller with Open Service Mesh + +There are two ways to integrate the NGINX Ingress Controller with Open Service Mesh (OSM): + +1. Injecting an envoy sidecar directly with NGINX Ingress Controller. +2. Using the Open Service Mesh `ingressBackend` "proxy" feature. + + +# NGINX Ingress controller and OSM with sidecar injected + +Install OSM in the cluster + +```bash +osm install --mesh-name osm-nginx --osm-namespace osm-system +``` + +### Mark F5 NGINX Ingress controller namespace for sidecar injection + +*NOTE:* Depending on how you install NGINX Ingress controller, you might need to create the `namespae`. For example, if you are using manifests to install NGINX Ingress controller, you can complete all of the steps on our documentation page, *EXCEPT*, actually deploying NGINX Ingress controller. This is because, when using the sidecar approach, OSM needs to "manage" the namespace so it knows what `namespaces` it needs to inject sidecars into. + +Next thing we need to do is install OSM into the `NGINX Ingress controller` namespace so that the `envoy` sidecar will be injected into NGINX Ingress controller. +First, create the `nginx-ingress` namespace: + +```bash +kubectl get ns nginx-ingress +``` +Then "mark" the `nginx-ingress` namespace for OSM to deploy a sidecar. + +```bash +osm namespace add nginx-ingress --mesh-name osm-nginx +``` + +The above command will use the mark the `nginx-ingress` namespace, where OSM will be installed (sidecar) + +# Istall F5 NGINX Ingress controller. Here the links to the install guides: + +[Using Helm to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) +[Using Manifests to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) + + +When using the sidecar method, ensure that you add the correct annotations listed below. This ensures proper integration of NGINX Ingress Controller with the envoy sidecar proxy. + +If using `helm`, add the following `annotation` to your `values.yaml` file: + +```yaml + annotations: { + openservicemesh.io/inbound-port-exclusion-list: "80, 443" + } +``` + +At a minimum, the following annotation needs to be set on your deployment: + +```yaml +annotations: + openservicemesh.io/inbound-port-exclusion-list: "80,443" +``` + +### Install a Test Application +To test the integration, we will use the `httpbin` sample application from the [Ingress With Kubernetes NGINX Ingress Controller](https://release-v1-2.docs.openservicemesh.io/docs/demos/ingress_k8s_nginx/) guide. + +The following three commands will create the namespace for the application, add the namespace to OSM for monitoring, then install the application. + +```bash +kubectl create ns httpbin +osm namespace add httpbin --mesh-name osm-nginx +kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm-docs/release-v1.2/manifests/samples/httpbin/httpbin.yaml -n httpbin +``` + +### Add required annotations to NGINX Ingress Controller deployment: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-ingress + namespace: nginx-ingress +spec: + replicas: 1 + selector: + matchLabels: + app: nginx-ingress + template: + metadata: + labels: + app: nginx-ingress + annotations: + openservicemesh.io/inbound-port-exclusion-list: "80,443" +``` + +This annotation is *required* when injecting envoy sidecar into NGINX Ingress controller. + +`InboundPortExclusionList` defines a global list of ports to exclude from inbound traffic interception by the sidecar proxy. + + +### Verify that the envoy sidecar has been *injected* into NGINX Ingress + +```bash +kubectl get pods -n nginx-ingress +NAME READY STATUS RESTARTS AGE +nginx-ingress-7b9557ddc6-zw7l5 2/2 Running 1 (5m8s ago) 5m19s +``` + +2/2 shows we have two containers in the NGINX Ingress controller pod: NGINX Ingress and Envoy + + +Configure your NGINX VirtualServer yaml to similar below + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: VirtualServer +metadata: + name: httpbin + namespace: httpbin +spec: + host: httpbin.example.com + tls: + secret: secret01 + upstreams: + - name: httpbin + service: httpbin + port: 14001 + use-cluster-ip: true + routes: + - path: / + action: + proxy: + upstream: httpbin + requestHeaders: + set: + - name: Host + value: httpbin.httpbin.svc.cluster.local +``` + +Test your configuration: + +```bash + curl http://httpbin.example.com/get -v +* Trying 172.19.0.2:80... +* TCP_NODELAY set +* Connected to httpbin.example.com (172.19.0.2) port 80 (#0) +> GET /get HTTP/1.1 +> Host: httpbin.example.com +> User-Agent: curl/7.68.0 +> Accept: */* +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< Server: nginx/1.23.3 +< Date: Sun, 19 Feb 2023 19:06:47 GMT +< Content-Type: application/json +< Content-Length: 454 +< Connection: keep-alive +< access-control-allow-origin: * +< access-control-allow-credentials: true +< x-envoy-upstream-service-time: 2 +< +{ + "args": {}, + "headers": { + "Accept": "*/*", + "Host": "httpbin.httpbin.svc.cluster.local", + "Osm-Stats-Kind": "Deployment", + "Osm-Stats-Name": "httpbin", + "Osm-Stats-Namespace": "httpbin", + "Osm-Stats-Pod": "httpbin-78555f5c4b-t6qln", + "User-Agent": "curl/7.68.0", + "X-Envoy-Internal": "true", + "X-Forwarded-Host": "httpbin.example.com" + }, + "origin": "172.19.0.1", + "url": "http://httpbin.example.com/get" +} +* Connection #0 to host httpbin.example.com left intact +``` + + + +## Using The Open Service Mesh `ingressBackend` "proxy" Feature + +Install OSM into cluster. +By running the following command, you will install OSM into the cluster with the mesh name `osm-nginx` using the `osm-system` namespace. + +```bash +osm install --mesh-name osm-nginx --osm-namespace osm-system +``` + +Once OSM has been installed, this next command will mark the NGINX Ingress Controller as part of the OSM mesh, while also disabling sidecar injection. +*NOTE*: The nginx-ingress name can be created as part of the NGINX Ingress install process, or manually. It must be created before you "add" the namespace to nginx-ingress. + +```bash +osm namespace add nginx-ingress --mesh-name osm-nginx --disable-sidecar-injection +``` + +### Install a Test Application + +To test the integration, we will use the `httpbin` sample application from the [Ingress With Kubernetes NGINX Ingress Controller](https://release-v1-2.docs.openservicemesh.io/docs/demos/ingress_k8s_nginx/) guide. + +The following three commands will create the namespace for the application, add the namespace to OSM for monitoring, then install the application. + +```bash +kubectl create ns httpbin +osm namespace add httpbin --mesh-name osm-nginx +kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm-docs/release-v1.2/manifests/samples/httpbin/httpbin.yaml -n httpbin +``` + +### mTLS Setup + +To enable mTLS for NGINX Ingress Controller and OSM, you need to configure the `IngressBackend` API to use `https` as the backend protocol as and trigger OSM to issue a certificate. NGINX will use this certificate to proxy HTTPS connections to the TLS backends. The client certificate and certificate authority (CA) certificate will be stored in a Kubernetes secret that NGINX will use for authentication."* + +To begin, edit the `osm-mesh-config` resource: + +```bash +kubectl edit meshconfig osm-mesh-config -n osm-system +``` + +You will need to update under `certificate` to look like this: + +```yaml +spec: + certificate: + ingressGateway: + secret: + name: osm-nginx-client-cert + namespace: osm-system + subjectAltNames: + - nginx-ingress.nginx-ingress.cluster.local + validityDuration: 24h +``` + +This will generate a new client certificate (osm-nginx-client-cert) that NGINX Ingress controller will use for mTLS. +The *SAN*, `subjectAltNames`, is the following form: + +```bash +..cluster.local +``` + +With the above OSM mesh config changed, that secret will be created in the `osm-system` namespace. +There will also be the `osm-ca-bundle` secret as well, which is autogenerated by OSM. + +```bash +kubectl get secrets -n osm-system +NAME TYPE DATA AGE +osm-ca-bundle Opaque 2 37m +osm-nginx-client-cert kubernetes.io/tls 3 17m +``` + +Now, we need to "export" out these certificates in order to use them with NGINX Ingress Controller. + +```bash +kubectl get secret osm-ca-bundle -n osm-system -o yaml > osm-ca-bundle-secret.yaml +kubectl get secret osm-nginx-client-cert -n osm-system -o yaml > osm-nginx-client-cert.yaml +``` + + +We need to edit the two exported out .yaml files and change a few parts. + +Edit `osm-ca-bundle-secret.yaml` +Remove the `private.key` section under `data.` +Change the `namespace` field to your nginx-ingress location +Change the `type` to `type: nginx.org/ca` + +Updated file should look like the following. +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: osm-ca-bundle + namespace: nginx-ingress +type: nginx.org/ca +data: + ca.crt: +``` + +Edit `osm-nginx-client-cert.yaml` +Remove the `ca.crt` in the `data` section +Change the namespace to the nginx-ingress namespace. + +Updated file should look like the following. + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: osm-nginx-client-cert + namespace: nginx-ingress +type: kubernetes.io/tls +data: + tls.crt: + tls.key: +``` + +Then apply these two secrets to the cluster. + +```bash +kubectl apply -f osm-ca-bundle-secret.yaml +kubectl apply -f osm-nginx-client-cert.yaml + +``` +Ensure the secrets exisit in the `nginx-ingress` namespace: + +```bash +kubectl get secrets -n nginx-ingress +NAME TYPE DATA AGE +osm-nginx-client-cert kubernetes.io/tls 2 23m +osm-ca-bundle nginx.org/ca 1 23m +``` + +We now need to create our CRDs (virtualServer and policy). +Here is the `policy` resource that holds the mTLS information. +Make sure you apply the `policy` or the mTLS connection will not work. (required for virtualServer) + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: Policy +metadata: + name: osm-mtls + namespace: nginx-ingress +spec: + egressMTLS: + tlsSecret: osm-nginx-client-cert + trustedCertSecret: osm-ca-bundle + verifyDepth: 2 + verifyServer: on + sslName: httpbin.httpbin.cluster.local +``` + +Here is an example `virtualServer` resource as well as the `ingressBackend`. + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: VirtualServer +metadata: + name: httpbin + namespace: httpbin +spec: + policies: + - name: osm-mtls + namespace: nginx-ingress + host: httpbin.example.com + tls: + secret: secret01 + upstreams: + - name: httpbin + service: httpbin + port: 14001 + tls: + enable: true + routes: + - path: / + action: + pass: httpbin +--- +kind: IngressBackend +apiVersion: policy.openservicemesh.io/v1alpha1 +metadata: + name: httpbin + namespace: httpbin +spec: + backends: + - name: httpbin + port: + number: 14001 # targetPort of httpbin service + protocol: https + tls: + skipClientCertValidation: false + sources: + - kind: Service + namespace: nginx-ingress + name: nginx-ingress + - kind: AuthenticatedPrincipal + name: nginx-ingress.nginx-ingress.cluster.local +``` + +Once these are applied, verify they are valid (virtualServer) and committed (ingressBackend): + +```bash +kubectl get vs,ingressbackend -A +NAMESPACE NAME STATE HOST IP PORTS AGE +httpbin virtualserver.k8s.nginx.org/httpbin Valid httpbin.example.com 26m + +NAMESPACE NAME STATUS +httpbin ingressbackend.policy.openservicemesh.io/httpbin committed +``` + +You can now send traffic through NGINX Ingress Controller with open service mesh. + +```bash +curl http://httpbin.example.com/get -v +* Trying 172.18.0.2:80... +* TCP_NODELAY set +* Connected to httpbin.example.com (172.18.0.2) port 80 (#0) +> GET /get HTTP/1.1 +> Host: httpbin.example.com +> User-Agent: curl/7.68.0 +> Accept: */* +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< Server: nginx/1.23.3 +< Date: Sat, 18 Feb 2023 22:41:27 GMT +< Content-Type: application/json +< Content-Length: 280 +< Connection: keep-alive +< access-control-allow-origin: * +< access-control-allow-credentials: true +< x-envoy-upstream-service-time: 1 +< +{ + "args": {}, + "headers": { + "Accept": "*/*", + "Host": "httpbin.example.com", + "User-Agent": "curl/7.68.0", + "X-Envoy-Internal": "true", + "X-Forwarded-Host": "httpbin.example.com" + }, + "origin": "172.18.0.1", + "url": "http://httpbin.example.com/get" +} +* Connection #0 to host httpbin.example.com left intact +``` + From 3cdd03b3fa294504384f17d0b120439553b3e513 Mon Sep 17 00:00:00 2001 From: Jason Williams Date: Wed, 22 Mar 2023 19:51:34 -0700 Subject: [PATCH 11/25] Updated helm install directions. --- docs/content/tutorials/nginx-ingress-osm.md | 447 ++++++++++++++++++++ 1 file changed, 447 insertions(+) create mode 100644 docs/content/tutorials/nginx-ingress-osm.md diff --git a/docs/content/tutorials/nginx-ingress-osm.md b/docs/content/tutorials/nginx-ingress-osm.md new file mode 100644 index 0000000000..ced588437c --- /dev/null +++ b/docs/content/tutorials/nginx-ingress-osm.md @@ -0,0 +1,447 @@ +## This document outlines how to integrate F5 NGINX Ingress Controller with Open Service Mesh (OSM) + +Open Service Mesh will work with both versions of [F5 NGINX Ingress controller](https://github.com/nginxinc/kubernetes-ingress): the free as well as the NGINX Plus versions. + +Below is a link to the official F5 NGINX Ingress controller documentation. +[F5 NGINX Ingress controller](https://docs.nginx.com/nginx-ingress-controller/) + +# Integrating NGINX Ingress Controller with Open Service Mesh + +There are two ways to integrate the NGINX Ingress Controller with Open Service Mesh (OSM): + +1. Injecting an envoy sidecar directly with NGINX Ingress Controller. +2. Using the Open Service Mesh `ingressBackend` "proxy" feature. + + +# NGINX Ingress controller and OSM with sidecar injected + +Install OSM in the cluster + +```bash +osm install --mesh-name osm-nginx --osm-namespace osm-system +``` + +### Mark F5 NGINX Ingress controller namespace for sidecar injection + +*NOTE:* Depending on how you install NGINX Ingress controller, you might need to create the `namespace`. For example, if you are using manifests to install NGINX Ingress controller, you can complete all of the steps on our documentation page, *EXCEPT*, actually deploying NGINX Ingress controller. This is because, when using the sidecar approach, OSM needs to "manage" the namespace so it knows what `namespaces` it needs to inject sidecars into. + +Next thing we need to do is install OSM into the `NGINX Ingress controller` namespace so that the `envoy` sidecar will be injected into NGINX Ingress controller. +First, create the `nginx-ingress` namespace: + +```bash +kubectl create ns nginx-ingress +``` +Then "mark" the `nginx-ingress` namespace for OSM to deploy a sidecar. + +```bash +osm namespace add nginx-ingress --mesh-name osm-nginx +``` + +The above command will use the mark the `nginx-ingress` namespace, where OSM will be installed (sidecar) + +# Install F5 NGINX Ingress controller. Here the links to the install guides: + +[Using Helm to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) +[Using Manifests to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) + + +When using the sidecar method, ensure that you add the correct annotations listed below. This ensures proper integration of NGINX Ingress Controller with the envoy sidecar proxy. + +## Helm installs + +If using `helm`, add the following `annotation` to your `values.yaml` file: + + +Under `controller.pod.annotations`: + +```yaml +pod: + annotations: { + openservicemesh.io/inbound-port-exclusion-list: "80, 443" + } +``` + +You can also use the `set` command available with `helm` to set these at install time. + +```bash +helm install nic01 nginx-stable/nginx-ingress -n nginx-ingress --create-namespace --set controller.pod.annotations.'openservicemesh\.io/inbound\-port\-exclusion\-list=\{ "80"\, "443"\ }' +``` + +Change your `release` accordingly to match your environment. + + +## Manifest installs + +For your `manifest` deployments, add the following `annotation`. + +```yaml +annotations: + openservicemesh.io/inbound-port-exclusion-list: "80,443" +``` + +### Sample deployment file with annotation required + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-ingress + namespace: nginx-ingress +spec: + replicas: 1 + selector: + matchLabels: + app: nginx-ingress + template: + metadata: + labels: + app: nginx-ingress + annotations: + openservicemesh.io/inbound-port-exclusion-list: "80,443" +``` + +This annotation is *required* when injecting envoy sidecar into NGINX Ingress controller. +`InboundPortExclusionList` defines a global list of ports to exclude from inbound traffic interception by the sidecar proxy. + +### Install a Test Application +To test the integration, we will use the `httpbin` sample application from the [Ingress With Kubernetes NGINX Ingress Controller](https://release-v1-2.docs.openservicemesh.io/docs/demos/ingress_k8s_nginx/) guide. + +The following three commands will create the namespace for the application, add the namespace to OSM for monitoring, then install the application. + +```bash +kubectl create ns httpbin +osm namespace add httpbin --mesh-name osm-nginx +kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm-docs/release-v1.2/manifests/samples/httpbin/httpbin.yaml -n httpbin +``` + +### Verify that the envoy sidecar has been *injected* into NGINX Ingress + +```bash +kubectl get pods -n nginx-ingress +NAME READY STATUS RESTARTS AGE +nginx-ingress-7b9557ddc6-zw7l5 2/2 Running 1 (5m8s ago) 5m19s +``` + +2/2 shows we have two containers in the NGINX Ingress controller pod: NGINX Ingress and Envoy + + +Configure your NGINX VirtualServer yaml to similar below + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: VirtualServer +metadata: + name: httpbin + namespace: httpbin +spec: + host: httpbin.example.com + tls: + secret: secret01 + upstreams: + - name: httpbin + service: httpbin + port: 14001 + use-cluster-ip: true + routes: + - path: / + action: + proxy: + upstream: httpbin + requestHeaders: + set: + - name: Host + value: httpbin.httpbin.svc.cluster.local +``` + +Test your configuration: + +```bash + curl http://httpbin.example.com/get -v +* Trying 172.19.0.2:80... +* TCP_NODELAY set +* Connected to httpbin.example.com (172.19.0.2) port 80 (#0) +> GET /get HTTP/1.1 +> Host: httpbin.example.com +> User-Agent: curl/7.68.0 +> Accept: */* +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< Server: nginx/1.23.3 +< Date: Sun, 19 Feb 2023 19:06:47 GMT +< Content-Type: application/json +< Content-Length: 454 +< Connection: keep-alive +< access-control-allow-origin: * +< access-control-allow-credentials: true +< x-envoy-upstream-service-time: 2 +< +{ + "args": {}, + "headers": { + "Accept": "*/*", + "Host": "httpbin.httpbin.svc.cluster.local", + "Osm-Stats-Kind": "Deployment", + "Osm-Stats-Name": "httpbin", + "Osm-Stats-Namespace": "httpbin", + "Osm-Stats-Pod": "httpbin-78555f5c4b-t6qln", + "User-Agent": "curl/7.68.0", + "X-Envoy-Internal": "true", + "X-Forwarded-Host": "httpbin.example.com" + }, + "origin": "172.19.0.1", + "url": "http://httpbin.example.com/get" +} +* Connection #0 to host httpbin.example.com left intact +``` + + + +## Using The Open Service Mesh `ingressBackend` "proxy" Feature + +Install OSM into cluster. +By running the following command, you will install OSM into the cluster with the mesh name `osm-nginx` using the `osm-system` namespace. + +```bash +osm install --mesh-name osm-nginx --osm-namespace osm-system +``` + +Once OSM has been installed, this next command will mark the NGINX Ingress Controller as part of the OSM mesh, while also disabling sidecar injection. +*NOTE*: The nginx-ingress name can be created as part of the NGINX Ingress install process, or manually. It must be created before you "add" the namespace to nginx-ingress. + +```bash +osm namespace add nginx-ingress --mesh-name osm-nginx --disable-sidecar-injection +``` + +# You can now install NGINX Ingress Controller by one of th above methods listed: `helm` or `manifetsts`. +*NOTE*: This method does NOT require annotations added to the deployment. + +### Install a Test Application + +To test the integration, we will use the `httpbin` sample application from the [Ingress With Kubernetes NGINX Ingress Controller](https://release-v1-2.docs.openservicemesh.io/docs/demos/ingress_k8s_nginx/) guide. + +The following three commands will create the namespace for the application, add the namespace to OSM for monitoring, then install the application. + +```bash +kubectl create ns httpbin +osm namespace add httpbin --mesh-name osm-nginx +kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm-docs/release-v1.2/manifests/samples/httpbin/httpbin.yaml -n httpbin +``` + +### mTLS Setup + +To enable mTLS for NGINX Ingress Controller and OSM, you need to configure the `IngressBackend` API to use `https` as the backend protocol as and trigger OSM to issue a certificate. NGINX will use this certificate to proxy HTTPS connections to the TLS backends. The client certificate and certificate authority (CA) certificate will be stored in a Kubernetes secret that NGINX will use for authentication." + +To begin, edit the `osm-mesh-config` resource: + +```bash +kubectl edit meshconfig osm-mesh-config -n osm-system +``` + +You will need to update under `certificate` to look like this: + +```yaml +spec: + certificate: + ingressGateway: + secret: + name: osm-nginx-client-cert + namespace: osm-system + subjectAltNames: + - nginx-ingress.nginx-ingress.cluster.local + validityDuration: 24h +``` + +This will generate a new client certificate (osm-nginx-client-cert) that NGINX Ingress controller will use for mTLS. +The *SAN*, `subjectAltNames`, is the following form: + +```bash +..cluster.local +``` + +With the above OSM mesh config changed, that secret will be created in the `osm-system` namespace. +There will also be the `osm-ca-bundle` secret as well, which is autogenerated by OSM. + +```bash +kubectl get secrets -n osm-system +NAME TYPE DATA AGE +osm-ca-bundle Opaque 2 37m +osm-nginx-client-cert kubernetes.io/tls 3 17m +``` + +Now, we need to "export" out these certificates in order to use them with NGINX Ingress Controller. + +```bash +kubectl get secret osm-ca-bundle -n osm-system -o yaml > osm-ca-bundle-secret.yaml +kubectl get secret osm-nginx-client-cert -n osm-system -o yaml > osm-nginx-client-cert.yaml +``` + + +We need to edit the two exported out .yaml files and change a few parts. + +Edit `osm-ca-bundle-secret.yaml` +Remove the `private.key` section under `data.` +Change the `namespace` field to your nginx-ingress location +Change the `type` to `type: nginx.org/ca` + +Updated file should look like the following. +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: osm-ca-bundle + namespace: nginx-ingress +type: nginx.org/ca +data: + ca.crt: +``` + +Edit `osm-nginx-client-cert.yaml` +Remove the `ca.crt` in the `data` section +Change the namespace to the nginx-ingress namespace. + +Updated file should look like the following. + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: osm-nginx-client-cert + namespace: nginx-ingress +type: kubernetes.io/tls +data: + tls.crt: + tls.key: +``` + +Then apply these two secrets to the cluster. + +```bash +kubectl apply -f osm-ca-bundle-secret.yaml +kubectl apply -f osm-nginx-client-cert.yaml + +``` +Ensure the secrets exisit in the `nginx-ingress` namespace: + +```bash +kubectl get secrets -n nginx-ingress +NAME TYPE DATA AGE +osm-nginx-client-cert kubernetes.io/tls 2 23m +osm-ca-bundle nginx.org/ca 1 23m +``` + +We now need to create our CRDs (virtualServer and policy). +Here is the `policy` resource that holds the mTLS information. +Make sure you apply the `policy` or the mTLS connection will not work. (required for virtualServer) + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: Policy +metadata: + name: osm-mtls + namespace: nginx-ingress +spec: + egressMTLS: + tlsSecret: osm-nginx-client-cert + trustedCertSecret: osm-ca-bundle + verifyDepth: 2 + verifyServer: on + sslName: httpbin.httpbin.cluster.local +``` + +Here is an example `virtualServer` resource as well as the `ingressBackend`. + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: VirtualServer +metadata: + name: httpbin + namespace: httpbin +spec: + policies: + - name: osm-mtls + namespace: nginx-ingress + host: httpbin.example.com + tls: + secret: secret01 + upstreams: + - name: httpbin + service: httpbin + port: 14001 + tls: + enable: true + routes: + - path: / + action: + pass: httpbin +--- +kind: IngressBackend +apiVersion: policy.openservicemesh.io/v1alpha1 +metadata: + name: httpbin + namespace: httpbin +spec: + backends: + - name: httpbin + port: + number: 14001 # targetPort of httpbin service + protocol: https + tls: + skipClientCertValidation: false + sources: + - kind: Service + namespace: nginx-ingress + name: nginx-ingress + - kind: AuthenticatedPrincipal + name: nginx-ingress.nginx-ingress.cluster.local +``` + +Once these are applied, verify they are valid (virtualServer) and committed (ingressBackend): + +```bash +kubectl get vs,ingressbackend -A +NAMESPACE NAME STATE HOST IP PORTS AGE +httpbin virtualserver.k8s.nginx.org/httpbin Valid httpbin.example.com 26m + +NAMESPACE NAME STATUS +httpbin ingressbackend.policy.openservicemesh.io/httpbin committed +``` + +You can now send traffic through NGINX Ingress Controller with open service mesh. + +```bash +curl http://httpbin.example.com/get -v +* Trying 172.18.0.2:80... +* TCP_NODELAY set +* Connected to httpbin.example.com (172.18.0.2) port 80 (#0) +> GET /get HTTP/1.1 +> Host: httpbin.example.com +> User-Agent: curl/7.68.0 +> Accept: */* +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< Server: nginx/1.23.3 +< Date: Sat, 18 Feb 2023 22:41:27 GMT +< Content-Type: application/json +< Content-Length: 280 +< Connection: keep-alive +< access-control-allow-origin: * +< access-control-allow-credentials: true +< x-envoy-upstream-service-time: 1 +< +{ + "args": {}, + "headers": { + "Accept": "*/*", + "Host": "httpbin.example.com", + "User-Agent": "curl/7.68.0", + "X-Envoy-Internal": "true", + "X-Forwarded-Host": "httpbin.example.com" + }, + "origin": "172.18.0.1", + "url": "http://httpbin.example.com/get" +} +* Connection #0 to host httpbin.example.com left intact +``` + From 7a84e6d253d40960c06a45068824aa6426f74724 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 23 Mar 2023 02:53:43 +0000 Subject: [PATCH 12/25] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- .../tutorials/f5_nginx_ingress_controller.md | 15 +++++++-------- docs/content/tutorials/nginx-ingress-osm.md | 17 ++++++++--------- 2 files changed, 15 insertions(+), 17 deletions(-) diff --git a/docs/content/tutorials/f5_nginx_ingress_controller.md b/docs/content/tutorials/f5_nginx_ingress_controller.md index 91943aef62..d1a44e2081 100644 --- a/docs/content/tutorials/f5_nginx_ingress_controller.md +++ b/docs/content/tutorials/f5_nginx_ingress_controller.md @@ -2,7 +2,7 @@ Open Service Mesh will work with both versions of [F5 NGINX Ingress controller](https://github.com/nginxinc/kubernetes-ingress): the free as well as the NGINX Plus versions. -Below is a link to the official F5 NGINX Ingress controller documentation. +Below is a link to the official F5 NGINX Ingress controller documentation. [F5 NGINX Ingress controller](https://docs.nginx.com/nginx-ingress-controller/) # Integrating NGINX Ingress Controller with Open Service Mesh @@ -13,7 +13,7 @@ There are two ways to integrate the NGINX Ingress Controller with Open Service M 2. Using the Open Service Mesh `ingressBackend` "proxy" feature. -# NGINX Ingress controller and OSM with sidecar injected +# NGINX Ingress controller and OSM with sidecar injected Install OSM in the cluster @@ -41,8 +41,8 @@ The above command will use the mark the `nginx-ingress` namespace, where OSM wil # Istall F5 NGINX Ingress controller. Here the links to the install guides: -[Using Helm to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) -[Using Manifests to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) +[Using Helm to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) +[Using Manifests to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) When using the sidecar method, ensure that you add the correct annotations listed below. This ensures proper integration of NGINX Ingress Controller with the envoy sidecar proxy. @@ -50,8 +50,8 @@ When using the sidecar method, ensure that you add the correct annotations liste If using `helm`, add the following `annotation` to your `values.yaml` file: ```yaml - annotations: { - openservicemesh.io/inbound-port-exclusion-list: "80, 443" + annotations: { + openservicemesh.io/inbound-port-exclusion-list: "80, 443" } ``` @@ -125,7 +125,7 @@ spec: upstreams: - name: httpbin service: httpbin - port: 14001 + port: 14001 use-cluster-ip: true routes: - path: / @@ -426,4 +426,3 @@ curl http://httpbin.example.com/get -v } * Connection #0 to host httpbin.example.com left intact ``` - diff --git a/docs/content/tutorials/nginx-ingress-osm.md b/docs/content/tutorials/nginx-ingress-osm.md index ced588437c..64d8586c6e 100644 --- a/docs/content/tutorials/nginx-ingress-osm.md +++ b/docs/content/tutorials/nginx-ingress-osm.md @@ -2,7 +2,7 @@ Open Service Mesh will work with both versions of [F5 NGINX Ingress controller](https://github.com/nginxinc/kubernetes-ingress): the free as well as the NGINX Plus versions. -Below is a link to the official F5 NGINX Ingress controller documentation. +Below is a link to the official F5 NGINX Ingress controller documentation. [F5 NGINX Ingress controller](https://docs.nginx.com/nginx-ingress-controller/) # Integrating NGINX Ingress Controller with Open Service Mesh @@ -13,7 +13,7 @@ There are two ways to integrate the NGINX Ingress Controller with Open Service M 2. Using the Open Service Mesh `ingressBackend` "proxy" feature. -# NGINX Ingress controller and OSM with sidecar injected +# NGINX Ingress controller and OSM with sidecar injected Install OSM in the cluster @@ -41,8 +41,8 @@ The above command will use the mark the `nginx-ingress` namespace, where OSM wil # Install F5 NGINX Ingress controller. Here the links to the install guides: -[Using Helm to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) -[Using Manifests to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) +[Using Helm to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) +[Using Manifests to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) When using the sidecar method, ensure that you add the correct annotations listed below. This ensures proper integration of NGINX Ingress Controller with the envoy sidecar proxy. @@ -56,15 +56,15 @@ Under `controller.pod.annotations`: ```yaml pod: - annotations: { - openservicemesh.io/inbound-port-exclusion-list: "80, 443" + annotations: { + openservicemesh.io/inbound-port-exclusion-list: "80, 443" } ``` You can also use the `set` command available with `helm` to set these at install time. ```bash -helm install nic01 nginx-stable/nginx-ingress -n nginx-ingress --create-namespace --set controller.pod.annotations.'openservicemesh\.io/inbound\-port\-exclusion\-list=\{ "80"\, "443"\ }' +helm install nic01 nginx-stable/nginx-ingress -n nginx-ingress --create-namespace --set controller.pod.annotations.'openservicemesh\.io/inbound\-port\-exclusion\-list=\{ "80"\, "443"\ }' ``` Change your `release` accordingly to match your environment. @@ -140,7 +140,7 @@ spec: upstreams: - name: httpbin service: httpbin - port: 14001 + port: 14001 use-cluster-ip: true routes: - path: / @@ -444,4 +444,3 @@ curl http://httpbin.example.com/get -v } * Connection #0 to host httpbin.example.com left intact ``` - From ceee82765c6930b1214aa60a1396ab712ae8f3b8 Mon Sep 17 00:00:00 2001 From: Jason Williams Date: Thu, 23 Mar 2023 12:21:15 -0700 Subject: [PATCH 13/25] Update NIC with OSM tutorial doc --- .../tutorials/f5_nginx_ingress_controller.md | 428 ------------- docs/content/tutorials/nginx-ingress-osm.md | 17 +- docs/content/tutorials/nic-osm.md | 569 ------------------ 3 files changed, 9 insertions(+), 1005 deletions(-) delete mode 100644 docs/content/tutorials/f5_nginx_ingress_controller.md delete mode 100644 docs/content/tutorials/nic-osm.md diff --git a/docs/content/tutorials/f5_nginx_ingress_controller.md b/docs/content/tutorials/f5_nginx_ingress_controller.md deleted file mode 100644 index d1a44e2081..0000000000 --- a/docs/content/tutorials/f5_nginx_ingress_controller.md +++ /dev/null @@ -1,428 +0,0 @@ -## This document outlines how to integrate F5 NGINX Ingress Controller with Open Service Mesh (OSM) - -Open Service Mesh will work with both versions of [F5 NGINX Ingress controller](https://github.com/nginxinc/kubernetes-ingress): the free as well as the NGINX Plus versions. - -Below is a link to the official F5 NGINX Ingress controller documentation. -[F5 NGINX Ingress controller](https://docs.nginx.com/nginx-ingress-controller/) - -# Integrating NGINX Ingress Controller with Open Service Mesh - -There are two ways to integrate the NGINX Ingress Controller with Open Service Mesh (OSM): - -1. Injecting an envoy sidecar directly with NGINX Ingress Controller. -2. Using the Open Service Mesh `ingressBackend` "proxy" feature. - - -# NGINX Ingress controller and OSM with sidecar injected - -Install OSM in the cluster - -```bash -osm install --mesh-name osm-nginx --osm-namespace osm-system -``` - -### Mark F5 NGINX Ingress controller namespace for sidecar injection - -*NOTE:* Depending on how you install NGINX Ingress controller, you might need to create the `namespae`. For example, if you are using manifests to install NGINX Ingress controller, you can complete all of the steps on our documentation page, *EXCEPT*, actually deploying NGINX Ingress controller. This is because, when using the sidecar approach, OSM needs to "manage" the namespace so it knows what `namespaces` it needs to inject sidecars into. - -Next thing we need to do is install OSM into the `NGINX Ingress controller` namespace so that the `envoy` sidecar will be injected into NGINX Ingress controller. -First, create the `nginx-ingress` namespace: - -```bash -kubectl get ns nginx-ingress -``` -Then "mark" the `nginx-ingress` namespace for OSM to deploy a sidecar. - -```bash -osm namespace add nginx-ingress --mesh-name osm-nginx -``` - -The above command will use the mark the `nginx-ingress` namespace, where OSM will be installed (sidecar) - -# Istall F5 NGINX Ingress controller. Here the links to the install guides: - -[Using Helm to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) -[Using Manifests to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) - - -When using the sidecar method, ensure that you add the correct annotations listed below. This ensures proper integration of NGINX Ingress Controller with the envoy sidecar proxy. - -If using `helm`, add the following `annotation` to your `values.yaml` file: - -```yaml - annotations: { - openservicemesh.io/inbound-port-exclusion-list: "80, 443" - } -``` - -At a minimum, the following annotation needs to be set on your deployment: - -```yaml -annotations: - openservicemesh.io/inbound-port-exclusion-list: "80,443" -``` - -### Install a Test Application -To test the integration, we will use the `httpbin` sample application from the [Ingress With Kubernetes NGINX Ingress Controller](https://release-v1-2.docs.openservicemesh.io/docs/demos/ingress_k8s_nginx/) guide. - -The following three commands will create the namespace for the application, add the namespace to OSM for monitoring, then install the application. - -```bash -kubectl create ns httpbin -osm namespace add httpbin --mesh-name osm-nginx -kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm-docs/release-v1.2/manifests/samples/httpbin/httpbin.yaml -n httpbin -``` - -### Add required annotations to NGINX Ingress Controller deployment: - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: nginx-ingress - namespace: nginx-ingress -spec: - replicas: 1 - selector: - matchLabels: - app: nginx-ingress - template: - metadata: - labels: - app: nginx-ingress - annotations: - openservicemesh.io/inbound-port-exclusion-list: "80,443" -``` - -This annotation is *required* when injecting envoy sidecar into NGINX Ingress controller. - -`InboundPortExclusionList` defines a global list of ports to exclude from inbound traffic interception by the sidecar proxy. - - -### Verify that the envoy sidecar has been *injected* into NGINX Ingress - -```bash -kubectl get pods -n nginx-ingress -NAME READY STATUS RESTARTS AGE -nginx-ingress-7b9557ddc6-zw7l5 2/2 Running 1 (5m8s ago) 5m19s -``` - -2/2 shows we have two containers in the NGINX Ingress controller pod: NGINX Ingress and Envoy - - -Configure your NGINX VirtualServer yaml to similar below - -```yaml -apiVersion: k8s.nginx.org/v1 -kind: VirtualServer -metadata: - name: httpbin - namespace: httpbin -spec: - host: httpbin.example.com - tls: - secret: secret01 - upstreams: - - name: httpbin - service: httpbin - port: 14001 - use-cluster-ip: true - routes: - - path: / - action: - proxy: - upstream: httpbin - requestHeaders: - set: - - name: Host - value: httpbin.httpbin.svc.cluster.local -``` - -Test your configuration: - -```bash - curl http://httpbin.example.com/get -v -* Trying 172.19.0.2:80... -* TCP_NODELAY set -* Connected to httpbin.example.com (172.19.0.2) port 80 (#0) -> GET /get HTTP/1.1 -> Host: httpbin.example.com -> User-Agent: curl/7.68.0 -> Accept: */* -> -* Mark bundle as not supporting multiuse -< HTTP/1.1 200 OK -< Server: nginx/1.23.3 -< Date: Sun, 19 Feb 2023 19:06:47 GMT -< Content-Type: application/json -< Content-Length: 454 -< Connection: keep-alive -< access-control-allow-origin: * -< access-control-allow-credentials: true -< x-envoy-upstream-service-time: 2 -< -{ - "args": {}, - "headers": { - "Accept": "*/*", - "Host": "httpbin.httpbin.svc.cluster.local", - "Osm-Stats-Kind": "Deployment", - "Osm-Stats-Name": "httpbin", - "Osm-Stats-Namespace": "httpbin", - "Osm-Stats-Pod": "httpbin-78555f5c4b-t6qln", - "User-Agent": "curl/7.68.0", - "X-Envoy-Internal": "true", - "X-Forwarded-Host": "httpbin.example.com" - }, - "origin": "172.19.0.1", - "url": "http://httpbin.example.com/get" -} -* Connection #0 to host httpbin.example.com left intact -``` - - - -## Using The Open Service Mesh `ingressBackend` "proxy" Feature - -Install OSM into cluster. -By running the following command, you will install OSM into the cluster with the mesh name `osm-nginx` using the `osm-system` namespace. - -```bash -osm install --mesh-name osm-nginx --osm-namespace osm-system -``` - -Once OSM has been installed, this next command will mark the NGINX Ingress Controller as part of the OSM mesh, while also disabling sidecar injection. -*NOTE*: The nginx-ingress name can be created as part of the NGINX Ingress install process, or manually. It must be created before you "add" the namespace to nginx-ingress. - -```bash -osm namespace add nginx-ingress --mesh-name osm-nginx --disable-sidecar-injection -``` - -### Install a Test Application - -To test the integration, we will use the `httpbin` sample application from the [Ingress With Kubernetes NGINX Ingress Controller](https://release-v1-2.docs.openservicemesh.io/docs/demos/ingress_k8s_nginx/) guide. - -The following three commands will create the namespace for the application, add the namespace to OSM for monitoring, then install the application. - -```bash -kubectl create ns httpbin -osm namespace add httpbin --mesh-name osm-nginx -kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm-docs/release-v1.2/manifests/samples/httpbin/httpbin.yaml -n httpbin -``` - -### mTLS Setup - -To enable mTLS for NGINX Ingress Controller and OSM, you need to configure the `IngressBackend` API to use `https` as the backend protocol as and trigger OSM to issue a certificate. NGINX will use this certificate to proxy HTTPS connections to the TLS backends. The client certificate and certificate authority (CA) certificate will be stored in a Kubernetes secret that NGINX will use for authentication."* - -To begin, edit the `osm-mesh-config` resource: - -```bash -kubectl edit meshconfig osm-mesh-config -n osm-system -``` - -You will need to update under `certificate` to look like this: - -```yaml -spec: - certificate: - ingressGateway: - secret: - name: osm-nginx-client-cert - namespace: osm-system - subjectAltNames: - - nginx-ingress.nginx-ingress.cluster.local - validityDuration: 24h -``` - -This will generate a new client certificate (osm-nginx-client-cert) that NGINX Ingress controller will use for mTLS. -The *SAN*, `subjectAltNames`, is the following form: - -```bash -..cluster.local -``` - -With the above OSM mesh config changed, that secret will be created in the `osm-system` namespace. -There will also be the `osm-ca-bundle` secret as well, which is autogenerated by OSM. - -```bash -kubectl get secrets -n osm-system -NAME TYPE DATA AGE -osm-ca-bundle Opaque 2 37m -osm-nginx-client-cert kubernetes.io/tls 3 17m -``` - -Now, we need to "export" out these certificates in order to use them with NGINX Ingress Controller. - -```bash -kubectl get secret osm-ca-bundle -n osm-system -o yaml > osm-ca-bundle-secret.yaml -kubectl get secret osm-nginx-client-cert -n osm-system -o yaml > osm-nginx-client-cert.yaml -``` - - -We need to edit the two exported out .yaml files and change a few parts. - -Edit `osm-ca-bundle-secret.yaml` -Remove the `private.key` section under `data.` -Change the `namespace` field to your nginx-ingress location -Change the `type` to `type: nginx.org/ca` - -Updated file should look like the following. -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: osm-ca-bundle - namespace: nginx-ingress -type: nginx.org/ca -data: - ca.crt: -``` - -Edit `osm-nginx-client-cert.yaml` -Remove the `ca.crt` in the `data` section -Change the namespace to the nginx-ingress namespace. - -Updated file should look like the following. - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: osm-nginx-client-cert - namespace: nginx-ingress -type: kubernetes.io/tls -data: - tls.crt: - tls.key: -``` - -Then apply these two secrets to the cluster. - -```bash -kubectl apply -f osm-ca-bundle-secret.yaml -kubectl apply -f osm-nginx-client-cert.yaml - -``` -Ensure the secrets exisit in the `nginx-ingress` namespace: - -```bash -kubectl get secrets -n nginx-ingress -NAME TYPE DATA AGE -osm-nginx-client-cert kubernetes.io/tls 2 23m -osm-ca-bundle nginx.org/ca 1 23m -``` - -We now need to create our CRDs (virtualServer and policy). -Here is the `policy` resource that holds the mTLS information. -Make sure you apply the `policy` or the mTLS connection will not work. (required for virtualServer) - -```yaml -apiVersion: k8s.nginx.org/v1 -kind: Policy -metadata: - name: osm-mtls - namespace: nginx-ingress -spec: - egressMTLS: - tlsSecret: osm-nginx-client-cert - trustedCertSecret: osm-ca-bundle - verifyDepth: 2 - verifyServer: on - sslName: httpbin.httpbin.cluster.local -``` - -Here is an example `virtualServer` resource as well as the `ingressBackend`. - -```yaml -apiVersion: k8s.nginx.org/v1 -kind: VirtualServer -metadata: - name: httpbin - namespace: httpbin -spec: - policies: - - name: osm-mtls - namespace: nginx-ingress - host: httpbin.example.com - tls: - secret: secret01 - upstreams: - - name: httpbin - service: httpbin - port: 14001 - tls: - enable: true - routes: - - path: / - action: - pass: httpbin ---- -kind: IngressBackend -apiVersion: policy.openservicemesh.io/v1alpha1 -metadata: - name: httpbin - namespace: httpbin -spec: - backends: - - name: httpbin - port: - number: 14001 # targetPort of httpbin service - protocol: https - tls: - skipClientCertValidation: false - sources: - - kind: Service - namespace: nginx-ingress - name: nginx-ingress - - kind: AuthenticatedPrincipal - name: nginx-ingress.nginx-ingress.cluster.local -``` - -Once these are applied, verify they are valid (virtualServer) and committed (ingressBackend): - -```bash -kubectl get vs,ingressbackend -A -NAMESPACE NAME STATE HOST IP PORTS AGE -httpbin virtualserver.k8s.nginx.org/httpbin Valid httpbin.example.com 26m - -NAMESPACE NAME STATUS -httpbin ingressbackend.policy.openservicemesh.io/httpbin committed -``` - -You can now send traffic through NGINX Ingress Controller with open service mesh. - -```bash -curl http://httpbin.example.com/get -v -* Trying 172.18.0.2:80... -* TCP_NODELAY set -* Connected to httpbin.example.com (172.18.0.2) port 80 (#0) -> GET /get HTTP/1.1 -> Host: httpbin.example.com -> User-Agent: curl/7.68.0 -> Accept: */* -> -* Mark bundle as not supporting multiuse -< HTTP/1.1 200 OK -< Server: nginx/1.23.3 -< Date: Sat, 18 Feb 2023 22:41:27 GMT -< Content-Type: application/json -< Content-Length: 280 -< Connection: keep-alive -< access-control-allow-origin: * -< access-control-allow-credentials: true -< x-envoy-upstream-service-time: 1 -< -{ - "args": {}, - "headers": { - "Accept": "*/*", - "Host": "httpbin.example.com", - "User-Agent": "curl/7.68.0", - "X-Envoy-Internal": "true", - "X-Forwarded-Host": "httpbin.example.com" - }, - "origin": "172.18.0.1", - "url": "http://httpbin.example.com/get" -} -* Connection #0 to host httpbin.example.com left intact -``` diff --git a/docs/content/tutorials/nginx-ingress-osm.md b/docs/content/tutorials/nginx-ingress-osm.md index 64d8586c6e..ced588437c 100644 --- a/docs/content/tutorials/nginx-ingress-osm.md +++ b/docs/content/tutorials/nginx-ingress-osm.md @@ -2,7 +2,7 @@ Open Service Mesh will work with both versions of [F5 NGINX Ingress controller](https://github.com/nginxinc/kubernetes-ingress): the free as well as the NGINX Plus versions. -Below is a link to the official F5 NGINX Ingress controller documentation. +Below is a link to the official F5 NGINX Ingress controller documentation. [F5 NGINX Ingress controller](https://docs.nginx.com/nginx-ingress-controller/) # Integrating NGINX Ingress Controller with Open Service Mesh @@ -13,7 +13,7 @@ There are two ways to integrate the NGINX Ingress Controller with Open Service M 2. Using the Open Service Mesh `ingressBackend` "proxy" feature. -# NGINX Ingress controller and OSM with sidecar injected +# NGINX Ingress controller and OSM with sidecar injected Install OSM in the cluster @@ -41,8 +41,8 @@ The above command will use the mark the `nginx-ingress` namespace, where OSM wil # Install F5 NGINX Ingress controller. Here the links to the install guides: -[Using Helm to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) -[Using Manifests to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) +[Using Helm to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) +[Using Manifests to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) When using the sidecar method, ensure that you add the correct annotations listed below. This ensures proper integration of NGINX Ingress Controller with the envoy sidecar proxy. @@ -56,15 +56,15 @@ Under `controller.pod.annotations`: ```yaml pod: - annotations: { - openservicemesh.io/inbound-port-exclusion-list: "80, 443" + annotations: { + openservicemesh.io/inbound-port-exclusion-list: "80, 443" } ``` You can also use the `set` command available with `helm` to set these at install time. ```bash -helm install nic01 nginx-stable/nginx-ingress -n nginx-ingress --create-namespace --set controller.pod.annotations.'openservicemesh\.io/inbound\-port\-exclusion\-list=\{ "80"\, "443"\ }' +helm install nic01 nginx-stable/nginx-ingress -n nginx-ingress --create-namespace --set controller.pod.annotations.'openservicemesh\.io/inbound\-port\-exclusion\-list=\{ "80"\, "443"\ }' ``` Change your `release` accordingly to match your environment. @@ -140,7 +140,7 @@ spec: upstreams: - name: httpbin service: httpbin - port: 14001 + port: 14001 use-cluster-ip: true routes: - path: / @@ -444,3 +444,4 @@ curl http://httpbin.example.com/get -v } * Connection #0 to host httpbin.example.com left intact ``` + diff --git a/docs/content/tutorials/nic-osm.md b/docs/content/tutorials/nic-osm.md deleted file mode 100644 index 4db762a512..0000000000 --- a/docs/content/tutorials/nic-osm.md +++ /dev/null @@ -1,569 +0,0 @@ -## This document outlines how to integrate F5 NGINX Ingress Controller with Open Service Mesh (OSM) - -Open Service Mesh works with both the free and NGINX Plus versions of the [F5 NGINX Ingress controller](https://github.com/nginxinc/kubernetes-ingress). - -Below is a link to the official NGINX Ingress Controller documentation. -[NGINX Ingress Controller](https://docs.nginx.com/nginx-ingress-controller/) - -# Integrating NGINX Ingress Controller with Open Service Mesh - -There are two ways to integrate the NGINX Ingress Controller with Open Service Mesh (OSM): - -1. Injecting an envoy sidecar directly with NGINX Ingress Controller. -2. Using the Open Service Mesh `ingressBackend` "proxy" feature. - -# First, install NGINX Ingress Controller into your cluster. - - -When using NGINX Ingress controller with thes sidecar method, you will want to ensure you are providing the correct annotation to your deployment. - -[Using Helm to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) -[Using manifests to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) - - -If you are using `helm`, make sure you pass in the correct `annotation` in this example: - -```yaml - annotations: { openservicemesh.io/inbound-port-exclusion-list: "80, 443" } -``` - -If you are using `manifests`, add the following line to the the deploment file: - -```yaml -annotations: - openservicemesh.io/inbound-port-exclusion-list: "80,443" -``` - - -# NGINX Ingress controller and OSM with sidecar injected - -First install OSM in the cluster - -```bash -osm install --mesh-name osm-nginx --osm-namespace osm-system -``` - -### Mark NGINX Ingress controller namespace for sidecar injection - -*NOTE:* Depending on how you install NGINX Ingress controller, you might need to create the `namespae`. For example, if you are using manifests to install NGINX Ingress controller, you can complete all of the steps on our documentation page, *EXCEPT*, actually deploying NGINX Ingress controller. This is because, when using the sidecar approach, OSM needs to "manage" the namespace so it knows what `namespaces` it needs to inject sidecars into. - -Next thing we need to do is install OSM into the `NGINX Ingress controller` namespace so that the `envoy` sidecar will be injected into NGINX Ingress controller. -First, create the `nginx-ingress` namespace: - -```bash -kubectl get ns nginx-ingress -``` -Then "mark" the `nginx-ingress` namespace for OSM to deploy a sidecar. - -```bash -osm namespace add nginx-ingress --mesh-name osm-nginx -``` - -The above command will use the mark the `nginx-ingress` namespace, where OSM will be installed (sidecar) - -### Install a Test Application -To test the integration, we will use the `httpbin` sample application from the [Ingress With Kubernetes NGINX Ingress Controller](https://release-v1-2.docs.openservicemesh.io/docs/demos/ingress_k8s_nginx/) guide. - -The following three commands will create the namespace for the application, add the namespace to OSM for monitoring, then install the application. - -```bash -kubectl create ns httpbin -osm namespace add httpbin --mesh-name osm-nginx -kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm-docs/release-v1.2/manifests/samples/httpbin/httpbin.yaml -n httpbin -``` - -### Add required annotations to NGINX Ingress Controller deployment: - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: nginx-ingress - namespace: nginx-ingress -spec: - replicas: 1 - selector: - matchLabels: - app: nginx-ingress - template: - metadata: - labels: - app: nginx-ingress - annotations: - openservicemesh.io/inbound-port-exclusion-list: "80,443" -``` - -This annotation is *required* when injecting envoy sidecar into NGINX Ingress controller. - -`InboundPortExclusionList` defines a global list of ports to exclude from inbound traffic interception by the sidecar proxy. - - -### Verify that the envoy sidecar has been *injected* into NGINX Ingress - -```bash -kubectl get pods -n nginx-ingress -NAME READY STATUS RESTARTS AGE -nginx-ingress-7b9557ddc6-zw7l5 2/2 Running 1 (5m8s ago) 5m19s -``` - -2/2 shows we have two containers in the NGINX Ingress controller pod: NGINX Ingress and Envoy - - -Configure your NGINX VirtualServer yaml definitions to similar configuration below. - -```yaml -apiVersion: k8s.nginx.org/v1 -kind: VirtualServer -metadata: - name: httpbin - namespace: httpbin -spec: - host: httpbin.example.com - tls: - secret: secret01 - upstreams: - - name: httpbin - service: httpbin - port: 14001 - use-cluster-ip: true - routes: - - path: / - action: - proxy: - upstream: httpbin - requestHeaders: - set: - - name: Host - value: httpbin.httpbin.svc.cluster.local -``` - -Test your configuration: - -```bash - curl http://httpbin.example.com/get -v -* Trying 172.19.0.2:80... -* TCP_NODELAY set -* Connected to httpbin.example.com (172.19.0.2) port 80 (#0) -> GET /get HTTP/1.1 -> Host: httpbin.example.com -> User-Agent: curl/7.68.0 -> Accept: */* -> -* Mark bundle as not supporting multiuse -< HTTP/1.1 200 OK -< Server: nginx/1.23.3 -< Date: Sun, 19 Feb 2023 19:06:47 GMT -< Content-Type: application/json -< Content-Length: 454 -< Connection: keep-alive -< access-control-allow-origin: * -< access-control-allow-credentials: true -< x-envoy-upstream-service-time: 2 -< -{ - "args": {}, - "headers": { - "Accept": "*/*", - "Host": "httpbin.httpbin.svc.cluster.local", - "Osm-Stats-Kind": "Deployment", - "Osm-Stats-Name": "httpbin", - "Osm-Stats-Namespace": "httpbin", - "Osm-Stats-Pod": "httpbin-78555f5c4b-t6qln", - "User-Agent": "curl/7.68.0", - "X-Envoy-Internal": "true", - "X-Forwarded-Host": "httpbin.example.com" - }, - "origin": "172.19.0.1", - "url": "http://httpbin.example.com/get" -} -* Connection #0 to host httpbin.example.com left intact -``` - -## Using The Open Service Mesh `IngressBackend` "proxy" Feature - -# NGINX Ingress Controller and Open Service Mesh with Sidecar Injection - -First, install OSM in the cluster. - -```bash -osm install --mesh-name osm-nginx --osm-namespace osm-system -``` - -### Mark the NGINX Ingress Controller namespace for Sidecar Injection - -*NOTE:* Depending on how you install NGINX Ingress Controller, you might need to create the `namespace`. For example, if you are using manifests to install NGINX Ingress Controller, you can complete all of the steps on [its documentation page](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/), *EXCEPT* for deploying NGINX Ingress Controller. When using the sidecar approach, OSM needs to "manage" the namespace so it knows what `namespaces` to inject sidecars into. - -The next step is to install OSM into the `NGINX Ingress Controller` namespace so the `envoy` sidecar will be injected into NGINX Ingress Controller. -First, create the `nginx-ingress` namespace: - -```bash -kubectl get ns nginx-ingress -``` -Then "mark" the `nginx-ingress` namespace for OSM to deploy a sidecar. - -```bash -osm namespace add nginx-ingress --mesh-name osm-nginx -``` - -The above command will use the mark the `nginx-ingress` namespace, where OSM will be installed (sidecar). - -### Install a Test Application -To test the integration, we will use the `httpbin` sample application from the [Ingress With Kubernetes NGINX Ingress Controller](https://release-v1-2.docs.openservicemesh.io/docs/demos/ingress_k8s_nginx/) guide. - -The following three commands will create the namespace for the application, add the namespace to OSM for monitoring, then install the application. - -```bash -kubectl create ns httpbin -osm namespace add httpbin --mesh-name osm-nginx -kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm-docs/release-v1.2/manifests/samples/httpbin/httpbin.yaml -n httpbin -``` - -### Add required annotations to NGINX Ingress Controller deployment: - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: nginx-ingress - namespace: nginx-ingress -spec: - replicas: 1 - selector: - matchLabels: - app: nginx-ingress - template: - metadata: - labels: - app: nginx-ingress - annotations: - openservicemesh.io/inbound-port-exclusion-list: "80,443" -``` - -This annotation is *required* when injecting envoy sidecar into NGINX Ingress Controller. - -`InboundPortExclusionList` defines a global list of ports to exclude from inbound traffic interception by the sidecar proxy. - - -### Verify that the envoy sidecar has been *injected* into NGINX Ingress - -```bash -kubectl get pods -n nginx-ingress -NAME READY STATUS RESTARTS AGE -nginx-ingress-7b9557ddc6-zw7l5 2/2 Running 1 (5m8s ago) 5m19s -``` - -"2/2" demonstrates there are two containers in the NGINX Ingress Controller pod: NGINX Ingress and Envoy - - -Configure your NGINX VirtualServer `yaml` definitions with the adjustments below. - -```yaml -apiVersion: k8s.nginx.org/v1 -kind: VirtualServer -metadata: - name: httpbin - namespace: httpbin -spec: - host: httpbin.example.com - tls: - secret: secret01 - upstreams: - - name: httpbin - service: httpbin - port: 14001 - use-cluster-ip: true - routes: - - path: / - action: - proxy: - upstream: httpbin - requestHeaders: - set: - - name: Host - value: httpbin.httpbin.svc.cluster.local -``` - -Test your configuration: - -```bash - curl http://httpbin.example.com/get -v -* Trying 172.19.0.2:80... -* TCP_NODELAY set -* Connected to httpbin.example.com (172.19.0.2) port 80 (#0) -> GET /get HTTP/1.1 -> Host: httpbin.example.com -> User-Agent: curl/7.68.0 -> Accept: */* -> -* Mark bundle as not supporting multiuse -< HTTP/1.1 200 OK -< Server: nginx/1.23.3 -< Date: Sun, 19 Feb 2023 19:06:47 GMT -< Content-Type: application/json -< Content-Length: 454 -< Connection: keep-alive -< access-control-allow-origin: * -< access-control-allow-credentials: true -< x-envoy-upstream-service-time: 2 -< -{ - "args": {}, - "headers": { - "Accept": "*/*", - "Host": "httpbin.httpbin.svc.cluster.local", - "Osm-Stats-Kind": "Deployment", - "Osm-Stats-Name": "httpbin", - "Osm-Stats-Namespace": "httpbin", - "Osm-Stats-Pod": "httpbin-78555f5c4b-t6qln", - "User-Agent": "curl/7.68.0", - "X-Envoy-Internal": "true", - "X-Forwarded-Host": "httpbin.example.com" - }, - "origin": "172.19.0.1", - "url": "http://httpbin.example.com/get" -} -* Connection #0 to host httpbin.example.com left intact -``` - -## Using The Open Service Mesh `IngressBackend` "proxy" Feature -By running the following command, you will install OSM into the cluster with the mesh name `osm-nginx` using the `osm-system` namespace. - -```bash -osm install --mesh-name osm-nginx --osm-namespace osm-system -``` - -Once OSM has been installed, this next command will mark the NGINX Ingress Controller as part of the OSM mesh, while also disabling sidecar injection. -*NOTE*: The nginx-ingress name can be created as part of the NGINX Ingress install process, or manually. It must be created **before** you "add" the namespace to nginx-ingress. - -```bash -osm namespace add nginx-ingress --mesh-name osm-nginx --disable-sidecar-injection -``` - -### Install a Test Application - -To test the integration, we will use the `httpbin` sample application from the [Ingress With Kubernetes NGINX Ingress Controller](https://release-v1-2.docs.openservicemesh.io/docs/demos/ingress_k8s_nginx/) guide. - -The following three commands will create the namespace for the application, add the namespace to OSM for monitoring, then install the application. - -```bash -kubectl create ns httpbin -osm namespace add httpbin --mesh-name osm-nginx -kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm-docs/release-v1.2/manifests/samples/httpbin/httpbin.yaml -n httpbin -``` - -### mTLS Setup - -To enable mTLS for NGINX Ingress Controller and OSM, you need to configure the `IngressBackend` API to use `https` as the backend protocol and trigger OSM to issue a certificate. NGINX will use this certificate to proxy HTTPS connections to the TLS backends. The client certificate and certificate authority (CA) certificate will be stored in a Kubernetes secret that NGINX will use for authentication."* - -To begin, edit the `osm-mesh-config` resource: - -```bash -kubectl edit meshconfig osm-mesh-config -n osm-system -``` - -The certificate configuration must then be updated as below: - -```yaml -spec: - certificate: - ingressGateway: - secret: - name: osm-nginx-client-cert - namespace: osm-system - subjectAltNames: - - nginx-ingress.nginx-ingress.cluster.local - validityDuration: 24h -``` - -This will generate a new client certificate (osm-nginx-client-cert) that NGINX Ingress Controller will use for mTLS. -The *SAN*, `subjectAltNames`, is the following form: - -```bash -..cluster.local -``` - -When the OSM mesh configuration changes, the secret will be created in the `osm-system` namespace. -There will also be the `osm-ca-bundle` secret as well, which is autogenerated by OSM. - -```bash -kubectl get secrets -n osm-system -NAME TYPE DATA AGE -osm-ca-bundle Opaque 2 37m -osm-nginx-client-cert kubernetes.io/tls 3 17m -``` - -The certificates must then be exported in order to use them with NGINX Ingress Controller. - -```bash -kubectl get secret osm-ca-bundle -n osm-system -o yaml > osm-ca-bundle-secret.yaml -kubectl get secret osm-nginx-client-cert -n osm-system -o yaml > osm-nginx-client-cert.yaml -``` - - -The two exported .yaml files will now require changes: - -Edit `osm-ca-bundle-secret.yaml` -Remove the `private.key` section under `data.` -Change the `namespace` field to your nginx-ingress location -Change the `type` to `type: nginx.org/ca` - -The updated file should look like the below example: -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: osm-ca-bundle - namespace: nginx-ingress -type: nginx.org/ca -data: - ca.crt: -``` - -Edit `osm-nginx-client-cert.yaml` -Remove the `ca.crt` in the `data` section -Change the namespace to the nginx-ingress namespace. - -The updated file should look like the below example: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: osm-nginx-client-cert - namespace: nginx-ingress -type: kubernetes.io/tls -data: - tls.crt: - tls.key: -``` - -Once these two files have been edited, they will need to be applied to the cluster: - -```bash -kubectl apply -f osm-ca-bundle-secret.yaml -kubectl apply -f osm-nginx-client-cert.yaml - -``` -Ensure the secrets exist in the `nginx-ingress` namespace: - -```bash -kubectl get secrets -n nginx-ingress -NAME TYPE DATA AGE -osm-nginx-client-cert kubernetes.io/tls 2 23m -osm-ca-bundle nginx.org/ca 1 23m -``` - -The CRDs (virtualServer and policy) must now be created. -Here is the `policy` resource that holds the mTLS information. -It is required for virtualServer, and the `policy` must be applied or the mTLS connection will not work. - -```yaml -apiVersion: k8s.nginx.org/v1 -kind: Policy -metadata: - name: osm-mtls - namespace: nginx-ingress -spec: - egressMTLS: - tlsSecret: osm-nginx-client-cert - trustedCertSecret: osm-ca-bundle - verifyDepth: 2 - verifyServer: on - sslName: httpbin.httpbin.cluster.local -``` - -Here is an example `virtualServer` resource as well as the `ingressBackend`. - -```yaml -apiVersion: k8s.nginx.org/v1 -kind: VirtualServer -metadata: - name: httpbin - namespace: httpbin -spec: - policies: - - name: osm-mtls - namespace: nginx-ingress - host: httpbin.example.com - tls: - secret: secret01 - upstreams: - - name: httpbin - service: httpbin - port: 14001 - tls: - enable: true - routes: - - path: / - action: - pass: httpbin ---- -kind: IngressBackend -apiVersion: policy.openservicemesh.io/v1alpha1 -metadata: - name: httpbin - namespace: httpbin -spec: - backends: - - name: httpbin - port: - number: 14001 # targetPort of httpbin service - protocol: https - tls: - skipClientCertValidation: false - sources: - - kind: Service - namespace: nginx-ingress - name: nginx-ingress - - kind: AuthenticatedPrincipal - name: nginx-ingress.nginx-ingress.cluster.local -``` - -Once these are applied, verify they are valid (virtualServer) and committed (ingressBackend): - -```bash -kubectl get vs,ingressbackend -A -NAMESPACE NAME STATE HOST IP PORTS AGE -httpbin virtualserver.k8s.nginx.org/httpbin Valid httpbin.example.com 26m - -NAMESPACE NAME STATUS -httpbin ingressbackend.policy.openservicemesh.io/httpbin committed -``` - -You can now send traffic through NGINX Ingress Controller with Open Service Mesh. - -```bash -curl http://httpbin.example.com/get -v -* Trying 172.18.0.2:80... -* TCP_NODELAY set -* Connected to httpbin.example.com (172.18.0.2) port 80 (#0) -> GET /get HTTP/1.1 -> Host: httpbin.example.com -> User-Agent: curl/7.68.0 -> Accept: */* -> -* Mark bundle as not supporting multiuse -< HTTP/1.1 200 OK -< Server: nginx/1.23.3 -< Date: Sat, 18 Feb 2023 22:41:27 GMT -< Content-Type: application/json -< Content-Length: 280 -< Connection: keep-alive -< access-control-allow-origin: * -< access-control-allow-credentials: true -< x-envoy-upstream-service-time: 1 -< -{ - "args": {}, - "headers": { - "Accept": "*/*", - "Host": "httpbin.example.com", - "User-Agent": "curl/7.68.0", - "X-Envoy-Internal": "true", - "X-Forwarded-Host": "httpbin.example.com" - }, - "origin": "172.18.0.1", - "url": "http://httpbin.example.com/get" -} -* Connection #0 to host httpbin.example.com left intact -``` From 8a70c764c32bcc9d8df9b864d215cd7adf9adfe3 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 23 Mar 2023 19:21:47 +0000 Subject: [PATCH 14/25] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/content/tutorials/nginx-ingress-osm.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/content/tutorials/nginx-ingress-osm.md b/docs/content/tutorials/nginx-ingress-osm.md index ced588437c..64d8586c6e 100644 --- a/docs/content/tutorials/nginx-ingress-osm.md +++ b/docs/content/tutorials/nginx-ingress-osm.md @@ -2,7 +2,7 @@ Open Service Mesh will work with both versions of [F5 NGINX Ingress controller](https://github.com/nginxinc/kubernetes-ingress): the free as well as the NGINX Plus versions. -Below is a link to the official F5 NGINX Ingress controller documentation. +Below is a link to the official F5 NGINX Ingress controller documentation. [F5 NGINX Ingress controller](https://docs.nginx.com/nginx-ingress-controller/) # Integrating NGINX Ingress Controller with Open Service Mesh @@ -13,7 +13,7 @@ There are two ways to integrate the NGINX Ingress Controller with Open Service M 2. Using the Open Service Mesh `ingressBackend` "proxy" feature. -# NGINX Ingress controller and OSM with sidecar injected +# NGINX Ingress controller and OSM with sidecar injected Install OSM in the cluster @@ -41,8 +41,8 @@ The above command will use the mark the `nginx-ingress` namespace, where OSM wil # Install F5 NGINX Ingress controller. Here the links to the install guides: -[Using Helm to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) -[Using Manifests to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) +[Using Helm to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) +[Using Manifests to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) When using the sidecar method, ensure that you add the correct annotations listed below. This ensures proper integration of NGINX Ingress Controller with the envoy sidecar proxy. @@ -56,15 +56,15 @@ Under `controller.pod.annotations`: ```yaml pod: - annotations: { - openservicemesh.io/inbound-port-exclusion-list: "80, 443" + annotations: { + openservicemesh.io/inbound-port-exclusion-list: "80, 443" } ``` You can also use the `set` command available with `helm` to set these at install time. ```bash -helm install nic01 nginx-stable/nginx-ingress -n nginx-ingress --create-namespace --set controller.pod.annotations.'openservicemesh\.io/inbound\-port\-exclusion\-list=\{ "80"\, "443"\ }' +helm install nic01 nginx-stable/nginx-ingress -n nginx-ingress --create-namespace --set controller.pod.annotations.'openservicemesh\.io/inbound\-port\-exclusion\-list=\{ "80"\, "443"\ }' ``` Change your `release` accordingly to match your environment. @@ -140,7 +140,7 @@ spec: upstreams: - name: httpbin service: httpbin - port: 14001 + port: 14001 use-cluster-ip: true routes: - path: / @@ -444,4 +444,3 @@ curl http://httpbin.example.com/get -v } * Connection #0 to host httpbin.example.com left intact ``` - From 378578693aa8834735706870efa514b621ab6545 Mon Sep 17 00:00:00 2001 From: Jason Williams Date: Sun, 2 Apr 2023 16:08:25 -0700 Subject: [PATCH 15/25] Custom listen ports document --- docs/content/tutorials/custom-listen-ports.md | 137 ++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 docs/content/tutorials/custom-listen-ports.md diff --git a/docs/content/tutorials/custom-listen-ports.md b/docs/content/tutorials/custom-listen-ports.md new file mode 100644 index 0000000000..3dd99d5c03 --- /dev/null +++ b/docs/content/tutorials/custom-listen-ports.md @@ -0,0 +1,137 @@ +## Customizing the `listen` line in NGINX Ingress Controller. + +This document will explain how to change the default ports that NGINX Ingress Controller is configured for, as well as add additional `listen` settings. For more information, please read the [NGINX Listen documentation](http://nginx.org/en/docs/http/ngx_http_core_module.html#listen). + + +## Changing Default Ports + +By default, NGINX Ingress Controller listens on ports 80 and 443. These ports can be changed easily, but modifying the `listen` ports for your NGINX Ingress resources will require the editing of .tmpl files. + +If you are using `ingress` resource you will need to modify: +- `nginx-plus-ingress.tmpl` if using NGINX Plus +- `nginx-ingress.tmpl` if using NGINX OSS + +If you are using NGINX Ingress Controller CRDs (virtualServer): +- `nginx-plus-virtualserver.tmpl` for NGINX Plus +- `nginx-virtualserver.tmpl` if using NGINX OSS + +For this example, we are going to use the `nginx-virtualserver.tmpl` to change the port from 80 to 85. + +Here we modify `nginx-virtualserver.tmpl` to change the port setting: + +``` +server { + listen 80{{ if $s.ProxyProtocol }} proxy_protocol{{ end }}; + + server_name {{ $s.ServerName }}; + + set $resource_type "virtualserver"; + set $resource_name "{{$s.VSName}}"; + set $resource_namespace "{{$s.VSNamespace}}"; +``` +To change the listen port from `80` to `85`, we modify the `listen` line at the start of the server configuration block. + +It would then look like this: +``` +server { + listen 85{{ if $s.ProxyProtocol }} proxy_protocol{{ end }}; + + server_name {{ $s.ServerName }}; + + set $resource_type "virtualserver"; + set $resource_name "{{$s.VSName}}"; + set $resource_namespace "{{$s.VSNamespace}}"; +``` + +Edit the file you need (per the example above). In my case, I edited, `nginx-plus-virtualserver.tmpls`: + + +## Rebuild your NGINX Ingress controller image + +You will need to build your new NGINX Ingress controller image for the new port settings to take affect. +Once the image is built and pushed, make sure you update your deployment to point to the new image and deploy. +Once deployed, create a new `virtualServer` resource and then run `nginx -T` to see if the port takes affect. + +Ensure that your `deployment` and your `service` match up to the new port you configured in the templates. +Here is simple example of my `deployment` and my `service` matching to the new port that NGINX Ingress controller now listens on. + +``` +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-ingress + namespace: nginx-ingress +spec: + replicas: 1 + selector: + matchLabels: + app: nginx-ingress + template: + metadata: + labels: + app: nginx-ingress + annotations: + prometheus.io/scrape: "true" + prometheus.io/port: "9113" + prometheus.io/scheme: http + spec: + serviceAccountName: nginx-ingress + containers: + - image: nginx/nginx-ingress:3.0.2 + imagePullPolicy: IfNotPresent + name: nginx-ingress + ports: + - name: http + containerPort: 85 + - name: https + containerPort: 443 + - name: readiness-port + containerPort: 8081 + - name: prometheus + containerPort: 9113 + readinessProbe: + httpGet: + path: /nginx-ready + port: readiness-port + periodSeconds: 1 + securityContext: +``` + +Notice that now, my `http` port is set to `85`, which reflects the change I made in the template file. + +Here is my `service` file: + +``` +apiVersion: v1 +kind: Service +metadata: + name: nginx-ingress + namespace: nginx-ingress +spec: + externalTrafficPolicy: Local + type: LoadBalancer + ports: + - port: 80 + targetPort: 85 + protocol: TCP + name: http + - port: 8443 + targetPort: 8443 + protocol: TCP + name: https + selector: + app: nginx-ingress +``` + +Since NGINX Ingress controller is now listening on ports 85 and 8443, we modify the `targetPort` in the NGINX Ingress controller service, to match what we have changed in our deployment, to ensure traffic will be sent to the proper port. +The key part above is the `targetPort` section. Since I change NGINX Ingress to listen on port 85, I need to match that in the service. That way, requests will be sent to NGINX Ingress controller on port 85 instead of the default value which is port 80. + + +If you view the `NGINX` configuration .conf file using `nginx -T`, you should see the port you defined in the .template file, now is set on the `listen` line. + +``` +server { + listen 85; + listen [::]:85; + listen 8011; +``` From 31ba6a6f6a04eff78d8ceff81cce35ddd2a87ca6 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sun, 2 Apr 2023 23:12:15 +0000 Subject: [PATCH 16/25] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/content/tutorials/custom-listen-ports.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/tutorials/custom-listen-ports.md b/docs/content/tutorials/custom-listen-ports.md index 3dd99d5c03..536478997e 100644 --- a/docs/content/tutorials/custom-listen-ports.md +++ b/docs/content/tutorials/custom-listen-ports.md @@ -6,7 +6,7 @@ This document will explain how to change the default ports that NGINX Ingress Co ## Changing Default Ports By default, NGINX Ingress Controller listens on ports 80 and 443. These ports can be changed easily, but modifying the `listen` ports for your NGINX Ingress resources will require the editing of .tmpl files. - + If you are using `ingress` resource you will need to modify: - `nginx-plus-ingress.tmpl` if using NGINX Plus - `nginx-ingress.tmpl` if using NGINX OSS @@ -15,7 +15,7 @@ If you are using NGINX Ingress Controller CRDs (virtualServer): - `nginx-plus-virtualserver.tmpl` for NGINX Plus - `nginx-virtualserver.tmpl` if using NGINX OSS -For this example, we are going to use the `nginx-virtualserver.tmpl` to change the port from 80 to 85. +For this example, we are going to use the `nginx-virtualserver.tmpl` to change the port from 80 to 85. Here we modify `nginx-virtualserver.tmpl` to change the port setting: From 2e699e9fdaf53068364527393f1b674bcc0b1ba0 Mon Sep 17 00:00:00 2001 From: Jason Williams Date: Wed, 5 Apr 2023 14:34:43 -0700 Subject: [PATCH 17/25] Merged updated URL --- docs/content/tutorials/custom-listen-ports.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/tutorials/custom-listen-ports.md b/docs/content/tutorials/custom-listen-ports.md index 536478997e..1b3c7c54ea 100644 --- a/docs/content/tutorials/custom-listen-ports.md +++ b/docs/content/tutorials/custom-listen-ports.md @@ -15,7 +15,7 @@ If you are using NGINX Ingress Controller CRDs (virtualServer): - `nginx-plus-virtualserver.tmpl` for NGINX Plus - `nginx-virtualserver.tmpl` if using NGINX OSS -For this example, we are going to use the `nginx-virtualserver.tmpl` to change the port from 80 to 85. +For this example, we are going to use the `nginx-virtualserver.tmpl` to change the port from 80 to 85. [nginx-virtualserver template files](https://github.com/nginxinc/kubernetes-ingress/tree/main/internal/configs/version2) Here we modify `nginx-virtualserver.tmpl` to change the port setting: @@ -43,7 +43,7 @@ server { set $resource_namespace "{{$s.VSNamespace}}"; ``` -Edit the file you need (per the example above). In my case, I edited, `nginx-plus-virtualserver.tmpls`: +Edit the file you need (per the example above). In my case, I edited, `nginx-plus-virtualserver.tmpl`: ## Rebuild your NGINX Ingress controller image From ef703829d8f5820e74019b42af9fc118a6010132 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 5 Apr 2023 22:19:09 +0000 Subject: [PATCH 18/25] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/content/tutorials/custom-listen-ports.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/tutorials/custom-listen-ports.md b/docs/content/tutorials/custom-listen-ports.md index 1b3c7c54ea..a2f9b6ab29 100644 --- a/docs/content/tutorials/custom-listen-ports.md +++ b/docs/content/tutorials/custom-listen-ports.md @@ -15,7 +15,7 @@ If you are using NGINX Ingress Controller CRDs (virtualServer): - `nginx-plus-virtualserver.tmpl` for NGINX Plus - `nginx-virtualserver.tmpl` if using NGINX OSS -For this example, we are going to use the `nginx-virtualserver.tmpl` to change the port from 80 to 85. [nginx-virtualserver template files](https://github.com/nginxinc/kubernetes-ingress/tree/main/internal/configs/version2) +For this example, we are going to use the `nginx-virtualserver.tmpl` to change the port from 80 to 85. [nginx-virtualserver template files](https://github.com/nginxinc/kubernetes-ingress/tree/main/internal/configs/version2) Here we modify `nginx-virtualserver.tmpl` to change the port setting: From dcbf445e9fe750593c94782b16903ffef31a91fd Mon Sep 17 00:00:00 2001 From: Jason Williams Date: Tue, 4 Apr 2023 12:44:25 -0700 Subject: [PATCH 19/25] Add DOC ID --- docs/content/tutorials/custom-listen-ports.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/content/tutorials/custom-listen-ports.md b/docs/content/tutorials/custom-listen-ports.md index a2f9b6ab29..9534317ff2 100644 --- a/docs/content/tutorials/custom-listen-ports.md +++ b/docs/content/tutorials/custom-listen-ports.md @@ -1,3 +1,12 @@ +--- +title: Customze ports for NGINX Ingress Controller +description: | + Customze ports for NGINX Ingress Controller +weight: 1800 +doctypes: ["concept"] +toc: true +docs: "DOCS-1191" +--- ## Customizing the `listen` line in NGINX Ingress Controller. This document will explain how to change the default ports that NGINX Ingress Controller is configured for, as well as add additional `listen` settings. For more information, please read the [NGINX Listen documentation](http://nginx.org/en/docs/http/ngx_http_core_module.html#listen). @@ -128,10 +137,21 @@ The key part above is the `targetPort` section. Since I change NGINX Ingress to If you view the `NGINX` configuration .conf file using `nginx -T`, you should see the port you defined in the .template file, now is set on the `listen` line. +Here is an example output of the `NGINX` configuration that is now generated: + +```bash +k exec -it -n nginx-ingress nginx-ingress-54bffd78d9-v7bns -- nginx -T +``` ``` server { listen 85; listen [::]:85; listen 8011; + + server_name cafe.example.com; + + set $resource_type "virtualserver"; + set $resource_name "cafe"; + set $resource_namespace "default"; ``` From 915879514ba4862947835415d4799e6ab472d70a Mon Sep 17 00:00:00 2001 From: Jason Williams Date: Wed, 5 Apr 2023 15:25:18 -0700 Subject: [PATCH 20/25] Fix URL link typo --- docs/content/tutorials/custom-listen-ports.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/content/tutorials/custom-listen-ports.md b/docs/content/tutorials/custom-listen-ports.md index 9534317ff2..a7b71d0281 100644 --- a/docs/content/tutorials/custom-listen-ports.md +++ b/docs/content/tutorials/custom-listen-ports.md @@ -24,7 +24,11 @@ If you are using NGINX Ingress Controller CRDs (virtualServer): - `nginx-plus-virtualserver.tmpl` for NGINX Plus - `nginx-virtualserver.tmpl` if using NGINX OSS -For this example, we are going to use the `nginx-virtualserver.tmpl` to change the port from 80 to 85. [nginx-virtualserver template files](https://github.com/nginxinc/kubernetes-ingress/tree/main/internal/configs/version2) +For this example, we are going to use the `nginx-virtualserver.tmpl` to change the port from 80 to 85. +Here is a link to the directory for the `.tmpl` files: + +[nginx-virtualserver template files](https://github.com/nginxinc/kubernetes-ingress/tree/main/internal/configs/version2) + Here we modify `nginx-virtualserver.tmpl` to change the port setting: From 04b7d98cabd67f3831e0c34d1656ded08abe6fd5 Mon Sep 17 00:00:00 2001 From: Jason Williams Date: Fri, 7 Apr 2023 09:23:19 -0700 Subject: [PATCH 21/25] Update DOC ID --- docs/content/tutorials/nginx-ingress-osm.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/content/tutorials/nginx-ingress-osm.md b/docs/content/tutorials/nginx-ingress-osm.md index 64d8586c6e..dae7d68eaa 100644 --- a/docs/content/tutorials/nginx-ingress-osm.md +++ b/docs/content/tutorials/nginx-ingress-osm.md @@ -1,8 +1,18 @@ +--- +title: NGINX Ingress Controller and Open Service Mesh +description: | + Use NGINX Ingress Controller with Open Service Mesh. +weight: 1800 +doctypes: ["concept"] +toc: true +docs: "DOCS-1181" +--- + ## This document outlines how to integrate F5 NGINX Ingress Controller with Open Service Mesh (OSM) Open Service Mesh will work with both versions of [F5 NGINX Ingress controller](https://github.com/nginxinc/kubernetes-ingress): the free as well as the NGINX Plus versions. -Below is a link to the official F5 NGINX Ingress controller documentation. +Below is a link to the official F5 NGINX Ingress Controller documentation. [F5 NGINX Ingress controller](https://docs.nginx.com/nginx-ingress-controller/) # Integrating NGINX Ingress Controller with Open Service Mesh From f7d72f2c96ff63a59ea46b8aefd0e92de7b08edb Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 7 Apr 2023 17:34:32 +0000 Subject: [PATCH 22/25] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/content/tutorials/custom-listen-ports.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/content/tutorials/custom-listen-ports.md b/docs/content/tutorials/custom-listen-ports.md index a7b71d0281..7502b437dd 100644 --- a/docs/content/tutorials/custom-listen-ports.md +++ b/docs/content/tutorials/custom-listen-ports.md @@ -1,7 +1,7 @@ --- -title: Customze ports for NGINX Ingress Controller +title: Customze ports for NGINX Ingress Controller description: | - Customze ports for NGINX Ingress Controller + Customze ports for NGINX Ingress Controller weight: 1800 doctypes: ["concept"] toc: true @@ -24,8 +24,8 @@ If you are using NGINX Ingress Controller CRDs (virtualServer): - `nginx-plus-virtualserver.tmpl` for NGINX Plus - `nginx-virtualserver.tmpl` if using NGINX OSS -For this example, we are going to use the `nginx-virtualserver.tmpl` to change the port from 80 to 85. -Here is a link to the directory for the `.tmpl` files: +For this example, we are going to use the `nginx-virtualserver.tmpl` to change the port from 80 to 85. +Here is a link to the directory for the `.tmpl` files: [nginx-virtualserver template files](https://github.com/nginxinc/kubernetes-ingress/tree/main/internal/configs/version2) From b143bc63c5d8741c5628ba76fb4121c19069f3b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jason=20Williams=20-=20NGI=D0=98X?= Date: Fri, 7 Apr 2023 11:46:18 -0700 Subject: [PATCH 23/25] Delete custom-listen-ports.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jason Williams - NGIИX --- docs/content/tutorials/custom-listen-ports.md | 161 ------------------ 1 file changed, 161 deletions(-) delete mode 100644 docs/content/tutorials/custom-listen-ports.md diff --git a/docs/content/tutorials/custom-listen-ports.md b/docs/content/tutorials/custom-listen-ports.md deleted file mode 100644 index 7502b437dd..0000000000 --- a/docs/content/tutorials/custom-listen-ports.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: Customze ports for NGINX Ingress Controller -description: | - Customze ports for NGINX Ingress Controller -weight: 1800 -doctypes: ["concept"] -toc: true -docs: "DOCS-1191" ---- -## Customizing the `listen` line in NGINX Ingress Controller. - -This document will explain how to change the default ports that NGINX Ingress Controller is configured for, as well as add additional `listen` settings. For more information, please read the [NGINX Listen documentation](http://nginx.org/en/docs/http/ngx_http_core_module.html#listen). - - -## Changing Default Ports - -By default, NGINX Ingress Controller listens on ports 80 and 443. These ports can be changed easily, but modifying the `listen` ports for your NGINX Ingress resources will require the editing of .tmpl files. - -If you are using `ingress` resource you will need to modify: -- `nginx-plus-ingress.tmpl` if using NGINX Plus -- `nginx-ingress.tmpl` if using NGINX OSS - -If you are using NGINX Ingress Controller CRDs (virtualServer): -- `nginx-plus-virtualserver.tmpl` for NGINX Plus -- `nginx-virtualserver.tmpl` if using NGINX OSS - -For this example, we are going to use the `nginx-virtualserver.tmpl` to change the port from 80 to 85. -Here is a link to the directory for the `.tmpl` files: - -[nginx-virtualserver template files](https://github.com/nginxinc/kubernetes-ingress/tree/main/internal/configs/version2) - - -Here we modify `nginx-virtualserver.tmpl` to change the port setting: - -``` -server { - listen 80{{ if $s.ProxyProtocol }} proxy_protocol{{ end }}; - - server_name {{ $s.ServerName }}; - - set $resource_type "virtualserver"; - set $resource_name "{{$s.VSName}}"; - set $resource_namespace "{{$s.VSNamespace}}"; -``` -To change the listen port from `80` to `85`, we modify the `listen` line at the start of the server configuration block. - -It would then look like this: -``` -server { - listen 85{{ if $s.ProxyProtocol }} proxy_protocol{{ end }}; - - server_name {{ $s.ServerName }}; - - set $resource_type "virtualserver"; - set $resource_name "{{$s.VSName}}"; - set $resource_namespace "{{$s.VSNamespace}}"; -``` - -Edit the file you need (per the example above). In my case, I edited, `nginx-plus-virtualserver.tmpl`: - - -## Rebuild your NGINX Ingress controller image - -You will need to build your new NGINX Ingress controller image for the new port settings to take affect. -Once the image is built and pushed, make sure you update your deployment to point to the new image and deploy. -Once deployed, create a new `virtualServer` resource and then run `nginx -T` to see if the port takes affect. - -Ensure that your `deployment` and your `service` match up to the new port you configured in the templates. -Here is simple example of my `deployment` and my `service` matching to the new port that NGINX Ingress controller now listens on. - -``` -apiVersion: apps/v1 -kind: Deployment -metadata: - name: nginx-ingress - namespace: nginx-ingress -spec: - replicas: 1 - selector: - matchLabels: - app: nginx-ingress - template: - metadata: - labels: - app: nginx-ingress - annotations: - prometheus.io/scrape: "true" - prometheus.io/port: "9113" - prometheus.io/scheme: http - spec: - serviceAccountName: nginx-ingress - containers: - - image: nginx/nginx-ingress:3.0.2 - imagePullPolicy: IfNotPresent - name: nginx-ingress - ports: - - name: http - containerPort: 85 - - name: https - containerPort: 443 - - name: readiness-port - containerPort: 8081 - - name: prometheus - containerPort: 9113 - readinessProbe: - httpGet: - path: /nginx-ready - port: readiness-port - periodSeconds: 1 - securityContext: -``` - -Notice that now, my `http` port is set to `85`, which reflects the change I made in the template file. - -Here is my `service` file: - -``` -apiVersion: v1 -kind: Service -metadata: - name: nginx-ingress - namespace: nginx-ingress -spec: - externalTrafficPolicy: Local - type: LoadBalancer - ports: - - port: 80 - targetPort: 85 - protocol: TCP - name: http - - port: 8443 - targetPort: 8443 - protocol: TCP - name: https - selector: - app: nginx-ingress -``` - -Since NGINX Ingress controller is now listening on ports 85 and 8443, we modify the `targetPort` in the NGINX Ingress controller service, to match what we have changed in our deployment, to ensure traffic will be sent to the proper port. -The key part above is the `targetPort` section. Since I change NGINX Ingress to listen on port 85, I need to match that in the service. That way, requests will be sent to NGINX Ingress controller on port 85 instead of the default value which is port 80. - - -If you view the `NGINX` configuration .conf file using `nginx -T`, you should see the port you defined in the .template file, now is set on the `listen` line. -Here is an example output of the `NGINX` configuration that is now generated: - -```bash -k exec -it -n nginx-ingress nginx-ingress-54bffd78d9-v7bns -- nginx -T -``` - -``` -server { - listen 85; - listen [::]:85; - listen 8011; - - server_name cafe.example.com; - - set $resource_type "virtualserver"; - set $resource_name "cafe"; - set $resource_namespace "default"; -``` From 971a7f6776e479372a0a8b9de96da28667e7b80a Mon Sep 17 00:00:00 2001 From: Jason Williams Date: Fri, 7 Apr 2023 15:15:24 -0700 Subject: [PATCH 24/25] Grammer and type fixes --- docs/content/tutorials/nginx-ingress-osm.md | 26 ++++++++++++++------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/docs/content/tutorials/nginx-ingress-osm.md b/docs/content/tutorials/nginx-ingress-osm.md index dae7d68eaa..489ddd7ddf 100644 --- a/docs/content/tutorials/nginx-ingress-osm.md +++ b/docs/content/tutorials/nginx-ingress-osm.md @@ -23,7 +23,7 @@ There are two ways to integrate the NGINX Ingress Controller with Open Service M 2. Using the Open Service Mesh `ingressBackend` "proxy" feature. -# NGINX Ingress controller and OSM with sidecar injected +# NGINX Ingress controller and OSM with sidecar proxy injected Install OSM in the cluster @@ -31,7 +31,7 @@ Install OSM in the cluster osm install --mesh-name osm-nginx --osm-namespace osm-system ``` -### Mark F5 NGINX Ingress controller namespace for sidecar injection +### Mark the F5 NGINX Ingress controller namespace for sidecar injection *NOTE:* Depending on how you install NGINX Ingress controller, you might need to create the `namespace`. For example, if you are using manifests to install NGINX Ingress controller, you can complete all of the steps on our documentation page, *EXCEPT*, actually deploying NGINX Ingress controller. This is because, when using the sidecar approach, OSM needs to "manage" the namespace so it knows what `namespaces` it needs to inject sidecars into. @@ -49,7 +49,9 @@ osm namespace add nginx-ingress --mesh-name osm-nginx The above command will use the mark the `nginx-ingress` namespace, where OSM will be installed (sidecar) -# Install F5 NGINX Ingress controller. Here the links to the install guides: +# Install F5 NGINX Ingress controller + +Links to the complete install guides: [Using Helm to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) [Using Manifests to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) @@ -89,7 +91,7 @@ annotations: openservicemesh.io/inbound-port-exclusion-list: "80,443" ``` -### Sample deployment file with annotation required +### Sample deployment file with required annotation ```yaml apiVersion: apps/v1 @@ -124,7 +126,7 @@ osm namespace add httpbin --mesh-name osm-nginx kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm-docs/release-v1.2/manifests/samples/httpbin/httpbin.yaml -n httpbin ``` -### Verify that the envoy sidecar has been *injected* into NGINX Ingress +### Verify that the envoy sidecar has been *injected* into NGINX Ingress Controller ```bash kubectl get pods -n nginx-ingress @@ -209,7 +211,7 @@ Test your configuration: ## Using The Open Service Mesh `ingressBackend` "proxy" Feature -Install OSM into cluster. +Install OSM into the cluster. By running the following command, you will install OSM into the cluster with the mesh name `osm-nginx` using the `osm-system` namespace. ```bash @@ -217,14 +219,20 @@ osm install --mesh-name osm-nginx --osm-namespace osm-system ``` Once OSM has been installed, this next command will mark the NGINX Ingress Controller as part of the OSM mesh, while also disabling sidecar injection. -*NOTE*: The nginx-ingress name can be created as part of the NGINX Ingress install process, or manually. It must be created before you "add" the namespace to nginx-ingress. +*NOTE*: The nginx-ingress name can be created as part of the NGINX Ingress install process, or manually. If you are creating it manually, the namespace must created before you "add" the namespace to Open Service Mesh. ```bash osm namespace add nginx-ingress --mesh-name osm-nginx --disable-sidecar-injection ``` -# You can now install NGINX Ingress Controller by one of th above methods listed: `helm` or `manifetsts`. -*NOTE*: This method does NOT require annotations added to the deployment. +# Install F5 NGINX Ingress controller + +Links to the complete install guides: + +[Using Helm to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) +[Using Manifests to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) + +*NOTE*: This method does NOT require annotations added to the deployment, compared to the sidecar install method. ### Install a Test Application From 1c3c76ac78aade12b998e28592cd8197292f7c13 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 7 Apr 2023 22:15:47 +0000 Subject: [PATCH 25/25] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/content/tutorials/nginx-ingress-osm.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/content/tutorials/nginx-ingress-osm.md b/docs/content/tutorials/nginx-ingress-osm.md index 489ddd7ddf..973d93d310 100644 --- a/docs/content/tutorials/nginx-ingress-osm.md +++ b/docs/content/tutorials/nginx-ingress-osm.md @@ -49,9 +49,9 @@ osm namespace add nginx-ingress --mesh-name osm-nginx The above command will use the mark the `nginx-ingress` namespace, where OSM will be installed (sidecar) -# Install F5 NGINX Ingress controller +# Install F5 NGINX Ingress controller -Links to the complete install guides: +Links to the complete install guides: [Using Helm to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) [Using Manifests to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) @@ -225,9 +225,9 @@ Once OSM has been installed, this next command will mark the NGINX Ingress Contr osm namespace add nginx-ingress --mesh-name osm-nginx --disable-sidecar-injection ``` -# Install F5 NGINX Ingress controller +# Install F5 NGINX Ingress controller -Links to the complete install guides: +Links to the complete install guides: [Using Helm to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) [Using Manifests to install NGINX Ingress](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/)