feat(backup-services): the Veeam backup surface, reached from the machine it protects

[Denis-hamon]

What this is

Seventeen v2 paths manage the Veeam Backup product — tenants, storage vaults, the Service Provider Console that drives the agents — and none had a command. Not skipped: invisible, because this repository could only fetch v1 schemas until #262.

All 25 operations are badged Beta version upstream.

ovhcloud backup-services tenant|vault|vspc list|get|edit
ovhcloud backup-services vault buckets <vault>
ovhcloud backup-services policies
ovhcloud backup-services deploy-script
ovhcloud backup-services licenses list|servers <license>

ovhcloud baremetal backup-agent show|create|edit|delete <server>

The hierarchy is three UUIDs deep, so it is resolved

A tenant holds a VSPC tenant which holds the agents. Nobody knows any of those identifiers. One of each is taken silently; several are refused with an identifier to paste and a name to recognise; none is an answer, not a stack of failed lookups. --tenant and --vspc exist for the accounts where there is a choice.

An agent is reached from the machine it protects

backup.AgentProductTypeEnum lists OVHCLOUD_BAREMETAL as a first-class product type, and an agent names its server in productResourceName. Measured on the real account:

	agents
type OVHCLOUD_BAREMETAL	9 / 9
named agent-<server>	9 / 9
ips = the server's own address in a /32	9 / 9
region = the server's own region	9 / 9

That correspondence is why create needs nothing but a server name:

$ ovhcloud baremetal backup-agent create ns3118333.ip-51-68-100.eu --dry-run
🔍 Dry run: nothing was sent. This would have been called:
  POST /v2/backupServices/tenant/15d3f0dd…/vspc/9b0752a1…/backupAgent

with:
  {
    "displayName": "agent-ns3118333.ip-51-68-100.eu",
    "ips": [ "51.68.100.165/32" ],
    "productResourceName": "ns3118333.ip-51-68-100.eu",
    "region": "eu-west-rbx"
  }

Three things the measurement decided

NOT_INSTALLED is where a created agent stops, not a step on the way. The object exists; the software is not on the machine. All nine agents of this account are in that state, with an empty policy, while two retention policies sit beside them — nine provisioned, none deployed, none retaining anything. So it counts as settled for --wait, and the success message says what is left to do instead of "created":

✅ Backup agent a-1 created for ns1.example, status NOT_INSTALLED.
   It protects nothing until the agent software runs on the machine:
     ovhcloud backup-services deploy-script
   And nothing is retained until it is put on a policy:
     ovhcloud baremetal backup-agent edit ns1.example --policy <name>

The PUT replaces the target spec, so edit carries over what it is not changing. Sending only --policy would blank the display name and the addresses — the trap iam resource edit --tag still has.

vault bucket credentials is deliberately absent. The schema declares a GET; the API answers 405 on all three buckets of this account, with no Allow header. Controls, same client and token:

request	answer
GET .../bucket/{realId}/credentials	405, no body, no Allow
GET .../bucket/{fakeId}/credentials	404
GET .../bucket/{realId}	200
OPTIONS .../credentials	200

The route resolves the bucket and then refuses the method, so the command would always fail. Same reason install/hardwareRaidSize was left out of #250. Worth reporting to the owner of the route — sixth API defect found by this audit.

Two columns exist because the object hides what you are looking for

Tasks. This generation of the API has no task route to poll: a resource carries the tasks running on it, and that list is the only place a failure appears. The column names the operation, because ERROR answers "error doing what?" with nothing.

Not allowedIps. It looks like a field of a vault and it is not — the addresses allowed to reach one are listed in the VSPC tenant's own view of its vaults. Reading it off the vault resource answers 0 where the truth is 9, and a column that is wrong reads worse than a column that is missing. A test pins its absence.

The tasks column found something on the first run

backup-vault-paygo-standard-ca-east-tor-610301  READY  BACKUP_VAULT_CREATE ERROR
backup-vault-paygo-standard-sgp-610301          READY  BACKUP_VAULT_CREATE ERROR, BACKUP_VAULT_CREATE ERROR
vspc-tenant-610301                              READY  VSPC_TENANT_UPDATE PENDING, VSPC_AGENT_UPDATE ERROR, …

Three failed BACKUP_VAULT_CREATE, one failed VSPC_AGENT_UPDATE, two VSPC_TENANT_UPDATE stuck in PENDING — sampled six times over five minutes, identical identifiers and statuses each time — on resources that all report READY. Nothing surfaced them before.

Two things about those tasks are worth noting upstream: errors is declared on a task in the schema and is empty even on a failed one, and link — documented as "Link to the task details" — is the empty string. A failure with no message and nowhere to look.

Verified against the API

Every read exercised live: tenants, vaults (3), buckets, VSPC tenant, policies (14d_retention, 30d_retention), licences (none, which is an answer), deploy script, and the agents of a server that has one and of one that has not.

