From edef542116d70512c04eebc62e70b49157789f51 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Fri, 17 May 2024 17:14:38 +0200 Subject: [PATCH 1/5] global and route based setup for ext auth service --- examples/kubernetes/Justfile | 12 +++++++--- .../overlays/nginx-global/ingress.yaml | 24 +++++++++++++++++++ .../kustomization.yaml | 0 .../{nginx => nginx-route-based}/ingress.yaml | 0 .../nginx-route-based/kustomization.yaml | 5 ++++ 5 files changed, 38 insertions(+), 3 deletions(-) create mode 100644 examples/kubernetes/quickstarts/demo-app/overlays/nginx-global/ingress.yaml rename examples/kubernetes/quickstarts/demo-app/overlays/{nginx => nginx-global}/kustomization.yaml (100%) rename examples/kubernetes/quickstarts/demo-app/overlays/{nginx => nginx-route-based}/ingress.yaml (100%) create mode 100644 examples/kubernetes/quickstarts/demo-app/overlays/nginx-route-based/kustomization.yaml diff --git a/examples/kubernetes/Justfile b/examples/kubernetes/Justfile index 559a86321..2bdfed743 100644 --- a/examples/kubernetes/Justfile +++ b/examples/kubernetes/Justfile @@ -93,11 +93,15 @@ install-heimdall-pod-monitor: install-observability-stack: install-grafana install-prometheus install-loki install-tempo install-phlare install-dashboards install-heimdall-pod-monitor -install-nginx-ingress-controller: +install-nginx-ingress-controller global_ext_auth="true": + #!/usr/bin/env bash + + valuesFile=$({{global_ext_auth}} && echo global-helm-values.yaml || echo helm-values.yaml) + helm upgrade --install ingress-nginx ingress-nginx/ingress-nginx \ -n nginx-controller --create-namespace \ --version {{nginx_version}} \ - --set controller.allowSnippetAnnotations=true \ + -f nginx/${valuesFile} \ --wait install-contour-ingress-controller: @@ -222,7 +226,9 @@ create-cluster: setup-cluster: create-cluster setup-charts install-lb install-cert-manager -install-ngnix-decision-demo: setup-cluster install-nginx-ingress-controller (install-heimdall "nginx") (install-echo-service "nginx") +install-ngnix-decision-demo: setup-cluster (install-nginx-ingress-controller "false") (install-heimdall "nginx") (install-echo-service "nginx-route-based") + +install-ngnix-global-decision-demo: setup-cluster install-nginx-ingress-controller (install-heimdall "nginx") (install-echo-service "nginx-global") install-contour-decision-demo: setup-cluster install-contour-ingress-controller (install-heimdall "contour") (install-echo-service "contour") diff --git a/examples/kubernetes/quickstarts/demo-app/overlays/nginx-global/ingress.yaml b/examples/kubernetes/quickstarts/demo-app/overlays/nginx-global/ingress.yaml new file mode 100644 index 000000000..cc15a8168 --- /dev/null +++ b/examples/kubernetes/quickstarts/demo-app/overlays/nginx-global/ingress.yaml @@ -0,0 +1,24 @@ +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: echo-app + namespace: quickstarts + labels: + app.kubernetes.io/name: echo-app +spec: + ingressClassName: "nginx" + tls: + - hosts: + - echo-app.local + secretName: echo-app + rules: + - host: echo-app.local + http: + paths: + - path: / + pathType: ImplementationSpecific + backend: + service: + name: echo-app + port: + number: 8080 \ No newline at end of file diff --git a/examples/kubernetes/quickstarts/demo-app/overlays/nginx/kustomization.yaml b/examples/kubernetes/quickstarts/demo-app/overlays/nginx-global/kustomization.yaml similarity index 100% rename from examples/kubernetes/quickstarts/demo-app/overlays/nginx/kustomization.yaml rename to examples/kubernetes/quickstarts/demo-app/overlays/nginx-global/kustomization.yaml diff --git a/examples/kubernetes/quickstarts/demo-app/overlays/nginx/ingress.yaml b/examples/kubernetes/quickstarts/demo-app/overlays/nginx-route-based/ingress.yaml similarity index 100% rename from examples/kubernetes/quickstarts/demo-app/overlays/nginx/ingress.yaml rename to examples/kubernetes/quickstarts/demo-app/overlays/nginx-route-based/ingress.yaml diff --git a/examples/kubernetes/quickstarts/demo-app/overlays/nginx-route-based/kustomization.yaml b/examples/kubernetes/quickstarts/demo-app/overlays/nginx-route-based/kustomization.yaml new file mode 100644 index 000000000..c9af21949 --- /dev/null +++ b/examples/kubernetes/quickstarts/demo-app/overlays/nginx-route-based/kustomization.yaml @@ -0,0 +1,5 @@ +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +resources: + - ../../base + - ingress.yaml \ No newline at end of file From 587b01d65aef8cef14db64e54f952630a188e28b Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Fri, 17 May 2024 20:25:01 +0200 Subject: [PATCH 2/5] forgotten helm settings --- examples/kubernetes/nginx/global-helm-values.yaml | 9 +++++++++ examples/kubernetes/nginx/helm-values.yaml | 2 ++ 2 files changed, 11 insertions(+) create mode 100644 examples/kubernetes/nginx/global-helm-values.yaml create mode 100644 examples/kubernetes/nginx/helm-values.yaml diff --git a/examples/kubernetes/nginx/global-helm-values.yaml b/examples/kubernetes/nginx/global-helm-values.yaml new file mode 100644 index 000000000..24b83b8e7 --- /dev/null +++ b/examples/kubernetes/nginx/global-helm-values.yaml @@ -0,0 +1,9 @@ +controller: + config: + global-auth-url: https://heimdall.heimdall.svc.cluster.local:4456 + global-auth-response-headers: "Authorization" + global-auth-snippet: | + proxy_set_header X-Forwarded-Method $request_method; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Host $http_host; + proxy_set_header X-Forwarded-Uri $request_uri; \ No newline at end of file diff --git a/examples/kubernetes/nginx/helm-values.yaml b/examples/kubernetes/nginx/helm-values.yaml new file mode 100644 index 000000000..a004fcc2f --- /dev/null +++ b/examples/kubernetes/nginx/helm-values.yaml @@ -0,0 +1,2 @@ +controller: + allowSnippetAnnotations: true \ No newline at end of file From 2927958cafe27552267da500fb0a35ebbb8bc783 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Fri, 17 May 2024 20:45:42 +0200 Subject: [PATCH 3/5] nginx guide updated to describe a global integration option --- docs/content/guides/proxies/nginx.adoc | 41 +++++++++++++++++++------- 1 file changed, 31 insertions(+), 10 deletions(-) diff --git a/docs/content/guides/proxies/nginx.adoc b/docs/content/guides/proxies/nginx.adoc index 6a5e8849d..31e2e7df2 100644 --- a/docs/content/guides/proxies/nginx.adoc +++ b/docs/content/guides/proxies/nginx.adoc @@ -124,24 +124,21 @@ location = /_auth { == NGINX Ingress Controller -Even one can configure an external auth server globally with vanilla NGINX, there is no way to achieve that with the https://kubernetes.github.io/ingress-nginx/[NGINX Ingress Controller]. Only route based configuration/integration is possible. +=== Global Configuration -=== Using `X-Forwarded-*` headers +NOTE: The configuration used in the example below requires proper configuration of `trusted_proxies` on heimdall side. -To integrate heimdall with the NGINX Ingress Controller you can make use of the `nginx.ingress.kubernetes.io/auth-url`, `nginx.ingress.kubernetes.io/auth-response-headers` and the `nginx.ingress.kubernetes.io/auth-snippet` annotation as shown in the example below. This will result in an NGINX configuration corresponding to the integration option, described in the link:{{< relref "#_second_option" >}}[Forward all information in `X-Forwarded-*` headers] section. - -NOTE: The configuration used in the example below requires proper configuration of `trusted_proxies` on heimdall side. On NGINX Ingress Controller side you must allow the usage of `nginx.ingress.kubernetes.io/auth-snippet` (See also https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#allow-snippet-annotations[here]). +Global configuration can be achieved by setting the following properties in controller `ConfigMap`. If you install the NGINX controller via the helm chart, you can add these properties under the `controller.config` property of your helm `values.yaml` file. [source, yaml] ---- -nginx.ingress.kubernetes.io/auth-url: "http://..svc.cluster.local:" # <1> -nginx.ingress.kubernetes.io/auth-response-headers: Authorization # <2> -nginx.ingress.kubernetes.io/auth-snippet: | # <3> +global-auth-url: "http://..svc.cluster.local:" # <1> +global-auth-response-headers: Authorization # <2> +global-auth-snippet: | # <3> proxy_set_header X-Forwarded-Method $request_method; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Host $http_host; proxy_set_header X-Forwarded-Uri $request_uri; -# other annotations required ---- <1> Configures the controller to use heimdall's decision service endpoint with ``, `` and `` depending on your configuration. <2> Let NGINX forward the `Authorization` header set by heimdall to the upstream service upon successful response. This configuration depends on @@ -150,7 +147,31 @@ your link:{{< relref "/docs/mechanisms/contextualizers.adoc" >}}[Contextualizers + NOTE: Without that, heimdall will not be able extracting relevant information from the NGINX request as it does not support NGINX proprietary `X-Original-Method` and `X-Original-Uri` used by it for the same purposes. -=== Alternative Configuration +With that in place, you can simply use the standard https://kubernetes.io/docs/concepts/services-networking/ingress/[`Ingress`] resource, and the NGINX Ingress Controller will ensure, each request will be analyzed by heimdall first. + +=== Integration on `Ingress` Resource Level + +==== Using `X-Forwarded-*` headers + +To integrate heimdall with the NGINX Ingress Controller you can make use of the `nginx.ingress.kubernetes.io/auth-url`, `nginx.ingress.kubernetes.io/auth-response-headers` and the `nginx.ingress.kubernetes.io/auth-snippet` annotation as shown in the example below. This will result in an NGINX configuration corresponding to the integration option, described in the link:{{< relref "#_second_option" >}}[Forward all information in `X-Forwarded-*` headers] section. + +NOTE: The configuration used in the example below requires proper configuration of `trusted_proxies` on heimdall side. On NGINX Ingress Controller side you must allow the usage of `nginx.ingress.kubernetes.io/auth-snippet` (See also https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#allow-snippet-annotations[here]). + +[source, yaml] +---- +nginx.ingress.kubernetes.io/auth-url: "http://..svc.cluster.local:" +nginx.ingress.kubernetes.io/auth-response-headers: Authorization +nginx.ingress.kubernetes.io/auth-snippet: | + proxy_set_header X-Forwarded-Method $request_method; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Host $http_host; + proxy_set_header X-Forwarded-Uri $request_uri; +# other annotations required +---- + +It is very similar to the link:{{< relref "#_global_configuration" >}}[Global Configuration]. + +==== Alternative Configuration Alternatively, if you don't want configuring `trusted_proxies` and do not rely on the used HTTP scheme, host and port in your rules, you can also use the `nginx.ingress.kubernetes.io/configuration-snippet` and `nginx.ingress.kubernetes.io/server-snippet` annotations and use the configuration shown below. From 133d676150bd5288ec2b6c010dde21d8b38c0157 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Fri, 17 May 2024 20:47:48 +0200 Subject: [PATCH 4/5] some simplifications --- docs/content/guides/proxies/nginx.adoc | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/content/guides/proxies/nginx.adoc b/docs/content/guides/proxies/nginx.adoc index 31e2e7df2..a6cc3d19a 100644 --- a/docs/content/guides/proxies/nginx.adoc +++ b/docs/content/guides/proxies/nginx.adoc @@ -153,7 +153,7 @@ With that in place, you can simply use the standard https://kubernetes.io/docs/c ==== Using `X-Forwarded-*` headers -To integrate heimdall with the NGINX Ingress Controller you can make use of the `nginx.ingress.kubernetes.io/auth-url`, `nginx.ingress.kubernetes.io/auth-response-headers` and the `nginx.ingress.kubernetes.io/auth-snippet` annotation as shown in the example below. This will result in an NGINX configuration corresponding to the integration option, described in the link:{{< relref "#_second_option" >}}[Forward all information in `X-Forwarded-*` headers] section. +To integrate heimdall with the NGINX Ingress Controller you can make use of the `nginx.ingress.kubernetes.io/auth-url`, `nginx.ingress.kubernetes.io/auth-response-headers` and the `nginx.ingress.kubernetes.io/auth-snippet` annotation as shown in the example below. This will result in an NGINX configuration corresponding to the integration option, described in the link:{{< relref "#_second_option" >}}[Forward all information in `X-Forwarded-*` headers] and the link:{{< relref "#_global_configuration" >}}[Global Configuration] for the NGINX Ingress Controller sections. NOTE: The configuration used in the example below requires proper configuration of `trusted_proxies` on heimdall side. On NGINX Ingress Controller side you must allow the usage of `nginx.ingress.kubernetes.io/auth-snippet` (See also https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#allow-snippet-annotations[here]). @@ -169,8 +169,6 @@ nginx.ingress.kubernetes.io/auth-snippet: | # other annotations required ---- -It is very similar to the link:{{< relref "#_global_configuration" >}}[Global Configuration]. - ==== Alternative Configuration Alternatively, if you don't want configuring `trusted_proxies` and do not rely on the used HTTP scheme, host and port in your rules, you can also use the `nginx.ingress.kubernetes.io/configuration-snippet` and `nginx.ingress.kubernetes.io/server-snippet` annotations and use the configuration shown below. From 600fe96f33e6068370495303e3b8df5a4eb76550 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Fri, 17 May 2024 21:44:05 +0200 Subject: [PATCH 5/5] more global integration options --- docs/content/guides/proxies/nginx.adoc | 37 +++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/docs/content/guides/proxies/nginx.adoc b/docs/content/guides/proxies/nginx.adoc index a6cc3d19a..91e9439f6 100644 --- a/docs/content/guides/proxies/nginx.adoc +++ b/docs/content/guides/proxies/nginx.adoc @@ -126,6 +126,8 @@ location = /_auth { === Global Configuration +==== Using `X-Forwarded-*` headers + NOTE: The configuration used in the example below requires proper configuration of `trusted_proxies` on heimdall side. Global configuration can be achieved by setting the following properties in controller `ConfigMap`. If you install the NGINX controller via the helm chart, you can add these properties under the `controller.config` property of your helm `values.yaml` file. @@ -149,13 +151,42 @@ NOTE: Without that, heimdall will not be able extracting relevant information fr With that in place, you can simply use the standard https://kubernetes.io/docs/concepts/services-networking/ingress/[`Ingress`] resource, and the NGINX Ingress Controller will ensure, each request will be analyzed by heimdall first. +This will result in an NGINX configuration corresponding to the integration option, described in the link:{{< relref "#_second_option" >}}[Forward all information in `X-Forwarded-*` headers] section. + +==== Alternative Configuration + +Alternatively, if you don't want configuring `trusted_proxies` and do not rely on the used HTTP scheme, host and port in your rules, you can also use the `location-snippet` and the `server-snippet` to the `ConfigMap` of the NGINX Ingress Controller with values shown below. + +This example is an exact copy of the configuration used in the very first link:{{< relref "#_first_option" >}}[integration option] described above. + +[source, yaml] +---- +location-snippet: | + auth_request /_auth; + auth_request_set $auth_cookie $upstream_http_set_cookie; + add_header Set-Cookie $auth_cookie; + auth_request_set $auth_header $upstream_http_authorization; + proxy_set_header 'Authorization' $auth_header; + proxy_set_header Proxy ""; +server-snippet: | + location = /_auth { + internal; + access_log off; + proxy_method $request_method; + proxy_pass http://..svc.cluster.local:$request_uri; + proxy_pass_request_body off; + proxy_set_header Content-Length ""; + proxy_set_header Host $http_host; + } +---- + +As with the previous integration option, you can add these properties under the `controller.config` property of your helm `values.yaml` file if you install the NGINX Ingress Controller via helm. + === Integration on `Ingress` Resource Level ==== Using `X-Forwarded-*` headers -To integrate heimdall with the NGINX Ingress Controller you can make use of the `nginx.ingress.kubernetes.io/auth-url`, `nginx.ingress.kubernetes.io/auth-response-headers` and the `nginx.ingress.kubernetes.io/auth-snippet` annotation as shown in the example below. This will result in an NGINX configuration corresponding to the integration option, described in the link:{{< relref "#_second_option" >}}[Forward all information in `X-Forwarded-*` headers] and the link:{{< relref "#_global_configuration" >}}[Global Configuration] for the NGINX Ingress Controller sections. - -NOTE: The configuration used in the example below requires proper configuration of `trusted_proxies` on heimdall side. On NGINX Ingress Controller side you must allow the usage of `nginx.ingress.kubernetes.io/auth-snippet` (See also https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#allow-snippet-annotations[here]). +One option to integrate heimdall with the NGINX Ingress Controller on the `Ingress` resource level is making use of the `nginx.ingress.kubernetes.io/auth-url`, `nginx.ingress.kubernetes.io/auth-response-headers` and the `nginx.ingress.kubernetes.io/auth-snippet` annotation as shown in the example below. This approach requires proper configuration of `trusted_proxies` on heimdall side. On NGINX Ingress Controller side you must allow the usage of `nginx.ingress.kubernetes.io/auth-snippet` (See also https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#allow-snippet-annotations[here]). [source, yaml] ----