Kubernetes Installation Guide

Table of Contents

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 on 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

Use the following command to log in:

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

Replace <ORG_ID> and 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 1.0.0
helm pull oci://artifacts.authlete.com/authlete-platform-chart --version 1.0.0 --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 Mirror Images section 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	Supported Version Tags
server	3.0.11
server-db-schema	v3.0.11
idp	1.0.5
idp-db-schema	v1.0.5
console	v1.0.5
authlete-nginx	1.26.3
valkey	8.0.1
gce-proxy	1.34.0
authlete-bootstrapper	1.0.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.

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

Mirror using crane

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

# Image copy commands
crane cp artifacts.authlete.com/server:3.0.9 $TARGET_REGISTRY/server:3.0.9
crane cp artifacts.authlete.com/server-db-schema:v3.0.9 $TARGET_REGISTRY/server-db-schema:v3.0.9
crane cp artifacts.authlete.com/idp:1.0.5 $TARGET_REGISTRY/idp:1.0.5
crane cp artifacts.authlete.com/idp-db-schema:v1.0.5 $TARGET_REGISTRY/idp-db-schema:v1.0.5
crane cp artifacts.authlete.com/console:v1.0.5 $TARGET_REGISTRY/console:v1.0.5
crane cp artifacts.authlete.com/authlete-nginx:1.26.3 $TARGET_REGISTRY/authlete-nginx:1.26.3
crane cp artifacts.authlete.com/valkey:8.0.1 $TARGET_REGISTRY/valkey:8.0.1
crane cp artifacts.authlete.com/gce-proxy:1.34.0 $TARGET_REGISTRY/gce-proxy:1.34.0
crane cp artifacts.authlete.com/authlete-bootstrapper:1.0.0 $TARGET_REGISTRY/authlete-bootstrapper:1.0.0

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

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

3. 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:

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
    name: idp           # Database name
    user: authlete      # Database user
    password: !raw ***** # User password
    host: localhost     # Database host
    connectionOpts: "sslMode=DISABLED&useSSL=false&allowPublicKeyRetrieval=true"  # Use additional configuration if necessary
  api: # API Server Database
    name: server
    user: authlete
    password: !raw ******
    host: localhost
    connectionOpts: "sslMode=DISABLED&useSSL=false&allowPublicKeyRetrieval=true"  # Use additional configuration if necessary

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

For GCP Cloud SQL:

  cloudSql:
    enabled: true
    image: gce-proxy:1.34.0
    instance: project:region:instance  # Your Cloud SQL instance
    port: 3306

For other cloud providers, disable Cloud SQL proxy and use direct connection:

cloudSql:
  enabled: false

Deployment Phase

1. Install Core Platform Components

Install the core platform components using Helm:

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

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
redis-5f8f64df5d-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

The following components are optional based on your requirements:

Management Console: Primary interface for Authlete platform configuration
IDP Server: OIDC compliant identity provider for user authentication and management To install optional components:

helm upgrade authlete-platform . -f secret-values.yaml -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

Create a load balancer service using the reserved IP. Create a file named proxy-lb-service.yaml:

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

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 output similar to:

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

Once the EXTERNAL-IP shows your static IP (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 that:

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