Kubernetes インストールガイド

前提条件

MySQL インスタンス（v8.0+）にアクセス可能な Kubernetes クラスター（v1.24 以降）
最低限必要なクラスターリソース：4 vCPU、16GB RAM
テーブルに対する読み書きおよび削除権限を持つデータベース認証情報
Helm（バージョン 3.17.0 以降）
API、Console、IDP エンドポイント用のドメイン名

インストール手順

Authlete レジストリから Helm チャートおよびコンテナイメージにアクセスするには、以下の手順に従ってください。

セットアップフェーズ

1. 組織の作成

Authlete Console にログインします。
自社用の組織を作成します。
Organization ID を控えておきます。

2. アクセスのリクエスト

Organization ID と Organization Name を Authlete サポートに共有します。
Authlete は、あなたの組織に対してレジストリアクセスを許可します。

3. 組織トークンの発行

Authlete Console にて、組織用の Token を発行します。
Organization ID と Token は認証に必要なので手元に保持しておいてください。

準備フェーズ

1. Kubernetes ネームスペースの作成

kubectl create ns authlete

2. Helm レジストリへのログイン

以下のコマンドを使用してログインします：

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

<ORG_ID> および <TOKEN> を実際の値に置き換えてください。ログインが完了すると、レジストリから Helm チャートを取得できるようになります。

3. Helm チャートの取得

Authlete の Helm チャートは OCI フォーマットで配布されています。以下のコマンドでチャートを取得してローカルに展開します：

# 安定版の最新バージョンは 2.1.7
helm pull oci://artifacts.authlete.com/authlete-platform-chart --version 2.1.7 --untar
cd authlete-platform-chart

4. イメージレジストリの設定

Authlete のコンテナイメージへのアクセスには 2 つのオプションがあります： オプション A: 直接レジストリアクセス（開発／評価環境） 開発または評価目的の環境では、Authlete のレジストリから直接イメージを取得可能です：

# レジストリ認証用のシークレットを作成
kubectl create secret docker-registry authlete-registry \
-n authlete \
--docker-server=artifacts.authlete.com \
--docker-username=<ORG_ID> \
--docker-password=<TOKEN>

# デフォルトの ServiceAccount にこのシークレットを設定
kubectl patch serviceaccount default \
-n authlete \
-p '{"imagePullSecrets": [{"name": "authlete-registry"}]}'

オプション B: イメージのミラー（本番環境推奨） 本番環境では、イメージのミラーセクションを参照し、イメージをプライベートレジストリにミラーリングしてください。

5. イメージのミラー

信頼性と制御性を高めるため、Authlete 提供のコンテナイメージを自社のレジストリにミラーリングすることを推奨します。これにより、Authlete のレジストリへの直接依存を避け、再現性のあるデプロイが可能になります。

イメージ	説明	対応バージョンタグ
server	OAuth 2.0 および OpenID Connect 処理を担うコア API サーバー	3.0.35
server-db-schema	API サーバー用の DB 初期化ツール	v3.0.35
idp	ユーザー認証と管理を行う ID プロバイダサーバー	1.0.30
idp-db-schema	IdP サーバー用のデータベーススキーマ初期化ツール	v1.0.30
console	プラットフォーム設定および監視用の React ベース管理コンソール	1.0.25
token-migrator	OAuth トークンを Authlete 2.3 から Authlete 3.0 へ移行するためのバックグラウンドジョブ	1.4
authlete-ops	定期的なクリーンアップを実行するための cron ジョブ	0.3.1

# Authlete レジストリにログイン
docker login artifacts.authlete.com -u <ORG_ID> -p <TOKEN>

# イメージを取得
docker pull artifacts.authlete.com/<image>:<tag>

# タグを付けて自社レジストリにプッシュ
docker tag artifacts.authlete.com/<image>:<tag> registry.mycompany.com/<image>:<tag>
docker push registry.mycompany.com/<image>:<tag>

values.yaml を更新して、インストール前にミラーしたイメージパスを使用してください。

注記: docker pull はマルチアーキテクチャのイメージを単一のアーキテクチャに解決します。そのため自社レジストリへプッシュしたイメージは Authlete が公開したものとは異なるダイジェストを持つことになり、元のイメージに付与された署名と SBOM では検証できなくなります。ミラー後にイメージを検証する場合は、後述の crane を使用する方法をご利用ください。

代替として、crane を使用してイメージを直接プッシュすることもできます。

crane を使用したミラー

# 対象レジストリのベースを設定
TARGET_REGISTRY="ghcr.io/your-org-name"

