Blueprint Specification

Sample Blueprint Spec

Here’s a sample Blueprint spec 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 (defaults to starter instance type)
    branch: master # optional (defaults to master)
    rootDir: webdis
    dockerCommand: ./webdis.sh # optional (defaults to Dockerfile command)
    numInstances: 3 # optional (defaults to 1)
    healthCheckPath: /
    envVars:
      - key: REDIS_HOST
        fromService:
          type: redis
          name: lightning
          property: host # available properties are listed below
      - key: REDIS_PORT
        fromService:
          type: redis
          name: lightning
          property: port
      - fromGroup: conc-settings
  # A private Minio instance
  - type: pserv
    name: minio
    env: docker
    repo: https://github.com/render-examples/minio.git # optional
    envVars:
    - key: MINIO_ROOT_PASSWORD
      generateValue: true # will generate a base64-encoded 256-bit secret
    - key: MINIO_ROOT_USER
      sync: false # placeholder for a value to be added in the dashboard
    - key: PORT
      value: 10000
    disk:
      name: data
      mountPath: /data
      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: MINIO_ROOT_PASSWORD
        fromService:
          type: pserv
          name: minio
          envVarKey: MINIO_ROOT_PASSWORD

    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
    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 # optional (defaults to starter instance type)
    maxmemoryPolicy: noeviction # optional (defaults to allkeys-lru)

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 Blueprint spec. Each service must have a type and name. 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
• redis for a Redis instance

Web Services, Workers, Private Services, and Cron Jobs

This includes:

• web for a web service
• worker for a background worker
• pserv for a private service
• cron for a cron job

Type

• In addition to type and name, each service should have an env
• Cron jobs must have a schedule.
• Each service should have a startCommand unless it’s a Docker service. For Docker services (both from images you build and from Dockerfile), Render users the command in your Dockerfile. This can be overridden by specifying dockerCommand in your service definition.

Docker Images

Services in render.yaml can specify a docker image they would like to use. This is done by using an image. The image must contain a url. If the image is private, you must also specify a creds that contains the name of a credential that has access to the image.

env: image

image:
  url: docker.io/my-name/my-image:latest
  creds:
    fromRegistryCreds:
      name: my-credential-name

Repo & Branch

Services in render.yaml can omit a repo. If a repo is missing, we will look to see if an image is specified. If neither an image nor a repo is in the file, it is assumed to be the repo the Blueprint spec 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.

Root Directory

Defining the Root Directory for a service ensures changes to files inside the Root Directory trigger a build and deploy. Changes to files outside the Root Directory will not trigger a build for the service. This is useful for monorepo services.

You can also omit rootDir. The default value of a service’s Root Directory is the top-level directory of the Git repository.

rootDir: webdis

Build Filters

Specifying Build Filters for a service allows you to use glob patterns to include and exclude individual file paths for which changes trigger a build.

Paths for Build Filters are always relative to the top-level directory of your Git repository.

You can also omit buildFilter. By default, a change to any file path will trigger a build for the service.

buildFilter:
  paths:
  - src/**/*.js
  ignoredPaths:
  - src/**/*.test.js

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
• ohio
• singapore

If not specified, the region defaults to oregon.

Environment

The service environment must be one of the following:

• docker
• elixir
• go
• image
• 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 services like PostgresSQL databases and Redis instances:

key: DB_URL
fromDatabase:
  name: prod
  property: connectionString
key: REDIS_URL
fromService:
  type: redis
  name: lightning
  property: connectionString

The set of available properties is defined below.

You can pull environment variables from other servers and cron jobs 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

Environment variables can also be set all at once from an environment group:

fromGroup: my-env-group

Placeholder Environment Variables

There are some environment variables which you don’t want to include in your Blueprint spec 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 Blueprint spec. 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 # will not be copied to preview environments

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

Properties Available to Environment Variables

Environment variables can refer to the following properties on PostgreSQL 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 Redis instances:

• host
• port
• connectionString takes the form of redis://red-xxxxxxxxxxxxxxxxxxxx:6379

Environment variables can refer to the following properties on servers and cron jobs:

• host
• port
• hostport is the service’s host and port separated by a colon, as in host:port

When depending on other Redis instances, servers, or cron jobs, you must include the type and name of the target service. The service does not need to be in the Blueprint spec. If it’s not in the Blueprint spec, it must already exist in your Render account.

Here’s an example of an environment variable referring to a service property:

fromService:
  name: minio
  type: pserv
  property: host

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

Instance Types

The service instance type (plan field) can be specified by name and is case insensitive. Render will maintain the service’s current instance type for existing services where no instance type is specified in the render.yaml. The following values are valid for instance types (plan):

• free (not available for Private Services, Background Workers, and Cron Jobs)
• starter
• standard
• pro
• pro plus
• pro max
• pro ultra

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

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)

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 monorepo Docker services.

dockerfilePath: ./sub/Dockerfile
dockerContext: ./sub/src

Redis Instances

You can create Redis instances by defining them in render.yaml under the services section. A Redis instance requires type, name and ipAllowList — all other fields are optional.

You can also set the Redis plan, previewPlan, region, and maxmemoryPolicy. The following Redis specifications are valid:

services:
  # Redis 1 - all fields defined
  - type: redis
    name: thunder
    ipAllowList: # required - 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 # optional (defaults to oregon)
    plan: pro # optional (defaults to starter instance type)
    previewPlan: starter # optional (defaults to the value specified by 'plan')
    maxmemoryPolicy: allkeys-lru # optional (defaults to allkeys-lru)
  # Redis 2 - all external connections allowed
  - type: redis
    name: lightning
    ipAllowList: # required - allow external connections from everywhere
      - source: 0.0.0.0/0
        description: everywhere
  # Redis 3 - no external connections allowed
  - type: redis
    name: private redis
    ipAllowList: [] # only allow internal connections

See Access Control for details on using the ipAllowList field.

Once a Redis instance is created, you can change the plan, previewPlan, maxmemoryPolicy and ipAllowList fields. Changes to the region field for an existing Redis instance will be ignored.

Like other types of services, you can reference Redis instance properties from environment variables. See Environment Variables for details.

Databases

You can create PostgresSQL databases by defining them in render.yaml. A PostgreSQL database only needs a name — all other fields are optional.

You can also set the PostgreSQL databaseName, user, plan, and postgresMajorVersion. The following PostgreSQL database specifications are 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: 15 # optional (defaults to the latest available, supported versions are 11, 12, 13, 14 and 15)

Just like the dashboard, once a PostgreSQL database is created, you can only change the instance type 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.

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 # optional
  - source: 198.51.100.1

IP address ranges can be given with CIDR notation and the description is optional.

The IP allow list is optional for PostgreSQL databases. If it’s omitted, any source with the right credentials can access your PostgreSQL database.

The IP allow list is required for Redis instances.

You can block all external connections by providing an empty list.

ipAllowList: [] # only allow internal connections

You can allow all external connections with the following CIDR block and description.

ipAllowList: # allow external connections from everywhere
  - source: 0.0.0.0/0
    description: everywhere

Learn more at Database Access Control and Redis Access Control.

Environment Groups

You can define environment groups in your Blueprint spec.

• 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:

envVarGroups:
- name: conc-settings
  envVars:
    - key: CONCURRENCY
      value: 2
    - key: SECRET
      generateValue: true