Refusals executed live: unknown retention policy, edit and delete on a server with no agent, and --dry-run on create and delete.

The write cycle, run end to end

Authorised by the account owner and run on ns3118333.ip-51-68-100.eu, a server with no agent:

step	measured
before, read outside the CLI	no agent on this server; 9 agents ↔ 9 allowed addresses on each of the 3 vaults
create --wait --yes	38 s, exit 0, NOT_INSTALLED, name / address / region derived from the server
side effect	the 3 vaults go to 10 addresses; 51.68.100.165/32 added — the confirmation prompt was right
edit --policy 14d_retention	HTTP 500, state unchanged when re-read outside the CLI
edit --policy '' (a write that changes nothing)	HTTP 500 as well
delete --wait --yes	31 s, exit 0, agent gone, tenant back to 9
removing the same agent again	refused, with the command that lists

Two things came out of it that no amount of reading the schema would have shown.

The PUT answers 500. Twice, with two query ids, and the second call is the control: it sets the target spec to exactly what it already was, so the failure is not about the value being applied. The command reports it and claims nothing — the state re-read outside the CLI is unchanged. Root cause is almost certainly BKP-1517, filed by the backup team the day before; the API-side evidence has been added there as a comment.

Deleting an agent does not take back its storage authorisation. After the delete, the three vaults still allow 51.68.100.165/32 — 10 addresses for 9 agents, and the orphan is exactly the deleted agent's. Sampled three times over 90 seconds and again later: not eventual consistency. Before the cycle the correspondence was exact, 9 ↔ 9, zero orphans. Filed as BKP-1523; on a customer account every agent ever deleted leaves a permanent entry in the allow-list of the backup vaults.

Against LVL2-19664

The acceptance criteria of the product ticket, and where each one lands:

criterion	command	status
MUST List Agent	backup-services agents	✅ estate-wide, plus baremetal backup-agent show <server> per machine
MUST Enable Backup Agent on a Bare Metal	baremetal backup-agent create <server>	✅ run end to end
MUST Modify Policies on a specific Agent / Server	baremetal backup-agent edit --policy	✅ command correct, API answers 500 (BKP-1517)
MUST Download Agent	backup-services deploy-script (alias download-agent)	✅
MUST list Vault specific details (localisation)	backup-services vault list / get / buckets	✅ region per vault and per bucket
MUST List billing / invoices pricing / consumption	backup-services billing	✅ plan, price, period, renewal, state, consumption
SHOULD Order service	—	❌ not covered, see below

The billing view needed a join the backup API does not offer: a v2 resource carries no price at all. Measured — /v1/services?resourceName=<uuid> answers with exactly one billable service for the backup tenant, for the VSPC tenant and for each vault, so it is one lookup per resource rather than a sweep of the 826 services on this account.

kind    name                                            plan                price   period  consumption  renew      state
tenant  15d3f0dd-6b46-46c8-9e4e-2a48015c90ec            backup-tenant       0.00 €  P1M     none yet     automatic  active
vspc    vspc-tenant-610301                              vspc-tenant         0.00 €  P1M     none yet     automatic  active
vault   backup-vault-paygo-standard-sbg-610301          backup-vault-paygo  0.00 €  P1M     none yet     automatic  active

none yet is a fact — nothing has been stored, every agent is NOT_INSTALLED. Consumption that could not be read says unknown instead: a failed read is not a reading of zero.

What is not covered, and why. Ordering (the SHOULD) goes through the order cart, which is its own surface and its own lot. Account-level invoices (/v1/me/bill) are account-wide and no command exposes them yet; scoping them to one product belongs to an account lot rather than to this one.

Gate

go build, go vet, make wasm, go test ./..., docgen — all clean. backup-services is added to the hand-written command index, which make doc discards and therefore never updates on its own.

36 tests (13 unit, 19 cobra) and 22 sabotages, 22 red — each on the test it was meant to exercise, restoration checked by digest.

Stacked on #264 → #263 → #262 → #261.

[Denis-hamon]

Human review — Works as intended

M4 · deploy-script makes the agent installable
Dimension: Discoverability

Expected: This is what makes the product usable from a terminal. Does the format suit a runbook?

Dont call it "Veeam backup agent", call it "Backup Agent"
Also, remove MAC URL https://…/VeeamAgent.pkg, we don't provide MAC agents.

— Antoine Ruelle (PU Lead), through CLI sandbox review page

[Denis-hamon]

Human review — Works as intended

M4 · deploy-script makes the agent installable
Dimension: Discoverability

Expected: This is what makes the product usable from a terminal. Does the format suit a runbook?

Dont call it "Veeam backup agent", call it "Backup Agent"
Also, remove MAC URL https://…/VeeamAgent.pkg, we don't provide MAC agents.

— Antoine Ruelle (PU Lead), through CLI sandbox review page