Blueprint YAML Reference

Every Render Blueprint is backed by a YAML file that defines a set of interconnected services, databases, and environment groups.

A Blueprint file must be named render.yaml, and it must be located in the root directory of a Git repository.

This reference page provides an example Blueprint file, along with documentation for supported fields.

Example Blueprint file

The following render.yaml file demonstrates usage for most supported fields. These fields are documented in further detail below.

+ Show example Blueprint file
#################################################################
# Example render.yaml                                           #
# Do not use this file directly! Consult it for reference only. #
#################################################################

# List all services *except* PostgreSQL databases here
services:
  # A web service on the Ruby native runtime
  - type: web
    runtime: ruby
    name: sinatra-app
    repo: https://github.com/render-examples/sinatra # Default: Repo containing render.yaml
    numInstances: 3   # Manual scaling configuration. Default: 1
    region: frankfurt # Default: oregon
    plan: standard    # Default: starter
    branch: prod      # Default: master
    buildCommand: bundle install
    preDeployCommand: bundle exec ruby migrate.rb
    startCommand: bundle exec ruby main.rb
    autoDeploy: false # Disable automatic deploys
    maxShutdownDelaySeconds: 120 # Increase graceful shutdown period. Default: 30, Max: 300
    domains: # Custom domains
      - example.com
      - www.example.org
    envVars: # Environment variables
      - key: API_BASE_URL
        value: https://api.example.com # Hardcoded value
      - key: APP_SECRET
        generateValue: true # Generate a base64-encoded 256-bit value
      - key: STRIPE_API_KEY
        sync: false # Prompt for a value in the Render Dashboard
      - key: DATABASE_URL
        fromDatabase: # Reference a property of a database (see available properties below)
          name: mydatabase
          property: connectionString
      - key: MINIO_PASSWORD
        fromService: # Reference a value from another service
          name: minio
          type: pserv
          envVarKey: MINIO_ROOT_PASSWORD
      - fromGroup: my-env-group # Add all variables from an environment group

  # A web service that builds from a Dockerfile
  - type: web
    runtime: docker
    name: webdis
    repo: https://github.com/render-examples/webdis.git # Default: Repo containing render.yaml
    rootDir: webdis # Default: Repo root
    dockerCommand: ./webdis.sh # Default: Dockerfile CMD
    scaling: # Autoscaling configuration
      minInstances: 1
      maxInstances: 3
      targetMemoryPercent: 60 # Optional if targetCPUPercent is set
      targetCPUPercent: 60    # Optional if targetMemory is set
    healthCheckPath: /
    registryCredential: # Default: No credential
      fromRegistryCreds:
        name: my-credentials
    envVars:
      - key: REDIS_HOST
        fromService: # Reference a property from another service (see available properties below)
          type: redis
          name: lightning
          property: host
      - key: REDIS_PORT
        fromService:
          type: redis
          name: lightning
          property: port
      - fromGroup: conc-settings

  # A private service with an attached persistent disk
  - type: pserv
    runtime: docker
    name: minio
    repo: https://github.com/render-examples/minio.git # Default: Repo containing render.yaml
    envVars:
    - key: MINIO_ROOT_PASSWORD
      generateValue: true # Generate a base64-encoded 256-bit value
    - key: MINIO_ROOT_USER
      sync: false # Prompt for a value in the Render Dashboard
    - key: PORT
      value: 10000
    disk: # Persistent disk configuration
      name: data
      mountPath: /data
      sizeGB: 10 # 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 Dockerfile-based background worker
  - 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 # Enable service previews
    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 # Default: starter
    maxmemoryPolicy: noeviction # Default: allkeys-lru

# List all PostgreSQL databases here
databases:

  # A database with a read replica
  - 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
    readReplicas:
      - name: elephant-replica

  # A database that allows only private network connections
  - name: private database
    databaseName: private
    ipAllowList: [] # No entries in the IP allow list

  # A database that enables high availability
  - name: highly available database
    plan: pro
    highAvailability:
      enabled: true

# Environment groups
envVarGroups:
  - name: conc-settings
    envVars:
      - key: CONCURRENCY
        value: 2
      - key: SECRET
        generateValue: true
  - name: stripe
    envVars:
      - key: STRIPE_API_URL
        value: https://api.stripe.com/v2

Service fields

