Blueprint YAML Reference

services

A list of non-Postgres services to manage with the Blueprint. Each entry is an object that represents a single service. See all service fields.

Services in this top-level list keep their currently assigned environment (if any) after each sync.

• To move a service into a specific environment, instead define it in the services list for that environment.
• To remove a service from its current environment, instead define it under the ungrouped field.

Do not define the same service in more than one location.

databases

A list of Postgres databases to manage with the Blueprint. Each entry is an object that represents a single database. See all database fields.

Databases in this top-level list keep their currently assigned environment (if any) after each sync.

• To move a database into a specific environment, instead define it in the databases list for that environment.
• To remove a database from its current environment, instead define it under the ungrouped field.

Do not define the same database in more than one location.

envVarGroups

A list of environment groups to manage with the Blueprint. Each entry is an object that represents a single environment group. See supported fields.

Environment groups in this top-level list keep their currently assigned environment (if any) after each sync.

• To move an environment group into a specific environment, instead define it in the envVarGroups list for that environment.
• To remove an environment group from its current environment, instead define it under the ungrouped field.

Do not define the same environment group in more than one location.

projects

A list of projects to manage with the Blueprint. A project defines one or more environments, each of which lists the services and environment groups that belong to it.

For details, see Projects and environments.

ungrouped

An object for defining resources that should not belong to any environment. Can contain optional fields services, databases, and envVarGroups, each of which matches the format of its root-level counterpart.

Moving a resource definition into this object removes it from its current environment, guaranteeing that it is "ungrouped". In contrast, root-level definitions keep their currently assigned environment (if any).

Do not define the same resource in more than one location.

previews.generation

The generation mode to use for preview environments.

Supported values include:

• off
• manual
• automatic

For details on each, see Manual vs. automatic preview environments.

If you omit this field, preview environments are disabled for any linked Blueprints.

Setting the deprecated field previewsEnabled: true is equivalent to setting this field to automatic.

This field does not affect configuration for individual service previews.

previews.expireAfterDays

The number of days to retain a preview environment that receives no updates. After this period, Render automatically deprovisions the preview environment to help reduce your compute costs.

By default, preview environments are retained indefinitely until their associated pull request is closed.

For details, see Automatic expiration.

name

Required. The service's name. Provide a unique name for each resource in your Blueprint file.

If you add the name of an existing service to your Blueprint file, Render attempts to apply the Blueprint's configuration to that existing service.

type

Required. The type of service. One of the following:

• web for a web service or static site
  • For a static site, you also set runtime: static.
• pserv for a private service
• worker for a background worker
• cron for a cron job
• keyvalue for a Render Key Value instance
  • redis is a deprecated alias for keyvalue.
• workflow for a workflow

You can't modify this value after creation.

You define Render Postgres databases separately, in the databases list.

runtime

Required unless type is keyvalue or redis. The service's runtime.

Supported values include:

Native language runtimes

• node
• python
• ruby
• go
• elixir
• rust

Special-case runtimes

• docker for services that build an image from a Dockerfile
• image for services that pull a prebuilt image from a registry
• static for static sites

You can change a service's runtime after creation (except for static sites).

Workflow services currently only support node and python.

This field replaces the deprecated env field.

plan

The service's compute plan, such as free or 1c-2g. Sets the service's available compute resources.

If you omit this field:

• Render uses 0.5c-512mb for a new web service, private service, background worker, or cron job.
• Render uses 256mb for a new Key Value instance.
• Render retains the current compute plan for an existing service.

Not supported for:

