ランタイム設定

ランタイム設定は、Nx Plugin for AWSが生成されたプロジェクトとコンポーネント間でデプロイ時の値を渡し、相互に接続できるようにするメカニズムです。例えば、APIを生成すると、そのURLは自動的にランタイム設定に登録され、接続されたウェブサイトがそれを検出できるようになります。

仕組み

ランタイム設定は名前空間に整理されています。各名前空間は、関連する設定値の論理的なグループです。デプロイ時に、すべての名前空間はAWS AppConfigに設定プロファイルとして保存されます。

生成されたコンストラクトによって使用される4つの組み込み名前空間があります：

connection — 生成されたプロジェクトが相互に接続できるようにする設定：
- API URL — APIコンストラクトによって自動的に登録されます
- Cognito設定 — UserIdentityコンストラクトによって自動的に登録されます
- エージェントランタイムARN — Reactウェブサイトをエージェントに接続する際に、接続ジェネレーターによって追加されます
agentcore — エージェントとMCPサーバー用のAgentCoreランタイムARN。エージェント/MCPコンストラクトによって自動的に登録され、サーバーサイドの検出（A2A経由のエージェント→エージェント、エージェント→MCPサーバー）に使用されます。
dynamodb — テーブル名。DynamoDBテーブルコンストラクトによって自動的に登録され、生成されたテーブルクライアントによって読み取られます。
database — Auroraの接続詳細。リレーショナルデータベースコンストラクトによって自動的に登録され、生成されたデータベースクライアントによって読み取られます。

connection名前空間は、ウェブサイトのS3バケットにruntime-config.jsonファイルとしてもデプロイされ、バックエンドリソースのクライアントサイド検出を可能にします。他の名前空間はサーバーサイドのみ（AppConfig経由）であるため、ウェブサイトを明示的に接続しない限り、エージェントランタイムARNやテーブル名などの値はフロントエンドに公開されません。

必要に応じて追加の名前空間をいくつでも定義でき、デプロイ時の値をLambda関数や他のコンピュートリソースに渡すための環境変数の便利な代替手段を提供します。

インフラストラクチャ

設定の書き込み

生成されたコンストラクトは、関連する設定をconnection名前空間に自動的に書き込みます。任意の名前空間に独自の値を書き込むこともできます。

CDK
Terraform

RuntimeConfig CDKコンストラクトはステージスコープのシングルトンです。set()を使用して名前空間にキーを書き込みます：

import { RuntimeConfig } from '@my-scope/common-constructs';

const rc = RuntimeConfig.ensure(this);

// Built-in 'connection' namespace (written automatically by generated constructs)
rc.set('connection', 'apis', {
  ...rc.get('connection').apis,
  MyApi: api.url,
});

// Custom namespaces for server-side configuration
rc.set('tables', 'users', {
  tableName: usersTable.tableName,
  tableArn: usersTable.tableArn,
});

synth/デプロイ時に、RuntimeConfigは以下を含むAWS AppConfigアプリケーションを作成します：

各名前空間の設定プロファイル
各プロファイルのJSONデータを含むホスト型設定バージョン
default環境への即座のデプロイメント

