Skip to main content

​
Overview

A Blueprint is a versioned, ready-to-use template for a single piece of infrastructure — a managed database, an object storage bucket, a cache, a message broker, a CDN distribution, or a third-party SaaS resource such as a Snowflake database or a MongoDB Atlas cluster. Instead of writing Terraform or Helm from scratch, you browse Qovery’s catalog, pick a blueprint and version, fill in a short form, and Qovery provisions the resource as a fully managed service inside one of your environments. Blueprints turn infrastructure provisioning into governed self-service. The platform team curates which templates are available, and role-based access control governs who can deploy them. Developers — and AI agents working through the API — provision what they need without a review queue, and without direct access to the underlying cloud account. Behind the scenes, a blueprint materializes as a standard Qovery Terraform (or OpenTofu) service or Helm service. The service stays linked to the blueprint, so Qovery can later tell you when a newer version of the template is available, show you the diff, and apply the upgrade. The catalog is maintained by Qovery in the public Qovery/service-catalog repository and grows over time.
“Blueprint” is used for a few different things in Qovery. This page is about catalog-based infrastructure and service templates. It is not the same as:

​
Where a blueprint provisions

Blueprints come from three kinds of source — cloud provider, Helm, and External — and the source decides what the resource runs on and how it authenticates.

​
What’s in the catalog

The catalog is expanding — catalog.json in the repository is the source of truth, and the Console groups blueprints by the categories below.

​
Databases & Caches

​
Messaging & Streaming

​
Storage

​
Networking & Edge

​
Compute & Runtime

​
AI & Analytics

​
Observability

​
How Blueprints Work

When you create a blueprint service, you fill in a short form built from the blueprint’s template: the variables it exposes (with defaults, dropdowns, and validation), while read-only context variables such as the cluster region and name are resolved automatically. Qovery then provisions the resource on your cluster as a managed Terraform (or OpenTofu) service or Helm service and links it to the blueprint. Once deployed, the service publishes its outputs — endpoints, ports, credentials — so other services in the same environment can consume them through variable interpolation, just like any other Qovery service. Outputs marked sensitive (passwords, tokens) are stored encrypted and hidden in the Console. Blueprints are versioned: you pick a version when you create the service, and Qovery flags when a newer one is available (see Updating a Blueprint).

​
Browsing the Catalog

1

Open the service creation flow

In the Qovery Console, open the environment where you want the resource, then start creating a new service and choose Blueprint (create from catalog).
2

Pick a blueprint

Browse the catalog by category (databases & caches, messaging & streaming, storage, networking & edge, compute & runtime, AI & analytics, observability) and select the blueprint you need. Cloud-provider blueprints are filtered to the target cluster’s provider; External blueprints show up on every cluster.
3

Choose a version

Select the major version (for example PostgreSQL 17). Qovery uses the latest released tag for that major version.
Blueprint catalog in the Qovery Console
Each blueprint ships with a README describing the resource it provisions and its variables. Read it before deploying so you know which inputs are required.

​
Creating a Blueprint Service

1

Fill in the variables

Complete the form generated from the blueprint’s manifest. Required variables are marked; optional ones fall back to their defaults. Variables constrained to a set of values render as dropdowns, and secret variables (passwords, keys) render as password fields and are stored encrypted.
Context variables such as the cluster region and name are filled in automatically from the target environment’s cluster — you don’t set them.
For an External blueprint, the vendor credentials are part of this form — for example the Snowflake account identifier, user, and PEM-encoded private key, or the Cloudflare API token. Create the vendor-side service account first; the blueprint does not create it for you.
2

Review advanced settings (optional)

Some blueprints let you override engine-level settings the template author marked as overridable — for example the Terraform/OpenTofu version, credentials mode, state backend, or compute resources. See Variables & Engine Reference. If a setting is not overridable, the blueprint’s default applies.
3

Create, and optionally deploy

Create the blueprint service. You can create it and deploy immediately, or create it first and deploy later from the service like any other Qovery service.
Blueprint variables form

​
Variables & Engine Reference

​
Variables

Variables are the editable inputs a blueprint exposes. Each is described in the manifest and rendered in the form.

​
Context variables

Context variables are read-only and resolved automatically from the target environment’s cluster. You cannot edit them.

​
Outputs

Outputs are the values the deployed service publishes back to Qovery — endpoints, ports, bucket names, generated credentials. Other services in the same environment consume them by variable interpolation, so an application can point at a blueprint-provisioned database without anyone copying a hostname by hand. Sensitive outputs are encrypted and masked in the Console.

​
Engine & advanced settings

