BYO PostgreSQL データベース

組み込みの PostgreSQL データベースを本番環境で使用するための Amazon RDS PostgreSQL インスタンスに置き換えます。

Solo Enterprise for agentregistry はデフォルトで、PostgreSQL データベースをクラスターにデプロイします。このデータベースは、公開された AI アーティファクトやデプロイを含むレジストリサーバーのデータを保存するために使用されます。このデータベースはクラスター内の単一の Pod としてデプロイされるため、Pod が再起動したり使用不能になったりするとデータが失われます。

本番環境では、組み込みの PostgreSQL データベースを、独自に管理してバックアップする外部データベースインスタンスに置き換えることを推奨します。

このガイドの手順では、EKS クラスターと同じ VPC 内に Amazon RDS for PostgreSQL インスタンスをプロビジョニングし、Solo Enterprise for agentregistry がそれを使用するように構成する方法を説明します。

始める前に

OIDC プロバイダーをセットアップして、ユーザーがレジストリで認証できるようにします。
AWS EKS クラスターに Solo Enterprise for agentregistry をインストールし、arctl CLI をセットアップします。
まだ実行していない場合は、Solo Enterprise for agentregistry サーバーをポート 12121 でポートフォワードします。レジストリはデフォルトでは外部に公開されないため、ローカルマシンから到達するにはポートフォワードが必要です。
```
kubectl -n agentregistry-system port-forward svc/agentregistry-enterprise-server 12121:12121
```

クラスター名と AWS リージョンを環境変数として設定します。

AWS_REGION=<your-aws-region>  # AWS region of your EKS cluster
EKS_CLUSTER_NAME=<your-eks-cluster-name>  # AWS EKS cluster name

EKS クラスターがデプロイされている VPC ID を取得します。

VPC_ID=$(aws eks describe-cluster \
  --name "$EKS_CLUSTER_NAME" \
  --region "$AWS_REGION" \
  --query "cluster.resourcesVpcConfig.vpcId" \
  --output text)
echo "VPC ID: $VPC_ID"

EKS クラスターのセキュリティグループ ID を取得します。EKS はこのセキュリティグループをすべてのノードとコントロールプレーンにアタッチします。

EKS_NODE_SG=$(aws eks describe-cluster \
  --name "$EKS_CLUSTER_NAME" \
  --region "$AWS_REGION" \
  --query "cluster.resourcesVpcConfig.clusterSecurityGroupId" \
  --output text)
echo "EKS node security group: $EKS_NODE_SG"

RDS インスタンスと Kubernetes Secret の残りの変数を設定します。

VPC_ID=$(aws eks describe-cluster \
  --name "$EKS_CLUSTER_NAME" \
  --region "$AWS_REGION" \
  --query "cluster.resourcesVpcConfig.vpcId" \
  --output text)
echo "VPC ID: $VPC_ID"

ステップ 1: AWS RDS for PostgreSQL インスタンスを作成する

RDS PostgreSQL インスタンス用のセキュリティグループを作成します。

RDS_SG_ID=$(aws ec2 create-security-group \
 --group-name agentregistry-rds-sg \
 --description "Allow PostgreSQL from EKS nodes" \
 --vpc-id "$VPC_ID" \
 --region "$AWS_REGION" \
 --query "GroupId" --output text)
echo "RDS security group: $RDS_SG_ID"

