Add device provisioning documentation by swagner-de · Pull Request #530 · ironcore-dev/network-operator

swagner-de · 2026-08-28T13:32:07Z

Document the platform-agnostic provisioning contract in
docs/concepts/provisioning.md: the Device resource, lifecycle phases,
HTTP endpoints, source validation, the ProvisioningProvider hook
interface, and password handling. Document Cisco NX-OS specifics
(POAP, install all, password hash formats) in docs/concepts/ztp-nxos.md,
with the reference POAP boot script at hack/ztp/nxos.py.

Signed-off-by: Sebastian Wagner sebastian.wagner02@sap.com

Document the platform-agnostic provisioning contract in docs/concepts/provisioning.md: the Device resource, lifecycle phases, HTTP endpoints, source validation, the ProvisioningProvider hook interface, and password handling. Document Cisco NX-OS specifics (POAP, install all, password hash formats) in docs/concepts/ztp-nxos.md, with the reference POAP boot script at hack/ztp/nxos.py. Signed-off-by: Sebastian Wagner <sebastian.wagner02@sap.com>

felix-kaestner · 2026-09-01T09:28:13Z

                    { text: 'Pausing Reconciliation', link: '/concepts/pausing' },
                    { text: 'Numbered Resources', link: '/concepts/numbered-resources' },
+                    { text: 'Device Provisioning', link: '/concepts/provisioning' },
+                    { text: 'ZTP for Cisco NX-OS', link: '/concepts/ztp-nxos' },


Shouldn't "ZTP for Cisco NX-OS" be a sub-section under the the "Device Provisioning"?

felix-kaestner · 2026-09-01T09:29:50Z

@@ -0,0 +1,212 @@
+# Device Provisioning
+
+The network operator can bootstrap a device automatically on first boot, from initial network configuration through OS image upgrade and final handoff to the operator. This page describes the platform-agnostic provisioning contract: the `Device` resource, the lifecycle phases, the HTTP endpoints a device talks to, and the provider hook interface a new platform must implement.


Lifecycle phases and the http endpoints were already documented in https://github.com/ironcore-dev/network-operator/blob/main/docs/tutorials/device-onboarding.md#device-lifecycle-phases. Please condense this information to a single location.

felix-kaestner · 2026-09-01T09:35:21Z

+
+The `provisioning.image` section tells the operator which image the device should run. When the boot script contacts the operator, this is what gets returned in the config response.
+
+The `provisioning.bootScript` holds the boot script the device runs, supplied inline or from a referenced Secret or ConfigMap. The operator ships an optional built-in TFTP server (beta) that serves this script directly: the device requests a filename encoding its serial (`serial-<serial>` or `<serial>.<ext>`), the server resolves the matching `Device`, reads `spec.provisioning.bootScript`, and returns its contents as-is. With source validation enabled it also checks that the client IP matches the device endpoint and the serial matches `status.serialNumber`. If you already run your own TFTP infrastructure, delivery can stay external to the operator instead.


Where do we take the "beta" state of the built-in TFTP Server from?

felix-kaestner · 2026-09-01T09:38:46Z

+
+### `GET /provisioning/mtls-client-ca` and `GET /provisioning/device-certificate`
+
+Both are optional. They let the device fetch the operator's mTLS client CA and a per-device certificate so the operator can later connect over an authenticated channel. A device that does not need certificates can ignore these; the operator returns `404` when there is nothing to hand out, which the boot script treats as "skip".


"per-device" is nothing the operator does or enforces. It just serves what a user sets in the Device spec. How these server certificates are created, is up to the user.

felix-kaestner · 2026-09-01T09:40:40Z

+
+## Provisioning provider interface
+
+A platform plugs into provisioning by implementing `ProvisioningProvider` (`internal/provider/provider.go`):


