Description
https://render.com/docs/blueprint-spec
Blueprint YAML Reference
Every Render Blueprint is backed by a YAML file that defines a set of interconnected services, databases, and environment groups.
A Blueprint file must be named render.yaml, and it must be located in the root directory of a Git repository.
This reference page provides an example Blueprint file, along with documentation for supported fields.
Example Blueprint file
The following render.yaml file demonstrates usage for most supported fields. These fields are documented in further detail below.
IDE validation
The Render Blueprint specification is served from SchemaStore.org, which many popular IDEs use to provide live validation and autocompletion for JSON and YAML files.
For VS Code, install the YAML extension by Red Hat to enable validation of render.yaml files:
render.yaml validation in VS Code
If your IDE doesn't integrate with SchemaStore.org, the Blueprint specification is also hosted at https://render.com/schema/render.yaml.json in JSON Schema format. Consult your IDE's documentation to learn how to use this schema for validation.
Root-level fields
The following fields are valid at the root level of a render.yaml file:
Field Description
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.
Service fields
Each entry in a Blueprint file's services list is an object that represents a single, non-PostgreSQL service. (You define PostgreSQL databases in the databases list.)
See below for supported fields.
Essential fields
These fields pertain to a service's core configuration (name, runtime, region, and so on).
Field Description
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 PostgreSQL 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.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.
Docker
The following fields are specific to Docker-based services. This includes both services that build an image with a Dockerfile (runtime: docker) and services that pull a prebuilt image from a registry (runtime: image).
Building from a Dockerfile
Field Description
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.
Pulling a prebuilt image
Field Description
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.
Scaling
Note the following about scaling:
You can't scale a service with an attached persistent disk.
Autoscaling requires a Professional workspace or higher.
Manual scaling is available for all workspaces.
If you add an existing service to a Blueprint, that service retains any existing autoscaling settings unless you add the scaling field in your Blueprint.
Autoscaling is disabled in preview environments.
Instead, autoscaled services always run a number of instances equal to their minInstances.
Field Description
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)
Build
Field Description
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.
Disks
Attach a persistent disk to a compatible service with the disk field:
disk:
name: app-data # Required field
mountPath: /opt/data # Required field
sizeGB: 5 # Default: 10
You can modify the name and mountPath of an existing disk. You can increase the sizeGB of an existing disk, but you can't reduce it.
Static sites
The following fields are specific to static sites:
Field Description
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.
Render Key Value
You define Render Key Value instances in the services field of render.yaml alongside your other non-PostgreSQL services. A Key Value instance has the type keyvalue (or its deprecated alias redis).
Example definitions
Key-Value-specific fields
Field Description
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.
Environment variables
See Setting environment variables.
Database fields
Each entry in a Blueprint file's databases list is an object that represents a PostgreSQL instance.
See below for supported fields.
Example definitions
Essential fields
Field Description
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).
If your primary database uses a new flexible instance type, you cannot specify a non-flexible instance type for previewPlan (or vice versa).
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.
PostgreSQL settings
Field Description
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.
Database replicas
You can add two types of replica to a Render Postgres instance:
Read replicas for increased query throughput
A high availability standby for rapid recovery from primary instance failures
Field Description
readReplicas
Add one or more read replicas to a Render Postgres instance with the following syntax:
readReplicas:
- name: my-db-replica
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 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.
Data access control
To control which IP addresses can access your Render Postgres and Key Value instances from outside Render's network, use the ipAllowList field:
ipAllowList:
- source: 203.0.113.4/30
description: office # optional - source: 198.51.100.1
The ipAllowList field is required for Key Value instances. If you omit this field for a Render Postgres database, any source with valid credentials can access the database.
IP address ranges use CIDR notation. The description field is optional.
To block all external connections, provide an empty list:
ipAllowList: [] # Only allow internal connections
To allow all external connections, provide the following CIDR block:
ipAllowList: # allow external connections from everywhere
- source: 0.0.0.0/0
description: everywhere
Learn more about access control for Render Postgres and Render Key Value.
Setting environment variables
Set names and values for a service's environment variables in the envVars field:
envVars:
Sets a hardcoded value
(DO NOT hardcode secrets in your Blueprint file!)
- key: API_BASE_URL
value: https://api.example.com
Generates a base64-encoded 256-bit value
(unless a value already exists)
- key: APP_SECRET
generateValue: true
Prompts for a value in the Render Dashboard on creation
(useful for secrets)
- key: STRIPE_API_KEY
sync: false
References a property of a database
(see available properties below)
- key: DATABASE_URL
fromDatabase:
name: mydatabase
property: connectionString
References an environment variable of another service
(see available properties below)
- key: MINIO_PASSWORD
fromService:
name: minio
type: pserv
envVarKey: MINIO_ROOT_PASSWORD
Adds all environment variables from an environment group
- fromGroup: my-env-group
A Blueprint can create new environment variables or modify the values of existing ones. Render preserves existing environment variables, even if you omit them from the Blueprint file.
Referencing values from other services
When setting an environment variable in a Blueprint file, you can reference certain values from your other Render services.
You can reference a service that isn't in the Blueprint, but that service must exist in your workspace for the Blueprint to be valid.
To reference a value from most service types, use the fromService field. For PostgreSQL, instead use fromDatabase:
Any non-PostgreSQL service
- key: MINIO_HOST
fromService:
name: minio
type: pserv
property: host
PostgreSQL service
-
key: DATABASE_URL
fromDatabase:
name: mydatabase
property: connectionString
To reference another service's environment variable, set envVarKey instead of property: -
key: MINIO_PASSWORD
fromService:
name: minio
type: pserv
envVarKey: MINIO_ROOT_PASSWORD
In all cases, provide the service's name, along with the property or envVarKey to use.
For fromService, you must also provide the referenced service's type.
Supported values of property include:
Property Description
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
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.
Prompting for secret values
Some environment variables contain secret credentials, such an API key or access token. Do not hardcode these values in your render.yaml file!
Instead, you can define these environment variables with sync: false, like so:
- key: STRIPE_API_KEY
sync: false
During the initial Blueprint creation flow in the Render Dashboard, you're prompted to provide a value for each environment variable with sync: false:
render.yaml sync false
Note the following limitations:
Render prompts you for these values only during the initial Blueprint creation flow.
When you update an existing Blueprint, Render ignores any environment variables with sync: false.
Add any new secret credentials to your existing services manually.
Render does not include sync: false environment variables in preview environments.
As a workaround, you can also manually define the environment variable in an environment group that you apply to the service. For details, see this page.
You can't apply sync: false to environment variables defined in an environment group.
If you do this, Render ignores the environment variable.
Environment groups
You can define environment groups in the root-level envVarGroups field of your render.yaml file:
envVarGroups:
- name: my-env-group
envVars:- key: CONCURRENCY
value: 2 - key: SHARED_SECRET
generateValue: true
Each environment group has a name and a list of zero or more envVars. Definitions in the envVars list can use some (but not all) of the same formats as envVars for a service:
- key: CONCURRENCY
An environment group can't reference values from your services, or from other environment groups.
You can't define an environment variable with sync: false in an environment group.
Variable interpolation
Render does not support variable interpolation in a render.yaml file.
To achieve a similar behavior, pair environment variables with a build or start script that performs the interpolation for you.