# イメージコピーコマンド
crane cp artifacts.authlete.com/server:3.0.35 $TARGET_REGISTRY/server:3.0.35
crane cp artifacts.authlete.com/server-db-schema:v3.0.35 $TARGET_REGISTRY/server-db-schema:v3.0.35
crane cp artifacts.authlete.com/idp:1.0.30 $TARGET_REGISTRY/idp:1.0.30
crane cp artifacts.authlete.com/idp-db-schema:v1.0.30 $TARGET_REGISTRY/idp-db-schema:v1.0.30
crane cp artifacts.authlete.com/console:1.0.25 $TARGET_REGISTRY/console:1.0.25
crane cp artifacts.authlete.com/authlete-ops:0.3.1 $TARGET_REGISTRY/authlete-ops:0.3.1
crane cp artifacts.authlete.com/token-migrator:1.4 $TARGET_REGISTRY/token-migrator:1.4
crane cp nginx:1.30.5 $TARGET_REGISTRY/nginx:1.30.5

crane cp がコピーするのはイメージ本体のみです。署名と SBOM アテステーションはイメージとは別のタグとして保存されており、一緒にはコピーされません。これらも保持したい場合は、明示的にミラーしてください。

for img in server:3.0.35 server-db-schema:v3.0.35 idp:1.0.30 idp-db-schema:v1.0.30 console:1.0.25; do
  cosign copy --only=sig,att artifacts.authlete.com/$img $TARGET_REGISTRY/$img
done

6. イメージの署名と SBOM の検証 (任意)

Authlete はコンテナイメージに cosign で署名し、 CycloneDX 形式の SBOM (ソフトウェア部品表) を署名付きアテステーションとして添付しています。これらを検証することで、イメージが Authlete によって公開され、改変されていないことを確認でき、また自社の脆弱性スキャンに利用できる、そのイメージのコンポーネントの一覧を取得できます。署名と SBOM アテステーションの両方が付与されているイメージは以下のとおりです。

server および server-db-schema
idp および idp-db-schema
console

token-migrator と authlete-ops にはいずれも付与されていません。

注記: 署名と SBOM アテステーションは server 3.0.35、console 1.0.25、idp 1.0.30 以降で利用可能です。server-db-schema と idp-db-schema はそれぞれ対応するバージョンに従います。これより前のリリースにはいずれも付与されていません。

本手順には cosign と crane が必要です。

Authlete の署名鍵

以下を cosign.pub として保存してください。

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmOCQfS4MuzCm8p3vKd8ccRYRZ0m/
P0dR3b5ChXjUtt/w3kQ38VbbomXVaNe4X703fc0y1TOx/lLy0Fa8btUcag==
-----END PUBLIC KEY-----

DER 形式の公開鍵の SHA-256 フィンガープリントは fafe88f5f3ca31cc29557de31828fed2f57faa9aeefa4f9c8b5b209f80d845de です。次のコマンドで確認できます。

openssl pkey -pubin -in cosign.pub -outform DER | sha256sum

イメージの検証と SBOM の取得

署名と SBOM アテステーションは、マルチアーキテクチャのタグではなく、アーキテクチャごとのイメージダイジェストに紐づいています。そのため、検証する前に使用するアーキテクチャのダイジェストを解決してください。

IMAGE=artifacts.authlete.com/server
TAG=3.0.35

# 使用するアーキテクチャのダイジェストを解決
DIGEST=$(crane digest --platform linux/amd64 $IMAGE:$TAG)

# 署名を検証
cosign verify --key cosign.pub --insecure-ignore-tlog=true $IMAGE@$DIGEST

# SBOM アテステーションを検証し、SBOM を取り出す
cosign verify-attestation --type cyclonedx --key cosign.pub --insecure-ignore-tlog=true \
  $IMAGE@$DIGEST | jq -r .payload | base64 -d | jq .predicate > server-amd64.cdx.json

arm64 のイメージについては --platform linux/arm64 を指定して同様に実行してください。 2 つのイメージでは OS パッケージが異なるため、SBOM の内容も異なります。取り出した SBOM は標準的な CycloneDX ドキュメントであり、イメージを取得することなくオフラインでスキャンできます。

trivy sbom server-amd64.cdx.json

注記: --insecure-ignore-tlog=true の指定が必要です。Authlete はハードウェアで保護された鍵管理サービス (KMS) に保管された長期利用の鍵で署名しており、公開の Rekor 透明性ログには署名を登録していません。

設定フェーズ

1. Values とシークレットの設定

既定の values.yaml はチャートに同梱されています。必要に応じて内容を確認・変更してください。
global.repo を自社レジストリに設定します。

global:
  id: "authlete-platform"
  repo: "registry.your-company.com"  # 必須: 自社のコンテナレジストリ

ドメイン名を domains セクションに設定します：

  # 必須: これらのドメインは利用者からアクセス可能である必要があります
  api: "api.your-domain.com"     # API サーバー
  idp: "login.your-domain.com"   # IDP サーバー
  console: "console.your-domain.com"  # 管理コンソール

重要: ドメイン名は初回インストール後に変更することができません。ドメイン名を変更する場合は、データベースを初期化し、Authlete を最初から再インストールする必要があります。インストール前に使用するドメイン名を慎重に決定してください。

