Web services in porter.yaml

Complete field reference for web services in porter.yaml including ports, custom domains, health checks, autoscaling, and path-based routing

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	Make service private (default: false)
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 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.

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