Requisitos previos Uso de comandos de la CLI de AWS SAM con Terraform Configuración para proyectos de Terraform Configuración para Terraform Cloud

Introducción a compatibilidad de Terraform con CLI de AWS SAM

En este tema se explica cómo empezar a utilizar la interfaz de línea de comandos AWS Serverless Application Model (CLI de AWS SAM) con Terraform.

Para enviar comentarios y solicitudes de características, cree un Problema de GitHub.

Temas

Requisitos previos de Terraform para la CLI de AWS SAM
Uso de comandos de la CLI de AWS SAM con Terraform
Configuración para proyectos de Terraform
Configuración para Terraform Cloud

Requisitos previos de Terraform para la CLI de AWS SAM

Completa todos los requisitos previos para empezar a utilizar la CLI de AWS SAM en sus proyectos de Terraform.

Instala o actualiza la CLI de AWS SAM

Para comprobar si tienes la CLI de AWS SAM instalada, ejecuta lo siguiente:
```
$ sam --version
```
Si la CLI de AWS SAM ya está instalada, el resultado mostrará una versión. Para actualizar a la versión más reciente, consulta Actualización de AWS SAM CLI.

Para obtener instrucciones sobre la instalación de la CLI de AWS SAM junto con todos sus requisitos previos, consultaInstala la AWS SAM CLI.
Instalar Terraform

Para comprobar si instalaste Terraform, ejecuta lo siguiente:
```
$ terraform -version
```
Para instalar Terraform, consulta Instalar Terraform en el registro de Terraform.
Instala Docker para realizar el testeo local

La CLI de AWS SAM requiere Docker para las pruebas locales. Para instalarDocker, consulta Instalación de Docker para usarlo con la CLI de AWS SAM.

Uso de comandos de la CLI de AWS SAM con Terraform

Cuando ejecuta un comando compatible con la CLI de AWS SAM, utiliza la opción --hook-name y proporcione el valor terraform. A continuación, se muestra un ejemplo:


$ sam local invoke --hook-name terraform

Puedes configurar esta opción en su archivo de configuración de la CLI de AWS SAM con lo siguiente:

hook_name = "terraform"

Configuración para proyectos de Terraform

Completa los pasos de este tema para utilizar la CLI de AWS SAM con proyectos de Terraform.

No se requiere ninguna configuración adicional si crea sus artefactos de AWS Lambda fuera del proyecto de Terraform. Consulte Uso de la CLI de AWS SAM con Terraform para la depuración y las pruebas locales para empezar a utilizar la AWS SAM de CLI.

Si crea los artefactos de Lambda en sus proyectos de Terraform, debes hacer lo siguiente:

Instalación de Python 3.8 o posterior
Instala la herramienta Make.
Define la lógica de creación de artefactos de Lambda en su proyecto de Terraform.
Define un recurso sam metadata para informar su lógica de compilación a la CLI de AWS SAM.
Usa el comando AWS SAM CLI sam build para crear sus artefactos de Lambda.

Instalación de Python 3.8 o posterior

Se requiere Python 3.8 o una versión posterior para su uso con la CLI de AWS SAM Cuando se ejecuta sam build, la AWS SAM de Python crea makefiles que contiene comandos de CLI para crear sus artefactos de Lambda.

Para obtener instrucciones de instalación, consulta la página Downloading Python (Descarga de Python) en la Guía para principiantes de Python.

Compruebe que Python 3.8 o una versión posterior esté agregada a la ruta de su máquina ejecutando:


$ python --version

El resultado debe mostrar una versión de Python 3.8 o posterior.

Instala la herramienta Make.

GNUMake es una herramienta que controla la generación de ejecutables y otros archivos que no son el origen del proyecto. La CLI de AWS SAM crea makefiles que se basa en esta herramienta para crear sus artefactos de Lambda.

Si no has instalado Make en su máquina local, instálalo antes de continuar.

Para Windows, puedes realizar la instalación mediante Chocolatey. Para obtener instrucciones, consulta Uso de Chocolatey en Cómo instalar y usar “Make” en Windows

Define la lógica de construcción de los artefactos de Lambda

Utiliza el tipo de recurso null_resource Terraform para definir la lógica de compilación de Lambda. El siguiente es un ejemplo que utiliza un script de compilación personalizado para crear una función de Lambda.


resource "null_resource" "build_lambda_function" {
    triggers = {
        build_number = "${timestamp()}" 
    }

    provisioner "local-exec" {
        command =  substr(pathexpand("~"), 0, 1) == "/"? "./py_build.sh \"${local.lambda_src_path}\" \"${local.building_path}\" \"${local.lambda_code_filename}\" Function" : "powershell.exe -File .\\PyBuild.ps1 ${local.lambda_src_path} ${local.building_path} ${local.lambda_code_filename} Function"
    }
}

