Suporte do AWS SAM para o HashiCorp Terraform já está disponível ao público em geral

Suporte ao Terraform

O blog público de pré-visualização demonstrou o suporte inicial para o Terraform. Este blog demonstra o conjunto expandido de recursos do AWS SAM para o desenvolvimento local. O blog também simplifica a implementação usando os módulos Serverless.tf para funções e camadas do AWS Lambda, em vez dos recursos nativos do Terraform.

Os módulos podem criar os artefatos de implantação para as funções e camadas do Lambda. Além disso, o módulo gera automaticamente os metadados exigidos pelo AWS SAM para interagir com os recursos do Terraform. Para usar os recursos nativos do Terraform, consulte o blog de pré-visualização  para ver a configuração de metadados.

Baixando o código

Para explorar o suporte do AWS SAM para o Terraform, visite o repositório aws-sam-terraform-examples. Clone o repositório e mude para o diretório ga para começar:

git clone https://github.com/aws-samples/aws-sam-terraform-examples

cd ga

Nesse diretório, há dois aplicativos de demonstração. Ambos os aplicativos são idênticos, exceto que api_gateway_v1 usa uma API REST do Amazon API Gateway (v1) e api_gateway_v2 usa uma API HTTP do Amazon API Gateway (v2). Escolha um e mude para a pasta tf-resources nesse diretório.

cd api_gateway_v1/tf-resources

Salvo indicação contrária, os exemplos nesta postagem fazem referência ao aplicativo api_gateway_v1.

Estrutura do código

O Terraform suporta a distribuição de IaC em vários arquivos. Por causa disso, os desenvolvedores geralmente coletam todos os arquivos do Terraform em um único diretório e mantêm os arquivos de recursos em outro lugar. Os aplicativos de exemplo são configurados dessa forma.

Qualquer comando do Terraform ou do AWS SAM deve ser executado a partir do local do arquivo main.tf, nesse caso, o diretório tf-resources. Como os comandos do AWS SAM geralmente são executados a partir da raiz do projeto, o AWS SAM tem um comando para suportar estruturas aninhadas. Se estiver executando o comando sam build em uma pasta aninhada, passe o sinalizador terraform-project-root-path com um caminho relativo ou absoluto até a raiz do projeto.

Invocação local

A versão prévia do Terraform suportava a invocação local, mas a equipe simplificou a experiência com o suporte para Serverless.tf. Os aplicativos de exemplos têm duas funções. Uma função de resposta é a integração de back-end para os endpoints do API Gateway e a função Auth é um autorizador personalizado. Encontre as duas definições de módulo no arquivo functions.tf.

Função (Lambda) de resposta

module "lambda_function_responder" {
  source        = "terraform-aws-modules/lambda/aws"
  version       = "~> 6.0"
  timeout       = 300
  source_path   = "${path.module}/src/responder/"
  function_name = "responder"
  handler       = "app.open_handler"
  runtime       = "python3.9"
  create_sam_metadata = true
  publish       = true
  allowed_triggers = {
    APIGatewayAny = {
      service    = "apigateway"
      source_arn = "${aws_api_gateway_rest_api.api.execution_arn}/*/*"
    }
  }
}

Há dois parâmetros importantes:

• source_path, que aponta para uma pasta local. Como esse não é um arquivo zip, o Serverless.tf cria os artefatos conforme necessário.
• create_sam_dat a, que gera os metadados necessários para que o AWS SAM localize os arquivos e módulos necessários.

Para invocar a função localmente, execute os seguintes comandos:

1. Execute build para executar qualquer script de build

   sam build --hook-name terraform --terraform-project-root-path ../

   Bash
2. Execute a invocação local para invocar a função Lambda desejada

   sam local invoke --hook-name terraform --terraform-project-root-path ../ 'module.lambda_function_responder.aws_lambda_function.this[0]’

   Bash

Como o projeto é Terraform, o parâmetro hook-name com o valor terraform é necessário para que o AWS SAM saiba como proceder. O nome da função é uma combinação do nome do módulo e do tipo de recurso que ele se torna. Se você não tiver certeza do nome, execute o comando sem o nome:

sam local invoke --hook-name terraform

O AWS SAM avalia o modelo. Se houver apenas uma função, o AWS SAM continuará a invocá-la. Se houver mais de uma, como é o caso aqui, o AWS SAM pergunta qual delas e fornece uma lista de opções.

Função (Lambda) de autenticação

A função do autorizador requer alguns dados de entrada como um evento simulado. Para gerar um evento simulado para o projeto api_gateway_v1:

sam local generate-event apigateway authorizer

Para o projeto api_gateway_v2, use:

sam local generate-event apigateway request-authorizer

Os eventos resultantes são diferentes porque as APIs REST e HTTP do API Gateway podem lidar com autorizadores personalizados de forma diferente. Nesses exemplos, o REST usa um autorizador de token padrão e retorna a função adequada do AWS Identity and Access Management (IAM). O exemplo da API HTTP usa uma opção simples de aprovação ou falha.

Cada um dos exemplos já tem o evento devidamente formatado para teste incluído em events/auth.json. Para invocar a função Auth, execute o seguinte:

sam local invoke --hook-name terraform 'module.lambda_function_auth.aws_lambda_function.this[0]' -e events/auth.json

