Configuration d'exécution

La configuration d’exécution est le mécanisme utilisé par Nx Plugin for AWS pour transmettre des valeurs de déploiement entre les projets et composants générés afin qu’ils puissent se connecter les uns aux autres. Par exemple, lorsque vous générez une API, son URL est automatiquement enregistrée dans la configuration d’exécution afin qu’un site web connecté puisse la découvrir.

Fonctionnement

La configuration d’exécution est organisée en espaces de noms. Chaque espace de noms est un regroupement logique de valeurs de configuration associées. Au moment du déploiement, tous les espaces de noms sont stockés dans AWS AppConfig en tant que profils de configuration.

Quatre espaces de noms intégrés sont utilisés par les constructions générées :

• connection — configuration qui permet aux projets générés de se connecter les uns aux autres :
  • URL d’API — enregistrées automatiquement par les constructions d’API
  • Paramètres Cognito — enregistrés automatiquement par la construction UserIdentity
  • ARN d’exécution d’agent — ajoutés par le générateur de connexion lorsque vous connectez un site web React à un agent
• agentcore — ARN d’exécution AgentCore pour les agents et les serveurs MCP. Enregistrés automatiquement par les constructions agent/MCP et utilisés pour la découverte côté serveur (agent → agent via A2A, agent → serveur MCP).
• dynamodb — noms de tables, enregistrés automatiquement par les constructions de tables DynamoDB et lus par le client de table généré.
• database — détails de connexion Aurora, enregistrés automatiquement par les constructions de bases de données relationnelles et lus par le client de base de données généré.

L’espace de noms connection est également déployé sous forme de fichier runtime-config.json dans le bucket S3 de votre site web, permettant la découverte côté client des ressources backend. Les autres espaces de noms sont uniquement côté serveur (via AppConfig), de sorte que les valeurs telles que les ARN d’exécution d’agent et les noms de tables ne sont pas exposées au frontend à moins que vous ne connectiez explicitement un site web à eux.

Vous pouvez définir autant d’espaces de noms supplémentaires que vous le souhaitez, offrant une alternative pratique aux variables d’environnement pour transmettre des valeurs de déploiement à vos fonctions Lambda ou autres ressources de calcul.

Infrastructure

Écriture de la configuration

Les constructions générées écrivent automatiquement la configuration pertinente dans l’espace de noms connection. Vous pouvez également écrire vos propres valeurs dans n’importe quel espace de noms.

CDK

La construction CDK RuntimeConfig est un singleton limité à la phase. Utilisez set() pour écrire une clé dans un espace de noms :

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

Au moment de la synthèse/du déploiement, RuntimeConfig crée une application AWS AppConfig contenant :

• Un profil de configuration pour chaque espace de noms
• Une version de configuration hébergée avec les données JSON pour chaque profil
• Un déploiement instantané vers l’environnement default

Terraform

Terraform connecte la configuration d’exécution à travers trois modules core/runtime-config/*. Déclarez-les dans l’ordre suivant dans votre module racine :

1. core/runtime-config/appconfig — déclaré une fois, près du haut du module racine. Crée l’application AppConfig, l’environnement, la stratégie de déploiement et un profil de configuration par espace de noms. Ses sorties application_id et application_arn sont transmises à chaque module qui lit la configuration d’exécution au moment de l’exécution (agents, serveurs MCP, fonctions 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 est par défaut définie sur tous les espaces de noms intégrés, de sorte que les modules générés fonctionnent sans la configurer. Pour ajouter vos propres espaces de noms, listez-les aux côtés des espaces de noms intégrés :

   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 — une invocation par contribution. Les modules API, agent et MCP générés appellent ceci en interne pour publier leurs URL et ARN. Appelez-le directement pour publier une configuration personnalisée.

   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 — déclaré une fois, à la fin du module racine, avec depends_on couvrant chaque module qui contribue une entrée. Agrège les entrées contribuées en un JSON par espace de noms et crée la version de configuration hébergée + le déploiement contre l’application partagée.

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

Lecture de la configuration

Les consommateurs côté serveur ont besoin de l’ID d’application AppConfig et des permissions IAM pour lire la configuration au moment de l’exécution. Les constructions générées gèrent cela automatiquement.

CDK

Utilisez appConfigApplicationId pour obtenir l’ID d’application AppConfig, et grantReadAppConfig() pour accorder les permissions de lecture :

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

Enregistrement automatique

Les constructions d’API et d’agent générées font cela automatiquement — vous n’avez besoin de le faire manuellement que si vous créez vos propres fonctions Lambda ou ressources de calcul qui doivent lire la configuration d’exécution.

Terraform

Référencez la sortie application_id du module partagé runtime_config_appconfig pour obtenir l’ID d’application AppConfig, et ajoutez les déclarations de politique IAM appropriées :

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

Enregistrement automatique

Les modules agent et MCP générés acceptent les entrées appconfig_application_id + appconfig_application_arn — transmettez les sorties partagées runtime_config_appconfig et ils configurent la variable d’environnement et les permissions IAM pour vous. Vous n’avez besoin de le faire manuellement que pour les fonctions Lambda personnalisées ou les ressources de calcul.

Développement local

Si vous utilisez la configuration d’exécution avec des espaces de noms personnalisés (par exemple tables, features), vous n’avez besoin de définir qu’une seule variable d’environnement RUNTIME_CONFIG_APP_ID localement pour pointer vers votre application AppConfig déployée. Cela permet à vos API ou agents locaux de récupérer la même configuration que l’environnement déployé sans avoir besoin de répliquer toutes les variables d’environnement individuelles.

Accès côté serveur via AppConfig

Les consommateurs côté serveur tels que les fonctions Lambda et les agents peuvent récupérer la configuration d’exécution depuis AWS AppConfig en utilisant AWS Lambda Powertools.

Toutes les constructions d’API et d’agent générées sont automatiquement configurées avec :

• La variable d’environnement RUNTIME_CONFIG_APP_ID (l’ID d’application AppConfig)
• Les permissions IAM pour lire depuis AppConfig

TypeScript

Utilisez getAppConfig depuis @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;

Vous pouvez également récupérer des espaces de noms personnalisés :

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

Utilisez get_app_config depuis 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")

Vous pouvez également récupérer des espaces de noms personnalisés :

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

Accès côté client

Pour les sites web, l’espace de noms connection est déployé sous forme de fichier runtime-config.json dans le bucket S3. Consultez le guide Configuration d’exécution du site web React pour plus de détails sur la façon d’accéder à ces valeurs depuis votre code frontend.