Terraformは、3つのcore/runtime-config/*モジュールを通じてランタイム設定を配線します。ルートモジュールで次の順序で宣言します：

core/runtime-config/appconfig — ルートモジュールの上部付近で一度宣言します。AppConfigアプリケーション、環境、デプロイメント戦略、および名前空間ごとに1つの設定プロファイルを作成します。そのapplication_idとapplication_arn出力は、ランタイムでランタイム設定を読み取るすべてのモジュール（エージェント、MCPサーバー、Lambda関数など）に渡されます。
packages/infra/src/main.tf
```
module "runtime_config_appconfig" {
  source = "../../common/terraform/src/core/runtime-config/appconfig"

  application_name = "my-app-runtime-config"
}
```
namespaces変数はデフォルトですべての組み込み名前空間に設定されているため、生成されたモジュールは設定なしで動作します。独自の名前空間を追加するには、組み込みの名前空間と一緒にリストします：
packages/infra/src/main.tf
```
module "runtime_config_appconfig" {
  source = "../../common/terraform/src/core/runtime-config/appconfig"

  application_name = "my-app-runtime-config"
  namespaces       = ["connection", "agentcore", "database", "dynamodb", "tables"]
}
```

core/runtime-config/entry — コントリビューションごとに1回の呼び出し。生成されたAPI、エージェント、MCPモジュールは、URLとARNを公開するために内部的にこれを呼び出します。カスタム設定を公開するには直接呼び出します。

# Automatic — done inside generated modules
module "add_api_url" {
  source = "../../common/terraform/src/core/runtime-config/entry"

  namespace = "connection"
  key       = "apis"
  value     = { "MyApi" = module.my_api.api_url }
}

# Custom namespace for server-side configuration
module "add_table_config" {
  source = "../../common/terraform/src/core/runtime-config/entry"

  namespace = "tables"
  key       = "users"
  value     = {
    tableName = aws_dynamodb_table.users.name
    arn       = aws_dynamodb_table.users.arn
  }
}

core/runtime-config/appconfig-deployment — ルートモジュールの最後に一度宣言し、エントリを提供するすべてのモジュールをカバーするdepends_onを指定します。提供されたエントリを名前空間ごとに1つのJSONに集約し、共有アプリケーションに対してホスト型設定バージョン+デプロイメントを作成します。

module "runtime_config_appconfig_deployment" {
  source = "../../common/terraform/src/core/runtime-config/appconfig-deployment"

  application_id            = module.runtime_config_appconfig.application_id
  environment_id            = module.runtime_config_appconfig.environment_id
  deployment_strategy_id    = module.runtime_config_appconfig.deployment_strategy_id
  configuration_profile_ids = module.runtime_config_appconfig.configuration_profile_ids
  namespaces                = module.runtime_config_appconfig.namespaces

  depends_on = [
    module.my_api,
    module.add_table_config,
    # ...every module that contributes an entry
  ]
}

設定の読み取り

サーバーサイドのコンシューマーは、ランタイムで設定を読み取るためにAppConfigアプリケーションIDとIAM権限が必要です。生成されたコンストラクトはこれを自動的に処理します。

CDK
Terraform

appConfigApplicationIdを使用してAppConfigアプリケーションIDを取得し、grantReadAppConfig()を使用して読み取り権限を付与します：

const rc = RuntimeConfig.ensure(this);

// Get the AppConfig Application ID (lazy token, resolved at synth time)
const appId = rc.appConfigApplicationId;

// Pass it as an environment variable to a Lambda function
const myFunction = new Function(this, 'MyFunction', {
  // ...
  environment: {
    RUNTIME_CONFIG_APP_ID: appId,
  },
});

// Grant the function permission to read from AppConfig
rc.grantReadAppConfig(myFunction);

共有runtime_config_appconfigモジュールのapplication_id出力を参照してAppConfigアプリケーションIDを取得し、適切なIAMポリシーステートメントを追加します：

# Pass the AppConfig Application ID as an environment variable
resource "aws_lambda_function" "my_function" {
  # ...
  environment {
    variables = {
      RUNTIME_CONFIG_APP_ID = module.runtime_config_appconfig.application_id
    }
  }
}

# Grant the function permission to read from AppConfig
resource "aws_iam_policy" "appconfig_read" {
  name = "AppConfigReadPolicy"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "appconfig:StartConfigurationSession",
        "appconfig:GetLatestConfiguration"
      ]
      Resource = ["${module.runtime_config_appconfig.application_arn}/*"]
    }]
  })
}

AppConfig経由のサーバーサイドアクセス

Lambda関数やエージェントなどのサーバーサイドコンシューマーは、AWS Lambda Powertoolsを使用してAWS AppConfigからランタイム設定を取得できます。

生成されたすべてのAPIおよびエージェントコンストラクトは、次のように自動的に設定されます：

RUNTIME_CONFIG_APP_ID環境変数（AppConfigアプリケーションID）
AppConfigから読み取るためのIAM権限

TypeScript
Python

@aws-lambda-powertools/parametersのgetAppConfigを使用します：

import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';

// Retrieve the 'connection' namespace as a parsed JSON object
const config = await getAppConfig('connection', {
  application: process.env.RUNTIME_CONFIG_APP_ID!,
  environment: 'default',
  transform: 'json',
});

// Access values
const apiUrl = config.apis?.MyApi;
const cognitoProps = config.cognitoProps;

カスタム名前空間を取得することもできます：

// Retrieve a custom 'tables' namespace
const tablesConfig = await getAppConfig('tables', {
  application: process.env.RUNTIME_CONFIG_APP_ID!,
  environment: 'default',
  transform: 'json',
});

const usersTableName = tablesConfig.users?.tableName;

aws_lambda_powertools.utilities.parametersのget_app_configを使用します：

import os
from aws_lambda_powertools.utilities import parameters

# Retrieve the 'connection' namespace as a parsed JSON object
config = parameters.get_app_config(
    name="connection",
    environment="default",
    application=os.environ["RUNTIME_CONFIG_APP_ID"],
    transform="json",
)

# Access values
api_url = config.get("apis", {}).get("MyApi")
cognito_props = config.get("cognitoProps")

カスタム名前空間を取得することもできます：

# Retrieve a custom 'tables' namespace
tables_config = parameters.get_app_config(
    name="tables",
    environment="default",
    application=os.environ["RUNTIME_CONFIG_APP_ID"],
    transform="json",
)

users_table_name = tables_config.get("users", {}).get("tableName")

クライアントサイドアクセス

ウェブサイトの場合、connection名前空間はS3バケットにruntime-config.jsonファイルとしてデプロイされます。フロントエンドコードからこれらの値にアクセスする方法の詳細については、Reactウェブサイトのランタイム設定ガイドを参照してください。