Each entry in a Blueprint file’s services list is an object that represents a single, non-PostgreSQL service. (You define PostgreSQL databases in the databases list.)

See below for supported fields.

Essential fields

These fields pertain to a service’s core configuration (name, runtime, region, and so on).

FieldDescription
name

Required. The service’s name. Provide a unique name for each service in your Blueprint file.

If you add the name of an existing service to your Blueprint file, Render attempts to apply the Blueprint’s configuration to that existing service.

type

Required. The type of service. One of the following:

You can’t modify this value after creation.

You define PostgreSQL databases separately, in the databases list.

runtime

Required except for Redis instances. The service’s runtime.

Supported values include the following native language runtimes:

  • node
  • python
  • elixir
  • go
  • ruby
  • rust

Along with the following special-case runtimes:

You can’t modify this value after creation.

This field replaces the env field (env is still supported but is discouraged).

plan

The service’s instance type (see pricing). One of the following:

  • free (not available for private services, background workers, or cron jobs)
  • starter
  • standard
  • pro
  • pro plus

The following additional instance types are available for web services, private services, and background workers:

  • pro max
  • pro ultra

If you omit this option:

  • Render uses starter for a new service.
  • Render retains the current instance type for an existing service.
previewPlan

The instance type to use for this service in preview environments.

If you omit this option, preview instances use the same instance type as the base service.

buildCommand

Required for non-Docker-based services. The command that Render runs to build your service.

Basic examples include:

  • npm install (Node.js)
  • pip install -r requirements.txt (Python)
startCommand

Required for non-Docker-based services. The command that Render runs to start your service.

Basic examples include:

  • npm start (Node.js)
  • gunicorn your_application.wsgi (Python)

Docker-based services set the optional dockerCommand field instead of this field.

schedule

Required for cron jobs, omit otherwise. The schedule for running the cron job, as a cron expression.

preDeployCommand

If specified, this command runs after the service’s buildCommand but before its startCommand. Recommended for running database migrations and other pre-deploy tasks.

Learn more about the pre-deploy command.

region

The region to deploy the service to. One of the following:

  • oregon (default)
  • frankfurt
  • ohio
  • singapore

You can’t modify this value after creation. This field does not apply to static sites.

repo

For Git-based services, the URL of the GitHub/GitLab repo to use. Your Git provider account must have access to the repo.

If omitted, Render uses the repo that contains the render.yaml file itself.

For services that pull a prebuilt Docker image, set image instead of this field.

branch

For Git-based services, the branch of the linked repo to use.

If omitted, Render uses the repo’s default branch.

If you’re using preview environments, you probably don’t want to set this field. If you do set it, Render uses the specified branch in all preview environments, instead of your pull request’s associated branch. This prevents you from testing code changes in the preview environment.

domains

Web services and static sites only. A list of custom domains for the service. Internet-accessible services are always reachable at their .onrender.com subdomain.

For each root domain in the list, Render automatically adds a www. subdomain that redirects to the root domain.

For each www. subdomain in the list, Render automatically adds the corresponding root domain and redirects it to the www. subdomain.

healthCheckPath

Web services only. The path of the service’s health check endpoint for zero-downtime deploys.

maxShutdownDelaySeconds

Web services, private services, and background workers only. The maximum amount of time (in seconds) that Render waits for your application process to exit gracefully after sending it a SIGTERM signal. For details, see Zero-downtime deploys.

After this delay, Render terminates the process with a SIGKILL signal if it’s still running.

Render most commonly shuts down instances as part of redeploying your service or scaling it down. Set this field to give instances more time to finish any existing work before termination.

This value must be an integer between 1 and 300, inclusive.

If omitted, the default value is 30.

Docker

The following fields are specific to Docker-based services. This includes both services that build an image with a Dockerfile (runtime: docker) and services that pull a prebuilt image from a registry (runtime: image).

Building from a Dockerfile

FieldDescription
dockerCommand

The command to run when starting the Docker-based service.

If omitted, Render uses the CMD defined in the Dockerfile.

dockerfilePath

The path to the service’s Dockerfile, relative to the repo root. Typically used for services in a monorepo.

If omitted, Render uses ./Dockerfile.

dockerContext

The path to the service’s Docker build context, relative to the repo root. Typically used for services in a monorepo.

If omitted, Render uses the repo root.

registryCredential

If your Dockerfile references any private images, you must specify a valid credential that can access those images.

