런타임 구성

런타임 구성은 Nx Plugin for AWS가 생성된 프로젝트와 컴포넌트 간에 배포 시점 값을 전달하여 서로 연결할 수 있도록 하는 메커니즘입니다. 예를 들어, API를 생성하면 해당 URL이 런타임 구성에 자동으로 등록되어 연결된 웹사이트가 이를 검색할 수 있습니다.

작동 방식

런타임 구성은 네임스페이스로 구성됩니다. 각 네임스페이스는 관련된 구성 값의 논리적 그룹입니다. 배포 시점에 모든 네임스페이스는 AWS AppConfig에 Configuration Profile로 저장됩니다.

생성된 구성 요소에서 사용하는 두 가지 내장 네임스페이스가 있습니다:

connection — 생성된 프로젝트가 서로 연결될 수 있도록 하는 구성:
- API URLs — API 구성 요소에 의해 자동으로 등록됨
- Cognito settings — UserIdentity 구성 요소에 의해 자동으로 등록됨
- Agent runtime ARNs — React 웹사이트를 Strands Agent에 연결할 때 connection 생성기에 의해 추가됨
agentcore — 에이전트 및 MCP 서버를 위한 AgentCore 런타임 ARN. 에이전트/MCP 구성 요소에 의해 자동으로 등록되며 서버 측 검색에 사용됨(A2A를 통한 에이전트 → 에이전트, 에이전트 → MCP 서버).

connection 네임스페이스는 또한 웹사이트의 S3 버킷에 runtime-config.json 파일로 배포되어 클라이언트 측에서 백엔드 리소스를 검색할 수 있도록 합니다. agentcore 네임스페이스는 서버 측 전용(AppConfig를 통해)이므로 웹사이트를 에이전트에 명시적으로 연결하지 않는 한 에이전트 런타임 ARN이 프론트엔드에 노출되지 않습니다.

원하는 만큼 추가 네임스페이스를 정의할 수 있으며, 이는 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 애플리케이션을 생성합니다:

각 네임스페이스에 대한 Configuration Profile
각 프로필의 JSON 데이터가 포함된 Hosted Configuration Version
default 환경으로의 즉시 Deployment

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

그런 다음 모든 네임스페이스 파일에서 AppConfig 리소스를 생성하기 위해 runtime-config/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 Application ID와 IAM 권한이 필요합니다. 생성된 구성 요소는 이를 자동으로 처리합니다.

CDK
Terraform

appConfigApplicationId를 사용하여 AppConfig Application 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 Application 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 Application 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 Website Runtime Configuration 가이드를 참조하세요.