Criar e fazer upload de um blueprint

Um blueprint é uma configuração do Terraform empacotada como uma imagem da Open Container Initiative (OCI). A configuração do Terraform especifica a infraestrutura e o aplicativo que o ambiente de execução de SaaS implanta Google Cloud.

Esta página descreve como criar uma imagem OCI com base em configurações do Terraform e como fazer upload delas para o ambiente de execução de SaaS.

Para mais detalhes sobre essas configurações do Terraform, consulte Blueprints no ambiente de execução de SaaS.

Antes de começar

Verifique se o ambiente de execução de SaaS está ativado.
No projeto que você está usando para o ambiente de execução de SaaS, verifique se você tem um repositório do Artifact Registry definido como formato do Docker. Para mais detalhes, consulte Criar um repositório para o ambiente de execução de SaaS.
Identifique as configurações do Terraform que você quer implantar usando o ambiente de execução de SaaS.
- Para detalhes sobre como decidir como modelar a oferta de SaaS usando blueprints, consulte Determinar o modelo da oferta de SaaS
- Para detalhes sobre os requisitos da configuração do Terraform, consulte Requisitos do blueprint.

Criar e fazer upload do blueprint

Para implantar as configurações do Terraform usando o ambiente de execução de SaaS, é necessário: Google Cloud

Empacotar as configurações do Terraform em imagens OCI. Essas imagens OCI são chamadas de blueprints.
Colocar essas imagens OCI no repositório do Artifact Registry que você identificou ou configurou.

Dependendo de como você escolhe criar e fazer upload do blueprint, é possível realizar todas as etapas manualmente ou o ambiente de execução de SaaS pode realizar algumas delas.

É possível criar a imagem OCI e fazer upload dela para o repositório usando qualquer um dos seguintes métodos:

Fazer upload de um arquivo ZIP que contenha a configuração do Terraform. O ambiente de execução de SaaS usa o arquivo ZIP para criar a imagem OCI.

Consulte os detalhes na seção a seguir: Fazer upload de um arquivo ZIP.
Conectar um repositório Git que tenha os arquivos do Terraform. O ambiente de execução de SaaS usa os arquivos para criar a imagem OCI. Em seguida, o ambiente de execução de SaaS usa o Cloud Build para criar e fazer upload do blueprint sempre que você atualiza o repositório.

Consulte os detalhes na seção a seguir: Conectar a um repositório Git.
Criar a imagem OCI localmente e enviar a imagem para o repositório no Artifact Registry.

Consulte os detalhes na seção a seguir: Criar e enviar uma imagem manualmente.
Automatizar a criação e o envio da imagem OCI para um repositório no Artifact Registry. A automação desse processo ajuda a incorporar o ambiente de execução de SaaS em um pipeline de CI/CD.

Consulte os detalhes na seção a seguir: Automatizar a criação de blueprints.

Fazer upload de um arquivo ZIP

É possível criar um arquivo ZIP dos arquivos do Terraform. Você faz upload desse arquivo para o ambiente de execução de SaaS ao criar uma versão ou um tipo de unidade. O ambiente de execução de SaaS usa o arquivo ZIP para criar a imagem OCI necessária.

Para fornecer um blueprint usando um arquivo ZIP, faça o seguinte:

Navegue até o diretório do projeto do Terraform.
Crie um arquivo ZIP que contenha a configuração do Terraform.
- Verifique se:
  - O arquivo ZIP contém apenas os arquivos do Terraform. Por exemplo, main.tf, variables.tf, outputs.tf, versions.tf e módulos.
  - O arquivo ZIP não contém arquivos desnecessários, por exemplo, diretórios .git ou um Dockerfile.
- O comando para criar um arquivo ZIP pode ser semelhante a este: zip terraform-files.zip main.tf outputs.tf variables.tf versions.tf
Faça upload do arquivo ZIP ao criar uma versão ou ao criar um tipo de unidade.

O ambiente de execução de SaaS usa o arquivo ZIP para criar a imagem OCI necessária e a envia para o repositório do Artifact Registry.

Conectar a um repositório Git

Se você armazenar a configuração do Terraform em um repositório Git, poderá conectar o ambiente de execução de SaaS a esse repositório. O ambiente de execução de SaaS usa os arquivos para criar a imagem OCI necessária ao criar um tipo de unidade ou uma versão.

Para fornecer um blueprint usando um repositório Git, faça o seguinte:

Verifique se os arquivos do Terraform estão localizados no diretório raiz do repositório Git.
Conecte o repositório Git ao ambiente de execução de SaaS ao criar uma versão ou ao criar um tipo de unidade.

O ambiente de execução de SaaS usa o Developer Connect para se conectar ao repositório Git. Para mais detalhes sobre o Developer Connect, consulte a documentação do Developer Connect.

O ambiente de execução de SaaS usa os arquivos do Terraform do repositório Git para criar a imagem OCI necessária e a envia para o repositório do Artifact Registry.

