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.

Make sure to place render.yaml at the root of your repository.

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 (defaults to starter)
  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, and

env.

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 your Dockerfile. This can be overridden by specifying dockerCommand 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 service
worker for a background worker
pserv for a private service
cron for a cron job

A static site is not considered a service type. It is a 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.

The region of a service cannot be changed once it's created.

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.

Variables defined with sync: false will not be copied to preview environments. To share these variables across preview environments, add them to an environment group instead.

key: SOME_SECRET
sync: false       # will not be copied to preview environments

You can choose to provide a value for these variables before you approve your changes:

render.yaml sync false

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 in host: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

Services with disks cannot be scaled up yet.

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

Just like the dashboard, once a database is created, you can only change the plan it's on. Other `render.yaml` changes to database fields for an existing database will be ignored.

Also like the dashboard, Render may add a random suffix to a given 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.
Environment groups can be used to propagate sync: false environment variables to preview environments.
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