This field uses the following format:

registryCredential:
  fromRegistryCreds:
    name: my-credentials # The name of a credential you've added to your account

Add registry credentials in the Render Dashboard from your Account Settings or Team Settings page, or via the Render API.

Pulling a prebuilt image

FieldDescription
image

Details for the Docker image to pull from a registry.

This field uses the following format:

image:
  url: docker.io/my-name/my-image:latest
  creds: # Only for private images
    fromRegistryCreds:
      name: my-credential-name # The name of a credential you've added to your account

Provide creds only if you’re pulling a private image. Add registry credentials in the Render Dashboard from your Account Settings or Team Settings page, or via the Render API.

For more information, see Deploy a Prebuilt Docker Image.

Scaling

Note the following about scaling:

  • Scaling a service with an attached persistent disk is currently in early access.
  • Autoscaling requires a team account.
    • Manual scaling is available for all accounts.
  • If you add an existing service to a Blueprint, that service retains any existing autoscaling settings unless you add the scaling field in your Blueprint.
  • Autoscaling is disabled in preview environments.
    • Instead, autoscaled services always run a number of instances equal to their minInstances.
FieldDescription
numInstances

For a manually scaled service, the number of instances to scale the service to.

The default value is 1.

This value has no effect for services with autoscaling enabled. Configure autoscaling behavior with the scaling field.

scaling

For an autoscaled service, configuration details for the service’s autoscaling behavior.

Example:

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

Build

FieldDescription
buildFilter

File paths in the service’s repo to include or ignore when determining whether to trigger an automatic build. Especially useful for monorepos.

Build filter paths use glob syntax. They are always relative to the repo’s root directory.

When synced, this value fully replaces an existing service’s build filter settings. If you omit this field for a service with existing build filter settings, Render replaces those settings with empty lists.

buildFilter:
  paths: # Only trigger a build with changes to these files
    - src/**/*.js
  ignoredPaths: # Ignore these files, even if they match a path in 'paths'
    - src/**/*.test.js
rootDir

The service’s root directory within its repo. Changes to files outside the root directory do not trigger a build for the service. Set this when working in a monorepo.

If omitted, Render uses the repo’s root directory.

Disks

Attach a persistent disk to a compatible service with the disk field:

disk:
  name: redis-data # Required field
  mountPath: /opt/redis # Required field
  sizeGB: 5 # Default: 10

You can modify the name and mountPath of an existing disk. You can increase the sizeGB of an existing disk, but you can’t reduce it.

Static sites

The following fields are specific to static sites:

FieldDescription
staticPublishPath

Required. The path to the directory that contains the static files to publish, relative to the repo root. Common examples include ./build and ./dist.

headers

Configuration details for a static site’s HTTP response headers.

Example:

