# SSH Access process

This Deployment composes [SSH Access](../../../../../services/metallo/contexts/ssh_access/README.md):
canonical Party/Project projections, resource and AUP queries, request handling,
propagation, automatic AUP revocation and browser delivery.

The base has zero replicas until an HPC installation supplies and qualifies its
owner inputs. Its committed `ssh_access` environment policy enables one replica
after the steps below. Development boxes default to disabled too: the HPC page
has no SSH Access consumer until the policy is enabled.
The service fails startup on incomplete configuration; `/readyz` remains
unavailable until its Beto projections match the owner checkpoints.

## Configuration

| Source | Required values |
| --- | --- |
| `ssh-access-settings` ConfigMap | `SSH_ACCESS_SITE`, matching `SITE_API_SITE_ID`, propagation window and login nodes |
| `ssh-access-credentials` Secret | `SSH_ACCESS_DATABASE_URL`, `SSH_ACCESS_REQUESTS_BROKER_URL`, `SSH_ACCESS_VIEWS_BROKER_URL`, `SSH_ACCESS_REALTIME_KEY`, `RESOURCE_PROVISIONING_DATABASE_URL` |
| `metallo-project-source` Secret | The exact enrolled `PROJECT_SOURCE_SCOPE` |
| `hpc-offering-settings` ConfigMap | `WALDUR_HPC_SITE=slurm`, `WALDUR_HPC_OFFERING_UUID` and `WALDUR_HPC_ALLOCATION_LIMITS` |
| `ssh-access-policy` Secret | `SSH_ACCESS_POLICY_KEY`, `SSH_ACCESS_GITLAB_INSTANCE`, private `ca.crt` |

The broker view identity is `pharos_ssh_access_views`. It reads its eight durable
Beto event subscriptions and issues Party/Project queries; its broker permissions
exclude owner commands and other consumers' replies. Resource Provisioning uses
its own restricted database connection through its owner adaptor. No administrator
credentials enter runtime containers.

The authentication administration job extends existing material with a separate
SSH policy key without rotating established credentials. It projects that key to
the retained private policy endpoint and SSH Access. The reader uses
`https://themelio-auth.themelio-compat.svc.cluster.local` with explicit CA trust.
Network policies allow this TLS listener and exclude provider actor listeners.

## Installation and activation

1. Record the deployed revisions and current key roots before changing the
   installation. If it has fixture-owned keys, revoke and confirm their removal
   using the fixture installation first. Canonical integration does not reassign
   those roots or infer a Party from a username.
   Upgrading canonical keys created before access-grant recording also withdraws
   those keys once: their original authority cannot be reconstructed safely.
   Members resubmit them after current checks pass. Deploy both SSH Access and
   Site API with the new image before qualifying these new private snapshots.
2. Apply the bootstrap Secret slot and restricted RBAC for `ssh-access-policy`.
   Deliver the updated authentication administration image and retained web
   image, then run credential reconciliation. The existing API policy reader
   keeps its own key.
3. Qualify the AAI's `site_username` claim for the HPC Site. Set
   `WALDUR_HPC_SITE=slurm` in `hpc-offering-settings`; the authentication
   administration Job uses that setting to add the Site alongside `k8s`.
   Reconciliation preserves existing credentials and restarts Beto when its
   enrolments change. Sign in again so Beto establishes the actual Site binding.
4. Apply SSH Access migrations `0002` and `0003` and Resource Provisioning migration
   `0009`, which stores the numeric POSIX UID separately from LDAP entry identity.
   Deliver the new broker credential,
   run broker administration, and rerun Waldur Project consumer registration so
   Beto enrols `ssh_access` for the exact Project source. Restart Beto after scope
   changes and restart owner processes after configuration changes.
