Workspace Deployment Guide⚓︎
The Workspace Building Block provides a comprehensive solution for storing assets and offering services like cataloguing, data access, and visualisation to explore stored assets. Workspaces can cater to individual users or serve as collaborative spaces for groups or projects. This guide provides step-by-step instructions to deploy the Workspace BB in your Kubernetes cluster using Helm.
Introduction⚓︎
The Workspace Building Block provides a comprehensive environment where users can store, organise, and process data. It leverages Kubernetes and GitOps principles to create isolated and customisable workspaces for projects or individual users.
Components Overview⚓︎
The Workspace BB comprises the following key components:
-
Workspace Controller: Manages the provisioning and lifecycle of workspaces using Kubernetes Custom Resource Definitions (CRDs) and controllers.
-
Storage Controller: Provides an API for self-service management of storage buckets within the workspace.
-
Workspace Services: An extensible set of services that can be provisioned within the workspace, such as resource discovery, data access, and visualisation tools.
-
Workspace User Interface: A web-based interface for workspace lifecycle management and resource management.
Prerequisites⚓︎
Before deploying the Workspace Building Block, ensure you have the following:
Component | Requirement | Documentation Link |
---|---|---|
Kubernetes | Cluster (tested on v1.28) | Installation Guide |
Helm | Version 3.7 or newer | Installation Guide |
kubectl | Configured for cluster access | Installation Guide |
TLS Certificates | Managed via cert-manager or manually |
TLS Certificate Management Guide |
APISIX Ingress Controller | Properly installed | Installation Guide |
Container Registry | ECR or Harbor (for images) | Installation Guide |
Clone the Deployment Guide Repository:
Validate your environment:
Run the validation script to ensure all prerequisites are met:
Deployment Steps⚓︎
1. Run the Configuration Script⚓︎
Configuration Parameters
During the script execution, you will be prompted to provide:
INGRESS_HOST
: Base domain for ingress hosts.- Example:
example.com
- Example:
CLUSTER_ISSUER
: Cert-Manager ClusterIssuer for TLS certificates.- Example:
letsencrypt-http01-apisix
- Example:
HARBOR_ADMIN_PASSWORD
: Password for the Harbor admin user (This should have been automatically configured in the Container Registry guide).- S3 Credentials: Endpoint, region, access key, and secret key for your S3-compatible storage.
OIDC Configuration:
You will be prompted to provide whether you wish to enable OIDC authentication. If you choose to enable OIDC, ensure that you follow the steps in the OIDC Configuration section after deployment.
For instructions on how to set up IAM, you can follow the IAM Building Block guide.
2. Apply Kubernetes Secrets⚓︎
Run the script to create the necessary Kubernetes secrets.
Secrets Created in the workspace
namespace:
harbor-admin-password
minio-secret
3. Deploy Crossplane⚓︎
Crossplane is used for managing cloud resources within Kubernetes.
helm repo add crossplane https://charts.crossplane.io/stable
helm repo update crossplane
helm upgrade -i workspace-crossplane crossplane/crossplane \
--version v1.17.1 \
--namespace workspace \
--create-namespace
4. Deploy the Workspace API⚓︎
helm repo add eoepca-dev https://eoepca.github.io/helm-charts-dev
helm repo update eoepca-dev
helm upgrade -i workspace-api eoepca-dev/rm-workspace-api \
--version 2.0.0 \
--namespace workspace \
--values workspace-api/generated-values.yaml
Ingress is currently only available via APISIX routes, if you have not enabled OIDC, you will need to port-forward to access the API for now. If you have enabled OIDC, we will set up the APISIX route/ingress in later steps.
5. Deploy the Workspace Pipelines⚓︎
The Workspace Pipelines define the template that specifies the services provisioned within newly created Workspaces.
Some example pipelines are provided in the Workspace Git Repository under the path setup/eoepca-demo
.
These example pipelines are deployed here using kustomize
(kubectl -k
) with inline patching to apply the values configured via the configure-workspace.sh
script.
Apply the Pipelines:
NOTE that due to a race condition regarding the deployment of the Crossplane CRDs, it is necessary to run the apply command twice.
kubectl -n workspace apply -k workspace-pipelines 2>/dev/null
while ! kubectl get crd providerconfigs.kubernetes.crossplane.io >/dev/null 2>&1 || \
! kubectl get crd providerconfigs.minio.crossplane.io >/dev/null 2>&1; \
do sleep 1; done
kubectl -n workspace apply -k workspace-pipelines
6. Deploy the Workspace Admin Dashboard⚓︎
Install the Workspace Admin Dashboard:
helm repo add kubernetes-dashboard https://kubernetes.github.io/dashboard/
helm repo update kubernetes-dashboard
helm upgrade -i workspace-admin kubernetes-dashboard/kubernetes-dashboard \
--version 7.10.1 \
--namespace workspace \
--values workspace-admin/generated-values.yaml
There is currently no ingress set up for the Workspace Admin Dashboard. To access it, you can use port-forwarding.
7. Deploy the Workspace UI⚓︎
Install the Workspace UI:
helm repo add eoepca-dev https://eoepca.github.io/helm-charts-dev
helm repo update eoepca-dev
helm upgrade -i workspace-ui eoepca-dev/workspace-ui \
--version 0.0.3 \
--namespace workspace \
--values workspace-ui/generated-values.yaml
There is currently no ingress set up for the Workspace UI. To access it, you can use port-forwarding.
8. Optional: Enable OIDC with Keycloak⚓︎
If you do not wish to use OIDC/IAM right now, you can skip these steps and proceed directly to the Validation section.
If you do want to protect endpoints with IAM policies (i.e. require Keycloak tokens, limit access by groups/roles, etc.) and you enabled OIDC
in the configuration script then follow these steps. You will create a new client in Keycloak and optionally define resource-protection rules (e.g. restricting who can list jobs).
Before starting this please ensure that you have followed our IAM Deployment Guide and have a Keycloak instance running.
8.1 Create a Keycloak Client⚓︎
Use the create-client.sh
script in the /scripts/utils/
directory. This script prompts you for basic details and automatically creates a Keycloak client in your chosen realm:
When prompted:
- Keycloak Admin Username and Password: Enter the credentials of your Keycloak admin user (these are also in
~/.eoepca/state
if you have them set). - Keycloak base domain: e.g.
auth.example.com
-
Realm: Typically
eoepca
. -
Client ID: You should use
workspace
or what you set in the configuration script. - Client name and description: Provide any helpful text (e.g.,
Workspace Client
). - Client secret: Enter the Workspace Client Secret that was generated during the configuration script (check
~/.eoepca/state
). - Subdomain: Use
workspace-api
. - Additional Subdomains: Use
workspace-swagger,workspace-ui,workspace-admin
.
After it completes, you should see a JSON snippet confirming the newly created client.
8.2 Define Resource Protection⚓︎
Before protecting the resource, please ensure that you have a user in Keycloak other than the admin user. If you don’t have a user, you can create one using:
Protect the /workspaces/*
Endpoint⚓︎
- Use the
protect-resource.sh
:
When prompted:
- Client ID:
workspace
(the client you created in the previous step) - Username: e.g.
eoepcauser
(or any user you want to test with, if you don’t have a user, then create one in Keycloak) - Display Name:
eoepcauser
- Resource Type:
urn:workspace:resources:default
- Resource URI:
/workspaces/*
8.3 Create APISIX Route Ingress⚓︎
Apply the APISIX route ingress:
Validation and Usage⚓︎
After deploying the Workspace Building Block, you can validate and interact with it through a series of checks and tests described below.
Automated Validation⚓︎
To run automated checks:
If all checks pass, your Workspace BB deployment is functioning as expected.
Manual Validation Steps⚓︎
1. Check Kubernetes Resources⚓︎
List all resources in the workspace
namespace:
Confirm that all pods are Running
and no errors are reported.
2. Access the Workspace API Swagger Documentation⚓︎
You can view the Workspace API’s Swagger documentation at:
Replace ${INGRESS_HOST}
with your configured ingress host domain.
NOTE that the ingress integrates with IAM via OIDC, and so expects an authenticated user - for example
eoepcauser
created earlier.
Creating and Testing a Workspace⚓︎
1. Create a New Workspace⚓︎
Apply a sample Workspace
resource definition:
cat <<EOF | kubectl apply -f -
apiVersion: epca.eo/v1beta1
kind: Workspace
metadata:
name: ws-deploytest
namespace: workspace
spec:
subscription: bronze
EOF
Check that a new namespace was created:
2. Verify Storage Buckets⚓︎
Confirm that the workspace’s storage buckets (ws-deploytest
and ws-deploytest-stage
) were created:
3. Query the Workspace API⚓︎
Port-forward the Workspace API service:
Use of port forward allows to bypass the IAM to simplify the test
From another terminal window, call the Workspace API to get details for the newly created workspace:
Record the secret from the response for S3 access:
SECRET="$(curl -s http://localhost:8080/workspaces/ws-deploytest -H 'accept: application/json' | jq -r '.storage.credentials.secret')"
Now the port-forward
to the Workspace API service can be stopped - Ctrl-C
in original terminal window.
4. Interacting with S3 Buckets⚓︎
Use s3cmd
(configured via source ~/.eoepca/state
) to list and manipulate objects in the workspace’s S3 buckets.
List Buckets:
source ~/.eoepca/state
s3cmd ls \
--host minio.${INGRESS_HOST} \
--host-bucket minio.${INGRESS_HOST} \
--access_key ws-deploytest \
--secret_key $SECRET
Upload a Test File:
Ensure you are in the directory
scripts/workspace
for access to the test filevalidation.sh
.
source ~/.eoepca/state
s3cmd put validation.sh s3://ws-deploytest \
--host minio.${INGRESS_HOST} \
--host-bucket minio.${INGRESS_HOST} \
--access_key ws-deploytest \
--secret_key $SECRET
Check the Uploaded File:
source ~/.eoepca/state
s3cmd ls s3://ws-deploytest \
--host minio.${INGRESS_HOST} \
--host-bucket minio.${INGRESS_HOST} \
--access_key ws-deploytest \
--secret_key $SECRET
Delete the Test File:
source ~/.eoepca/state
s3cmd del s3://ws-deploytest/validation.sh \
--host minio.${INGRESS_HOST} \
--host-bucket minio.${INGRESS_HOST} \
--access_key ws-deploytest \
--secret_key $SECRET
5. Delete the Test Workspace⚓︎
To remove the test workspace:
Uninstallation⚓︎
To uninstall the Workspace Building Block and clean up associated resources:
helm uninstall workspace-ui -n workspace ; \
helm uninstall workspace-admin -n workspace ; \
kubectl -n workspace delete -f workspace-api/generated-ingress.yaml; \
helm uninstall workspace-api -n workspace ; \
helm uninstall workspace-crossplane -n workspace ; \
kubectl delete -k workspace-pipelines -n workspace ; \
kubectl delete namespace workspace