Configurar a imagem de VM para implantação do Terraform

Neste artigo, descrevemos como concluir a configuração e o envio da imagem de VM para implantação usando o Terraform.

Determinar como criar o pacote de implantação

Recomendamos que você use a opção de configuração guiada do Portal do Produtor para criar seu pacote de implantação diretamente no console do Google Cloud.

A opção de configuração guiada oferece suporte a produtos de VM simples, como implantações de VM única com regras básicas de firewall, mas não oferece suporte a alguns recursos complexos, como implantações com várias VMs e recursos que não são de computação. Se você precisar de recursos incompatíveis com a configuração guiada, use a opção de configuração manual para criar o pacote de implantação ou personalizar um pacote existente adicionando outros recursos a ele.

Alternar entre a configuração guiada e a configuração manual

Se você usar a opção de configuração guiada do Portal do Produtor e quiser mudar para a configuração manual do pacote de implantação, clique em Ir para configuração manual.

Concluir a configuração guiada

Para concluir a configuração e o envio de um pacote de implantação simples usando o console do Google Cloud, siga estas etapas:

No Portal do Produtor, acesse a seção Pacote de implantação.
Em Configuração do Terraform, ao lado do campo de entrada rotulado como bucket do Cloud Storage, clique em Procurar.

Se você já criou um bucket do Cloud Storage, selecione-o aqui.

Se você não tiver um bucket do Cloud Storage, clique no ícone Criar novo bucket. Após criar um novo bucket, siga estas etapas:
- Selecione um nome para o bucket.
- Especifique em qual região ou regiões o bucket armazena dados.
- Especifique a classe de armazenamento dos seus dados.
- Determine o nível de granularidade a ser aplicado às permissões do Identity and Access Management (IAM) para os dados do bucket.
- Defina configurações avançadas opcionais, como criptografia ou políticas de retenção de dados.
Verifique se você ativou o controle de versões de objetos para o bucket do Cloud Storage.
Para salvar as configurações do bucket e continuar a definir o pacote de implantação, clique em Configurar.
Em Escolher o tipo de máquina, especifique uma Zona padrão, um Tipo mínimo de máquina e um Tipo de máquina padrão para o produto de VM, assim como o tamanho e o tipo do disco de inicialização dele.
Em Especificar o sistema operacional, especifique o nome e a versão do SO que a imagem de VM usa, bem como o número da versão da imagem de VM.
Opcionalmente, em Configurar acesso à VM, especifique os URLs do site e do administrador, além de um nome de usuário e uma senha, que os usuários poderão usar para acessar a VM após a implantação.
Opcionalmente, em Configurar rede, especifique configurações para Encaminhamento de IP e defina regras de Firewall.
Opcionalmente, em Definir as próximas etapas, é possível fornecer instruções para os usuários do seu produto orientá-los sobre como começar a usar o produto. Estas instruções vão aparecer para eles após a implantação do produto.
Depois de concluir as etapas anteriores, clique em Gerar para criar o pacote de implantação.

Se você precisar fazer outras alterações no pacote de implantação mais tarde, clique em Editar para fazer alterações e, em seguida, clique em Gerar para gerar novamente o pacote de implantação com essas alterações.
Envie o pacote de implantação para análise no Portal do Produtor. Depois do envio, pode levar até duas semanas para que o Google o analise e aprove.

Concluir a configuração manual

Nesta seção, explicamos como usar a opção de configuração manual para criar um pacote de implantação e enviá-lo para revisão.

Especifique se você quer usar o módulo padrão ou personalizado do Terraform

Escolha se quer que os clientes usem o módulo padrão ou personalizado do Terraform ao implantar o produto.

Se você optar por usar o módulo padrão do Terraform, o Google Cloud fornecerá aos clientes um código do Terraform gerado automaticamente que eles podem usar para implantar seu produto.

Se você usar um módulo personalizado do Terraform, vai precisar fornecer seus próprios modelos do Terraform ao cliente. É possível fornecer esses modelos em um formato que os clientes possam implantar usando a interface de linha de comando (CLI) ou com metadados extras que permitam que os clientes implantem módulos diretamente do Cloud Marketplace.

Para especificar se os clientes precisam usar o módulo do Terraform padrão ou personalizado e, para módulos do Terraform personalizados, como você quer que os clientes implantem o módulo, conclua as seguintes etapas:

