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.
+ Show example Blueprint file
#################################################################
# Example render.yaml #
# Do not use this file directly! Consult it for reference only. #
#################################################################
previews:
generation: automatic # Enable preview environments
# List all services *except* PostgreSQL databases here
services:
# A web service on the Ruby native runtime
- type: web
runtime: ruby
name: sinatra-app
repo: https://github.com/render-examples/sinatra # Default: Repo containing render.yaml
numInstances: 3 # Manual scaling configuration. Default: 1 for new services
region: frankfurt # Default: oregon
plan: standard # Default: starter
branch: prod # Default: master
buildCommand: bundle install
preDeployCommand: bundle exec ruby migrate.rb
startCommand: bundle exec ruby main.rb
autoDeploy: false # Disable automatic deploys
maxShutdownDelaySeconds: 120 # Increase graceful shutdown period. Default: 30, Max: 300
domains: # Custom domains
- example.com
- www.example.org
envVars: # Environment variables
- key: API_BASE_URL
value: https://api.example.com # Hardcoded value
- key: APP_SECRET
generateValue: true # Generate a base64-encoded 256-bit value
- key: STRIPE_API_KEY
sync: false # Prompt for a value in the Render Dashboard
- key: DATABASE_URL
fromDatabase: # Reference a property of a database (see available properties below)
name: mydatabase
property: connectionString
- key: MINIO_PASSWORD
fromService: # Reference a value from another service
name: minio
type: pserv
envVarKey: MINIO_ROOT_PASSWORD
- fromGroup: my-env-group # Add all variables from an environment group
# A web service that builds from a Dockerfile
- type: web
runtime: docker
name: webdis
repo: https://github.com/render-examples/webdis.git # Default: Repo containing render.yaml
rootDir: webdis # Default: Repo root
dockerCommand: ./webdis.sh # Default: Dockerfile CMD
scaling: # Autoscaling configuration
minInstances: 1
maxInstances: 3
targetMemoryPercent: 60 # Optional if targetCPUPercent is set
targetCPUPercent: 60 # Optional if targetMemory is set
healthCheckPath: /
registryCredential: # Default: No credential
fromRegistryCreds:
name: my-credentials
envVars:
- key: REDIS_HOST
fromService: # Reference a property from another service (see available properties below)
type: redis
name: lightning
property: host
- key: REDIS_PORT
fromService:
type: redis
name: lightning
property: port
- fromGroup: conc-settings
# A private service with an attached persistent disk
- type: pserv
runtime: docker
name: minio
repo: https://github.com/render-examples/minio.git # Default: Repo containing render.yaml
envVars:
- key: MINIO_ROOT_PASSWORD
generateValue: true # Generate a base64-encoded 256-bit value
- key: MINIO_ROOT_USER
sync: false # Prompt for a value in the Render Dashboard
- key: PORT
value: 10000
disk: # Persistent disk configuration
name: data
mountPath: /data
sizeGB: 10 # optional
# A Python cron job that runs every hour
- type: cron
name: date
runtime: python
schedule: "0 * * * *"
buildCommand: "true" # ensure it's a string
startCommand: date
repo: https://github.com/render-examples/docker.git # optional
# A Dockerfile-based background worker
- type: worker
name: queue
runtime: docker
dockerfilePath: ./sub/Dockerfile # Optional
dockerContext: ./sub/src # Optional
branch: queue # Optional
# A static site
- type: web
name: my-blog
runtime: static
buildCommand: yarn build
staticPublishPath: ./build
previews:
generation: automatic # Enable service previews
buildFilter:
paths:
- src/**/*.js
ignoredPaths:
- src/**/*.test.js
headers:
- path: /*
name: X-Frame-Options
value: sameorigin
routes:
- type: redirect
source: /old
destination: /new
- type: rewrite
source: /a/*
destination: /a
# A Redis instance
- type: redis
name: lightning
ipAllowList: # Required
- source: 0.0.0.0/0
description: everywhere
plan: free # Default: starter
maxmemoryPolicy: noeviction # Default: allkeys-lru
# List all PostgreSQL databases here
databases:
# A database with a read replica
- name: elephant
databaseName: mydb # Optional (Render may add a suffix)
user: adrian # Optional
ipAllowList: # Optional (defaults to allow all)
- source: 203.0.113.4/30
description: office
- source: 198.51.100.1
description: home
readReplicas:
- name: elephant-replica
# A database that allows only private network connections
- name: private database
databaseName: private
ipAllowList: [] # No entries in the IP allow list
# A flexible-plan database with specified disk size
# Flexible PostgreSQL plans are currently in early access.
# See https://docs.render.com/postgresql-refresh
- name: pachyderm
plan: basic-1gb
diskSizeGB: 35
# A database that enables high availability
- name: highly available database
plan: pro-8gb
highAvailability:
enabled: true
# Environment groups
envVarGroups:
- name: conc-settings
envVars:
- key: CONCURRENCY
value: 2
- key: SECRET
generateValue: true
- name: stripe
envVars:
- key: STRIPE_API_URL
value: https://api.stripe.com/v2
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:
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 |
---|---|
|
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. |
|
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. |
|
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. |
|
The generation mode to use for preview environments.
Supported values include:
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 This field does not affect configuration for individual service previews. |
|
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 |
---|---|
|
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. |
|
Required. The type of service. One of the following:
You can’t modify this value after creation. You define PostgreSQL databases separately, in the |
|
Required except for Redis instances. The service’s runtime. Supported values include the following native language runtimes:
Along with the following special-case runtimes:
You can’t modify this value after creation. This field replaces the |
|
The service’s instance type (see pricing). One of the following:
The following additional instance types are available for web services, private services, and background workers:
If you omit this field:
|
|
The preview generation mode to use for this service’s pull request previews. Supported values include:
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 This field does not affect configuration for preview environments. |
|
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. |
|
Required for non-Docker-based services. The command that Render runs to build your service. Basic examples include:
|
|
Required for non-Docker-based services. The command that Render runs to start your service. Basic examples include:
Docker-based services set the optional |
|
Required for cron jobs, omit otherwise. The schedule for running the cron job, as a cron expression. |
|
If specified, this command runs after the service’s Learn more about the pre-deploy command. |
|
The region to deploy the service to. One of the following:
You can’t modify this value after creation. This field does not apply to static sites. |
|
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 For services that pull a prebuilt Docker image, set |
|
For Git-based services, the branch of the linked 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. |
|
Web services and static sites only. A list of custom domains for the service. Internet-accessible services are always reachable at their For each root domain in the list, Render automatically adds a For each |
|
Web services only. The path of the service’s health check endpoint for zero-downtime deploys. |
|
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 After this delay, Render terminates the process with a 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 If omitted, the default value is |
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 |
---|---|
|
The command to run when starting the Docker-based service. If omitted, Render uses the |
|
The path to the service’s If omitted, Render uses |
|
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. |
|
If your This field uses the following format:
Add registry credentials in the Render Dashboard from your Workspace Settings page, or via the Render API. |
Pulling a prebuilt image
Field | Description |
---|---|
|
Details for the Docker image to pull from a registry. This field uses the following format:
Provide 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
.
- Instead, autoscaled services always run a number of instances equal to their
Field | Description |
---|---|
|
For a manually scaled service, the number of instances to scale the service to. If you omit this field:
This value has no effect for services with autoscaling enabled. Configure autoscaling behavior with the |
|
For an autoscaled service, configuration details for the service’s autoscaling behavior. Example:
|
Build
Field | Description |
---|---|
|
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.
|
|
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: redis-data # Required field
mountPath: /opt/redis # 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 |
---|---|
|
Required. The path to the directory that contains the static files to publish, relative to the repo root. Common examples include |
|
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. |
|
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. |
Redis
You define Redis instances in the services
field of render.yaml
alongside your other non-PostgreSQL services. A Redis instance has the type
redis
.
Example definitions
+ Show example Redis definitions
services:
# A Redis instance that defines all available fields
- type: redis
name: thunder
ipAllowList: # Allow external connections from only these CIDR blocks
- source: 203.0.113.4/30
description: office
- source: 198.51.100.1
description: home
region: frankfurt # Default: oregon
plan: pro # Default: starter
previewPlan: starter # Default: use the value for 'plan'
maxmemoryPolicy: allkeys-lru # Default: allkeys-lru)
# A Redis instance that allows all external connections
- type: redis
name: lightning
ipAllowList: # Allow external connections from everywhere
- source: 0.0.0.0/0
description: everywhere
# A Redis instance that allows only internal connections
- type: redis
name: private redis
ipAllowList: [] # Only allow internal connections
Redis-specific fields
Field | Description |
---|---|
|
Required. See Data access control. |
|
The Redis instance’s eviction policy for when it reaches its maximum memory limit. One of the following:
For details on these policies, see Render’s Redis 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
+ Show example database definitions
databases:
# A basic-4gb database instance with a read replica
- name: prod # Required
postgresMajorVersion: "16" # Default: most recent supported version
region: frankfurt # Default: oregon
plan: basic-4gb # Default: basic-256mb
databaseName: prod_app # Default: generated value based on name
user: app_user # Default: generated value based on name
ipAllowList: # Default: allows all connections
- source: 203.0.113.4/30
description: office
- source: 198.51.100.1
description: home
readReplicas: # Default: does not add a read replica
- name: prod-replica
# A database that allows only private network connections
- name: private database
databaseName: private
ipAllowList: [] # Only allow internal connections
# A database that enables high availability
- name: highly available database
plan: pro-16gb
highAvailability:
enabled: true
Essential fields
Field | Description |
---|---|
|
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. |
|
The database’s instance type (see pricing). One of the following: + View values for
|
|
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 If your primary database uses a new flexible instance type, you cannot specify a non-flexible instance type for |
|
The database’s disk size, in GB. Not valid for legacy instance types, which have a fixed disk size. This value must be either You can increase disk size, but you can’t decrease it. If you omit this field:
|
|
The region to deploy the instance to. One of the following:
You can’t modify this value after creation. |
|
See Data access control. |
PostgreSQL settings
Field | Description |
---|---|
|
The major version number of PostgreSQL to use, as a string (e.g., If omitted, Render uses the most recent version supported by the platform. You can’t modify this value after creation. |
|
The name of your database in the PostgreSQL instance. This is different from the If omitted, Render automatically generates a name for the database based on You can’t modify this value after creation. |
|
The name of the PostgreSQL user to create for your instance. If omitted, Render automatically generates a name for the database based on You can’t modify this value after creation. |
Database replicas
You can add two types of replica to a PostgreSQL instance:
- A read replica for increased query throughput
- A high availability standby for rapid recovery from primary instance failures
Field | Description |
---|---|
|
Add a read replica to a PostgreSQL instance with the following syntax:
Note the following:
For more information, see PostgreSQL Read Replicas. |
|
Add a high availability standby to a PostgreSQL instance with the following syntax:
For your database to support high availability, it must:
For more information, see PostgreSQL High Availability. |
Data access control
To control which IP addresses can access your PostgreSQL databases and Redis 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 Redis instances. If you omit this field for a PostgreSQL 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 and description:
ipAllowList: # allow external connections from everywhere
- source: 0.0.0.0/0
description: everywhere
Learn more about PostgreSQL access control and Redis access aontrol.
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 theproperty
orenvVarKey
to use. - For
fromService
, you must also provide the referenced service’stype
.
Supported values of property
include:
Property | Description |
---|---|
|
Web services and private services only. The service’s hostname on the private network. |
|
Web services and private services only. The port of the service’s HTTP server. |
|
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: |
|
PostgreSQL and Redis only. The URL for connecting to the datastore over the private network.
|
|
PostgreSQL only. The name of the user for your PostgreSQL database. Included as a component of |
|
PostgreSQL only. The password for your PostgreSQL database. Included as a component of |
|
PostgreSQL only. The name of your database within the PostgreSQL instance (not the Included as a component of |
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
:
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.
- When you update an existing Blueprint, Render ignores any environment variables with
- 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:
- 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.