• Static sites (which don't have a compute plan)
• Workflows (which instead set per-task compute plans in code)

previews

An object for configuring this service's pull request previews and preview environments.

Not supported for workflows.

Supported subfields

ipAllowList

Web services and static sites only. Requires a Scale or Enterprise plan. A list of the IP address ranges allowed to connect to your service over the public internet.

If you omit this field:

• Render allows all IPs for a new service.
• Render retains the current IP ranges for an existing service.

For details, see Inbound IP rules.

buildCommand

Required for non-Docker-based services. The command that Render runs to build your service.

Basic examples include:

• npm install (Node.js)
• pip install -r requirements.txt (Python)

startCommand

The command that Render runs to start your service.

Basic examples include:

• npm start (Node.js)
• gunicorn your_application.wsgi (Python)

Required for most services.

Unsupported for static sites (which instead set staticPublishPath).

schedule

Required for cron jobs, omit otherwise. The schedule for running the cron job, as a cron expression.

preDeployCommand

Available for paid web services, private services, and background workers. If specified, this command runs after the service’s buildCommand but before its startCommand. Recommended for running database migrations and other pre-deploy tasks.

Learn more about the pre-deploy command.

region

The region to deploy the service to. One of the following:

• oregon (default for non-workflow services)
• ohio
• virginia
• frankfurt
• singapore

You can't modify this value after creation.

Required for workflows.

Unsupported for static sites (which are hosted on a global CDN).

If omitted for other service types, the default value is oregon.

repo

For Git-based services, the URL of the Git provider repo to use. Your Git provider account must have access to the repo.

If omitted, Render uses the repo that contains the Blueprint file.

For services that pull a prebuilt Docker image, set image instead of this field.

branch

For Git-based services, the branch of the linked repo to use.

If you omit this field:

• Render uses the repo's default branch (most commonly main or master) if the service uses a different repo from the Blueprint file.
• Render uses the Blueprint's branch if the service uses the same repo as the Blueprint file.

If you're using preview environments, you probably don't want to set this field. If you do set it, Render uses the specified branch in all preview environments, instead of your pull request's associated branch. This prevents you from testing code changes in the preview environment.

autoDeployTrigger

Sets the automatic deploy behavior for a Git-based service.

One of the following:

• commit: Trigger a deploy on each commit to the service's linked branch.
  • Equivalent to the deprecated setting autoDeploy: true
• checksPass: Trigger a deploy only if the linked branch's CI checks pass.
• off: Disable auto-deploys.
  • Equivalent to the deprecated setting autoDeploy: false

This field replaces the deprecated autoDeploy field. If you include both, autoDeployTrigger takes precedence.

This field has no effect for services that deploy a prebuilt Docker image.

If you omit this field:

• Render uses commit for a new service.
• Render retains the current value for an existing service.

domains

Web services and static sites only. A list of custom domains for the service. Internet-accessible services are always reachable at their onrender.com subdomain.

For each root domain in the list, Render automatically adds a www. subdomain that redirects to the root domain.

For each www. subdomain in the list, Render automatically adds the corresponding root domain and redirects it to the www. subdomain.

renderSubdomainPolicy

Web services and static sites only. Controls whether the service is reachable at its onrender.com subdomain.

One of the following:

• enabled: The service is reachable at its onrender.com subdomain.
• disabled: The service is not reachable at its onrender.com subdomain. Requests to the subdomain receive a 404 response.

Disabling a service's onrender.com subdomain requires the service to have at least one custom domain. Learn more.

If you omit this field:

• Render uses enabled for a new service.
• Render retains the current value for an existing service.

healthCheckPath

Web services only. The path of the service's health check endpoint.

This value always starts with a / character.

maxShutdownDelaySeconds

Web services, private services, and background workers only. The maximum amount of time (in seconds) that Render waits for your application process to exit gracefully after sending it a SIGTERM signal. For details, see Zero-downtime deploys.

After this delay, Render terminates the process with a SIGKILL signal if it's still running.

Render most commonly shuts down instances as part of redeploying your service or scaling it down. Set this field to give instances more time to finish any existing work before termination.

This value must be an integer between 1 and 300, inclusive.

If omitted, the default value is 30.

maintenanceMode

Web services only. Requires a paid compute plan. Use this field to enable maintenance mode for a service and temporarily disable public traffic.

Set enabled to true to enable maintenance mode or false to disable it. Optionally, set uri to an absolute URL for a custom maintenance page. The URL must not point to the same service. If you omit uri, Render displays its default maintenance page.

initialDeployHook

Web services, private services, and background workers only. Render runs this command after a service's first successful deploy. Useful for one-time initialization tasks such as seeding a database or downloading files to a persistent disk.

This command runs only once per service instance (including in preview environments). For commands that should run before every deploy, use preDeployCommand instead.

afterFirstDeployCommand is a deprecated alias for this field.

dockerCommand

The command to run when starting the Docker-based service.

If omitted, Render uses the CMD defined in the Dockerfile.

Not supported for workflows.

dockerfilePath

The path to the service's Dockerfile, relative to the repo root. Typically used for services in a monorepo.

If omitted, Render uses ./Dockerfile.

Not supported for workflows.

dockerContext

The path to the service's Docker build context, relative to the repo root. Typically used for services in a monorepo.

If omitted, Render uses the repo root.

Not supported for workflows.

registryCredential

If your Dockerfile references any private images, you must specify a valid credential that can access those images.

This field uses the following format:

Add registry credentials in the Render Dashboard from your Workspace Settings page, or via the Render API.

Not supported for workflows.

image

Details for the Docker image to pull from a registry.

This field uses the following format:

Provide creds only if you're pulling a private image. Add registry credentials in the Render Dashboard from your Workspace Settings page, or via the Render API.

Not supported for workflows.

For more information, see Deploy a Prebuilt Docker Image.

numInstances

For a manually scaled service, the number of instances to scale the service to.

If you omit this field:

• Render uses 1 for a new service.
• Render retains the current value for an existing service.

This value has no effect for services with autoscaling enabled. Configure autoscaling behavior with the scaling field.

scaling

For an autoscaled service, configuration details for the service's autoscaling behavior.

Example:

buildFilter

File paths in the service's repo to include or ignore when determining whether to trigger an automatic build. Especially useful for monorepos.

Build filter paths use glob syntax. They are always relative to the repo's root directory.

When synced, this value fully replaces an existing service's build filter settings. If you omit this field for a service with existing build filter settings, Render replaces those settings with empty lists.

rootDir

The service's root directory within its repo. Changes to files outside the root directory do not trigger a build for the service. Set this when working in a monorepo.

If omitted, Render uses the repo's root directory.

staticPublishPath

Required. The path to the directory that contains the static files to publish, relative to the repo root. Common examples include ./build and ./dist.

headers

Configuration details for a static site's HTTP response headers.

Example:

You can modify existing header rules and add new ones. Render preserves any existing header rules that are not included in the Blueprint file.

routes

Configuration details for a static site's redirect and rewrite routes.

Example:

You can modify existing routing rules and add new ones. Render preserves any existing routing rules that are not included in the Blueprint file.

ipAllowList

Required. A list of the IP address ranges allowed to connect to your Key Value instance over the public internet.

For details, see Inbound IP rules.

maxmemoryPolicy

The Key Value instance's eviction policy for when it reaches its maximum memory limit. One of the following:

• allkeys-lru (default)
• volatile-lru
• allkeys-random
• volatile-random
• volatile-ttl
• noeviction

For details on these policies, see the Render Key Value documentation.

persistenceMode

The Key Value instance's data persistence behavior. One of the following:

• journal-snapshot
• snapshot
• off

If you omit this field:

• Render uses journal-snapshot for a new paid instance.
• Render retains the current value for an existing paid instance.
• Render uses off for a new free instance (data persistence is not available for free instances).

For details on persistence modes, see the Render Key Value documentation.

name

Required. The Postgres instance's name. Provide a unique name for each resource in your Blueprint file.

If you add the name of an existing instance to your Blueprint file, Render attempts to apply the Blueprint's configuration to that existing instance.

You can't modify this value after creation.

plan

The database's compute plan, such as 0.5c-1g or 2c-8g. Sets the database's available compute resources.

If your database uses a legacy instance type, you cannot move it back if you move it to a current compute plan.

If you omit this field:

• Render uses 0.1c-256mb for a new database.
• Render retains the current compute plan for an existing database.

previewPlan

The compute plan to use for this database in preview environments. Sets the preview database's available compute resources.

See all Render Postgres compute plans.

If you omit this field, preview instances use the same compute plan as the primary database (specified by plan).

diskSizeGB

The database's disk size, in GB. Not valid for legacy instance types, which have a fixed disk size.

This value must be either 1 or a multiple of 5.

You can increase disk size, but you can't decrease it.

If you omit this field:

• For a new database, Render sets the disk size based on plan:

  Compute plan	Default disk size
  free	1 GB (fixed)
  0.1c-256mb, 0.5c-1g, 2c-4g	15 GB
  1c-2g, all paid plans with 4 GB RAM per CPU	100 GB
  All paid plans with 8 GB RAM per CPU	250 GB

• For an existing database, Render retains the current disk size.

previewDiskSizeGB

The disk size to use for this database in preview environments.

If you omit this field, preview instances use the same disk size as the primary database (specified by diskSizeGB).

storageAutoscalingEnabled

If true, enables storage autoscaling for the database. If false, disables storage autoscaling.

Not valid for legacy instance types, which have a fixed disk size.

If you omit this field:

• Render uses false for a new database.
• Render retains the current value for an existing database.

region

The region to deploy the instance to. One of the following:

• oregon (default)
• ohio
• virginia
• frankfurt
• singapore

You can't modify this value after creation.

If omitted, the default value is oregon.

ipAllowList

A list of the IP address ranges allowed to connect to your database over the public internet.

If you omit this field:

• Render allows all IPs for a new database (all connections require valid credentials).
• Render retains the current IP ranges for an existing database.

For details, see Inbound IP rules.

connectionPool

The type of connection pool to operate in front of the database, if any. One of the following:

• pgbouncer
• none

If you omit this field:

• Render uses none for a new database.
• Render retains the current setting for an existing database.

For details, see Connection Pooling for Render Postgres.

postgresMajorVersion

The major version number of PostgreSQL to use, as a string (e.g., "17").

If omitted, Render uses the most recent version supported by the platform (currently 18).

You can't modify this value after creation.

databaseName

The name of your database in the PostgreSQL instance. This is different from the name of the Render Postgres instance itself.

If omitted, Render automatically generates a name for the database based on name.

You can't modify this value after creation.

user

The name of the PostgreSQL user to create for your instance.

If omitted, Render automatically generates a name for the database based on name.

You can't modify this value after creation.

readReplicas

Add one or more read replicas to a Render Postgres instance with the following syntax:

Note the following:

• You can add up to five read replicas to a given Render Postgres instance.
• If you omit this field, Render preserves any existing read replicas for the instance.
• If you provide different name values from a database's existing read replicas, Render creates a new replica for each new name and destroys any existing replicas that don't match any provided name.
• If you provide an empty list (e.g., readReplicas: []), Render destroys any existing replicas and does not create new replicas.
• You can reference a read replica's properties in another service's environment variables, as you would for any other database. See Referencing service properties.

For more information, see Read Replicas for Render Postgres.

highAvailability

Add a high availability standby to a Render Postgres instance with the following syntax:

For your database to support high availability, it must:

• Belong to a Pro workspace or higher
• Use a compute plan with at least 1 CPU
• Use PostgreSQL version 13 or later

For more information, see High Availability for Render Postgres.

source

Required. The IP address or range in CIDR notation, such as 203.0.113.4/30.

description

A label for this IP address or range (e.g., office, home, VPN).

name

Required. The project's name.

environments

Required. A list of the project's environments. Each project must have at least one environment.

name

Required. The environment's name.

services

A list of the services that belong to the environment.

Matches the format of the root-level services field.

Do not define the same service in more than one location.

databases

A list of the Render Postgres databases that belong to the environment.

Matches the format of the root-level databases field.

Do not define the same database in more than one location.

envVarGroups

A list of the environment groups that belong to the environment.

Matches the format of the root-level envVarGroups field.

Do not define the same environment group in more than one location.

networking.isolation

Controls private network isolation for the environment.

Supported values include:

• enabled
• disabled

If omitted, the default value is disabled.

permissions.protection

Controls whether the environment is protected, which prevents destructive actions by non-admin workspace members.

Supported values include:

• enabled
• disabled

If omitted, the default value is disabled.

host

Web services and private services only. The service's hostname on the private network.

port

Web services and private services only. The port of the service's HTTP server.

hostport

Web services and private services only. The service's host and port, separated by a colon. Use this value to connect to the service over the private network.

Example: my-service:10000

slug

Workflow services only. The workflow's slug, such as my-workflow.

Each of your workflow's defined tasks has a slug that starts with this value. For example, if the workflow's slug is my-workflow, task slugs might include my-workflow/run-agent and my-workflow/extract-data.

You provide a task's slug when triggering runs.

connectionString

Render Postgres and Key Value only. The URL for connecting to the datastore over the private network.

• For Render Postgres, has the format postgresql://user:password@host:port/database
• For Render Key Value, has the format redis://red-xxxxxxxxxxxxxxxxxxxx:6379 (or redis://user:password@red-xxxxxxxxxxxxxxxxxxxx:6379 if internal authentication is enabled)

connectionPoolString

Render Postgres only. The URL for connecting to the database through its managed connection pool (if enabled).

Has the format postgresql://user:password@host:port/database

user

Render Postgres only. The name of the user for your PostgreSQL database.

Included as a component of connectionString.

password

Render Postgres only. The password for your PostgreSQL database.

Included as a component of connectionString.

database

Render Postgres only. The name of your database within the PostgreSQL instance (not the name of the PostgreSQL instance itself).

Included as a component of connectionString.