diff --git a/examples/custom-resources/service-insight/README.md b/examples/custom-resources/service-insight/README.md new file mode 100644 index 0000000000..425f02ffbf --- /dev/null +++ b/examples/custom-resources/service-insight/README.md @@ -0,0 +1,424 @@ +# Support for Service Insight + + > The Service Insight feature is available only for F5 NGINX Plus. + +To use the [Service Insight](https://docs.nginx.com/nginx-ingress-controller/logging-and-monitoring/service-insight/) feature provided by F5 NGINX Ingress Controller you must enable it by setting `serviceInsight.create=true` in your `helm install/upgrade...` command OR [manifest](../../../deployments/deployment/nginx-plus-ingress.yaml) depending on your preferred installation method. + +The following example demonstrates how to enable the Service Insight for NGINX Ingress Controller using [manifests (Deployment)](../../../deployments/deployment/nginx-plus-ingress.yaml): + +```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 + app.kubernetes.io/name: nginx-ingress + spec: + serviceAccountName: nginx-ingress + automountServiceAccountToken: true + securityContext: + ... + containers: + - image: nginx-plus-ingress:3.0.2 + imagePullPolicy: IfNotPresent + name: nginx-plus-ingress + ports: + - name: http + containerPort: 80 + - name: https + containerPort: 443 + - name: readiness-port + containerPort: 8081 + - name: prometheus + containerPort: 9113 + - name: service-insight + containerPort: 9114 + readinessProbe: + httpGet: + path: /nginx-ready + port: readiness-port + periodSeconds: 1 + resources: + ... + securityContext: + ... + env: + ... + args: + - -nginx-plus + - -nginx-configmaps=$(POD_NAMESPACE)/nginx-config + ... + - -enable-service-insight + +``` + +## Deployment + +[Install NGINX Ingress Controller](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/), and uncomment the `-enable-service-insight` option: this will allow Service Insight to interact with it. + +The examples below use the `nodeport` service. + +## Configuration + +First, get the pod name in namespace `nginx-ingress`: + +```bash +kubectl get pods -n nginx-ingress +``` + +```bash +NAME READY STATUS RESTARTS AGE +nginx-ingress-5b99f485fb-vflb8 1/1 Running 0 72m +``` + +Using the id, forward the service insight port (9114) to localhost port 9114: + +```bash +kubectl port-forward -n nginx-ingress nginx-ingress-5b99f485fb-vflb8 9114:9114 +``` + +## Virtual Servers + +### Deployment + +Follow the [basic configuration example](../basic-configuration/) to deploy `cafe` app and `cafe virtual server`. + +### Testing + +Verify that the virtual server is running, and check the hostname: + +```bash +kubectl get vs cafe +NAME STATE HOST IP PORTS AGE +cafe Valid cafe.example.com 16m +``` + +Scale down the `tea` and `coffee` deployments: + +```bash +kubectl scale deployment tea --replicas=1 +``` + +```bash +kubectl scale deployment coffee --replicas=1 +``` + +Verify `tea` deployment: + +```bash +kubectl get deployments.apps tea +``` + +```bash +NAME READY UP-TO-DATE AVAILABLE AGE +tea 1/1 1 1 19m +``` + +Verify `coffee` deployment: + +```bash +kubectl get deployments.apps coffee +``` + +```bash +NAME READY UP-TO-DATE AVAILABLE AGE +coffee 1/1 1 1 20m +``` + +Send a `GET` request to the service insight endpoint to check statistics: + +Request: + +```bash +curl http://localhost:9114/probe/cafe.example.com +``` + +Response: + +```json +{"Total":2,"Up":2,"Unhealthy":0} +``` + +Scale up deployments: + +```bash +kubectl scale deployment tea --replicas=3 +``` + +```bash +kubectl scale deployment coffee --replicas=3 +``` + +Verify deployments: + +```bash +kubectl get deployments.apps tea +``` + +```bash +NAME READY UP-TO-DATE AVAILABLE AGE +tea 3/3 3 3 31m +``` + +```bash +kubectl get deployments.apps coffee +``` + +```bash +NAME READY UP-TO-DATE AVAILABLE AGE +coffee 3/3 3 3 31m +``` + +Send a `GET` HTTP request to the service insight endpoint to check statistics: + +```bash +curl http://localhost:9114/probe/cafe.example.com +``` + +Response: + +```json +{"Total":6,"Up":6,"Unhealthy":0} +``` + +## Transport Servers + +[Install NGINX Ingress Controller](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/), and uncomment the `-enable-service-insight`, `-enable-custom-resources`, and `-enable-tls-passthrough` options. + +The examples below use the `nodeport` service. + +First, get the nginx-ingress pod id: + +```bash +kubectl get pods -n nginx-ingress +``` + +``` +NAME READY STATUS RESTARTS AGE +nginx-ingress-67978954cc-l6gvq 1/1 Running 0 72m +``` + +Using the id, forward the service insight port (9114) to localhost port 9114: +```bash +kubectl port-forward -n nginx-ingress nginx-ingress-67978954cc-l6gvq 9114:9114 & +``` + +### Deployment + +Follow the [tls passthrough example](../tls-passthrough/) to deploy the `secure-app` and configure load balancing. + +### Testing + +Verify that the transport server is running, and check the app name: + +```bash +kubectl get ts secure-app +NAME STATE REASON AGE +secure-app Valid AddedOrUpdated 5h37m +``` + +Scale down the `secure-app` deployment: + +```bash +kubectl scale deployment secure-app --replicas=1 +``` + +Verify `secure-app` deployment: + +```bash +kubectl get deployments.apps secure-app +NAME READY UP-TO-DATE AVAILABLE AGE +secure-app 1/1 1 1 5h41m +``` + +Send a `GET` request to the service insight endpoint to check statistics: + +Request: + +```bash +curl http://localhost:9114/probe/ts/secure-app +``` + +Response: + +```json +{"Total":1,"Up":1,"Unhealthy":0} +``` + +Scale up deployments: + +```bash +kubectl scale deployment secure-app --replicas=3 +``` + +Verify deployments: + +```bash +kubectl get deployments.apps secure-app +``` + +```bash +NAME READY UP-TO-DATE AVAILABLE AGE +secure-app 3/3 3 3 5h53m +``` + +Send a `GET` HTTP request to the service insight endpoint to check statistics: + +Request: + +```bash +curl http://localhost:9114/probe/ts/secure-app +``` + +Response: + +```json +{"Total":3,"Up":3,"Unhealthy":0} +``` + +## Service Insight with TLS + +The following example demonstrates how to enable the Service Insight for NGINX Ingress Controller with **TLS** using [manifests (Deployment)](../../../deployments/deployment/nginx-plus-ingress.yaml): + +```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 + app.kubernetes.io/name: nginx-ingress + spec: + serviceAccountName: nginx-ingress + automountServiceAccountToken: true + securityContext: + ... + containers: + - image: nginx-plus-ingress:3.0.2 + imagePullPolicy: IfNotPresent + name: nginx-plus-ingress + ports: + - name: http + containerPort: 80 + - name: https + containerPort: 443 + - name: readiness-port + containerPort: 8081 + - name: prometheus + containerPort: 9113 + - name: service-insight + containerPort: 9114 + readinessProbe: + httpGet: + path: /nginx-ready + port: readiness-port + periodSeconds: 1 + resources: + ... + securityContext: + ... + env: + ... + args: + - -nginx-plus + - -nginx-configmaps=$(POD_NAMESPACE)/nginx-config + ... + - -enable-service-insight + - -service-insight-tls-secret=default/service-insight-secret +``` + +The example below uses the `nodeport` service. + + +First, create and verify the secret: + +```bash +kubectl apply -f service-insight-secret.yaml +``` + +```bash +kubectl get secrets service-insight-secret +``` + +```bash +NAME TYPE DATA AGE +service-insight-secret kubernetes.io/tls 2 55s +``` + + +Get the nginx-ingress pod id: + +```bash +kubectl get pods -n nginx-ingress +``` + +```bash +NAME READY STATUS RESTARTS AGE +nginx-ingress-687d9c6764-g6vwx 1/1 Running 0 2m8s +``` + +Verify the nginx-ingress configuration parameters: + +```bash +kubectl describe pods -n nginx-ingress nginx-ingress-687d9c6764-g6vwx +``` + +```bash +... +Containers: + nginx-plus-ingress: + Container ID: containerd://fdff9038d747cada877cd547d88aa4a94af3d243e43956445d81f1e9d641be86 + Image: nginx-plus-ingress:jjplus + Image ID: docker.io/library/import-2023-03-27@sha256:85120b9f157bd6bb8e4469fa4aee3bbeac62c0a494d2707b47daab66b6b0b199 + Ports: 80/TCP, 443/TCP, 8081/TCP, 9113/TCP, 9114/TCP + Host Ports: 0/TCP, 0/TCP, 0/TCP, 0/TCP, 0/TCP + Args: + -nginx-plus + -nginx-configmaps=$(POD_NAMESPACE)/nginx-config + ... + -enable-service-insight + -service-insight-tls-secret=default/service-insight-secret + ... + State: Running + Started: Wed, 29 Mar 2023 14:32:25 +0100 +... +``` + +Using the nginx-ingress pod id, forward the service insight port (9114) to localhost port 9114: + +```bash +kubectl port-forward -n nginx-ingress nginx-ingress-687d9c6764-g6vwx 9114:9114 & +``` + +Follow the [basic configuration example](../basic-configuration/) to deploy `cafe` app and `cafe virtual server`. + +Send a `GET` request to the service insight (TLS) endpoint to check statistics: + +Request: + +```bash +curl https://localhost:9114/probe/cafe.example.com --insecure +``` + +Response: + +```json +{"Total":2,"Up":2,"Unhealthy":0} +``` diff --git a/examples/custom-resources/service-insight/service-insight-secret.yaml b/examples/custom-resources/service-insight/service-insight-secret.yaml new file mode 100644 index 0000000000..dea0d7dc89 --- /dev/null +++ b/examples/custom-resources/service-insight/service-insight-secret.yaml @@ -0,0 +1,8 @@ +apiVersion: v1 +kind: Secret +metadata: + name: service-insight-secret +type: kubernetes.io/tls +data: + tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURMakNDQWhZQ0NRREFPRjl0THNhWFdqQU5CZ2txaGtpRzl3MEJBUXNGQURCYU1Rc3dDUVlEVlFRR0V3SlYKVXpFTE1Ba0dBMVVFQ0F3Q1EwRXhJVEFmQmdOVkJBb01HRWx1ZEdWeWJtVjBJRmRwWkdkcGRITWdVSFI1SUV4MApaREViTUJrR0ExVUVBd3dTWTJGbVpTNWxlR0Z0Y0d4bExtTnZiU0FnTUI0WERURTRNRGt4TWpFMk1UVXpOVm9YCkRUSXpNRGt4TVRFMk1UVXpOVm93V0RFTE1Ba0dBMVVFQmhNQ1ZWTXhDekFKQmdOVkJBZ01Ba05CTVNFd0h3WUQKVlFRS0RCaEpiblJsY201bGRDQlhhV1JuYVhSeklGQjBlU0JNZEdReEdUQVhCZ05WQkFNTUVHTmhabVV1WlhoaApiWEJzWlM1amIyMHdnZ0VpTUEwR0NTcUdTSWIzRFFFQkFRVUFBNElCRHdBd2dnRUtBb0lCQVFDcDZLbjdzeTgxCnAwanVKL2N5ayt2Q0FtbHNmanRGTTJtdVpOSzBLdGVjcUcyZmpXUWI1NXhRMVlGQTJYT1N3SEFZdlNkd0kyaloKcnVXOHFYWENMMnJiNENaQ0Z4d3BWRUNyY3hkam0zdGVWaVJYVnNZSW1tSkhQUFN5UWdwaW9iczl4N0RsTGM2SQpCQTBaalVPeWwwUHFHOVNKZXhNVjczV0lJYTVyRFZTRjJyNGtTa2JBajREY2o3TFhlRmxWWEgySTVYd1hDcHRDCm42N0pDZzQyZitrOHdnemNSVnA4WFprWldaVmp3cTlSVUtEWG1GQjJZeU4xWEVXZFowZXdSdUtZVUpsc202OTIKc2tPcktRajB2a29QbjQxRUUvK1RhVkVwcUxUUm9VWTNyemc3RGtkemZkQml6Rk8yZHNQTkZ4MkNXMGpYa05MdgpLbzI1Q1pyT2hYQUhBZ01CQUFFd0RRWUpLb1pJaHZjTkFRRUxCUUFEZ2dFQkFLSEZDY3lPalp2b0hzd1VCTWRMClJkSEliMzgzcFdGeW5acS9MdVVvdnNWQTU4QjBDZzdCRWZ5NXZXVlZycTVSSWt2NGxaODFOMjl4MjFkMUpINnIKalNuUXgrRFhDTy9USkVWNWxTQ1VwSUd6RVVZYVVQZ1J5anNNL05VZENKOHVIVmhaSitTNkZBK0NuT0Q5cm4yaQpaQmVQQ0k1ckh3RVh3bm5sOHl3aWozdnZRNXpISXV5QmdsV3IvUXl1aTlmalBwd1dVdlVtNG52NVNNRzl6Q1Y3ClBwdXd2dWF0cWpPMTIwOEJqZkUvY1pISWc4SHc5bXZXOXg5QytJUU1JTURFN2IvZzZPY0s3TEdUTHdsRnh2QTgKN1dqRWVxdW5heUlwaE1oS1JYVmYxTjM0OWVOOThFejM4Zk9USFRQYmRKakZBL1BjQytHeW1lK2lHdDVPUWRGaAp5UkU9Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K + tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBcWVpcCs3TXZOYWRJN2lmM01wUHJ3Z0pwYkg0N1JUTnBybVRTdENyWG5LaHRuNDFrCkcrZWNVTldCUU5semtzQndHTDBuY0NObzJhN2x2S2wxd2k5cTIrQW1RaGNjS1ZSQXEzTVhZNXQ3WGxZa1YxYkcKQ0pwaVJ6ejBza0lLWXFHN1BjZXc1UzNPaUFRTkdZMURzcGRENmh2VWlYc1RGZTkxaUNHdWF3MVVoZHErSkVwRwp3SStBM0kreTEzaFpWVng5aU9WOEZ3cWJRcCt1eVFvT05uL3BQTUlNM0VWYWZGMlpHVm1WWThLdlVWQ2cxNWhRCmRtTWpkVnhGbldkSHNFYmltRkNaYkp1dmRySkRxeWtJOUw1S0Q1K05SQlAvazJsUkthaTAwYUZHTjY4NE93NUgKYzMzUVlzeFR0bmJEelJjZGdsdEkxNURTN3lxTnVRbWF6b1Z3QndJREFRQUJBb0lCQVFDUFNkU1luUXRTUHlxbApGZlZGcFRPc29PWVJoZjhzSStpYkZ4SU91UmF1V2VoaEp4ZG01Uk9ScEF6bUNMeUw1VmhqdEptZTIyM2dMcncyCk45OUVqVUtiL1ZPbVp1RHNCYzZvQ0Y2UU5SNThkejhjbk9SVGV3Y290c0pSMXBuMWhobG5SNUhxSkpCSmFzazEKWkVuVVFmY1hackw5NGxvOUpIM0UrVXFqbzFGRnM4eHhFOHdvUEJxalpzVjdwUlVaZ0MzTGh4bndMU0V4eUZvNApjeGI5U09HNU9tQUpvelN0Rm9RMkdKT2VzOHJKNXFmZHZ5dGdnOXhiTGFRTC94MGtwUTYyQm9GTUJEZHFPZVBXCktmUDV6WjYvMDcvdnBqNDh5QTFRMzJQem9idWJzQkxkM0tjbjMyamZtMUU3cHJ0V2wrSmVPRmlPem5CUUZKYk4KNHFQVlJ6NWhBb0dCQU50V3l4aE5DU0x1NFArWGdLeWNrbGpKNkY1NjY4Zk5qNUN6Z0ZScUowOXpuMFRsc05ybwpGVExaY3hEcW5SM0hQWU00MkpFUmgySi9xREZaeW5SUW8zY2czb2VpdlVkQlZHWTgrRkkxVzBxZHViL0w5K3l1CmVkT1pUUTVYbUdHcDZyNmpleHltY0ppbS9Pc0IzWm5ZT3BPcmxEN1NQbUJ2ek5MazRNRjZneGJYQW9HQkFNWk8KMHA2SGJCbWNQMHRqRlhmY0tFNzdJbUxtMHNBRzR1SG9VeDBlUGovMnFyblRuT0JCTkU0TXZnRHVUSnp5K2NhVQprOFJxbWRIQ2JIelRlNmZ6WXEvOWl0OHNaNzdLVk4xcWtiSWN1YytSVHhBOW5OaDFUanNSbmU3NFowajFGQ0xrCmhIY3FIMHJpN1BZU0tIVEU4RnZGQ3haWWRidUI4NENtWmlodnhicFJBb0dBSWJqcWFNWVBUWXVrbENkYTVTNzkKWVNGSjFKelplMUtqYS8vdER3MXpGY2dWQ0thMzFqQXdjaXowZi9sU1JxM0hTMUdHR21lemhQVlRpcUxmZVpxYwpSMGlLYmhnYk9jVlZrSkozSzB5QXlLd1BUdW14S0haNnpJbVpTMGMwYW0rUlk5WUdxNVQ3WXJ6cHpjZnZwaU9VCmZmZTNSeUZUN2NmQ21mb09oREN0enVrQ2dZQjMwb0xDMVJMRk9ycW40M3ZDUzUxemM1em9ZNDR1QnpzcHd3WU4KVHd2UC9FeFdNZjNWSnJEakJDSCtULzZzeXNlUGJKRUltbHpNK0l3eXRGcEFOZmlJWEV0LzQ4WGY2ME54OGdXTQp1SHl4Wlp4L05LdER3MFY4dlgxUE9ucTJBNWVpS2ErOGpSQVJZS0pMWU5kZkR1d29seHZHNmJaaGtQaS80RXRUCjNZMThzUUtCZ0h0S2JrKzdsTkpWZXN3WEU1Y1VHNkVEVXNEZS8yVWE3ZlhwN0ZjanFCRW9hcDFMU3crNlRYcDAKWmdybUtFOEFSek00NytFSkhVdmlpcS9udXBFMTVnMGtKVzNzeWhwVTl6WkxPN2x0QjBLSWtPOVpSY21Vam84UQpjcExsSE1BcWJMSjhXWUdKQ2toaVd4eWFsNmhZVHlXWTRjVmtDMHh0VGwvaFVFOUllTktvCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==