Skip to content

docs: explain phoneHomeEnabled flag and the phone-home flow #3007

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
CTOmari360 wants to merge 2 commits into
base: main
Choose a base branch
from
+43 −2
Open

docs: explain phoneHomeEnabled flag and the phone-home flow #3007

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6951cde
docs: explain phoneHomeEnabled flag and the phone-home flow
CTOmari360 Jun 30, 2026
186d596
docs: correct phone-home injection behavior
CTOmari360 Jul 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions docs/configuration/tenant_management.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -589,6 +589,35 @@ nicocli instance status-history <instance-id>

The instance detail response is rich -- it includes `interfaces[]` with assigned IP addresses and VPC prefix info, `ipxeScript` showing the live boot script, `serialConsoleUrl` for console access, full machine and SKU metadata, and any active `deprecations[]` warnings. The API uses inline `deprecations[]` arrays to flag fields scheduled for removal -- watch for these in your responses.

### Phone-home

`phoneHomeEnabled` (`--phone-home-enabled`) controls whether NICo waits for the booted operating system to call back -- to "phone home" -- before it reports the instance as ready. It is a property of the operating-system definition (`operating-system create` / `operating-system update`) and can also be set per instance (`instance create` / `instance update`).

**What it does.** When phone-home is enabled, NICo does not consider the instance fully provisioned until the booted OS contacts NICo's metadata service from inside the guest. The instance is held in a provisioning state -- the transition to `Ready` is gated -- until that callback arrives. When it is disabled, NICo reports the instance ready as soon as provisioning and config sync finish, without waiting for any signal from the OS.

