Criando modelos Terraform

Aprenda a criar modelos Terraform que são bem estruturados, reutilizáveis e abrangentes.

Um modelo Terraform consiste em um ou mais arquivos de configuração do Terraform que declaram o estado que você deseja alcançar para seus recursos do IBM Cloud®. Para trabalhar com sucesso com seus recursos, você deve configurar o IBM como seu provedor de nuvem e adicionar recursos ao seu arquivo de configuração do Terraform. Opcionalmente, é possível usar variáveis de entrada para customizar seus recursos.

É possível gravar o seu arquivo de configuração do Terraform usando o HashiCorp Configuration Language (HCL) ou o formato JSON. Você também pode usar o Terraform IBM Modules(TIM), que oferece componentes de infraestrutura pré-criados que ajudam a padronizar e simplificar o processo de implantação.

Antes de começar a criar seu modelo Terraform, certifique-se de revisar as limitações do IBM Cloud Schematics.

Configurando o bloco `provider`

Especifique o provedor em nuvem que deseja usar no bloco provider de seu arquivo de configuração do Terraform. O bloco provider inclui todas as variáveis de entrada que o plug-in do IBM Cloud® Provider para Terraform requer para provisionar seus recursos.

Chave de API da IBM Cloud

A chave da API IBM Cloud é essencial para a autenticação na plataforma IBM Cloud. Além disso, o token do IAM e o token de atualização do IAM que o site Schematics exige para trabalhar com a API do recurso e para determinar as permissões que lhe foram concedidas. Ao usar o Terraform nativo, deve-se sempre fornecer a chave API do IBM Cloud. No Schematics, o token do IAM é recuperado para todos os recursos ativados por IAM, incluindo os clusters do IBM Cloud Kubernetes Service e os recursos de infraestrutura da VPC. No entanto, o token IAM não é recuperado para recursos de infraestrutura clássica, e a chave da API deve ser fornecida no bloco provider .

**Chave de API IBM Cloud diferente no bloco provider **

Se você quiser usar uma chave de API diferente da que está associada à sua conta do IBM Cloud, será possível fornecer essa chave de API no bloco provider. Se uma chave de API for configurada no bloco provider, essa chave terá precedência sobre a chave de API que está armazenada no IBM Cloud.

IBM Cloud Chave de API para um ID de serviço

É possível fornecer uma chave de API para um ID de serviço para todos os serviços ativados para IAM, incluindo recursos de infraestrutura do VPC. Não é possível usar um ID de serviço para recursos de infraestrutura clássica.

Siga as instruções para configurar o bloco provider.

Escolha como deseja configurar o bloco provider.
- Opção 1: Criar um arquivo separado chamado “ provider.tf ”. As informações nesse arquivo são carregadas pelo Terraform e pelo IBM Cloud Schematics e aplicadas a todos os arquivos de configuração do Terraform existentes no mesmo diretório do GitHub ou no arquivo tape archive .tar. Essa abordagem será útil ao dividir o código de infraestrutura em diversos arquivos.
- Opção 2: Adicione um bloco provider ao seu arquivo de configuração do Terraform. Você poderá escolher essa opção se preferir especificar o provedor ao lado de suas variáveis e recursos em um arquivo de configuração do Terraform.
Revise as credenciais e informações que você deve fornecer no bloco provider para trabalhar com seus recursos. O Schematics recupera automaticamente a chave de API IBM Cloud para que você não precise especificar essas informações no bloco provider.
Crie um arquivo provider.tf ou inclua o código a seguir em seu arquivo de configuração do Terraform. Para obter uma lista integral de parâmetros suportados que podem ser configurados no bloco do provider, consulte a Referência do provedor da IBM Cloud.

Exemplo de recursos de infraestrutura da VPC
```
provider "ibm" {
    generation = 1
    region = "<region_name>"
}
```
Exemplo de recursos de infraestrutura clássica
```
variable "iaas_classic_username" {
    type = "string"
}
variable "iaas_classic_api_key" {
    type = "string"
}
provider "ibm" {
    region = "<region_name>"
    iaas_classic_username = var.iaas_classic_username
    iaas_classic_api_key  = var.iaas_classic_api_key
}
```
Exemplo para todos os recursos do IBM Cloud Kubernetes Service
```
provider "ibm" {
}
```
Exemplo para todos os demais recursos
```
provider "ibm" {
    region = "<region_name>"
}
```