Anything in /internal is intentionally private and no public API (ref/ https://github.com/golang-standards/project-layout/tree/master/internal). As such I'm not sure we want to document that in a public documentation. With code in /internal we reserve the possibility to change that interface at any time w/o external guarantees.

felix-kaestner · 2026-09-01T09:42:09Z

+
+The operator never sends a plaintext password to the device over the provisioning channel. That channel may be unauthenticated or otherwise not fully trusted (the device has not yet been secured, and the operator does not verify the device's identity at this stage), so shipping a cleartext credential over it would be unsafe.
+
+Instead the operator reads the admin credential from the device's endpoint Secret and passes the plaintext to the provider's `HashProvisioningPassword` hook. The hook returns two things: a hash in the device's native on-box format, and an algorithm label identifying which hash format it is.


We don't have any "admin" semantics here. This is just a user account from the device spec from our perspective.

felix-kaestner · 2026-09-01T09:43:45Z

+
+Both are placed in the config response as `userAccounts[].hashedPassword` and `userAccounts[].hashAlgorithm`. The boot script maps the algorithm label to the platform's corresponding on-device password type and configures the account with the pre-hashed value; the plaintext never leaves the operator.
+
+## Observing provisioning progress


This just shows normal kubectl usage, nothing specific to our network-operator. As such, do we even want to have that in our documentation. Users can also choose an GUI or any other way of looking at kubernetes resources.

felix-kaestner · 2026-09-01T09:44:40Z

+
+## Boot script
+
+The network operator ships its own POAP boot script at [`hack/ztp/nxos.py`](https://github.com/ironcore-dev/network-operator/blob/main/hack/ztp/nxos.py). It is not Cisco's reference POAP script; it talks to the operator's provisioning API and uses `install all` (see below). Site-specific values like the provisioning server URL have been replaced with placeholders and must be adapted to your environment before use.


We don't do that by default (like this sentence implies). This is just an example. Users might set their own version, however they desire.

This whole document is written in this way that the "network operator provides" which is not the case. We should rephrase this to state this as an example for reference.

github-actions Bot added the size/XL label Aug 28, 2026

swagner-de force-pushed the docs/provisioning branch from b448d9a to 3a9b9df Compare August 28, 2026 13:34

swagner-de force-pushed the docs/provisioning branch from 3a9b9df to 9b47913 Compare August 28, 2026 13:41

swagner-de enabled auto-merge (rebase) August 28, 2026 13:42

felix-kaestner changed the title ~~docs: add device provisioning documentation~~ Add device provisioning documentation Aug 28, 2026

hardikdr added the area/switch-automation Automation processes for network switch management and operations. label Aug 29, 2026

hardikdr added this to Roadmap Aug 29, 2026

felix-kaestner reviewed Sep 1, 2026

View reviewed changes

Navigation Menu

Uh oh!

Add device provisioning documentation - #530

Add device provisioning documentation#530
swagner-de wants to merge 1 commit into
mainfrom
docs/provisioning

swagner-de commented Aug 28, 2026

Uh oh!

felix-kaestner Sep 1, 2026

Uh oh!

felix-kaestner Sep 1, 2026

Uh oh!

felix-kaestner Sep 1, 2026

Uh oh!

felix-kaestner Sep 1, 2026

Uh oh!

felix-kaestner Sep 1, 2026

Uh oh!

felix-kaestner Sep 1, 2026

Uh oh!

felix-kaestner Sep 1, 2026

Uh oh!

felix-kaestner Sep 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		@@ -0,0 +1,212 @@
		# Device Provisioning

		The network operator can bootstrap a device automatically on first boot, from initial network configuration through OS image upgrade and final handoff to the operator. This page describes the platform-agnostic provisioning contract: the `Device` resource, the lifecycle phases, the HTTP endpoints a device talks to, and the provider hook interface a new platform must implement.


		The `provisioning.image` section tells the operator which image the device should run. When the boot script contacts the operator, this is what gets returned in the config response.

		The `provisioning.bootScript` holds the boot script the device runs, supplied inline or from a referenced Secret or ConfigMap. The operator ships an optional built-in TFTP server (beta) that serves this script directly: the device requests a filename encoding its serial (`serial-<serial>` or `<serial>.<ext>`), the server resolves the matching `Device`, reads `spec.provisioning.bootScript`, and returns its contents as-is. With source validation enabled it also checks that the client IP matches the device endpoint and the serial matches `status.serialNumber`. If you already run your own TFTP infrastructure, delivery can stay external to the operator instead.


		### `GET /provisioning/mtls-client-ca` and `GET /provisioning/device-certificate`

		Both are optional. They let the device fetch the operator's mTLS client CA and a per-device certificate so the operator can later connect over an authenticated channel. A device that does not need certificates can ignore these; the operator returns `404` when there is nothing to hand out, which the boot script treats as "skip".


		## Provisioning provider interface

		A platform plugs into provisioning by implementing `ProvisioningProvider` (`internal/provider/provider.go`):


		The operator never sends a plaintext password to the device over the provisioning channel. That channel may be unauthenticated or otherwise not fully trusted (the device has not yet been secured, and the operator does not verify the device's identity at this stage), so shipping a cleartext credential over it would be unsafe.

		Instead the operator reads the admin credential from the device's endpoint Secret and passes the plaintext to the provider's `HashProvisioningPassword` hook. The hook returns two things: a hash in the device's native on-box format, and an algorithm label identifying which hash format it is.


		Both are placed in the config response as `userAccounts[].hashedPassword` and `userAccounts[].hashAlgorithm`. The boot script maps the algorithm label to the platform's corresponding on-device password type and configures the account with the pre-hashed value; the plaintext never leaves the operator.

		## Observing provisioning progress


		## Boot script

		The network operator ships its own POAP boot script at [`hack/ztp/nxos.py`](https://github.com/ironcore-dev/network-operator/blob/main/hack/ztp/nxos.py). It is not Cisco's reference POAP script; it talks to the operator's provisioning API and uses `install all` (see below). Site-specific values like the provisioning server URL have been replaced with placeholders and must be adapted to your environment before use.

Uh oh!

Conversation

swagner-de commented Aug 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants