Como Gerenciar Dados de Infraestrutura com Saídas do Terraform

Tutoriais
Terraform

Introdução

As saídas de Terraform são usadas para extrair informações sobre recursos de infraestrutura do estado do projeto. Utilizando outras funcionalidades do Hashicorp Configuration Language (HCL), que o Terraform usa, informações de recursos podem ser consultadas e transformadas em estruturas de dados mais complexas, como listas e mapas. As saídas são úteis para fornecer informações a software externo, que pode operar sobre os recursos de infraestrutura criados.

Neste tutorial, você vai aprender sobre a sintaxe de saída do Terraform e seus parâmetros criando uma infraestrutura simples que implanta Droplets. Você também vai analisar as saídas de forma programática convertendo-as para JSON.

Pré-requisitos

Nota: Este tutorial foi testado especificamente com Terraform 1.0.2.

Definição de Saídas

Nesta seção, você declarará um Droplet, o deployá para o cloud e aprenderá sobre saídas definindo uma que mostrará o endereço IP do Droplet.

A partir do diretório terraform-outputs que você criou como pré-requisito, crie e abra o arquivo droplets.tf para edição:

  1. nano droplets.tf

Adicione o seguinte recurso de Droplet e definição de saída:

terraform-outputs/droplets.tf
resource "digitalocean_droplet" "web" {
  image  = "ubuntu-20-04-x64"
  name   = "test-droplet"
  region = "fra1"
  size   = "s-1vcpu-1gb"
}

output "droplet_ip_address" {
  value = digitalocean_droplet.web.ipv4_address
}

A tradução para o português brasileiro é a seguinte:

Você primeiramente declara um recurso de Gotão chamado web. Seu nome real na nuvem será test-droplet, na região fra1, com o Ubuntu 20.04.

Então, você declara uma saída chamada droplet_ip_address. Na Terraform, as saídas são usadas para exportar e mostrar valores e informações sobre os recursos internos e computados. Aqui, você define o parâmetro value, que aceita o dado a ser exibido, como o endereço IP do declarado Gotão. Na hora da declaração, ele é desconhecido, mas tornará disponível após a implantação do Gotão. As saídas são mostradas e acessíveis após cada implantação.

Salve e fecharem o arquivo, então deploy o projeto executando o seguinte comando:

  1. terraform apply -var "do_token=${DO_PAT}"

Digite sim para aplicar quando solicitado. O fim da saída será semelhante a este:

Output
...
digitalocean_droplet.web: Creating...
...
digitalocean_droplet.web: Creation complete after 32s [id=207631771]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Outputs:

droplet_ip_address = ip_address

O endereço IP destacado pertence ao seu novo Gotão implantado. A aplicação do projeto deploys os recursos para a nuvem e mostra as saídas no final, quando todos os atributos dos recursos estiverem disponíveis. Sem a saída droplet_ip_address, a Terraform mostrará apenas que o Gotão foi implantado.

As saídas também podem ser mostradas usando o comando output:

  1. terraform output

A saída listará todas as outputs no projeto:

Output
droplet_ip_address = ip_address

Você pode consultar uma saída específica por nome especificando-la como argumento:

  1. terraform output output_name

Para droplet_ip_address, a saída consistirá apenas do endereço IP:

Output
ip_address

Excepcionalmente, além de definir o parâmetro obrigatório value, as saídas têm alguns outros parâmetros opcionais:

  • descrição: embeda breve documentação detalhando o que a saída mostra.
  • depende_em: um parâmetro meta disponível em cada recurso que permite especificar explicitamente os recursos que a saída depende, o que o Terraform não é capaz de deduzir automaticamente durante a planificação.
  • sensível: aceita um valor booleano, que previne que o conteúdo da saída seja mostrado após a implantação se definido como true.

O parâmetro sensível é útil quando os logues do deploy do Terraform serão publicamente disponíveis, mas o conteúdo da saída deve ser mantido escondido. Você agora adicionará-lo à definição de seu recurso de Droplata.

Abra droplets.tf para editar e adicione a linha destacada:

terraform-outputs/droplets.tf
resource "digitalocean_droplet" "web" {
  image  = "ubuntu-20-04-x64"
  name   = "test-droplet"
  region = "fra1"
  size   = "s-1vcpu-1gb"
}

output "droplet_ip_address" {
  value      = digitalocean_droplet.web.ipv4_address
  sensitive = true
}

Salve e fecha o arquivo quando você estiver pronto. Deploye o projeto novamente executando:

  1. terraform apply -var "do_token=${DO_PAT}"