Adicionando recursos da nuvem ao bloco “ `resource` ”

Use os blocos “ resource ” para definir os recursos da nuvem que você deseja gerenciar com o “ IBM Cloud Schematics ”.

Para suportar uma abordagem multicloud, o Terraform funciona com diversos provedores em nuvem. Um provedor em nuvem é responsável por entender os recursos que podem ser provisionados, a API deles e os métodos para expor estes recursos na nuvem. Para disponibilizar esse conhecimento para os usuários, todo provedor em nuvem suportado deve fornecer um plug-in de linha de comandos para o Terraform que os usuários possam usar para trabalhar com os recursos. Para localizar uma visão geral dos recursos que você pode provisionar no IBM Cloud, consulte a referência do IBM Cloud Provider Plug-in for Terraform.

Exemplo de código de infraestrutura para provisionamento de uma VPC

resource ibm_is_vpc "vpc" {
    name = "myvpc"
}

Referenciando recursos em outros blocos de recursos

Revise as opções disponíveis para referenciar recursos existentes em outros blocos de recursos de seu arquivo de configuração do Terraform.

A referência do plug-in do IBM Cloud Provider inclui dois tipos de objetos, origens de dados e recursos. É possível usar ambos para referenciar recursos em outros blocos de recursos.

Recursos: para criar um recurso, use a definição de recurso na referência do plug-in do IBM Cloud Provider. Uma definição de recurso inclui a sintaxe para configurar seus recursos na nuvem e uma referência de atributos que mostra as propriedades que você pode utilizar como parâmetros de entrada em outros blocos de recursos. Por exemplo, ao criar um VPC, o ID do VPC é disponibilizado após a criação. É possível usar o ID como um parâmetro de entrada ao criar uma sub-rede para seu VPC. Use essa opção ao combinar diversos recursos em um arquivo de configuração do Terraform.

Exemplo de um código de infraestrutura
```
resource ibm_is_vpc "vpc" {
    name = "myvpc"
}
resource ibm_is_security_group "sg1" {
    name = "mysecuritygroup"
vpc  = ibm_is_vpc.vpc.id
}
```
Fontes de dados: Você também pode usar as fontes de dados descritas na referência do plug-in “ IBM Cloud Provider” para recuperar informações sobre um recurso na nuvem já existente. Revise a seção Referência de argumento na referência do plug-in do IBM Cloud Provider para ver quais parâmetros de entrada devem ser fornecidos para recuperar um recurso existente. Em seguida, revise a seção Referência de atributos para localizar uma visão geral dos parâmetros disponibilizados para você e que podem ser referenciados em seus blocos de resource. Use essa opção se desejar acessar os detalhes de um recurso configurado em outro arquivo de configuração do Terraform.

Exemplo de um código de infraestrutura
```
data ibm_is_image "ubuntu" {
    name = "ubuntu-18.04-amd64"
}
resource ibm_is_instance "vsi1" {
    name    = "$mysi"
vpc     = ibm_is_vpc.vpc.id
zone    = "us-south1"
keys    = [data.ibm_is_ssh_key.ssh_key_id.id]
image   = data.ibm_is_image.ubuntu.id
profile = "cc1-2x4"
primary_network_interface {
    subnet          = ibm_is_subnet.subnet1.id
    security_groups = [ibm_is_security_group.sg1.id]
}
}
```

Gerenciando recursos em outra conta

Você pode usar espaços de trabalho na conta de origem IBM Cloud para executar trabalhos do Terraform para criar recursos em uma conta de destino. Para provisionar recursos em uma conta de destino, a identidade e as permissões de acesso da conta de destino devem ser fornecidas. Isso pode ser feito usando a identidade de um usuário com permissões para a conta de destino. Ou uma ID de serviço com autenticação e autorização apropriada entre contas para a conta de destino usando uma chave de API.

Ao executar trabalhos por meio da interface do usuário sem passar chaves de API, a identidade do usuário conectado é assumida para a execução de operações.

Usando blocos `variable` para customizar recursos

É possível usar blocos variable para criar modelos para o seu código de infraestrutura. Por exemplo, em vez de criar vários arquivos de configuração do Terraform para um recurso que você deseja implantar em vários data centers. Basta reutilizar a mesma configuração com uma variável de entrada para definir o data center.

