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

2. Login 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 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.

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.11 $TARGET_REGISTRY/server:3.0.11
crane cp artifacts.authlete.com/server-db-schema:v3.0.11 $TARGET_REGISTRY/server-db-schema:v3.0.11
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:

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

• Character set: utf8mb4
• Collation: utf8mb4_0900_ai_ci

• 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

4. Configure Caching

The platform supports two caching configuration options:

Option 1: Default Valkey Cache (Built-in)

By default, the platform deploys a Valkey pod as the caching solution. This configuration is ready to use out of the box and is defined in values.yaml:

redis:
  name: redis
  enabled: true
  image: valkey:8.0.1 
  # -- Resources requirements
  resources:
    requests:
      cpu: 10m
      memory: 440M
    limits:
      cpu: 1
      memory: 440M

Option 2: 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
• Azure: Azure Cache for Redis

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:

1. Disable the default Valkey service in values.yaml:

redis:
  enabled: false

2. Configure the managed cache connection in values.yaml under the API section:

api:
  env:
    - name: MEMCACHE_ENABLE
      value: "true"
    - name: MEMCACHE_HOST
      value: "<your-cache-service-host-or-ip>"  # Can be hostname or IP address

Note: If your managed cache service is configured in clustered mode, add the following environment variable:

    - name: MEMCACHE_BACKEND
      value: "redis-cluster"

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:

1. 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

2. 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

3. Apply the load balancer configuration:

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

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

1. Navigate to https://console.your-domain.com
2. Log in using the admin credentials specified in your secret-values.yaml
3. 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