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 hereservices:# A web service on the Ruby native runtime- type: webruntime: rubyname: sinatra-apprepo: https://github.com/render-examples/sinatra # Default: Repo containing render.yamlnumInstances: 3 # Manual scaling configuration. Default: 1 for new servicesregion: frankfurt # Default: oregonplan: standard # Default: starterbranch: prod # Default: masterbuildCommand: bundle installpreDeployCommand: bundle exec ruby migrate.rbstartCommand: bundle exec ruby main.rbautoDeploy: false # Disable automatic deploysmaxShutdownDelaySeconds: 120 # Increase graceful shutdown period. Default: 30, Max: 300domains: # Custom domains- example.com- www.example.orgenvVars: # Environment variables- key: API_BASE_URLvalue: https://api.example.com # Hardcoded value- key: APP_SECRETgenerateValue: true # Generate a base64-encoded 256-bit value- key: STRIPE_API_KEYsync: false # Prompt for a value in the Render Dashboard- key: DATABASE_URLfromDatabase: # Reference a property of a database (see available properties below)name: mydatabaseproperty: connectionString- key: MINIO_PASSWORDfromService: # Reference a value from another servicename: miniotype: pservenvVarKey: MINIO_ROOT_PASSWORD- fromGroup: my-env-group # Add all variables from an environment group# A web service that builds from a Dockerfile- type: webruntime: dockername: webdisrepo: https://github.com/render-examples/webdis.git # Default: Repo containing render.yamlrootDir: webdis # Default: Repo rootdockerCommand: ./webdis.sh # Default: Dockerfile CMDscaling: # Autoscaling configurationminInstances: 1maxInstances: 3targetMemoryPercent: 60 # Optional if targetCPUPercent is settargetCPUPercent: 60 # Optional if targetMemory is sethealthCheckPath: /registryCredential: # Default: No credentialfromRegistryCreds:name: my-credentialsenvVars:- key: REDIS_HOSTfromService: # Reference a property from another service (see available properties below)type: keyvaluename: lightningproperty: host- key: REDIS_PORTfromService:type: keyvaluename: lightningproperty: port- fromGroup: conc-settings# A private service with an attached persistent disk- type: pservruntime: dockername: miniorepo: https://github.com/render-examples/minio.git # Default: Repo containing render.yamlenvVars:- key: MINIO_ROOT_PASSWORDgenerateValue: true # Generate a base64-encoded 256-bit value- key: MINIO_ROOT_USERsync: false # Prompt for a value in the Render Dashboard- key: PORTvalue: 10000disk: # Persistent disk configurationname: datamountPath: /datasizeGB: 10 # optional# A Python cron job that runs every hour- type: cronname: dateruntime: pythonschedule: '0 * * * *'buildCommand: 'true' # ensure it's a stringstartCommand: daterepo: https://github.com/render-examples/docker.git # optional# A Dockerfile-based background worker- type: workername: queueruntime: dockerdockerfilePath: ./sub/Dockerfile # OptionaldockerContext: ./sub/src # Optionalbranch: queue # Optional# A static site- type: webname: my-blogruntime: staticbuildCommand: yarn buildstaticPublishPath: ./buildpreviews:generation: automatic # Enable service previewsbuildFilter:paths:- src/**/*.jsignoredPaths:- src/**/*.test.jsheaders:- path: /*name: X-Frame-Optionsvalue: sameoriginroutes:- type: redirectsource: /olddestination: /new- type: rewritesource: /a/*destination: /a# A Key Value instance- type: keyvaluename: lightningipAllowList: # Required- source: 0.0.0.0/0description: everywhereplan: free # Default: startermaxmemoryPolicy: noeviction # Default: allkeys-lru# List all PostgreSQL databases heredatabases:# A database with one read replica- name: elephantdatabaseName: mydb # Optional (Render may add a suffix)user: adrian # OptionalipAllowList: # Optional (defaults to allow all)- source: 203.0.113.4/30description: office- source: 198.51.100.1description: homereadReplicas:- name: elephant-replica# A database that allows only private network connections- name: private databasedatabaseName: privateipAllowList: [] # No entries in the IP allow list# A database with specified disk size- name: pachydermplan: basic-1gbdiskSizeGB: 35# A database that enables high availability- name: highly available databaseplan: pro-8gbhighAvailability:enabled: true# Environment groupsenvVarGroups:- name: conc-settingsenvVars:- key: CONCURRENCYvalue: 2- key: SECRETgenerateValue: true- name: stripeenvVars:- key: STRIPE_API_URLvalue: 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. yaml
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 unless Supported values include: Native language runtimes
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. If omitted, the default value is |
|
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. |
|
Set to This field has no effect for services that deploy a prebuilt Docker image. If you omit this field:
|
|
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: yaml
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: yaml
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: yaml
|
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. yaml
|
|
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 fieldmountPath: /opt/data # Required fieldsizeGB: 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: yaml
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: yaml
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
+ Show example Key Value definitions
services:# A Key Value instance that defines all available fields- type: keyvaluename: thunderipAllowList: # Allow external connections from only these CIDR blocks- source: 203.0.113.4/30description: office- source: 198.51.100.1description: homeregion: frankfurt # Default: oregonplan: pro # Default: starterpreviewPlan: starter # Default: use the value for 'plan'maxmemoryPolicy: allkeys-lru # Default: allkeys-lru)# A Key Value instance that allows all external connections- type: keyvaluename: lightningipAllowList: # Allow external connections from everywhere- source: 0.0.0.0/0description: everywhere# A Key Value instance that allows only internal connections- type: keyvaluename: private cacheipAllowList: [] # Only allow internal connections
Key-Value-specific fields
Field | Description |
---|---|
|
Required. See Data access control. |
|
The Key Value instance's eviction policy for when it reaches its maximum memory limit. One of the following:
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
+ Show example database definitions
databases:# A basic-4gb database instance with one read replica- name: prod # RequiredpostgresMajorVersion: '16' # Default: most recent supported versionregion: frankfurt # Default: oregonplan: basic-4gb # Default: basic-256mbdatabaseName: prod_app # Default: generated value based on nameuser: app_user # Default: generated value based on nameipAllowList: # Default: allows all connections- source: 203.0.113.4/30description: office- source: 198.51.100.1description: homereadReplicas: # Default: does not add any read replicas- name: prod-replica# A database that allows only private network connections- name: private databasedatabaseName: privateipAllowList: [] # Only allow internal connections# A database that enables high availability- name: highly available databaseplan: pro-16gbhighAvailability: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 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 |
|
The region to deploy the instance to. One of the following:
You can't modify this value after creation. If omitted, the default value is |
|
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 Render Postgres instance:
- Read replicas for increased query throughput
- A high availability standby for rapid recovery from primary instance failures
Field | Description |
---|---|
|
Add one or more read replicas to a Render Postgres instance with the following syntax: yaml
Note the following:
For more information, see Read Replicas for Render Postgres. |
|
Add a high availability standby to a PostgreSQL instance with the following syntax: yaml
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 Render Postgres and Key Value instances from outside Render's network, use the ipAllowList
field:
ipAllowList:- source: 203.0.113.4/30description: 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/0description: 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_URLvalue: https://api.example.com# Generates a base64-encoded 256-bit value# (unless a value already exists)- key: APP_SECRETgenerateValue: true# Prompts for a value in the Render Dashboard on creation# (useful for secrets)- key: STRIPE_API_KEYsync: false# References a property of a database# (see available properties below)- key: DATABASE_URLfromDatabase:name: mydatabaseproperty: connectionString# References an environment variable of another service# (see available properties below)- key: MINIO_PASSWORDfromService:name: miniotype: pservenvVarKey: 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_HOSTfromService:name: miniotype: pservproperty: host# PostgreSQL service- key: DATABASE_URLfromDatabase:name: mydatabaseproperty: connectionString
To reference another service's environment variable, set envVarKey
instead of property
:
- key: MINIO_PASSWORDfromService:name: miniotype: pservenvVarKey: 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: |
|
Render Postgres and Key Value only. The URL for connecting to the datastore over the private network.
|
|
Render Postgres only. The name of the user for your PostgreSQL database. Included as a component of |
|
Render Postgres only. The password for your PostgreSQL database. Included as a component of |
|
Render Postgres 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_KEYsync: 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-groupenvVars:- key: CONCURRENCYvalue: 2- key: SHARED_SECRETgenerateValue: 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.