Define un recurso sam metadata

El recurso sam metadata es un tipo de recurso null_resource Terraform que proporciona a la CLI de AWS SAM la información que necesita para localizar los artefactos de Lambda. Se requiere un recurso de sam metadata único para cada función o capa de Lambda del proyecto. Para obtener más información sobre este tipo de recurso, consulta null_resource en el registro de Terraform.

Para definir un recurso sam metadata

Asigne un nombre al recurso empezando por sam_metadata_ para identificar el recurso como un recurso sam metadata.
Define las propiedades de sus artefactos Lambda dentro del bloque de triggers de tu recurso.

Especifica el null_resource que contiene la lógica de compilación de Lambda con el argumento depends_on.

La siguiente es una plantilla de ejemplo:


resource "null_resource" "sam_metadata_..." {
  triggers = {
    resource_name = resource_name
    resource_type = resource_type
    original_source_code = original_source_code
    built_output_path = built_output_path
  }
  depends_on = [
    null_resource.build_lambda_function # ref to your build logic
  ]
}

El siguiente es un recurso sam metadata de ejemplo:


resource "null_resource" "sam_metadata_aws_lambda_function_publish_book_review" {
    triggers = {
        resource_name = "aws_lambda_function.publish_book_review"
        resource_type = "ZIP_LAMBDA_FUNCTION"
        original_source_code = "${local.lambda_src_path}"
        built_output_path = "${local.building_path}/${local.lambda_code_filename}"
    }
    depends_on = [
        null_resource.build_lambda_function
    ]
}

El contenido del recurso sam metadata variará según el tipo de recurso de Lambda (función o capa) y el tipo de empaquetado (ZIP o imagen). Para obtener más información y ejemplos, consulta recurso de metadatos de sam.

Al configurar un recurso sam metadata y utilizar un comando compatible con la CLI de AWS SAM, la CLI de AWS SAM generará el archivo de metadatos antes de ejecutar el comando de la CLI de AWS SAM. Una vez hayas generado este archivo, puedes usar la opción --skip-prepare-infra con comandos futuros de la CLI de AWS SAM para omitir el proceso de generación de metadatos y ahorrar tiempo. Esta opción solo debe usarse si no ha realizado ningún cambio en la infraestructura, como la creación de nuevas funciones de Lambda o nuevos puntos de conexión de API.

Utiliza la CLI de AWS SAM para crear sus artefactos de Lambda.

Usa el comando AWS SAM CLI sam build para crear sus artefactos de Lambda. Cuando se ejecuta sam build, la CLI de AWS SAM hace lo siguiente:

Busca recursos sam metadata en tu proyecto de Terraform para conocer y localizar tus recursos de Lambda.
Inicia la lógica de compilación de Lambda para crear sus artefactos de Lambda.
Crea un directorio de .aws-sam que organiza el proyecto de Terraform para usarlo con los comandos sam local de la CLI de AWS SAM.

Para crear con sam build

Desde el directorio que contiene el módulo raíz de Terraform, ejecuta lo siguiente:
```
$ sam build --hook-name terraform
```
Para crear una función o capa de Lambda específica, ejecuta lo siguiente
```
$ sam build --hook-name terraform lambda-resource-id
```
El ID de recurso de Lambda puede ser el nombre de la función de Lambda o la dirección completa del recurso de Terraform, como aws_lambda_function.list_books o module.list_book_function.aws_lambda_function.this[0].

Si el código de origen de la función u otros archivos de configuración de Terraform se encuentran fuera del directorio que contiene el módulo raíz de Terraform, debes especificar la ubicación. Utiliza la opción --terraform-project-root-path para especificar la ruta absoluta o relativa al directorio de nivel superior que contiene estos archivos. A continuación, se muestra un ejemplo:


$ sam build --hook-name terraform --terraform-project-root-path ~/projects/terraform/demo

Creación mediante un contenedor

Al ejecutar el comando sam build de la CLI de AWS SAM, puedes configurar la CLI de AWS SAM para que compile tu aplicación mediante un contenedor local de Docker.

nota

Debe tener Docker instalado y configurado. Para obtener instrucciones, consulta Instalación de Docker para usarlo con la CLI de AWS SAM.

Para compilar usando un contenedor

Crea un Dockerfile que contenga las herramientas Terraform, Python y Make. También debes incluir el tiempo de ejecución de la función de Lambda.

A continuación, se muestra un Dockerfile de ejemplo:

FROM public.ecr.aws/amazonlinux/amazonlinux:2

RUN yum -y update \
    && yum install -y unzip tar gzip bzip2-devel ed gcc gcc-c++ gcc-gfortran \
    less libcurl-devel openssl openssl-devel readline-devel xz-devel \
    zlib-devel glibc-static libcxx libcxx-devel llvm-toolset-7 zlib-static \
    && rm -rf /var/cache/yum

