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

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
• elixir
• go
• ruby
• 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't modify this value after creation.

This field replaces the env field (env is still supported but is discouraged).

plan

The service's instance type (see pricing). One of the following:

• free (not available for private services, background workers, or cron jobs)
• starter
• standard
• pro
• pro plus

The following additional instance types are available for web services, private services, and background workers:

• pro max
• pro ultra

If you omit this field:

• Render uses starter for a new service.
• Render retains the current instance type for an existing service.

previews.generation

The preview generation mode to use for this service's pull request previews.

Supported values include:

• manual
• automatic

For details on each, see Manual vs. automatic PR previews.

If you omit this field, pull request previews are disabled for the service.

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

This field does not affect configuration for preview environments.

previews.numInstances

The number of instances to use for this service in preview environments.

If you omit this field, preview instances use the same number of instances as the base service. If the base service uses autoscaling, preview instances use the minimum number of instances for the base service.

previews.plan

The instance type to use for this service in preview environments.

If you omit this field, preview instances use the same instance type as the base service.

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

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

Basic examples include:

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

Docker-based services set the optional dockerCommand field instead of this field.

schedule

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

preDeployCommand

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)
• ohio
• virginia
• frankfurt
• singapore

You can't modify this value after creation. This field does not apply to static sites.

If omitted, the default value is oregon.

repo

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

If omitted, Render uses the repo that contains the render.yaml file itself.

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 omitted, Render uses the repo's default branch.

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.

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

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

healthCheckPath

Web services only. The path of the service's health check endpoint for zero-downtime deploys.

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.

dockerCommand

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

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

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.

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.

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.

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.

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.

See Data access control.

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.

name

Required. The Postgres instance's name. Provide a unique name for each service 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 instance type (see pricing).

One of the following:

If you omit this field:

• Render uses basic-256mb for a new database.
• Render retains the current instance type for an existing database.

previewPlan

The instance type to use for this database in preview environments.

If you omit this field, preview instances use the same instance type 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 uses a default disk size based on the instance type's tier:
  • Free: 1 GB
  • Basic: 15 GB
  • Pro: 100 GB
  • Accelerated: 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).

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

See Data access control.

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

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 values from other services.

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 Professional workspace or higher
• Use the Pro instance type or higher
• Use PostgreSQL version 13 or later

For more information, see High Availability for Render Postgres.

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.

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

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)

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.