Workload API Resource

Workloads represent deployed applications in Rancher. The Workload API provides a unified interface to manage Kubernetes workload resources including Deployments, StatefulSets, DaemonSets, CronJobs, and Jobs.

Workload Types

Rancher aggregates multiple Kubernetes workload types into a single Workload resource:

Deployment

Stateless applications with rolling updates

StatefulSet

Stateful applications requiring stable identities

DaemonSet

One pod per node (monitoring, logging agents)

CronJob

Scheduled batch jobs

Workload Resource

From pkg/api/norman/customization/workload/workload.go:48

Workload Spec

name

string

required

Name of the workload

namespaceId

string

required

Namespace where the workload is deployed

workloadType

string

required

Type of workload: deployment, statefulSet, daemonSet, cronJob, job

containers

array<Container>

required

List of containers in the workload

name

string

required

Container name

image

string

required

Container image (e.g., nginx:1.21)

ports

array<ContainerPort>

Exposed container ports

env

array<EnvVar>

Environment variables

resources

ResourceRequirements

Resource requests and limits

volumeMounts

array<VolumeMount>

Volume mount points

scale

integer

Number of replicas (for Deployment, StatefulSet, ReplicaSet)

volumes

array<Volume>

Volumes available to containers

labels

map<string, string>

Labels for the workload

annotations

map<string, string>

Annotations for the workload

scheduling

Scheduling

Pod scheduling configuration

node

NodeScheduling

Node selection criteria

tolerations

array<Toleration>

Tolerations for node taints

paused

boolean

Whether the deployment is paused (Deployment only)

Workload Status

state

string

Current state: active, updating, paused, stopped

replicas

integer

Desired number of replicas

readyReplicas

integer

Number of ready replicas

availableReplicas

integer

Number of available replicas

unavailableReplicas

integer

Number of unavailable replicas

publicEndpoints

array<PublicEndpoint>

Exposed endpoints for the workload

Create Deployment

Deploy a stateless application:

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "workload",
    "name": "nginx-web",
    "namespaceId": "my-namespace",
    "containers": [
      {
        "name": "nginx",
        "image": "nginx:1.21",
        "ports": [
          {
            "containerPort": 80,
            "protocol": "TCP",
            "name": "http"
          }
        ],
        "resources": {
          "requests": {
            "cpu": "100m",
            "memory": "128Mi"
          },
          "limits": {
            "cpu": "500m",
            "memory": "512Mi"
          }
        },
        "env": [
          {
            "name": "NGINX_HOST",
            "value": "example.com"
          }
        ]
      }
    ],
    "scale": 3,
    "labels": {
      "app": "nginx",
      "environment": "production"
    }
  }' \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789/workloads

Create StatefulSet

Deploy a stateful application with persistent storage:

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "workload",
    "name": "postgres-db",
    "workloadType": "statefulSet",
    "namespaceId": "databases",
    "containers": [
      {
        "name": "postgres",
        "image": "postgres:14",
        "ports": [
          {
            "containerPort": 5432,
            "protocol": "TCP"
          }
        ],
        "env": [
          {
            "name": "POSTGRES_PASSWORD",
            "valueFrom": {
              "secretKeyRef": {
                "name": "postgres-secret",
                "key": "password"
              }
            }
          }
        ],
        "volumeMounts": [
          {
            "name": "data",
            "mountPath": "/var/lib/postgresql/data"
          }
        ]
      }
    ],
    "scale": 3,
    "volumeClaimTemplates": [
      {
        "name": "data",
        "spec": {
          "accessModes": ["ReadWriteOnce"],
          "resources": {
            "requests": {
              "storage": "10Gi"
            }
          }
        }
      }
    ]
  }' \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789/workloads

Create DaemonSet

Deploy a pod on every node:

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "workload",
    "name": "log-collector",
    "workloadType": "daemonSet",
    "namespaceId": "monitoring",
    "containers": [
      {
        "name": "fluentd",
        "image": "fluentd:v1.14",
        "volumeMounts": [
          {
            "name": "varlog",
            "mountPath": "/var/log",
            "readOnly": true
          }
        ]
      }
    ],
    "volumes": [
      {
        "name": "varlog",
        "hostPath": {
          "path": "/var/log",
          "type": "Directory"
        }
      }
    ]
  }' \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789/workloads

Create CronJob

Schedule a recurring batch job:

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "workload",
    "name": "backup-job",
    "workloadType": "cronJob",
    "namespaceId": "default",
    "schedule": "0 2 * * *",
    "containers": [
      {
        "name": "backup",
        "image": "backup-tool:latest",
        "command": ["/bin/sh"],
        "args": ["-c", "backup.sh"]
      }
    ]
  }' \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789/workloads

List Workloads

Retrieve all workloads in a project:

curl -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789/workloads

Filter by Namespace

curl -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  "https://rancher-server/v3/projects/c-m-abc123:p-xyz789/workloads?namespaceId=production"

Get Workload

Retrieve a specific workload:

curl -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789/workloads/deployment:my-namespace:nginx-web

Response Example

{
  "id": "deployment:my-namespace:nginx-web",
  "type": "workload",
  "links": {
    "self": "...",
    "update": "...",
    "revisions": "..."
  },
  "name": "nginx-web",
  "state": "active",
  "containers": [...],
  "scale": 3,
  "status": {
    "replicas": 3,
    "readyReplicas": 3,
    "availableReplicas": 3,
    "unavailableReplicas": 0
  },
  "publicEndpoints": [
    {
      "addresses": ["192.168.1.100"],
      "port": 80,
      "protocol": "TCP"
    }
  ]
}

Update Workload

Update workload configuration:

