Skip to main content
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

FieldTypeRequiredDescription
namestringYesService identifier (max 31 chars)
typestringYesMust be web
runstringYesCommand to execute
portintegerYesPort the service listens on
cpuCoresnumberYesCPU allocation
ramMegabytesintegerYesMemory allocation in MB
instancesintegerNoNumber of replicas (default: 1)
privatebooleanNoMake service private (default: false)
disableTLSbooleanNoDisable TLS termination
autoscalingobjectNoAutoscaling configuration
domainsarrayNoCustom domain configuration
healthCheckobjectNoCombined health check config
livenessCheckobjectNoLiveness probe config
readinessCheckobjectNoReadiness probe config
startupCheckobjectNoStartup probe config
pathRoutingarrayNoPath-based routing rules
pathRoutingConfigobjectNoPath routing options
ingressAnnotationsobjectNoCustom ingress annotations
connectionsarrayNoExternal cloud connections
serviceMeshEnabledbooleanNoEnable service mesh
metricsScrapingobjectNoPrometheus metrics config
terminationGracePeriodSecondsintegerNoGraceful shutdown timeout
gpuCoresNvidiaintegerNoNVIDIA GPU cores
nodeGroupstringNoNode 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 only accessible within the cluster (not publicly exposed). 
private: true

​
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.
FieldTypeDescription
namestringDomain name
domains:
  - name: example.com

​
healthCheck

object Optional Configure a combined health check that applies to liveness, readiness, and startup probes.
FieldTypeDescription
enabledbooleanEnable health checks
httpPathstringHTTP endpoint to check
timeoutSecondsintegerRequest timeout (min: 1)
initialDelaySecondsintegerInitial 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.
FieldTypeRequiredDescription
pathstringYesURL path prefix
portintegerYesPort to route to
serviceNamestringNoService to route to (defaults to current)
appNamestringNoApplication 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.
FieldTypeDescription
rewriteModestringPath rewrite mode
Rewrite Modes:
ModeDescriptionExample: /api/v1/users
rewrite-allRewrite entire path to root (default)/
rewrite-prefixRemove the matched prefix only/users
rewrite-offNo 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.
FieldTypeDescription
enabledbooleanEnable metrics scraping
pathstringHTTP path to scrape (default: /metrics)
portintegerPort to scrape metrics from
scrapeIntervalSecondsintegerScrape 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