Fichier de configuration CLI AWS SAM

L'interface de ligne de AWS Serverless Application Model commande (AWS SAMCLI) prend en charge un fichier de configuration au niveau du projet que vous pouvez utiliser pour configurer les valeurs des paramètres de AWS SAMCLI commande.

Pour obtenir de la documentation sur la création et l'utilisation de fichiers de configuration, veuillez consulter la section Configuration de la CLI  AWS SAM.

Paramètres du fichier de configuration par défaut

AWS SAM utilise les paramètres de fichier de configuration par défaut suivants :

• Nom : samconfig.

• Emplacement : à la racine de votre projet. Il s'agit du même emplacement que celui de votre fichier template.yaml.

• Format : TOML. Pour en savoir plus, veuillez consulter la section TOML dans la documentation TOML.

Voici un exemple de structure de projet qui inclut le nom et l'emplacement du fichier de configuration par défaut :

sam-app
├── README.md
├── __init__.py
├── events
├── hello_world
├── samconfig.toml
├── template.yaml
└── tests

Voici un exemple de fichier de samconfig.toml :

...
version = 0.1

[default]
[default.global]
[default.global.parameters]
stack_name = "sam-app"

[default.build.parameters]
cached = true
parallel = true

[default.deploy.parameters]
capabilities = "CAPABILITY_IAM"
confirm_changeset = true
resolve_s3 = true

[default.sync.parameters]
watch = true

[default.local_start_api.parameters]
warm_containers = "EAGER"

[prod]
[prod.sync]
[prod.sync.parameters]
watch = false

Formats de fichiers de configuration pris en charge

Les formats TOML et [YAML|YML] sont pris en charge. Consultez la syntaxe de base suivante :

TOML

version = 0.1
[environment]
[environment.command]
[environment.command.parameters]
option = parameter value

YAML

version: 0.1
environment:
  command:
    parameters:
      option: parameter value

Spécifier un fichier de configuration

Par défaut, la CLI  AWS SAM recherche un fichier de configuration dans l'ordre suivant :

1. Fichier de configuration personnalisé : si vous utilisez l'option --config-file pour spécifier un nom et un emplacement de fichier, la CLI  AWS SAM recherche d'abord ce fichier.

2. Fichier samconfig.toml par défaut : il s'agit du nom et du format du fichier de configuration par défaut, situé à la racine de votre projet. Si vous ne spécifiez pas de fichier de configuration personnalisé, la CLI  AWS SAM recherche ensuite ce fichier.

3. Fichier samconfig.[yaml|yml] : si le fichier samconfig.toml n'existe pas à la racine de votre projet, la CLI  AWS SAM recherche ce fichier.

Voici un exemple de spécification d'un fichier de configuration personnalisé à l'aide de l'option --config-file :

$ sam deploy --config-file myconfig.yaml

Note

Le --config-file paramètre doit être relatif à l'emplacement du fichier AWS SAM modèle, car il AWS SAMCLI doit déterminer le contexte dans lequel la configuration est appliquée. Le samconfig.toml fichier gère les paramètres de configuration de votre version de AWS SAMCLI, et la CLI recherche le samconfig.toml fichier (ou le paramètre du fichier de configuration remplacé) dans le dossier relatif du template.yaml fichier.

Principes de base relatifs au fichier de configuration

Environnement

Un environnement est un identifiant nommé qui contient un ensemble unique de paramètres de configuration. Vous pouvez avoir plusieurs environnements dans une seule AWS SAM application.

Le nom de l'environnement par défaut est default.

Utilisez l' AWS SAMCLI--config-envoption pour spécifier l'environnement à utiliser.

Commande

La commande est la commande CLI  AWS SAM pour laquelle les valeurs des paramètres sont spécifiées.

Pour spécifier les valeurs des paramètres pour toutes les commandes, utilisez l'identificateur global.

Lorsque vous faites référence à une commande CLI  AWS SAM, remplacez les espaces (–) et les traits d'union ( ) par des traits de soulignement (_). Voir les exemples suivants :

• build

• local_invoke

• local_start_api

Parameters

Les paramètres sont spécifiés sous forme de paires clé-valeur.

• La clé est le nom de l'option de commande CLI  AWS SAM.

• La valeur est celle à spécifier.

Lorsque vous spécifiez des clés, utilisez le nom complet de l'option de commande et remplacez les traits d'union (–) par des traits de soulignement (_). Voici quelques exemples :

• region

• stack_name

• template_file

Règles de valeur des paramètres

TOML

• Les valeurs booléennes peuvent être true ou false. Par exemple, confirm_changeset = true.

• Pour les valeurs de chaîne de caractères, utilisez des guillemets (""). Par exemple, region = "us-west-2".

