Configuración en Tiempo de Ejecución

La configuración en tiempo de ejecución es el mecanismo utilizado por Nx Plugin for AWS para pasar valores en tiempo de despliegue entre proyectos y componentes generados para que puedan conectarse entre sí. Por ejemplo, cuando generas una API, su URL se registra automáticamente en la configuración en tiempo de ejecución para que un sitio web conectado pueda descubrirla.

Cómo Funciona

La configuración en tiempo de ejecución está organizada en espacios de nombres. Cada espacio de nombres es una agrupación lógica de valores de configuración relacionados. En tiempo de despliegue, todos los espacios de nombres se almacenan en AWS AppConfig como Perfiles de Configuración.

Cuatro espacios de nombres integrados son utilizados por los constructos generados:

• connection — configuración que permite a los proyectos generados conectarse entre sí:
  • URLs de API — registradas automáticamente por los constructos de API
  • Configuración de Cognito — registrada automáticamente por el constructo UserIdentity
  • ARNs de tiempo de ejecución de agentes — agregados por el generador de conexión cuando conectas un sitio web React a un agente
• agentcore — ARNs de tiempo de ejecución de AgentCore para agentes y servidores MCP. Registrados automáticamente por los constructos de agente/MCP y utilizados para descubrimiento del lado del servidor (agente → agente vía A2A, agente → servidor MCP).
• dynamodb — nombres de tablas, registrados automáticamente por los constructos de tabla DynamoDB y leídos por el cliente de tabla generado.
• database — detalles de conexión de Aurora, registrados automáticamente por los constructos de base de datos relacional y leídos por el cliente de base de datos generado.

El espacio de nombres connection también se despliega como un archivo runtime-config.json en el bucket S3 de tu sitio web, permitiendo el descubrimiento del lado del cliente de recursos backend. Los otros espacios de nombres son solo del lado del servidor (vía AppConfig), por lo que valores como ARNs de tiempo de ejecución de agentes y nombres de tablas no se exponen al frontend a menos que conectes explícitamente un sitio web a ellos.

Puedes definir tantos espacios de nombres adicionales como desees, proporcionando una alternativa conveniente a las variables de entorno para pasar valores en tiempo de despliegue a tus funciones Lambda u otros recursos de cómputo.

Infraestructura

Escribir Configuración

Los constructos generados escriben automáticamente la configuración relevante en el espacio de nombres connection. También puedes escribir tus propios valores en cualquier espacio de nombres.

CDK

El constructo CDK RuntimeConfig es un singleton con ámbito de stage. Usa set() para escribir una clave en un espacio de nombres:

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

En tiempo de synth/deploy, RuntimeConfig crea una aplicación AWS AppConfig que contiene:

• Un Perfil de Configuración para cada espacio de nombres
• Una Versión de Configuración Alojada con los datos JSON para cada perfil
• Un Despliegue instantáneo al entorno default

Terraform

Terraform conecta la configuración en tiempo de ejecución a través de tres módulos core/runtime-config/*. Declara estos en el siguiente orden en tu módulo raíz:

1. core/runtime-config/appconfig — declarado una vez, cerca del inicio del módulo raíz. Crea la aplicación AppConfig, el entorno, la estrategia de despliegue y un perfil de configuración por espacio de nombres. Sus salidas application_id y application_arn se pasan a cada módulo que lee la configuración en tiempo de ejecución en tiempo de ejecución (agentes, servidores MCP, funciones Lambda, etc.).

   packages/infra/src/main.tf

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

   La variable namespaces tiene como valor predeterminado todos los espacios de nombres integrados, por lo que los módulos generados funcionan sin configurarla. Para agregar espacios de nombres propios, enuméralos junto con los integrados:

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

2. core/runtime-config/entry — una invocación por contribución. Los módulos generados de API, agente y MCP llaman a esto internamente para publicar sus URLs y ARNs. Llámalo directamente para publicar configuración personalizada.

   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 — declarado una vez, al final del módulo raíz, con depends_on cubriendo cada módulo que contribuye una entrada. Agrega las entradas contribuidas en un JSON por espacio de nombres y crea la versión de configuración alojada + despliegue contra la aplicación compartida.

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

Leer Configuración

Los consumidores del lado del servidor necesitan el ID de Aplicación AppConfig y permisos IAM para leer la configuración en tiempo de ejecución. Los constructos generados manejan esto automáticamente.

CDK

Usa appConfigApplicationId para obtener el ID de Aplicación AppConfig, y grantReadAppConfig() para otorgar permisos de lectura:

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

Registro Automático

Los constructos generados de API y agente hacen esto automáticamente — solo necesitas hacer esto manualmente si creas tus propias funciones Lambda o recursos de cómputo que necesitan leer la configuración en tiempo de ejecución.

Terraform

Referencia la salida application_id del módulo compartido runtime_config_appconfig para obtener el ID de Aplicación AppConfig, y agrega las declaraciones de política IAM apropiadas:

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

Registro Automático

Los módulos generados de agente y MCP aceptan entradas appconfig_application_id + appconfig_application_arn — pasa las salidas compartidas de runtime_config_appconfig y ellos configuran la variable de entorno y los permisos IAM por ti. Solo necesitas hacer esto manualmente para funciones Lambda personalizadas o recursos de cómputo.

Desarrollo Local

Si usas configuración en tiempo de ejecución con espacios de nombres personalizados (por ejemplo, tables, features), solo necesitas definir una única variable de entorno RUNTIME_CONFIG_APP_ID localmente para apuntar a tu aplicación AppConfig desplegada. Esto permite que tus APIs o agentes locales recuperen la misma configuración que el entorno desplegado sin necesidad de replicar todas las variables de entorno individuales.

Acceso del Lado del Servidor vía AppConfig

Los consumidores del lado del servidor como funciones Lambda y agentes pueden recuperar la configuración en tiempo de ejecución desde AWS AppConfig usando AWS Lambda Powertools.

Todos los constructos generados de API y agente se configuran automáticamente con:

• La variable de entorno RUNTIME_CONFIG_APP_ID (el ID de Aplicación AppConfig)
• Permisos IAM para leer desde AppConfig

TypeScript

Usa getAppConfig de @aws-lambda-powertools/parameters:

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;

También puedes recuperar espacios de nombres personalizados:

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

Usa get_app_config de aws_lambda_powertools.utilities.parameters:

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

También puedes recuperar espacios de nombres personalizados:

# 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")

Acceso del Lado del Cliente

Para sitios web, el espacio de nombres connection se despliega como un archivo runtime-config.json en el bucket S3. Consulta la guía Configuración en Tiempo de Ejecución del Sitio Web React para detalles sobre cómo acceder a estos valores desde tu código frontend.