Kubernetes (Helm)

Running auth-server for real, with more than one replica, rolling upgrades, and no single host to babysit by hand, calls for something more than docker compose up. The auth-server project ships a Helm chart for exactly that: deploying to a Kubernetes cluster, alongside whichever of MongoDB or PostgreSQL and Redis it needs, either bundled or pointed at instances you already run. See Docker Compose instead for local development or a small single-host deployment.

A chart is published to GitHub as oci://ghcr.io/rapidrest/charts/auth-server for every tagged release, versioned to match the release tag rather than the version checked into helm/Chart.yaml (CI overwrites it at package time). As of this writing no release has been tagged yet, check the packages page above for the current version once one exists.

Architecture

The chart deploys auth-server as a stateless Kubernetes Deployment, not a StatefulSet. Every replica is identical and runs behind a single Service, which is in turn exposed outside the cluster through a Gateway API Gateway/HTTPRoute rather than an Ingress. Each pod waits, via an init container, for its datastores to accept connections before starting.

      ------------           ---------------           -----------
     |  Gateway   |  --->   |   HTTPRoute   |  --->   |  Service  |
      ------------           ---------------           -----------
                                                              |
                     -----------------------------------------------------------
                     |                        |                                |
                ------------             ------------                    ------------
               |    Pod     |           |    Pod     |        ...       |    Pod     |
               | (replica)  |           | (replica)  |                  | (replica)  |
                ------------             ------------                    ------------
                     |                        |                                |
                     -----------------------------------------------------------
                                               |
                                -----------------------------------
                               |                                   |
                          ------------                       ------------
                         |  MongoDB   |                      |   Redis    |
                         |     or     |                      | (optional, |
                         | PostgreSQL |                      | standalone)|
                         | (optional, |                       ------------
                         | standalone)|
                          ------------

MongoDB, PostgreSQL, and Redis are each optional, standalone Bitnami subcharts, bundled by default (mongodb.create/postgresql.create/redis.create). Point the chart at datastores you already run instead by setting the corresponding create to false and providing a connection URL. auth-server only ever uses one primary datastore at a time; see PostgreSQL below for how the chart picks between MongoDB and PostgreSQL when both are left enabled.

Prerequisites

• Kubernetes 1.23+
• Helm 3.8.0+
• A Gateway API implementation with an nginx GatewayClass installed in the cluster (for example, NGINX Gateway Fabric). The chart deploys a Gateway/HTTPRoute, not an Ingress.
• PV provisioner support in the underlying infrastructure, since the bundled MongoDB or PostgreSQL persists data to a PVC by default
• cert-manager, if deploying with gateway.tls enabled (the default) against a public hostname. Skipped automatically for localhost or a .local hostname.

Dependencies

Dependency	Version	Description
@bitnami/mongodb	18.4.8	When MongoDB is desired.
@bitnami/postgresql	18.8.13	When PostgreSQL is desired.
@bitnami/redis	24.1.8	Required for cache, push, and sessions systems

Installing the Chart

helm install --create-namespace --namespace auth-server auth-server \
  oci://ghcr.io/rapidrest/charts/auth-server \
  --set host=auth.example.com

Add --version <x.y.z> to pin a specific release; omitted here, Helm installs whatever version was published most recently. host and --set overrides at install time cover most cases. See Parameters below for every configurable value.

Two-step install when provisioning your own datastores

When mongodb.create/postgresql.create/redis.create are left at their default, the chart reads the subcharts' generated credentials back out via a Helm lookup to build its own connection secrets. On a brand-new install, those subchart secrets don't exist yet at template-rendering time, so the API's pods will crash-loop immediately after install. Run helm upgrade once more, against the same chart reference you installed with, after the datastore pods are up, and the credentials will be picked up correctly. The chart's post-install notes cover this: run helm get notes auth-server -n auth-server to see them.

Uninstalling the Chart

helm uninstall auth-server --namespace auth-server

Configuration and installation details

General

