Web services in porter.yaml

Web services are HTTP-based services that can be exposed publicly or kept private within your cluster. This is a complete reference for all fields that can be set for a web service in porter.yaml.

Field Reference

Field	Type	Required	Description
`name`	string	Yes	Service identifier (max 31 chars)
`type`	string	Yes	Must be `web`
`run`	string	Yes	Command to execute
`port`	integer	Yes	Port the service listens on
`cpuCores`	number	Yes	CPU allocation
`ramMegabytes`	integer	Yes	Memory allocation in MB
`instances`	integer	No	Number of replicas (default: 1)
`loadBalancers`	array	No	The load balancers that serve the service (`public_lb`, `private_lb`, or `public_alb`)
`private`	boolean	No	Give the service no load balancer (default: false)
`loadBalancerConfig`	object	No	Do not use this field. Use `loadBalancers`.
`disableTLS`	boolean	No	Disable TLS termination
`autoscaling`	object	No	Autoscaling configuration
`domains`	array	No	Custom domain configuration
`healthCheck`	object	No	Combined health check config
`livenessCheck`	object	No	Liveness probe config
`readinessCheck`	object	No	Readiness probe config
`startupCheck`	object	No	Startup probe config
`pathRouting`	array	No	Path-based routing rules
`pathRoutingConfig`	object	No	Path routing options
`ingressAnnotations`	object	No	Custom ingress annotations
`connections`	array	No	External cloud connections
`serviceMeshEnabled`	boolean	No	Enable service mesh
`metricsScraping`	object	No	Prometheus metrics config
`terminationGracePeriodSeconds`	integer	No	Graceful shutdown timeout
`gpuCoresNvidia`	integer	No	NVIDIA GPU cores
`nodeGroup`	string	No	Node group UUID

Basic Example

services:
  - name: api
    type: web
    run: node server.js
    port: 8080
    cpuCores: 0.5
    ramMegabytes: 512
    instances: 2

`loadBalancers`

array Optional The load balancers that serve the web service. Use this field if the service must receive traffic from outside the cluster. Each item is a mode. Write each mode as a simple string.

Mode	Description
`public_lb`	The default public load balancer of the cluster. Porter uses this mode if you do not set `loadBalancers`.
`private_lb`	The private load balancer of the cluster. Only peered networks can send traffic to it.
`public_alb`	The additional public application load balancer of the cluster.

The private_lb mode needs a private load balancer on the cluster. If a private service has custom domains, the cluster must also have DNS credentials. Porter uses these credentials to issue the certificates. The public_alb mode needs an application load balancer on the cluster. The domains of the service must be below one of the root domains of that load balancer.

services:
  - name: api
    type: web
    run: node server.js
    port: 8080
    loadBalancers:
      - public_alb
    domains:
      - name: api.alb.example.com

`private`

boolean Optional If private is true, the service has no load balancer. The service has no external address, public or private. Only other workloads in the cluster can send traffic to it, at its internal URL.

private: true

This is the only condition that loadBalancers does not include, so private: true continues to be available. Set all other conditions with loadBalancers, including the private load balancer of the cluster. The private load balancer is the private_lb mode, not this field. Do not set both fields. If you set both fields, Porter reads the list and ignores the flag.

`loadBalancerConfig`

object Optional

Do not use this field. Use loadBalancers, which also supports the public_alb mode.

This field has one field, mode. The mode field accepts public_lb or private_lb. Existing services continue to operate. Porter reads this field if loadBalancers is not present. The dashboard replaces this field at the next save. Use loadBalancers for new services. Only loadBalancers can select the public_alb mode.

# Deprecated
loadBalancerConfig:
  mode: private_lb

# Use instead
loadBalancers:
  - private_lb

`disableTLS`

boolean Optional Disable TLS termination at the load balancer. Only use this for services that handle their own TLS or for internal testing.

disableTLS: true

Disabling TLS exposes your service over HTTP. Only use this when you have a specific requirement.

`autoscaling`

object Optional Configure horizontal pod autoscaling based on CPU and memory utilization. See Autoscaling Configuration for full documentation.

`domains`

array Optional Configure custom domains for your web service.

Field	Type	Description
`name`	string	Domain name

domains:
  - name: example.com

`healthCheck`

object Optional Configure a combined health check that applies to liveness, readiness, and startup probes.

Field	Type	Description
`enabled`	boolean	Enable health checks
`httpPath`	string	HTTP endpoint to check
`timeoutSeconds`	integer	Request timeout (min: 1)
`initialDelaySeconds`	integer	Initial delay before checking (min: 0)

healthCheck:
  enabled: true
  httpPath: /healthz
  timeoutSeconds: 1
  initialDelaySeconds: 15

Cannot be used together with livenessCheck, readinessCheck, or startupCheck. Use either the combined healthCheck or the individual checks.

For best practices on combining health checks with graceful shutdown for zero-downtime deployments, see Zero-Downtime Deployments.

Advanced Health Checks

For fine-grained control, configure liveness, readiness, and startup probes separately.

`livenessCheck`

object Optional Determines if the container should be restarted.

livenessCheck:
  enabled: true
  httpPath: /livez
  timeoutSeconds: 1
  initialDelaySeconds: 15

`readinessCheck`

object Optional Determines if the container is ready to receive traffic.

readinessCheck:
  enabled: true
  httpPath: /readyz
  timeoutSeconds: 1
  initialDelaySeconds: 15

