Traits Guide

This guide covers using traits to add operational capabilities to your workloads.

Auto-scaling

Horizontal Scaling with CPU

traits:
  - type: scaler
    properties:
      replicas: 3
      min: 2
      max: 10
      scaleMetric: cpu
      scaleTarget: 70  # Scale when CPU > 70%

Scaling with Memory

traits:
  - type: scaler
    properties:
      replicas: 2
      min: 1
      max: 5
      scaleMetric: memory
      scaleTarget: 80  # Scale when memory > 80%

HTTP Routing

Basic Ingress

traits:
  - type: ingress
    properties:
      host: api.example.com
      port: 8080
      tls: true

Ingress with Path Prefix

traits:
  - type: ingress
    properties:
      host: example.com
      pathPrefix: /v1
      port: 8080
      tls: true
      stripPrefix: true

Ingress with Middleware

traits:
  - type: ingress
    properties:
      host: api.example.com
      tls: true
      middleware:
        - rate-limit-medium
        - oauth2

Secrets Management

Vault Secrets

traits:
  - type: vault-secret
    properties:
      path: secret/data/database
      changeMode: restart
      env:
        username: DB_USER
        password: DB_PASS

Storage

CSI Volume Mount

traits:
  - type: volume
    properties:
      name: data-storage
      type: csi
      source: my-csi-volume
      mountPath: /data
      readOnly: false

Host Volume Mount

traits:
  - type: volume
    properties:
      name: logs
      type: host
      source: /var/log/myapp
      mountPath: /var/log
      readOnly: true

Deployment Strategies

Rolling Update

traits:
  - type: updatestrategy.nomad.oam.dev
    properties:
      strategy: rolling
      maxParallel: 2
      minHealthyTime: 30s
      healthyDeadline: 5m
      autoRevert: true

Canary Deployment

traits:
  - type: updatestrategy.nomad.oam.dev
    properties:
      strategy: canary
      canary: 1
      maxParallel: 1
      minHealthyTime: 60s
      healthyDeadline: 10m
      autoRevert: true

Node Scheduling

Node Affinity

traits:
  - type: affinity
    properties:
      nodeClass: compute-optimized
      cloud: aws
      region: us-east-1

Spread Across Datacenters

traits:
  - type: affinity
    properties:
      spread: true

GPU Nodes

traits:
  - type: affinity
    properties:
      nodeMeta:
        gpu: "true"
      constraints:
        - attribute: "${attr.nvidia.com/gpu}"
          operator: ">"
          value: "0"

Service Discovery

Basic Service Registration

traits:
  - type: servicediscovery.nomad.oam.dev
    properties:
      serviceName: my-api
      tags:
        - v1
        - production
      port: http

With Health Check

traits:
  - type: servicediscovery.nomad.oam.dev
    properties:
      serviceName: my-api
      tags:
        - v1
      port: http
      check:
        type: http
        path: /health
        interval: 10s
        timeout: 3s

TCP Health Check

traits:
  - type: servicediscovery.nomad.oam.dev
    properties:
      serviceName: redis
      port: redis
      check:
        type: tcp
        interval: 10s
        timeout: 3s

Node Migration

Configure how tasks handle node draining:

traits:
  - type: migration.nomad.oam.dev
    properties:
      maxParallel: 1
      healthCheck: checks
      minHealthyTime: 15s
      healthyDeadline: 5m

Combining Traits

Multiple traits can be combined:

components:
  - name: api
    type: webservice
    properties:
      image: myapp/api:latest
    traits:
      - type: scaler
        properties:
          replicas: 3
      - type: ingress
        properties:
          host: api.example.com
      - type: servicediscovery.nomad.oam.dev
        properties:
          serviceName: api
          check:
            type: http
            path: /health
      - type: vault-secret
        properties:
          path: secret/data/api-keys
          env:
            API_KEY: API_KEY
      - type: volume
        properties:
          name: data
          type: csi
          source: api-storage
          mountPath: /data