Skip to content
Kindgi

client.system_deployments

View as Markdown

client.system_deployments — the systemDeployments operations.

On AsyncKindgi every method is the same, awaited.

client.system_deployments.list()

Section titled “client.system_deployments.list()”
list(
    *,
    endpoint: Literal['missing', 'ready', 'retire'],
    cursor: str | None = None,
    limit: int | None = None,
    timeout: float | None = None,
) -> SystemDeploymentPage
Signature

List deployments that need a pack service, have a ready one, or should lose theirs. GET /v1/system/deployments

Across tenants, oldest activatedAt first. endpoint=missing: deployments that need a pack service. Each serves something a call can still ask for, and no newer deployment into its project serves it: a tool, agent or flow version that's registered or held (a flow or agent version a run can reach pins it, or an unfinished run uses it), a tool deployed without a version, or a pack check a registered guardrail runs in its project (from Kindgi 0.4.0; before, each was the newest into its project with routes for some tool version or pack check, and one whose endpoint an earlier runtime made or last set still needs that too). Each has no endpoint or a cleared one, and nothing about it is closing or suspended. endpoint=ready: deployments whose endpoint is ready and whose pack service stays (no retire reason applies). Both lists say whether each service is warm: keep an instance running. endpoint=retire: deployments with an endpoint whose pack service should go, each with its reason. Name each service packServiceName(tenantId, deploymentId) (@kindgi/api). Takes system:deployments. Each entry carries the tenant's id and nothing else of it.

client.system_deployments.claim_round()

