Workload Placement

This topic describes APIs used to create, get, update, and delete a Workload Placement.

Create Workload Placement

Use this API to create a Workload Placement.

Method and URL

POST /api/v1/workload-placement

Parameters

Parameter	Parameter Type	Description	Required
WorkspaceName	String	The workspace under which the workload is deployed.	Mandatory
name	String	The unique name of the workload placement. This is used as the identifier.	Mandatory
clusters	array[string]	The list of cluster names where the workload is deployed.	Mandatory
burstDuration	String	The time duration for temporary scaling or burst activity (for example, 15m).	Mandatory
deletionPolicy	String	This defines what happens on delete (Delete or Retain).	Mandatory
helmConfigs	array[object]	The list of Helm deployments included in the workload.	Mandatory
manifestResources	array[object]	The list of Kubernetes manifests to apply (for example, ConfigMaps and Deployments).	Mandatory
cmdExec	array[object]	The list of shell/command executions to run (for example, kubectl commands).	Mandatory
steps	array[object]	The ordered execution steps defining workload sequence (command, helm, manifest, etc.).	Mandatory

Helm Configuration Parameters

Parameter	Parameter Type	Description	Required
chart	String	The Helm chart identifier (repo/chart-name).	Mandatory
releaseName	String	The Helm release name.	Mandatory
releaseNamespace	String	The target namespace for Helm release.	Mandatory
repoName	String	The Helm repository name.	Mandatory
repoURL	String	The URL to the Helm chart repository.	Mandatory
SecretRef	String	The secret reference for Helm repository authentication.	Optional
values	Object	The key-value map of Helm chart values.	Optional

Manifest Resources Parameters

Parameter	Parameter Type	Description	Required
name	String	The logical name for the manifest.
namespace	String	The namespace where the manifest applies.
apiVersion	String	The API version of the Kubernetes resource (for example, v1).
kind	String	The Kubernetes resource kind (for example, ConfigMap and Deployment).
data	Object	The resource content or data fields.

Command Execution Parameters

Parameter	Parameter Type	Description	Required
name	String	The name or label for the command step.	Mandatory
cmd	String	The command line to execute (for example, kubectl get pods -n bookinfo).	Mandatory

Steps Configuration Parameters

Parameter	Parameter Type	Description	Required
name	String	The step name referencing a Helm config, manifest, or command.	Mandatory
type	String	The step type for deployment. The values are helm, manifest, or command.	Mandatory

Example Request

{
  "workspaceName": "abc",
  "name": "bookinfo-workload-template-worker-4-0",
  "clusters": ["worker-1"],
  "burstDuration": "15m",
  "deletionPolicy": "Delete",
  "helmConfigs": [
    {
      "chart": "vaidio/cuda",
      "releaseName": "cuda",
      "releaseNamespace": "bookinfo",
      "repoName": "vaidio",
      "repoURL": "https://smartscaler.nexus.aveshalabs.io/repository/vaidio/",
      "secretRef": "vaidio-secret",
      "values": { "replicaCount": 2 }
    }
  ],
  "manifestResources": [
    {
      "name": "sample-configmap",
      "namespace": "bookinfo",
      "apiVersion": "v1",
      "kind": "ConfigMap",
      "data": {
        "database.properties": "host=localhost\nport=5432\ndatabase=myapp",
        "ui.properties": "color=purple\ntheme=dark\nlanguage=en"
      }
    }
  ],
  "cmdExec": [
    { "name": "create-namespace", "cmd": "kubectl get pods -n bookinfo" }
  ],
  "steps": [
    { "name": "create-namespace", "type": "command" },
    { "name": "cuda", "type": "helm" },
    { "name": "sample-configmap", "type": "manifest" }
  ]
}

Example Responses

Example Request: Success

{
    "statusCode": 200,
    "status": "OK",
    "message": "Success",
    "data": {
        "name": "bookinfo-workload-template-worker-4-0"
    }
}

Example Request: Bad Request

{
    "statusCode": 409,
    "status": "Error",
    "message": "Already Exists",
    "data": null,
    "error": {
        "errorKey": "",
        "message": "Already Exists",
        "data": "{\"error\":{\"Message\":\"Error registering WorkloadPlacement\",\"Status\":409,\"DetailedError\":{\"Errormessage\":\"workloadplacements.worker.kubeslice.io \\\"bookinfo-workload-template-worker-4-0\\\" already exists\",\"Reason\":\"AlreadyExists\",\"Details\":\"\"},\"StatusCode\":409,\"ReferenceDocumentation\":\"https://docs.avesha.io/documentation/enterprise-egs\"}}"
    }
}

List Workload Placements

Use this API to list all the Workload Placements.

Method and URL

GET /api/v1/workload-placement

Example Request

GET /api/v1/workload-placement

Example Responses

Example Request: Success

