Kubernetes Installation Guide - Authlete Documentation

Prerequisites

A Kubernetes cluster (v1.24 or later) with access to your MySQL instance (v8.0+)
Minimum cluster resources: 4 vCPUs, 16GB RAM
Database credentials with read/write and delete access to the tables
Helm (version 3.17.0 or later)
Domain names for API, Console and IdP endpoints

Installation Steps

To access Helm charts and container images from the Authlete registry, follow these steps:

Setup Phase

1. Create an Organization

Log in to the Authlete Console.
Create an organization for your company.
Note down the Organization ID.

2. Request Access

Share the Organization ID and Organization Name with Authlete Support.
Authlete will authorize registry access for your organization.

3. Generate Organization Token

In the Authlete Console, generate a Token for your organization.
Keep the Organization ID and Token handy for authentication.

Preparation Phase

1. Create a Kubernetes Namespace

kubectl create ns authlete

2. Log in to the Helm Registry

Use the following command to log in:

helm registry login -u <ORG_ID> -p <TOKEN> artifacts.authlete.com

Replace <ORG_ID> and <TOKEN> with your actual values. Once logged in, you can pull Helm charts from the registry.

3. Pull Helm Chart

Authlete Helm chart is distributed using the OCI format. Use the following command to pull and extract the chart locally:

#Current stable version is 2.1.6
helm pull oci://artifacts.authlete.com/authlete-platform-chart --version 2.1.6 --untar
cd authlete-platform-chart

4. Image Registry Setup

You have two options for accessing Authlete container images: Option A: Direct Registry Access (Development/Evaluation) For development or evaluation environments, you can pull images directly from Authlete’s registry:

# Create a secret for registry authentication
kubectl create secret docker-registry authlete-registry \
-n authlete \
--docker-server=artifacts.authlete.com \
--docker-username=<ORG_ID> \
--docker-password=<TOKEN>

# Configure the default ServiceAccount to use this secret
kubectl patch serviceaccount default \
-n authlete \
-p '{"imagePullSecrets": [{"name": "authlete-registry"}]}'

Option B: Mirror Images (Production Recommended) For production environments, see the section below for instructions on mirroring images to your private registry.

5. Mirror Images

For improved reliability and control, we recommend customers mirror Authlete-provided container images to their own container registry. This avoids direct runtime dependency on Authlete’s registry, and ensures reproducible deployments.

Image	Description	Supported Version Tags
server	Core API server that handles OAuth 2.0 and OpenID Connect operations	3.0.33
server-db-schema	Database schema initialization tool for the API server	v3.0.33
idp	Identity Provider server for user authentication and management	1.0.28
idp-db-schema	Database schema initialization tool for the IdP server	v1.0.28
console	React based management console for platform configuration and monitoring	1.0.23
nginx	Nginx-based reverse proxy for handling TLS termination and routing	1.29.1
authlete-bootstrapper	Initialization service for the platform. Only used during first deployment.	1.2.1
token-migrator	A stateful background job that migrates OAuth tokens from Authlete v2.3 to v3.0	1.3
authlete-ops	A cronjob to run scheduled cleanup	0.1.0

Mirror using docker

# Authenticate to Authlete registry
docker login artifacts.authlete.com -u <ORG_ID> -p <TOKEN>

# Pull an image
docker pull artifacts.authlete.com/<image>:<tag>

# Tag and push to your own registry
docker tag artifacts.authlete.com/<image>:<tag> registry.mycompany.com/<image>:<tag>
docker push registry.mycompany.com/<image>:<tag>

Update your values.yaml to use the mirrored image paths before running the installation.

Mirror using crane

Alternatively, you can use crane if you want to directly push the images to your own registry.

# Set your target registry base
TARGET_REGISTRY="ghcr.io/your-org-name"

# Image copy commands
crane cp artifacts.authlete.com/server:3.0.33 $TARGET_REGISTRY/server:3.0.33
crane cp artifacts.authlete.com/server-db-schema:v3.0.33 $TARGET_REGISTRY/server-db-schema:v3.0.33
crane cp artifacts.authlete.com/idp:1.0.28 $TARGET_REGISTRY/idp:1.0.28
crane cp artifacts.authlete.com/idp-db-schema:v1.0.28 $TARGET_REGISTRY/idp-db-schema:v1.0.28
crane cp artifacts.authlete.com/console:1.0.23 $TARGET_REGISTRY/console:1.0.23
crane cp artifacts.authlete.com/nginx:1.29.1 $TARGET_REGISTRY/nginx:1.29.1
crane cp artifacts.authlete.com/authlete-bootstrapper:1.2.1 $TARGET_REGISTRY/authlete-bootstrapper:1.2.1
crane cp artifacts.authlete.com/token-migrator:1.3 $TARGET_REGISTRY/token-migrator:1.3
crane cp artifacts.authlete.com/authlete-ops:0.1.0 $TARGET_REGISTRY/authlete-ops:0.1.0

Note: The image tags listed here correspond to the latest Helm chart version. For older Helm chart versions, please refer to the image tags defined within that specific chart version.