No Portal do Produtor, acesse a seção Pacote de implantação.
Em Terraform configuration, em Tipo, selecione Padrão, Personalizado (implantação da CLI) ou Personalizado (implantação da UI).

Requisitos para módulos personalizados do Terraform

Se você optar por usar módulos personalizados do Terraform, eles precisam atender aos seguintes requisitos:

O módulo personalizado precisa ter um que o Cloud Marketplace possa usar para verificar se ele atende aos requisitos. Para mais informações, consulte Testar se o módulo foi aprovado na verificação.
Seu módulo precisa ter uma variável chamada project_id, que armazena o ID do projeto que seus clientes usam para implantar o módulo.
É preciso especificar referências aos nomes das imagens como variáveis do Terraform, com o formato projects/PROJECT_NAME/global/images/IMAGE_NAME. O valor de default precisa ser definido como o nome da imagem de VM para que a cópia da imagem do Cloud Marketplace possa ser substituída no módulo quando o produto de VM for publicado.
Seu módulo não pode depender de módulos externos que não estão empacotados com ele.
Seu módulo precisa usar apenas os seguintes provedores aprovados:
- archive
- cloud-init
- dns
- google
- google-beta
- http
- null
- random
- time
- tls

Para conferir um exemplo de módulo personalizado em conformidade com esses requisitos, acesse o exemplo de módulo personalizado do Terraform (link em inglês).

Outros requisitos para módulos personalizados do Terraform para implantação UI

Se o módulo personalizado for compatível com a implantação UI, ele precisará atender aos seguintes requisitos extras:

Seu módulo precisa conter uma variável com o nome goog_cm_deployment_name. O Cloud Marketplace usa essa variável para nomear as implantações dos clientes na página de implantação deles. Use essa variável para evitar colisões de nomes de recursos entre várias implantações em um projeto. Para conferir um exemplo, consulte goog_cm_deployment_name no exemplo de módulo personalizado do Terraform.
No arquivo metadata.display.yaml, especifique ET_GCE_DISK_IMAGE como o tipo xGoogleProperty para todas as variáveis de imagem. Para ver um exemplo, consulte metadata.display.yaml no exemplo de módulo personalizado do Terraform.
Se o produto contém imagens de várias VMs ou imagens compatíveis com várias arquiteturas de CPU, adicione enumValueLabels para que os clientes possam selecionar a imagem de VM que querem usar. Para conferir um exemplo, consulte o exemplo de módulo personalizado do Terraform.
O módulo não pode depender do suporte para provisionadores do Terraform.

Etapas adicionais para módulos personalizados do Terraform

Se você optou por usar módulos personalizados do Terraform, conclua as seguintes etapas extras para configurar a imagem de VM para implantação:

No Portal do Produtor, acesse a seção Pacote de implantação.
Em Configuração do Terraform, em Variáveis de imagem, clique em Adicionar variável.

Para ativar a implantação do Terraform do seu produto, é preciso ativar o uso de imagens de propriedade do Marketplace. O Cloud Marketplace usa a variável adicionada aqui para trocar a versão da imagem de VM no Marketplace quando um cliente implanta o produto.
No campo de texto Variável de imagem, insira um nome para sua variável, como "imagem".
No módulo personalizado do Terraform, defina o valor padrão da variável criada na etapa anterior como o nome da imagem de VM do produto, no formato projects/YOUR_PROJECT/global/images/YOUR_IMAGE.
Em Especificar o local do objeto do GCS, clique em Procurar.

Se você já criou um bucket do Cloud Storage, selecione-o aqui.

Se você não tiver um bucket do Cloud Storage, clique no ícone rotulado Criar novo bucket. Após criar um novo bucket, siga estas etapas:
- Selecione um nome para o bucket.
- Especifique em qual região ou regiões o bucket armazena dados.
- Especifique a classe de armazenamento dos seus dados.
- Determine o nível de granularidade a ser aplicado às permissões de gerenciamento de identidade e acesso (IAM) para os dados do bucket.
- Defina configurações avançadas opcionais, como criptografia ou políticas de retenção de dados.
Verifique se o Controle de versão do objeto está ativado no bucket do Cloud Storage.
Para salvar as configurações do bucket e continuar a configurar o pacote de implantação, clique em Configurar.
Em Papéis obrigatórios, especifique os papéis do IAM que seus clientes precisam ter para implantar seu produto.

(Apenas implantação UI) Criar metadados para seu módulo personalizado do Terraform

