Configuração de Runtime

A configuração de runtime é o mecanismo usado pelo Nx Plugin for AWS para passar valores de tempo de implantação entre projetos e componentes gerados para que eles possam se conectar uns aos outros. Por exemplo, quando você gera uma API, sua URL é automaticamente registrada na configuração de runtime para que um site conectado possa descobri-la.

Como Funciona

A configuração de runtime é organizada em namespaces. Cada namespace é um agrupamento lógico de valores de configuração relacionados. No momento da implantação, todos os namespaces são armazenados no AWS AppConfig como Configuration Profiles.

Quatro namespaces integrados são usados por constructs gerados:

• connection — configuração que permite que projetos gerados se conectem uns aos outros:
  • URLs de API — registradas automaticamente por constructs de API
  • Configurações do Cognito — registradas automaticamente pelo construct UserIdentity
  • ARNs de runtime de Agent — adicionados pelo gerador de conexão quando você conecta um site React a um Agent
• agentcore — ARNs de runtime do AgentCore para agents e servidores MCP. Registrados automaticamente pelos constructs de agent/MCP e usados para descoberta do lado do servidor (agent → agent via A2A, agent → servidor MCP).
• dynamodb — nomes de tabelas, registrados automaticamente por constructs de tabela DynamoDB e lidos pelo cliente de tabela gerado.
• database — detalhes de conexão do Aurora, registrados automaticamente por constructs de banco de dados relacional e lidos pelo cliente de banco de dados gerado.

O namespace connection também é implantado como um arquivo runtime-config.json no bucket S3 do seu site, permitindo a descoberta de recursos de backend do lado do cliente. Os outros namespaces são apenas do lado do servidor (via AppConfig), portanto valores como ARNs de runtime de agent e nomes de tabelas não são expostos ao frontend, a menos que você conecte explicitamente um site a eles.

Você pode definir quantos namespaces adicionais desejar, fornecendo uma alternativa conveniente às variáveis de ambiente para passar valores de tempo de implantação para suas funções Lambda ou outros recursos de computação.

Infraestrutura

Escrevendo Configuração

Constructs gerados escrevem automaticamente a configuração relevante no namespace connection. Você também pode escrever seus próprios valores em qualquer namespace.

CDK

O construct CDK RuntimeConfig é um singleton com escopo de stage. Use set() para escrever uma chave em um namespace:

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

No momento de synth/deploy, RuntimeConfig cria uma aplicação AWS AppConfig contendo:

• Um Configuration Profile para cada namespace
• Uma Hosted Configuration Version com os dados JSON para cada perfil
• Uma Deployment instantânea para o ambiente default

Terraform

O Terraform conecta a configuração de runtime através de três módulos core/runtime-config/*. Declare-os na seguinte ordem no seu módulo raiz:

1. core/runtime-config/appconfig — declarado uma vez, próximo ao topo do módulo raiz. Cria a aplicação AppConfig, ambiente, estratégia de implantação e um perfil de configuração por namespace. Suas saídas application_id e application_arn são passadas para cada módulo que lê a configuração de runtime em tempo de execução (agents, servidores MCP, funções 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"
   }

   A variável namespaces tem como padrão todos os namespaces integrados, então os módulos gerados funcionam sem configurá-la. Para adicionar seus próprios namespaces, liste-os junto com os 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 — uma invocação por contribuição. Módulos gerados de API, agent e MCP chamam isso internamente para publicar suas URLs e ARNs. Chame-o diretamente para publicar configuração 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 uma vez, no final do módulo raiz, com depends_on cobrindo cada módulo que contribui com uma entrada. Agrega as entradas contribuídas em um JSON por namespace e cria a versão de configuração hospedada + implantação contra a aplicação compartilhada.

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

Lendo Configuração

Consumidores do lado do servidor precisam do AppConfig Application ID e permissões IAM para ler a configuração em tempo de execução. Constructs gerados lidam com isso automaticamente.

CDK

Use appConfigApplicationId para obter o AppConfig Application ID, e grantReadAppConfig() para conceder permissões de leitura:

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

Constructs gerados de API e agent fazem isso automaticamente — você só precisa fazer isso manualmente se criar suas próprias funções Lambda ou recursos de computação que precisam ler a configuração de runtime.

Terraform

Referencie a saída application_id do módulo compartilhado runtime_config_appconfig para obter o AppConfig Application ID, e adicione as declarações de política IAM apropriadas:

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

Módulos gerados de agent e MCP aceitam entradas appconfig_application_id + appconfig_application_arn — passe as saídas compartilhadas de runtime_config_appconfig e eles conectam a variável de ambiente e as permissões IAM para você. Você só precisa fazer isso manualmente para funções Lambda personalizadas ou recursos de computação.

Desenvolvimento Local

Se você usar configuração de runtime com namespaces personalizados (por exemplo, tables, features), você só precisa definir uma única variável de ambiente RUNTIME_CONFIG_APP_ID localmente para apontar para sua aplicação AppConfig implantada. Isso permite que suas APIs ou agents locais recuperem a mesma configuração do ambiente implantado sem precisar replicar todas as variáveis de ambiente individuais.

Acesso do Lado do Servidor via AppConfig

Consumidores do lado do servidor, como funções Lambda e agents, podem recuperar a configuração de runtime do AWS AppConfig usando AWS Lambda Powertools.

Todos os constructs gerados de API e agent são automaticamente configurados com:

• A variável de ambiente RUNTIME_CONFIG_APP_ID (o AppConfig Application ID)
• Permissões IAM para ler do AppConfig

TypeScript

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

Você também pode recuperar namespaces 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

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

Você também pode recuperar namespaces 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")

Acesso do Lado do Cliente

Para sites, o namespace connection é implantado como um arquivo runtime-config.json no bucket S3. Consulte o guia Configuração de Runtime do Site React para detalhes sobre como acessar esses valores do seu código frontend.