Update Tornjak deployment docs (#288)
* Update Tornjak deployment docs Signed-off-by: Mariusz Sabath <[email protected]> * Change the reference for installing standard Tornjak Signed-off-by: Mariusz Sabath <[email protected]> * Update examples/tornjak/README.md Co-authored-by: kfox1111 <[email protected]> Signed-off-by: Mariusz Sabath <[email protected]> * Adjust deployment paths Signed-off-by: Mariusz Sabath <[email protected]> * Remove the production README changes Signed-off-by: Mariusz Sabath <[email protected]> * Minor text edits Signed-off-by: Mariusz Sabath <[email protected]> * Fix incorrect namespace value Signed-off-by: Mariusz Sabath <[email protected]> * Updat Tornjak README Signed-off-by: Mariusz Sabath <[email protected]> * Update Keycloak README Signed-off-by: Mariusz Sabath <[email protected]> * Text updates in Keycloak doc Signed-off-by: Mariusz Sabath <[email protected]> * Post-review updates Signed-off-by: Mariusz Sabath <[email protected]> * Update Tornjak message for User Management Signed-off-by: Mariusz Sabath <[email protected]> * Update examples/tornjak/keycloak/README.md Co-authored-by: Mohammed Abdi <[email protected]> Signed-off-by: Mariusz Sabath <[email protected]> * Update Tornjak deployment doc Signed-off-by: Mariusz Sabath <[email protected]> * Improve the Tornjak Auth message Signed-off-by: Mariusz Sabath <[email protected]> * Fix error with incorrect Ingress value Signed-off-by: Mariusz Sabath <[email protected]> * Fix documentation format Signed-off-by: Mariusz Sabath <[email protected]> * Update parameter format Signed-off-by: Mariusz Sabath <[email protected]> * Removed redundand doc sections Signed-off-by: Mariusz Sabath <[email protected]> --------- Signed-off-by: Mariusz Sabath <[email protected]> Co-authored-by: kfox1111 <[email protected]> Co-authored-by: Mohammed Abdi <[email protected]>
This commit is contained in:
Mariusz Sabath
co-authored by
kfox1111
Mohammed Abdi
kfox1111
Mohammed Abdi
parent
a9b04fd86c
commit
b6575c172d
@@ -1,8 +1,8 @@
|
|||||||
Installed {{ .Chart.Name }}…
|
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
|
spire-server entry show
|
||||||
|
|
||||||
{{- if eq (.Values.tornjak.enabled | toString) "true" }}
|
{{- if eq (.Values.tornjak.enabled | toString) "true" }}
|
||||||
|
|||||||
@@ -6,14 +6,15 @@ Your release is named: {{ .Release.Name }}
|
|||||||
Namespace: {{ include "tornjak-frontend.namespace" . }}
|
Namespace: {{ include "tornjak-frontend.namespace" . }}
|
||||||
|
|
||||||
Tornjak UI (Frontend)
|
Tornjak UI (Frontend)
|
||||||
image: {{ template "spire-lib.image" (dict "appVersion" $.Chart.AppVersion "image" .Values.image "global" .Values.global) }}
|
Image: {{ template "spire-lib.image" (dict "appVersion" $.Chart.AppVersion "image" .Values.image "global" .Values.global) }}
|
||||||
pull policy: {{ .Values.image.pullPolicy }}
|
Image pull policy: {{ .Values.image.pullPolicy }}
|
||||||
|
Ingress enabled: {{ .Values.ingress.enabled }}
|
||||||
Tornjak API (Backend): {{ include "tornjak-frontend.apiURL" . }}
|
Tornjak API (Backend): {{ include "tornjak-frontend.apiURL" . }}
|
||||||
SPIRE health check enabled: "{{ .Values.spireHealthCheck.enabled }}"
|
SPIRE health check enabled: {{ .Values.spireHealthCheck.enabled }}
|
||||||
User Managemenet enabled: "{{ .Values.auth.enabled }}"
|
User Management enabled: {{ .Values.auth.enabled }}
|
||||||
User Managemenet API: "{{ .Values.auth.serverURL }}"
|
{{- if .Values.auth.enabled }}
|
||||||
|
User Management API: "{{ .Values.auth.serverURL }}"
|
||||||
{{- if not .Values.auth.enabled }}
|
{{- else }}
|
||||||
### WARNING ###
|
### WARNING ###
|
||||||
|
|
||||||
Tornjak is configured to run without authentication and is therefore NOT suitable to run in production environments.
|
Tornjak is configured to run without authentication and is therefore NOT suitable to run in production environments.
|
||||||
|
|||||||
+68
-31
@@ -1,29 +1,41 @@
|
|||||||
# Recommended setup to deploy Tornjak
|
# 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
|
```shell
|
||||||
kubectl create namespace "spire-system"
|
export TORNJAK_API=http://localhost:10000
|
||||||
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
|
|
||||||
|
|
||||||
# deploy SPIRE with Tornjak enabled
|
helm upgrade --install -n spire-mgmt spire spire \
|
||||||
helm upgrade --install --namespace spire-server spire charts/spire \
|
--repo https://spiffe.github.io/helm-charts-hardened/ \
|
||||||
--values tests/integration/psat/values.yaml \
|
--set tornjak-frontend.apiServerURL=$TORNJAK_API \
|
||||||
--values examples/tornjak/values.yaml \
|
--values examples/tornjak/values.yaml \
|
||||||
|
--values your-values.yaml \
|
||||||
--render-subchart-notes
|
--render-subchart-notes
|
||||||
|
|
||||||
|
|
||||||
# test the Tornjak deployment
|
# test the Tornjak deployment
|
||||||
helm test spire -n spire-server
|
helm test spire -n spire-server
|
||||||
```
|
```
|
||||||
|
|
||||||
## Access Tornjak
|
Run following commands from your shell, to start port forwarding for Tornjak backend (APIs)
|
||||||
|
and Tornjak frontend (UI) services.
|
||||||
To access Tornjak you will have to use port-forwarding for the time being *(until we add authentication and ingress)*.
|
If you deployed in different namespace, your values might differ. Consult the install notes printed when running above `helm upgrade` command in that case.
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
Since `port-forward` is a blocking command, execute them in two different consoles:
|
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
|
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.
|
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
|
```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 \
|
--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
|
Obtain the OpenShift Apps Subdomain for Ingress and assign it to the `trustDomain`
|
||||||
[Openshift README](../openshift/README.md)
|
environment variable:
|
||||||
|
|
||||||
Then just add Openshift specific configuration to the above command:
|
|
||||||
|
|
||||||
```shell
|
```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,
|
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
|
```shell
|
||||||
--set spiffe-csi-driver.kubeletPath=/var/data/kubelet \
|
--values examples/openshift/values-ibm-cloud.yaml
|
||||||
--set spiffe-csi-driver.restrictedScc.enabled=true \
|
```
|
||||||
|
|
||||||
|
## 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"
|
||||||
```
|
```
|
||||||
|
|||||||
@@ -4,16 +4,18 @@ This example demonstrates Tornjak's capability to control access to the Frontend
|
|||||||
User Management via [Keycloak](https://www.keycloak.org/).
|
User Management via [Keycloak](https://www.keycloak.org/).
|
||||||
|
|
||||||
Tested on:
|
Tested on:
|
||||||
|
|
||||||
- Keycloak Application Version - 24.0.3
|
- Keycloak Application Version - 24.0.3
|
||||||
- Keycloak Chart Version - 21.0.3
|
- Keycloak Chart Version - 21.0.3
|
||||||
|
|
||||||
For more information regarding Tornjak User Management, please refer to the following documentation:
|
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)
|
- [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)
|
- [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)
|
- [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.
|
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
|
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)
|
## 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
|
```shell
|
||||||
# Create a namespace to deploy Keycloak and SPIRE-server
|
# If does not exist, create a namespace to deploy Keycloak
|
||||||
kubectl create namespace spire-server
|
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
|
```shell
|
||||||
# Deploy Keycloak as an authentication service
|
# Deploy most recent Keycloak instance 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
|
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
|
```shell
|
||||||
# Start an auth Service [Keycloak] (Terminal 3)
|
# Start an auth Service [Keycloak] in separate terminal
|
||||||
kubectl -n spire-server port-forward service/keycloak 8080:80
|
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
|
## 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`.
|
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://<your-keycloakServicename>.<keycloak-namespace>:<your-keycloak-portnumber>/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
|
The sample [examples/tornjak/values-auth.yaml](../values-auth.yaml) assumes local
|
||||||
# Install SPIRE CRDs
|
Keycloak deployment using port forwarding. When using Ingress, update the URLs accordingly.
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|
||||||
## Access Tornjak
|
## Access Tornjak
|
||||||
|
|
||||||
To access Tornjak use port-forwarding or check the ingress option below.
|
Follow the standard [steps for Accessing Tornjak](../README.md)
|
||||||
|
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|||||||
@@ -4,7 +4,6 @@ spire-server:
|
|||||||
|
|
||||||
tornjak-frontend:
|
tornjak-frontend:
|
||||||
enabled: true
|
enabled: true
|
||||||
apiServerURL: "http://localhost:10000"
|
|
||||||
service:
|
service:
|
||||||
type: ClusterIP
|
type: ClusterIP
|
||||||
port: 3000
|
port: 3000
|
||||||
|
|||||||
Reference in New Issue
Block a user