Archivo de configuración de la CLI de AWS SAM

La interfaz de línea de comandos de AWS Serverless Application Model (la CLI de AWS SAM) admite un archivo de configuración a nivel de proyecto que puede usar para configurar los valores de los parámetros de comando de la CLI de AWS SAM.

Para obtener documentación sobre cómo crear y usar archivos de configuración, consulte Configuración de la AWS SAM de CLI.

Parámetros predeterminados del archivo de configuración

AWS SAM utiliza la configuración predeterminada del archivo de configuración:

• Nombre: samconfig.

• Ubicación: en la raíz del proyecto. Es la misma ubicación que el archivo template.yaml.

• Format: TOML Para obtener más información, consulte TOML en la TOMLdocumentación.

A continuación se muestra un ejemplo de estructura de proyecto que incluye el nombre y la ubicación por defecto del archivo de configuración:

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

A continuación se muestra un ejemplo de un archivo 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

Formatos de archivo de configuración admitidos

Los formatos admitidos son TOML y [YAML|YML]. Consulte la siguiente sintaxis básica:

TOML

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

YAML

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

Especificar un archivo de configuración

De forma predeterminada, la CLI de AWS SAM busca un archivo de configuración en el siguiente orden:

1. Archivo de configuración personalizado: si utiliza la opción --config-file para especificar un nombre y una ubicación de archivo, la CLI de AWS SAM busca primero este archivo.

2. Archivo predeterminado samconfig.toml: este es el nombre y el formato del archivo de configuración predeterminados y se encuentra en la raíz del proyecto. Si no especifica un archivo de configuración personalizado, la CLI de AWS SAM buscará este archivo a continuación.

3. Archivo samconfig.[yaml|yml]: si samconfig.toml no existe en la raíz del proyecto, AWS SAM CLI busca este archivo.

El siguiente es un ejemplo de cómo se especifica un archivo de configuración personalizado mediante la opción --config-file:

$ sam deploy --config-file myconfig.yaml

Fundamentos de los archivos de configuración

Entorno

Un entorno es un identificador con nombre que contiene un conjunto único de valores de configuración. Puede tener varios entornos en una sola aplicación AWS SAM.

El valor predeterminado del nombre del entorno es default.

Utilice la opción AWS SAM CLI --config-env para especificar el entorno que se va a utilizar.

Comando

El comando es el comando de la CLI de AWS SAM para el que se especifican los valores de los parámetros.

Para especificar los valores de los parámetros de todos los comandos, utilice el identificador global.

Al hacer referencia a un comando AWS SAM CLI, sustituya los espacios ( ) y los guiones (–) por guiones bajos (_). Consulte los siguientes ejemplos:

• build

• local_invoke

• local_start_api

Parámetros

Los parámetros se especifican como pares de clave-valor.

• La clave es el nombre de la opción de comando AWS SAM CLI.

• El valor es el valor que se debe especificar.

Al especificar las claves, utilice el nombre de la opción de comando de formato largo y sustituya los guiones (–) por guiones bajos (_). A continuación se muestran algunos ejemplos:

• region

• stack_name

• template_file

Reglas del valor del parámetro

TOML

• Los valores booleanos pueden ser true o false. Por ejemplo, confirm_changeset = true.

• Para los valores de cadena, utilice comillas (""). Por ejemplo, region = "us-west-2".

• Para los valores de lista, utilice comillas ("") y separe cada valor con un espacio ( ). Por ejemplo: capabilities = "CAPABILITY_IAM CAPABILITY_NAMED_IAM".

• En el caso de los valores que contienen una lista de pares clave-valor, los pares están delimitados por espacios ( ) y el valor de cada par va entre comillas codificadas (\" \"). Por ejemplo, tags = "project=\"my-application\" stage=\"production\"".

• En el caso de los valores de los parámetros que se pueden especificar varias veces, el valor es una matriz de argumentos. Por ejemplo: image_repositories = ["my-function-1=image-repo-1", "my-function-2=image-repo-2"].

YAML

• Los valores booleanos pueden ser true o false. Por ejemplo, confirm_changeset: true.

• Para las entradas que contienen un único valor de cadena, las comillas ("") son opcionales. Por ejemplo, region: us-west-2. Esto incluye las entradas que contienen varios pares clave-valor que se proporcionan como una sola cadena. A continuación, se muestra un ejemplo:

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

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

• Para las entradas que contienen una lista de valores o las entradas que se pueden usar varias veces en un solo comando, especifíquelas como una lista de cadenas.

  A continuación, se muestra un ejemplo:

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

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

Prioridad de configuración

Al configurar los valores, se produce la siguiente prioridad:

• Los valores de los parámetros que se proporcionan en la línea de comandos tienen prioridad sobre los valores correspondientes del archivo de configuración y de la sección Parameters del archivo de plantilla.

• Si la opción --parameter-overrides se usa en la línea de comandos o en el archivo de configuración con la clave parameter_overrides, sus valores tienen prioridad sobre los valores de la sección Parameters del archivo de plantilla.

• En el archivo de configuración, las entradas proporcionadas para un comando específico tienen prioridad sobre las entradas globales. En el siguiente ejemplo, el comando sam deploy utilizará el nombre de la pila 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

Crear y modificar archivos de configuración

Creación de archivos de configuración

Al crear una aplicación utilizando sam init, se crea un archivo samconfig.toml predeterminado. También puede crear su archivo de configuración manualmente.

Modificación de los archivos de configuración

También puede modificar su archivo de configuración manualmente. Además, durante cualquier flujo interactivo AWS SAM CLI, los valores configurados se mostrarán entre corchetes ([ ]). Si modifica estos valores, la CLI de AWS SAM actualizará el archivo de configuración.

A continuación, se muestra un ejemplo de flujo interactivo con el comando 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

Al modificar el archivo de configuración, la CLI de AWS SAM gestiona los valores globales de la siguiente manera:

• Si el valor del parámetro existe en la sección global del archivo de configuración, la CLI de AWS SAM no escribe el valor en la sección de comandos específica.

• Si el valor del parámetro existe tanto en la sección de comandos específica como en la sección global, la CLI de AWS SAM elimina la entrada específica en favor del valor global.