Kept commands (experiment)
Keep a command running in a Space: restarts, health checks, start on boot and logs.
These calls belong to the Child Spaces experiment (cua experiments enable child-spaces) for adding a service; listing, stopping and removing work either way. See Keep a command running.
Services#
Methods of Space.
Space.put_service#
Keeps a command running in this Space (replacing a service of that name): restarted by its policy when it ends or fails its health check, started when the Space boots, its output kept in a log file.
async def put_service(self, _def: SpaceServiceDef) -> SpaceServiceInfo| Parameter | Type | Default |
|---|---|---|
def | SpaceServiceDef | required |
Returns SpaceServiceInfo · Async · Raises CuaError
Space.kept_services#
This Space's services.
async def kept_services(self) -> List[SpaceServiceInfo]Returns Vec<SpaceServiceInfo> · Async · Raises CuaError
Space.start_service#
Starts a stopped service.
async def start_service(self, name: str) -> SpaceServiceInfo| Parameter | Type | Default |
|---|---|---|
name | String | required |
Returns SpaceServiceInfo · Async · Raises CuaError
Space.stop_service#
Stops a service and keeps it stopped (also across a reboot).
async def stop_service(self, name: str) -> SpaceServiceInfo| Parameter | Type | Default |
|---|---|---|
name | String | required |
Returns SpaceServiceInfo · Async · Raises CuaError
Space.restart_service#
Restarts a service.
async def restart_service(self, name: str) -> SpaceServiceInfo| Parameter | Type | Default |
|---|---|---|
name | String | required |
Returns SpaceServiceInfo · Async · Raises CuaError
Space.delete_service#
Stops a service and forgets it (its logs go too).
async def delete_service(self, name: str) -> None| Parameter | Type | Default |
|---|---|---|
name | String | required |
Async · Raises CuaError
Space.service_logs#
The end of a service's log (tail_bytes None: 64 KiB).
async def service_logs(self, name: str, tail_bytes: Optional[int]) -> str| Parameter | Type | Default |
|---|---|---|
name | String | required |
tail_bytes | Option<u64> | required |
Returns String · Async · Raises CuaError
SpaceServiceDef record#
A command a Space keeps running (Space.put_service).
| Field | Type | Default | Description |
|---|---|---|---|
name | String | Name: lowercase letters, digits, -, _, . (1 to 63). | |
command | String | The shell command line it runs. | |
env | HashMap<String, String> | [:] | Extra environment. |
cwd | Option<String> | None | Working directory. |
restart | Option<String> | None | When it is started again: always (default), on-failure or never. |
probe | Option<SpaceServiceProbe> | None | A health check; failing it restarts the service. |
start_on_boot / startOnBoot | Option<bool> | None | Start it when the Space boots. None: yes. |
SpaceServiceProbe record#
A health check: exactly one of http, tcp, command.
| Field | Type | Default | Description |
|---|---|---|---|
http | Option<String> | None | A URL that answers 2xx or 3xx. |
tcp | Option<String> | None | host:port that accepts a TCP connection. |
command | Option<String> | None | A shell command that exits 0 when healthy. |
interval_secs / intervalSecs | Option<u64> | None | Seconds between checks (default 10). |
failures | Option<u32> | None | Failed checks in a row that restart it (default 3). |
SpaceServiceInfo record#
A service and how it is doing (Space.services).
Returned by Space.kept_services, Space.put_service, Space.restart_service, Space.start_service, Space.stop_service.
| Field | Type | Default | Description |
|---|---|---|---|
name | String | Name. | |
command | String | The command line. | |
state | String | starting, running, unhealthy, backoff, stopped, exited or failed. | |
pid | u32 | Its process, while it runs. | |
restarts | u32 | Starts after the first. | |
last_end / lastEnd | String | How the last process ended, if one did. | |
probe_error / probeError | String | The last failed health check, if the last one failed. | |
restart | String | always, on-failure or never. | |
start_on_boot / startOnBoot | bool | Starts when the Space boots. | |
log_path / logPath | String | Its log file in the Space. |