Namespaces - IDYL Docs

A Namespace separates related resources inside an account and is the parent of Workspace resources.

When namespaces matter

Need	Workflow
Deploy into a specific environment	Deploy a workload
Create resources from YAML	Use a manifest
Inspect only one environment	Inspect resources

Scope

Direct Workload commands resolve Account and Namespace from the current CLI context unless a command or manifest provides another Namespace. They never require a Workspace. Workspace CRUD is nested below the Namespace:

/v1/accounts/{account}/namespaces/{namespace}/workspaces

Use the command reference for exact command syntax.

Account-wide listing

Every command that lists a Namespace-scoped collection accepts -A/--all-namespaces, which lists across every namespace in the account you can list. Each row and item identifies its namespace, results order by namespace and then name, and totals count the account-wide result. Reading or changing one named resource always addresses one namespace, because the same name may exist in more than one.

idyl get pods -A
idyl workspace ls -A

Lifecycle

A Namespace is in one of two phases. Every Namespace the API serves carries a phase.

Phase	Meaning
`active`	The Namespace is in service. It resolves, and every Namespace-scoped operation is accepted subject to authorization.
`terminating`	A deletion has been accepted and the platform has yet to finalize it. The Namespace still resolves.

Deleting a namespace

Deleting a Namespace is asynchronous. The API accepts the request with HTTP 202 and records the Namespace as terminating. The platform then drains everything the Namespace owns: its Workspaces and every Namespace-scoped resource in every zone. Once nothing remains, the platform finalizes the release. A finalized Namespace resolves 404, and its name is free to reuse. Deleting a Namespace that is already terminating is accepted again with the same result. The reserved default namespace cannot be deleted.

While terminating

Operation	Result
Read the Namespace or any resource in it	Accepted
Delete the Namespace or any resource in it	Accepted
Create a resource in the Namespace	Refused with HTTP 409 and code `NAMESPACE_TERMINATING`
Edit the Namespace or any resource in it	Refused with HTTP 409 and code `NAMESPACE_TERMINATING`

The refusal’s details name the Namespace. Automation should classify the refusal by its code.

Termination detail

While a Namespace is terminating, the API reports terminatingAt, the instant the deletion was recorded, and termination, which describes what still holds finalization back.

Field	Meaning
`workspacesRemaining`	Workspaces in the Namespace that have yet to be finalized.
`zones[].zone`	A zone that must drain the Namespace’s resources and acknowledge.
`zones[].acknowledged`	Whether the zone has reported. A zone that has yet to report holds the Namespace in `terminating`.
`zones[].reportedAt`	The instant of the zone’s latest report.
`zones[].remaining[]`	Resources still live in the zone, as a `kind` and a `count`.

The platform finalizes once no Workspaces remain and every zone has acknowledged and reports nothing remaining.

Observe a deletion

idyl namespace get lists every Namespace with a PHASE column. With a name, it shows the phase and, for a terminating Namespace, what still holds finalization back.

idyl namespace get <namespace>

Output similar to:

Name         staging
ID           019ad9ba-7334-7eca-9958-9f00c6c9f702
Account ID   550000000001
Description  Staging environment
Phase        Terminating
Terminating  3m ago
Created      Jun 1
Updated      Jun 1

Termination
  Workspaces  1 remaining
  zone-a      acknowledged just now · Pod 2, Service 1
  zone-b      unacknowledged
  zone-c      acknowledged just now · drained

Wait for finalization

Pass --wait to idyl namespace delete to block until the Namespace is finalized, and --timeout to bound the wait. After a deletion has been accepted, idyl wait namespace <namespace> --for deleted blocks the same way.

idyl namespace delete <namespace> --yes --wait --timeout 10m
idyl wait namespace <namespace> --for deleted --timeout 10m

Both exit 0 when the Namespace is finalized and 124 when the timeout passes first. While the Namespace is terminating, the wait reports what still holds it back. Deleting a Namespace releases the Workspaces within it. To release one Workspace on its own, see Workspaces.

​When namespaces matter

​Scope

​Account-wide listing

​Lifecycle

​Deleting a namespace

​While terminating

​Termination detail

​Observe a deletion

​Wait for finalization