Actions And Asynchronous Operations

This page explains the long-running operation model used by the kopernik.us API.

For field-level details, see the Action API reference.

Why actions exist

Many cloud operations are not instantaneous. Creating a machine, provisioning a Kubernetes cluster, or deleting a container app can take seconds or minutes.

Instead of blocking the request until the cloud provider finishes, the API creates an Action record that tracks progress and final outcome.

Which operations return actions

Actions are commonly used for:

machine creation and deletion
block storage creation and deletion
VPC creation and deletion
Kubernetes cluster creation and deletion
container app creation and deletion

Read-only operations such as list and get usually do not create actions.

Response model

For action-producing endpoints:

200 means the action completed within the requested wait window
202 means the action was created successfully but is still running

In both cases the body contains an Action.

This is important:

a successful HTTP response does not always mean the cloud resource operation ultimately succeeded
the source of truth is the returned Action object

Wait time

Many create and delete endpoints accept waitTime.

waitTime tells the API how long to wait before returning:

if the operation completes within that window, the API returns a completed action
if not, the API returns an in-progress action

This lets clients choose between more synchronous and more asynchronous behavior without changing the underlying operation model.

Action states

Common states include:

pending
running
success
failed
rollbackRequested
rollbackSuccess
rollbackFailed

Final states are:

success
failed
rollbackSuccess
rollbackFailed

How clients should use actions

Typical client behavior:

Submit the create or delete request.
Read the returned action UID.
Poll the action endpoint until the state becomes final.
Check statusCode, error, and rollbackError if applicable.

Rollback behavior

Some multi-step operations attempt rollback if a later step fails after partial success. For example, a machine might be created but subsequent setup could fail.

That is why both failed and rollback-related states matter.