Harthelm Docs
REST APILandscape

Plan a Sync

Reads `harthelm.yml` (or `harthelm.<profile>.yml`) from `/data/app` through the IDE agent, parses, validates and resolves it and compares it with the synced landscape. Changes nothing. The result lists the services to add, change or remove with replicas, CPU and RAM, the team quota share, the vault keys that have no value yet and blockers that would stop the Sync (a service type that is not supported yet, the team quota, the workspace's disk quota). An invalid file answers 422 with problem `invalid-config`, whose `errors` carry pointer, line and column. Needs `landscape.manage`; 409 when the IDE does not run.

Generated from openapi/harthelm.yaml at v1.5.0
POST
/workspaces/{ws}/landscape/plan

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

Request Body

application/json
  1. body
profile?ProfileName

A profile (harthelm.<profile>.yml); absent or empty for harthelm.yml.

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

Response Body

The plan; send its spec_hash as If-Match to Sync.

application/json
  1. response
profile?ProfileName

A profile (harthelm.<profile>.yml); absent or empty for harthelm.yml.

Match^([a-z0-9]([-a-z0-9]{0,30}[a-z0-9])?)?$
file*
spec_hash*string

Hash of the resolved spec; send it as If-Match (quoted) to Sync.

base_spec_hash?string

The landscape's current spec_hash; absent while it is empty.

services*array<>
totals?

CPU and memory limits of all replicas, before and after.

quota?

The team quota (requests) with this landscape before and after the Sync.

disk?

The workspace's soft disk quota.

secrets*array<string>

Every vault key the services reference.

missing_secrets*array<string>

The referenced keys without a value; the UI asks for them before the Sync.

blockers*array<>
warnings?array<>

Things the Sync will do that do not stop it; absent from an older core.

curl -X POST 'https://console.example.com/api/v1/workspaces/1/landscape/plan' \  -H 'Content-Type: application/json' \  -d '{}'
{  "profile": "string",  "file": {    "path": "string",    "sha256": "string",    "commit": "string"  },  "spec_hash": "string",  "base_spec_hash": "string",  "services": [    {      "name": "string",      "type": "steps",      "change": "add",      "from": {        "plan": "string",        "replicas": 0,        "cpu_millis": 0,        "memory_mib": 0      },      "to": {        "plan": "string",        "replicas": 0,        "cpu_millis": 0,        "memory_mib": 0      },      "fields": [        "string"      ],      "restart": true    }  ],  "totals": {    "from": {      "cpu_millis": 0,      "memory_mib": 0    },    "to": {      "cpu_millis": 0,      "memory_mib": 0    }  },  "quota": {    "limit": {      "cpu_millis": 0,      "memory_mib": 0    },    "used": {      "cpu_millis": 0,      "memory_mib": 0    },    "after": {      "cpu_millis": 0,      "memory_mib": 0    },    "fits": true  },  "disk": {    "used_bytes": 0,    "limit_bytes": 0,    "scanned_at": "2019-08-24T14:15:22Z"  },  "secrets": [    "string"  ],  "missing_secrets": [    "string"  ],  "blockers": [    {      "code": "unsupported-service-type",      "message": "string",      "pointer": "string",      "line": 1,      "column": 1    }  ],  "warnings": [    {      "code": "image-user-ignored",      "message": "string",      "pointer": "string",      "line": 1,      "column": 1    }  ]}

List the profiles

The profiles whose files exist in `/data/app`, the default (`""`, `harthelm.yml`) first, then by name; read through the IDE agent. `selected_profile` is what Plan and Sync use when the request names none, `synced_profile` what the landscape was last synced from. 409 without an IDE pod. Needs `workspace.view`.

Restart one service's steps

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