Render Blueprints (IaC)

Blueprints are Render's infrastructure-as-code (IaC) model for defining, deploying, and managing multiple resources with a single YAML file:

Show example Blueprint

A Blueprint acts as the single source of truth for configuring an interconnected set of services, databases, and environment groups. Whenever you update a Blueprint, Render automatically redeploys any affected services to apply the new configuration (you can disable this).

As your infrastructure grows over time, Blueprints become more and more helpful for managing changes and additions to it.

Do not manage a particular resource with more than one Blueprint.

If multiple Blueprints apply different configuration to the same resource, this can result in unpredictable behavior.

To avoid this scenario, make sure that each of your resources is managed by at most one Blueprint. Blueprint-managed resources are denoted with an icon in the Render Dashboard:

Setup

1. Create an empty YAML file in your repository where you'll define your Blueprint's resources.

   • By default, Render looks for the render.yaml file at the root of your repo, but you can define your Blueprint file anywhere.

2. Populate your Blueprint file with the details of the resources you want to create and manage.

   • If you're testing out Blueprints, try pasting the example Blueprint at the top of this page.
   • See also the complete Blueprint YAML Reference.

3. Commit and push your changes to your Git provider.

4. Open the Render Dashboard and click New > Blueprint:

   

5. In the list that appears, click the Connect button for whichever repo contains your Blueprint.

   • You'll first need to connect your Git provider account if you haven't yet.

6. In the form that appears, specify a name for your Blueprint and which branch of your repo to link.

   • Each push to the linked branch that modifies your Blueprint file triggers a deploy of any added or modified resources.

7. If needed, specify a custom file path to your Blueprint's YAML file in the Blueprint Path field.

   • By default, Render creates a Blueprint using the render.yaml file at your repository's root.

8. Review the list of the changes that Render will apply based on the linked Blueprint:

   

   If your Blueprint file contains errors, the page instead displays details about those errors.

9. If everything looks correct, click Deploy Blueprint.

You're all set! Render begins provisioning your Blueprint's specified resources:

Generating a Blueprint from existing services

You can generate a render.yaml file using any combination of your existing Render services. This is useful if you want to start managing those exact resources with a Blueprint, or if you want to replicate those resources.

In the Render Dashboard, select any number of your services, then click Generate Blueprint at the bottom of the page:

This opens a page where you can download or copy the generated render.yaml file. The page provides additional instructions for creating a Blueprint from that file.

The generated render.yaml file does not include environment variable values. This is a security precaution. Instead, the generated file sets sync: false for all environment variables, like so:

If you use this render.yaml file to create a Blueprint with new services (instead of your existing ones), you'll need to provide values for these environment variables. For details, see Setting environment variables.

Replicating a Blueprint

You can create multiple Blueprints from a single YAML file. Each Blueprint creates and manages a completely independent set of resources.

The Blueprint creation flow displays a notice if your new Blueprint matches existing resources in your workspace:

As shown in the screenshot above, Render appends a suffix to the name of each new resource to prevent collisions with your existing resources.

Click Deploy Blueprint to create the new resources as usual.

Managing Blueprint resources

Adding an existing resource

Do not add a resource to more than one Blueprint.

Doing so can lead to unpredictable behavior for your services.

You can add an existing Render resource to your Blueprint. To do so, add the resource's details to your Blueprint file as you would for a new resource. See all supported fields and values for each service type in the Blueprint specification reference.

Make sure to include all configuration options that are currently set for the resource in the Render Dashboard. For most services, this includes the service's name, type, plan, buildCommand, startCommand, and so on. If you omit some of these options, your Blueprint will use a default value that almost definitely differs from your service's existing configuration.

When you next sync your Blueprint, Render applies the new configuration to the existing resource. The resource retains any existing environment variable values that aren't overwritten by the Blueprint.

Modifying a resource outside of its Blueprint

You can still make changes to a Blueprint-managed resource via other mechanisms (the Render Dashboard, the Render CLI, and so on). However, if any such changes conflict with Blueprint-defined configuration, the next Blueprint sync overwrites them.

If you delete a Blueprint-managed resource, Render recreates it the next time you sync your Blueprint!

See Deleting resources.

Deleting resources

With one exception, removing a definition from a Blueprint file does not delete the corresponding resource. Existing resources remain intact. This is a safeguard against accidental deletions (for example, if you revert your Blueprint to a commit from before the addition of a critical resource).

Exception: Render Postgres read replicas can be deleted by Blueprint changes:

• Removing or renaming a replica in a database's readReplicas list deletes the replica.
• Setting readReplicas: [] deletes all of a database's read replicas.
• Omitting the readReplicas field entirely preserves any existing replicas.

Manually deleting a resource does not remove it from your Blueprint. The next time you sync your Blueprint, Render detects that a defined resource is missing and recreates it.

To properly delete a Blueprint-managed resource:

1. Update your Blueprint file to remove the relevant resource definition and sync your changes.
2. Delete the now-unmanaged resource via any supported mechanism (the Render Dashboard, the Render CLI, and so on).

Disabling automatic sync

By default, Render automatically updates affected resources every time you push Blueprint changes to your linked branch.

To instead control exactly when you sync a particular Blueprint, set Auto Sync to No on your Blueprint's Settings page:

You can then manually trigger a sync by clicking Manual Sync on your Blueprint's page.

Supported fields and values

See the complete Blueprint specification reference.