Pools

Pools. A pool is the set of computers that runs your work, and you choose the pool for each job. On a hosted pool, TALOS Defence operates the computers in AWS Sydney, and you pay from prepaid credit. On a customer-controlled pool, the computers are in your own AWS account, and you pay for a licence and support, and you pay AWS for the instances.

1. The pool object

GET /v1/pools lists the pools your organisation can see, and GET /v1/pools/{id} gives one, by id or by name.

Every certificate and every return shows the identity of the pool. A reader of a return sees where the job executed and under which jurisdiction, without asking Hangar.

2. The hosted pools

TALOS Defence Pty Ltd, which is 100% Australian-owned and controlled, operates both pools in AWS Asia Pacific (Sydney). The published key set of TALOS Defence signs the returns and certificates of both pools. You can verify them offline.

3. The customer-controlled form

The customer-controlled form runs the same releases inside the customer's own environment: the same package, release object, envelope and return, on capacity that the customer owns. TALOS Defence offers this form from 2027. Pool registration, licences, the local records contract and the offline bundles in this section are part of the Hangar control plane now. The runtime in the customer's environment is hangar-api --profile customer. The customer runtime explains how the runtime starts, checks the licence, imports releases and signs returns.

3.1 What the customer controls

3.2 Key custody

TALOS Defence keeps two keys for this form, and only two. The release signing key signs runtime releases and package acceptances. The entitlement key signs licences. The customer holds every other key: the root that signs the records, trees and returns of the customer, the day keys under the root, and the keys that protect the data of the customer. The device identity of each instance comes from the hardware of the instance.

The owner decides what runs, and TALOS Defence keeps only the proof of what TALOS Defence shipped and licensed. A return from a customer-controlled pool shows the organisation of the customer as the issuer. The keys of the customer sign the return. Anyone can verify the return offline against the published key set of the customer and the published release key set of TALOS Defence.

PUT /v1/pools/{id}/keyset records the key set of the customer for a registered pool. Hangar accepts a key set that its own root signs and that names the organisation of the customer as the issuer. Hangar refuses these key sets with keyset_issuer_refused: the record key set of TALOS Defence, and any set that shares a root with the record, release or entitlement key sets of TALOS Defence. After a pool has a key set, Hangar accepts a new key set only as a rotation: a root of the old set must sign the new set. Otherwise Hangar answers keyset_invalid.

3.3 Who operates what

The contract takes one of three forms. In every form, the keys and the data stay with the customer.

3.4 Registering a pool and its licence

hangar pool register --name harbour-aws --aws-account 123456789012
hangar pool licence harbour-aws

An owner registers a customer-controlled pool with POST /v1/pools. The request gives the name, the provider aws, the 12-digit AWS account id, the region ap-southeast-2, the platforms and, optionally, the revocation policy. The pool is registered until TALOS Defence issues the licence and the customer records the key set.

The licence is an entitlement file of the format hangar-entitlement-v1. The file is canonical CBOR, signed by the entitlement key of TALOS Defence. The licence lists:

• the customer organisation;
• the permitted deployments, as AWS account ids;
• the supported capability: the installation profiles, the number of packages and the number of tenants;
• the support level, standard or extended;
• the update channel;
• the term.

The price of the licence depends on organisational scale, permitted deployments, supported capability and lifecycle commitments. GET /v1/pools/{id}/licence gives the fields of the licence. GET /v1/pools/{id}/licence/file gives the signed file.

The local runtime checks the licence offline, at start and once a day. The runtime reports nothing to TALOS Defence. No usage record leaves the customer's account for licensing, and a renewal is a new file. A licence lists its deployments, so the runtime refuses at start a licence for another account. A changed byte fails the signature.

When the term ends, the runtime keeps running the releases that are installed, shows the lapse on every return, and takes no new release import. After a further 90 days of grace, the runtime takes no new tenant.

3.5 The local records contract

A customer-controlled pool keeps the records, tree heads and returns of the pool in the customer's account. The customer chooses what to share. POST /v1/pools/{id}/returns imports one return that the customer's runtime signed. Hangar can then list the return beside hosted returns. Hangar verifies the return against the key set of the pool and the release key set of TALOS Defence, and stores the return with the verifier report. If the return does not verify, Hangar refuses the import with return_import_invalid. The import contains only the return.

