Repository navigation
feat: set Arc extension settings and upgrade an instance through typed inputs - #86
Merged
Paymaun (digimaun) merged 12 commits intoOct 29, 2026
Conversation
A typed input contract can declare a stringMap input that writes a mapping of string keys to string values under Site parameters or properties. Operators supply one inline entry for each key as --input NAME=KEY=VALUE, or a mapping in the answer file. Inline keys replace answer file keys one by one. Values are never converted from other YAML types, and each source and the combined map are bounded by entries, code points and UTF-8 bytes. Errors name the input and the key, never the value, and redacted output omits the key. An omitted or empty map writes nothing. A map declares no default, cannot overlap siteDefaults or control a condition, and required means at least one entry. Scalar inputs keep their grammar, including values with `=`. `siteops inputs` shows each map's Site field, an answer file example and the inline form. `siteops browse` suggests a generic entry for a required map. Contracts that use the type need the package feature typed-input-maps/v1, which the engine supports and the package producer requires.
…grade aio-install accepts optional aioExtensionSettings, secretStoreExtensionSettings and certManagerExtensionSettings maps. They write the existing aioConfigurationOverrides, secretStoreConfigurationOverrides and certManagerConfigurationOverrides Site parameters. The cert-manager map applies only when enableCertManager is true. aio-upgrade has a typed contract for one existing instance. It reads the instance, its custom location and its cluster, requires aioRelease and an explicit enableCertManager answer, and accepts the same maps and optional labels. Runs with configured Sites and --site-file are unchanged. The guides describe the map inputs, the settings the installation derives, the dedicated trust and broker settings, the supported upgrade paths and upgrading at the current release to change only settings. The workspace preview release declares typed-input-maps/v1.
The v1.0.0b8 migration guide describes the typed extension settings, the typed aio-upgrade contract and the engine feature they need. The AIO release reference moves across several minor versions one minor version at a time, links the current Microsoft upgrade page and points to the extension settings section of the installation guide.
The package producer reads the input contract sidecar that the contract loader selects for each discovered manifest, `inputs.yaml` beside manifest.yaml or `<manifest>.inputs.yaml` beside a flat manifest, and requires typed-input-maps/v1 when that contract declares a stringMap input. Other files named `inputs.yaml`, such as parameter files, are ordinary content again, so a workspace that the v1.0.0b7 producer accepted builds without the feature. An unreadable sidecar of a manifest still stops production.
YAML tags a bare `=` key as a value key and loads it as the string "=". The strict loader now compares that key as "=" instead of skipping it, so two bare `=` keys, or a bare and a quoted `"="` key in either order, fail with the existing duplicate key error rather than keeping only the last value. Merge keys, a single `=` key and keys that contain `=` load as before. The loader reads every engine YAML document, so any Site, manifest, parameter file, input contract or answer file that repeats `=` in one mapping now fails where it previously dropped the earlier value. The migration guide describes the change.
A required controlling input without a default that has no answer is now reported as a missing required input, in input order, and its conditional inputs wait until it is answered. An optional controlling input keeps the explanation that it controls a conditional input. For the typed aio-upgrade contract, an unedited example now names `instance` first and an omitted cert-manager answer names `enableCertManager` itself. A missing required input ends with the inline form that supplies it, such as ``Supply `--input aioRelease=<value>`.``, with `<true-or-false>` for a boolean. Resource and map inputs keep their specific guidance.
stringMap keys must be printable text: Unicode control, format, surrogate, private use and unassigned characters stay rejected, and line and paragraph separators are now rejected too. The error says the keys must be printable text instead of naming only control characters. A key that YAML reads as a boolean, number or null asks to quote each key. A nested mapping value asks to write each setting as one dotted key with a quoted value, while other values that are not text still ask to quote each value. The guided inputs guide and the manifest reference state the key policy.
The --input help names the map entry form as NAME=KEY=VALUE and says that inline map entries merge with the input file's map key by key, while other inline answers replace the file's answer.
Installation writes each Arc extension's settings from the template defaults, the AIO release and the Site without reading the cluster's settings. The installation guide and the guided inputs guide no longer say that an omitted map keeps the cluster's settings. They send readers who change an existing installation's settings to aio-upgrade at its current AIO release, which keeps existing settings and removes no key. The upgrade guide lists the AIO version of every AIO release in this workspace, shows how to read the version an instance runs, and says never to select an older release. It says that an installation setting for a key the AIO release also sets returns to the release value unless supplied again. The documented typed upgrade commands and answer file leave enableCertManager as a placeholder, with when to answer true. The guided inputs guide notes that the private Site preview masks values whose names look sensitive while the saved Site keeps them.
The upgrade-aio skill says to cross several minor versions one minor version at a time, each with its own plan and deploy, and keeps uninstall and reinstall for a downgrade or a move between preview and GA. It links the current Microsoft upgrade page.
The migration guide shows the `--input` form that now ends a missing required typed input error and says to match the unchanged error code instead of the text.
A parameter value with an unresolved, unsupported or malformed template fails preparation with its location and the supported template syntax. The location names the Site parameter and, for a map such as an Arc extension settings answer, the key. The error does not repeat the value, so a typed map answer stays out of plain plan and deploy output as it already does in redacted and JSON output. Settings that contain a supported template still resolve and plan. The error code stays `operation-preparation.invalid`, and the v1.0.0b8 migration notes show the new message.
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues block the typed-input and AIO upgrade changes.
No open issues 🎉
What changed in this PR
This PR extends Site Ops typed inputs to configure Arc extensions and upgrade an existing AIO instance, while preserving the existing Site-based deployment routes.
Changes:
- Adds validated
stringMapinputs with key-by-key merging, CLI guidance, and package compatibility enforcement. - Adds typed AIO upgrade inputs with explicit release and cert-manager choices.
- Improves value-safe diagnostics, duplicate YAML key detection, documentation, and regression coverage.
| File | Description |
|---|---|
| workspaces/iot-operations/siteops-index.json | Updates indexed installation and upgrade guidance. |
| workspaces/iot-operations/siteops-index.inputs.json | Refreshes index and source digests. |
| workspaces/iot-operations/manifests/aio-upgrade/README.md | Documents typed upgrades, supported paths, and settings preservation. |
| workspaces/iot-operations/manifests/aio-upgrade/inputs.yaml | Defines the typed existing-instance upgrade contract. |
| workspaces/iot-operations/manifests/aio-upgrade/entry.yaml | Adds upgrade input metadata and prerequisites. |
| workspaces/iot-operations/manifests/aio-install/README.md | Explains extension maps and derived settings. |
| workspaces/iot-operations/manifests/aio-install/inputs.yaml | Adds three optional extension settings maps. |
| workspaces/iot-operations/manifests/aio-install/entry.yaml | Describes extension override parameters. |
| tests/workspace/test_aio_extension_settings.py | Covers workspace contracts, planning, and documented examples. |
| tests/test_yamlio.py | Covers bare and quoted equals-key duplicates. |
| tests/test_workspace_package.py | Tests map-feature enforcement and compatibility rejection. |
| tests/test_planning.py | Checks template errors omit supplied values. |
| tests/test_guided_inputs.py | Tests map validation, merging, limits, and required inputs. |
| tests/test_guided_cli.py | Covers map help, previews, and safe diagnostics. |
| tests/test_copilot_plugin.py | Checks consistent upgrade-path guidance. |
| tests/test_browse.py | Tests required-map command placeholders. |
| tests/fixtures/prepare_installed_project.py | Declares map support for applicable package fixtures. |
| siteops/yamlio.py | Detects duplicate bare equals keys. |
| siteops/workspace_package.py | Registers the typed-map package feature. |
| siteops/planning.py | Replaces echoed template values with corrective guidance. |
| siteops/package_builder.py | Requires map-feature declarations for relevant contracts. |
| siteops/guided_inputs.py | Implements typed maps and clearer missing-input errors. |
| siteops/cli.py | Displays map examples and expanded input help. |
| siteops/browse_output.py | Adds map-entry placeholders. |
| plugins/siteops/skills/upgrade-aio/SKILL.md | Clarifies sequential minor-version upgrades. |
| docs/workspace-packages.md | Documents map-feature compatibility requirements. |
| docs/migrating.md | Records typed inputs and diagnostic changes. |
| docs/manifest-reference.md | Defines the stringMap contract and limits. |
| docs/guided-inputs.md | Adds extension settings and typed upgrade workflows. |
| docs/aio-releases.md | Updates settings links and upgrade-path guidance. |
| .github/release-examples/workspace-preview/release.json | Declares typed-map support in the release example. |
Review effort: Balanced
Sri Harsha Kalavala (shkalavala)
approved these changes
Oct 28, 2026
Paymaun (digimaun)
deleted the
feat/extension-settings-and-guided-upgrade
branch
October 29, 2026 00:43
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
aio-installaccepts the AIO, Secret Store and cert-manager Arc extension settings as typed inputs, inline or in an answer file, andaio-upgradegains typed inputs for one existing instance. Both write the Site parameters that earlier releases already document, so existing Sites, overlays, parameter files and pipelines work unchanged.What changes for Operators
stringMaptyped input takes string keys and string values. Repeat--input NAME=KEY=VALUEonce for each setting, or give a mapping in the answer file. Inline entries replace answer file entries key by key. Values are never converted from other YAML types, keys must be printable text, and each input is bounded in entries and size. Errors name the input and the key, never the value.aio-installacceptsaioExtensionSettings,secretStoreExtensionSettingsandcertManagerExtensionSettings. They writeaioConfigurationOverrides,secretStoreConfigurationOverridesandcertManagerConfigurationOverrides. The cert-manager map applies only whenenableCertManageris true.aio-upgradehas a typed contract for an existing instance. It reads the instance, its custom location and its cluster from the instance resource ID, and requiresaioReleaseand an explicitenableCertManageranswer: "Include the existing cert-manager Arc extension in this upgrade?". It accepts the same settings maps, an optional Site name and labels. Runs with configured Sites and--site-fileare unchanged.siteops inputsshows each map's Site field, an answer file example and the inline form, andbrowsesuggests an entry for a required map.--inputform that supplies it, such as--input aioRelease=<value>. A required question that controls other inputs is reported in input order. The error code staysinputs.invalid.=, bare or quoted, now fails with the existing duplicate key error instead of keeping only the last value.trustConfigandbrokerConfigfor those concerns. Installation writes each extension's settings without reading the cluster's, so the guides send readers who change an existing installation toaio-upgrade, which keeps existing settings.Upgrading
docs/migrating.mdlists these changes under "To v1.0.0b8". Contracts that usestringMapneed the package featuretyped-input-maps/v1. An earlier Site Ops engine refuses a package that declares it, so install the engine that the content release names. If you build your own packages, the producer requires the feature for a workspace whose input contract declares astringMapinput.Validation
GitHub Actions CI runs ruff, the unit suite, both bootstrap lanes and CodeQL on the final commit. Live installation and upgrade runs with real settings are separate qualification steps.