render-private-services

# Render Private Services Private services are identical to web services except they have **no public URL**. They are reachable only by other Render services on the same **private network** (same region + workspace). Use them for internal APIs, microservices, gRPC servers, sidecar processes, and anything that should never face the internet. ## When to Use - Building an **internal API** or **microservice** behind a public gateway - Running a **gRPC**, **TCP**, or other non-HTTP server that only your services call - Deploying infrastructure components (**Elasticsearch**, **ClickHouse**, **RabbitMQ**) - Choosing between a **private service** and a **background worker** For public-facing HTTP services, use **render-web-services**. For services that don't receive any traffic, use **render-background-workers**. ## Private Service vs Background Worker | Criterion | Private Service | Background Worker | |-----------|----------------|-------------------| | Binds to a port | **Yes** (required) | No | | Receives private network traffic | **Yes** | No | | Sends outbound traffic | Yes | Yes | | Has internal hostname | **Yes** | No | | Use case | Internal APIs, gRPC, TCP servers | Queue consumers, async processors | **Rule of thumb:** If the process **listens on a port** and other services call it, it's a private service. If it **pulls work from a queue** and never receives requests, it's a background worker. ## How Private Services Work - No `onrender.com` subdomain—not reachable from the internet - Reachable at `<service-name>:<port>` on the private network by services in the same region and workspace - Can listen on **any port** (except restricted system ports)—not limited to HTTP or port 10000 - Supports **any protocol**: HTTP, gRPC, TCP, WebSocket, custom binary protocols - Same build/deploy lifecycle as web services (build command, start command, pre-deploy, health checks via the private network) - Supports persistent disks, scaling, Docker runtime—same capabilities as web services ## Connecting to a Private Service Other services reference a private service via its **internal hostname and port**: ``` http://<service-name>:<port> ``` In Blueprints, wire the address using `fromService`: ```yaml - key: INTERNAL_API_URL fromService: name: my-api type: pserv property: hostport ``` Available `fromService` properties for `pserv`: | Property | Value | |----------|-------| | `host` | Internal hostname (e.g. `my-api`) | | `port` | Port the service listens on | | `hostport` | `host:port` combined (e.g. `my-api:10000`) | You can also reference a specific env var from the private service using `envVarKey` instead of `property`. ## Port Binding Private services **must bind to at least one port**. If your process does not need to receive traffic, create a background worker instead. - Bind to `0.0.0.0` (not `127.0.0.1` or `localhost`) - The `PORT` env var defaults to `10000`, but you can listen on any non-restricted port - For non-HTTP protocols (gRPC, TCP), configure your server on the desired port and tell consumers the `hostport` ## Blueprint Configuration ```yaml services: - type: pserv name: internal-api runtime: node region: oregon plan: starter buildCommand: npm ci && npm run build startCommand: npm start envVars: - key: DATABASE_URL fromDatabase: name: db property: connectionString ``` ### Microservices pattern (gateway + internal services) ```yaml services: - type: web name: gateway runtime: node plan: starter region: oregon buildCommand: npm ci && npm run build startCommand: npm start envVars: - key: USER_SERVICE_URL fromService: name: user-service type: pserv property: hostport - key: BILLING_SERVICE_URL fromService: name: billing-service type: pserv property: hostport - type: pserv name: user-service runtime: node plan: starter region: oregon buildCommand: npm ci startCommand: node server.js envVars: - key: DATABASE_URL fromDatabase: name: db property: connectionString - type: pserv name: billing-service runtime: python plan: starter region: oregon buildCommand: pip install -r requirements.txt startCommand: gunicorn billing:app envVars: - key: DATABASE_URL fromDatabase: name: db property: connectionString ``` ## References | Document | Contents | |----------|----------| | `references/patterns.md` | Microservice topology, gRPC setup, sidecar patterns, health checks for private services | ## Related Skills - **render-web-services** — Public HTTP services - **render-networking** — Private network, DNS, service discovery - **render-background-workers** — Services that don't receive traffic - **render-blueprints** — Full `render.yaml` schema, `fromService` wiring - **render-scaling** — Instance types and autoscaling for private services