EQTY LabDocs

Helm Deployment

Install the Guardian Platform Helm chart on a Kubernetes cluster and verify the rollout.

View as Markdown

Deploy the Guardian Platform to a Kubernetes cluster.

Overview

Run this after the earlier steps in Deployment Process.

Prerequisites

Before deploying, ensure the following are available:

  • Kubernetes 1.29+ cluster
  • Helm 3.20+ (installation guide)
  • kubectl configured to access the cluster
  • Persistent volume provisioner available in the cluster
  • Ingress, DNS, and TLS: NGINX ingress controller, DNS record, cert-manager, and an Issuer (Domain and TLS)
  • Identity provider configured, with its bootstrap chart or the manual setup
  • Completed values.yaml and secrets.yaml files from previous setup steps

Step 1: Set the Namespace

Create the guardian namespace if an earlier step hasn’t, and make it the default for kubectl:

bash
kubectl create namespace guardian   # skip if it exists
kubectl config set-context --current --namespace=guardian

Step 2: Deploy with Helm

Sign in to the chart registry, install the platform, and watch the rollout.

The commands below install from GitHub Container Registry (GHCR), which applies until your version has a verified Cloudsmith delivery. For a delivered stable version, add the Cloudsmith repository and install from it as Connected Install describes, then continue from Monitor Deployment.

Authenticate to GitHub Container Registry

bash
helm registry login ghcr.io

Enter GitHub username and personal access token when prompted.

Deploy the Platform

Replace <chart-version> with the guardian-platform chart version recorded in the release manifest for the platform version you are deploying.

bash
helm upgrade --install guardian-platform \
  oci://ghcr.io/eqtylab/charts/guardian-platform \
  --version <chart-version> \
  --namespace guardian \
  --create-namespace \
  --values values.yaml \
  --values secrets.yaml \
  --wait \
  --timeout 10m

Always pass --version. Without it Helm installs whichever chart version is newest in the registry, which may not be the version your values, images, and release manifest were validated against.

Note: For a release installed with this command, run the same command to upgrade after changing values or deploying a new version, updating --version to the target release. A release installed before 1.3 upgrades differently; see “Upgrading from 1.2.x” in the Guardian Platform v1.3.0 release notes.

Monitor Deployment

bash
kubectl get pods -n guardian -w
helm status guardian-platform -n guardian

Verify Deployment

Once the release is installed, check its pods, services, TLS certificates, and the organization setup.

Check Pods and Services

bash
kubectl get pods -n guardian
kubectl get svc -n guardian
kubectl get ingress -n guardian

All Deployment and StatefulSet pods should show Running status and Ready state, one line per replica. Pods from Jobs, such as the identity provider post-install setup, show Completed. With the default replica counts:

text
NAME                                                READY   STATUS    AGE
guardian-platform-auth-service-xxxxx-xxxxx        1/1     Running   2m
guardian-platform-auth-service-xxxxx-xxxxx        1/1     Running   2m
guardian-platform-eqty-pdfgen-xxxxx-xxxxx         1/1     Running   2m
guardian-platform-eqty-pdfgen-xxxxx-xxxxx         1/1     Running   2m
guardian-platform-governance-service-xxxxx-xxxxx  1/1     Running   2m
guardian-platform-governance-service-xxxxx-xxxxx  1/1     Running   2m
guardian-platform-guardian-xxxxx-xxxxx   1/1     Running   2m
guardian-platform-integrity-service-xxxxx-xxxxx   1/1     Running   2m
guardian-platform-integrity-service-xxxxx-xxxxx   1/1     Running   2m
guardian-platform-postgresql-0                    1/1     Running   3m

Verify TLS Certificates

bash
kubectl get certificates -n guardian

Each certificate should show READY True. If one does not, see Domain and TLS.

Check the Organization Setup

With createOrganization: true under your provider’s key (auth0, entra, or keycloak), a post-install hook creates the organization and, with createPlatformAdmin: true, makes the platform admin its owner. It runs on every install and upgrade. Check that it completed, using auth0-org-setup, entra-org-setup, or keycloak-org-setup for your provider:

bash
kubectl get jobs -n guardian -l app.kubernetes.io/component=keycloak-org-setup
kubectl logs -n guardian -l app.kubernetes.io/component=keycloak-org-setup

The Job is deleted five minutes after it finishes, so no output after that is expected.

Then sign in to Guardian as the platform admin and open Members from the profile menu (Member Management). The admin should be listed as an Organization Owner.

To check from the command line instead, call Auth Service’s user roles endpoint with the admin’s access token from the signed-in Studio session:

bash
curl -H "Authorization: Bearer <admin-access-token>" \
  https://<domain>/authService/api/v1/rbac/user/roles

The roles list should include organization_owner for the organization.

To re-run the setup outside a Helm upgrade, for example after the Job failed, use the deployment repository’s script for your provider. The scripts run psql in the bundled PostgreSQL pod, so with an external database run helm upgrade instead:

bash
./scripts/auth0/post-install-auth0-setup.sh -n guardian -d <auth0-domain> -e <admin-email>
./scripts/entra/post-install-entra-setup.sh -n guardian -e <admin-email>
./scripts/keycloak/post-install-keycloak-setup.sh -n guardian -k https://<domain>/keycloak -e <admin-email>

Run a script with --help for its other options, such as the organization name (-r, the realm, for Keycloak).

Troubleshooting

If pods fail to start, check the logs:

bash
kubectl get pods -n guardian
kubectl logs <pod-name> -n guardian
kubectl describe pod <pod-name> -n guardian

Common issues:

  • ImagePullBackOff: Check the image pull secret’s registry and credentials, and that values.yaml leaves image tags unset
  • CrashLoopBackOff: Check pod logs for application errors
  • Pending PVCs: Verify persistent volume provisioner is available
  • Database connection errors: Verify database credentials in secrets.yaml, and that the bundled PostgreSQL pod is running

To inspect the pull secret’s registry and username, or the database pod:

bash
kubectl get secret platform-image-pull-secret -n guardian \
  -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d
kubectl get pod guardian-platform-postgresql-0 -n guardian
kubectl logs guardian-platform-postgresql-0 -n guardian

Access the Platform

Open Guardian at the configured domain. It redirects to the identity provider; sign in as the platform admin. With the Auth0 or Keycloak bootstrap chart, the initial password is in the platform-admin secret.

Uninstalling

To completely remove the platform:

bash
# Uninstall the Helm release
helm uninstall guardian-platform -n guardian

# Delete the namespace, including the bundled PostgreSQL volume
kubectl delete namespace guardian

A release installed before 1.3 is governance-platform in the governance namespace; use those names to remove it.

Warning: helm uninstall keeps the bundled PostgreSQL persistent volume claim; deleting the namespace deletes it and all data stored in Kubernetes. External resources (databases, buckets, keys, identity provider applications) must be deleted separately.

Next Steps

  • Review the Chart Values documentation for customization options
  • Set up monitoring and alerting
  • Configure backups for the PostgreSQL database
  • Review security best practices for your deployment

Official Documentation