5. Provision the HPC offering through the
   [central setup](../../../../../dx/metallo/icarus-hpc/README.md). Install the
   Site agent plugin from [PR #974](https://github.com/pharos-ai-factory/pharos-platform/pull/974)
   or a release containing it; record the exact revision. Its `site-username` and
   `site-slurm` backends require the offering's `service_provider` username policy
   and report LDAP `entryUUID` values in `backend_metadata.accounts`. The upstream
   agent alone does not supply that identity evidence. Confirm that Metallo sets
   the offering username from Beto's established `site/slurm` binding, its reported
   `uidnumber` matches LDAP, and each reported account identity matches that LDAP
   entry's `entryUUID`. The existing Metallo offering-user reconciliation must be
   running and publishing fresh Resource Provisioning reports. Set
   `WALDUR_HPC_ALLOCATION_LIMITS` in `hpc-offering-settings` through central setup;
   without it, the Waldur allocation poller stays disabled. Confirm a fresh,
   usable allocation for the member's Project and configured offering: account
   reports alone do not establish HPC eligibility.
6. Deliver the canonical Metallo image and enable SSH Access in the committed
   environment policy described below. Confirm `/readyz`, the eight consumer queues and current
   Party/Project checkpoint matches. Confirm the running SSH Access and Site API
   containers have no `SSH_ACCESS_FIXTURE_FILE` environment variable or fixture
   mount. An image being healthy alone does not qualify the member journey.

The runtime Site ID can be `hpc`, while the canonical binding instance and resource
environment are `slurm`; the manifest maps these explicitly. The Site API and SSH
Access runtime Site IDs must match.

### Committed activation policy

For a development box, edit `devops/platform/environments/devbox.yml`. For a
distributed installation, edit its `devops/platform/environments/<environment>.yml`.
The common default is `ssh_access: {enabled: false}`. Once the prerequisites above
are ready, commit the Site's actual login nodes and measured propagation window:

```yaml
ssh_access:
  enabled: true
  login_nodes: [hpc-login.example.org]
  propagation_window_seconds: 120
```

Deliver that revision with the existing `make reconcile TARGET=<target>` dev-box
workflow or `make deploy ENV=<environment>` distributed workflow. Delivery renders
the replica count and Site settings into the Argo Application and enables the
bounded Metallo-to-Waldur access required by the owner queries. Argo retains these
settings on subsequent synchronisation; manual scaling is unnecessary.

Disabling the process stops reconciliation, including removals. Revoke and confirm
removal of its keys before committing `enabled: false` during decommissioning.

## Real member qualification

Use a real test member and a dedicated test key. Record the canonical Party and
Project, Site-binding ID, username, numeric UID, AUP version and tested image
revisions without recording private keys or bearer credentials.

- Sign in and check that only the member's eligible HPC Projects appear.
- Check rejection before current AUP acceptance, then accept through the retained
  member flow and submit the public key.
- Observe `pending_deployment`, the exact LDAP value and Site acknowledgement,
  then `deployed` after the configured propagation window. Test SSH login.
- Revoke the key; confirm LDAP removal, acknowledgement, `revoked` after the
  window, and failed login with that key.
- In an isolated policy qualification environment, require a new AUP version and
  verify automatic revocation for a member who has not accepted it.
- Check membership removal, owner outages, restart/rebuild and a mismatched UID.
  Revocation of existing keys stays available when eligibility disappears.
- Suspend the test Party and confirm LDAP removal and rejected fresh SSH login.
  Reinstate the Party, confirm that the key stays revoked, then explicitly
  resubmit it and check that normal access returns. Also cover suspension followed
  by reinstatement while SSH Access is stopped.
- With a separate disposable account, retire its Site binding for `security`.
  Confirm removal from the original LDAP account. This retirement is permanent;
  reinstating the Party must not restore the association.

Record disposable fixture results, deployed configuration and the real member
journey separately. The base's zero-replica gate can be removed once HPC owner
configuration and this journey are part of the installation's normal qualification.

The retained `ssh-access-fixture` ConfigMap supports explicit development tests,
including `pnpm test:integration --group images-browser`. `make ssh-access-seed`
only updates that data and reports that canonical deployments ignore it.
Installed deployments do not mount the fixture; the seed command cannot activate
canonical access.