ランタイム設定

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

仕組み

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

組み込みのconnection名前空間は、生成されたプロジェクト間の接続を可能にする設定に使用されます。例えば:

API URL — APIコンストラクトによって自動的に登録されます
Cognito設定 — UserIdentityコンストラクトによって自動的に登録されます
エージェントランタイムARN — エージェントコンストラクトによって自動的に登録されます

connection名前空間は、WebサイトのS3バケットにruntime-config.jsonファイルとしてもデプロイされ、クライアント側でバックエンドリソースを検出できるようにします。

追加の名前空間を必要なだけ定義でき、DynamoDBテーブル名などのデプロイ時の値を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環境への即時デプロイメント

runtime-config/entryモジュールを使用して名前空間にキーを書き込みます:

# Writes to the 'connection' namespace (done automatically by 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
  }
}

次に、runtime-config/appconfigモジュールを宣言して、すべての名前空間ファイルからAppConfigリソースを作成する必要があります:

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

  application_name = "my-app-runtime-config"

  depends_on = [module.add_api_url, module.add_table_config]
}

設定の読み取り

サーバー側のコンシューマーは、実行時に設定を読み取るために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);

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

module "appconfig" {
  source = "../../common/terraform/src/core/runtime-config/appconfig"
  application_name = "my-app-runtime-config"
}

# Pass the AppConfig Application ID as an environment variable
resource "aws_lambda_function" "my_function" {
  # ...
  environment {
    variables = {
      RUNTIME_CONFIG_APP_ID = module.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.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")

クライアント側アクセス

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