EKS ノードのセキュリティグループからポート 5432 への TCP トラフィックを許可するインバウンドルールを RDS セキュリティグループに追加します。
```
aws ec2 authorize-security-group-ingress \
 --group-id "$RDS_SG_ID" \
 --protocol tcp \
 --port 5432 \
 --source-group "$EKS_NODE_SG" \
 --region "$AWS_REGION"
```
EKS クラスターが使用しているサブネット ID を取得します。クラスター自身のサブネットを使用すると、DB サブネットグループが少なくとも 2 つのアベイラビリティーゾーンをカバーすることを簡単に保証できます。これは RDS が要求する最小条件です。
```
SUBNET_IDS=$(aws eks describe-cluster \
 --name "$EKS_CLUSTER_NAME" \
 --region "$AWS_REGION" \
 --query "cluster.resourcesVpcConfig.subnetIds" \
 --output text | tr '\t' ',')
echo "Subnet IDs: $SUBNET_IDS"
```
データベースサブネットグループを作成します。RDS では少なくとも 2 つのアベイラビリティーゾーンのサブネットをグループでカバーする必要がありますが、VPC 内のすべてのサブネットを含める必要はありません。この VPC に既存のサブネットグループがある場合は、このステップをスキップして DB_SUBNET_GROUP をその名前に設定します。
```
DB_SUBNET_GROUP=agentregistry-db-subnet-group

aws rds create-db-subnet-group \
 --db-subnet-group-name "$DB_SUBNET_GROUP" \
 --db-subnet-group-description "Subnet group for agentregistry RDS" \
 --subnet-ids $(echo $SUBNET_IDS | tr ',' ' ') \
 --region "$AWS_REGION"
```

RDS インスタンスの詳細を設定します。

EKS_NODE_SG=$(aws eks describe-cluster \
 --name "$EKS_CLUSTER_NAME" \
 --region "$AWS_REGION" \
 --query "cluster.resourcesVpcConfig.clusterSecurityGroupId" \
 --output text)
echo "EKS node security group: $EKS_NODE_SG"

先ほど設定したサブネットグループとセキュリティグループで AWS RDS for PostgreSQL インスタンスを作成します。

aws rds create-db-instance \
 --db-instance-identifier "$DB_INSTANCE_ID" \
 --db-instance-class "$DB_INSTANCE_CLASS" \
 --engine postgres \
 --engine-version "$DB_ENGINE_VERSION" \
 --master-username "$PG_USER" \
 --master-user-password "$PG_PASS" \
 --db-name postgres \
 --allocated-storage 20 \
 --storage-type gp3 \
 --no-publicly-accessible \
 --vpc-security-group-ids "$RDS_SG_ID" \
 --db-subnet-group-name "$DB_SUBNET_GROUP" \
 --backup-retention-period 7 \
 --region "$AWS_REGION"

Note

初期データベースの名前は postgres です。agentregistry アプリケーションデータベースは後のステップで作成します。RDS ではインスタンス作成時にマスターデータベースの名前変更が許可されないため、この時点では作成できません。

インスタンスが available 状態になるまで待ちます。セットアップには 5～10 分かかることがあります。
```
aws rds wait db-instance-available \
 --db-instance-identifier "$DB_INSTANCE_ID" \
 --region "$AWS_REGION"
echo "RDS instance is available."
```
データベースが使用可能になった場合の出力例:
```
RDS instance is available.
```

RDS の接続詳細を取得します。

PG_HOST=$(aws rds describe-db-instances \
 --db-instance-identifier "$DB_INSTANCE_ID" \
 --region "$AWS_REGION" \
 --query "DBInstances[0].Endpoint.Address" \
 --output text)
PG_PORT=5432
echo "RDS endpoint: $PG_HOST:$PG_PORT"

agentregistry データベースを作成します。データベースを作成するには、クラスター内で一時的な Pod を実行して RDS インスタンスに接続し、アプリケーションデータベースを作成する必要があります。
```
kubectl -n agentregistry-system run pg-setup --rm -it --image=postgres:16 --restart=Never -- \
 psql "host=$PG_HOST port=$PG_PORT user=$PG_USER password='$PG_PASS' dbname=postgres sslmode=require" \
 -c 'CREATE DATABASE agentregistry;'
```
出力例:
```
CREATE DATABASE
```
Helm リリースをアップグレードする前に、agentregistry-system ネームスペース内の Pod が新しいデータベースに到達できることを確認します。このコマンドがタイムアウトするか接続エラーを返す場合は、セキュリティグループのルールとサブネットの設定を確認してください。

