> ## Documentation Index
> Fetch the complete documentation index at: https://qovery-docs-agent-console-2026-09-29.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Blueprints

> Provision managed cloud infrastructure, Kubernetes add-ons, and third-party SaaS resources from Qovery's catalog, no Terraform or Helm required

## 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](/configuration/organization/members-rbac) 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`](https://github.com/Qovery/service-catalog) repository and grows over time.

<Info>
  "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:

  * The **Blueprint Environment** used by [Preview Environments](/configuration/environment#blueprint-environment) — an environment cloned per pull request.
  * The **Blueprint** in the [AI Builder Portal](/rde/admin/blueprint-management) — a workspace template.
</Info>

### 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.

| Source | What it provisions | Credentials |
| - | - | - |
| **AWS / GCP / Scaleway** | A managed resource in the cloud account backing the target cluster (RDS, ElastiCache, S3, Memorystore, Scaleway Managed Database…). | Reuses the cluster's cloud credentials by default. |
| **Helm** | A Kubernetes add-on deployed on the cluster itself, from a curated Helm chart. | Runs in-cluster, no cloud credentials needed. |
| **External** | A third-party SaaS resource provisioned through that vendor's own Terraform provider. Available on **every** cluster regardless of its cloud provider. | You supply the vendor's credentials as secret variables on the service. |

### What's in the catalog

The catalog is expanding — [`catalog.json`](https://github.com/Qovery/service-catalog/blob/main/catalog.json) in the repository is the source of truth, and the Console groups blueprints by the categories below.

#### Databases & Caches

| Blueprint | Source | Versions |
| - | - | - |
| **Amazon RDS for PostgreSQL** | AWS | 14–17 |
| **Amazon RDS for MySQL** | AWS | 8 |
| **Amazon ElastiCache for Redis** | AWS | 7 |
| **Amazon ElastiCache for Valkey** | AWS | 9 |
| **Google Cloud Memorystore for Redis** | GCP | 7 |
| **Scaleway Managed PostgreSQL** | Scaleway | 16 |
| **Scaleway MySQL** | Scaleway | 8 |
| **Redis** | Helm | 8 |
| **MongoDB Atlas Cluster** | External | — |
| **PlanetScale Database** | External | — |
| **Timescale Cloud Service** | External | — |

#### Messaging & Streaming

| Blueprint | Source | Versions |
| - | - | - |
| **Amazon MSK** (Kafka, serverless) | AWS | — |
| **RabbitMQ** | Helm | 4 |
| **Aiven for Apache Kafka** | External | — |
| **Confluent Cloud for Apache Kafka** | External | — |
| **Redpanda Cloud** | External | — |

#### Storage

| Blueprint | Source | Versions |
| - | - | - |
| **Amazon S3** | AWS | — |
| **Scaleway Object Storage** | Scaleway | — |

#### Networking & Edge

| Blueprint | Source | Versions |
| - | - | - |
| **AWS CloudFront** | AWS | — |
| **Cloudflare DNS Zone** | External | — |

#### Compute & Runtime

| Blueprint | Source | Versions |
| - | - | - |
| **Cloudflare Workers** | External | — |
| **Temporal Cloud Namespace** | External | — |

#### AI & Analytics

| Blueprint | Source | Versions |
| - | - | - |
| **AWS Bedrock Access** (scoped IAM policy, optional user and keys) | External | — |
| **Google BigQuery Dataset** | External | — |
| **Snowflake Database** | External | — |

#### Observability

| Blueprint | Source | Versions |
| - | - | - |
| **Datadog** (agent, metrics, logs, optional APM) | Helm | 7 |
| **New Relic** (`nri-bundle`) | Helm | — |

## 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](#updating-a-blueprint)).

## Browsing the Catalog

<Steps>
  <Step title="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).
  </Step>

  <Step title="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.
  </Step>

  <Step title="Choose a version">
    Select the major version (for example PostgreSQL 17). Qovery uses the latest released tag for that major version.

    <Frame>
      <img src="https://mintcdn.com/qovery-docs-agent-console-2026-09-29/5_7758n1u9ok1i87/images/configuration/blueprints/catalog.png?fit=max&auto=format&n=5_7758n1u9ok1i87&q=85&s=3eafcdc7b67ab713934c639f1745a89e" alt="Blueprint catalog in the Qovery Console" width="2646" height="1708" data-path="images/configuration/blueprints/catalog.png" />
    </Frame>
  </Step>
</Steps>

<Tip>
  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.
</Tip>

## Creating a Blueprint Service

<Steps>
  <Step title="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.

    <Info>
      Context variables such as the cluster region and name are filled in automatically from the target environment's cluster — you don't set them.
    </Info>

    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.
  </Step>

  <Step title="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](#variables--engine-reference). If a setting is not overridable, the blueprint's default applies.
  </Step>

  <Step title="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.

    <Frame>
      <img src="https://mintcdn.com/qovery-docs-agent-console-2026-09-29/5_7758n1u9ok1i87/images/configuration/blueprints/create_form.png?fit=max&auto=format&n=5_7758n1u9ok1i87&q=85&s=eba5bbf437eb8af6f44cf8f9a228d8ad" alt="Blueprint variables form" width="1396" height="1894" data-path="images/configuration/blueprints/create_form.png" />
    </Frame>
  </Step>
</Steps>

## Variables & Engine Reference

### Variables

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

| Field | Description |
| - | - |
| **Name** | The variable key (for example `db_name`, `instance_class`). |
| **Type** | `string`, `number`, or `bool`. |
| **Required** | Whether a value must be provided. Optional variables use their default. |
| **Secret** | Secret values are entered as password fields and stored encrypted. |
| **Default** | Pre-filled value when the variable is optional. |
| **Allowed values** | When set, the field is a dropdown limited to these values. |
| **Validation** | Optional constraints: regex `pattern`, `minLength`/`maxLength` (strings), `min`/`max` (numbers). |

### Context variables

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

| Example | Sourced from |
| - | - |
| `region` | `cluster.region` |
| `cluster_name` | `cluster.name` |

### 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).

| Setting | Applies to | Description |
| - | - | - |
| **Engine** | all | `terraform`, `opentofu`, or `helm` — the tool used to provision the resource. |
| **Version** | Terraform / OpenTofu | Engine version. Editable only if the author marked it overridable, and constrained to the allowed values. |
| **Credentials** | Terraform / OpenTofu | `cluster` (use the cluster's cloud credentials) or `env` (credentials supplied as variables on the service). External blueprints are always `env`. |
| **State backend** | Terraform / OpenTofu | `qovery` (Qovery-managed state) or `user_provided` (bring your own backend, e.g. S3/GCS/Azure). |
| **Resources** | all | CPU, RAM, and ephemeral storage allocated to the provisioning job (for example `500m`, `512Mi`, `1Gi`). |
| **Timeout** | all | Maximum duration, in seconds, for the provisioning run. |
| **Chart** | Helm | Chart repository, name, and version (fixed by the blueprint). |

<Info>
  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.
</Info>

## Editing a Blueprint Service

After a blueprint service is created, you can change the inputs it was provisioned with from its **Blueprint configuration** settings page. Open the blueprint service, go to its **Settings**, and select **Blueprint configuration** to review and edit the variables and any overridable engine settings the blueprint exposes (see [Variables & Engine Reference](#variables--engine-reference)). Secret values are handled without exposing the stored secret, and the **Overrides** section is collapsed by default.

Save your changes, then redeploy the service to apply them.

<Info>
  The **Blueprint configuration** page is only available for blueprint-backed services. For a blueprint service, source, build, and deployment-restriction settings are not shown, since they are managed by the blueprint.
</Info>

## 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:

<Steps>
  <Step title="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.

    <Frame>
      <img src="https://mintcdn.com/qovery-docs-agent-console-2026-09-29/5_7758n1u9ok1i87/images/configuration/blueprints/update_preview.png?fit=max&auto=format&n=5_7758n1u9ok1i87&q=85&s=0550c52bc5ef0e70f5e5f8572cf9ae19" alt="Blueprint update preview diff" width="1344" height="1920" data-path="images/configuration/blueprints/update_preview.png" />
    </Frame>
  </Step>

  <Step title="Apply">
    If the diff looks correct, **apply** the update. Qovery deploys the linked service with the new configuration.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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.

<Warning>
  **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).
</Warning>

### What can be migrated

| Requirement | Supported today |
| - | - |
| Cloud provider | AWS only |
| Database engine | PostgreSQL only. MySQL, Redis, and MongoDB are not wired yet. |
| PostgreSQL major version | 14, 15, 16, 17 |
| Database mode | `MANAGED` (a container database has nothing to adopt) |

### How a migration runs

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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](/configuration/organization/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

<AccordionGroup>
  <Accordion title="Pick the latest version for new services" icon="arrow-up-right-dots">
    When creating a new blueprint service, use the latest released version so you start on a supported, up-to-date template.
  </Accordion>

  <Accordion title="Always preview before applying updates" icon="magnifying-glass">
    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.
  </Accordion>

  <Accordion title="Prefer Qovery-managed state" icon="database">
    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.
  </Accordion>

  <Accordion title="Keep sensitive inputs as secrets" icon="key">
    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.
  </Accordion>

  <Accordion title="Scope the credentials you give an External blueprint" icon="user-shield">
    Create a dedicated vendor-side service account per blueprint service, limited to what the template provisions, rather than reusing an administrator token.
  </Accordion>

  <Accordion title="Consume outputs instead of hardcoding endpoints" icon="link">
    Wire applications to a blueprint's published outputs. A later update that changes an endpoint then propagates on its own.
  </Accordion>

  <Accordion title="Use blueprints over hand-written Terraform for supported services" icon="cubes">
    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.
  </Accordion>
</AccordionGroup>

## 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](/api-reference/introduction).

## Next Steps

<CardGroup cols={2}>
  <Card title="Databases" icon="database" href="/configuration/database">
    Compare blueprint-provisioned databases with Qovery's container and managed database options.
  </Card>

  <Card title="Object Storage" icon="box-archive" href="/configuration/object-storage">
    Learn about object storage on Qovery.
  </Card>

  <Card title="Terraform Services" icon="code" href="/configuration/terraform">
    Understand the Terraform service that backs a blueprint.
  </Card>

  <Card title="Members & RBAC" icon="shield-halved" href="/configuration/organization/members-rbac">
    Control who can create and manage blueprints.
  </Card>
</CardGroup>