`startupCheck`

object Optional Used for slow-starting containers. Other probes are disabled until this passes.

startupCheck:
  enabled: true
  httpPath: /startupz
  timeoutSeconds: 1
  initialDelaySeconds: 15

`pathRouting`

array Optional Configure path-based routing to direct requests to different ports or services.

Field	Type	Required	Description
`path`	string	Yes	URL path prefix
`port`	integer	Yes	Port to route to
`serviceName`	string	No	Service to route to (defaults to current)
`appName`	string	No	Application to route to (requires `serviceName`)

pathRouting:
  - path: /api/v1/
    port: 8080
  - path: /api/v2/
    port: 8081
  - path: /admin/
    port: 9000
    serviceName: admin-service
  - path: /auth/
    port: 8080
    appName: auth-app
    serviceName: auth-service

A path must be specified for the default port set in services.port.

`pathRoutingConfig`

object Optional Configure path rewriting behavior for path-based routing.

Field	Type	Description
`rewriteMode`	string	Path rewrite mode

Rewrite Modes:

Mode	Description	Example: `/api/v1/users`
`rewrite-all`	Rewrite entire path to root (default)	`/`
`rewrite-prefix`	Remove the matched prefix only	`/users`
`rewrite-off`	No rewriting, keep original path	`/api/v1/users`

pathRouting:
  - path: /api/v1/
    port: 8080
  - path: /api/v2/
    port: 8081
pathRoutingConfig:
  rewriteMode: rewrite-prefix

`ingressAnnotations`

object Optional Add custom NGINX ingress annotations for advanced configuration.

ingressAnnotations:
  nginx.ingress.kubernetes.io/proxy-connect-timeout: "18000"

Common use cases include increasing upload limits, configuring timeouts, and enabling WebSocket support.

`connections`

array Optional Connect to external cloud services. See Connections Configuration for full documentation.

`serviceMeshEnabled`

boolean Optional Enable service mesh for enhanced inter-service communication with improved performance, reliability, and monitoring.

serviceMeshEnabled: true

Recommended for applications with multiple services that communicate with each other, especially those using gRPC or WebSockets.

`metricsScraping`

object Optional Configure Prometheus metrics scraping for custom application metrics.

Field	Type	Description
`enabled`	boolean	Enable metrics scraping
`path`	string	HTTP path to scrape (default: `/metrics`)
`port`	integer	Port to scrape metrics from
`scrapeIntervalSeconds`	integer	Scrape interval in seconds (default: 60)

metricsScraping:
  enabled: true
  path: /metrics
  port: 9090
  scrapeIntervalSeconds: 60

`terminationGracePeriodSeconds`

integer Optional Seconds to wait for graceful shutdown before forcefully terminating the container.

terminationGracePeriodSeconds: 60

Increase this value for services that need time to complete in-flight requests or cleanup tasks.

`gpuCoresNvidia`

integer Optional Allocate NVIDIA GPU cores for ML inference or GPU-accelerated workloads.

gpuCoresNvidia: 1
nodeGroup: gpu-node-group-uuid

Requires a node group with GPU-enabled instances.

Complete Example

services:
  - name: api
    type: web
    run: npm start
    port: 8080
    cpuCores: 1
    ramMegabytes: 1024

    # Autoscaling
    autoscaling:
      enabled: true
      minInstances: 1
      maxInstances: 10
      cpuThresholdPercent: 80
      memoryThresholdPercent: 80

    # Custom domains
    domains:
      - name: example.com

    # Health checks
    livenessCheck:
      enabled: true
      httpPath: /livez
      timeoutSeconds: 1
      initialDelaySeconds: 15
    readinessCheck:
      enabled: true
      httpPath: /readyz
      timeoutSeconds: 1
      initialDelaySeconds: 15

    # Path routing
    pathRouting:
      - path: /api/v1/
        port: 8080
      - path: /api/v2/
        port: 8081
    pathRoutingConfig:
      rewriteMode: rewrite-prefix

    # Ingress configuration
    ingressAnnotations:
      nginx.ingress.kubernetes.io/proxy-connect-timeout: "18000"

    # Service mesh and metrics
    serviceMeshEnabled: true
    metricsScraping:
      enabled: true
      path: /metrics
      port: 9090
      scrapeIntervalSeconds: 60

    # Cloud connections
    connections:
      - type: awsRole
        role: api-s3-access

    # Graceful shutdown
    terminationGracePeriodSeconds: 30

​Field Reference

​Basic Example

​loadBalancers

​private

​loadBalancerConfig

​disableTLS

​autoscaling

​domains

​healthCheck

​Advanced Health Checks

​livenessCheck

​readinessCheck

​startupCheck

​pathRouting

​pathRoutingConfig

​ingressAnnotations

​connections

​serviceMeshEnabled

​metricsScraping

​terminationGracePeriodSeconds

​gpuCoresNvidia

​Complete Example

Field Reference

Basic Example

`loadBalancers`

`private`

`loadBalancerConfig`

`disableTLS`

`autoscaling`

`domains`

`healthCheck`

Advanced Health Checks

`livenessCheck`

`readinessCheck`

`startupCheck`

`pathRouting`

`pathRoutingConfig`

`ingressAnnotations`

`connections`

`serviceMeshEnabled`

`metricsScraping`

`terminationGracePeriodSeconds`

`gpuCoresNvidia`

Complete Example