Não há necessidade de executar o comando sam build novamente porque o aplicativo não foi alterado.

API de inicialização local

Agora você pode emular uma versão local do API Gateway com a versão disponível ao público em geral. Cada um desses exemplos tem dois endpoints. Um endpoint está aberto e um autorizador personalizado protege o outro. Ambos retornam a mesma resposta:

{
  “message”: “Hello TF World”,
  “location”: “ip address”
}

Para iniciar o emulador local, execute o seguinte:

sam local start-api –hook-name terraform

O AWS SAM inicia o emulador e expõe os dois endpoints para testes locais.

Endpoint aberto

Usando curl, teste o endpoint aberto:

curl --location http://localhost:3000/open

O emulador local processa a solicitação e fornece uma resposta na janela do terminal. O emulador também inclui registros da função Lambda.

Endpoint de autenticação

Teste o endpoint seguro e passe o cabeçalho extra necessário, myheader:

curl -v --location http://localhost:3000/secure --header 'myheader: 123456789'

O endpoint retorna uma resposta autorizada com a mensagem “Hello TF World”. Tente o endpoint novamente com um valor de cabeçalho inválido:

curl --location http://localhost:3000/secure --header 'myheader: IamInvalid'

O endpoint retorna uma resposta não autenticada.

Parâmetros

Há várias opções ao usar o AWS SAM com o Terraform:

• Hook-name: necessário para cada comando ao trabalhar com o Terraform. Isso informa ao AWS SAM que o projeto é um aplicativo Terraform.
• Skip-Prepare-Infra: O AWS SAM usa o comando terraform plan para identificar e processar todos os artefatos necessários. No entanto, ele só deve ser executado quando novos recursos são adicionados ou modificados. Essa opção impede que o AWS SAM execute o comando terraform plan. Se esse sinalizador for aprovado e um plano não existir, o AWS SAM ignorará o sinalizador e executará o comando terraform plan de qualquer maneira.
• Prepare-infra: força o AWS SAM a executar o comando terraform plan.
• Terraform-project-root-path: substitui o diretório atual como raiz do projeto. Você pode usar um caminho absoluto (/path/to/project/root) ou um caminho relativo (../ou../.. /).
• Terraform-plan-file: permite que um desenvolvedor especifique um arquivo de plano específico do Terraform. Esse comando também permite que os usuários do Terraform usem comandos locais.

A combinação dessas opções pode criar comandos longos:

sam build --hook-name terraform --terraform-project-root-path ../

ou

sam local invoke –hook-name terraform –skip-prepare-infra 'module.lambda_function_responder.aws_lambda_function.this[0]'

Você pode usar o arquivo samconfig para definir padrões, encurtar comandos e otimizar o processo de desenvolvimento. Usando o novo suporte samconfig YAML, o arquivo tem a seguinte aparência:

version: 0.1
default:
  global:
    parameters:
      hook_name: terraform
      skip_prepare_infra: true
  build:
    parameters:
      terraform_project_root_path: ../

Ao definir esses padrões, o comando agora é mais curto:

sam local invoke 'module.lambda_function_responder.aws_lambda_function.this[0]'

O AWS SAM agora sabe que é um projeto do Terraform e ignora a tarefa de preparação, a menos que o plano do Terraform esteja ausente. Se for necessária uma atualização do plano, adicione a sinalização —prepare-infra para substituir a configuração padrão.

Implantação e depuração remota

Os aplicativos nesses projetos são aplicativos regulares do Terraform. Implante-os como qualquer outro projeto do Terraform.

terraform plan
terraform apply

Atualmente, o AWS SAM Accelerate não é compatível com projetos do Terraform. No entanto, como o Terraform é implantado usando o método de API, os aplicativos Serverless são implantados rapidamente. Use um relógio de terceiros e o comando terraform apply —auto-approve para aproximar essa experiência.

Para registrar, aproveite o comando sam logs. Consulte a saída de implantação dos projetos para ver um exemplo de como rastrear os registros de um ou de todos os recursos.

Plataforma de nuvem HashiCorp

O HashiCorp Cloud Platform permite que os desenvolvedores executem implantações usando um local centralizado para manter a segurança e o estado. Quando os desenvolvedores executam compilações na nuvem, um arquivo de plano local não está disponível para o AWS SAM usar em testes e depuração locais. No entanto, os desenvolvedores podem gerar um plano na nuvem e usar o plano localmente para desenvolvimento. Para obter instruções, consulte a documentação.

Conclusão

O HashiCorp Terraform é uma estrutura de IaC popular para criar aplicativos na nuvem da AWS. O AWS SAM é uma estrutura de IaC e a CLI foi projetada especificamente para ajudar os desenvolvedores a criar aplicativos Serverless.

Este blog aborda o novo suporte do AWS SAM para o Terraform e como os desenvolvedores podem usá-lo juntos para maximizar a experiência de desenvolvimento. O blog aborda a invocação local de uma única função, a emulação local dos endpoints do API Gateway e o teste local de um autorizador Lambda antes da implantação. Por fim, o blog implanta o aplicativo e usa o AWS SAM para monitorar os recursos implantados.

Para obter mais recursos de aprendizado Serverless, visite Serverless Land.