headers:
  # Adds X-Frame-Options: sameorigin to all site paths
  - path: /*
    name: X-Frame-Options
    value: sameorigin
  # Adds Cache-Control: must-revalidate to /blog paths
  - path: /blog/*
    name: Cache-Control
    value: must-revalidate

You can modify existing header rules and add new ones. Render preserves any existing header rules that are not included in the Blueprint file.

routes

Configuration details for a static site’s redirect and rewrite routes.

Example:

routes:
  # Redirect (HTTP status 301) from /a to /b
  - type: redirect
    source: /a
    destination: /b
  # Rewrite all /app/* requests to /app
  - type: rewrite
    source: /app/*
    destination: /app

You can modify existing routing rules and add new ones. Render preserves any existing routing rules that are not included in the Blueprint file.

Redis

You define Redis instances in the services field of render.yaml alongside your other non-PostgreSQL services. A Redis instance has the type redis.

Example definitions

+ Show example Redis definitions
services:
  # A Redis instance that defines all available fields
  - type: redis
    name: thunder
    ipAllowList: # 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    # Default: oregon
    plan: pro            # Default: starter
    previewPlan: starter # Default: use the value for 'plan'
    maxmemoryPolicy: allkeys-lru # Default: allkeys-lru)

  # A Redis instance that allows all external connections
  - type: redis
    name: lightning
    ipAllowList: # Allow external connections from everywhere
      - source: 0.0.0.0/0
        description: everywhere

  # A Redis instance that allows only internal connections
  - type: redis
    name: private redis
    ipAllowList: [] # Only allow internal connections

Redis-specific fields

FieldDescription
ipAllowList

Required.

See Data access control.

maxmemoryPolicy

The Redis instance’s eviction policy for when it reaches its maximum memory limit. One of the following:

  • allkeys-lru (default)
  • volatile-lru
  • allkeys-random
  • volatile-random
  • volatile-ttl
  • noeviction

For details on these policies, see Render’s Redis documentation.

Environment variables

See Setting environment variables.

Database fields

Each entry in a Blueprint file’s databases list is an object that represents a PostgreSQL instance.

See below for supported fields.

Example definitions

+ Show example database definitions
databases:
  # A Pro database instance with a read replica
  - name: prod # Required
    postgresMajorVersion: 16 # Default: most recent supported version
    region: frankfurt # Default: oregon
    plan: pro # Default: starter
    databaseName: prod_app # Default: generated value based on name
    user: app_user # Default: generated value based on name
    ipAllowList: # Default: allows all connections
      - source: 203.0.113.4/30
        description: office
      - source: 198.51.100.1
        description: home
    readReplicas: # Default: does not add a read replica
      - name: prod-replica

  # A database that allows only private network connections
  - name: private database
    databaseName: private
    ipAllowList: [] # Only allow internal connections

  # A database that enables high availability
  - name: highly available database
    plan: pro
    highAvailability:
      enabled: true

Essential fields

FieldDescription
name

Required. The PostgreSQL instance’s name. Provide a unique name for each service in your Blueprint file.

If you add the name of an existing instance to your Blueprint file, Render attempts to apply the Blueprint’s configuration to that existing instance.

You can’t modify this value after creation.

plan

The database’s instance type (see pricing). One of the following:

  • free
  • starter
  • standard
  • pro
  • pro plus

You can upgrade an existing instance to a larger instance type, but you can’t downgrade it.

If you omit this option:

  • Render uses starter for a new instance.
  • Render retains the current instance type for an existing service.
region

The region to deploy the instance to. One of the following:

  • oregon (default)
  • frankfurt
  • ohio
  • singapore

You can’t modify this value after creation.

ipAllowList

See Data access control.

PostgreSQL settings

FieldDescription
postgresMajorVersion

The major version of PostgreSQL to use, such as 16.

If omitted, Render uses the most recent version supported by the platform.

You can’t modify this value after creation.

databaseName

The name of your database in the PostgreSQL instance. This is different from the name of the PostgreSQL instance itself.

If omitted, Render automatically generates a name for the database based on name.

You can’t modify this value after creation.

user

The name of the PostgreSQL user to create for your instance.

If omitted, Render automatically generates a name for the database based on name.

You can’t modify this value after creation.

Database replicas

You can add two types of replica to a PostgreSQL instance:

FieldDescription
readReplicas

Add a read replica to a PostgreSQL instance with the following syntax:

readReplicas:
  - name: my-db-replica

Note the following:

  • Although the readReplicas field takes a list, you can add only one read replica to a PostgreSQL instance.
  • If you omit this field, Render preserves any existing read replica for the instance.
  • If you provide a different name from a database’s existing read replica, Render creates a new replica with the provided name and destroys the existing replica.
  • If you provide an empty list (e.g., readReplicas: []), Render destroys any existing replica and does not create a new replica.
  • You can reference a read replica’s properties in another service’s environment variables, as you would for any other database. See Referencing values from other services.

For more information, see PostgreSQL Read Replicas.

highAvailability

Add a high availability standby to a PostgreSQL instance with the following syntax:

highAvailability:
  enabled: true

For your database to support high availability, it must:

  • Belong to a team account
  • Use the Pro instance type or higher
  • Use PostgreSQL version 13 or later

For more information, see PostgreSQL High Availability.

Data access control

To control which IP addresses can access your PostgreSQL databases and Redis instances from outside Render’s network, use the ipAllowList field:

ipAllowList:
  - source: 203.0.113.4/30
    description: office # optional
  - source: 198.51.100.1

The ipAllowList field is required for Redis instances. If you omit this field for a PostgreSQL database, any source with valid credentials can access the database.

IP address ranges use CIDR notation. The description field is optional.

To block all external connections, provide an empty list:

ipAllowList: [] # Only allow internal connections

To allow all external connections, provide the following CIDR block and description:

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

Learn more about PostgreSQL access control and Redis access aontrol.

Setting environment variables

Set names and values for a service’s environment variables in the envVars field:

envVars:
  # Sets a hardcoded value
  # (DO NOT hardcode secrets in your Blueprint file!)
  - key: API_BASE_URL
    value: https://api.example.com

  # Generates a base64-encoded 256-bit value
  # (unless a value already exists)
  - key: APP_SECRET
    generateValue: true

  # Prompts for a value in the Render Dashboard on creation
  # (useful for secrets)
  - key: STRIPE_API_KEY
    sync: false

  # References a property of a database
  # (see available properties below)
  - key: DATABASE_URL
    fromDatabase:
      name: mydatabase
      property: connectionString

  # References an environment variable of another service
  # (see available properties below)
  - key: MINIO_PASSWORD
    fromService:
      name: minio
      type: pserv
      envVarKey: MINIO_ROOT_PASSWORD

  # Adds all environment variables from an environment group
  - fromGroup: my-env-group

A Blueprint can create new environment variables or modify the values of existing ones. Render preserves existing environment variables, even if you omit them from the Blueprint file.

Referencing values from other services

When setting an environment variable in a Blueprint file, you can reference certain values from your other Render services.

You can reference a service that isn’t in the Blueprint, but that service must exist in your Render account for the Blueprint to be valid.

To reference a value from most service types, use the fromService field. For PostgreSQL, instead use fromDatabase:

# Any non-PostgreSQL service
- key: MINIO_HOST
  fromService:
    name: minio
    type: pserv
    property: host

# PostgreSQL service
- key: DATABASE_URL
  fromDatabase:
    name: mydatabase
    property: connectionString

To reference another service’s environment variable, set envVarKey instead of property:

- key: MINIO_PASSWORD
  fromService:
    name: minio
    type: pserv
    envVarKey: MINIO_ROOT_PASSWORD
  • In all cases, provide the service’s name, along with the property or envVarKey to use.
  • For fromService, you must also provide the referenced service’s type.

Supported values of property include:

PropertyDescription
host

Web services and private services only. The service’s hostname on the private network.

port

Web services and private services only. The port of the service’s HTTP server.

hostport

Web services and private services only. The service’s host and port, separated by a colon. Use this value to connect to the service over the private network.

Example: my-service:10000

connectionString

PostgreSQL and Redis only. The URL for connecting to the data store over the private network.

  • For PostgreSQL, has the format postgresql://user:password@host:port/database
  • For Redis, has the format redis://red-xxxxxxxxxxxxxxxxxxxx:6379
user

PostgreSQL only. The name of the user for your PostgreSQL database.

Included as a component of connectionString.

password

PostgreSQL only. The password for your PostgreSQL database.

Included as a component of connectionString.

database

PostgreSQL only. The name of your database within the PostgreSQL instance (not the name of the PostgreSQL instance itself).

Included as a component of connectionString.

Prompting for secret values

Some environment variables contain secret credentials, such an API key or access token. Do not hardcode these values in your render.yaml file!

Instead, you can define these environment variables with sync: false, like so:

- key: STRIPE_API_KEY
  sync: false

During the initial Blueprint creation flow in the Render Dashboard, you’re prompted to provide a value for each environment variable with sync: false:

render.yaml sync false

Note the following limitations:

  • Render prompts you for these values only during the initial Blueprint creation flow.
    • When you update an existing Blueprint, Render ignores any environment variables with sync: false.
    • Add any new secret credentials to your existing services manually.
  • Render does not include sync: false environment variables in preview environments.
    • As a workaround, you can also manually define the environment variable in an environment group that you apply to the service. For details, see this page.
  • You can’t apply sync: false to environment variables defined in an environment group.
    • If you do this, Render ignores the environment variable.

Environment groups

You can define environment groups in the envVarGroups field of your render.yaml file.:

envVarGroups:
- name: my-env-group
  envVars:
    - key: CONCURRENCY
      value: 2
    - key: SHARED_SECRET
      generateValue: true

Each environment group has a name and a list of zero or more envVars. Definitions in the envVars list can use some (but not all) of the same formats as envVars for a service:

  • An environment group can’t reference values from your services, or from other environment groups.
  • You can’t define an environment variable with sync: false in an environment group.

Variable interpolation

Render does not support variable interpolation in a render.yaml file.

To achieve a similar behavior, pair environment variables with a build or start script that performs the interpolation for you.