콘텐츠로 이동
@aws/nx-plugin
Blog

런타임 구성

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

작동 방식

섹션 제목: “작동 방식”

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

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

  • connection — 생성된 프로젝트가 서로 연결될 수 있도록 하는 구성:
    • API URL — API 구성 요소에 의해 자동으로 등록됨
    • Cognito 설정 — UserIdentity 구성 요소에 의해 자동으로 등록됨
    • Agent 런타임 ARN — React 웹사이트를 Agent에 연결할 때 연결 생성기에 의해 추가됨
  • agentcore — 에이전트 및 MCP 서버를 위한 AgentCore 런타임 ARN. 에이전트/MCP 구성 요소에 의해 자동으로 등록되며 서버 측 검색(A2A를 통한 에이전트 → 에이전트, 에이전트 → MCP 서버)에 사용됩니다.
  • dynamodb — 테이블 이름, DynamoDB 테이블 구성 요소에 의해 자동으로 등록되며 생성된 테이블 클라이언트에 의해 읽힙니다.
  • database — Aurora 연결 세부 정보, 관계형 데이터베이스 구성 요소에 의해 자동으로 등록되며 생성된 데이터베이스 클라이언트에 의해 읽힙니다.

connection 네임스페이스는 웹사이트의 S3 버킷에 runtime-config.json 파일로도 배포되어 백엔드 리소스의 클라이언트 측 검색을 가능하게 합니다. 다른 네임스페이스는 서버 측 전용(AppConfig를 통해)이므로 웹사이트를 명시적으로 연결하지 않는 한 에이전트 런타임 ARN 및 테이블 이름과 같은 값이 프론트엔드에 노출되지 않습니다.

원하는 만큼 추가 네임스페이스를 정의할 수 있으며, 이는 배포 시점 값을 Lambda 함수나 기타 컴퓨팅 리소스에 전달하기 위한 환경 변수의 편리한 대안을 제공합니다.

Diagram

인프라

섹션 제목: “인프라”

구성 작성

섹션 제목: “구성 작성”

생성된 구성 요소는 자동으로 관련 구성을 connection 네임스페이스에 작성합니다. 모든 네임스페이스에 자신의 값을 작성할 수도 있습니다.

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

합성/배포 시점에 RuntimeConfig는 다음을 포함하는 AWS AppConfig 애플리케이션을 생성합니다:

  • 각 네임스페이스에 대한 구성 프로필
  • 각 프로필의 JSON 데이터가 포함된 호스팅 구성 버전
  • default 환경에 대한 즉시 배포

구성 읽기

섹션 제목: “구성 읽기”

서버 측 소비자는 런타임에 구성을 읽기 위해 AppConfig 애플리케이션 ID와 IAM 권한이 필요합니다. 생성된 구성 요소는 이를 자동으로 처리합니다.

appConfigApplicationId를 사용하여 AppConfig 애플리케이션 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);

AppConfig를 통한 서버 측 액세스

섹션 제목: “AppConfig를 통한 서버 측 액세스”

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

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

  • RUNTIME_CONFIG_APP_ID 환경 변수(AppConfig 애플리케이션 ID)
  • AppConfig에서 읽을 수 있는 IAM 권한

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

클라이언트 측 액세스

섹션 제목: “클라이언트 측 액세스”

웹사이트의 경우 connection 네임스페이스는 S3 버킷에 runtime-config.json 파일로 배포됩니다. 프론트엔드 코드에서 이러한 값에 액세스하는 방법에 대한 자세한 내용은 React 웹사이트 런타임 구성 가이드를 참조하세요.