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)
    numInstances: 3 # optional (defaults to 1)
    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
    scaling:
      minInstances: 1
      maxInstances: 3
      targetMemoryPercent: 60 # optional if targetCPUPercent is set
      targetCPUPercent: 60 # optional if targetMemory is set
    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. The type of a service cannot be changed once it's created. Services created as static sites cannot be changed to other environments.

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. The plan will default to “Starter” if unspecified on service creation. Render will maintain the service’s current plan for existing services where no plan is specified in the render.yaml. 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.

Scaling

Instead of setting a static number of instances for your service, you can autoscale your service based on target CPU and/or memory utilization.

scaling:
  minInstances: 1
  maxInstances: 3
  targetMemoryPercent: 60 # optional if targetCPUPercent is set (valid: 1-90)
  targetCPUPercent: 60 # optional if targetMemory is set (valid: 1-90)

Notes and Limitations

Services with disks cannot be scaled up yet.
Payment info is required to turn on autoscaling.
Services with autoscaling enabled prior to render.yaml support will keep existing settings set in dashboard until this section is specified in their render.yaml file for their service.
Services in preview environments will launch with minInstances number of instances. Autoscaling is disabled for services in preview environments.

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, plan, and postgresMajorVersion. 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
    postgresMajorVersion: 13 # optional (defaults to 13, supported versions are 11, 12, and 13)

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, and changes to the major version will result in an error. 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