Create and upload a blueprint
Stay organized with collections Save and categorize content based on your preferences.

A blueprint is a Terraform configuration packaged as an Open Container Initiative (OCI) image. The Terraform configuration specifies the infrastructure and application that SaaS Runtime deploys onto Google Cloud.

This page describes how to create an OCI image from existing Terraform configurations, and how to upload these to SaaS Runtime.

For details about these Terraform configurations, see Blueprints in SaaS Runtime.

Before you begin

Ensure you have enabled SaaS Runtime.
In the project that you are using for SaaS Runtime, ensure you have an Artifact Registry repository that is set to the Docker format. For more details, see Create a repository for SaaS Runtime.
Identify the Terraform configurations that you want to deploy using SaaS Runtime.
- For details about how to decide how to model the SaaS offering using blueprints, see Determine the model of the SaaS offering
- For details about the requirements for the Terraform configuration, see Blueprint requirements.

Create and upload the blueprint

To deploy the Terraform configurations onto Google Cloud using SaaS Runtime, you need to:

Package the Terraform configurations into OCI images. These OCI images are called blueprints.
Put these OCI images in the Artifact Registry repository you identified or set up.

Depending on how you choose to create and upload the blueprint, you can do all of the steps manually, or SaaS Runtime can perform some of the steps.

You can create the OCI image and upload it to the repository using any of the following methods:

Upload a zip archive that contains the Terraform configuration. SaaS Runtime uses the zip archive to create the OCI image.

See details in the following section: Upload a zip archive.
Connect a Git repository that has the Terraform files. SaaS Runtime uses the files to create the OCI image. SaaS Runtime then uses Cloud Build to build and upload the blueprint whenever you update your repository.

See details in the following section: Connect to a Git repository.
Build the OCI image locally and push the image to the repository in Artifact Registry.

See details in the following section: Build and push an image manually.
Automate the creation and push of the OCI image to a repository in Artifact Registry. Automating this process helps you incorporate SaaS Runtime into a CI/CD pipeline.

See details in the following section: Automate blueprint creation.

Upload a zip archive

You can create a zip archive of the Terraform files. You upload this archive to SaaS Runtime when you create a release or a unit kind. SaaS Runtime uses the zip archive to create the required OCI image.

To provide a blueprint using a zip archive, do the following:

Navigate to your Terraform project directory.
Create a zip archive containing the Terraform configuration.
- Ensure that:
  - The zip archive contains only your Terraform files. For example, main.tf, variables.tf, outputs.tf, versions.tf, and modules.
  - The zip archive does not contain unnecessary files, for example .git directories, or a dockerfile.
- The command to create a zip archive might look similar to this: zip terraform-files.zip main.tf outputs.tf variables.tf versions.tf
Upload the zip archive when you create a release, or when you create a unit kind.

SaaS Runtime uses the zip archive to create the required OCI image, and pushes it to the Artifact Registry repository.

Connect to a Git repository

If you store your Terraform configuration in a Git repository, then you can connect SaaS Runtime to this repository. SaaS Runtime uses the files to create the required OCI image when you create a unit kind or create a release.

To provide a blueprint using a Git repository, do the following:

Ensure your Terraform files are located in the root directory of your Git repository.
Connect your Git repository to SaaS Runtime when you create a release, or when you create a unit kind.

SaaS Runtime uses Developer Connect to connect to the Git repository. For more details about Developer Connect, see the Developer Connect documentation.

SaaS Runtime uses the Terraform files from the Git repository to create the required OCI image, and pushes it to the Artifact Registry repository.

This integration automates the blueprint creation process whenever you update your Terraform code in your repository. When there are changes in the linked Git repository, SaaS Runtime uses the changed files to automatically build a new OCI image and then pushes it to the Artifact Registry repository.

Build and push an image manually

This method gives you fine-grained control over the blueprint creation process.

To create a blueprint manually, do the following steps:

In the root directory of your Terraform files, create a file named Dockerfile with the following content:
```
# syntax=docker/dockerfile:1-labs
FROM scratch
COPY --exclude=Dockerfile --exclude=.git --exclude=.gitignore . /
```
This Dockerfile uses a minimal base image (scratch). Consider including dockerignore to the command to exclude files that are not relevant, such as:
- the Dockerfile itself
- the .git directory
- the .gitignore file
If you don't have a Docker builder, then create a docker-container builder using docker buildx by using the following command:
```
docker buildx create --name container --driver=docker-container
```

Run the following docker buildx build command from your Terraform directory to build and push the blueprint to 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 .

Replace the following:

PROJECT_ID: Your project ID.
REPOSITORY_NAME: The name of your Artifact Registry repository.
IMAGE_NAME: A name for your blueprint image.
TAG: A tag for your image version (for example, latest, or v1.0.0). Choosing a descriptive tag helps you effectively manage versions of the blueprint.
TERRAFORM_VERSION: the supported version of Terraform to use. See Supported Terraform versions for the list of versions supported by Infrastructure Manager.

A command might look similar to the following example:

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 .

The OCI image is in the Artifact Registry repository.

To use this image with SaaS Runtime, select this image when you create a release, or when you create a unit kind.

Automate blueprint creation

You can automate the creation of the OCI image and the push to Artifact Registry by using Cloud Build. You can set up a trigger so that whenever the Terraform code is changed, the OCI image is automatically built and pushed to Artifact Registry.

To set up this automation, do the following:

In the root of your Terraform repository, create a cloudbuild.yaml file with the following configuration:

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