RUN yum -y install make \
    && yum -y install zip

RUN yum install -y yum-utils \
    && yum-config-manager --add-repo https://rpm.releases.hashicorp.com/AmazonLinux/hashicorp.repo \
    && yum -y install terraform \
    && terraform --version

# AWS Lambda Builders
RUN amazon-linux-extras enable python3.8
RUN yum clean metadata && yum -y install python3.8
RUN curl -L get-pip.io | python3.8
RUN pip3 install aws-lambda-builders
RUN ln -s /usr/bin/python3.8 /usr/bin/python3
RUN python3 --version

VOLUME /project
WORKDIR /project

ENTRYPOINT ["sh"]

Use docker build para crear su imagen de Docker.

A continuación, se muestra un ejemplo:
```
$ docker build --tag terraform-build:v1 <path-to-directory-containing-Dockerfile>
```
Ejecuta el comando sam build de la CLI de AWS SAM con las opciones --use-container y --build-image.

A continuación, se muestra un ejemplo:
```
$ sam build --use-container --build-image terraform-build:v1
```

Pasos a seguir a continuación

Para empezar a utilizar la CLI de AWS SAM en sus proyectos de Terraform, consulta Uso de la CLI de AWS SAM con Terraform para la depuración y las pruebas locales.

Configuración para Terraform Cloud

Se recomienda usar Terraform v1.6.0 o posterior. Si usa una versión anterior, debes generar un archivo de plan de Terraform de forma local. El archivo del plan local proporciona a la CLI de AWS SAM la información necesaria para realizar las pruebas y la depuración locales.

Para generar un archivo de plan local

nota

Estos pasos no son necesarios con Terraform v1.6.0 o posterior. Para empezar a usar la CLI de AWS SAM con Terraform Cloud, consulta Uso de la CLI de AWS SAM con Terraform.

Configurar un token de API: el tipo de token dependerá de su nivel de acceso. Para obtener más información, consulta Tokens de API en la documentación de Terraform Cloud.
Configurar la variable de entorno del token de la API: el siguiente es un ejemplo de la línea de comandos:
```
$ export TOKEN="<api-token-value>"
```
Obtener su ID de ejecución: en la consola Terraform Cloud, localiza el ID de ejecución de la ejecución de Terraform que quiere usar con la CLI de AWS SAM.

El ID de ejecución se encuentra en la ruta de navegación del proceso de ejecución.

Obtener el archivo del plan: con su token de API, obtengas el archivo del plan local. A continuación, se muestra un ejemplo de la línea de comando:


curl \
   --header "Authorization: Bearer $TOKEN" \
   --header "Content-Type: application/vnd.api+json" \
   --location \
   https://app.terraform.io/api/v2/runs/<run ID>/plan/json-output \
   > custom_plan.json

Ahora ya puedes utilizar la CLI de AWS SAM con Terraform Cloud. Si utilizas un comando compatible con la CLI de AWS SAM, utiliza la opción --terraform-plan-file para especificar el nombre y la ruta del archivo del plan local. A continuación, se muestra un ejemplo:


$ sam local invoke --hook-name terraform --terraform-plan-file custom-plan.json

A continuación, se muestra un ejemplo con el comando sam local start-api:


$ sam local start-api --hook-name terraform --terraform-plan-file custom-plan.json

Para ver una aplicación de muestra que pueda usar con estos ejemplos, consulta api_gateway_v2_tf_cloud en el repositorio de GitHub aws-samples.

Pasos a seguir a continuación

Para comenzar a usar la CLI de AWS SAM con Terraform Cloud,consulta Uso de la CLI de AWS SAM con Terraform para la depuración y las pruebas locales.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

TerraformCompatibilidad con

Uso de la CLI de AWS SAM con Terraform

Introducción a compatibilidad de Terraform con CLI de AWS SAM

Temas

Requisitos previos de Terraform para la CLI de AWS SAM

Instala o actualiza la CLI de AWS SAM

Instalar Terraform

Instala Docker para realizar el testeo local

Uso de comandos de la CLI de AWS SAM con Terraform

Configuración para proyectos de Terraform

Instalación de Python 3.8 o posterior

Instala la herramienta Make.

Define la lógica de construcción de los artefactos de Lambda

Define un recurso sam metadata

Para definir un recurso sam metadata

Utiliza la CLI de AWS SAM para crear sus artefactos de Lambda.

Para crear con sam build

Creación mediante un contenedor

nota

Para compilar usando un contenedor

Pasos a seguir a continuación

Configuración para Terraform Cloud

Para generar un archivo de plan local

nota

Pasos a seguir a continuación