Web Services

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

Type: boolean - Optional

When true, the service is only accessible within the cluster (not publicly exposed).

private: true

---

disableTLS

Type: 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

Type: object - Optional

Configure horizontal pod autoscaling based on CPU and memory utilization.

Field	Type	Description
enabled	boolean	Enable autoscaling
minInstances	integer	Minimum number of replicas
maxInstances	integer	Maximum number of replicas
cpuThresholdPercent	integer	CPU usage threshold (0-100)
memoryThresholdPercent	integer	Memory usage threshold (0-100)

autoscaling:
  enabled: true
  minInstances: 2
  maxInstances: 10
  cpuThresholdPercent: 70
  memoryThresholdPercent: 80

When autoscaling is enabled, the instances field is ignored.

---

domains

Type: array - Optional

Configure custom domains for your web service.

Field	Type	Description
name	string	Domain name

domains:
  - name: api.example.com
  - name: api.staging.example.com

---

healthCheck

Type: 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: /health
  timeoutSeconds: 5
  initialDelaySeconds: 10

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

---

Advanced Health Checks

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

livenessCheck

Type: object - Optional

Determines if the container should be restarted.

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

readinessCheck

Type: object - Optional

Determines if the container is ready to receive traffic.

readinessCheck:
  enabled: true
  httpPath: /readyz
  timeoutSeconds: 3
  initialDelaySeconds: 5

startupCheck

Type: object - Optional

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

startupCheck:
  enabled: true
  httpPath: /startupz
  timeoutSeconds: 10
  initialDelaySeconds: 0

---

pathRouting

Type: 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

Type: 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
pathRoutingConfig:
  rewriteMode: rewrite-prefix

---

ingressAnnotations

Type: object - Optional

Add custom NGINX ingress annotations for advanced configuration.

ingressAnnotations:
  nginx.ingress.kubernetes.io/proxy-body-size: "100m"
  nginx.ingress.kubernetes.io/proxy-connect-timeout: "60"
  nginx.ingress.kubernetes.io/proxy-read-timeout: "60"
  nginx.ingress.kubernetes.io/proxy-send-timeout: "60"

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

---

connections

Type: array - Optional

Connect to external cloud services. See Reference for full documentation.

AWS Role

connections:
  - type: awsRole
    role: my-iam-role

---

serviceMeshEnabled

Type: 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

Type: 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

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

---

terminationGracePeriodSeconds

Type: 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

Type: 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: 2
      maxInstances: 20
      cpuThresholdPercent: 70
      memoryThresholdPercent: 80

    # Custom domains
    domains:
      - name: api.example.com

    # Health checks
    livenessCheck:
      enabled: true
      httpPath: /livez
      timeoutSeconds: 5
    readinessCheck:
      enabled: true
      httpPath: /readyz
      timeoutSeconds: 3

    # 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-body-size: "50m"

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

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

    # Graceful shutdown
    terminationGracePeriodSeconds: 30