The engine block defines how the resource is provisioned. Which settings you can override is controlled by the blueprint author (via overridable and allowed_values in the manifest).
For Helm blueprints, engine version, credentials, and state backend do not apply — the chart and its version are defined by the blueprint, and the resources block is ignored because the chart declares its own.

​
Updating a Blueprint

When Qovery maintains a newer version of a blueprint’s template, the linked service surfaces an available update. Qovery compares your current tag to the latest catalog tag and reports exactly what changed:
  • New variables — added as optional or required.
  • Now-required variables — previously optional variables that are now required.
  • Updated variables — changed defaults, allowed values, or constraints.
  • Removed variables — no longer used by the template.
  • Engine changes — version or resource changes.
  • New major versions — a newer major version of the underlying service (for example PostgreSQL 16 → 17).
Upgrading is a two-step, safe workflow:
1

Preview

Run a preview — a dry run that produces a terraform plan-style diff of the actual infrastructure and streams it into the Console. Preview makes no changes.
Blueprint update preview diff
2

Apply

If the diff looks correct, apply the update. Qovery deploys the linked service with the new configuration.
Applying an update changes live infrastructure. Always review the preview diff before applying — some changes (for example a storage or instance-class change on a managed database) can be disruptive.

​
Migrating a Managed Database to a Blueprint

An existing Qovery managed database can be migrated to blueprint-backed provisioning. Terraform adopts the running instance — no re-provisioning, no data movement, no change of endpoint or password — and the Qovery database is converted rather than deleted, so applications keep the connection environment variables they already use. Afterwards the resource is an ordinary blueprint service: versioned template, preview-then-apply update path, and access to every variable the template exposes.
Migration is not self-service. It is run by the Qovery team together with you. To start one, reach out directly in the product (help button in the Console, or your dedicated Slack channel).

​
What can be migrated

​
How a migration runs

1

You get in touch

Tell us which database you want migrated. We confirm eligibility and check that the cluster is on an engine version able to plan the target catalog template.
2

Preview

Qovery runs a preview: a terraform plan against the live instance with the connection details, sizing, and storage settings read from your existing database. A safety gate rejects any plan that would replace or destroy the instance, and nothing is persisted unless the plan is clean. We review the diff with you.
3

Apply

Once you approve the plan, we apply it. The blueprint service is created, it imports the live instance, and the Qovery database converts to blueprint-backed provisioning.
Applying a migration is irreversible — there is no rollback endpoint. Review the preview diff carefully and take a database backup before approving. New resources do not need any of this: create them directly from the catalog as described above.

​
Permissions

Creating, updating, and deploying a blueprint requires the Manager role on the target environment. Access follows Qovery’s standard role-based access control — see Members & RBAC. Migrating an existing managed database is a Qovery-side operation and is not exposed to organization members; every attempt is recorded in the organization audit logs.

​
Best Practices

When creating a new blueprint service, use the latest released version so you start on a supported, up-to-date template.
Run a preview and read the diff before applying any blueprint update. It’s the only way to see exactly what will change in your live infrastructure.
Use the Qovery-managed Terraform backend unless you have a specific reason to bring your own. Qovery handles state storage, locking, and safety for you.
Mark passwords, tokens, and keys as secret variables so they’re stored encrypted and hidden in the Console. This matters most for External blueprints, where the vendor credentials live in the form.
Create a dedicated vendor-side service account per blueprint service, limited to what the template provisions, rather than reusing an administrator token.
Wire applications to a blueprint’s published outputs. A later update that changes an endpoint then propagates on its own.
For anything the catalog covers, a blueprint gives you a maintained, versioned template with a built-in upgrade path — less to write and less to keep current yourself.

​
API Reference

Blueprints are fully scriptable through the Qovery API. The endpoints live under the Blueprint Catalog and Blueprint Main Calls tags and cover:
  • Listing the catalog, and reading a blueprint’s README and manifest (the form fields the Console renders).
  • Creating a blueprint in an environment, with or without an immediate deploy.
  • Creating a blueprint and getting back the deployment identifiers of the dispatch it started, so a script can follow the provisioning run.
  • Reading a blueprint together with the underlying Terraform or Helm service and the status of its latest dispatch.
  • Checking for an available update, previewing it, saving new values, and deploying.
See the API Reference.

​
Next Steps

Databases

Compare blueprint-provisioned databases with Qovery’s container and managed database options.

Object Storage

Learn about object storage on Qovery.

Terraform Services

Understand the Terraform service that backs a blueprint.

Members & RBAC

Control who can create and manage blueprints.