Para que o módulo personalizado seja compatível com a implantação da UI, você precisa criar e adicionar metadados que o Cloud Marketplace usa para analisar corretamente o módulo e renderizá-lo na UI para o cliente.

Para criar e adicionar esses metadados, use a ferramenta de código aberto da CLI do CFT. Para usar o CFT na criação e adição de metadados aos módulos personalizados, conclua as seguintes etapas:

Instale a ferramenta CLI do CFT. Para mais informações, acesse a documentação da CLI do CFT. Recomendamos que você especifique o valor de VERSION como latest e defina PLATFORM como um dos seguintes valores:
- linux
- windows
- darwin
Execute este comando:
```
 cft blueprint metadata -p TF_PACKAGE_PATH -q -d --nested=false
```
No comando anterior, a sinalização -p fornece um caminho para o pacote do Terraform, a sinalização -q gera metadados sem precisar de informações de um repositório remoto, a sinalização -d gera o arquivo metadata.display.yaml e a sinalização --nested=false gera metadados para o módulo raiz, ignorando todos os módulos na pasta modules/.

Depois de concluir as etapas anteriores, a ferramenta CLI do CFT gera dois novos arquivos: metadata.yaml e metadata.display.yaml.

Personalizar os metadados do módulo personalizado do Terraform

O Cloud Marketplace usa o arquivo metadata.display.yaml para personalizar o formulário que os clientes usam para implantar o produto pela UI. Se você quiser personalizar esse formulário, depois de criar os metadados, poderá alterar os valores dos campos em metadata.display.yaml. Para detalhes sobre as opções de personalização disponíveis, acesse a documentação de código aberto do BlueprintUI ou consulte o esquema do BlueprintUI.

Recomendamos que você use a extensão GooglePropertyExtensions para alterar seus metadados. GooglePropertyExtensions permite usar validações específicas do Google Cloud, como garantir que os clientes possam selecionar apenas redes de nuvem privada virtual (VPC) que já existem no projeto. Para conferir um exemplo, consulte o exemplo de módulo personalizado do Terraform.

Validar os metadados do módulo personalizado

Para validar os metadados do seu módulo personalizado, execute o seguinte comando:

cft blueprint metadata -p TF_PACKAGE_PATH -v

No comando anterior, a sinalização -p fornece um caminho para o pacote do Terraform, e a sinalização -v valida todos os arquivos de metadados no caminho fornecido com base no esquema BlueprintMetadata.

Testar se o módulo foi aprovado na verificação

O módulo personalizado será aprovado na verificação se o comando a seguir for executado com êxito:

terraform plan -var project_id=YOUR_PROJECT -var-file marketplace_test.tfvars

No comando anterior, marketplace_test.tfvars é um arquivo de variáveis do Terraform que apenas o Cloud Marketplace usa, exclusivamente para esta verificação do módulo. Se o modelo declarar alguma variável que não tenha um valor padrão e você não definir um valor para elas, o comando não será executado com êxito. Para garantir que o comando seja executado com êxito, crie um arquivo marketplace_test.tfvars para definir valores para as variáveis declaradas pelo modelo. Para um exemplo de arquivo marketplace_test.tfvars, consulte o exemplo de módulo personalizado do Terraform.

(Opcional) (somente implantação da CLI) Incluir um módulo de teste

Caso seu módulo personalizado seja compatível com a implantação da CLI, será possível incluir uma pasta chamada examples/marketplace_test. Faça isso se o produto precisar incluir um módulo de teste separado para verificar os recursos. Se você incluir essa pasta, para que o módulo seja aprovado na verificação, o comando a seguir precisará ser executado com êxito:

terraform -chdir=examples/marketplace_test plan -var project_id=YOUR_PROJECT

Enviar o pacote de implantação para análise

Depois de criar e configurar o pacote de implantação, é preciso enviá-lo ao Portal do Produtor para que a equipe do Cloud Marketplace possa analisá-lo e aprová-lo.

No Portal do Produtor, acesse a seção Pacote de implantação.
Clique em Validate (Validar). O processo de validação pode levar até duas horas para ser concluído, e é possível sair da tela enquanto ele é concluído.
Após a validação ser concluída, clique em Enviar para enviar o pacote de implantação para análise. Depois de enviar o pacote, pode levar até duas semanas para que o Google o analise e aprove.

Como criar sua imagem de VM

Configurar a imagem da VM para implantação do Deployment Manager