From b6575c172db0069ab68532438bb99fd76e53c28b Mon Sep 17 00:00:00 2001 From: Mariusz Sabath Date: Thu, 9 May 2024 07:26:17 -0400 Subject: [PATCH] Update Tornjak deployment docs (#288) * Update Tornjak deployment docs Signed-off-by: Mariusz Sabath * Change the reference for installing standard Tornjak Signed-off-by: Mariusz Sabath * Update examples/tornjak/README.md Co-authored-by: kfox1111 Signed-off-by: Mariusz Sabath * Adjust deployment paths Signed-off-by: Mariusz Sabath * Remove the production README changes Signed-off-by: Mariusz Sabath * Minor text edits Signed-off-by: Mariusz Sabath * Fix incorrect namespace value Signed-off-by: Mariusz Sabath * Updat Tornjak README Signed-off-by: Mariusz Sabath * Update Keycloak README Signed-off-by: Mariusz Sabath * Text updates in Keycloak doc Signed-off-by: Mariusz Sabath * Post-review updates Signed-off-by: Mariusz Sabath * Update Tornjak message for User Management Signed-off-by: Mariusz Sabath * Update examples/tornjak/keycloak/README.md Co-authored-by: Mohammed Abdi Signed-off-by: Mariusz Sabath * Update Tornjak deployment doc Signed-off-by: Mariusz Sabath * Improve the Tornjak Auth message Signed-off-by: Mariusz Sabath * Fix error with incorrect Ingress value Signed-off-by: Mariusz Sabath * Fix documentation format Signed-off-by: Mariusz Sabath * Update parameter format Signed-off-by: Mariusz Sabath * Removed redundand doc sections Signed-off-by: Mariusz Sabath --------- Signed-off-by: Mariusz Sabath Co-authored-by: kfox1111 Co-authored-by: Mohammed Abdi --- .../charts/spire-server/templates/NOTES.txt | 4 +- .../tornjak-frontend/templates/NOTES.txt | 15 ++- examples/tornjak/README.md | 99 +++++++++----- examples/tornjak/keycloak/README.md | 121 +++++++----------- examples/tornjak/values.yaml | 1 - 5 files changed, 122 insertions(+), 118 deletions(-) diff --git a/charts/spire/charts/spire-server/templates/NOTES.txt b/charts/spire/charts/spire-server/templates/NOTES.txt index f4d368f..d882cad 100644 --- a/charts/spire/charts/spire-server/templates/NOTES.txt +++ b/charts/spire/charts/spire-server/templates/NOTES.txt @@ -1,8 +1,8 @@ Installed {{ .Chart.Name }}… -1. Get the currently registered SPIFFE entries from the server: +Get the currently registered SPIFFE entries from the server: - kubectl exec -n {{ .Release.Namespace }} {{ include "spire-server.fullname" . }}-0 -c spire-server -- \ + kubectl exec -n {{ include "spire-server.namespace" . }} {{ include "spire-server.fullname" . }}-0 -c spire-server -- \ spire-server entry show {{- if eq (.Values.tornjak.enabled | toString) "true" }} diff --git a/charts/spire/charts/tornjak-frontend/templates/NOTES.txt b/charts/spire/charts/tornjak-frontend/templates/NOTES.txt index ad5c90f..752ca75 100644 --- a/charts/spire/charts/tornjak-frontend/templates/NOTES.txt +++ b/charts/spire/charts/tornjak-frontend/templates/NOTES.txt @@ -6,14 +6,15 @@ Your release is named: {{ .Release.Name }} Namespace: {{ include "tornjak-frontend.namespace" . }} Tornjak UI (Frontend) - image: {{ template "spire-lib.image" (dict "appVersion" $.Chart.AppVersion "image" .Values.image "global" .Values.global) }} - pull policy: {{ .Values.image.pullPolicy }} + Image: {{ template "spire-lib.image" (dict "appVersion" $.Chart.AppVersion "image" .Values.image "global" .Values.global) }} + Image pull policy: {{ .Values.image.pullPolicy }} + Ingress enabled: {{ .Values.ingress.enabled }} Tornjak API (Backend): {{ include "tornjak-frontend.apiURL" . }} - SPIRE health check enabled: "{{ .Values.spireHealthCheck.enabled }}" - User Managemenet enabled: "{{ .Values.auth.enabled }}" - User Managemenet API: "{{ .Values.auth.serverURL }}" - -{{- if not .Values.auth.enabled }} + SPIRE health check enabled: {{ .Values.spireHealthCheck.enabled }} + User Management enabled: {{ .Values.auth.enabled }} +{{- if .Values.auth.enabled }} + User Management API: "{{ .Values.auth.serverURL }}" +{{- else }} ### WARNING ### Tornjak is configured to run without authentication and is therefore NOT suitable to run in production environments. diff --git a/examples/tornjak/README.md b/examples/tornjak/README.md index cf876ca..8893209 100644 --- a/examples/tornjak/README.md +++ b/examples/tornjak/README.md @@ -1,29 +1,41 @@ # Recommended setup to deploy Tornjak -To install Spire with the least privileges possible we deploy spire across 2 namespaces. +> [!WARNING] +> The default version of Tornjak in this chart is deployed without authentication. Therefore it is not suitable to run this version in production. In order to enable the user authentication, +> follow [Keycloak instructions](keycloak/README.md) + +## Deploy Standard SPIRE + +Follow the production installation of SPIRE as described in the [install instructions] (https://artifacthub.io/packages/helm/spiffe/spire) document. + +## Upgrade to enable Tornjak + +Before we can deploy Tornjak with SPIRE we need to decide whether the services would be +using direct access, Ingress, or some other method. + +## Tornjak with Direct Access + +This can be done using port-forward. For example, to start Tornjak APIs on port 10000 + +Deploy SPIRE with Tornjak enabled ```shell -kubectl create namespace "spire-system" -kubectl label namespace "spire-system" pod-security.kubernetes.io/enforce=privileged -kubectl create namespace "spire-server" -kubectl label namespace "spire-server" pod-security.kubernetes.io/enforce=restricted +export TORNJAK_API=http://localhost:10000 -# deploy SPIRE with Tornjak enabled -helm upgrade --install --namespace spire-server spire charts/spire \ ---values tests/integration/psat/values.yaml \ +helm upgrade --install -n spire-mgmt spire spire \ +--repo https://spiffe.github.io/helm-charts-hardened/ \ +--set tornjak-frontend.apiServerURL=$TORNJAK_API \ --values examples/tornjak/values.yaml \ +--values your-values.yaml \ --render-subchart-notes - # test the Tornjak deployment helm test spire -n spire-server ``` -## Access Tornjak - -To access Tornjak you will have to use port-forwarding for the time being *(until we add authentication and ingress)*. - -Run following commands from your shell, if you ran with different values your namespace might differ. Consult the install notes printed when running above `helm upgrade` command in that case. +Run following commands from your shell, to start port forwarding for Tornjak backend (APIs) +and Tornjak frontend (UI) services. + If you deployed in different namespace, your values might differ. Consult the install notes printed when running above `helm upgrade` command in that case. Since `port-forward` is a blocking command, execute them in two different consoles: @@ -35,38 +47,63 @@ kubectl -n spire-server port-forward service/spire-tornjak-backend 10000:10000 kubectl -n spire-server port-forward service/spire-tornjak-frontend 3000:3000 ``` -You can now access Tornjak at [localhost:3000](http://localhost:3000). +You can now access Tornjak with your browser at [localhost:3000](http://localhost:3000). See [values.yaml](./values.yaml) for more details on the chart configurations to achieve this setup. -## Tornjak and Ingress with ingress-nginx +## Deploy Tornjak with ingress-nginx -Update examples/production/example-your-values.yaml with your information, most importantly, trustDomain. +Update your-values.yaml with your ingress information, most importantly, trustDomain, and redeploy +adding the following: ```shell -helm upgrade --install --namespace spire-server spire charts/spire \ ---values tests/integration/psat/values.yaml \ ---values examples/tornjak/values.yaml \ ---values examples/tornjak/values-ingress.yaml \ --set global.spire.ingressControllerType=ingress-nginx \ ---render-subchart-notes --debug +--values examples/tornjak/values-ingress.yaml ``` -## Tornjak and Ingress on Openshift +## Deploy Tornjak with Ingress on Openshift -When deploying on Openshift, follow the deployment setup as described in -[Openshift README](../openshift/README.md) - -Then just add Openshift specific configuration to the above command: +Obtain the OpenShift Apps Subdomain for Ingress and assign it to the `trustDomain` +environment variable: ```shell ---values examples/openshift/openshift-values.yaml +export appdomain=$(oc get cm -n openshift-config-managed console-public -o go-template="{{ .data.consoleURL }}" | sed 's@https://@@; s/^[^.]*\.//') +echo $appdomain +``` + +So it can be passed as follow: + +```shell +--set global.openshift=true \ +--set global.spire.trustDomain=$appdomain \ +--values examples/tornjak/values-ingress.yaml \ ``` When running on Openshift in some environments like IBM Cloud, -you might need to add the following configurations: +you might need to also add the following configurations: ```shell ---set spiffe-csi-driver.kubeletPath=/var/data/kubelet \ ---set spiffe-csi-driver.restrictedScc.enabled=true \ +--values examples/openshift/values-ibm-cloud.yaml +``` + +## Validation + +Confirm access to the Tornjak API (backend): + +```shell +curl https://tornjak-backend.$appdomain +"Welcome to the Tornjak Backend!" +``` + +If the APIs are accessible, we can verify the Tornjak UI (A React application running in the local browser) can be accessed. +Test access to Tornjak by opening the URL provided in Tornjak-frontend route: + +```shell +oc get route -n spire-server -l=app.kubernetes.io/name=tornjak-frontend -o jsonpath='https://{ .items[0].spec.host }' +``` + +The value should match the following URL: + +```shell +echo "https://tornjak-frontend.$appdomain" ``` diff --git a/examples/tornjak/keycloak/README.md b/examples/tornjak/keycloak/README.md index 46cc2c6..f9c4731 100644 --- a/examples/tornjak/keycloak/README.md +++ b/examples/tornjak/keycloak/README.md @@ -4,16 +4,18 @@ This example demonstrates Tornjak's capability to control access to the Frontend User Management via [Keycloak](https://www.keycloak.org/). Tested on: + - Keycloak Application Version - 24.0.3 - Keycloak Chart Version - 21.0.3 For more information regarding Tornjak User Management, please refer to the following documentation: -* [Tornjak User Management](https://github.com/spiffe/tornjak/blob/main/docs/keycloak-configuration.md) -* [Keycloak Configuration for Tornjak](https://github.com/spiffe/tornjak/blob/main/docs/keycloak-configuration.md) -* [Detailed Blogs on Tornjak User Management](https://github.com/spiffe/tornjak/blob/main/docs/blogs.md) +- [Tornjak User Management](https://github.com/spiffe/tornjak/blob/main/docs/user-management.md) +- [Keycloak Configuration for Tornjak](https://github.com/spiffe/tornjak/blob/main/docs/keycloak-configuration.md) +- [Detailed Blogs on Tornjak User Management](https://github.com/spiffe/tornjak/blob/main/docs/blogs.md) -**NOTE:** This example works only with the Vanilla version of Kubernetes; it does not yet support Openshift. +> [!NOTE] +> This example works only with the Vanilla version of Kubernetes; it does not yet support Openshift. As part of the exercise, an instance of Keycloak is deployed to illustrate how to manage users' access to Tornjak. Once enabled, the Tornjak UI will redirect all authentication calls to the Keycloak instance to obtain the @@ -21,94 +23,59 @@ correct credentials. Authorization is based on these credentials and occurs at t ## Deploy Keycloak Instance (Authentication Service) -We will deploy the instance of Keycloak in the same namespace as the SPIRE Server +We will deploy the instance of Keycloak in a dedicated namespace ```shell -# Create a namespace to deploy Keycloak and SPIRE-server -kubectl create namespace spire-server +# If does not exist, create a namespace to deploy Keycloak +kubectl create namespace keycloak ``` +> [!IMPORTANT] +> The example uses default userid and password (`admin`,`admin`). You must change these values +> by setting `auth.adminUser` and `auth.adminPassword` as shown below. + ```shell -# Deploy Keycloak as an authentication service -helm upgrade --install -n spire-server keycloak --values examples/tornjak/keycloak/values.yaml oci://registry-1.docker.io/bitnamicharts/keycloak --render-subchart-notes +# Deploy most recent Keycloak instance as an authentication service +helm upgrade --install -n keycloak keycloak \ +--values examples/tornjak/keycloak/values.yaml \ +--set auth.adminUser=your-userid --set auth.adminPassword=your-password \ +oci://registry-1.docker.io/bitnamicharts/keycloak --render-subchart-notes ``` -* It's important to start the service before configuring Tornjak with auth. +> [!IMPORTANT] +> It is important to start the Tornjak service before starting Tornjak with authentication + +The example below demonstrates port forward for local access. In cloud deployment scenario, +enable Ingress to the Keycloak service accordingly. ```shell -# Start an auth Service [Keycloak] (Terminal 3) -kubectl -n spire-server port-forward service/keycloak 8080:80 +# Start an auth Service [Keycloak] in separate terminal +kubectl -n keycloak port-forward service/keycloak 8080:80 ``` + +See the helm Notes for more information about accessing Keycloak + ## Deploy SPIRE with Tornjak User Management Enabled -Please follow the instructions for deploying Tornjak as specified in Tornjak Example [here](../README.md) +Please follow the instructions for [deploying Tornjak](../README.md) with addition of the User Management values `--values examples/tornjak/values-auth.yaml`. -For example: +> [!IMPORTANT] +> Make sure Tornjak backend User Management issuer points to the correct Keycloak issuer URL. Which is in format +> `http://.:/realms/tornjak`. +> For the example above it will be: `http://keycloak.keycloak:8080/realms/tornjak` +> You can set the issuer URL using `--set spire-server.tornjak.config.userManagement.issuer=http://tornjak.tornjak:8080/realms/tornjak` +> +> [!IMPORTANT] +> If audience is set, make sure the Tornjak backend `audience` is set correctly. You can set it using: +> `--set spire-server.tornjak.config.userManagement.audience=your-audience` +> +> [!TIP] +> Keep in mind, when redeploying Tornjak, you might have to recreate port forwarding for that service. -```shell -# Install SPIRE CRDs -helm upgrade --install --create-namespace -n spire-mgmt spire-crds charts/spire-crds -``` - -```shell -# Standard SPIRE and Tornjak deployment with Authentication enabled -helm upgrade --install \ ---set global.spire.namespaces.system.create=true \ ---values tests/integration/psat/values.yaml \ ---values examples/tornjak/values.yaml \ ---values examples/tornjak/values-auth.yaml \ ---render-subchart-notes spire charts/spire -``` - -To test the deployment, you can run the SPIRE test: - -```shell -# Test the Tornjak deployment -helm test spire -``` +The sample [examples/tornjak/values-auth.yaml](../values-auth.yaml) assumes local +Keycloak deployment using port forwarding. When using Ingress, update the URLs accordingly. ## Access Tornjak -To access Tornjak use port-forwarding or check the ingress option below. - -Run following commands from your shell, if you run with different values your namespace might differ. Consult the install notes printed when running above `helm upgrade` command in that case. - -Since `port-forward` is a blocking command, execute them in three different consoles (one for backend, one for frontend and one for auth that you already started in the previous step): - -```shell -# Start a backend Service (Terminal 1) -kubectl -n spire-server port-forward service/spire-tornjak-backend 10000:10000 -``` - -```shell -# Start a frontend Service (Terminal 2) -kubectl -n spire-server port-forward service/spire-tornjak-frontend 3000:3000 -``` - -* You can now access Tornjak at [localhost:3000](http://localhost:3000). - -* This will redirect to the auth service for authentication to [localhost:8080](http://localhost:8080) - -See [values.yaml](./values.yaml) for more details on the chart configurations to customize authentication config. - -## Deploy SPIRE with Tornjak User Management Enabled using Ingress - -When deployment uses Ingress, the access to Tornjak application and Keycloak will be different from above. -Please follow the deployment and configuration instructions as described [here](../README.md) -and make sure to add the `--values examples/tornjak/values-auth.yaml` parameter that is referencing Tornjak Authentication values. - -And update your `examples/production/example-your-values.yaml` most importantly, `trustDomain`, accordingly. - -E.g: - -```shell -helm upgrade --install \ ---set global.spire.namespaces.create=true \ ---set global.spire.ingressControllerType=ingress-nginx \ ---values tests/integration/psat/values.yaml \ ---values examples/tornjak/values.yaml \ ---values examples/tornjak/values-auth.yaml \ ---values examples/tornjak/values-ingress.yaml \ ---render-subchart-notes spire charts/spire -``` +Follow the standard [steps for Accessing Tornjak](../README.md) diff --git a/examples/tornjak/values.yaml b/examples/tornjak/values.yaml index 688c2b0..6ba0015 100644 --- a/examples/tornjak/values.yaml +++ b/examples/tornjak/values.yaml @@ -4,7 +4,6 @@ spire-server: tornjak-frontend: enabled: true - apiServerURL: "http://localhost:10000" service: type: ClusterIP port: 3000