Harthelm Docs
REST APILandscape

Scale a service

Sets the replicas of a `steps` or `container` service without a Sync: at least 1, at most the service's `max_replicas` (its `maxReplicas`, else the plan's), else 422 with pointer `/replicas`; a `forward` or `managed` service is 422 too. A sleeping service keeps sleeping and wakes with the new count; a stopped or torn-down landscape is 409 `landscape-not-synced`. The next Sync keeps the scaled count unless the file's `replicas` changed since the last Sync (then the file wins). The team quota applies as for a Sync (409 `quota-exceeded`). Needs `landscape.manage`; audited as `landscape.scale`; publishes `landscape.updated`.

Generated from openapi/harthelm.yaml at v1.5.0
PATCH
/workspaces/{ws}/landscape/services/{svc}

Authorization

cookie__Host-harthelm_session<token>

Browser session of the UI (12 h idle, 7 days absolute). State-changing requests also need the header Harthelm-CSRF: 1 and a matching Origin.

Path Parameters

ws*integer

Numeric resource id.

Formatint64
Range1 <= value
svc*string

A service of the synced landscape.

Match^[a-z]([-a-z0-9]{0,30}[a-z0-9])?$

Request Body

application/json
  1. body
replicas*integer
Range1 <= value <= 100

Response Body

The service.

application/json
  1. response
name*ServiceNameValue
Match^[a-z]([-a-z0-9]{0,30}[a-z0-9])?$
type*ServiceType

The service's type in harthelm.yml; steps, container, forward or managed.

Value in"steps""container""managed""forward"
plan?string

Service plan id (steps and container services).

replicas*integer

What the spec asks for.

Range1 <= value
desired_replicas*integer

What runs; 0 after a teardown and while asleep.

Range0 <= value
ready_replicas*integer
Range0 <= value
availability?Availability
Value in"always""on-demand"
run_state*RunState

started: the steps run, also after a pod restart or a wake; stopped: the pods stay, the steps do not run.

Value in"stopped""started"
status*ServiceStatus
  • pending: no replica is scheduled yet; starting: replicas start or run their first steps;
  • running: the last step runs and the health check passes (internal instead for a service without routes or public ports);
  • finished: the last step exited 0 ("run finished"), or a container's process exited 0; failure: a step failed, or the last step (a container's process) failed 5 times in 2 minutes. Both come from the agent's stage result (run_result), not from the pod;
  • stopped: the run switch is off.
Value in"pending""starting""running""finished""failure""stopped""internal"
status_detail?string
ports*array<>
health?
max_replicas?integer

The most replicas PATCH …/services/{svc} accepts (maxReplicas, else the plan's); steps and container services.

Range1 <= value
image?string

The image as harthelm.yml names it (container services, and steps services with a base image of their own).

image_ref?string

Container services, the image as the last Sync resolved it, <repository>@sha256:<digest>; what the pods run.

run_as_user?integer

Container services with runAsUser (teams a cluster admin allowed); absent, the workspace's UID.

Formatint64
Range0 <= value
autonomous?boolean

The service runs without the run stage (container services): its process starts with its pods and stops with the service's switch; Run and Stop of the landscape leave it alone.

target?string

Forward services, the resolved target URL.

routes?array<>

Forward services, the paths of the dev domain that go to target.

run_result?

The last stage result an agent reported for the service: the end of its run steps (steps), or of its process (container). status is failure or finished from it while generation is the service's current run generation.

upgrade_pending?boolean

The service's pods run a template from before an upgrade until it sleeps or is synced again.

managed_service_id?string

Managed services, the instance the Sync created (GET /managed-services/{ms}).

Formatuuid
managed_status?ManagedServiceStatus
  • creating, updating, pausing, unpausing, deleting: the backend works on a change;
  • synchronized: it runs as asked; paused: data kept, no server (a torn-down landscape's database);
  • deleted: a tombstone, listed with include_deleted until it is purged;
  • unknown: the backend does not answer or does not report it; the details are the last known ones;
  • invalid-provider: its provider version is gone or no longer accepts its settings.
Value in"creating""updating""synchronized""pausing""paused""unpausing""deleting""deleted""unknown""invalid-provider"
needs?array<>

The services it needs as harthelm.yml lists them, in name order; waking it wakes them, and Run starts them first. Absent when it needs none and from an older core.

failing?boolean

0.10.1: the service fails for the services that need it, as failing_needs says it: its run failed, it has no ready replica a minute after its wake, or a Run began while it failed and has not brought up a ready replica yet. A service that needs it neither waits for it at a wake nor at a Run, and shows "needs …, which is failing". Computed when read; absent when false and from an older core.

curl -X PATCH 'https://console.example.com/api/v1/workspaces/1/landscape/services/string' \  -H 'Content-Type: application/json' \  -d '{  "replicas": 1}'
{  "name": "string",  "type": "steps",  "plan": "string",  "replicas": 1,  "desired_replicas": 0,  "ready_replicas": 0,  "availability": "always",  "run_state": "stopped",  "status": "pending",  "status_detail": "string",  "ports": [    {      "port": 1,      "public": true,      "url": "string",      "routes": [        {          "path": "string",          "strip": true        }      ]    }  ],  "health": {    "port": 0,    "path": "string",    "mode": "any-http"  },  "max_replicas": 1,  "image": "string",  "image_ref": "string",  "run_as_user": 0,  "autonomous": true,  "target": "string",  "routes": [    {      "path": "string",      "strip": true    }  ],  "run_result": {    "result": "success",    "generation": 0,    "message": "string",    "at": "2019-08-24T14:15:22Z"  },  "upgrade_pending": true,  "managed_service_id": "77427583-c503-4b42-8d68-8e0a3b2c8384",  "managed_status": "creating",  "needs": [    "string"  ],  "failing": true}

Restart one service's steps

Stop plus start; the pods keep running. Needs `landscape.manage`; 409 `managed-service-bound` for a `managed` service.

Switch the landscape's profile

Selects the profile Plan and Sync use from now on when a request names none. Nothing is redeployed: while the landscape is synced from another profile, `Landscape.selected_profile` differs from `profile` and the console asks for a Sync ("requires a Sync"). The file need not exist yet (the Plan says so). Needs `landscape.manage`; audited as `landscape.profile_select`.