host and environment drive most of the chart's other defaults: host sets the auth.audience/auth.issuer claims, the Gateway/HTTPRoute hostname, and the TLS certificate's domain, while environment sets NODE_ENV on the deployment. The JWT, cookie, and session secrets (auth.secret, cookies.secret, sessions.secret) are each randomly generated at install time if left unset, and preserved across upgrades via a Helm lookup against the previously generated Secret, so a helm upgrade never rotates them out from under running sessions.

Gateway

The chart attaches an HTTPRoute to a Gateway named by gateway.name/gateway.namespace. By default (api-gateway in the release's own namespace) it also creates that Gateway itself. Pointing gateway.name/gateway.namespace at a Gateway that already exists in another namespace skips creating a new one, letting multiple releases share a single Gateway. gateway.tls adds an HTTPS listener and requests a cert-manager certificate for host; gateway.hsts controls whether the Strict-Transport-Security header is left on the response, which is useful to disable for local or non-TLS testing.

Redis

Redis backs the cache, event bus, and log streaming, not primary data storage, so the bundled subchart runs without persistence (redis.master.persistence.enabled/redis.replica.persistence.enabled both default to false). Set redis.create to false and redis.url to point the deployment at a Redis instance you already run instead of the bundled one.

MongoDB

The application keeps its own data and its ACL data in two separate MongoDB databases (service.mongodb.mongo.name and service.mongodb.acl.name), which can point at the same server or different ones. As with Redis, set mongodb.create to false and mongodb.url (or the per-database service.mongodb.*.host/*.url overrides, if the ACL and application databases live on different servers) to use MongoDB instances you already run.

PostgreSQL

postgresql.create is the SQL-backed alternative to mongodb.create, off by default. The chart's datastore wiring checks mongodb.create first, so if you turn postgresql.create on you also need to turn mongodb.create off, otherwise the app is configured for MongoDB regardless of the PostgreSQL subchart also being deployed alongside it unused:

--set mongodb.create=false --set postgresql.create=true

Unlike MongoDB, PostgreSQL doesn't create a database the first time something connects to it, so only one database is auto-provisioned by the bundled subchart (postgresql.auth.database, rrst_auth by default) and used for the application data (service.postgresql.sql.name). The ACL datastore defaults to reusing the server's own built-in postgres database (service.postgresql.acl.name) rather than a dedicated one; provision a real database for it out-of-band and point service.postgresql.acl.name at it if you'd rather keep ACL data separate. As with MongoDB and Redis, set postgresql.create to false and postgresql.url (or the per-database service.postgresql.*.host/*.url overrides) to use a PostgreSQL instance you already run.

Service

service.image.registry/service.image.repository/service.image.tag select the container image; service.image.tag defaults to the chart's own appVersion field when left empty, which CI sets to match the release tag (the same one the chart itself is versioned and published under) at package time, so an unpinned install pulls the image matching whichever chart version you installed. service.resources and service.replicas are sized for a reference deployment, not production load, and should be tuned before real traffic. service.config and service.spec are escape hatches for anything the chart doesn't expose as its own parameter: service.config merges arbitrary key/value pairs into the service's environment configuration, and service.spec merges arbitrary fields into the pod spec (for example, nodeSelector or tolerations).

Parameters

Name	Description	Value
host	Public hostname the Gateway, HTTPRoute, and TLS certificate are issued for	localhost
environment	Sets NODE_ENV for the deployment	dev
auth.audience	JWT audience claim	'{{ .Values.host }}'
auth.issuer	JWT issuer claim	'api.{{ .Values.host }}'
auth.expiresIn	Access token lifetime	1 hour
auth.secret	JWT signing secret. Randomly generated at install time and preserved across upgrades	'{{ randAlphaNum 32 }}'
cookies.secret	Cookie signing secret. Randomly generated at install time and preserved across upgrades	'{{ randAlphaNum 32 }}'
sessions.secret	Session secret. Randomly generated at install time and preserved across upgrades	'{{ randAlphaNum 32 }}'
gateway.name	Name of the Gateway the HTTPRoute attaches to. The chart only creates this Gateway itself when the name and namespace are both left at their defaults; point it at an existing Gateway to share one across releases	api-gateway
gateway.namespace	Namespace of that Gateway	'{{ .Release.Namespace }}'
gateway.tls	Add an HTTPS listener and request a cert-manager certificate for host. Skipped automatically when host is localhost or ends in .local	true
gateway.hsts	Keep the Strict-Transport-Security response header. Set to false to strip it, for local or non-TLS testing	true
redis.create	Deploy a Redis instance via the Bitnami subchart	true
redis.url	Redis connection URL. Override when redis.create is false to point at an external Redis	redis://db-redis-master
redis.architecture	Redis architecture, passed through to the Bitnami subchart	standalone
redis.auth.enabled	Require a password on the bundled Redis	true
redis.fullnameOverride	Resource name prefix for the bundled Redis subchart	db-redis
redis.master.persistence.enabled	Enable persistence on the Redis master	false
redis.replica.persistence.enabled	Enable persistence on Redis replicas	false
redis.networkPolicy.enabled	Create a NetworkPolicy restricting access to Redis	true
redis.networkPolicy.allowExternal	Allow traffic from outside the cluster when networkPolicy.enabled is true	false
mongodb.create	Deploy a MongoDB instance via the Bitnami subchart	true
mongodb.url	MongoDB connection URL, used only when mongodb.create is false	""
mongodb.architecture	MongoDB architecture, passed through to the Bitnami subchart	standalone
mongodb.auth.enabled	Require credentials on the bundled MongoDB	true
mongodb.fullnameOverride	Resource name prefix for the bundled MongoDB subchart	mongodb
postgresql.create	Deploy a PostgreSQL instance via the Bitnami subchart, as an alternative to mongodb.create	false
postgresql.url	PostgreSQL connection URL, used only when postgresql.create is false	""
postgresql.architecture	PostgreSQL architecture, passed through to the Bitnami subchart	standalone
postgresql.fullnameOverride	Resource name prefix for the bundled PostgreSQL subchart	postgresql
postgresql.auth.enablePostgresUser	Require credentials on the bundled PostgreSQL	true
postgresql.auth.database	Name of the one database the bundled subchart auto-provisions on first start	rrst_auth
service.image.registry	Container image registry	ghcr.io
service.image.repository	Container image repository	rapidrest/auth-server
service.image.tag	Container image tag. Defaults to the chart's appVersion when empty	""
service.imagePullSecret	Name of an existing image pull secret	""
service.replicas	Number of replicas	1
service.resources.requests.cpu	CPU request	100m
service.resources.requests.memory	Memory request	256Mi
service.resources.limits.memory	Memory limit	512Mi
service.mongodb.acl.name	Database name for the ACL datastore	access_control_lists
service.mongodb.acl.host	Host override for the ACL datastore	""
service.mongodb.acl.url	Full connection URL override for the ACL datastore	""
service.mongodb.mongo.name	Database name for the application datastore	rrst_auth
service.mongodb.mongo.host	Host override for the application datastore	""
service.mongodb.mongo.url	Full connection URL override for the application datastore	""
service.postgresql.acl.name	Database name for the ACL datastore	postgres
service.postgresql.acl.host	Host override for the ACL datastore	""
service.postgresql.acl.url	Full connection URL override for the ACL datastore	""
service.postgresql.sql.name	Database name for the application datastore	rrst_auth
service.postgresql.sql.host	Host override for the application datastore	""
service.postgresql.sql.url	Full connection URL override for the application datastore	""
service.config	Arbitrary key/value pairs merged into the service's environment configuration	{logs: true, metrics: true, releaseNotes: true}
service.spec	Arbitrary key/value pairs merged into the pod spec, for settings such as nodeSelector or tolerations	{}

See also

• Configuration for the full auth:*/session config tree.
• Strategies → Security Features for what to double-check before exposing a deployment publicly.