--- name: graphiant-plan-software-rollout description: Read the current software state of an estate, understand which release train each device is on, and schedule an upgrade rollout against a device set. api: openapi/graphiant-portal-openapi-original.json generated: '2026-08-01' method: generated risk: high operations: - getV1EdgesSummary - getV1SoftwareRollouts - postV1SoftwareRollouts - putV1SoftwareRollouts - getV1SoftwareRolloutsById - deleteV1SoftwareRolloutsById - postV1SoftwareRolloutsSchedule - getV1SoftwareAutoUpgradeDefault - putV1SoftwareAutoUpgradeDefault - getV1SoftwareReleasesDownload title: Plan and schedule a Graphiant software rollout --- # Plan and schedule a Graphiant software rollout **Upgrades reboot production network devices.** Creating or scheduling a rollout requires explicit human approval. Reading the current state does not. Complete `graphiant-authenticate-and-scope.md` first. ## 1. Establish where the estate sits today `GET /v1/edges-summary` returns `swVersion` and `swName` per device — for example `2506.202506021956` / `25.6.1`. Graphiant names software `YY.MM.`: two-digit year, month, counter. Sort by that, not lexically by `swVersion`. ## 2. Know which train you are moving to Graphiant runs three concurrent release trains. Choose deliberately: | Train | Released | Supported for | Use for | |---|---|---|---| | **Latest** | monthly | 2.5 months (1 month critical fixes, then 45 days spot fixes) | newest features, lab and pilot sites | | **Recommended** | every 3 months (every 3rd Latest) | 6.5 months (3 months active critical fixes, then 3.5 months spot fixes) | the default for production | | **Stable** | every 12 months (every 4th Recommended) | 12 months (6 months active critical fixes, then 6 months spot fixes) | long-lived sites you upgrade rarely | A device left on a train past its support window stops receiving fixes and leaves QA coverage. Support overlap with the preceding release is maintained so you can upgrade at your convenience — but the window is finite. Out-of-band **Maintenance Releases** are deployed when a fix cannot wait for the next scheduled release; upgrade to those when advised. `GET /v1/software/releases/download` lists what is available. ## 3. Read existing rollouts before creating another - `GET /v1/software/rollouts` — current campaigns - `GET /v1/software/rollouts/{id}` — one campaign Check for an overlapping rollout targeting the same devices before you create one. There is no idempotency key on the create operation and no server-side conflict check documented — two overlapping rollouts against one device set is your problem to prevent. ## 4. Create and schedule - `POST /v1/software/rollouts` — create a campaign against a device set (`UpgradeRolloutConfig`, `UpgradeRolloutDevice`) - `PUT /v1/software/rollouts` — modify - `POST /v1/software/rollouts/schedule` — attach a schedule; recurrence models are `UpgradeRecurringSchedule` with weekly, monthly or yearly variants - `DELETE /v1/software/rollouts/{id}` — cancel Schedule inside Graphiant's own maintenance posture where you can: **scheduled maintenance is every fourth Friday of the month, 14:00–16:00 ET**, and that window counts as *Available* under the SLA. Emergency maintenance counts as *Not Available*. ## 5. Auto-upgrade default - `GET /v1/software/auto-upgrade/default` — read the enterprise default - `PUT /v1/software/auto-upgrade/default` — change it Changing the enterprise auto-upgrade default affects every device that does not override it. Treat it as a higher-blast-radius change than any single rollout. ## SLA context Graphiant commits to **>99.99% availability**, with service credits from 2% (99.90–99.98%) up to 100% (below 92%). P1 incidents are acknowledged in 15 minutes with hourly updates and a one-hour resolution target. A botched rollout that takes sites down is a P1 — know the escalation path before you schedule. Watch `https://status.graphiant.io/` during the window (note: `.io`, not `.com`). See `lifecycle/graphiant-lifecycle.yml` and `changelog/graphiant-changelog.yml`.