Install Lamassu with Helm

Use the Helm workflow when you need explicit control over identity, databases, messaging, certificates, storage and upgrades. For an evaluation environment where the script can make those choices for you, use Fastlane.

Before you begin

Prepare the platform services that are deliberately outside the Lamassu chart:

• a Kubernetes 1.24+ cluster and Helm 3.2+
• a reachable PostgreSQL server and a role allowed to create databases and schemas
• a reachable RabbitMQ broker and credentials
• an OIDC provider, normally Keycloak, with a realm/tenant and client for Lamassu
• Envoy Gateway 1.8+ and a GatewayClass
• cert-manager 1.14+; for trusted TLS, either a trusted issuer or a Kubernetes TLS Secret
• a StorageClass and an external traffic design

The chart defaults to a GatewayClass named eg. Change gateway.className if your platform team uses another name.

The chart has no Helm dependencies that install PostgreSQL, RabbitMQ, an OIDC provider, Envoy Gateway or cert-manager.

1. Install the Gateway prerequisites

Install or upgrade the Envoy Gateway CRDs before its controller. The commands below match the version used by the Lamassu Helm repository:

export ENVOY_GATEWAY_VERSION=v1.8.0

helm template eg-crds oci://docker.io/envoyproxy/gateway-crds-helm \
  --version "$ENVOY_GATEWAY_VERSION" \
  --set crds.gatewayAPI.enabled=true \
  --set crds.gatewayAPI.channel=experimental \
  --set crds.envoyGateway.enabled=true \
  | kubectl apply --server-side --force-conflicts -f -

helm upgrade --install eg oci://docker.io/envoyproxy/gateway-helm \
  --version "$ENVOY_GATEWAY_VERSION" \
  --namespace envoy-gateway-system \
  --create-namespace

Create the default GatewayClass if it does not already exist. Save this manifest as gateway-class.yaml:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: eg
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller

kubectl apply -f gateway-class.yaml
kubectl rollout status deployment/envoy-gateway -n envoy-gateway-system

Install cert-manager separately before Lamassu. The current chart renders its self-signed issuer and CA certificate resources even when tls.type: external makes the Gateway use an existing TLS Secret. Selecting external TLS therefore does not remove the cert-manager prerequisite.

2. Create a values file

Start with the chart defaults and override the environment-specific values. This example assumes PostgreSQL, RabbitMQ and Keycloak are reachable through Kubernetes DNS, and exposes Keycloak at /auth through the shared Lamassu Gateway:

postgres:
  hostname: postgresql
  port: 5432
  username: lamassu
  password: change-me

amqp:
  hostname: rabbitmq
  port: 5672
  username: lamassu
  password: change-me
  tls: false

tls:
  type: certManager
  certManagerOptions:
    clusterIssuer: production-issuer
    certSpec:
      commonName: pki.example.com
      hostnames:
        - pki.example.com

gateway:
  className: eg
  ports:
    http: 80
    https: 443
  extraRouting:
    - name: auth
      path: /auth
      target:
        host: auth-keycloak
        port: 80

auth:
  oidc:
    frontend:
      clientId: frontend
      authority: https://pki.example.com/auth/realms/lamassu
    apiGateway:
      jwks:
        - name: oidc-authn
          uri: http://auth-keycloak.lamassu.svc.cluster.local/auth/realms/lamassu/protocol/openid-connect/certs

services:
  ca:
    domains:
      - pki.example.com
  authz:
    jwkUrl: http://auth-keycloak.lamassu.svc.cluster.local/auth/realms/lamassu/protocol/openid-connect/certs
    bootstrap:
      - principal_id: "oidc:pki-admin"
        principal_name: "PKI Admin"
        principal_type: "oidc"
        policy_ids:
          - "lamassu.a6811b60-5f89-4ce7-badb-78ea234794d3"
        auth_config:
          claims:
            - claim: realm_access.roles
              operator: contains
              value: pki-admin

Do not add gateway.addresses by default. Leave address assignment to the load-balancer implementation unless your network design requires a specific Kubernetes-side VIP. The public IP of an upstream NAT gateway or reverse proxy does not belong in this value.

If Keycloak is external and already has its own reachable URL, point the OIDC settings at it and omit the /auth entry from gateway.extraRouting.

TLS with an existing Secret

Create a Secret containing tls.crt and tls.key, then reference it:

tls:
  type: external
  externalOptions:
    secretName: lamassu-downstream-tls

Provision the first administrator

There is no implicit superuser. Create the role or group expected by services.authz.bootstrap in the OIDC provider and assign it to at least one administrator before exposing Lamassu.

The pre-install and pre-upgrade job applies the bootstrap idempotently: existing principals are preserved and missing grants are added.

See Access control for the principal and policy model.

3. Install Lamassu

helm repo add lamassu https://lamassuiot.github.io/lamassu-helm
helm repo update

helm upgrade --install lamassu lamassu/lamassu \
  --namespace lamassu \
  --create-namespace \
  --values values.yaml \
  --wait

To install a local checkout instead:

helm upgrade --install lamassu ./charts/lamassu \
  --namespace lamassu \
  --create-namespace \
  --values values.yaml \
  --wait

4. Verify the deployment

kubectl get pods -n lamassu
kubectl get gateway,httproute -n lamassu
kubectl get service -A
helm test lamassu -n lamassu --logs

The Gateway should report PROGRAMMED=True. If it is programmed but has no usable address, continue with Expose the Gateway.

The Helm test checks the CA, DMS Manager, Device Manager and VA health endpoints and verifies the UI response.

Production decisions

Before going live, review:

• backup and recovery for PostgreSQL and persistent volumes
• a production KMS engine; the default filesystem engine is not an HA design
• shared VA storage before increasing VA replicas
• managed OIDC roles and removal of evaluation credentials
• a trusted TLS issuer or externally managed certificate
• resource requests, replicas, autoscaling, disruption budgets and placement
• SMTP, observability and alert delivery
• the migrationfollow Upgrade the Helm chart and the version notes in charts/lamassu/CHANGELOG/ before every upgrade

The complete values reference is maintained in charts/lamassu/VALUES.md in the Helm repository.