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 do SaaS implanta em Google Cloud.

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

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

Antes de começar

Verifique se você ativou o ambiente de execução do SaaS.
No projeto que você está usando para o ambiente de execução de SaaS, verifique se há um repositório do Artifact Registry definido no formato Docker. Para mais detalhes, consulte Criar um repositório para o ambiente de execução do SaaS.
Identifique as configurações do Terraform que você quer implantar usando o SaaS Runtime.
- 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 em Google Cloud usando o ambiente de execução de SaaS, é necessário:

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

Dependendo de como você cria e faz upload do blueprint, é possível realizar todas as etapas manualmente ou deixar que o ambiente de execução de SaaS faça algumas delas.

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

Faça upload de um arquivo zip que contenha a configuração do Terraform. O SaaS Runtime usa o arquivo ZIP para criar a imagem OCI.

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

Confira detalhes na seção a seguir: Conectar a um repositório Git.
Crie a imagem OCI localmente e envie-a por push para o repositório no Artifact Registry.

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

Confira 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. Faça o upload desse arquivo para o ambiente de execução de SaaS ao criar um lançamento ou um tipo de unidade. O ambiente de execução do 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 com 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, como 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 envia para o repositório do Artifact Registry.

Conectar a um repositório Git

Se você armazenar sua configuração do Terraform em um repositório Git, poderá conectar o ambiente de execução de SaaS a ele. O SaaS Runtime usa os arquivos para criar a imagem OCI necessária quando você cria 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 seu 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 blueprint sempre que você atualiza o código do Terraform no repositório. Quando há mudanças no repositório Git vinculado, o SaaS Runtime usa os arquivos alterados para criar automaticamente uma nova imagem do 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 do blueprint.

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 . /
```
Este Dockerfile usa uma imagem de base mínima (scratch). Considere incluir dockerignore ao comando para excluir arquivos irrelevantes, 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 comando docker buildx build no diretório do Terraform para criar e enviar o blueprint ao 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 da imagem (por exemplo, latest ou v1.0.0). Escolher uma tag descritiva ajuda a gerenciar com eficiência as versões do blueprint.
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 um lançamento 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 do 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