Every return from a customer-controlled pool shows the licence of the runtime and the age of the revocation list that the runtime used. The verifier requires both. The import judges both against the licence of the pool that was in force when the last attempt of the job started, and against the revocation policy of the pool. The newest licence whose term had begun is the licence in force. The licence state must be the state that the term gives: valid, or lapsed, before or after the grace. The age of the list must meet the revocation policy of the pool. The import also refuses a return in three cases: the pool identity on the return is not the full identity of the pool; the last attempt starts after the return was issued; or the release was revoked before the list that the return says the runtime held. The import answer and the kept record show both results. A pool with no issued licence imports nothing (licence_not_found).

A vendor usually supplies the release that a customer-controlled pool runs. Hangar serves the release bundle (Section 3.6) to the vendor, and to an organisation that holds an issued licence for a customer-controlled pool. The release must be accepted and not revoked.

3.6 The release bundle and the site snapshot

A disconnected pool needs two documents. Each item in the two documents verifies offline on its own.

The vendor ships the image layers, as an OCI layout on the customer's media. The runtime checks every layer against the digests in the signed release.

3.7 The disconnected operating policy

With no outside connection, everything in the customer profile works: jobs, the compile, returns, approvals and the local log. Each imported item allows one more thing:

The revocation policy sets the maximum age of the list, from 1 to 365 days (30 by default). It also sets what happens after that age:

• record: jobs continue, and each return shows the age of the list;
• refuse: new jobs are refused with revocation_list_stale until a fresh list is imported.

Time comes from the time source of the customer. Each return shows the error bound of the clock, measured against the time source. The gateway connects to the destinations that the network of the customer connects to, and refuses every other destination.

3.8 Updates and rollback

A runtime update installs only when the customer accepts the update:

1. The customer imports a signed runtime release, from the channel that the licence lists or as an offline bundle.
2. The local control plane installs the new release beside the running release.
3. The control plane runs the conformance suite that ships with the release, and the acceptance jobs of the customer. The acceptance jobs are a list that the customer keeps of package jobs with their expected output checks.
4. A named person in the customer's organisation approves.
5. The control plane switches.

Every step is a record. A failed check stops the update and leaves the running release in place. A rollback returns to the previous release within the rollback window. The database migrations of each release are additive for one release, so the previous release still works on the new schema. Package releases follow the same path. The customer imports a release that TALOS Defence accepted and approves the release locally. The widening rule (Releases and jobs, Section 5) applies, and the customer is the approver.

3.9 The diagnostics export

When the customer wants support, the customer exports a diagnostics bundle. The customer previews every field before export. The customer signs the bundle with the day key of the customer and sends the bundle through the customer's own channel. The bundle contains:

• the versions and digests of every installed artefact;
• the configuration key names, with a digest of each value in place of the value;
• health, and the operating metrics;
• error codes, with their counts;
• attempt and switchover timings;
• record counts by kind;
• tenant ids, each replaced by a keyed hash;
• the redacted operational log.

3.10 Support boundaries

Support works from diagnostics exports and descriptions. It never asks for payloads, secrets or screen sharing.

3.11 The runtime release

The release root of TALOS Defence signs each runtime release. The manifest of the runtime release has the format hangar-runtime-release-v1 and lists:

The installation verifier reads the deployed account through the read-only role of the customer. It writes a signed installation report. The report covers every artefact digest against the manifest, every role and the trust policy of the role, the network paths, the bucket settings, the key-site link, the licence and the boot measurements. hangar verify checks the report offline.

4. The portability report

tools/portability_report.py compares two returns of one job: one release, the same inputs and narrowing, for one tenant, on two pools. The tool verifies each return with hangar verify --json, then lists:

• the fields that must be equal: the release id, the image, platform and command, the companions, the destinations and dropped items, the data scopes, secrets, model routes and person-present steps, the compute and failure policy, the inputs, the values digest, the tenant, the descriptor result of each output, and every other field of the compiled envelope (including the sources of the envelope), each shown by path;
• the fields that may differ: the pool, the attempts and instances, the times (including the window), the issuer, and the configuration digest, which is a declared difference;
• each output digest, equal or different, against the determinism that the package declares.

Only a return that hangar verify passes counts. Any other answer, or no hangar on the search path, fails the report. --no-verify compares the fields alone, and the report then never says that the returns are portable.

A package that declares deterministic promises equal output bytes for equal inputs and configuration, so a different digest fails the report. A package that declares envelope promises results within the declared contract, and the report lists any different digest.

tools/portability_report.py hosted.cert harbour.cert \
    --keys-b harbour_keyset.cbor --release-keys release_keyset.cbor

5. Errors

Read this page as Markdown