{
    "statusCode": 200,
    "status": "OK",
    "message": "Success",
    "data": [
        {
            "name": "bookinfo-workload-template-worker-4-0
            "workspaceName": "abc",
            "clusters": ["worker-1"],
            "burstDuration": "15m",
            "deletionPolicy": "Delete",
            "helmConfigs": [
                {
                    "chart": "vaidio/cuda",
                    "releaseName": "cuda",
                    "releaseNamespace": "bookinfo",
                    "repoName": "vaidio",
                    "repoURL": "https://smartscaler.nexus.aveshalabs.io/repository/vaidio/",
                    "values": { "replicaCount": 2 }
                }
            ],
            "manifestResources": [
                {
                    "name": "sample-configmap",
                    "namespace": "bookinfo",
                    "apiVersion": "v1",
                    "kind": "ConfigMap"
                }
            ],
            "cmdExec": [
                { "name": "create-namespace", "cmd": "kubectl get pods -n bookinfo" }
            ],
            "steps": [
                { "name": "create-namespace", "type": "command" },
                { "name": "cuda", "type": "helm" },
                { "name": "sample-configmap", "type": "manifest" }
            ],
            "status": {
                "provisioningStatus": "Successful",
                "phase": "Running",
                "message": "Workload successfully deployed",
                "conditions": [
                    {
                        "type": "HelmInstallComplete",
                        "status": "True",
                        "lastTransitionTime": "2025-10-30T09:00:32Z",
                        "reason": "HelmInstallSucceeded",
                        "message": "Helm release cuda installed successfully"
                    }
                ],
                "lastUpdated": "2025-10-30T09:05:00Z"
            },
            "createdAt": "2025-10-30T08:39:52Z"
        }
    ]
}

Example Request: Error

{
    "statusCode": 500,
    "status": "Error",
    "message": "Internal Server Error",
    "data": null,
    "error": {
        "errorKey": "",
        "message": "Failed to fetch workload placements",
        "data": "{\"error\":{\"Message\":\"Error retrieving workload placements\",\"Status\":500,\"DetailedError\":{\"Errormessage\":\"kubernetes API timeout\",\"Reason\":\"InternalError\",\"Details\":\"\"},\"StatusCode\":500,\"ReferenceDocumentation\":\"https://docs.avesha.io/documentation/enterprise-egs\"}}"
    }
}

Get Workload Placement

Use this API to get the Workload Placement by name.

Method and URL

GET /api/v1/workload-placement/{name} 

Example Request

GET /api/v1/workload-placement/bookinfo-workload-template-worker-4-0

Example Responses

Example Response: Success

{
    "statusCode": 200,
    "status": "OK",
    "message": "Success",
    "data": {
        "name": "bookinfo-workload-template-worker-4-0",
        "workspaceName": "abc",
        "clusters": ["worker-1"],
        "burstDuration": "15m",
        "deletionPolicy": "Delete",
        "helmConfigs": [
            {
                "chart": "vaidio/cuda",
                "releaseName": "cuda",
                "releaseNamespace": "bookinfo",
                "repoName": "vaidio",
                "repoURL": "https://smartscaler.nexus.aveshalabs.io/repository/vaidio/",
                "values": { "replicaCount": 2 }
            }
        ],
        "manifestResources": [
            {
                "name": "sample-configmap",
                "namespace": "bookinfo",
                "apiVersion": "v1",
                "kind": "ConfigMap",
                "data": {
                    "database.properties": "host=localhost\nport=5432\ndatabase=myapp"
                }
            }
        ],
        "cmdExec": [
            { "name": "create-namespace", "cmd": "kubectl get pods -n bookinfo" }
        ],
        "steps": [
            { "name": "create-namespace", "type": "command" },
            { "name": "cuda", "type": "helm" },
            { "name": "sample-configmap", "type": "manifest" }
        ],
        "status": {
            "provisioningStatus": "Successful",
            "phase": "Failed",
            "message": "Validation failed: step cuda references helm config cuda that doesn't exist",
            "conditions": [
                {
                    "type": "ValidationError",
                    "status": "True",
                    "reason": "InvalidHelmReference",
                    "message": "step cuda references helm config cuda that doesn't exist",
                    "lastTransitionTime": "2025-10-30T08:45:00Z"
                }
            ],
            "lastUpdated": "2025-10-30T08:45:10Z"
        },
        "createdAt": "2025-10-30T08:39:52Z",
        "updatedAt": "2025-10-30T08:45:10Z"
    }
}

Example Response: Error

{
    "statusCode": 404,
    "status": "Error",
    "message": "Not Found",
    "data": null,
    "error": {
        "errorKey": "",
        "message": "Workload Placement not found",
        "data": "{\"error\":{\"Message\":\"WorkloadPlacement with name 'bookinfo-workload-template-worker-4-0' not found\",\"Status\":404,\"DetailedError\":{\"Errormessage\":\"resource not found\",\"Reason\":\"NotFound\",\"Details\":\"\"},\"StatusCode\":404,\"ReferenceDocumentation\":\"https://docs.avesha.io/documentation/enterprise-egs\"}}"
    }
}

