YAML Specification
Here’s a sample YAML file that uses most of the supported settings for infrastructure as code. Use it to get started with your own render.yaml
.
services:
# A Docker web service
- type: web
name: webdis
env: docker
repo: https://github.com/render-examples/webdis.git # optional
region: oregon # optional (defaults to oregon)
plan: standard # optional
branch: master # optional (uses repo default)
dockerCommand: ./webdis.sh # optional (defaults to Dockerfile command)
healthCheckPath: /
envVars:
- key: REDIS_HOST
fromService:
name: redis
type: pserv
property: host # available properties are listed below
- key: REDIS_PORT
fromService:
name: redis
type: pserv
property: port
- fromGroup: conc-settings
# A private Redis instance
- type: pserv
name: redis
env: docker
repo: https://github.com/render-examples/redis.git # optional
envVars:
- key: GENERATED_SECRET
generateValue: true # will generate a base64-encoded 256-bit secret
- key: DASHBOARD_SECRET
sync: false # placeholder for a value to be added in the dashboard
disk:
name: redis-data
mountPath: /var/lib/redis
sizeGB: 10 # optional
# A Ruby web service
- type: web
name: sinatra
env: ruby
repo: https://github.com/renderinc/sinatra-example.git
numInstances: 3
buildCommand: bundle install
startCommand: bundle exec ruby main.rb
domains:
- test0.render.com
- test1.render.com
envVars:
- key: STRIPE_API_KEY
value: Z2V0IG91dHRhIGhlcmUhCg
- key: DB_URL
fromDatabase:
name: elephant
property: connectionString
- key: REDIS_SECRET
fromService:
type: pserv
name: redis
envVarKey: GENERATED_SECRET
autoDeploy: false # optional
# A Python cron job that runs every hour
- type: cron
name: date
env: python
schedule: "0 * * * *"
buildCommand: "true" # ensure it's a string
startCommand: date
repo: https://github.com/render-examples/docker.git # optional
# A background worker that consumes a queue
- type: worker
name: queue
env: docker
dockerfilePath: ./sub/Dockerfile # optional
dockerContext: ./sub/src # optional
branch: queue # optional
# A static site
- type: web
name: my blog
env: static
buildCommand: yarn build
staticPublishPath: ./build
pullRequestPreviewsEnabled: true # optional
headers:
- path: /*
name: X-Frame-Options
value: sameorigin
routes:
- type: redirect
source: /old
destination: /new
- type: rewrite
source: /a/*
destination: /a
databases:
- 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
- name: private database
databaseName: private
ipAllowList: [] # only allow internal connections
envVarGroups:
- name: conc-settings
envVars:
- key: CONCURRENCY
value: 2
- key: SECRET
generateValue: true
- key: USER_PROVIDED_SECRET
sync: false
- name: stripe
envVars:
- key: STRIPE_API_URL
value: https://api.stripe.com/v2
Services
You can define services in your YAML file.
- Each service should have a
type
,name
, andenv
. - Cron jobs must have a
schedule
. - Each service should have a
startCommand
unless it’s a Docker service. For Docker services, Render users the command in yourDockerfile
. This can be overridden by specifyingdockerCommand
in your service definition.
Repo & Branch
Services in render.yaml
can omit a repo. If a repo is missing, it is assumed to be the repo the YAML file is in. The specified repo must be accessible to you.
You can also omit a branch. Render will use the repo’s default branch if it’s omitted.
Type
The service type must be one of the following:
web
for a web serviceworker
for a background workerpserv
for a private servicecron
for a cron job
web
service with a static
environment.
Region
A service can be deployed in a specific region by adding an optional region
field. If specified, the region field must be one of following:
oregon
frankfurt
If not specified, the region defaults to oregon
.
Environment
The service environment must be one of the following:
docker
elixir
go
node
python
ruby
rust
static
Environment Variables
A service can specify zero or more environment variables. These variables can be plain variables as follows:
key: A
value: B
They can depend on the properties of other Render resources like databases:
key: DB_URL
fromDatabase:
name: prod
property: connectionString
The set of available properties is defined below.
You can pull copy environment variables from other services with a different key:
key: MYSQL_PASSWORD
fromService:
name: mysql
type: pserv
envVarKey: PASSWORD
The value of an environment variable can also be generated (only if the key doesn’t already exist).
key: APP_SECRET
generateValue: true
There are some environment variables which you don’t want to include in your YAML file and are not
generated such as external secrets. For those, you can specify a placeholder environment variable
with sync: false
. This allows you to declare that an environment variable is expected without
having to specify a value in your YAML file. You will later be prompted to enter a value for these
variables on the dashboard before your deployment is finalized.
key: SOME_SECRET
sync: false
You can choose to provide a value for these variables before you approve your changes:
Environment variables can also be set all at once from an environment group:
fromGroup: my-env-group
Properties Available to Environment Variables
Environment variables can refer to the following properties on databases:
host
port
database
is the PostgreSQL database name (not the friendly name)user
password
connectionString
Environment variables can refer to the following properties on services:
host
port
hostport
is the service’s host and port separated by a colon, as inhost
:port
When depending on other services, you must include the type
and name
of the target service. The
service does not need to be in the YAML file. If it’s not in the YAML file, it must already exist in your Render account.
Here’s an example of an environment variable referring to a service property:
fromService:
name: redis
type: pserv
property: host
render.yaml
does not support variable interpolation. The best way to accomplish this
is to pair environment variables with a build or start script that does the interpolation for you.
Disks
You can specify whether your service has a Disk attached to it. A disk must have a name
, mountPath
, and (optionally) a size in GB (sizeGB
).
disk:
name: redis-data
mountPath: /opt/redis
sizeGB: 10
Custom Domains
You can specify custom domains for your service in the domains
field. If a domain is an apex
domain, a www.
subdomain will be added automatically and will redirect to the apex domain.
If a domain is a www.
subdomain, the apex domain will be added automatically and will redirect to the www.
domain.
Every web service is always accessible at its .onrender.com
subdomain.
Static Site Headers
You can specify HTTP headers for your static site with the headers
field like
you can in the dashboard.
headers:
# add X-Frame-Options: sameorigin to all paths
- path: /*
name: X-Frame-Options
value: sameorigin
# add Cache-Control: must-revalidate to /blog paths
- path: /blog/*
name: Cache-Control
value: must-revalidate
Static Site Routes
You can specify redirect and rewrite routes for your static site with
the routes
field just like in the dashboard.
routes:
# redirect (HTTP status 301) from /a to /b
- type: redirect
source: /a
destination: /b
# rewrite /app/* requests to /app
- type: rewrite
source: /app/*
destination: /app
Plans
The service plan can be specified by name and is case insensitive. If it’s omitted, the plan will default to the “Starter” plan. The following values are valid for plans:
- Starter
- Starter Plus
- Standard
- Standard Plus
- Pro
- Pro Plus
Health Check Path
You can set a health check path for your HTTP service for zero downtime
deploys by adding the
healthCheckPath
field.
healthCheckPath: /healthz
Number of Instances
You can set the number of instances you want for your service by setting the numInstances
field.
numInstances: 3
Docker Options
If your service is Docker-based, i.e. it has env: docker
, then you can optionally specify the
dockerfilePath
and dockerContext
. These are relative to your repo root. This is useful for
mono-repo Docker services.
dockerfilePath: ./sub/Dockerfile
dockerContext: ./sub/src
Databases
You can create databases by defining them in render.yaml
. A database only needs a name
— all other fields are optional.
You can also set the PostgreSQL databaseName
, user
, and plan
. The following two database specifications are both valid:
databases:
# db 1
- name: staging
# db 2
- name: prod
region: frankfurt
plan: pro
databaseName: prod_app
user: app_user
ipAllowList: # optional (defaults to allow all)
- source: 203.0.113.4/30
description: office
- source: 198.51.100.1
description: home
# db 3
- name: private database
databaseName: private
ipAllowList: [] # only allow internal connections
databaseName
.
Access Control
You can specify which IP addresses can access your database from outside Render’s network using an ipAllowList
.
ipAllowList:
- source: 203.0.113.4/30
description: office
- source: 198.51.100.1
description: home
IP address ranges can be given with CIDR notation and the description is optional.
The IP allow list is optional. If it’s omitted, any source with the right credentials can access your database.
You can block all external access by providing an empty list.
ipAllowList: [] # only allow internal connections
Learn more at Database Access Control.
Environment Groups
You can define environment groups in your YAML file.
- Environment groups can have zero or more environment variables.
- The environment variables in an environment group cannot depend on other resources, unlike the environment variables in a service. However, you can still generate environment variables within an environment group. The following is a valid environment group spec:
- name: conc-settings
envVars:
- key: CONCURRENCY
value: 2
- key: SECRET
generateValue: true
- key: USER_PROVIDED_SECRET
sync: false