런타임 구성

런타임 구성은 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

RuntimeConfig CDK 구성 요소는 스테이지 범위의 싱글톤입니다. set()을 사용하여 네임스페이스에 키를 작성합니다:

packages/infra/src/stacks/application-stack.ts

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

Terraform

Terraform은 세 개의 core/runtime-config/* 모듈을 통해 런타임 구성을 연결합니다. 루트 모듈에서 다음 순서로 선언하세요:

1. core/runtime-config/appconfig — 루트 모듈의 상단 근처에 한 번 선언합니다. AppConfig 애플리케이션, 환경, 배포 전략 및 네임스페이스당 하나의 구성 프로필을 생성합니다. 이 모듈의 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"
   }

2. core/runtime-config/entry — 기여당 한 번 호출합니다. 생성된 API, 에이전트 및 MCP 모듈은 내부적으로 이를 호출하여 URL과 ARN을 게시합니다. 사용자 정의 구성을 게시하려면 직접 호출하세요.

   packages/infra/src/main.tf

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

3. core/runtime-config/appconfig-deployment — 루트 모듈의 끝에 한 번 선언하며, 항목을 기여하는 모든 모듈을 포함하는 depends_on을 사용합니다. 기여된 항목을 네임스페이스당 하나의 JSON으로 집계하고 공유 애플리케이션에 대해 호스팅된 구성 버전 + 배포를 생성합니다.

   packages/infra/src/main.tf

   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 Application ID와 IAM 권한이 필요합니다. 생성된 구성 요소는 이를 자동으로 처리합니다.

CDK

appConfigApplicationId를 사용하여 AppConfig Application ID를 가져오고, grantReadAppConfig()를 사용하여 읽기 권한을 부여합니다:

packages/infra/src/stacks/application-stack.ts

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);

자동 등록

생성된 API 및 에이전트 구성 요소는 이를 자동으로 수행합니다 — 런타임 구성을 읽어야 하는 자체 Lambda 함수나 컴퓨팅 리소스를 생성하는 경우에만 수동으로 수행하면 됩니다.

Terraform

공유 runtime_config_appconfig 모듈의 application_id 출력을 참조하여 AppConfig Application ID를 가져오고, 적절한 IAM 정책 문을 추가합니다:

packages/infra/src/main.tf

# 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}/*"]
    }]
  })
}

자동 등록

생성된 에이전트 및 MCP 모듈은 appconfig_application_id + appconfig_application_arn 입력을 받습니다 — 공유 runtime_config_appconfig 출력을 전달하면 환경 변수와 IAM 권한을 자동으로 연결합니다. 사용자 정의 Lambda 함수나 컴퓨팅 리소스에 대해서만 수동으로 수행하면 됩니다.

로컬 개발

사용자 정의 네임스페이스(예: tables, features)와 함께 런타임 구성을 사용하는 경우, 배포된 AppConfig 애플리케이션을 가리키도록 로컬에서 단일 RUNTIME_CONFIG_APP_ID 환경 변수만 정의하면 됩니다. 이를 통해 로컬 API나 에이전트가 모든 개별 환경 변수를 복제할 필요 없이 배포된 환경과 동일한 구성을 검색할 수 있습니다.

AppConfig를 통한 서버 측 액세스

Lambda 함수 및 에이전트와 같은 서버 측 소비자는 AWS Lambda Powertools를 사용하여 AWS AppConfig에서 런타임 구성을 검색할 수 있습니다.

생성된 모든 API 및 에이전트 구성 요소는 다음과 함께 자동으로 구성됩니다:

• RUNTIME_CONFIG_APP_ID 환경 변수 (AppConfig Application ID)
• AppConfig에서 읽을 수 있는 IAM 권한

TypeScript

@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;

Python

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 가이드를 참조하세요.