Armazenamento de variáveis

É possível decidir declarar suas variáveis dentro do mesmo arquivo de configuração do Terraform no qual você especifica os recursos que deseja provisionar ou para criar um arquivo variables.tf separado que inclua todas as declarações de variáveis. Ao criar uma área de trabalho, o IBM Cloud Schematics analisa automaticamente os arquivos de configuração do Terraform para localizar declarações de variáveis.

Declaração de variável

Ao declarar uma variável de entrada, deve-se fornecer um nome para sua variável e o tipo de dados de acordo com a versão do Terraform. Opcionalmente, é possível fornecer o valor padrão para a sua variável. Quando as variáveis de entrada são importadas para o Schematics e um valor padrão é especificado, é possível optar por substituir esse valor padrão. \n e IBM Cloud Schematics aceitam os valores como uma string para tipos primitivos, como bool, ` `number, string e no formato ` `HCL` ` para variáveis complexas. - O ` `Terraform v1.5` ` suporta **os tipos de dados string, lista, mapa, ` `bool, número e tipos complexos, como lista(tipo), mapa(tipo), objeto( {attribute name=type,.} ), conjunto(tipo) e tupla( [tipo] )**.

Limitação da variável de entrada

Sim. Se você definir variáveis de entrada em seu arquivo de configuração do Terraform, lembre-se de que o valor que você inserir para essas variáveis poderá ter até 2049 caracteres. Se a sua variável de entrada requerer um valor que exceda esse limite, o valor será truncado após 2049 caracteres.

Exemplo de declaração de variável sem valor padrão

variable "datacenter" {
    type        = "string"
    description = "The data center that you want to deploy your Kubernetes cluster in."
}

Exemplo de declaração de variável com um valor padrão

variable "datacenter" {
    type        = "string"
    description = "The data center that you want to deploy your Kubernetes cluster in."
    default = "dal10"
}

Referenciando variáveis

É possível referenciar o valor da variável em outros blocos de seus arquivos de configuração do Terraform usando a sintaxe "${var.<variable_name>}".

Exemplo de como fazer referência a uma variável datacenter

resource ibm_container_cluster "test_cluster" {
    name         = "test"
    datacenter   = var.datacenter
}

Aproveitamento do Terraform IBM Modules para um desenvolvimento mais rápido

Opcionalmente, você pode usar o Terraform IBM Modules(TIM) para criar seus modelos. Ele ajuda a criar rapidamente uma infraestrutura complexa, simplifica as dependências de recursos, aplica as práticas recomendadas do IBM Cloud e evolui por meio de contribuições da comunidade IBM Cloud.

Exemplo: Usando o módulo VPC da TIM

module "vpc" {
  source  = "terraform-ibm-modules/vpc/ibm"
  version = "1.1.0"
  
  vpc_name                    = "my-production-vpc"
  resource_group_id           = "Default"
  classic_access              = false
  default_address_prefix      = "auto"
  default_network_acl_name    = "my-default-acl"
  default_security_group_name = "my-default-sg"
  default_routing_table_name  = "my-default-rt"
}

Explore os módulos disponíveis:

Fornecendo às variáveis declaradas valores a serem usados pelo IBM Cloud Schematics

Você pode fornecer os valores depois de criar o espaço de trabalho para que o IBM Cloud Schematics seja usado nas ações do Terraform, para as variáveis declaradas no modelo.

Para o UI``, você pode definir os valores na página IBM Cloud > Schematics > workspace > Configurações. O campo de value é o valor de formato HCL como fornecido no arquivo .tfvars.
Em CLI, você pode criar, visualizar ou atualizar os valores do tipo de dados Complex. Nesse caso, o campo “ value ” deve conter uma string com caracteres de escape para a variável “store”, conforme mostrado no exemplo.

Em API, você pode criar ou atualizar os valores no campo template_data > variablestore. O campo “ value ” corresponde ao valor no formato “ HCL ”, conforme fornecido no arquivo “ .tfvars ”. É sempre uma sequência JSON para qualquer tipo da variável.

Exemplo