Configuration Phase

1. Configure Values and Secrets

The default values.yaml is already bundled inside the chart. You can inspect or modify it for custom configurations.
Update the global.repo to your own registry.

global:
  id: "authlete-platform"
  repo: "registry.your-company.com"  # Required: Your container registry

Update the domains section with your domain names:

  # Required: These domains must be accessible from your users
  api: "api.your-domain.com"     # API server
  idp: "login.your-domain.com"   # IdP server
  console: "console.your-domain.com"  # Management console

Important: Domain names cannot be changed after the initial installation. If you need to change a domain name, you must reinitialize the database and reinstall Authlete from scratch. Choose your domain names carefully before proceeding.

2. Configure TLS Certificates

Get a TLS certificate for your domain (e.g. from your certificate authority or Let’s Encrypt), and create a Kubernetes secret of type kubernetes.io/tls in the authlete namespace before installation. The certificate should cover all domains used by the platform (e.g. api.example.com, login.example.com, console.example.com). You can use a wildcard or a SAN certificate.

kubectl create secret tls proxy-certs \
  --cert=./tls.crt \
  --key=./tls.key \
  -n authlete

Note: If you want to manage proxy-certs through External Secret Manager and skip this step, refer to the External Secret Manager section below

3. Enabling TLS connection to database and memory cache (Optional)

Application Configuration

TLS encryption can be enabled with simple configuration changes. Redis: To enable TLS encryption for the Redis connection, set tls: true in the cache connection configuration:

cache:
  api:
    enabled: true
    provider: standalone
    auth:
      enabled: false
    connection:
      tls: true
      host: redis
      port: 6379
  idp:
    enabled: true
    provider: standalone
    auth:
      enabled: false
    connection:
      tls: true
      host: redis
      port: 6379

Database: TLS connection to the database can be enabled with sslMode property:

database:
  idp:  # IdP Server Database
    name: idp
    type: mysql # mysql|postgres (defaults to mysql if unset)
    host: localhost
    connectionParams:
      allowPublicKeyRetrieval: true
      sslMode: verify-ca # Configure the sslMode here.
  api: # API Server Database
    name: authlete
    type: mysql # mysql|postgres (defaults to mysql if unset)
    host: localhost
    connectionParams:
      allowPublicKeyRetrieval: true
      sslMode: verify-ca # Configure the sslMode here.

Note: If the certificate presented by Redis or Database over TLS is issued by a private CA, you should create a custom bundle containing all certificates and load the bundle into the application. Please refer to the Private CA section for more details.

4. Private CA (Optional)

To use TLS with private CA certificate, a custom bundle containing all necessary certificates needs to be prepared outside of the Helm Chart. Next, we will create a ConfigMap that contains the bundles, which satisfies the following contract:

ConfigMap must be named custom-ca-bundle
It must contain at least 2 keys: ca-bundle.p12 and ca-bundle.crt

Creating CA bundle

We recommend extracting the public CA bundle as described in the trust-manager documentation. Below is an explanation of how to create a ConfigMap with the bundle.

Creating bundle with Trust Manager (Optional)

Trust Manager makes it easy to manage trust bundles in Kubernetes. For installation instructions please consult trust-manager’s official documentation. Once trust-manager is installed, you will need to create a single bundle object. The ConfigMap containting all necessary certificates will be then generated automatically. Here is an example Bundle from which trust-manager will assemble the final bundle. This Bundle’s manifest file name is assumed to be bundle-creation.yaml

apiVersion: trust.cert-manager.io/v1alpha1
kind: Bundle
metadata:
  name: custom-ca-bundle
spec:
  sources:
  - useDefaultCAs: true

  # A manually specified PEM-encoded cert, included directly into the bundle
  - inLine: |
      -----BEGIN CERTIFICATE-----
      MIIC5zCCAc+gAwIBAgIBADANBgkqhkiG9w0BAQsFADAVMRMwEQYDVQQDEwprdWJl
      ...
      ... contents of proxy's CA certificate ...
      -----END CERTIFICATE-----
  - inLine: |
      -----BEGIN CERTIFICATE-----
      ... contents of mysql's CA certificate ...
      -----END CERTIFICATE-----
  target:
    # All ConfigMaps will include a PEM-formatted bundle, here named "root-certs.pem"
    # In this case we also request binary formatted bundles in PKCS#12 format, here named "bundle.p12"
    configMap:
      key: "ca-bundle.crt"
    additionalFormats:
      pkcs12:
        key: "ca-bundle.p12"
    namespaceSelector:
      matchLabels:
        kubernetes.io/metadata.name: "authlete" # Deployment namespace

Finally, create the bundle with the following command:

kubectl create -f bundle-creation.yaml -n authlete

Note: Please note that if you’re using an official cert-manager-provided Debian trust package, you should check regularly to ensure the trust package is kept up to date.

Manual creation of bundle

The custom bundle can created in a few simple steps by using Docker commands.

Note: The tutorial below demonstrates sample code only. Customers are responsible for creating, storing, and updating bundles securely.

