Configuration d'exécution

La configuration d’exécution est le mécanisme utilisé par Nx Plugin for AWS pour transmettre des valeurs au moment du 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.

Comment ça fonctionne

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

Deux namespaces intégrés sont utilisés par les constructs générés :

• connection — configuration qui permet aux projets générés de se connecter entre eux :
  • URLs d’API — enregistrées automatiquement par les constructs d’API
  • Paramètres Cognito — enregistrés automatiquement par le construct UserIdentity
  • ARNs d’exécution des agents — ajoutés par le générateur de connexion lorsque vous connectez un site web React à un Strands Agent
• agentcore — ARNs d’exécution AgentCore pour les agents et les serveurs MCP. Enregistrés automatiquement par les constructs d’agents/MCP et utilisés pour la découverte côté serveur (agent → agent via A2A, agent → serveur MCP).

Le namespace 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. Le namespace agentcore est uniquement côté serveur (via AppConfig), de sorte que les ARNs d’exécution des agents ne sont pas exposés au frontend à moins que vous ne connectiez explicitement un site web à un agent.

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

Infrastructure

Écriture de la configuration

Les constructs générés écrivent automatiquement la configuration pertinente dans le namespace connection. Vous pouvez également écrire vos propres valeurs dans n’importe quel namespace.

CDK

Le construct CDK RuntimeConfig est un singleton à portée de stage. Utilisez set() pour écrire une clé dans 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,
});

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

• Un Configuration Profile pour chaque namespace
• Une Hosted Configuration Version avec les données JSON pour chaque profil
• Un Deployment instantané vers l’environnement default

Terraform

Utilisez le module runtime-config/entry pour écrire une clé dans un namespace :

packages/infra/src/main.tf

# Writes to the 'connection' namespace (done automatically by 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
  }
}

Vous devez ensuite déclarer le module runtime-config/appconfig pour créer les ressources AppConfig à partir de tous les fichiers de namespace :

module "appconfig" {
  source = "../../common/terraform/src/core/runtime-config/appconfig"

  application_name = "my-app-runtime-config"

  depends_on = [module.add_api_url, module.add_table_config]
}

Enregistrement automatique

Chaque construct généré (APIs, agents) crée sa propre instance de module appconfig autonome. Elles sont toutes identiques — elles lisent toutes le même ensemble de fichiers de namespace et produisent la même application AppConfig. Cela garantit que chaque module est déployable indépendamment.

Lecture de la configuration

Les consommateurs côté serveur ont besoin de l’AppConfig Application ID et des permissions IAM pour lire la configuration à l’exécution. Les constructs générés gèrent cela automatiquement.

CDK

Utilisez appConfigApplicationId pour obtenir l’AppConfig Application ID, 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 constructs d’API et d’agents générés 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 appconfig pour obtenir l’AppConfig Application ID, et ajoutez les déclarations de politique IAM appropriées :

packages/infra/src/main.tf

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

# Pass the AppConfig Application ID as an environment variable
resource "aws_lambda_function" "my_function" {
  # ...
  environment {
    variables = {
      RUNTIME_CONFIG_APP_ID = module.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.appconfig.application_arn}/*"]
    }]
  })
}

Enregistrement automatique

Les modules d’API et d’agents générés gèrent cela automatiquement — chacun crée sa propre instance de module appconfig et configure la variable d’environnement et les permissions IAM. Vous n’avez besoin de le faire manuellement que pour les fonctions Lambda ou ressources de calcul personnalisées.

Développement local

Si vous utilisez la configuration d’exécution avec des namespaces 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 APIs 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.

Tous les constructs d’API et d’agents générés sont automatiquement configurés avec :

• La variable d’environnement RUNTIME_CONFIG_APP_ID (l’AppConfig Application ID)
• 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 namespaces 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 namespaces 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, le namespace 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.