• Pour les valeurs de liste, utilisez des guillemets ("") et séparez chaque valeur par une espace ( ). Par exemple : capabilities = "CAPABILITY_IAM CAPABILITY_NAMED_IAM".

• Pour la valeur contenant une liste de paires clé-valeur, les paires sont délimitées par des espaces ( ), et la valeur de chaque paire est entourée de guillemets (\" \") encodés. Par exemple, tags = "project=\"my-application\" stage=\"production\"".

• Pour les valeurs de paramètres qui peuvent être spécifiés plusieurs fois, la valeur est un tableau d'arguments. Par exemple : image_repositories = ["my-function-1=image-repo-1", "my-function-2=image-repo-2"].

YAML

• Les valeurs booléennes peuvent être true ou false. Par exemple, confirm_changeset: true.

• Pour les entrées contenant une seule valeur de chaîne de caractères, les guillemets ("") sont facultatifs. Par exemple, region: us-west-2. Cela inclut les entrées qui contiennent plusieurs paires clé-valeur fournies sous la forme d'une seule chaîne de caractères. Voici un exemple :

  $ sam deploy --tags "foo=bar hello=world"

  default:
    deploy:
      parameters:
        tags: foo=bar hello=world

• Pour les entrées qui contiennent une liste de valeurs ou pour les entrées qui peuvent être utilisées plusieurs fois au sein d'une même commande, spécifiez-les sous forme de liste de chaînes de caractères.

  Voici un exemple :

  $ sam remote invoke --parameter "InvocationType=Event" --parameter "LogType=None"

  default:
    remote_invoke:
      parameters:
          parameter:
          - InvocationType=Event
          - LogType=None

Ordre de priorité de configuration

Lors de la configuration des valeurs, l'ordre de priorité est le suivant :

• Les valeurs des paramètres que vous fournissez à la ligne de commande ont la priorité sur les valeurs correspondantes dans le fichier de configuration et la section Parameters du fichier modèle.

• Si l'option --parameter-overrides est utilisée sur la ligne de commande ou dans votre fichier de configuration avec la clé parameter_overrides, ses valeurs ont la priorité sur les valeurs de la section Parameters du fichier modèle.

• Dans votre fichier de configuration, les entrées fournies pour une commande spécifique sont prioritaires sur les entrées globales. Dans l'exemple suivant, la commande sam deploy utilisera le nom de pile my-app-stack.

  TOML

  [default.global.parameters]
  stack_name = "common-stack"
  
  [default.deploy.parameters]
  stack_name = "my-app-stack"

  YAML

  default:
    global:
      parameters:
        stack_name: common-stack
    deploy:
      parameters:
        stack_name: my-app-stack

Création et modification de fichiers de configuration

Création de fichiers de configuration

Lorsque vous créez une application à l'aide de sam init, un fichier samconfig.toml par défaut est créé. Vous pouvez également créer manuellement votre fichier de configuration.

Modification des fichiers de configuration

Vous pouvez modifier manuellement vos fichiers de configuration. De plus, lors de tout flux interactif de la CLI  AWS SAM, les valeurs configurées seront affichées entre crochets ([ ]). Si vous modifiez ces valeurs, la CLI  AWS SAM mettra à jour votre fichier de configuration.

Vous trouverez ci-dessous un exemple du flux interactif utilisant la commande sam deploy --guided :

$ sam deploy --guided

Configuring SAM deploy
======================

    Looking for config file [samconfig.toml] :  Found
    Reading default arguments  :  Success

    Setting default arguments for 'sam deploy'
    =========================================
    Stack Name [sam-app]: ENTER
    AWS Region [us-west-2]: ENTER
    #Shows you resources changes to be deployed and require a 'Y' to initiate deploy
    Confirm changes before deploy [Y/n]: n
    #SAM needs permission to be able to create roles to connect to the resources in your template
    Allow SAM CLI IAM role creation [Y/n]: ENTER
    #Preserves the state of previously provisioned resources when an operation fails
    Disable rollback [y/N]: ENTER
    HelloWorldFunction may not have authorization defined, Is this okay? [y/N]: y
    Save arguments to configuration file [Y/n]: ENTER
    SAM configuration file [samconfig.toml]: ENTER
    SAM configuration environment [default]: ENTER

Lorsque vous modifiez votre fichier de configuration, la CLI  AWS SAM traite les valeurs globales de la manière suivante :

• Si la valeur du paramètre existe dans la section global de votre fichier de configuration, la CLI  AWS SAM n'écrit pas la valeur dans la section de commande spécifique.

• Si la valeur du paramètre existe à la fois dans les sections de commande global et dans des sections de commande spécifiques, la CLI  AWS SAM supprime l'entrée spécifique au profit de la valeur globale.