panxiao81/helm-charts-hardened
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update Tornjak deployment docs (#288)

Browse Source 
* 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
2024-05-09 04:26:17 -07:00
committed by GitHub
co-authored by kfox1111 Mohammed Abdi
parent a9b04fd86c
commit b6575c172d
5 changed files with 122 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files
examples/tornjak/README.md
+68 -31
View File
@@ -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"
```
examples/tornjak/keycloak/README.md
+44 -77
View File
@@ -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://<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
# 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)
examples/tornjak/values.yaml
-1
View File
@@ -4,7 +4,6 @@ spire-server:
tornjak-frontend:
enabled: true
apiServerURL: "http://localhost:10000"
service:
type: ClusterIP
port: 3000