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, é possível consultar e transformar informações de recursos 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 Droplet. 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 recurso de Droplet e a definição de saída abaixo:

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
}

O primeiro passo é declarar um recurso de Gotas chamado web. Seu nome real na nuvem será test-droplet, na região fra1, com o Ubuntu 20.04.

Agora, 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 calculados. Aqui, você define o parâmetro value, que aceita um dado para exibir, definindo o IP da Gotas declarada. Na hora da declaração, é desconhecido, mas se tornará disponível após a deploy da Gotas. As saídas são mostradas e acessíveis após cada deploy.

Salve e fecha o arquivo, então deploye o projeto executando o seguinte comando:

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

Entre sim para aplicar quando solicitado. O fim do output será semelhante ao seguinte:

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 IP destacado pertence à sua nova Gotas deployada. A aplicação do projeto deploys os recursos na 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 a Gotas foi deployada.

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

  1. terraform output

O output listará todas as outputs do projeto:

Output
droplet_ip_address = ip_address

Pode consultar uma saída específica por nome especificando-a como argumento:

  1. terraform output output_name

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

Output
ip_address

Excepcionalmente para value, as saídas têm alguns parâmetros opcionais:

  • descrição: insere uma pequena documentação detalhando o que a saída mostra.
  • depends_on: um parâmetro meta disponível em cada recurso que permite que você explicitamente especifique recursos que a saída depende e que o Terraform não consegue deduzir automaticamente durante a planejamento.
  • sensitive: aceita um valor booleano, que impede que o conteúdo da saída seja mostrado após a implantação, se definido como true.

O parâmetro sensitive é útil quando os logs da implantação do Terraform estarão publicamente disponíveis, mas o conteúdo da saída deve ser mantido oculto. Agora você adicionará esse parâmetro à sua definição de recurso de Droplet.

Abra droplets.tf para edição 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 feche o arquivo quando você estiver pronto. Implante o projeto novamente, executando:

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

Digite yes quando solicitado. Você verá que a saída é redatada:

Output
...

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

Outputs:

droplet_ip_address = <sensitive>

Ainda que seja marcada como sensitive, a saída e seu conteúdo ainda estarão disponíveis por outros canais, como visualizar o estado do Terraform ou consultar as saídas diretamente.

No próximo passo, você criará uma estrutura de Droplet e saída diferente, então destrua as atualmente implantadas 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 seu endereço IP. Agora você aprenderá a usar saídas para mostrar estruturas mais complexas, como listas e mapas.

Saída de Estruturas Complexas

Nesta seção, você vai deployar múltiplos Droplet da mesma definição usando o palavra-chave count e exibir suas IPs em formatos variados.

Usando o laço for

Você precisará modificar a definição de recurso do Droplet, então abri-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, salvar e fechar o arquivo.

Aplique a configuração executando:

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

O Terraform planejará a criação de três Droplet numeradas chamadas test-droplet-0, test-droplet-1, e test-droplet-2. Digite yes quando solicitado para finalizar o processo. Você verá a 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.

A maneira mais fácil de acessar os atributos de recursos é 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á uma saída que irá exibir as IPs dos três Dropletts, juntas 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
  }
}

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

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

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

Digite yes quando solicitado e 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 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"}

O parsing JSON é amplamente utilizado e suportado em muitas linguagens de programação. Assim, você pode analisar informações sobre recursos deployados de forma programática.

Usando Expressões de Splay

Expressões de splay oferecem uma maneira compacta de iterar sobre 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 informações de endereço IP de três dropletas 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 por si só, 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 isto:

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
}

Depois de 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 das Dropletas:

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

Outputs:

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

Para obter 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 das Dropletas implantadas. Ele 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 dadas – para analisá-los.

Análise de Saídas Usando jq

Neste passo, você vai instalar e aprender os fundamentos do jq, uma ferramenta para manipular documentos JSON. Você vai usá-la para analisar as saídas de seu projeto Terraform.

Se você estiver no Ubuntu, execute o comando abaixo 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 fornecida em entrada dada, que pode ser encaminhada por pipeline. A tarefa mais fácil em jq é imprimir bonito a entrada:

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

Ao passar o operador de identidade (.), significa que todo o documento JSON processado da entrada deve ser saída sem modificações:

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

Você pode pedir apenas a segunda solicitação de endereço IP usando a notação de array de colchetes, contando a partir de zero:

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

A saída será:

Output
"second_ip_address"

Para tornar o resultado do processamento um array, envolva a expressão em colchetes:

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

Você obterá um array JSON impresso bonito:

Output
[
  "second_ip_address"
]

Você pode recuperar partes de arrays em vez de elementos únicos especificando um intervalo de índices dentro dos colchetes:

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

A saída 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 é incluída, portanto, apenas elementos nas posições 0 e 1 são buscados.

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ê aprenderá sobre as saídas do Terraform, usando-as para mostrar detalhes sobre os recursos implantados e para exportar estruturas de dados para processamento externo posterior. Você também usou as saídas para mostrar atributos de um recurso único, bem como para mostrar mapas e listas construídas contendo atributos de recursos.

Para obter 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 do Terraform, desde instalar o Terraform pela primeira vez até gerenciar projetos complexos.

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