# Site offering names

Resource Provisioning assigns an unnamed Waldur offering account the username
held by its Party's established `site` binding for the offering's environment.
The shared `OfferingNames` application service serves Kubernetes and Slurm.
The Site Agent continues to create native accounts and report their immutable
identities. Assigning an offering username supplies no native account confirmation.

The Kubernetes pass runs immediately after startup and then every minute.
Its three inputs are independent of the HPC settings:

| Input | Meaning |
| --- | --- |
| `WALDUR_K8S_API_URL` | The enrolled Waldur API root, including `/api/`. |
| `WALDUR_K8S_OFFERING_UUID` | The Cloud offering's opaque provider identity. |
| `WALDUR_K8S_OFFERING_TOKEN` | The dedicated offering-manager credential. |

All three absent disables the pass. Partial configuration, an invalid API URL
or a missing enrolled Party/Project view fails startup. The Kubernetes environment
is fixed to `k8s`. No implementation factory or alternate naming strategy comes
from configuration.

The Cloud offering bootstrap publishes the inputs together in
`pharos/metallo-k8s-offering`. It uses a separate non-staff account with
`OFFERING.MANAGER` on that offering only, an unusable login password and a stable
token. An existing account with unexpected credentials or roles is refused.
The Site Agent retains its own credential. Runtime Metallo receives no
administrator credential. Changed inputs restart only Metallo; unchanged inputs
preserve the token and avoid a restart.

Cloud naming defaults to disabled and keeps the chart's `identity_claim`
policy (#1192). It needs no provider patch or capability. A member whose Waldur
user came from the Themelio identity bridge has no `site_username`, so
`identity_claim` leaves their Cloud account empty; this pass names it. A
distributed environment enables it beside its Site Agent, and delivery sets the
chart's `pharos.siteAgent.offeringNames.enabled`:

```yaml
site_agent:
  enabled: true
  identity_source: metallo
  offering_names: true
```

The chart refuses to render the switch with any other policy, and the bootstrap
refuses an offering whose policy is not `identity_claim`. The bootstrap never
writes the offering's plugin options: changing its username settings makes
Waldur regenerate every account's name, and `service_provider` would generate
empty ones. Existing usernames are preserved.

After activation, the optional Secret remains the runtime input. To retire this
consumer, remove its exact `pharos/metallo-k8s-offering` Secret and restart
Metallo before disabling the bootstrap switch. Revoke the
dedicated offering-manager token through the provider's normal administration
flow once no consumer holds it. A routine sync retains credentials; it never
deletes or rotates them implicitly.

## Retry and refusal

The pass follows the complete paginated offering-user listing. It refuses
repeated identities, foreign offering scope and provider-backed accounts.
The pinned provider schema must explicitly include a null
`service_provider_account_uuid` in both listing and full account details; a
missing field is unavailable evidence. Before writing, it rechecks the Party's Site
binding and the provider account's exact user identity and current name.
The Kubernetes adaptor writes the name with the provider's ordinary
offering-user update, `PATCH /api/marketplace-offering-users/{uuid}/`, then
reads the account back and confirms the exact identity and name. It refuses to
write when the final read shows any name; the same name counts as done.

Waldur's update is not conditional. A different name committed between the
final read and the write would be replaced. That window is accepted for the
initial Icarus rollout: under `identity_claim` the only other automatic writer
is Waldur's own handler, which names the account when the member's
`site_username` arrives through a Waldur sign-in. Conditional naming,
preferably upstream, is #1194. Failed or ambiguous requests, including a lost
response, retry from current provider state on the next pass; a name already
written is then recognised and not written again.

Missing Party or Site bindings leave the account unnamed. An unreadable or
incomplete view remains unavailable. Five-second provider request bounds and
stop checks between pages and users let the worker drain before database disposal.

A nonempty different name is retained. Legacy-name recovery needs
an explicit operator procedure with a provider-local transaction and a controlled
maintenance boundary that prevents native creation and new accepted work while
absence is proved. Routine deployment and naming sweeps perform no such rename.

## Verification

The focused owner tests exercise Kubernetes/Slurm binding selection, interrupted
work, retries, scope and identity changes. The disposable Metallo lane includes
`kubernetes_offering_names.py`: it builds the real owner view from Party/Project
facts, writes through the HTTP adaptor, verifies idempotence and binding retirement,
and checks that native account storage is unchanged.

Bootstrap fixtures cover the dedicated role, token retention, the
`identity_claim` check and refusal of unexpected authority. Render tests check optional inputs, exact network peers
and bootstrap permissions. Live provider bootstrap and native Site confirmation
remain separate deployment qualifications.