curl -X PUT \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "containers": [
      {
        "name": "nginx",
        "image": "nginx:1.22"
      }
    ]
  }' \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789/workloads/deployment:my-namespace:nginx-web

Scale Workload

Update the scale:

curl -X PUT \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scale": 5
  }' \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789/workloads/deployment:my-namespace:nginx-web

Delete Workload

Delete a workload:

curl -X DELETE \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789/workloads/deployment:my-namespace:nginx-web

Workload Actions

From pkg/api/norman/customization/workload/workload.go:69

Pause Deployment

Pause a deployment to prevent updates:

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789/workloads/deployment:my-namespace:nginx-web?action=pause

Resume Deployment

Resume a paused deployment:

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789/workloads/deployment:my-namespace:nginx-web?action=resume

Redeploy

Force a redeployment of the workload:

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789/workloads/deployment:my-namespace:nginx-web?action=redeploy

Rollback

Rollback to a previous revision:

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "replicaSetId": "replicaset:my-namespace:nginx-web-7d8c9f6b5"
  }' \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789/workloads/deployment:my-namespace:nginx-web?action=rollback

Get Revisions

List deployment revisions:

curl -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789/workloads/deployment:my-namespace:nginx-web/revisions

Resource Requirements

Define CPU and memory for containers:

{
  "resources": {
    "requests": {
      "cpu": "100m",
      "memory": "128Mi"
    },
    "limits": {
      "cpu": "500m",
      "memory": "512Mi"
    }
  }
}

Always set resource requests and limits to ensure proper scheduling and prevent resource exhaustion.

Environment Variables

Static Values

{
  "env": [
    {
      "name": "APP_ENV",
      "value": "production"
    }
  ]
}

From ConfigMap

{
  "env": [
    {
      "name": "CONFIG_VALUE",
      "valueFrom": {
        "configMapKeyRef": {
          "name": "app-config",
          "key": "config.json"
        }
      }
    }
  ]
}

From Secret

{
  "env": [
    {
      "name": "DATABASE_PASSWORD",
      "valueFrom": {
        "secretKeyRef": {
          "name": "db-secret",
          "key": "password"
        }
      }
    }
  ]
}

Scheduling

Node Selection

{
  "scheduling": {
    "node": {
      "nodeSelector": {
        "disktype": "ssd",
        "environment": "production"
      }
    }
  }
}

Tolerations

{
  "scheduling": {
    "tolerations": [
      {
        "key": "dedicated",
        "operator": "Equal",
        "value": "gpu",
        "effect": "NoSchedule"
      }
    ]
  }
}

Affinity Rules

{
  "scheduling": {
    "affinity": {
      "podAffinity": {
        "requiredDuringSchedulingIgnoredDuringExecution": [
          {
            "labelSelector": {
              "matchExpressions": [
                {
                  "key": "app",
                  "operator": "In",
                  "values": ["cache"]
                }
              ]
            },
            "topologyKey": "kubernetes.io/hostname"
          }
        ]
      }
    }
  }
}

Best Practices

Set Resource Limits

Always define resource requests and limits:

Requests ensure proper scheduling
Limits prevent resource hogging
Required for QoS guarantees

Use Health Checks

Configure liveness and readiness probes:

Liveness: Restart unhealthy containers
Readiness: Control traffic routing
Startup: Handle slow-starting applications

Leverage Labels

Use meaningful labels for organization:

app: Application name
version: Application version
component: Application component
environment: Deployment environment

Store Secrets Securely

Never hardcode sensitive data:

Use Kubernetes Secrets
Reference secrets via environment variables
Rotate secrets regularly

Configure Rolling Updates

For Deployments, configure update strategy:

maxSurge: Extra pods during update
maxUnavailable: Pods that can be down
Balance between speed and availability

Monitoring Workloads

Check Workload Status

curl -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789/workloads/deployment:my-namespace:nginx-web

View Pod Logs

curl -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789/pods/my-namespace:nginx-web-7d8c9f6b5-abcde/logs

Execute Commands

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "command": ["/bin/sh", "-c", "ls -la"]
  }' \
  https://rancher-server/v3/projects/c-m-abc123:p-xyz789/pods/my-namespace:nginx-web-7d8c9f6b5-abcde?action=execute

Next Steps

Services

Expose workloads with services

Ingress

Configure external access

Volumes

Attach persistent storage

Monitoring

Monitor application metrics

​Workload Types

Deployment

StatefulSet

DaemonSet

CronJob

​Workload Resource

​Workload Spec

​Workload Status

​Create Deployment

​Create StatefulSet

​Create DaemonSet

​Create CronJob

​List Workloads

​Filter by Namespace

​Get Workload

​Response Example

​Update Workload

​Scale Workload

​Delete Workload

​Workload Actions

​Pause Deployment

​Resume Deployment

​Redeploy

​Rollback

​Get Revisions

​Resource Requirements

​Environment Variables

​Static Values

​From ConfigMap

​From Secret

​Scheduling

​Node Selection

​Tolerations

​Affinity Rules

​Best Practices

​Monitoring Workloads

​Check Workload Status

​View Pod Logs

​Execute Commands

​Next Steps

Services

Ingress

Volumes

Monitoring

Workload Types

Workload Resource

Workload Spec

Workload Status

Create Deployment

Create StatefulSet

Create DaemonSet

Create CronJob

List Workloads

Filter by Namespace

Get Workload

Response Example

Update Workload

Scale Workload

Delete Workload

Workload Actions

Pause Deployment

Resume Deployment

Redeploy

Rollback

Get Revisions

Resource Requirements

Environment Variables

Static Values

From ConfigMap

From Secret

Scheduling

Node Selection

Tolerations

Affinity Rules

Best Practices

Monitoring Workloads

Check Workload Status

View Pod Logs

Execute Commands

Next Steps