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)
`private`	boolean	No	Route the service through the cluster’s private load balancer (default: false)
`loadBalancerConfig`	object	No	Load balancer configuration (`public_lb` or `private_lb`)
`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

`private`

boolean Optional When true, the service is fronted by the cluster’s private load balancer instead of the default public one. The service is reachable only from networks peered to your VPC (PrivateLink, VPC peering, transit gateway) — not from the public internet. This requires the cluster to have a private load balancer provisioned. See advanced cluster settings to enable one.

private: true

private is shorthand for loadBalancerConfig.mode: private_lb. Prefer loadBalancerConfig for new services — setting both on the same service is not supported.

`loadBalancerConfig`

object Optional Configures the load balancer that fronts the web service. Use this to explicitly route the service through the cluster’s public or private load balancer.

Field	Type	Required	Description
`mode`	string	Yes	`public_lb` (default) or `private_lb`

When mode is private_lb, the service is fronted by the cluster’s private load balancer and is reachable only from peered networks. The cluster must have a private load balancer provisioned (see advanced cluster settings). Custom domains attached to a private service must have DNS provider credentials configured on the cluster so Porter can provision certificates for custom domains. When mode is public_lb or loadBalancerConfig is omitted, the service is fronted by the cluster’s default public load balancer.

services:
  - name: internal-admin
    type: web
    run: node server.js
    port: 8080
    cpuCores: 0.5
    ramMegabytes: 512
    loadBalancerConfig:
      mode: private_lb
    domains:
      - name: admin.internal.example.com

`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

​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

`private`

`loadBalancerConfig`

`disableTLS`

`autoscaling`

`domains`

`healthCheck`

Advanced Health Checks

`livenessCheck`

`readinessCheck`

`startupCheck`

`pathRouting`

`pathRoutingConfig`

`ingressAnnotations`

`connections`

`serviceMeshEnabled`

`metricsScraping`

`terminationGracePeriodSeconds`

`gpuCoresNvidia`

Complete Example