Install with Helm
Prepare dependencies, configure the Lamassu chart and verify a controlled Kubernetes deployment.
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+ (only for the default
tls.type: certManagermode); 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.
What Helm does with PostgreSQL
You provide the PostgreSQL server. The chart's pre-install job connects with the supplied credentials, creates the required pki, authz and wfx databases and service schemas, runs migrations, and applies services.authz.bootstrap.
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-namespaceCreate 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-controllerkubectl apply -f gateway-class.yaml
kubectl rollout status deployment/envoy-gateway -n envoy-gateway-systemInstall cert-manager separately before Lamassu, but only for the default tls.type: certManager mode. In that mode the chart renders its self-signed Issuer and CA Certificate resources regardless of whether tls.certManagerOptions.clusterIssuer is set, so cert-manager stays a prerequisite. With tls.type: external, the chart renders no cert-manager resources and the Gateway terminates TLS with an existing Secret you provide instead.
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
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-adminDo 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.
If your values file still carries the legacy gateway JWT validation settings — auth.oidc.apiGateway.jwks, auth.authorization.rolesClaim or auth.authorization.roles.admin — remove them. The migration guide charts/lamassu/CHANGELOG/3.8.0->4.0.0.md documents their removal with no compatibility aliases, and values.schema.json rejects the leftover blocks instead of silently ignoring them. The replacements are services.authz.jwkUrl and services.authz.bootstrap, already shown in the example above.
TLS with an existing Secret
Create a Secret containing tls.crt and tls.key, then reference it. The Secret must already exist before installing: in external mode the chart renders no cert-manager resources and never creates this Secret.
tls:
type: external
externalOptions:
secretName: provided-tlsAMQP TLS (AMQPS)
amqp.tls: true selects AMQPS in every event-bus configuration block. The default port stays 5672 and does not change automatically when TLS is enabled, so set amqp.port to the broker's TLS listener, commonly 5671.
With no CA Secret configured, the event-bus clients use the system-trusted CAs. To trust a private CA, create a Secret in the release namespace containing the CA certificate in PEM format and set amqp.ca.secretName (and amqp.ca.certificateKey if the data key is not ca.crt).
For brokers that require mutual TLS, create a Secret containing the client certificate and private key and set amqp.client.secretName (with amqp.client.certificateKey and amqp.client.privateKeyKey if the data keys are not tls.crt and tls.key).
amqp:
tls: true
port: 5671
ca:
secretName: rabbitmq-ca
client:
secretName: lamassu-amqp-clientThe chart mounts configured Secrets read-only into every AMQP-consuming workload: the CA certificate under /etc/lamassu/amqp/ca and the client certificate and key under /etc/lamassu/amqp/client. The mounted file names are always ca.crt, tls.crt and tls.key — the certificateKey and privateKeyKey values rename only the Secret data keys, never the on-disk paths. The client private key is mounted with restrictive permissions (defaultMode: 0440; the CA volume uses 0444), which works because the chart adds fsGroup to the pod security context when amqp.client.secretName is set — it uses the container runAsGroup (default 65532) when fsGroup is not already set.
Both Secret options require amqp.tls: true: values.schema.json rejects a non-empty secretName when tls is false, rejects unknown keys and rejects data-key names outside ^[A-Za-z0-9._-]+$. The referenced Secret must exist in the release namespace or the consuming pods fail to start.
The AMQP client loads certificates at startup, so restart the consuming pods after updating either Secret. Changing any amqp value rolls the consuming pods through the checksum/config annotation, but a change to Secret content alone does not trigger a rollout.
Set the AMQP port before upgrading
Per the migration guide charts/lamassu/CHANGELOG/3.8.0->4.0.0.md: in 3.8.0 amqp.tls was not applied and event-bus clients used plaintext AMQP; from 4.0.0, amqp.tls: true switches them to AMQPS. Set amqp.port to the broker TLS listener before upgrading, or set amqp.tls: false to keep plaintext AMQP. amqp.tls: false sends the broker credentials and all event-bus traffic in cleartext.
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.
Validate access before exposing the platform
Test both an authorized identity and a denied identity. If no token matches an active bootstrap principal, nobody can administer the PKI.
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 \
--waitTo install a local checkout instead:
helm upgrade --install lamassu ./charts/lamassu \
--namespace lamassu \
--create-namespace \
--values values.yaml \
--wait4. Verify the deployment
kubectl get pods -n lamassu
kubectl get gateway,httproute -n lamassu
kubectl get service -A
helm test lamassu -n lamassu --logsThe 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.
Upgrading Lamassu
Version-specific upgrade steps live in charts/lamassu/CHANGELOG/ in the Helm repository. The chart also ships an optional pre-upgrade Job that migrates existing CA private keys into the KMS engine configured for the release. It is off by default (migrations.caToKms.enabled: false) and is only needed when upgrading from a version prior to 3.7.0.
While the flag is enabled, every helm upgrade creates the <chart fullname>-ca-to-kms-migration Job (lamassu-ca-to-kms-migration for release lamassu); a fresh install does not create it. Its hook weight is -10, so it runs before the other pre-upgrade hooks: the authorization bootstrap configuration (weight -4) and the database-migration Job (weight -3).
The Job consumes the same KMS service configuration the chart renders into the KMS ConfigMap, including the engines from services.kms.cryptoEngines, and runs the migration tool defined in migrations.caToKms.image. It mounts that configuration read-only at /etc/lamassuiot/config.yml from the ConfigMap key config, so configure the destination engine in your values before the upgrade that performs the migration.
The Job resolves its configuration through a projected volume with two optional sources: the release-scoped <chart fullname>-kms-config (lamassu-kms-config for release lamassu, prod-lamassu-kms-config for release prod) and the legacy unscoped kms-config created by chart versions before release-scoped naming. The legacy configuration remains authoritative while it is still present, and the release-scoped one is used once the legacy one is gone. Both sources are optional, so a missing ConfigMap never leaves the upgrade pod in ContainerCreating.
Keep migrations.caToKms.enabled: true for the upgrade that performs the migration, then remove the flag from your values once the migration completes; it defaults to false.
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 version upgrade guides and migration notes in
charts/lamassu/CHANGELOG/before every upgrade, including the optional CA-to-KMS migration hook described above
The complete values reference is maintained in charts/lamassu/VALUES.md in the Helm repository.