Digite sim quando solicitado. Voulez-vous voir que a saída está redactada:

Output
...

Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

Outputs:

droplet_ip_address = <sensitive>

Mesmo se marcada como sensível, a saída e suas informações continuarão disponíveis por outros canais, como visualizar o estado do Terraform ou consultar as saídas diretamente.

No próximo passo, você criará um Droplet diferente e uma estrutura de saída diferente, então destrua os Droplet implantados atuais executando:

  1. terraform destroy -var "do_token=${DO_PAT}"

A saída no final será:

Output
...
Destroy complete! Resources: 1 destroyed.

Você declarou e implantou um Droplet e criou uma saída que mostra sua IP. Agora você aprenderá sobre usar saídas para mostrar estruturas mais complexas, como listas e mapas.

Saída de Estruturas Complexas

Nesta seção, você irá deployar vários Droplets da mesma definição usando o palavra-chave count. Eles irão exibir suas IPs em formatos diferentes.

Usando o laço for

Você precisará modificar a definição de recurso do Droplet, então abra-la para editar:

  1. nano droplets.tf

Modifique-a para parecer assim:

terraform-outputs/droplets.tf
resource "digitalocean_droplet" "web" {
  count  = 3
  image  = "ubuntu-20-04-x64"
  name   = "test-droplet-${count.index}"
  region = "fra1"
  size   = "s-1vcpu-1gb"
}

Você especificou que três Droplet devem ser criados usando a chave count e adicionou o índice atual ao nome do Droplet, para que possa discernir entre eles posteriormente. Remova a saída existente abaixo. Quando estiver pronto, salve e fecha o arquivo.

Aplique o código executando:

  1. terraform apply -var "do_token=${DO_PAT}"

Terraform planejará a criação de três Droplet numerados chamados test-droplet-0, test-droplet-1, e test-droplet-2. Digite yes quando solicitado para finalizar o processo. Você verá a seguinte saída no fim:

Output
...
Apply complete! Resources: 3 added, 0 changed, 0 destroyed.

Isso significa que todos os três Droplet foram implantados com sucesso e que toda informação sobre eles está armazenada na estrutura de estado do projeto.

Acessar os atributos de recursos mais facilmente é usando saídas, mas criar uma para cada Dropletto não é escalável. A solução é usar o loop for para percorrer a lista de Droplettos e coletar seus atributos, ou alternativamente usar expressões splat (que você aprenderá sobre na próxima etapa deste passo).

Você primeiro definirá um output que irá exibir as IPs dos três Dropletts, parados com suas nomes. Abra droplets.tf para editar:

  1. nano droplets.tf

Adicione as linhas seguintes:

terraform-outputs/droplets.tf
resource "digitalocean_droplet" "web" {
  count  = 3
  image  = "ubuntu-20-04-x64"
  name   = "test-droplet-${count.index}"
  region = "fra1"
  size   = "s-1vcpu-1gb"
}

output "droplet_ip_addresses" {
  value = {
    for droplet in digitalocean_droplet.web:
    droplet.name => droplet.ipv4_address
  }
}

O valor de saída droplet_ip_addresses é construído usando um loop for. Porque está encerrado em chaves, o tipo resultante será um mapa. O loop percorre a lista de Dropletts, e para cada instância, associa seu nome com sua IP e adiciona-o ao mapa resultante.

Salve e fecha o arquivo, então aplique o projeto novamente:

  1. terraform apply -var "do_token=${DO_PAT}"

Digite yes quando solicitado e você receberá os detalhes da saída no final:

Output
Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

Outputs:

droplet_ip_addresses = {
  "test-droplet-0" = "ip_address"
  "test-droplet-1" = "ip_address"
  "test-droplet-2" = "ip_address"
}

As informações de saída do droplet_ip_addresses mostram as IPs dos três dropletts deployados.

Usando o comando output do Terraform, você pode obter os conteúdos da saída usando seu argumento de comando:

  1. terraform output -json droplet_ip_addresses

O resultado será semelhante ao seguinte:

Output
{"test-droplet-0":"ip_address","test-droplet-1":"ip_address","test-droplet-2":"ip_address"}

A leitura de JSON é amplamente utilizada e suportada em muitas linguagens de programação. Assim, você pode analisar informações sobre recursos implantados de maneira programática.

Usando Expressões de Splay