**What NICo injects.** When phone-home is enabled, NICo edits your `userData` for you -- you do *not* add the callback yourself. NICo parses your cloud-init YAML, strips any existing [`phone_home`](https://cloudinit.readthedocs.io/en/latest/reference/modules.html#phone-home) block, and inserts one that POSTs to the site's metadata endpoint:

```yaml
#cloud-config
# ... your first-boot setup (SSH keys, passwords, packages, ...) ...
phone_home:
url: http://169.254.169.254:7777/latest/meta-data/phone_home
post: all
```

The injected `url` is the site-configured phone-home endpoint (`site.phoneHomeUrl`; default `http://169.254.169.254:7777/latest/meta-data/phone_home`), which the platform operator can override per deployment. If you supply no `userData`, NICo generates a minimal `#cloud-config` containing only the block above. Disabling phone-home reverses this: NICo removes the matching `phone_home` block it manages. Because NICo rewrites your user-data as YAML, **`userData` must be valid cloud-init YAML (a `#cloud-config` mapping) whenever phone-home is enabled** -- the API rejects the request otherwise.

cloud-init runs the `phone_home` module in its final stage, after the rest of your configuration has been applied, so the callback fires only once your setup has completed. When NICo receives the POST it records the contact and releases the readiness gate, allowing the instance to become `Ready`.

**When to use it.** Enable phone-home when "ready" must mean "the guest has finished its own first-boot setup" -- for example, to delay readiness until cloud-init has applied SSH keys and passwords, so that automation watching for `Ready` does not connect before the host is fully configured. Leave it disabled when NICo finishing provisioning is a sufficient ready signal and you do not need a callback from inside the guest.

**Notes and caveats.**

- Phone-home only gates *status reporting*. It does not change how the host is provisioned or booted -- the reboot into the provisioned OS happens identically whether or not phone-home is enabled.
- If phone-home is enabled but the booted OS never runs cloud-init -- or the guest cannot reach the metadata endpoint -- the callback never arrives and the instance stays in its provisioning state, never reporting ready.
- The metadata endpoint (`169.254.169.254:7777`) is reachable only from the provisioned host over its link-local metadata link; it is not a tenant-facing API.
- Rebooting the instance with a one-time custom iPXE override (`instance update --reboot-with-custom-ipxe=true`) re-arms the gate when phone-home is enabled: NICo clears the recorded contact, so the OS must phone home again before the instance is reported ready.
Comment on lines +594 to +619

@coderabbitai coderabbitai Bot Jun 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
rg -n -C 3 --hidden -g '!**/target/**' 'phoneHomeEnabled|phone-home-enabled' .

Repository: NVIDIA/infra-controller

Length of output: 50381

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Show the doc section around the reviewed lines.
sed -n '594,617p' docs/configuration/tenant_management.md

echo
echo '---'
echo

# Show the merge logic that resolves phoneHomeEnabled for instance creation/update.
sed -n '2068,2095p' rest-api/api/pkg/api/handler/instance.go

echo
echo '---'
echo

# Show the update-path precedence comment for phoneHomeEnabled.
sed -n '1228,1245p' rest-api/api/pkg/api/model/instance.go

Repository: NVIDIA/infra-controller

Length of output: 4532

🏁 Script executed:

#!/bin/bash
set -euo pipefail

sed -n '594,617p' docs/configuration/tenant_management.md
echo '---'
sed -n '2068,2095p' rest-api/api/pkg/api/handler/instance.go
echo '---'
sed -n '1228,1245p' rest-api/api/pkg/api/model/instance.go

Repository: NVIDIA/infra-controller

Length of output: 4528

State the precedence for phoneHomeEnabled. The text says the flag can be set both on the operating system and per instance, but it should explicitly say that the instance value overrides the OS default, and that the OS value is inherited only when the instance omits it.

🧰 Tools
🪛 LanguageTool

[style] ~614-~614: ‘whether or not’ might be wordy. Consider a shorter alternative.
Context: ... the provisioned OS happens identically whether or not phone-home is enabled. - If you enable ...

(EN_WORDINESS_PREMIUM_WHETHER_OR_NOT)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/configuration/tenant_management.md` around lines 594 - 617, Clarify the
precedence of phoneHomeEnabled in the tenant management docs: update the
phone-home section to explicitly state that an instance-level setting overrides
the operating-system default, and that the OS-level value is only inherited when
the instance does not specify one. Make this change in the phoneHomeEnabled
description and keep the wording aligned with the existing instance
create/update and operating-system create/update references.

Source: Path instructions


### Batch Instance Creation

For creating multiple identical instances at once, use `instance batch-create`. Unlike `create`, batch-create takes a single shared spec plus a count -- it provisions N instances with auto-generated names from the same instance type, tenant, and VPC. `nicocli instance batch-create --help` shows:
Expand Down
8 changes: 7 additions & 1 deletion docs/manuals/nico-admin-cli/commands/operating-system/operating-system-create.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,13 @@ Whether this OS definition is active (default: true).\
Allow users to override OS parameters.

**--phone-home-enabled**
Enable phone-home on first boot.
Hold the instance in a provisioning state until the booted OS calls back
("phones home") to NICo's metadata service, instead of reporting it ready as
soon as provisioning finishes. NICo injects the cloud-init `phone_home` block
into your user-data for you, so your `userData` must be valid cloud-init YAML
when this is enabled. See
[Phone-home](../../../../configuration/tenant_management.md#phone-home) for
what it injects, the endpoint, and usage guidance.

**--user-data** *\<USER_DATA\>*
Optional cloud-init / user-data script.
Expand Down
8 changes: 7 additions & 1 deletion docs/manuals/nico-admin-cli/commands/operating-system/operating-system-update.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,13 @@ Set whether users can override OS parameters.\
- false

**--phone-home-enabled** *\<PHONE_HOME_ENABLED\>*
Set whether phone-home on first boot is enabled.\
Set whether the instance is held in a provisioning state until the booted OS
calls back ("phones home") to NICo's metadata service, instead of being
reported ready as soon as provisioning finishes. NICo injects the cloud-init
`phone_home` block into your user-data for you, so your `userData` must be
valid cloud-init YAML when this is enabled. See
[Phone-home](../../../../configuration/tenant_management.md#phone-home) for
what it injects, the endpoint, and usage guidance.\

\
*Possible values:*
Expand Down
Loading