2. TLS 証明書の設定

ドメイン用の TLS 証明書（例: Let’s Encrypt や社内の証明機関から取得）を用意し、authlete ネームスペースに kubernetes.io/tls タイプの Kubernetes シークレットを作成してください。証明書はすべてのドメイン（例: api.example.com、login.example.com、console.example.com）をカバーしている必要があります。ワイルドカードまたは SAN 証明書を使用できます。

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

注意： proxy-certsを外部シークレットマネージャーから管理する場合は、このステップを省略し、外部シークレットマネージャーのセクションをご参照ください。

3. データベースおよびメモリキャッシュへの TLS 接続を有効化 (任意)

アプリケーション設定

環境変数の変更だけで TLS 暗号化を有効化できます。 Redis: Redis 接続で TLS 暗号化を有効にするには、キャッシュ接続設定で tls: true を指定します。

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 接続は sslMode プロパティで有効化します。

database:
  idp:  # IdP サーバーのデータベース
    name: idp
    type: mysql # mysql|postgres (defaults to mysql if unset)
    host: localhost
    connectionParams:
      allowPublicKeyRetrieval: true
      sslMode: verify-ca # ここで sslMode を設定
  api: # API サーバーのデータベース
    name: authlete
    type: mysql # mysql|postgres (defaults to mysql if unset)
    host: localhost
    connectionParams:
      allowPublicKeyRetrieval: true
      sslMode: verify-ca # ここで sslMode を設定

注記: Redis やデータベースが提示する TLS 証明書がプライベート CA によって発行されている場合は、すべての証明書を含むカスタムバンドルを作成し、アプリケーションに読み込ませる必要があります。詳細は Private CA セクションを参照してください。

4. Private CA (Optional)

プライベート CA 証明書で TLS を使用するには、必要な証明書をすべて含むカスタムバンドルを Helm チャートの外部で作成します。次に、そのバンドルを含む ConfigMap を作成します。要件は以下のとおりです。

ConfigMap 名は “custom-ca-bundle” とすること
少なくとも ca-bundle.p12 と ca-bundle.crt の 2 つのキーを含めること

CA バンドルの作成

trust-manager のドキュメントに記載の方法で公開 CA バンドルを抽出することを推奨します。以下では、そのバンドルを含む ConfigMap の作成方法を説明します。

trust-manager を使ったバンドル作成 (任意)

trust-manager を使うと、Kubernetes で信頼バンドルの管理が容易になります。インストール手順は trust-manager の公式ドキュメントを参照してください。trust-manager をインストールしたら、単一の Bundle オブジェクトを作成します。必要な証明書をすべて含む ConfigMap は自動的に生成されます。以下は trust-manager が最終バンドルを組み立てるための Bundle の例です。この Bundle のマニフェストファイル名は 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"
    # and 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

最後に、次のコマンドで Bundle を作成します。

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

注記: cert-manager が提供する公式の Debian trust パッケージを使用している場合は、trust パッケージが最新に保たれているか定期的に確認してください。

バンドルの手動作成

以下の手順では、docker コマンドを使ってカスタムバンドルを数ステップで作成します。

注記: 以下のチュートリアルはサンプルコードです。バンドルの作成・保管・更新を安全に行うことはお客様の責務です。

gen-bundles.sh ファイルを作成

# Input/output directories
SRC="/certs"                                         # crt ファイルを配置する場所
DST="/usr/local/share/ca-certificates/custom"        # update-ca-certificates が監視するディレクトリ
OUT="/bundle"                                        # バンドルの出力先

