stella estate placements — Command Guide

Audience: administrators who read the managed-placement count of an Installation. Scope: reading the count, what it includes and leaves out, and the API operations that end a placement or declare one the product does not detect.

Checked against src/Cli/StellaOps.Cli/Commands/EstateCommandGroup.cs and src/ReleaseOrchestrator/__Apps/StellaOps.ReleaseOrchestrator.WebApi/Endpoints/ManagedPlacementEndpoints.cs on 2026-10-29 (SPRINT_20261027_003 PLC-5). Re-run the command tests with pwsh ./tools/scripts/test-targeted-xunit.ps1 -Project src/Cli/__Tests/StellaOps.Cli.Tests/StellaOps.Cli.Tests.csproj -Class '*EstatePlacementsCommandTests' -BuildProjectReferences.

The LICENSE (Additional Use Grant §2) counts Placements: one managed workload in one environment. The rules the product applies, and the limits of what it detects today, are in the Release Orchestrator dossier, Managed placement (licence count).

stella estate placements

stella estate placements [--installation] [--json]

The command reads GET /api/v1/release-orchestrator/estate/placements from the Release Orchestrator. Without --installation it counts the signed-in tenant and requests release:read; with --installation it requests release:read ops.admin. A 403 response is printed with its body, for example installation_scope_requires_ops_admin.

Sample output for one tenant (illustrative values):

$ stella estate placements
Managed placements, tenant acme: 4 total (3 recorded, 2 declared; a pair both recorded and declared counts once)
Counted signals:     applied-scan-result, deployment, scan-of-installed-image
Not counted signals: agent-observed-container, gate-or-promotion, node-change
  gate-or-promotion keeps an already recorded placement active but creates none; declare a workload that is only gated or promoted.
Not the definitive licence total: the product does not count every detection signal yet. Declare the placements it cannot detect (supplementary declarations); the total counts each (environment, workload) pair once.

TENANT  ENVIRONMENT            RECORDED  DECLARED  TOTAL
------  ---------------------  --------  --------  -----
acme    development (env-dev)  1         0         1
acme    gate-only (env-gate)   0         1         1
acme    production (env-prod)  2         1         2

TENANT  ENVIRONMENT  WORKLOAD  SOURCE             SIGNALS                              LAST SIGNAL
------  -----------  --------  -----------------  -----------------------------------  --------------------
acme    development  api       recorded           deployment                           2026-10-29 08:00:00Z
acme    gate-only    batch     declared           -                                    2026-10-29 09:30:00Z
acme    production   api       recorded+declared  deployment, scan-of-installed-image  2026-10-29 10:00:00Z
acme    production   worker    recorded           applied-scan-result, deployment      2026-10-29 11:00:00Z

How to read it:

• Total is the count to compare with the free allowance or the recorded capacity. It is the union of the recorded and the declared placements: a pair in both counts once.
• Recorded placements are detected by the product: a deployment, a scan of an installed digest, or an earlier scan result applied to it. Declared placements are the supplementary declarations an administrator entered.
• SOURCE says whether a placement is recorded, declared or recorded+declared. A declared-only placement has no signals, and its last signal time is the declaration time.
• Counted signals and Not counted signals list the detection signals of the LICENSE that the product reads today and those it does not. While any signal is not counted, the output says the total is not the definitive licence total. The scan signals are counted only while the estate re-evaluation (ReleaseOrchestrator:EstateRetouch) runs. gate-or-promotion is listed as not counted because a gate decision or promotion keeps an already recorded placement active but creates none; the output says so, and a workload that is only gated or promoted is declared.
• Two reads of the same estate print the same output: the response carries no read time.

What is not counted

• Replicas, restarts, redeployments, and new digests, tags or versions of the same workload in the same environment: one workload in one environment is one placement.
• Stella Ops’ own containers, labelled com.stellaops.installation-component=true. A Stella Ops component deployed through a Stella Ops release carries no such label in the deployed estate, so it is counted until it is retired.
• An image or artifact held only in a registry, cache or backup, and a scan of something installed in no environment.
• The placementCount of GET /api/v1/release-orchestrator/estate/chain-completeness, which counts (environment, digest) pairs for evidence custody, not placements.

A workload stays counted after it leaves an environment’s latest deployment, after a rollback, and when observation stops: only an explicit retirement ends a placement.

End or declare a placement

The CLI only reads. The Console offers the three operations: Setup > Usage lists the placements of the signed-in tenant with Retire on a recorded placement, Withdraw on a declared one and a Declare placement action. Each operation needs orch:operate, takes a mandatory reason (at most 2000 characters) and is audited.

Use the environment ids that the read reports. A later deployment, gate decision, scan of the installed digest or applied scan result counts a retired workload again; a workload that stays in an environment’s current deployment is still managed, so deploy a release without it before you retire it. The responses and status codes are in the Release Orchestrator API reference.

Related

• stella entitlement and stella installation: the advisory capacity status that compares this count with the imported entitlement records.
• Installation entitlements runbook.