"variablestore": [
            {
                "value": "[\n    {\n      internal = 800\n      external = 83009\n      protocol = \"tcp\"\n    }\n  ]",
                "description": "",
                "name": "docker_ports",
                "type": "list(object({\n    internal = number\n    external = number\n    protocol = string\n  }))"
            },
            {
                "name": "worker_pool_labels",
                "type": "map(string)",
                "value": "{\n        \"label-name1\": \"label-value1\",\n        \"label-name2\": \"label-value2\"\n}"
            },
            {
                "name": "docker_ports",
                "type": "list(object({\n    internal = number\n    external = number\n    protocol = string\n  }))",
                "value": "[\n    {\n      internal = 800\n      external = 83009\n      protocol = \"tcp\"\n    }\n  ]",
                "description": ""
            }
    ]

É possível ver como declarar variáveis complexas em um arquivo?

Sim, ao declarar e atribuir o valor às variáveis, é possível visualizar a dica de ferramenta na IU. A tabela fornece alguns exemplos do tipo de dados complexo que pode ser declarado no armazenamento de variáveis.

Tipos de variáveis complexas com exemplos
Tipo	Exemplo
`number`	4.56
`string`	valor de exemplo
`bool`	Não
`map(string)`	{key1 = "value1", key2 = "value2"}
`set(string)`	["olá", "ele"]
`map(number)`	{internal = 8080, external = 2020}
`list(string)`	["us-south", "eu-gb"]
`list`	["valor", 30]
`list(list(string))`	Consulte a lista de exemplos de String.
`list(object({internal = number external = number protocol = string}))`	Consulte a lista de exemplos de objetos.

Exemplo de lista de strings

[
        "test", "env:prod", "env:agent:test"
]

Exemplo de lista de objetos

[
    {
        internal = 8300
        external = 8300
        protocol = "tcp"
    },
    {
        internal = 8301
        external = 8301
        protocol = "ldp"
    }
]

Armazenando seus modelos do Terraform

Seus arquivos de configuração do Terraform contêm o código de infraestrutura que deve ser tratado como código regular. Para facilitar a colaboração, o controle de código-fonte e o controle de versões, armazene seus arquivos em um repositório do GitHub ou do GitLab. Com o controle de versão, é possível reverter para versões anteriores, auditar mudanças e compartilhar o código com diversas equipes. Se você não quiser armazenar seus arquivos em GitHub,, forneça seu modelo fazendo o upload de um arquivo de arquivamento em fita ou de um arquivo do tipo “ .tar ” a partir do seu computador local. Se você quiser clonar, consulte as extensões de arquivo permitidas e bloqueadas para clonagem.

A estrutura de diretório do modelo do Terraform no repositório do GitHub está listada na tabela com a duração de atualização mais recente.

Estrutura de diretório do modelo Terraform
Arquivo	Descrição
README.md	Criar README.md
`main.tf`	Criar `main.tf`
`output.tf`	Criar `output.tf`
`provider.tf`	Criar `provider.tf`
`variables.tf`	Criar `variables.tf`

Exemplos de soluções do Terraform

Várias soluções mostram a força dos serviços IBM Cloud® Schematics e IBM Cloud® quando usados em conjunto. Essas soluções usam um modelo ou módulo simples do Terraform para configurar a infraestrutura. Mesmo que cada solução seja apresentada por meio das lentes de um caso de uso específico, essas infraestruturas são típicas em vários setores.

Use os Modelos da solução Terraform publicados por meio do IBM Cloud Schematics para criar sua infraestrutura, gerenciar os recursos e usar ferramentas potentes para proteger, gerenciar e monitorar sua área de trabalho e ações.

Criando modelos Terraform

Criando modelos Terraform

Configurando o bloco provider

Adicionando recursos da nuvem ao bloco “ resource ”

Referenciando recursos em outros blocos de recursos

Gerenciando recursos em outra conta

Usando blocos variable para customizar recursos

Referenciando variáveis

Aproveitamento do Terraform IBM Modules para um desenvolvimento mais rápido

Exemplo: Usando o módulo VPC da TIM

Fornecendo às variáveis declaradas valores a serem usados pelo IBM Cloud Schematics

Exemplo de lista de strings

Exemplo de lista de objetos

Armazenando seus modelos do Terraform

Exemplos de soluções do Terraform

Configurando o bloco `provider`

Adicionando recursos da nuvem ao bloco “ `resource` ”

Usando blocos `variable` para customizar recursos