# 出力ディレクトリをクリーンアップ
rm -f $OUT/*

# 出力ディレクトリを作成
mkdir -p "$DST"

# 必要なパッケージをインストール (Java の truststore 生成に ca-certificates-java が必要)
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) 追加証明書の配置 (*.pem / *.crt を .crt として配置)
cp -v ${SRC}/* ${DST}/
# .pem も .crt として扱うため拡張子を統一したい場合は以下を有効化
# for f in "$DST"/*.pem; do mv -v "$f" "${f%.pem}.crt"; done

# 2) システム & Java truststore を更新
update-ca-certificates -f

# 3) 出力 (PEM と 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

バンドルをビルド

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"

ca-bundle.p12 と ca-bundle.crt が準備できたら、次のように Kubernetes の ConfigMap を作成します。

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

注記: trust-manager のバンドル作成に使用されている現在の Debian ベースイメージは docker.io/library/debian:12-slim で、ca-certificates のターゲットバージョンは 20230311+deb12u1.6 です。

アプリケーションからカスタムバンドルを読み込む

バンドルの準備ができたら、アプリケーションから利用できるように追加設定を行います。.Values.global.tls.caBundle.enabled を “true” に設定して、バンドルをアプリケーションの Pod にマウントします。

  tls:
    caBundle:
      enabled: true # これを有効にする
      type: ConfigMap
      name: custom-ca-bundle
      trustStore:
        password: "changeit"

バンドルの更新

新しいバンドルを作成して既存のものと置き換えた場合は、IdP、Authlete Server、プロキシの各 Pod (アプリケーション) を再起動してください。再起動時に、アプリケーションが更新後のバンドルを読み込みます。

5. データベース接続を設定

本プラットフォームは 2 つのデータベースを必要とします。1 つは API サーバー用、もう 1 つは IdP サーバー用です。secret-values.yaml で接続情報を設定します。

注記: MySQL 8.0+ を使用する場合、データベースは次の設定で構成してください:

文字セット: utf8mb4

照合順序: utf8mb4_0900_ai_ci

チャートアーカイブには secret-values.yaml のテンプレートも同梱されています。データベースおよび Authlete 管理者の資格情報に合わせて修正してください。

database:
  idp:  # IdP サーバーのデータベース
    user: authlete      # DB ユーザー
    password: !raw ***** # ユーザーパスワード
  api: # API サーバーのデータベース
    user: authlete
    password: !raw ******

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

※ AWS-EKSでMySQLデータベースのDNS名を使用される場合：・RDS-Proxyを使用する場合：host: sample-db.proxy-stu901vwx234.us-east-1.rds.amazonaws.com ・RDS-Proxyを使用しない場合：host: sample-db.cluster-stu901vwx234.us-east-1.rds.amazonaws.com

6. キャッシュの設定

以下が現在サポートされているキャッシュソリューション：

マネージドキャッシュサービス

本番環境ではマネージドキャッシュサービスの利用を推奨します。以下のサービスに対応しています：

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

GCP 利用者への注意：Memorystore for Valkey を使用する際は、Private Service Connect（PSC）とサービス接続ポリシーを利用した接続を推奨します。これがサポートされている唯一のネットワーク方式です。詳細な手順は Memorystore for Valkey ネットワーク構成ガイドを参照してください。

マネージドキャッシュサービスを使用するには、values.yamlを下記の通りに編集します：

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

注意：キャッシュサービスがクラスターモードの場合は provider を cluster に設定してください：

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

7. メンテナンスタスクの設定

プラットフォームの安定性を維持し、不要なストレージの使用を避けながら最適なパフォーマンスを確保するためには、定期的なメンテナンスタスクを実行する必要があります。以下の項目を確認してください。

データのクリーンアップ

AuthletはOAuth 2.0およびOpenID Connectトランザクションを大量に処理しているため、期限切れのトークンや認可コードなどのような一時的な項目が蓄積されていきます。APIスループットを最大化し、またランタイム操作中のパフォーマンスを確保するため、Authleteは期限切れの項目に対して、有効期限を過ぎた直後に削除せず、期限切れのフラグを立て、このクリーンアップタスクの対象として削除します。管理をしなかった場合、このデータの肥大化はデータベースクエリのパフォーマンスの低下、および過剰なストレージの消費に繋がってしまうリスクがあります。クリーンアップタスクを定期的に実行し、期限切れまたは削除されたすべてのレコードに対して、物理的な削除を行う必要があります。そうするには、values.yml内にある下記のセクションを修正し、プロセスの実行時刻を指定してください。scheduleプロパティはKubernetesのスケジュール形式を使用します。

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

重要： 本番環境では、クリーンアッププロセスをピーク時間外（例：現地時刻で午前2時）に1日1回以上実行することをお勧めします。

専用APIインスタンスの使用

Authlete APIを通してデータ削除を実行するメンテナンスタスクは、データ削除を行うインスタンスへほとんど影響を与えないように設計されています。ただし、一部の環境においては、顧客リクエストを処理するAPIインスタンスを使用して、メンテナンスタスクを実行しない方が良い場合もあります。その場合、メンテナンスタスク専用のAPIコピーをデプロイするdeployApiSidecar: trueオプションを有効にすることをお勧めします。有効化した場合は、追加リソースがかかりますので注意してください。

8. HSM設定

AuthleteはGoogle Cloud HSMとAWS KMSをサポートしています。使用する場合は以下を参照してください。 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: ""

AWS KMSの場合：

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

9. 外部シークレットマネージャー

外部シークレットマネージャーを使用する場合、Helmデプロイに必要なシークレットがクラスター上に存在し、適切に構成されている必要があります。シークレットが見つからない場合は、デプロイおよびアップグレードの工程が失敗します。必要なシークレットはauthlete-credentialsとproxy-certs（proxy-certsを外部シークレットマネージャーで管理する場合）です。

外部シークレットマネージャーに`authlete-secret`のシークレットを追加します。

Cache Authが無効の場合：

{
  "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 Authが有効の場合：

{
  "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>"
      }
    }
  }
}

<ClusterSecretStore-name>をクラスターのClusterSecretStore名に置き換えてください。

kubectl apply -f - <<EOF
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: authlete-secret
  namespace: authlete
spec:
  refreshInterval: 30s
  secretStoreRef:
    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
  # Cache Authが有効になっている場合
  - 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
  # 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 トークン
  # API Pod の preStop ライフサイクルフックが /api/lifecycle/shutdown を
  # 呼び出す際の Bearer 認証トークンです。32文字程度のランダム英数字を
  # 任意で生成し、外部シークレットマネージャーへ登録してください。
  - 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
EOF

外部シークレットマネージャーでプロキシ証明書（proxy-certs）を管理する場合は、authlete-proxy-secretのシークレットを作成してください

# 外部シークレットマネージャー上に証明書を保存する場合、JSONキーは下記のものと一致しているかご確認ください:
- `tls.crt` for the certificate chain
- `tls.key` for the private key

# 使用例:
{
  "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-----"
}

# TLS証明書の外部シークレットマネージャーへの移行は任意です。
# 移行しない場合は、「インストール手順 → 設定フェーズ → TLS証明書の設定のセクションに従ってTLS証明書を設定してください。

kubectl apply -f - <<EOF
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: authlete-proxy-secret
  namespace: authlete
spec:
  refreshInterval: 30s
  secretStoreRef:
  # <ClusterSecretStore-name>をクラスターのClusterSecretStore名に置き換えてください。
    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

注意: HelmチャートのexternalSecrets機能を有効化する場合は、values.yamlを下記のように更新して下さい。

global:
  externalSecrets:
    enabled: true  # ESMを有効化する場合は'true' | デフォルト値は'false'

10. Podアフィニティの設定

Podアフィニティを有効化するには、values.yamlを下記のように編集してください:

global:
  apiAffinity: true

apiAffinityはデフォルトとしてfalseに設定されており、その場合podアフィニティは無効になります。 Podアフィニティを有効化することによって、API podと同じノードに存在するプロキシpodをスケジューリングすることが可能になり、パーフォーマンスを向上させ、またネットワークレイテンシーを軽減させることができます。

11. クリーンアップジョブを設定する

クリーンアップを有効にする場合、下記をvalues.yamlファイルに含めてください：

ops:
  cleanup:
    enabled: false

apiAffinityがfalse（デフォルト値）の場合, Podアフィニティは設定されません。 Podアフィニティを有効にすると、ネットワーク遅延を軽減させるためにプロキシのポッドがAPIポッドと同じノードに設定され、各コンポーネント間でのパフォーマンスが改善されます。

12. その他の設定オプション

プロキシ設定

ドメイン名が非常に長い場合、map_hash_max_size パラメータの制限に達する可能性があります。mapHashBucketSize と serverNamesHashBucketSize の値を増やすことで回避できます。

  configs:
    mapHashBucketSize: 128 # ここを調整
    serverNamesHashBucketSize: 128 # ここを調整

DB スキーマ更新フック

Liquibase の変更セットに含まれる新しい変更を自動適用し、アプリケーションと同じバージョンのデータベーススキーマを保つため、DB スキーマ更新フックを導入しました。これらのフックは冪等であり、アップグレード版と旧版の間でスキーマに変更がない限り、既存のデータベーススキーマを変更しません。 これらのフックは、インストール時およびアプリケーションバージョン更新時にスキーマを作成・更新するために必要です。ただし、新規アプリケーションをデプロイしない、またはスキーマ変更が見込まれない場合は無効化できます。

hooks:
  serviceAccount: ""
  idpDbSchemaUpgrade:
    enabled: true # 無効化可能
  serverDbSchemaUpgrade:
    enabled: true # 無効化可能

デプロイフェーズ

1. コアプラットフォームコンポーネントのインストール

Helm を使用してコアコンポーネントをインストールします。

外部シークレットマネージャーを使用しない場合:

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

外部シークレットマネージャーを使用する場合:

helm install authlete-platform . -n authlete

インストールの確認：

# Podのステータス確認
kubectl get pods -n authlete

期待される出力例：

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

注意：初回のデプロイにはイメージの取得とデータベース初期化のために最大 5 分程度かかることがあります。

2. オプションコンポーネントのインストール

要件に応じて、以下の任意コンポーネントをインストールすることも可能です。

管理コンソール: Authlete プラットフォームの主な設定 UI
IdP サーバー: ユーザー認証と管理のための OIDC 準拠 IdP

外部シークレットマネージャーを使用しない場合:

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

外部シークレットマネージャーを使用する場合:

helm upgrade authlete-platform . -n authlete

オプションコンポーネントの確認：

# 新しい Pod のステータス確認
kubectl get pods -n authlete

期待される出力例：

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

3. ロードバランサーの構成

最後のステップとして、Authlete デプロイメントを外部に公開するためのロードバランサーサービスを構成します。

まず、クラウドプロバイダーで静的外部 IP アドレスを予約します。

注意：以下のコマンドは GCP 専用です。他のクラウドプロバイダー（AWS、Azure など）を使用している場合は、各プロバイダーのドキュメントを参照して静的 IP アドレスを予約してください。
GCP では、GKE LoadBalancer サービスが同じリージョンに割り当てられた IP のみをサポートするため、リージョン固定の静的 IP を予約する必要があります。

# GCP 固有のコマンド
# 静的 IP アドレスを予約
gcloud compute addresses create authlete-ip --region=us-central1

# 予約済み IP アドレスを取得
gcloud compute addresses describe authlete-ip --region=us-central1

予約した IP を使用してロードバランサーサービスを作成します。以下の内容で proxy-lb-service.yaml というファイルを作成してください：

以下がGKEの使用例になります

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  # ここに予約済みの静的 IP を入力

以下がAWS-EKSの使用例になります

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

ロードバランサー設定を適用します：

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

ロードバランサーの構成を確認します：

kubectl get service proxy-lb -n authlete

次のような出力が得られるはずです：

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

EXTERNAL-IP に予約した IP アドレスが表示されれば、Authlete デプロイメントは HTTPS 経由でその IP を通じてアクセス可能になります。

4. ドメインとロードバランサーのマッピング

3 つのドメインすべてに対して、ロードバランサーの IP アドレスを指すように DNS レコードを作成してください：

# API サーバー
api.your-domain.com.     IN  A     YOUR_STATIC_IP

# IDP サーバー
login.your-domain.com.   IN  A     YOUR_STATIC_IP

# 管理コンソール
console.your-domain.com. IN  A     YOUR_STATIC_IP

DNS 設定の確認：

# DNS 設定のテスト
dig +short api.your-domain.com
dig +short login.your-domain.com
dig +short console.your-domain.com

# HTTPS エンドポイントのテスト
curl -I https://api.your-domain.com/api/info

すべてのドメインがロードバランサーの IP に解決され、エンドポイントにアクセス可能であれば、Authlete は利用準備が整っています。次の手順で管理コンソールにアクセスできます：

ブラウザで https://console.your-domain.com にアクセス
secret-values.yaml に設定した管理者アカウントでログイン
Authlete サービスの構成を開始

注意：コンソールにアクセスできない場合は、以下の項目を確認してください：

DNS レコードがすべてのネームサーバーに伝播されているか

ロードバランサーのヘルスチェックが成功しているか

TLS 証明書がすべてのドメインに対して有効であるか

移行フェーズ（任意）

Authlete 2.3から3.0へ移行される場合、トークン移行を行うために**トークン移行ツール（Token Migrator）**を有効にする必要があります。

1. トークン移行ツール用クライアントの作成

トークン移行ツールが3.0環境にアクセスできるようにするため、移行先となる3.0環境においてまずサービスとクライアントを作成する必要があります。作成したサービスとクライアントは、トークン移行ツール起動時に環境へのアクセス権を確認するために使用されます。クライアントの作成と設定は以下の手順で行なってください：

https://console.your-domain.comへアクセスします
管理者としてログインします
CLIENT_CREDENTIALSグラントを有効にした新しいサービスを作成し、サービス IDを控えます
サービスを使用するための権限を持つサービスアクセストークンを作成し、トークンを控えます
トークン移行ツール専用に使用するクライアントを下記設定で作成：
- クライアントIDエイリアス: migration-service@system.authlete.com
- クライアント認証方式: CLIENT_SECRET_POST
- サポートされるグラントタイプ: CLIENT_CREDENTIALS
新しく作成したクライアントのクライアントシークレットを控えます
チャートアーカイブに含まれるsecret-values.yamlファイルのtokenmigratorセクションを、作成したクライアント情報を指定して編集します

tokenmigrator:
  clientSecret: ""            # クライアントシークレット
  serviceApiKey: ""           # Authlete v3.0サービスID
  serviceToken: ""            # Authlete v3.0サービスアクセストークン

2. データベース設定

トークン移行ツールは2.3と3.0両方のデータベースに接続する必要があります。3.0のデータベース情報はHelmチャートにおいて既にアクセス可能ですが、2.3データベースに関しては接続情報を提供する必要があります。

values.yamlファイルのtokenmigrator.sourceDatabase.hostを、既存のAuthlete 2.3データベースに向くように設定します 2.3データベースにおいてTLSが必要な場合は、データベースおよびメモリキャッシュへの TLS 接続を有効化 (任意) のガイドラインに従ってtokenmigrator.sourceDatabase.connectionParamsプロパティを設定してください。
チャートアーカイブに含まれるsecret-values.yamlファイルのtokenmigrator.databaseセクションを2.3データベース接続用の資格情報を指定して編集します

tokenmigrator:
  database:
    user: root                # 移行元（v2.3）データベースのユーザー名
    password: !raw example**  # 移行元（v2.3）データベースのパスワード

3. 外部シークレットの設定 (任意)

外部シークレットマネージャーを使用している場合は、トークン移行ツールが使用するクライアント情報とデータベース資格情報を外部シークレットに追加する必要があります。以下のコードスニペットを参考にトークン移行ツールのプロパティを追加してください：

{
  "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>"
  }
}

Kubernetesの外部シークレットリソースに以下を追加してください：

kubectl apply -f - <<EOF
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: authlete-secret
  namespace: authlete
spec:
  refreshInterval: 30s
  secretStoreRef:
  # クラスターのClusterSecretStore名に置き換えてください
    kind: ClusterSecretStore
    name: <ClusterSecretStore-name>
  target:
    name: authlete-credentials
    creationPolicy: Owner
  data:
  # IDPデータベース
  - 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データベース
  - 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管理者
  - 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
  # トークン移行ツールのシークレット
  - 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. トークン移行ツールのデプロイ

これによりhelm upgradeを実行してトークンマイグレーターをデプロイすることが可能になります。初回デプロイの場合はdryrunモードを使用し、設定を確認することを推奨します。実際の移行を開始する際はsyncモードに切り替えてください。

tokenmigrator:
  enabled: true
  mode: dryrun # dryrun（検証・書き込みなし） | sync（実移行）

移行を開始する前に、Authlete 3.0 へのトークンの移行を参照してください。

5. トークン移行ツールの削除

トークン移行ツールは一時的な使用を目的としているため、移行が完了した後は廃止する必要があります。

tokenmigrator.enabledをfalseに設定します
クライアントを削除する、もしくはシークレットをローテーションすることによって、トークン移行ツール用のクライアントを無効化してください（ツールが再有効化されることを防ぎます）。
移行が完了したことを確認できた後、クライアントとサービスを削除してください。トークン移行ツール専用の組織を作成していた場合は、その組織も削除して構いません。

Helmチャートチェンジログ

現在のHelmチャートバージョンは2.1.7です。

v2.1.7 （2026年09月10日）

authlete-opsのイメージタグが0.3.1へ更新されました
token-migratorのイメージタグが1.4へ更新されました
api:3.0.35、idp:1.0.30、console:1.0.25の新バージョンのリリースが追加されました
トークン移行ツールのMaxRAMPercentage計算に対する階層化のロジックが実装されました
helm installコマンドが冪等性を持つよう修正されました

注意： v2.1.7以降nginxのコンテナイメージの提供を廃止しているため、nginx:1.30.5（Docker Hubより入手可能）の使用を推奨しています。

v2.1.6（2026年06月26日）

api:3.0.33、idp:1.0.28、console:1.0.23の新バージョンのリリースが追加されました
クリーンアップジョブ設定用のツール（authlete-ops:0.1.0）が追加されました

v2.1.5（2026年06月01日）アップデート

トークン移行ツールのサポートが実装されました（2.3から3.0への移行のみ対象）
pre-installとpre-upgradeのフックに対してラベルが追加されました
エラーログ処理用のLiquibaseスクリプトが改善されました
api:3.0.32、idp:1.0.27、console:1.0.22の新バージョンのリリースが追加されました
APIライフサイクルの終了フックにおけるcurlコマンドがwgetへ変更されました ⚠️ 破壊的変更 : Cloud SQL ProxyがHelmチャートのサイドカーとして含まれなくなったため、データベース接続の設定を直接行うことが必要になりました。接続オプションについてはvalues.yamlのデータベースに関するセクションをご参照ください。

v2.1.4（2026年04月03日）アップデート

AWS KMS向けにHSMサポートが実装されました
サポートされるデータベースタイプとしてPostgreSQLが追加されました

v2.1.3（2026年02月18日）アップデート

デフォルトのコンソールイメージが更新されました

v2.1.2（2026年02月10日）アップデート

standalone（単一キャッシュインスタンス）およびcluster（クラスタキャッシュモード）プロバイダーに対応した新しいキャッシュバックエンド設定が実装されました
APIポッド起動時の安定性向上のため、startUpプローブが追加されました
ノード間のポッドスケジューリング制御のため、設定可能なポッドアフィニティルールが追加されました
Shutdownエンドポイントが、Helmアップグレード時ににローテーションされる動的生成トークンによって保護されるようになりました
RFC 6749に準拠するため、nginxにキャッシュ制御ヘッダーが実装されました（各Authorizationサーバーに対して、レスポンス内にCache-Control: no-storeおよびPragma: no-cacheを含める必要があります）
nginxのポート8443に対するプロトコル定義が修正されました

v2.1.1（2025年11月06日）アップデート

nginxのバージョン情報が公開されなくなりました
Redisに対してACL(Access Control List)サポートが実装されました
Helm ChartからRedisのデプロイが廃止されました
- これよりキャッシュを個別にデプロイすることが必要になりました

v2.1（2025年10月02日）アップデート

外部シークレットマネージャーのサポートが実装されました

v2.0（2025年09月12日）アップデート

プライベート証明書認証局（CA）を通したTLS接続のサポートが実装されました
不足していた内部接続向けのIPレンジが追加されました
map_hash_bucket_sizeおよびserver_names_hash_bucket_sizeパラメーターが、より大きな値を受け付けられるように拡張されました

​前提条件

​インストール手順

​セットアップフェーズ

​1. 組織の作成

​2. アクセスのリクエスト

​3. 組織トークンの発行

​準備フェーズ

​1. Kubernetes ネームスペースの作成

​2. Helm レジストリへのログイン

​3. Helm チャートの取得

​4. イメージレジストリの設定

​5. イメージのミラー

crane を使用したミラー

​6. イメージの署名と SBOM の検証 (任意)

Authlete の署名鍵

イメージの検証と SBOM の取得

​設定フェーズ

​1. Values とシークレットの設定

​2. TLS 証明書の設定

​3. データベースおよびメモリキャッシュへの TLS 接続を有効化 (任意)

アプリケーション設定

​4. Private CA (Optional)

CA バンドルの作成

trust-manager を使ったバンドル作成 (任意)

バンドルの手動作成

アプリケーションからカスタムバンドルを読み込む

バンドルの更新

​5. データベース接続を設定

​6. キャッシュの設定

マネージドキャッシュサービス

​7. メンテナンスタスクの設定

データのクリーンアップ

専用APIインスタンスの使用

​8. HSM設定

​9. 外部シークレットマネージャー

外部シークレットマネージャーにauthlete-secretのシークレットを追加します。

Cache Authが無効の場合：

Cache Authが有効の場合：

​10. Podアフィニティの設定

​11. クリーンアップジョブを設定する

​12. その他の設定オプション

プロキシ設定

DB スキーマ更新フック

​デプロイフェーズ

​1. コアプラットフォームコンポーネントのインストール

外部シークレットマネージャーを使用しない場合:

外部シークレットマネージャーを使用する場合:

インストールの確認：

​2. オプションコンポーネントのインストール

外部シークレットマネージャーを使用しない場合:

外部シークレットマネージャーを使用する場合:

オプションコンポーネントの確認：

​3. ロードバランサーの構成

​4. ドメインとロードバランサーのマッピング

​移行フェーズ（任意）

​1. トークン移行ツール用クライアントの作成

​2. データベース設定

​3. 外部シークレットの設定 (任意)

​4. トークン移行ツールのデプロイ

​5. トークン移行ツールの削除

​Helmチャートチェンジログ

​v2.1.7 （2026年09月10日）

​v2.1.6（2026年06月26日）

​v2.1.5（2026年06月01日）アップデート

​v2.1.4（2026年04月03日）アップデート

​v2.1.3（2026年02月18日）アップデート

​v2.1.2（2026年02月10日）アップデート

​v2.1.1（2025年11月06日）アップデート

​v2.1（2025年10月02日）アップデート

​v2.0（2025年09月12日）アップデート

前提条件

インストール手順

セットアップフェーズ

1. 組織の作成

2. アクセスのリクエスト

3. 組織トークンの発行

準備フェーズ

1. Kubernetes ネームスペースの作成

2. Helm レジストリへのログイン

3. Helm チャートの取得

4. イメージレジストリの設定

5. イメージのミラー

6. イメージの署名と SBOM の検証 (任意)

設定フェーズ

1. Values とシークレットの設定

2. TLS 証明書の設定

3. データベースおよびメモリキャッシュへの TLS 接続を有効化 (任意)

4. Private CA (Optional)

5. データベース接続を設定

6. キャッシュの設定

7. メンテナンスタスクの設定

8. HSM設定

9. 外部シークレットマネージャー

外部シークレットマネージャーに`authlete-secret`のシークレットを追加します。

10. Podアフィニティの設定

11. クリーンアップジョブを設定する

12. その他の設定オプション

デプロイフェーズ

1. コアプラットフォームコンポーネントのインストール

2. オプションコンポーネントのインストール

3. ロードバランサーの構成

4. ドメインとロードバランサーのマッピング

移行フェーズ（任意）

1. トークン移行ツール用クライアントの作成

2. データベース設定

3. 外部シークレットの設定 (任意)

4. トークン移行ツールのデプロイ

5. トークン移行ツールの削除

Helmチャートチェンジログ

v2.1.7 （2026年09月10日）

v2.1.6（2026年06月26日）

v2.1.5（2026年06月01日）アップデート

v2.1.4（2026年04月03日）アップデート

v2.1.3（2026年02月18日）アップデート

v2.1.2（2026年02月10日）アップデート

v2.1.1（2025年11月06日）アップデート

v2.1（2025年10月02日）アップデート

v2.0（2025年09月12日）アップデート