kubectl -n agentregistry-system run pg-probe –rm -it –image=postgres:16 –restart=Never –
psql “host=$PG_HOST port=$PG_PORT user=$PG_USER password=’$PG_PASS’ dbname=agentregistry sslmode=require”
-c ‘SELECT current_user, version();’


 出力例:

 ```console
current_user  |                                              version                                              
current_user  |                                              version                                              
---------------+---------------------------------------------------------------------------------------------------
agentregistry | PostgreSQL 16.13 on x86_64-pc-linux-gnu, compiled by x86_64-pc-linux-gnu-gcc (GCC) 12.4.0, 64-bit
(1 row)

ステップ 2: データベースの接続詳細を保存する

データベース接続文字列を Kubernetes Secret に保存します。レジストリサーバーは起動時にこの Secret から接続文字列を読み取ります。接続文字列は次の形式で指定できます。

URL 形式 (libpq): 接続文字列は postgresql:// または postgres:// プレフィックススキームを持つ標準 URI 形式で指定します。パスワード内の @ や ! などの特殊文字はパーセントエンコードする必要があります。接続文字列の例: postgresql://myuser:password@mydb.com:5432/agentregistry。接続文字列内の @ は、ユーザー名とパスワードをデータベースホスト名から区切ります。
DSN 形式 (キーワード/値ペア): この形式はスペース区切りの key=value ペアを使用します。値にスペースが含まれる場合や値が空の場合は、シングルクォートで囲む必要があります。接続文字列の例: host=mydb.com port=5432 user=myuser password='password' dbname=agentregistry sslmode=require。

Note

Helm values にインラインで接続文字列を指定する予定の場合は、このステップをスキップしてステップ 3: Solo Enterprise for agentregistry をアップグレードするに進めます。

URL 形式では postgres:// 接続文字列を使用します。パスワードの $、@、/、? などの特殊文字は、接続文字列 URL に埋め込む前にパーセントエンコードしてください。

パスワードの特殊文字をパーセントエンコードします。

ENCODED_PASSWORD=$(python3 -c \
 "import urllib.parse, sys; print(urllib.parse.quote(sys.argv[1], safe=''))" \
 "$PG_PASS")

echo "Encoded password: $ENCODED_PASSWORD"

URL 形式で接続文字列を構築します。

URL="postgres://${PG_USER}:${ENCODED_PASSWORD}@${PG_HOST}:${PG_PORT}/agentregistry?sslmode=require"

echo "Connection string in URL format: $URL"

接続文字列を含む Kubernetes Secret を作成します。

kubectl -n agentregistry-system create secret generic agentregistry-db-creds \
  --from-literal=AGENT_REGISTRY_DATABASE_URL="$URL"

接続文字列が Secret に保存されていることを確認します。

kubectl -n agentregistry-system get secret agentregistry-db-creds \
  -o jsonpath="{.data.AGENT_REGISTRY_DATABASE_URL}" | base64 -d ; echo

キーワード/値形式は読みやすく、特殊文字をパーセントエンコードする必要はありません。

DSN 形式で接続文字列を構築します。

DSN="host=$PG_HOST port=$PG_PORT user=$PG_USER password='$PG_PASS' dbname=agentregistry sslmode=require"

echo "Connection string in DSN format: $DSN"

接続文字列を含む Kubernetes Secret を作成します。

kubectl -n agentregistry-system create secret generic agentregistry-db-creds \
 --from-literal=AGENT_REGISTRY_DATABASE_URL="$DSN"

接続文字列が Secret に保存されていることを確認します。

kubectl -n agentregistry-system get secret agentregistry-db-creds \
 -o jsonpath="{.data.AGENT_REGISTRY_DATABASE_URL}" | base64 -d ; echo

ステップ 3: Solo Enterprise for agentregistry をアップグレードする

オプション: 参照用に現在の Helm values をファイルに保存します。

helm get values agentregistry --namespace agentregistry-system -o yaml > agentregistry-values.yaml

組み込みの PostgreSQL データベースから AWS RDS インスタンスに切り替えるため、Helm リリースをアップグレードします。

--reuse-values フラグは前のリリースのすべての値を自動的に再適用するため、変更するデータベース設定だけを渡せば済みます。データベース接続文字列を以前に Kubernetes Secret に保存した場合は、Helm values にその Secret への参照を指定します。データベース接続文字列を Helm values にインラインで指定するには、Inline connection string の手順に従います。

helm upgrade -i agentregistry \
  oci://us-docker.pkg.dev/solo-public/agentregistry-enterprise/helm/agentregistry-enterprise \
  --namespace agentregistry-system \
  --reuse-values \
  --set database.postgres.type=external \
  --set database.postgres.external.secretRef.name=agentregistry-db-creds \
  --set database.postgres.external.secretRef.key=AGENT_REGISTRY_DATABASE_URL \
  --wait --timeout=5m

Helm の値	説明
`database.postgres.type`	Solo Enterprise for agentregistry が提供する組み込みの PostgreSQL データベースインスタンスではなく、独自のデータベースインスタンスを使用するには `external` に設定します。
`database.postgres.external.secretRef.name`	データベースインスタンスの接続文字列を保持する Kubernetes Secret の名前。`database.postgres.external.url` とは相互に排他的です。
`database.postgres.external.secretRef.key`	接続文字列情報が含まれる Secret 内のキー。

helm upgrade -i agentregistry \
  oci://us-docker.pkg.dev/solo-public/agentregistry-enterprise/helm/agentregistry-enterprise \
  --namespace agentregistry-system \
  --reuse-values \
  --set database.postgres.type=external \
  --set database.postgres.external.url=${DSN} \
  --wait --timeout=5m

Helm の値	説明
`database.postgres.type`	Solo Enterprise for agentregistry が提供する組み込みの PostgreSQL データベースインスタンスではなく、独自のデータベースインスタンスを使用するには `external` に設定します。
`database.postgres.external.url`	データベースインスタンスへの接続に使用する接続文字列。`database.postgres.external.secretRef.name` とは相互に排他的です。

ステップ 4: 接続を確認する

Solo Enterprise for agentregistry コントロールプレーンの Pod が正常に起動していること、および agentregistry-enterprise-postgresql-* Pod が表示されないことを確認します。
```
kubectl get pods -n agentregistry-system
```

レジストリサーバー Pod の環境変数に Secret 参照が設定されていることを確認します。

kubectl -n agentregistry-system describe pod -l app.kubernetes.io/component=server \
  | sed -n '/AGENT_REGISTRY_DATABASE_URL/,/^$/p' | head -5

期待される出力:

RDS instance is available.

サーバーログで、マイグレーションと接続が成功したことを示すメッセージを確認します。

kubectl -n agentregistry-system logs deploy/agentregistry-enterprise-server --tail=50 \
  | grep "migration"

期待される出力:

...
{"time":"2026-06-03T21:28:33.530149351Z","level":"info","msg":"all migrations applied successfully","component":"default","component":"database.migrate"}

レジストリが RDS インスタンスに作成したテーブルを一覧表示します。

kubectl -n agentregistry-system run pg-check --rm -it --image=postgres:16 --restart=Never -- \
  psql "host=$PG_HOST port=$PG_PORT user=$PG_USER password='$PG_PASS' dbname=agentregistry sslmode=require" \
  -c '\dt'

期待される出力:

                  List of relations
Schema |        Name        | Type  |     Owner     
--------+--------------------+-------+---------------
 public | aws_agents         | table | agentregistry
 public | aws_connections    | table | agentregistry
 public | gcp_connections    | table | agentregistry
 public | gcp_resources      | table | agentregistry
 public | issued_tokens      | table | agentregistry
 public | kagent_connections | table | agentregistry
 public | kagent_resources   | table | agentregistry
 public | schema_migrations  | table | agentregistry
 public | secret_payloads    | table | agentregistry
 public | signing_keys       | table | agentregistry
(10 rows)

アップグレード