Blueprint YAML Reference

services

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

For details, see Service fields.

databases

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

For details, see Database fields.

envVarGroups

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

For details, see Environment groups.

previews.generation

The generation mode to use for preview environments.

previews:
  generation: manual

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.

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
  • You specify a static site by setting runtime: static.
• pserv for a private service
• worker for a background worker
• cron for a cron job
• redis for a Redis instance

You can’t modify this value after creation.

You define PostgreSQL databases separately, in the databases list.

runtime

Required except for Redis instances. The service’s runtime.

Supported values include the following native language runtimes:

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

Along with the following 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.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.

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:

registryCredential:
  fromRegistryCreds:
    name: my-credentials # The name of a credential you've added to your workspace

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:

image:
  url: docker.io/my-name/my-image:latest
  creds: # Only for private images
    fromRegistryCreds:
      name: my-credential-name # The name of a credential you've added to your workspace

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:

scaling:
  minInstances: 1         # Required
  maxInstances: 3         # Required
  targetMemoryPercent: 60 # Optional if targetCPUPercent is set (valid: 1-90)
  targetCPUPercent: 60    # Optional if targetMemory is set (valid: 1-90)

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.

buildFilter:
  paths: # Only trigger a build with changes to these files
    - src/**/*.js
  ignoredPaths: # Ignore these files, even if they match a path in 'paths'
    - src/**/*.test.js

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:

headers:
  # Adds X-Frame-Options: sameorigin to all site paths
  - path: /*
    name: X-Frame-Options
    value: sameorigin
  # Adds Cache-Control: must-revalidate to /blog paths
  - path: /blog/*
    name: Cache-Control
    value: must-revalidate

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:

routes:
  # Redirect (HTTP status 301) from /a to /b
  - type: redirect
    source: /a
    destination: /b
  # Rewrite all /app/* requests to /app
  - type: rewrite
    source: /app/*
    destination: /app

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 Redis 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 Render’s Redis documentation.

name

Required. The PostgreSQL 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 instance, 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., "16").

If omitted, Render uses the most recent version supported by the platform.

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 PostgreSQL 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 a read replica to a PostgreSQL instance with the following syntax:

readReplicas:
  - name: my-db-replica

Note the following:

• Although the readReplicas field takes a list, you can add only one read replica to a PostgreSQL instance.
• If you omit this field, Render preserves any existing read replica for the instance.
• If you provide a different name from a database’s existing read replica, Render creates a new replica with the provided name and destroys the existing replica.
• If you provide an empty list (e.g., readReplicas: []), Render destroys any existing replica and does not create a new replica.
• 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 PostgreSQL Read Replicas.

highAvailability

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

highAvailability:
  enabled: true

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 PostgreSQL High Availability.

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

PostgreSQL and Redis only. The URL for connecting to the datastore over the private network.

• For PostgreSQL, has the format postgresql://user:password@host:port/database
• For Redis, has the format redis://red-xxxxxxxxxxxxxxxxxxxx:6379

user

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

Included as a component of connectionString.

password

PostgreSQL only. The password for your PostgreSQL database.

Included as a component of connectionString.

database

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

Included as a component of connectionString.