Expressões de splay oferecem uma maneira compacta de percorrer todos os elementos de uma lista e coletar o conteúdo de um atributo de cada um deles, resultando em uma lista. Uma expressão de splay que extrairia as URLs de endereço IP de três instâncias Droplet implantadas teria a seguinte sintaxe:

digitalocean_droplet.web[*].ipv4_address

O símbolo [*] percorre a lista à sua esquerda e para cada elemento, pega o conteúdo de seu atributo especificado à direita. Se a referência à esquerda não é uma lista em si, ela será convertida em uma onde será o único elemento.

Você pode abrir droplets.tf para edição e modificar as seguintes linhas para implementar isso:

terraform-outputs/droplets.tf
resource "digitalocean_droplet" "web" {
  count  = 3
  image  = "ubuntu-20-04-x64"
  name   = "test-droplet-${count.index}"
  region = "fra1"
  size   = "s-1vcpu-1gb"
}

output "droplet_ip_addresses" {
  value = digitalocean_droplet.web[*].ipv4_address
}

Após salvar o arquivo, aplique o projeto executando o seguinte comando:

  1. terraform apply -var "do_token=${DO_PAT}"

Você receberá saída que é agora uma lista e que contém apenas os endereços IP dos Droplet:

Output
...
Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

Outputs:

droplet_ip_addresses = [
  "ip_address",
  "ip_address",
  "ip_address",
]

Para receber a saída como JSON, execute o seguinte comando:

  1. terraform output -json droplet_ip_addresses

A saída será um único array:

Output
["ip_address","ip_address","ip_address"]

Você usou saídas juntamente com expressões de splay e laços de repetição for para exportar os endereços IP dos Droplet implantados. Você também recebeu o conteúdo da saída como JSON e agora usará o jq – uma ferramenta para filtrar JSON dinamicamente de acordo com expressões fornecidas – para analisá-los.

Sintaxe de saída usando o jq

Neste passo, você instalará e aprenderá as bases do jq, uma ferramenta para manipular documentos JSON. Você usará para analisar os resultados do seu projeto do Terraform.

Se você estiver no Ubuntu, execute o seguinte comando para instalar o jq:

  1. sudo snap install jq

No macOS, você pode usar o Homebrew para instalá-lo:

  1. brew install jq

jq aplica a expressão de processamento providida sobre a entrada que pode ser enviada por linha de comandos. A tarefa mais simples em jq é imprimir a saída sem alterações:

  1.  terraform output -json droplet_ip_addresses | jq '.'

Passando o operador identidade (.) significa que todo o documento JSON parseado da entrada deve ser exibido sem modificações:

Output
[
  "first_ip_address",
  "second_ip_address",
  "third_ip_address"
]

Você pode pedir apenas a segunda subrede usando notação de conjunto de índices, contando a partir de zero:

  1. terraform output -json droplet_ip_addresses | jq '.[1]'

A saída será:

Output
"second_ip_address"

Para obter o resultado da expressão de processamento como um array, envolva a expressão dentro de parênteses:

  1. terraform output -json droplet_ip_addresses | jq '[.[1]]'

Você receberá um array de JSON formatado:

Output
[
  "second_ip_address"
]

Você pode retornar partes de arrays ao invés de elementos individuais especificando um rango de índices dentro das barras:

  1. terraform output -json droplet_ip_addresses | jq '.[0:2]'

O resultado será:

Output
[
  "first_ip_address",
  "second_ip_address"
]

O intervalo 0:2 retorna os dois primeiros elementos — a parte superior do intervalo (2) não é inclusiva, portanto, apenas os elementos nas posições 0 e 1 são obtidos.

Você agora pode destruir os recursos implantados executando:

  1. terraform destroy -var "do_token=${DO_PAT}"

Neste passo, você instalou o jq e o usou para analisar e manipular a saída do seu projeto Terraform, que implanta três Droplet.

Conclusão

Você aprendera sobre saídas Terraform, usando-as para mostrar detalhes sobre os recursos implantados e para exportar estruturas de dados para processamento externo posterior. Também usou saídas para mostrar atributos de um recurso único, bem como para mostrar mapas e listas construídas contendo atributos de recursos.

Para informações mais detalhadas sobre as funcionalidades do jq, visite as documentações oficiais.

Este tutorial é parte da série Como Gerenciar Infraestrutura com Terraform. A série abrange vários tópicos Terraform, desde instalar Terraform pela primeira vez até gerenciar projetos complexos.

Source:
https://www.digitalocean.com/community/tutorials/how-to-manage-infrastructure-data-with-terraform-outputs