Section titled “client.system_deployments.claim_round()”
claim_round(
    body: ClaimOrchestratorRoundBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> OrchestratorRound
Signature

Claim the orchestrator's round. POST /v1/system/deployments/round

One orchestrator pass at a time, whatever starts them (scheduled runs can overlap): a pass claims the round before it acts, for holdSeconds, and stops on a 409. A claim is never renewed, the claimant's own included: the pass ends within its hold (round/end), or its claim lapses and the next pass takes the round over. Takes system:deployments.

client.system_deployments.end_round()

Section titled “client.system_deployments.end_round()”
end_round(
    body: EndOrchestratorRoundBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> None
Signature

End the orchestrator's round. POST /v1/system/deployments/round/end

Ends the round the pass claimed, so the next pass claims it at once instead of waiting for the hold to lapse. Takes system:deployments.

client.system_deployments.set_endpoint()

Section titled “client.system_deployments.set_endpoint()”
set_endpoint(
    tenant_id: str | UUID,
    deployment_id: str | UUID,
    body: SetPackEndpointBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> DeploymentEndpoint
Signature

Record where a deployment's pack service runs. PUT /v1/system/tenants/{tenantId}/deployments/{deploymentId}/endpoint

Records the endpoint, once every check passes: the URL is https://<host> (endpoint-url-invalid); its host is on the operator's allowlist (endpoint-host-not-allowed); its host names the deployment's own service, packServiceName(tenantId, deploymentId) then - or . (endpoint-name-mismatch); the image is in the tenant's repository (image-not-allowed); the pack service answers /v1/info, with the kindgi-tenant-id header, as this deployment (endpoint-unreachable, endpoint-info-mismatch, with the names of the fields that differed). A refusal is also recorded as the endpoint's problem, which the tenant sees as a code. The deployment's endpoint is then ready. Refused for a closing or suspended tenant, project or pack, so a sweep can't recreate a service another one retired. Takes system:deployments. The same body twice records it once.

client.system_deployments.clear_endpoint()

Section titled “client.system_deployments.clear_endpoint()”
clear_endpoint(
    tenant_id: str | UUID,
    deployment_id: str | UUID,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> DeploymentEndpoint
Signature

Clear a deployment's endpoint. DELETE /v1/system/tenants/{tenantId}/deployments/{deploymentId}/endpoint

Clears the endpoint before its pack service is deleted: the deployment's endpoint is cleared, and calls to its tools fail closed (pack-endpoint-cleared), never going to another deployment. Works for a closing or suspended tenant too: that's how its services are retired. Clearing twice keeps the first time. Takes system:deployments.

client.system_deployments.list_pack_env_changed()

Section titled “client.system_deployments.list_pack_env_changed()”
list_pack_env_changed(
    *,
    cursor: str | None = None,
    limit: int | None = None,
    timeout: float | None = None,
) -> SystemPackEnvPage
Signature

List deployments whose pack service runs on values that changed. GET /v1/system/pack-env

Across tenants: deployments with a ready pack service, whose pack declares an environment, and whose values changed since the revision their service runs (and weren't held back at this revision, but for one held as pack-env-update-failed, listed for an hour after it was first held so it's tried again, and one held for a cause the platform fixes, pack-env-secret-unreadable or pack-env-secrets-unaudited, listed every time with its held, as the revision doesn't move when that's fixed). Read each one's values with GET …/deployments/{deploymentId}/pack-env, give them to the service, and record it with PUT …/pack-env, sending back the appliedRevision it was listed with. Ids, the image and the revision each runs, never a value. Takes system:pack-env.

client.system_deployments.get_pack_env()

Section titled “client.system_deployments.get_pack_env()”
get_pack_env(
    tenant_id: str | UUID,
    deployment_id: str | UUID,
    /,
    *,
    secrets: Literal['values'] | None = None,
    timeout: float | None = None,
) -> SystemPackEnv
Signature

Read the env a deployment's pack service is to be given. GET /v1/system/tenants/{tenantId}/deployments/{deploymentId}/pack-env

For whatever runs the deployment's pack service: where each name its pack declares is set (at the deployment's project, then its org, then the tenant, at the env the server serves), and the values when nothing stands in the way. A name set two ways (pack-env-ambiguous: two of a plain value, a secret and a cloud secret), a required one set nowhere (pack-env-missing), or one set only as a secret whose value wasn't asked for (pack-env-secret-not-yet) is a problem, and then no value is given. With secrets=values, each name set only as a secret is given in secrets, read at the version its revision names; a secret that can't be read for a reason the platform fixes is pack-env-secret-unreadable, and then no value is given. Each name set to a cloud secret is given in cloudSecrets, with its version's resource name, for the pack service's host to read as the pack service's own account. Each value given out is on the audit record, a secret's written before the answer. Refused for a retired deployment (endpoint-retired) and a closing or suspended tenant. On a key of its own, system:pack-env: system:deployments reads no value, and kindgi:system no secret's.

client.system_deployments.record_pack_env()

Section titled “client.system_deployments.record_pack_env()”
record_pack_env(
    tenant_id: str | UUID,
    deployment_id: str | UUID,
    body: RecordPackEnvBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> DeploymentEndpoint
Signature

Record the env revision a deployment's pack service runs. PUT /v1/system/tenants/{tenantId}/deployments/{deploymentId}/pack-env

After giving a ready pack service its values: the revision it now runs. Or, with held, that this revision's values couldn't be given (a required one was removed, say), or were given and its new revision didn't start (pack-env-update-failed): the service keeps what it runs, and the tenant sees the code on the endpoint (packEnvProblem) until a later revision is given. The same code for the same revision keeps the time it was first recorded. Compare-and-set: appliedRevision is the one the service was found running, and another recorded since is pack-env-conflict. A new service's revision goes with its endpoint instead (packEnvRevision). Takes system:pack-env.

client.system_deployments.record_problem()

Section titled “client.system_deployments.record_problem()”
record_problem(
    tenant_id: str | UUID,
    deployment_id: str | UUID,
    body: RecordDeploymentProblemBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> DeploymentEndpoint
Signature

Record why a deployment has no pack service yet. PUT /v1/system/tenants/{tenantId}/deployments/{deploymentId}/endpoint/problem

For whatever creates the pack services: records why a deployment waiting for one has none yet (pending, or cleared and waiting, as after a suspension is lifted), as one of the fixed codes (tenant-not-provisioned, capacity-unavailable, service-start-failed, image-not-allowed, and the endpoint checks'). The tenant sees the code and when, so a deploy waiting for ready can say why at once. Takes system:deployments.

client.system_deployments.set_suspended()

Section titled “client.system_deployments.set_suspended()”
set_suspended(
    tenant_id: str | UUID,
    deployment_id: str | UUID,
    body: SetPackSuspendedBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> PackSuspension
Signature

Suspend a deployment's pack, or restore it. PUT /v1/system/tenants/{tenantId}/deployments/{deploymentId}/suspended

Suspended, the pack's calls fail closed (pack-suspended), never going to an older deployment of the same tool version; its endpoint can't be set again; and it lists to retire as pack-suspended. Restored, it serves again from the endpoint recorded for it; if that endpoint is pending or was cleared meanwhile, it lists as needing a pack service. Nothing is deleted. Refused for a closing tenant; a suspended tenant's pack can still be suspended or restored. Takes system:suspend, which the orchestrator's key doesn't hold; system:deployments is refused.