Configurazione Runtime

La configurazione runtime è il meccanismo utilizzato da Nx Plugin for AWS per passare valori di deploy-time tra progetti e componenti generati in modo che possano connettersi tra loro. Ad esempio, quando generi un’API, il suo URL viene automaticamente registrato nella configurazione runtime in modo che un sito web connesso possa scoprirlo.

Come Funziona

La configurazione runtime è organizzata in namespace. Ogni namespace è un raggruppamento logico di valori di configurazione correlati. Al momento del deploy, tutti i namespace vengono memorizzati in AWS AppConfig come Configuration Profile.

Quattro namespace integrati vengono utilizzati dai costrutti generati:

• connection — configurazione che consente ai progetti generati di connettersi tra loro:
  • URL delle API — registrati automaticamente dai costrutti API
  • Impostazioni Cognito — registrate automaticamente dal costrutto UserIdentity
  • ARN runtime degli Agent — aggiunti dal generatore di connessioni quando connetti un sito web React a un Agent
• agentcore — ARN runtime di AgentCore per agent e server MCP. Registrati automaticamente dai costrutti agent/MCP e utilizzati per la scoperta lato server (agent → agent tramite A2A, agent → server MCP).
• dynamodb — nomi delle tabelle, registrati automaticamente dai costrutti delle tabelle DynamoDB e letti dal client della tabella generato.
• database — dettagli di connessione Aurora, registrati automaticamente dai costrutti dei database relazionali e letti dal client del database generato.

Il namespace connection viene anche distribuito come file runtime-config.json nel bucket S3 del tuo sito web, consentendo la scoperta lato client delle risorse backend. Gli altri namespace sono solo lato server (tramite AppConfig), quindi valori come gli ARN runtime degli agent e i nomi delle tabelle non vengono esposti al frontend a meno che tu non connetta esplicitamente un sito web a essi.

Puoi definire tutti i namespace aggiuntivi che desideri, fornendo una comoda alternativa alle variabili d’ambiente per passare valori di deploy-time alle tue funzioni Lambda o ad altre risorse di calcolo.

Infrastruttura

Scrittura della Configurazione

I costrutti generati scrivono automaticamente la configurazione rilevante nel namespace connection. Puoi anche scrivere i tuoi valori in qualsiasi namespace.

CDK

Il costrutto CDK RuntimeConfig è un singleton con scope di stage. Usa set() per scrivere una chiave in un 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,
});

Al momento di synth/deploy, RuntimeConfig crea un’applicazione AWS AppConfig contenente:

• Un Configuration Profile per ogni namespace
• Una Hosted Configuration Version con i dati JSON per ogni profilo
• Un Deployment istantaneo nell’ambiente default

Terraform

Terraform collega la configurazione runtime attraverso tre moduli core/runtime-config/*. Dichiarali nel seguente ordine nel tuo modulo root:

1. core/runtime-config/appconfig — dichiarato una volta, vicino all’inizio del modulo root. Crea l’applicazione AppConfig, l’ambiente, la strategia di deployment e un profilo di configurazione per namespace. I suoi output application_id e application_arn vengono passati in ogni modulo che legge la configurazione runtime a runtime (agent, server MCP, funzioni Lambda, ecc.).

   packages/infra/src/main.tf

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

   La variabile namespaces ha come default tutti i namespace integrati, quindi i moduli generati funzionano senza configurarla. Per aggiungere namespace personalizzati, elencali insieme a quelli integrati:

   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 — un’invocazione per contributo. I moduli API, agent e MCP generati chiamano questo internamente per pubblicare i loro URL e ARN. Chiamalo direttamente per pubblicare configurazioni personalizzate.

   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 — dichiarato una volta, alla fine del modulo root, con depends_on che copre ogni modulo che contribuisce con una voce. Aggrega le voci contribuite in un JSON per namespace e crea la versione di configurazione ospitata + deployment contro l’applicazione condivisa.

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

Lettura della Configurazione

I consumatori lato server necessitano dell’AppConfig Application ID e dei permessi IAM per leggere la configurazione a runtime. I costrutti generati gestiscono questo automaticamente.

CDK

Usa appConfigApplicationId per ottenere l’AppConfig Application ID, e grantReadAppConfig() per concedere i permessi di lettura:

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

Registrazione Automatica

I costrutti API e agent generati fanno questo automaticamente — devi farlo manualmente solo se crei le tue funzioni Lambda o risorse di calcolo che devono leggere la configurazione runtime.

Terraform

Fai riferimento all’output application_id del modulo condiviso runtime_config_appconfig per ottenere l’AppConfig Application ID, e aggiungi le appropriate dichiarazioni di policy 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}/*"]
    }]
  })
}

Registrazione Automatica

I moduli agent e MCP generati accettano input appconfig_application_id + appconfig_application_arn — passa gli output condivisi di runtime_config_appconfig e collegheranno la variabile d’ambiente e i permessi IAM per te. Devi farlo manualmente solo per funzioni Lambda personalizzate o risorse di calcolo.

Sviluppo Locale

Se utilizzi la configurazione runtime con namespace personalizzati (ad es. tables, features), devi solo definire una singola variabile d’ambiente RUNTIME_CONFIG_APP_ID localmente per puntare alla tua applicazione AppConfig distribuita. Questo consente alle tue API o agent locali di recuperare la stessa configurazione dell’ambiente distribuito senza dover replicare tutte le singole variabili d’ambiente.

Accesso Lato Server tramite AppConfig

I consumatori lato server come funzioni Lambda e agent possono recuperare la configurazione runtime da AWS AppConfig utilizzando AWS Lambda Powertools.

Tutti i costrutti API e agent generati sono automaticamente configurati con:

• La variabile d’ambiente RUNTIME_CONFIG_APP_ID (l’AppConfig Application ID)
• Permessi IAM per leggere da AppConfig

TypeScript

Usa getAppConfig da @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;

Puoi anche recuperare namespace personalizzati:

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

Puoi anche recuperare namespace personalizzati:

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

Accesso Lato Client

Per i siti web, il namespace connection viene distribuito come file runtime-config.json nel bucket S3. Consulta la guida Configurazione Runtime del Sito Web React per dettagli su come accedere a questi valori dal tuo codice frontend.