Create file named gen-bundles.sh

# Input/output directories
SRC="/certs"                                         # Location to place crt files
DST="/usr/local/share/ca-certificates/custom"        # Directory monitored by update-ca-certificates
OUT="/bundle"                                        # Output directory for the bundle

# Clean up output directory
rm -f $OUT/*

# Create output directories
mkdir -p "$DST"

# Install required packages (ca-certificates-java is necessary for generating the Java truststore)
apt-get -y update
apt-cache madison ca-certificates
DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends openssl default-jre-headless ca-certificates-java "ca-certificates=20230311+deb12u1"

# 1) Place additional certificates (*.pem / *.crt placed as .crt)
cp -v ${SRC}/* ${DST}/
# If you want to unify the extension so that .pem files are also treated as .crt, enable the following:
# for f in "$DST"/*.pem; do mv -v "$f" "${f%.pem}.crt"; done

# 2) Update system & Java truststore
update-ca-certificates -f

# 3) Output (PEM and PKCS12)
cp -v /etc/ssl/certs/ca-certificates.crt "$OUT/ca-bundle.crt"
keytool -importkeystore -srckeystore /etc/ssl/certs/java/cacerts -destkeystore $OUT/ca-bundle.p12 -deststoretype PKCS12 -srcstorepass changeit -deststorepass changeit

Prepare certificates to trust

Place the additional trusted certificates (one or more files) under the certs directory with .crt extension.

   ./certs/
     ├── sql-ca.crt
     ├── redis-ca.crt
     └── ...

Build the bundle

docker run --rm --user root -v "$PWD/certs:/certs:ro" -v "$PWD/out:/bundle" -v "$PWD/gen-bundles.sh:/usr/local/bin/gen-bundles.sh:ro" --entrypoint bash docker.io/library/debian:12-slim -c "sh /usr/local/bin/gen-bundles.sh"

After preparing ca-bundle.p12 and ca-bundle.crt files, you can create the kubernetes ConfigMap with the following command:

kubectl create cm custom-ca-bundle --from-file=ca-bundle.p12 --from-file=ca-bundle.crt

Note: The current debian base image used for the trust-manager’s bundle creation is docker.io/library/debian:12-slim and ca-certificates target version is at 20230311+deb12u1.6

Loading the custom bundles from the application

Now that the bundle is created and ready for use, we will need to configure one more property to make the bundles available for applications. Set .Values.global.tls.caBundle.enabled to true so that the bundle is mounted into the application pods.

global:
  tls:
    caBundle:
      enabled: true # Enable this
      type: ConfigMap
      name: custom-ca-bundle
      trustStore:
        password: "changeit"

Updating the bundle

If you created a new bundle and replaced the old bundle with it, you should restart IdP, Authlete Server and proxy pods(applications). On a restart, applications will load the updated bundle.

5. Configure Database Connection

The platform requires two databases: one for the API server and one for the IdP server. Configure the connection details in secret-values.yaml:

Note: For MySQL 8.0+, ensure your databases are configured with:

Character set: utf8mb4

Collation: utf8mb4_0900_ai_ci

If using PostgreSQL 16 or 17, you can use the standard configuration below:

Character set: UTF8

Collation: en_US.UTF8

A template secret-values.yaml file is also included in the chart archive. Modify secret-values.yaml with your database and Authlete admin credentials.

database:
  idp:  # IdP Server Database
    user: authlete      # Database user
    password: !raw ***** # User password
  api: # API Server Database
    user: authlete
    password: !raw ******

idp:
  auth:
    adminUser:
      email: "admin@authlete.com"
      password: !raw ******
  encryptionSecret: ********

Note: For AWS-EKS, you may use a DNS name for your MySQL Database with or without RDS-Proxy:

with RDS-Proxy: host: sample-db.proxy-stu901vwx234.us-east-1.rds.amazonaws.com

without RDS-Proxy: host: sample-db.cluster-stu901vwx234.us-east-1.rds.amazonaws.com

6. Configure Caching

Below are the caching configuration options currently supported by the platform.

Managed Cache Services

For production environments, you might prefer using managed cache services. The platform supports various managed services including:

Google Cloud Platform: Memorystore for Valkey
Amazon Web Services: ElastiCache for Redis or Serverless-Valkey
Azure: Azure Cache for Redis

7. Configure Maintenance Tasks

To keep the platform stable, avoid using unnecessary storage and ensure optimal performance, deployments must run regularly scheduled maintenance tasks. Review the following tasks and configure the required tasks.

Data Cleanup

As Authlete handles high volumes of OAuth 2.0 and OpenID Connect transactions, it accumulates transient records such as expired tokens, authorization codes, and other types of codes. To maximize API throughput and during runtime operations, Authlete does not immediately delete all expired records at the exact moment of expiration. Instead, they are marked as expired and are deleted as part of this task. If left unchecked, this data bloat can degrade database query performance and consume excessive storage. You should schedule the cleanup task to run regularly to perform the physical removal of all expired or delete records. To do so modify the following section in the values.yml file to provide the times at which the process should be run. The schedule property uses the format of schedules in kubernetes).

ops:
  cleanup:
    enabled: true
    schedule: "0 3 * * *"
    timezone: "Etc/UTC"

Important: For production environments, we recommend executing the cleanup process at least once a day during off-peak hours (e.g., 2:00 AM local time).

Use a dedicated API instance

The maintenance task uses Authlete API to perform the actual removal of data and it has been designed to have little to no impact on the instances used to perform the data removal. However, in some environments it is desired that the maintenance task do not use any of the API instances serving customer requests, in these cases you can enable the option deployApiSidecar: true which will deploy a specific copy of API to be used by the maintenance task. Keep in mind that this will require additional resources.

8. HSM configuration

Authlete currently supports Google Cloud HSM and AWS KMS. Refer to the configurations below if your setup relies on either one of those. For Google CloudHSM:

hsm:
  enabled: true
  provider: "google"
  google:
    projectId: "<replace-me>"         # required - e.g. "authlete-project-1"
    location: "<replace-me>"          # required - e.g. "us-west1-c"
  aws:
    region: ""

For AWS KMS:

hsm:
  enabled: true
  provider: "aws"
  google:
    projectId: ""
    location: ""
  aws:
    region: "<replace-me>"          # required - e.g. "ap-northeast-1"

9. External Secret Manager

When using External Secret Manager, make sure the secrets needed for the helm deployment are pre-configured and present on the cluster. Any absence of the following secrets will result in deployment/upgrade failures. Secrets needed are authlete-credentials and proxy-certs (only if you want ExternalSecretManager to manage proxy-certs)

Create a secret named `authlete-secret` in your External Secret Manager.

Without cache auth enabled:

{
  "database": {
    "idp": {
      "user": "root",
      "password": "<placeholder-idp-db-password>"
    },
    "api": {
      "user": "root",
      "password": "<placeholder-api-db-password>"
    }
  },
  "idp": {
    "adminUser": {
      "email": "admin@authlete.com",
      "password": "mypassword"
    },
    "encryptionSecret": "<placeholder-random-secret>"
  },
  "api": {
    "shutdownToken": "<placeholder-api-shutdown-token>"
  }
}

With cache auth enabled:

{
  "database": {
    "idp": {
      "user": "root",
      "password": "<placeholder-idp-db-password>"
    },
    "api": {
      "user": "root",
      "password": "<placeholder-api-db-password>"
    }
  },
  "idp": {
    "adminUser": {
      "email": "admin@authlete.com",
      "password": "mypassword"
    },
    "encryptionSecret": "<placeholder-random-secret>"
  },
  "api": {
    "shutdownToken": "<placeholder-api-shutdown-token>"
  },
  "cache": {
    "api": {
      "auth": {
        "user": "default",
        "password": "<placeholder-api-cache-password>"
      }
    },
    "idp": {
      "auth": {
        "user": "default",
        "password": "<placeholder-idp-cache-password>"
      }
    }
  }
}

kubectl apply -f - <<EOF
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: authlete-secret
  namespace: authlete
spec:
  refreshInterval: 30s
  secretStoreRef:
  # replace <ClusterSecretStore-name> with the correct ClusterSecretStore name in your cluster
    kind: ClusterSecretStore
    name: <ClusterSecretStore-name>
  target:
    name: authlete-credentials
    creationPolicy: Owner
  data:
  # IDP Database
  - secretKey: authlete-idp-db-user
    remoteRef:
      key: authlete-secret
      property: database.idp.user
  - secretKey: authlete-idp-db-password
    remoteRef:
      key: authlete-secret
      property: database.idp.password
  # API Database
  - secretKey: authlete-api-db-user
    remoteRef:
      key: authlete-secret
      property: database.api.user
  - secretKey: authlete-api-db-password
    remoteRef:
      key: authlete-secret
      property: database.api.password
  # API Graceful Shutdown token
  # Bearer token used by the API Pod's preStop lifecycle hook when calling
  # /api/lifecycle/shutdown. Generate any 32-character random alphanumeric
  # string and register it in the external secret manager.
  - secretKey: authlete-api-shutdown-token
    remoteRef:
      key: authlete-secret
      property: api.shutdownToken
  # IDP Admin
  - secretKey: authlete-idp-admin-email
    remoteRef:
      key: authlete-secret
      property: idp.adminUser.email
  - secretKey: authlete-idp-admin-password
    remoteRef:
      key: authlete-secret
      property: idp.adminUser.password
  - secretKey: authlete-idp-encryption-secret
    remoteRef:
      key: authlete-secret
      property: idp.encryptionSecret
  # Only needed if cache auth is enabled
  - secretKey: authlete-api-memcache-auth-user
    remoteRef:
      key: authlete-secret
      property: cache.api.auth.user
  - secretKey: authlete-api-memcache-auth-password
    remoteRef:
      key: authlete-secret
      property: cache.api.auth.password
  - secretKey: authlete-idp-memcache-auth-user
    remoteRef:
      key: authlete-secret
      property: cache.idp.auth.user
  - secretKey: authlete-idp-memcache-auth-password
    remoteRef:
      key: authlete-secret
      property: cache.idp.auth.password
EOF

If you want secret manager to manage your proxy certificates (proxy-certs) then create a secret by name: authlete-proxy-secret

# When storing certificates in the external secret manager, ensure the JSON keys are exactly:
- `tls.crt` for the certificate chain
- `tls.key` for the private key

# Example format:
{
  "tls.crt": "-----BEGIN CERTIFICATE-----\nMIIE...server-cert-data...==\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIF...intermediate-cert...==\n-----END CERTIFICATE-----",
  "tls.key": "-----BEGIN PRIVATE KEY-----\nMIIE...private-key-data...==\n-----END PRIVATE KEY-----"
}

# Moving TLS certificates to the External Secret Manager is optional.
# Else follow the deployment guide to configure TLS certificates
# (Installation Steps -> Configuration Phase -> Configure TLS Certificates)

kubectl apply -f - <<EOF
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: authlete-proxy-secret
  namespace: authlete
spec:
  refreshInterval: 30s
  secretStoreRef:
  # replace <ClusterSecretStore-name> with the correct ClusterSecretStore name in your cluster
    kind: ClusterSecretStore
    name: <ClusterSecretStore-name>
  target:
    name: proxy-certs
    creationPolicy: Owner
  data:
  # TLS Certificates
  - secretKey: tls.crt
    remoteRef:
      key: authlete-proxy-secret
      property: tls.crt
  - secretKey: tls.key
    remoteRef:
      key: authlete-proxy-secret
      property: tls.key
EOF

Note: To enable the externalSecrets feature in the Helm chart, refer to the values below inside values.yaml

global:
  externalSecrets:
    enabled: true  # Set to true to enable ESM | default 'false'

10. Configure Pod Affinity

To enable pod affinity, add or modify the following in your values.yaml:

lobal:
  apiAffinity: true

11. Configure Cleanup

To enable cleanup within your deployment, modify the following in your values.yaml:

ops:
  cleanup:
    enabled: false

By default, apiAffinity is set to false, meaning no pod affinity preferences are applied. Enabling pod affinity schedules proxy pods on the same node as API pods to reduce network latency, and improve performance between these tightly-coupled components.

12. Other configuration options

Proxy configuration

If your domain name is very long, you might hit a limit on the map_hash_max_size parameter. You can work around this problem by increasing the values of mapHashBucketSize and serverNamesHashBucketSize.

  configs:
    mapHashBucketSize: 128 # Change this
    serverNamesHashBucketSize: 128 # Change this

DB Schema update hooks

We introduced DB Schema update hooks to streamline the image version update. With these hooks, new changes in liquibase changesets are automatically applied to ensure database schema is on the same version as the application version. These hooks are idempotent and will not change the existing database schema as long as there is no change in schema between the upgraded version and the old version. These hooks are required to create the database schema during installation and when updating the application version. However, if you are not deploying a new application or expecting any schema changes, they can be disabled.

hooks:
  serviceAccount: ""
  idpDbSchemaUpgrade:
    enabled: true # You can disable this
  serverDbSchemaUpgrade:
    enabled: true # You can disable this

Note for Google Cloud Users: When using Memorystore for Valkey, we recommend setting up connectivity using Private Service Connect (PSC) with service connection policies. This is the only supported networking method for Memorystore for Valkey. For detailed setup instructions, refer to the Memorystore for Valkey networking documentation.

To use a managed cache service, update your values.yaml file with the following information:

cache:
  api:
    enabled: true
    provider: standalone
    auth:
      enabled: false
    connection:
      tls: false
      host: redis
      port: 6379
  idp:
    enabled: true
    provider: standalone
    auth:
      enabled: false
    connection:
      tls: false
      host: redis
      port: 6379

Note: If your managed cache service is configured in clustered mode, set the provider to cluster:

cache:
  api:
    provider: cluster
  idp:
    provider: cluster

Deployment Phase

1. Install Core Platform Components

Install the core platform components using Helm.

Without External Secret Manager:

helm install authlete-platform . -n authlete -f secret-values.yaml

With External Secret Manager:

helm install authlete-platform . -n authlete

Verify the installation:

# Check pod status
kubectl get pods -n authlete

Expected output:

NAME                       READY   STATUS    RESTARTS   AGE
api-6b78f87847-xxxxx       2/2     Running   0          2m
proxy-6c99bdc94b-xxxxx     1/1     Running   0          2m

Note: Initial deployment may take 5 minutes while images are pulled and databases are initialized.

2. Install Optional Components

You may also install the following optional components based on your requirements:

Management Console: Primary interface for Authlete platform configuration
IdP Server: OIDC compliant identity provider for user authentication and management

Without External Secret Manager:

helm upgrade authlete-platform . -n authlete -f secret-values.yaml

With External Secret Manager:

helm upgrade authlete-platform . -n authlete

Verify the optional components:

# Check new pod status
kubectl get pods -n authlete

Expected output:

NAME                       READY   STATUS    RESTARTS   AGE
console-6b78f87847-xxxxx   1/1     Running   0          2m
idp-6c99bdc94b-xxxxx       2/2     Running   0          2m

3. Configure Load Balancer

The final step is to set up a load balancer service to expose your Authlete deployment.

First, reserve a static external IP address in your cloud provider.

Note: The following commands are GCP-specific. For other cloud providers (AWS, Azure, etc.), please refer to your cloud provider’s documentation for reserving a static IP address. You must reserve a regional static external IP address in GCP. This is required because GKE LoadBalancer services only support IPs allocated in the same region as the cluster.

# GCP-specific commands
# Reserve a static IP address
gcloud compute addresses create authlete-ip --region=us-central1

# Get the reserved IP address
gcloud compute addresses describe authlete-ip --region=us-central1

Using the reserved IP, Create a load balancer service named proxy-lb-service.yaml.

Below is an example file for GKE deployment:

apiVersion: v1
kind: Service
metadata:
  labels:
    app: proxy
  name: proxy-lb
spec:
  externalTrafficPolicy: Local
  ports:
  - name: https
    port: 443
    protocol: TCP
    targetPort: 8443
  selector:
    app: proxy
  sessionAffinity: None
  type: LoadBalancer
  loadBalancerIP: #external_static_ip  # Replace with your reserved static IP

Below is an example file for AWS-EKS deployment:

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-eip-allocations: eipalloc-xxxxxxxxxxxxxxxxx  # Replace with your EIP allocation ID
    service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
    service.beta.kubernetes.io/aws-load-balancer-subnets: subnet-xxxxxxxxx  # Replace with your subnet ID
    service.beta.kubernetes.io/aws-load-balancer-type: external
    service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip
  labels:
    app: proxy
  name: proxy-lb
spec:
  externalTrafficPolicy: Local
  ports:
  - name: https
    port: 443
    protocol: TCP
    targetPort: 8443
  selector:
    app: proxy
  sessionAffinity: None
  type: LoadBalancer

Apply the load balancer configuration:

kubectl apply -f proxy-lb-service.yaml -n authlete

Verify the load balancer is properly configured:

kubectl get service proxy-lb -n authlete

You should see an output similar to the following:

NAME       TYPE           CLUSTER-IP      EXTERNAL-IP          PORT(S)         AGE
proxy-lb   LoadBalancer   10.x.x.x        YOUR_STATIC_IP      443:32xxx/TCP   1m

Once EXTERNAL-IP shows your static IP (this operation may take a few minutes), your Authlete deployment is accessible via HTTPS on that IP address.

4. Map Domain to Load Balancer

Create DNS records for all three domains pointing to your load balancer IP:

# API Server
api.your-domain.com.     IN  A     YOUR_STATIC_IP

# IdP Server
login.your-domain.com.   IN  A     YOUR_STATIC_IP

# Management Console
console.your-domain.com. IN  A     YOUR_STATIC_IP

Verify the DNS configuration:

# Test DNS configuration
dig +short api.your-domain.com
dig +short login.your-domain.com
dig +short console.your-domain.com

# Test HTTPS endpoints
curl -I https://api.your-domain.com/api/info

If all domains resolve to your load balancer IP and the endpoints are accessible, your Authlete deployment is ready for use. You can now access the Management Console:

Navigate to https://console.your-domain.com
Log in using the admin credentials specified in your secret-values.yaml
Begin configuring your Authlete services

Note: If you cannot access the console, verify the following:

DNS records have fully propagated
Load balancer health checks are passing
TLS certificate is valid for all domains

Migration Phase (Optional)

If you are performing a migration from a 2.3 environment to a 3.0 environment you might need to enable the Token Migrator which is responsible to perform token migration between the two environments.

1. Create token migrator client

In order to ensure that the token migrator has access to the 3.0 environment, you need to create a service and a client in the target 3.0 environment. The service and the client you create will be used by the token migrator at startup to confirm it still has access to the environment. To create and configure the client, follow these steps:

Navigate to https://console.your-domain.com
Log in using your admin credentials
Create a new service with the Client credentials grant enabled. Take note of the Service ID to be used later
Create a service access token with permission to use the service. Take note of the token to be used later
Create a client that will be used exclusively by the token migrator service with the following characteristics:
- Client ID Alias set to: migration-service@system.authlete.com
- Client Authentication Method must be set to CLIENT_SECRET_POST
- Supported Grant Types must include CLIENT_CREDENTIALS
Take a note of the Client Secret for the newly created client
In the secret-values.yaml file included in the chart archive modify the tokenmigrator section to specify the information of the newly create client

tokenmigrator:
  clientSecret: ""            # Client secret
  serviceApiKey: ""           # Authlete v3.0 Service ID
  serviceToken: ""            # Authlete v3.0 service access token

2. Configure Databases

The token migrator requires to connect to the 2.3 and 3.0 databases. The information of the 3.0 database is already available in the helm chart but you will need to provide the information to connect to the 2.3 database.

In the values.yaml file configure tokenmigrator.sourceDatabase.host to point to the pre-existing Authlete 2.3 Database. If your 2.3 database requires TLS follow the guidance in section Enabling TLS Connection to Database and Memory Cache to update the tokenmigrator.sourceDatabase.connectionParams property.
In the secret-values.yaml file included in the chart archive modify the tokenmigrator.database section to specify the credentials to be used to connect to the 2.3 database.

tokenmigrator:
  database:
    user: root                # Source (v2.3) database username
    password: !raw example**  # Source (v2.3) database password

3. Configure External Secrets (Optional)

If you are using an External Secret Manager you need to add the client information and the database credentials that the token migrator will use to your external secret. To do so, add the token migrator properties using the following snippet as an example:

{
  "database": {
    "idp": {
      "user": "root",
      "password": "<placeholder-idp-db-password>"
    },
    "api": {
      "user": "root",
      "password": "<placeholder-api-db-password>"
    }
  },
  "idp": {
    "adminUser": {
      "email": "admin@authlete.com",
      "password": "mypassword"
    },
    "encryptionSecret": "<placeholder-random-secret>"
  },
  "tokenmigrator": {
    "datasource-username": "<placeholder-source-database-user>",
    "datasource-password": "<placeholder-source-database-password>",
    "client-secret": "<placeholder-client-secret>",
    "service-api-key": "<placeholder-service-id>",
    "service-token": "<placeholder-service-token>"
  }
}

And then add the following to the external secret resource in kubernetes

kubectl apply -f - <<EOF
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: authlete-secret
  namespace: authlete
spec:
  refreshInterval: 30s
  secretStoreRef:
  # replace <ClusterSecretStore-name> with the correct ClusterSecretStore name in your cluster
    kind: ClusterSecretStore
    name: <ClusterSecretStore-name>
  target:
    name: authlete-credentials
    creationPolicy: Owner
  data:
  # IDP Database
  - secretKey: authlete-idp-db-user
    remoteRef:
      key: authlete-secret
      property: database.idp.user
  - secretKey: authlete-idp-db-password
    remoteRef:
      key: authlete-secret
      property: database.idp.password
  # API Database
  - secretKey: authlete-api-db-user
    remoteRef:
      key: authlete-secret
      property: database.api.user
  - secretKey: authlete-api-db-password
    remoteRef:
      key: authlete-secret
      property: database.api.password
  # IDP Admin
  - secretKey: authlete-idp-admin-email
    remoteRef:
      key: authlete-secret
      property: idp.adminUser.email
  - secretKey: authlete-idp-admin-password
    remoteRef:
      key: authlete-secret
      property: idp.adminUser.password
  - secretKey: authlete-idp-encryption-secret
    remoteRef:
      key: authlete-secret
      property: idp.encryptionSecret
  # Token Migrator secrets
  - secretKey: authlete-client-secret
    remoteRef:
      key: authlete-secret
      property: tokenmigrator.client-secret
  - secretKey: authlete-service-api-key
    remoteRef:
      key: authlete-secret
      property: tokenmigrator.service-api-key
  - secretKey: authlete-service-token
    remoteRef:
      key: authlete-secret
      property: tokenmigrator.service-token
  - secretKey: authlete-source-datasource-username
    remoteRef:
      key: authlete-secret
      property: tokenmigrator.datasource-username
  - secretKey: authlete-source-datasource-password
    remoteRef:
      key: authlete-secret
      property: tokenmigrator.datasource-password

4. Deploy the token migrator

You can now deploy the token migrator by enabling it and running helm upgrade. We recommend that the first time you deploy the service you deploy it in dryrun mode to verify that all the configuration is working correctly. Only use mode sync when you are starting the migration.

tokenmigrator:
  enabled: true
  mode: dryrun # dryrun (verify, no writes) | sync (actual migration)

Read Migrate from an old version to plan your migration strategy and measure the impact of the token migration process in the resources of your environment before starting your migration path.

5. Remove the token migrator

The token migrator is intended to be used temporarily so as part of your journey you will have to decomission the service.

Remove the service by setting tokenmigrator.enabled to false.
Disable the token migrator client either by rotating the secret or by deleting the client. This prevents the service to be re-enabled.
When you are completely sure that migration has finished you can delete the client and the service. If you created a dedicated organization for the token migrator, you can delete that organization as well.

Helm Chart Changelog

The current Helm chart version is 2.1.6.

v2.1.6 (June 26th 2026) update

Added new version releases for api:3.0.33, idp:1.0.28 and console:1.0.23
Added cleanup job to schedule automated cleanups authlete-ops:0.1.0

v2.1.5 (June 1st 2026) update

Added token migrator support (only applies to migrations from 2.3 to 3.0)
Added labels to the pre-install/pre-upgrade hooks
Added enhancements to the liquibase scripts to handle error logging
Added new version releases for api:3.0.32, idp:1.0.27 and console:1.0.22
Replaced curl with wget in the API lifecycle shutdown hook ⚠️ Breaking Change : Cloud SQL Proxy is no longer included as a sidecar in the Helm chart. Database connectivity must now be configured directly. Please refer to the database section in values.yaml for connection options.

v2.1.4 (April 3rd 2026) update

Added HSM support for AWS KMS
Added PostgreSQL as a supported database type

v2.1.3 (February 18th 2026) update

Updated default console images

v2.1.2 (February 10th 2026) update

Added new cache backend configuration with support for standalone (single cache instance) and cluster (cluster cache mode) providers
Added startUp Probe to api pods for improved startup reliability
Added configurable pod affinity rules for controlling pod scheduling across nodes
Shutdown endpoint is now protected with a dynamically generated token that rotates on every helm upgrade
Added cache control headers to nginx to comply with RFC 6749 (Authorization servers MUST include Cache-Control: no-store and Pragma "no-cache" in responses)
Fixed protocol definition for port 8443 of nginx

v2.1.1 (November 6th 2025) update

Disabled nginx version disclosure (nginx configuration change)
Added ACL (Access Control List) support to Redis
Removed Redis deployment from Helm Chart
- Cache must now be deployed independently

v2.1 (October 2nd 2025) update

Added functionality to support External Secret Manager

v2.0 (September 12th 2025) update

Added support for TLS connection with a private Certificate Authority
Added missing IP ranges for internal connections
Updated map_hash_bucket_size and server_names_hash_bucket_size parameters to accept larger values

​Prerequisites

​Installation Steps

​Setup Phase

​1. Create an Organization

​2. Request Access

​3. Generate Organization Token

​Preparation Phase

​1. Create a Kubernetes Namespace

​2. Log in to the Helm Registry

​3. Pull Helm Chart

​4. Image Registry Setup

​5. Mirror Images

Mirror using docker

Mirror using crane

​Configuration Phase

​1. Configure Values and Secrets

​2. Configure TLS Certificates

​3. Enabling TLS connection to database and memory cache (Optional)

Application Configuration

​4. Private CA (Optional)

Creating CA bundle

Creating bundle with Trust Manager (Optional)

Manual creation of bundle

Loading the custom bundles from the application

Updating the bundle

​5. Configure Database Connection

​6. Configure Caching

Managed Cache Services

​7. Configure Maintenance Tasks

Data Cleanup

Use a dedicated API instance

​8. HSM configuration

​9. External Secret Manager

Create a secret named authlete-secret in your External Secret Manager.

Without cache auth enabled:

With cache auth enabled:

​10. Configure Pod Affinity

​11. Configure Cleanup

​12. Other configuration options

Proxy configuration

DB Schema update hooks

​Deployment Phase

​1. Install Core Platform Components

Without External Secret Manager:

With External Secret Manager:

Verify the installation:

​2. Install Optional Components

Without External Secret Manager:

With External Secret Manager:

Verify the optional components:

​3. Configure Load Balancer

​4. Map Domain to Load Balancer

​Migration Phase (Optional)

​1. Create token migrator client

​2. Configure Databases

​3. Configure External Secrets (Optional)

​4. Deploy the token migrator

​5. Remove the token migrator

​Helm Chart Changelog

​v2.1.6 (June 26th 2026) update

​v2.1.5 (June 1st 2026) update

​v2.1.4 (April 3rd 2026) update

​v2.1.3 (February 18th 2026) update

​v2.1.2 (February 10th 2026) update

​v2.1.1 (November 6th 2025) update

​v2.1 (October 2nd 2025) update

​v2.0 (September 12th 2025) update

Prerequisites

Installation Steps

Setup Phase

1. Create an Organization

2. Request Access

3. Generate Organization Token

Preparation Phase

1. Create a Kubernetes Namespace

2. Log in to the Helm Registry

3. Pull Helm Chart

4. Image Registry Setup

5. Mirror Images

Configuration Phase

1. Configure Values and Secrets

2. Configure TLS Certificates

3. Enabling TLS connection to database and memory cache (Optional)

4. Private CA (Optional)

5. Configure Database Connection

6. Configure Caching

7. Configure Maintenance Tasks

8. HSM configuration

9. External Secret Manager

Create a secret named `authlete-secret` in your External Secret Manager.

10. Configure Pod Affinity

11. Configure Cleanup

12. Other configuration options

Deployment Phase

1. Install Core Platform Components

2. Install Optional Components

3. Configure Load Balancer

4. Map Domain to Load Balancer

Migration Phase (Optional)

1. Create token migrator client

2. Configure Databases

3. Configure External Secrets (Optional)

4. Deploy the token migrator

5. Remove the token migrator

Helm Chart Changelog

v2.1.6 (June 26th 2026) update

v2.1.5 (June 1st 2026) update

v2.1.4 (April 3rd 2026) update

v2.1.3 (February 18th 2026) update

v2.1.2 (February 10th 2026) update

v2.1.1 (November 6th 2025) update

v2.1 (October 2nd 2025) update

v2.0 (September 12th 2025) update