Update Workload Placement

Use this API to update the Workload Placement.

Method and URL

PUT /api/v1/workload-placement/{name}

Change {name} to the actual name of the workload placement you want to update. Workload placement name (from path), must match existing CR.

Update Rules

Condition	Editable Fields	Description
When status.provisioningStatus is Pending or Queued	All fields except workspaceName and name	The workload is not yet provisioned, so full reconfiguration is allowed.
When status.provisioningStatus is Successful	Only burstDuration and deletionPolicy	The workload is being processed or partially deployed, only limited updates are allowed.
When status.provisioningStatus is Completed	No fields editable	After provisioning is successful, the CR becomes immutable.

Example Request

You can edit the Workload Placement if the GPR provisioning request is still in the pending or queued state.

Request Body Example (Allowed full update – Pending/Queued)

{
    "namespace": "kubeslice-avesha",
    "clusters": ["worker-1", "worker-2"],
    "burstDuration": "20m",
    "deletionPolicy": "Delete",
    "helmConfigs": [
        {
            "chart": "vaidio/cuda",
            "releaseName": "cuda",
            "releaseNamespace": "bookinfo",
            "repoName": "vaidio",
            "repoURL": "https://smartscaler.nexus.aveshalabs.io/repository/vaidio/",
            "values": { "replicaCount": 3 }
        }
    ],
    "manifestResources": [
        {
            "name": "sample-configmap",
            "namespace": "bookinfo",
            "apiVersion": "v1",
            "kind": "ConfigMap",
            "data": {
                "database.properties": "host=localhost\nport=5432\ndatabase=myapp"
            }
        }
    ],
    "cmdExec": [
        { "name": "create-namespace", "cmd": "kubectl get pods -n bookinfo" }
    ],
    "steps": [
        { "name": "create-namespace", "type": "command" },
        { "name": "cuda", "type": "helm" },
        { "name": "sample-configmap", "type": "manifest" }
    ]
}

Request Body Example (Limited update – Active but not successful)

{
    "burstDuration": "30m",
    "deletionPolicy": "Retain"
}

Example Responses

Example Response: Success

{
    "statusCode": 200,
    "status": "OK",
    "message": "Workload Placement updated successfully",
    "data": {
        "name": "bookinfo-workload-template-worker-4-0",
    }
}

Example Responses: Error

{
    "statusCode": 409,
    "status": "Error",
    "message": "Field update not allowed",
    "data": null,
    "error": {
        "errorKey": "InvalidUpdate",
        "message": "Cannot update workspaceName or name when provisioningStatus is InProgress",
        "data": "{\"error\":{\"Message\":\"Invalid field update\",\"Status\":409,\"DetailedError\":{\"Errormessage\":\"workspaceName and name are immutable fields\",\"Reason\":\"Conflict\",\"Details\":\"Modification restricted\"},\"StatusCode\":409,\"ReferenceDocumentation\":\"https://docs.avesha.io/documentation/enterprise-egs\"}}"
    }
}

Delete Workload Placement

Use this API to delete a Workload Placement.

Method and URL

DELETE /api/v1/workload-placement/{name}

Change {name} to the actual name of the workload placement you want to delete.

Deletion Rules

Condition	Editable Parameters	Description
When status.provisioningStatus is NOT one of (Successful, Completed, Failed)	Deletion Allowed	Workload is still provisioning or pending — safe to delete.
When status.provisioningStatus is Successful, Completed, or Failed	Deletion Unallowed	Workload lifecycle finished — deletion not allowed.

Example Requests

DELETE /api/v1/workload-placement/bookinfo-workload-template-worker-4-0

Example Responses

Example Responses: Success

{
    "statusCode": 200,
    "status": "OK",
    "message": "Workload Placement deleted successfully",
    "data": {
        "name": "bookinfo-workload-template-worker-4-0"
    }
}

Example Response: Error

{
    "statusCode": 409,
    "status": "Error",
    "message": "Deletion not permitted for completed workload",
    "data": null,
    "error": {
        "errorKey": "DeletionRestricted",
        "message": "Cannot delete workload placement when phase is Successful, Completed, or Failed",
        "data": "{\"error\":{\"Message\":\"Deletion restricted\",\"Status\":409,\"DetailedError\":{\"Errormessage\":\"WorkloadPlacement cannot be deleted after completion\",\"Reason\":\"Conflict\",\"Details\":\"Deletion blocked by status phase\"},\"StatusCode\":409,\"ReferenceDocumentation\":\"https://docs.avesha.io/documentation/enterprise-egs\"}}"
    }
}