Essa integração automatiza o processo de criação de blueprints sempre que você atualiza o código do Terraform no repositório. Quando há mudanças no repositório Git vinculado, o ambiente de execução de SaaS usa os arquivos alterados para criar automaticamente uma nova imagem OCI e a envia para o repositório do Artifact Registry.

Criar e enviar uma imagem manualmente

Esse método oferece controle refinado sobre o processo de criação de blueprints.

Para criar um blueprint manualmente, siga estas etapas:

No diretório raiz dos arquivos do Terraform, crie um arquivo chamado Dockerfile com o seguinte conteúdo:
```
# syntax=docker/dockerfile:1-labs
FROM scratch
COPY --exclude=Dockerfile --exclude=.git --exclude=.gitignore . /
```
Esse Dockerfile usa uma imagem de base mínima (scratch). Considere incluir dockerignore no comando para excluir arquivos que não são relevantes, como:
- o próprio Dockerfile
- o diretório .git
- o arquivo .gitignore
Se você não tiver um builder do Docker, crie um builder docker-container usando docker buildx com o seguinte comando:
```
docker buildx create --name container --driver=docker-container
```

Execute o seguinte comando docker buildx build no diretório do Terraform para criar e enviar o blueprint para o Artifact Registry:

IMAGE_NAME=us-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME:TAG
ENGINE_TYPE=inframanager
ENGINE_VERSION=TERRAFORM_VERSION

docker buildx build -t $IMAGE_NAME \
  --builder=container \
  --push \
  --annotation "com.easysaas.engine.type=$ENGINE_TYPE" \
  --annotation "com.easysaas.engine.version=$ENGINE_VERSION" \
  --provenance=false .

Substitua:

PROJECT_ID: o ID do projeto.
REPOSITORY_NAME: o nome do repositório do Artifact Registry.
IMAGE_NAME: um nome para a imagem do blueprint.
TAG: uma tag para a versão de imagem (por exemplo, latest ou v1.0.0). Escolher uma tag descritiva ajuda a gerenciar versões do blueprint de maneira eficaz.
TERRAFORM_VERSION: a versão compatível do Terraform a ser usada. Consulte Versões compatíveis do Terraform para conferir a lista de versões compatíveis com o Infrastructure Manager.

Um comando pode ser semelhante ao exemplo a seguir:

IMAGE_NAME=us-docker.pkg.dev/saas-docs-testing/blueprints-repo/my-terraform-blueprint:v1.0.0
ENGINE_TYPE=inframanager
ENGINE_VERSION=1.5.7

docker buildx build -t $IMAGE_NAME \
  --builder=container \
  --push \
  --annotation "com.easysaas.engine.type=$ENGINE_TYPE" \
  --annotation "com.easysaas.engine.version=$ENGINE_VERSION" \
  --provenance=false .

A imagem OCI está no repositório do Artifact Registry.

Para usar essa imagem com o ambiente de execução de SaaS, selecione-a ao criar uma versão, ou ao criar um tipo de unidade.

Automatizar a criação de blueprints

É possível automatizar a criação da imagem OCI e o envio para o Artifact Registry usando o Cloud Build. É possível configurar um gatilho para que, sempre que o código do Terraform for alterado, a imagem OCI seja criada e enviada automaticamente para o Artifact Registry.

Para configurar essa automação, faça o seguinte:

Na raiz do repositório do Terraform, crie um arquivo cloudbuild.yaml com a seguinte configuração:

steps:
- id: 'Create Dockerfile'
  name: 'bash'
  args: ['-c', 'echo -e "# syntax=docker/dockerfile:1-labs\nFROM scratch\nCOPY --exclude=Dockerfile.Blueprint --exclude=.git --exclude=.gitignore . /" > Dockerfile.Blueprint']
- id: 'Create docker-container driver'
  name: 'docker'
  args: ['buildx', 'create', '--name', 'container', '--driver=docker-container']
- id: 'Build and Push docker image'
  name: 'docker'
  args: ['buildx', 'build', '-t', '${_IMAGE_NAME}', '--builder=container', '--push', '--annotation', 'com.easysaas.engine.type=${_ENGINE_TYPE}','--annotation', 'com.easysaas.engine.version=${_ENGINE_VERSION}', '--provenance=false','-f', 'Dockerfile.Blueprint', '.']
serviceAccount: '${_SERVICE_ACCOUNT}'
substitutions:
  _SERVICE_ACCOUNT: 'projects/PROJECT_ID/serviceAccounts/CLOUD_BUILD_SERVICE_ACCOUNT'
  _IMAGE_NAME: 'us-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME:latest'
  _ENGINE_TYPE: 'inframanager'
  _ENGINE_VERSION: 'TERRAFORM_VERSION'
options:
  logging: CLOUD_LOGGING_ONLY