Table of Contents
Authlete レジストリから Helm チャートおよびコンテナイメージにアクセスするには、以下の手順に従ってください。
kubectl create ns authlete
以下のコマンドを使用してログインします：
helm registry login -u <ORG_ID> -p <TOKEN> artifacts.authlete.com
<ORG_ID> および <TOKEN> を実際の値に置き換えてください。
ログインが完了すると、レジストリから Helm チャートを取得できるようになります。
Authlete の Helm チャートは OCI フォーマットで配布されています。以下のコマンドでチャートを取得してローカルに展開します：
# 安定版の最新バージョンは 2.0.1
helm pull oci://artifacts.authlete.com/authlete-platform-chart --version 2.0.1 --untar
cd authlete-platform-chart
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: イメージのミラー（本番環境推奨）
本番環境では、イメージのミラー セクションを参照し、イメージをプライベートレジストリにミラーリングしてください。
信頼性と制御性を高めるため、Authlete 提供のコンテナイメージを自社のレジストリにミラーリングすることを推奨します。これにより、Authlete のレジストリへの直接依存を避け、再現性のあるデプロイが可能になります。
| イメージ | 説明 | 対応バージョンタグ |
|---|---|---|
| server | OAuth 2.0 および OpenID Connect 処理を担うコア API サーバー | 3.0.19 |
| server-db-schema | API サーバー用の DB 初期化ツール | v3.0.19 |
| idp | ユーザー認証と管理を行う ID プロバイダサーバー | 1.0.18 |
| idp-db-schema | IdP サーバー用のデータベーススキーマ初期化ツール | v1.0.18 |
| console | プラットフォーム設定および監視用の React ベース管理コンソール | 1.0.11 |
| nginx | TLS 終端とルーティングを担当する Nginx リバースプロキシ | 1.26.3 |
| valkey | パフォーマンス向上と DB 負荷軽減のためのキャッシュサービス | 8.0.1 |
| gce-proxy | GCP 環境での安全な DB 接続のための Cloud SQL プロキシ | 1.37.0 |
| authlete-bootstrapper | プラットフォーム初回デプロイ時のみ使用される初期化サービス | 1.1.0 |
# 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 を更新して、インストール前にミラーしたイメージパスを使用してください。
代替として、crane を使用してイメージを直接プッシュすることもできます。
# 対象レジストリのベースを設定
TARGET_REGISTRY="ghcr.io/your-org-name"
# イメージコピーコマンド
crane cp artifacts.authlete.com/server:3.0.19 $TARGET_REGISTRY/server:3.0.19
crane cp artifacts.authlete.com/server-db-schema:v3.0.19 $TARGET_REGISTRY/server-db-schema:v3.0.19
crane cp artifacts.authlete.com/idp:1.0.18 $TARGET_REGISTRY/idp:1.0.18
crane cp artifacts.authlete.com/idp-db-schema:v1.0.18 $TARGET_REGISTRY/idp-db-schema:v1.0.18
crane cp artifacts.authlete.com/console:1.0.11 $TARGET_REGISTRY/console:1.0.11
crane cp artifacts.authlete.com/nginx:1.26.3 $TARGET_REGISTRY/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.37.0 $TARGET_REGISTRY/gce-proxy:1.37.0
crane cp artifacts.authlete.com/authlete-bootstrapper:1.1.0 $TARGET_REGISTRY/authlete-bootstrapper:1.1.0
既定の 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 ネームスペースに 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
環境変数の変更だけで TLS 暗号化を有効化できます。
Redis: Redis 接続で TLS 暗号化が必要な場合は、MEMCACHE_HOST に rediss:// を指定します。
api:
env:
- name: MEMCACHE_ENABLE
value: "true"
- name: MEMCACHE_HOST
value: "rediss://<your-cache-service-host-or-ip>:<port>" # ホスト名または IP アドレス
IdP デプロイの場合:
env:
- name: JAVA_OPTS
value: "-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8008"
- name: AUTHLETE_IDP_REMOTE_CACHE_ENDPOINT
value: "rediss://<your-cache-service-host-or-ip>:<port>" # ホスト名または IP アドレス
- name: CLUSTER_NAME
...
Database: データベースへの TLS 接続は sslMode プロパティで有効化します。
database:
idp: # IdP サーバーのデータベース
name: idp
user: authlete
password: !raw *****
host: localhost
connectionParams:
allowPublicKeyRetrieval: true
sslMode: verify-ca # ここで sslMode を設定
api: # API サーバーのデータベース
name: server
user: authlete
password: !raw ******
host: localhost
connectionParams:
allowPublicKeyRetrieval: true
sslMode: verify-ca # ここで sslMode を設定
注記: Cloud SQL Proxy を使用する場合、接続はプロキシにより既に暗号化されるため、sslMode は
disableを設定してください。追加の TLS 層を有効にすると動作しません。
注記: Redis やデータベースが提示する TLS 証明書がプライベート CA によって発行されている場合は、すべての証明書を含むカスタムバンドルを作成し、アプリケーションに読み込ませる必要があります。詳細は Private CA セクションを参照してください。
プライベート CA 証明書で TLS を使用するには、必要な証明書をすべて含むカスタムバンドルを Helm チャートの外部で作成します。次に、そのバンドルを含む ConfigMap を作成します。要件は以下のとおりです。
ca-bundle.p12 と ca-bundle.crt の 2 つのキーを含めることtrust-manager のドキュメント に記載の方法で公開 CA バンドルを抽出することを推奨します。以下では、そのバンドルを含む ConfigMap の作成方法を説明します。
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-----
- inLine: |
-----BEGIN CERTIFICATE-----
... contents of valkey'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.0です。
バンドルの準備ができたら、アプリケーションから利用できるように追加設定を行います。.Values.global.tls.caBundle.enabled を “true” に設定して、バンドルをアプリケーションの Pod にマウントします。
tls:
caBundle:
enabled: true # これを有効にする
type: ConfigMap
name: custom-ca-bundle
trustStore:
password: "changeit"
新しいバンドルを作成して既存のものと置き換えた場合は、IdP、Authlete Server、プロキシの各 Pod (アプリケーション) を再起動してください。再起動時に、アプリケーションが更新後のバンドルを読み込みます。
本プラットフォームは 2 つのデータベースを必要とします。1 つは API サーバー用、もう 1 つは IdP サーバー用です。secret-values.yaml で接続情報を設定します。
注記: MySQL 8.0+ を使用する場合、データベースは次の設定で構成してください:
- 文字セット:
utf8mb4- 照合順序:
utf8mb4_0900_ai_ci
secret-values.yaml のテンプレートも同梱されています。データベースおよび Authlete 管理者の資格情報に合わせて修正してください。database:
idp: # IdP サーバーのデータベース
name: idp # データベース名
user: authlete # DB ユーザー
password: !raw ***** # ユーザーパスワード
host: localhost # DB ホスト
connectionParams:
allowPublicKeyRetrieval: true
sslMode: disable # disable|trust|verify-ca|verify-full
api: # API サーバーのデータベース
name: server
user: authlete
password: !raw ******
host: localhost
connectionParams:
allowPublicKeyRetrieval: true
sslMode: disable # disable|trust|verify-full
idp:
auth:
adminUser:
email: "admin@authlete.com"
password: !raw ******
encryptionSecret: ********
GCP Cloud SQL を使用する場合：
cloudSql:
enabled: true
image: gce-proxy:1.37.0
instance: project:region:instance # Cloud SQL インスタンス名
port: 3306
他のクラウドプロバイダーを使用する場合は、Cloud SQL プロキシを無効にして直接接続を使用します：
cloudSql:
enabled: false
このプラットフォームは 2 種類のキャッシュ構成に対応しています：
デフォルトでは、キャッシュとして Valkey Pod をデプロイします。この構成は 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
本番環境ではマネージドキャッシュサービスの利用を推奨します。以下のサービスに対応しています：
GCP 利用者への注意：Memorystore for Valkey を使用する際は、Private Service Connect（PSC）とサービス接続ポリシーを利用した接続を推奨します。これがサポートされている唯一のネットワーク方式です。詳細な手順は Memorystore for Valkey ネットワーク構成ガイド を参照してください。
マネージドキャッシュサービスを使用するには：
values.yaml 内で Valkey を無効化します：redis:
enabled: false
api:
env:
- name: MEMCACHE_ENABLE
value: "true"
- name: MEMCACHE_HOST
value: "<your-cache-service-host-or-ip>" # ホスト名または IP アドレス
注意：キャッシュサービスがクラスターモードの場合は以下の環境変数も追加してください：
- name: MEMCACHE_BACKEND
value: "redis-cluster"
ドメイン名が非常に長い場合、map_hash_max_size パラメータの制限に達する可能性があります。mapHashBucketSize と serverNamesHashBucketSize の値を増やすことで回避できます。
configs:
mapHashBucketSize: 128 # ここを調整
serverNamesHashBucketSize: 128 # ここを調整
Liquibase の変更セットに含まれる新しい変更を自動適用し、アプリケーションと同じバージョンのデータベーススキーマを保つため、DB スキーマ更新フックを導入しました。これらのフックは冪等であり、アップグレード版と旧版の間でスキーマに変更がない限り、既存のデータベーススキーマを変更しません。
これらのフックは、インストール時およびアプリケーションバージョン更新時にスキーマを作成・更新するために必要です。ただし、新規アプリケーションをデプロイしない、またはスキーマ変更が見込まれない場合は無効化できます。
hooks:
serviceAccount: ""
idpDbSchemaUpgrade:
enabled: true # 無効化可能
serverDbSchemaUpgrade:
enabled: true # 無効化可能
Helm を使用してコアコンポーネントをインストールします：
helm install authlete-platform . -n authlete -f secret-values.yaml
インストールの確認：
# 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
redis-5f8f64df5d-xxxxx 1/1 Running 0 2m
注意：初回のデプロイにはイメージの取得とデータベース初期化のために最大 5 分程度かかることがあります。
要件に応じて、以下のコンポーネントは任意でインストールできます。
インストールコマンド：
helm upgrade authlete-platform . -f secret-values.yaml -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
最後のステップとして、Authlete デプロイメントを外部に公開するためのロードバランサーサービスを構成します。
注意：以下のコマンドは 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
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 # ここに予約済みの静的 IP を入力
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 を通じてアクセス可能になります。
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 に設定した管理者アカウントでログイン注意：コンソールにアクセスできない場合は、以下の項目を確認してください：
- DNS レコードがすべてのネームサーバーに伝播されているか
- ロードバランサーのヘルスチェックが成功しているか
- TLS 証明書がすべてのドメインに対して有効であるか
現在のHelmチャートバージョンは2.0.1です。
map_hash_bucket_sizeおよびserver_names_hash_bucket_sizeパラメーターが、より大きな値を受け付けられるように拡張されました