Blueprint Spec

# Render Blueprint Specification Complete reference for render.yaml Blueprint files. Blueprints define your infrastructure as code for reproducible deployments on Render. ## Overview A Blueprint is a YAML file (typically `render.yaml`) placed in your repository root that describes: - Services (web, worker, cron, static, private) - Databases (PostgreSQL, Redis) - Environment variables and secrets - Scaling and resource configuration - Project organization ## Root-Level Structure ```yaml # Top-level fields services: [] # Array of service definitions databases: [] # Array of PostgreSQL databases envVarGroups: [] # Reusable environment variable groups (optional) projects: [] # Project organization (optional) ungrouped: [] # Resources outside projects (optional) previews: # Preview environment configuration (optional) generation: auto_preview | manual | none ``` ## Service Types ### Web Services (`type: web`) HTTP services, APIs, and web applications. Publicly accessible via HTTPS. **Required fields:** - `name`: Unique service identifier - `type`: Must be `web` - `runtime`: Language/environment (see Runtimes section) - `buildCommand`: Command to build the application - `startCommand`: Command to start the server **Common optional fields:** - `plan`: Instance type (default: `free`) - `region`: Deployment region (default: `oregon`) - `branch`: Git branch to deploy (default: `main`) - `autoDeploy`: Auto-deploy on push (default: `true`) - `envVars`: Environment variables array - `healthCheckPath`: Health check endpoint (default: `/`) - `numInstances`: Number of instances (manual scaling) - `scaling`: Autoscaling configuration **Example:** ```yaml services: - type: web name: api-server runtime: node plan: free buildCommand: npm ci startCommand: npm start branch: main autoDeploy: true envVars: - key: NODE_ENV value: production - key: PORT value: 10000 ``` ### Worker Services (`type: worker`) Background job processors, queue consumers. Not publicly accessible. **Required fields:** - `name`: Unique service identifier - `type`: Must be `worker` - `runtime`: Language/environment - `buildCommand`: Command to build - `startCommand`: Command to start worker process **Key differences from web services:** - No public URL - No health checks - No port binding required **Example:** ```yaml services: - type: worker name: job-processor runtime: python plan: free buildCommand: pip install -r requirements.txt startCommand: celery -A tasks worker --loglevel=info envVars: - key: REDIS_URL fromDatabase: name: redis property: connectionString ``` ### Cron Jobs (`type: cron`) Scheduled tasks that run on a cron schedule. **Required fields:** - `name`: Unique service identifier - `type`: Must be `cron` - `runtime`: Language/environment - `schedule`: Cron expression - `buildCommand`: Command to build - `startCommand`: Command to execute on schedule **Schedule format:** Standard cron syntax (minute hour day month weekday) **Examples:** - `0 0 * * *` - Daily at midnight UTC - `*/15 * * * *` - Every 15 minutes - `0 9 * * 1` - Every Monday at 9 AM UTC **Example:** ```yaml services: - type: cron name: daily-backup runtime: node schedule: "0 2 * * *" buildCommand: npm ci startCommand: node scripts/backup.js envVars: - key: DATABASE_URL fromDatabase: name: postgres property: connectionString ``` ### Static Sites (`type: static` or `type: web` with `runtime: static`) Serve static HTML/CSS/JS files via CDN. **Required fields:** - `name`: Unique service identifier - `type`: `web` - `runtime`: `static` - `buildCommand`: Command to build static assets - `staticPublishPath`: Path to built files (e.g., `./build`, `./dist`) **Optional configuration:** - `routes`: Routing rules for SPAs - `headers`: Custom HTTP headers - `buildFilter`: Path filters for build triggers **Example:** ```yaml services: - type: web name: react-app runtime: static buildCommand: npm ci && npm run build staticPublishPath: ./dist routes: - type: rewrite source: /* destination: /index.html headers: - path: /* name: Cache-Control value: public, max-age=31536000, immutable ``` ### Private Services (`type: pserv`) Internal services accessible only within your Render account. **Required fields:** - `name`: Unique service identifier - `type`: Must be `pserv` - `runtime`: Language/environment - `buildCommand`: Command to build - `startCommand`: Command to start **Use cases:** - Internal APIs - Database proxies - Microservices not exposed to internet **Example:** ```yaml services: - type: pserv name: internal-api runtime: go plan: free buildCommand: go build -o bin/app startCommand: ./bin/app ``` ## Runtimes ### Native Runtimes **Node.js (`runtime: node`):** - Versions: 14, 16, 18, 20, 21 - Default version: 20 - Specify version in `package.json` engines field **Python (`runtime: python`):** - Versions: 3.8, 3.9, 3.10, 3.11, 3.12 - Default version: 3.11 - Specify version in `runtime.txt` or `Pipfile` **Go (`runtime: go`):** - Versions: 1.20, 1.21, 1.22, 1.23 - Uses go modules - Version from `go.mod` **Ruby (`runtime: ruby`):** - Versions: 3.0, 3.1, 3.2, 3.3 - Uses Bundler - Version from `.ruby-version` or `Gemfile` **Rust (`runtime: rust`):** - Latest stable version - Uses Cargo **Elixir (`runtime: elixir`):** - Latest stable version - Uses Mix ### Docker Runtime **Docker (`runtime: docker`):** Build from a Dockerfile in your repository. **Additional fields:** - `dockerfilePath`: Path to Dockerfile (default: `./Dockerfile`) - `dockerContext`: Build context directory (default: `.`) **Example:** ```yaml services: - type: web name: docker-app runtime: docker dockerfilePath: ./docker/Dockerfile dockerContext: . plan: free ``` **Image (`runtime: image`):** Deploy pre-built Docker images from a registry. **Additional fields:** - `image`: Image URL (e.g., `registry.com/image:tag`) - `registryCredential`: Credentials for private registries **Example:** ```yaml services: - type: web name: prebuilt-app runtime: image image: myregistry.com/app:v1.2.3 plan: free ``` ## Service Plans Available instance types: | Plan | RAM | CPU | Price | |------|-----|-----|-------| | `free` | 512 MB | 0.5 | Free (750 hrs/mo) | | `starter` | 512 MB | 0.5 | $7/month | | `standard` | 2 GB | 1 | $25/month | | `pro` | 4 GB | 2 | $85/month | | `pro_plus` | 8 GB | 4 | $175/month | **Always default to `plan: free` unless user specifies otherwise.** ## Regions Available deployment regions: - `oregon` (US West) - Default - `ohio` (US East) - `virginia` (US East) - `frankfurt` (EU) - `singapore` (Asia) **Example:** ```yaml services: - type: web name: my-app runtime: node region: frankfurt ``` ## Environment Variables Three patterns for defining environment variables: ### 1. Hardcoded Values For non-sensitive configuration: ```yaml envVars: - key: NODE_ENV value: production - key: API_URL value: https://api.example.com - key: LOG_LEVEL value: info ``` ### 2. Generated Secrets Render generates a base64-encoded 256-bit random value: ```yaml envVars: - key: SESSION_SECRET generateValue: true - key: ENCRYPTION_KEY generateValue: true ``` ### 3. User-Provided Secrets Prompt user for values during Blueprint creation: ```yaml envVars: - key: STRIPE_SECRET_KEY sync: false - key: JWT_SECRET sync: false - key: API_KEY sync: false ``` **The `sync: false` flag means "user will fill this in the Dashboard".** ### 4. Database References Link to database connection strings: ```yaml envVars: - key: DATABASE_URL fromDatabase: name: postgres property: connectionString - key: REDIS_URL fromDatabase: name: redis property: connectionString ``` **Available properties:** - `connectionString`: Full connection URL - `host`: Database host - `port`: Database port - `user`: Database username - `password`: Database password - `database`: Database name - `hostport`: Combined `host:port` ### 5. Service References Link to other services: ```yaml envVars: - key: API_URL fromService: name: api-server type: web property: host ``` ### 6. Environment Variable Groups Reusable groups shared across services: ```yaml envVarGroups: - name: shared-config envVars: - key: LOG_LEVEL value: info - key: ENVIRONMENT value: production services: - type: web name: web-app runtime: node envVars: - fromGroup: shared-config - key: PORT value: 10000 ``` ## Databases ### PostgreSQL ```yaml databases: - name: postgres databaseName: myapp_prod user: myapp_user plan: free postgresMajorVersion: "15" ipAllowList: [] ``` **Plans:** - `free`: 1 GB storage, 97 MB RAM, 0.1 CPU - `basic-256mb`, `basic-512mb`, `basic-1gb`, `basic-4gb` - `pro-4gb`, `pro-8gb`, `pro-16gb`, etc. - `accelerated-4gb`, `accelerated-8gb`, etc. (SSD-backed) **Key fields:** - `name`: Identifier for references - `databaseName`: Actual PostgreSQL database name - `user`: Database username - `postgresMajorVersion`: PostgreSQL version (11-16) - `ipAllowList`: Array of CIDR blocks (empty = internal only) - `diskSizeGB`: Storage size (paid plans only) **High Availability (paid plans):** ```yaml databases: - name: postgres databaseName: myapp_prod plan: pro-4gb highAvailabilityEnabled: true ``` **Read Replicas (paid plans):** ```yaml databases: - name: postgres databaseName: myapp_prod plan: pro-4gb readReplicas: - name: read-replica-1 region: ohio - name: read-replica-2 region: frankfurt ``` ### Redis (Key-Value Store) ```yaml databases: - name: redis plan: free maxmemoryPolicy: allkeys-lru ipAllowList: [] ``` **Plans:** Same as PostgreSQL **maxmemoryPolicy options:** - `allkeys-lru`: Evict least recently used keys - `volatile-lru`: Evict LRU keys with TTL - `allkeys-random`: Evict random keys - `volatile-random`: Evict random keys with TTL - `volatile-ttl`: Evict keys with soonest TTL - `noeviction`: Return errors when memory full ## Scaling ### Manual Scaling Fixed number of instances: ```yaml services: - type: web name: my-app runtime: node plan: standard numInstances: 3 ``` ### Autoscaling Dynamic scaling based on CPU/memory (Professional workspace required): ```yaml services: - type: web name: my-app runtime: node plan: standard scaling: minInstances: 1 maxInstances: 5 targetCPUPercent: 60 targetMemoryPercent: 70 ``` **Notes:** - Autoscaling disabled in preview environments - Preview environments run `minInstances` count - Requires Professional or higher workspace ## Health Checks Configure health check endpoints: ```yaml services: - type: web name: my-app runtime: node healthCheckPath: /health ``` **Default:** `/` (root path) **Recommended:** Add a dedicated `/health` endpoint that returns `200 OK`. ## Build Filters Control when builds are triggered based on changed files: ```yaml services: - type: web name: frontend runtime: static buildFilter: paths: - frontend/** ignoredPaths: - frontend/README.md - frontend/**/*.test.js ``` **Behavior:** - If `paths` specified: Build only when files in those paths change - If `ignoredPaths` specified: Don't build when only ignored files change ## Projects and Environments Organize services into projects with multiple environments: ```yaml projects: - name: my-application environments: - name: production services: - type: web name: prod-api runtime: node plan: pro buildCommand: npm ci startCommand: npm start databases: - name: prod-postgres plan: pro-4gb networking: isolation: enabled permissions: protection: enabled - name: staging services: - type: web name: staging-api runtime: node plan: starter buildCommand: npm ci startCommand: npm start databases: - name: staging-postgres plan: free ``` **Environment features:** - `networking.isolation`: Enable network isolation between environments - `permissions.protection`: Require approval for environment changes ## Preview Environments Configure automatic preview environments for pull requests: ```yaml previews: generation: auto_preview # auto_preview | manual | none ``` **Options:** - `auto_preview`: Create preview environment for each PR automatically - `manual`: User manually triggers preview creation - `none`: Disable preview environments ## Complete Example Full-featured Blueprint with multiple services and databases: ```yaml services: # Web service - type: web name: web-app runtime: node plan: free region: oregon buildCommand: npm ci && npm run build startCommand: npm start branch: main autoDeploy: true healthCheckPath: /health envVars: - key: NODE_ENV value: production - key: DATABASE_URL fromDatabase: name: postgres property: connectionString - key: REDIS_URL fromDatabase: name: redis property: connectionString - key: JWT_SECRET sync: false # Background worker - type: worker name: queue-worker runtime: node plan: free buildCommand: npm ci startCommand: node worker.js envVars: - key: REDIS_URL fromDatabase: name: redis property: connectionString # Cron job - type: cron name: daily-cleanup runtime: node schedule: "0 3 * * *" buildCommand: npm ci startCommand: node scripts/cleanup.js envVars: - key: DATABASE_URL fromDatabase: name: postgres property: connectionString # Static frontend - type: web name: frontend runtime: static buildCommand: npm ci && npm run build staticPublishPath: ./dist routes: - type: rewrite source: /* destination: /index.html databases: - name: postgres databaseName: app_production user: app_user plan: free postgresMajorVersion: "15" ipAllowList: [] - name: redis plan: free maxmemoryPolicy: allkeys-lru ipAllowList: [] ``` ## Validation Validate your Blueprint before deploying (when CLI command is available): ```bash render blueprint validate ``` **Common validation errors:** - Missing required fields - Invalid runtime values - Incorrect environment variable references - Invalid cron expressions - Invalid YAML syntax ## Best Practices 1. **Always use `plan: free` by default** - Let users upgrade if needed 2. **Mark all secrets with `sync: false`** - Never hardcode sensitive values 3. **Use `fromDatabase` for database URLs** - Automatic internal connection strings 4. **Add health check endpoints** - Faster deployment detection 5. **Use non-interactive build commands** - Prevents build hangs 6. **Bind to `0.0.0.0:$PORT`** - Required for web services 7. **Use environment variable groups** - Share config across services 8. **Enable autoDeploy: true** - Deploy automatically on push 9. **Set appropriate regions** - Choose closest to your users 10. **Use build filters** - Optimize build triggers in monorepos ## Additional Resources - Official Blueprint Specification: https://render.com/docs/blueprint-spec - Render CLI Documentation: https://render.com/docs/cli - Environment Variables Guide: https://render.com/docs/environment-variables