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
runtime: 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
runtime: 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
runtime: 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
preDeployCommand: bundle exec ruby migrate.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
runtime: 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
runtime: docker
dockerfilePath: ./sub/Dockerfile # optional
dockerContext: ./sub/src # optional
branch: queue # optional
# A static site
- type: web
name: my blog
runtime: 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 serviceworker
for a background workerpserv
for a private servicecron
for a cron jobredis
for a Redis instance
web
service with a static
runtime.
The type of a service cannot be changed once it's created. Services created as static sites cannot be changed to other runtimes.
Web Services, Workers, Private Services, and Cron Jobs
This includes:
web
for a web serviceworker
for a background workerpserv
for a private servicecron
for a cron job
Type
- In addition to
type
andname
, each service should have anruntime
- 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 yourDockerfile
. This can be overridden by specifyingdockerCommand
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.
runtime: 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.
If you explicitly set a branch
then that will apply to all preview environments created. If you omit this then the rules above will apply and for preview environments, the branch the pull request is against would be deployed.
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
.
Runtime
The service runtime must be one of the following:
docker
elixir
go
image
node
python
ruby
rust
static
Note that runtime was previously specified using env:
instead. Both keys work, but for clarity, runtime:
is preferred.
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.
Placeholder environment variables defined with sync: false
will not be copied to preview environments, unless they’re part of a separately managed environment group.
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 ofredis://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 inhost
: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
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
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
The instance type will default to starter
if plan
is unspecified on service creation.
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)
- 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 theirrender.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 runtime: 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.
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 # 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
Placeholder environment variables defined with sync: false
don’t have any effect when they’re included as part an environment group in a blueprint.
Blueprint Specification
- Web Services, Workers, Private Services, and Cron Jobs
- Type
- Docker Images
- Repo & Branch
- Root Directory
- Build Filters
- Region
- Runtime
- Environment Variables
- Placeholder Environment Variables
- Properties Available to Environment Variables
- Disks
- Custom Domains
- Static Site Headers
- Static Site Routes
- Instance Types
- Health Check Path
- Number of Instances
- Scaling
- Docker Options
- Redis Instances