feat: set Arc extension settings and upgrade an instance through typed inputs

.github/release-examples/workspace-preview/release.json

@@ -14,7 +14,8 @@
         "requiredFeatures": [
           "manifest/v1",
           "composition/v1",
-          "manifest-selection/v1"
+          "manifest-selection/v1",
+          "typed-input-maps/v1"
         ]
       },
       "include": [

docs/aio-releases.md

@@ -77,8 +77,8 @@ parameters:
 
 Site values win over the release settings and template defaults. Values must
 be strings and are visible in Azure, not secret storage. See
-[configure the install Site](../workspaces/iot-operations/manifests/aio-install/README.md#configure-the-site)
-for all extension override maps and the saved Site route for guided users.
+[Arc extension settings](../workspaces/iot-operations/manifests/aio-install/README.md#arc-extension-settings)
+for all extension override maps and the typed inputs that set them.
 
 ## Pinning a Site to an AIO release
 
@@ -167,7 +167,7 @@ This applies to every resource area a Site selects through `properties.resourceS
 
 ### Supported upgrade paths
 
-Azure IoT Operations supports upgrade to any patch of the same minor version, or to the next minor version. Other transitions (downgrades, jumps across several minor versions, and moves between preview and GA) require uninstall and reinstall. See [Upgrade Azure IoT Operations](https://learn.microsoft.com/azure/iot-operations/deploy-iot-ops/howto-upgrade) for the authoritative rules.
+Azure IoT Operations supports upgrade to any patch of the same minor version, or to the next minor version. Move across several minor versions one minor version at a time, for example from a 1.2.x release through a 1.3.x release to a 1.4.x release. A downgrade, or a move between preview and GA in either direction, requires uninstall and reinstall. See [Upgrade Azure IoT Operations](https://learn.microsoft.com/azure/iot-operations/manage-iot-ops/howto-upgrade) for the authoritative rules, and the [upgrade operation guide](../workspaces/iot-operations/manifests/aio-upgrade/README.md#choose-a-supported-upgrade-path) for the minor version of each AIO release and the broker redundancy requirement.
 
 The optional E2E workflow can exercise selected upgrades between adjacent AIO releases,
 such as `2608` to `2609`. A passing dispatch establishes its selected

docs/guided-inputs.md

@@ -9,7 +9,9 @@ separate plan command.
 |---|---|
 | Install AIO on an existing Arc cluster | [AIO installation](#install-aio-from-an-existing-cluster) |
 | Install AIO and enable Secret Sync together | [Combined installation](#install-aio-with-secret-sync) |
+| Set Arc extension configuration | [Arc extension settings](#set-arc-extension-settings) |
 | Enable Secret Sync without reinstalling AIO | [Enablement on an existing instance](#enable-secret-sync-on-an-existing-instance) |
+| Upgrade an existing instance | [Upgrade with typed inputs](#upgrade-an-existing-instance) |
 
 Install a compatible Site Ops build and select a release containing the
 complete AIO workspace and its typed input contract. The source and release
@@ -129,7 +131,9 @@ For a short command without secrets, supply the same named answers with repeated
 the input file. `--input-file` selects exactly one answer file. Repeating
 that option is an error, not a way to select several Sites. Strings and
 strict `true` or `false` booleans are parsed
-according to the selected contract. Do not put secrets in process arguments
+according to the selected contract. A map input takes one `NAME=KEY=VALUE`
+entry for each key, as [Arc extension settings](#set-arc-extension-settings)
+describes. Do not put secrets in process arguments
 or shell history. Input contracts that declare sensitive inputs are
 rejected. Duplicate and unknown answer names fail.
 
@@ -174,6 +178,70 @@ experience, give your account a Key Vault data role as
 [vault access](secret-sync.md#give-your-account-access-to-the-vault)
 describes.
 
+## Set Arc extension settings
+
+`aioExtensionSettings`, `secretStoreExtensionSettings` and
+`certManagerExtensionSettings` set the configuration of the AIO, secret
+store and cert-manager Arc extensions. Each is an optional map of string
+keys and string values. Inline, supply one entry for each key as
+`NAME=KEY=VALUE`:
+
+```text
+siteops deploy aio-install --source "official@<release>" --input "cluster=<Arc-cluster-resource-ID>" --input "aioExtensionSettings=observability.metrics.exportIntervalSeconds=60"
+```
+
+The input name ends at the first `=` and the key ends at the second, so the
+value can contain `=`. An empty value after the second `=` sets an empty
+string. Keys that contain `=` need the answer file, which holds the same
+maps. Quote keys and values there, because YAML reads an unquoted `on` as
+true and `1.10` as 1.1:
+
+```yaml
+apiVersion: siteops.inputs/v1
+kind: SiteInputValues
+values:
+  cluster: "<Arc-cluster-resource-ID>"
+  aioExtensionSettings:
+    "observability.metrics.exportIntervalSeconds": "60"
+```
+
+Inline entries replace answer file entries key by key, and other file
+entries remain. A key repeated inline fails, even with the same value.
+Keys and values must be text. Numbers, booleans, null, lists and nested maps
+fail rather than being converted, so quote each key and value, and write a
+nested setting as one dotted key. Keys must also be printable: no control,
+format, surrogate, private use or unassigned characters, and no line or
+paragraph separators. Which characters are unassigned depends on the Unicode
+version of the engine's Python. Each map, from the file, inline or combined,
+holds at most 64 entries, with keys of 1 to 256 characters, values of at
+most 4,096 characters, and at most 64 KiB of keys and values together.
+Errors name the input and, unless output is redacted, the key, never the
+value. The settings appear in answer files, shell history, the Site preview
+and Azure, so never put secrets in them. The private Site preview shows `***`
+for values whose names look sensitive, such as the whole
+`secretStoreConfigurationOverrides` map and keys that contain `token`. A
+saved Site keeps the real values.
+
+An omitted map or `{}` adds no settings. With `aio-upgrade`, the settings
+already on the cluster stay in place and no answer removes a key.
+Installation writes each extension's settings without reading the
+cluster's, so change the settings of an existing installation with
+[aio-upgrade](../workspaces/iot-operations/manifests/aio-upgrade/README.md#change-extension-settings)
+rather than by installing again. Typed answers build a new Site each time,
+so they never change a saved Site. `certManagerExtensionSettings`
+applies only while `enableCertManager` is true. Supplying it otherwise, even
+as `{}`, fails like any inactive input. The secret store settings apply
+whether or not Secret Sync is enabled. See
+[Arc extension settings](../workspaces/iot-operations/manifests/aio-install/README.md#arc-extension-settings)
+for the Site parameters these inputs set and the settings the installation
+derives.
+
+These typed maps need a Site Ops engine that supports them. An older engine
+refuses a package that uses them with
+`This package requires unsupported Site Ops features.` Install the engine
+that the content release names. Configured Sites and complete Site files
+set the same maps under `parameters` without typed inputs.
+
 ## Manual Site values without resource reads
 
 Omit `cluster` and provide `siteName`, `subscription`, `resourceGroup`,
@@ -222,6 +290,32 @@ still updates the default Secret Provider Class binding. It does not prove
 that a secret materialized in Kubernetes. See the [Secret Sync reference](secret-sync.md)
 for preservation, vault permissions and functional checks.
 
+## Upgrade an existing instance
+
+To upgrade one existing instance without a saved Site, supply its resource
+ID, the target AIO release and whether this upgrade includes the existing
+cert-manager Arc extension:
+
+```text
+siteops deploy aio-upgrade --source "official@<release>" --input "instance=<AIO-instance-resource-ID>" --input aioRelease=2609 --input "enableCertManager=<true-or-false>"
+```
+
+`aioRelease` and `enableCertManager` have no defaults. Answer
+`enableCertManager=true` when Scale Kit installed cert-manager and manages
+it, as an installation with the default `enableCertManager` does. Answer
+`false` when another owner manages cert-manager, and the upgrade neither
+reads nor updates that extension. Site Ops reads the instance, its custom
+location and that location's Arc cluster, as for Secret Sync enablement,
+but checks no OIDC or workload identity prerequisite. The extension
+settings inputs apply here too. Choose a supported transition from the
+version the instance runs, never an older release, as the
+[upgrade guide](../workspaces/iot-operations/manifests/aio-upgrade/README.md#choose-a-supported-upgrade-path)
+describes.
+
+If you saved the installation's Site, change `properties.aioRelease` in that
+file and upgrade with `--site-file` or `-l name=<site>` instead. Typed
+answers never change a saved Site.
+
 ## Check the result
 
 A successful Site Ops result means the deployment operations completed.
@@ -306,8 +400,9 @@ Site must be complete and cannot inherit from packaged example Sites.
 Configured Sites can continue to use the existing inheritance and overlay
 rules.
 
-Settings outside the typed inputs belong in the saved Site, such as
-[AIO extension configuration overrides](../workspaces/iot-operations/manifests/aio-install/README.md#configure-the-site).
+Settings outside the typed inputs belong in the saved Site, such as a
+[trust bundle you manage](../workspaces/iot-operations/manifests/aio-install/README.md#settings-scale-kit-derives).
+Typed answers never change a saved Site, so edit the file itself.
 
 Use one resource group per AIO instance. A Site built from a cluster ID
 takes that cluster's resource group, so connect each Arc cluster in its own

docs/manifest-reference.md

@@ -125,8 +125,8 @@ inputs:
 ```
 
 `siteDefaults` may hold only `labels`, `properties`, and `parameters`.
-Each ordinary `inputs` row declares one semantic name, a `string` or
-`boolean` type, description, and a destination under `name`,
+Each ordinary `inputs` row declares one semantic name, a `string`,
+`boolean` or `stringMap` type, description, and a destination under `name`,
 `subscription`, `resourceGroup`, `location`, `labels`, `parameters`, or
 `properties`.
 An input without a default is required unless `required: false` is
@@ -143,6 +143,31 @@ The DNS label format accepts lowercase letters, digits and interior hyphens,
 with at most 63 characters. `maxLength` supplies a further string limit.
 These constraints apply to defaults, file values and inline overrides.
 
+A `stringMap` input writes a mapping of string keys to string values under
+`parameters` or `properties`:
+
+```yaml
+- name: settings
+  type: stringMap
+  required: false
+  description: Extension configuration settings.
+  sitePath: parameters.settingsOverrides
+```
+
+It declares no default, and `required: true` means at least one entry. Its
+path cannot overlap `siteDefaults` or another input, and it cannot control a
+condition. An omitted map or `{}` writes nothing. Operators supply one inline
+entry for each key as `--input NAME=KEY=VALUE`, and inline keys replace answer
+file keys one by one. Keys and values are never converted from other YAML
+types. Keys must be printable text, with no control, format, surrogate,
+private use or unassigned characters and no line or paragraph separators.
+Which characters are unassigned depends on the Unicode version of the
+engine's Python. Each supplied map and the combined map hold at most 64
+entries, keys of 1 to 256 characters, values of at most 4,096 characters
+and at most 64 KiB of UTF-8 keys and values. A package whose contract uses
+`stringMap` must declare the required feature `typed-input-maps/v1`, which
+the package producer enforces.
+
 A named `azureResourceId` input can instead derive values for existing
 semantic inputs. This is an optional read, not a source of Azure
 credentials or arbitrary provider commands. For example, after declaring

docs/migrating.md

@@ -47,6 +47,12 @@ These changes affect how you install or run Site Ops after v1.0.0b7.
 | Install Site Ops on Windows with the PowerShell bootstrap | Review the [saved user PATH](#windows-user-path). |
 | Match artifact verification error text, or read `source` from failed `browse --output json` | Review [artifact verification messages](#artifact-verification-messages). |
 | Read `diagnostics` from `validate`, `plan` or `deploy` JSON, or render it in a pipeline | Review [warnings in JSON results](#warnings-in-json-results). |
+| Want Arc extension settings without a saved Site | Nothing changes for existing use. Review [typed extension settings](#typed-extension-settings). |
+| Upgrade an existing AIO instance that has no configured Site | Nothing changes for existing use. Review the [typed AIO upgrade](#typed-aio-upgrade). |
+| Run v1.0.0b8 content with an earlier Site Ops engine, or produce your own packages | Install the matching engine. Review the [typed map feature](#typed-map-feature). |
+| Write the YAML key `=` twice in one mapping, quoted or bare | Keep one. Review [repeated equals keys](#repeated-equals-keys). |
+| Match the text of a missing typed input error | Review [missing input messages](#missing-input-messages). |
+| Match the text of a template error from `plan` or `deploy` | Review [template error messages](#template-error-messages). |
 
 ### Windows user PATH
 
@@ -110,6 +116,80 @@ If your automation treats every diagnostic record as a failure, check
 your templates to show the occurrence count. The v1.0.0b7 renderer shows the
 same warnings as single records. See [warnings in results](run-output.md#read-warnings).
 
+### Typed extension settings
+
+This change is additive. `aio-install` accepts three optional typed inputs:
+`aioExtensionSettings`, `secretStoreExtensionSettings` and
+`certManagerExtensionSettings`. They write the existing Site parameters
+`aioConfigurationOverrides`, `secretStoreConfigurationOverrides` and
+`certManagerConfigurationOverrides`. Repeat `--input NAME=KEY=VALUE` once for
+each setting, or put the maps in the answer file. See
+[Arc extension settings](guided-inputs.md#set-arc-extension-settings).
+
+Existing Sites, overlays, `SITE_OVERRIDES`, parameter files and answer files
+work unchanged. Scalar `--input NAME=VALUE` answers keep their meaning,
+including values that contain `=`. Bundled AIO release files still set
+`certManagerConfigurationOverrides`, and Site keys still replace release
+keys one by one.
+
+### Typed AIO upgrade
+
+This change is additive. `aio-upgrade` accepts typed inputs for one existing
+instance: its resource ID, the required `aioRelease` and `enableCertManager`
+answers, the extension settings maps and optional labels. Runs with
+configured Sites and `--site-file` are unchanged. See
+[upgrade an existing instance](guided-inputs.md#upgrade-an-existing-instance).
+
+### Typed map feature
+
+The typed maps are additive for existing Sites and answers, and they need a
+Site Ops engine that supports the package feature `typed-input-maps/v1`. An
+earlier engine refuses a package that declares it, on every route, with
+`This package requires unsupported Site Ops features.` Install the Site Ops
+engine that the content release names. With a local checkout, typed routes on
+an earlier engine fail with `type must be string, boolean or azureResourceId`,
+while configured Sites and `--site-file` runs read no input contract.
+
+If you produce your own packages, add `typed-input-maps/v1` to
+`requiredFeatures`, or `--require-feature typed-input-maps/v1`, for a
+workspace whose input contract declares a `stringMap` input. The producer
+rejects such a workspace without it. See
+[workspace packages](workspace-packages.md#build-workspaces-declared-by-a-release).
+
+### Repeated equals keys
+
+YAML reads a bare `=` key and a quoted `"="` key as the same key. Site Ops
+now rejects a mapping that repeats it in any spelling, as it already rejects
+other repeated keys, with
+`found a duplicate key '='. YAML keeps the last one, so the first is discarded. Merge them or rename one.`
+Earlier releases kept only the last value. Keep the entry you intend and
+remove the other.
+
+### Missing input messages
+
+A missing required typed input now ends with the `--input` form that
+supplies it, for example:
+
+```text
+Missing required input 'siteName'. Supply `--input siteName=<value>`.
+```
+
+A boolean input shows `<true-or-false>` instead of `<value>`. The error code
+stays `inputs.invalid`, so match the code rather than the text.
+
+### Template error messages
+
+An error for a template that is unresolved, unsupported or malformed in a
+parameter value names the value's location and the supported syntax. It no
+longer repeats the value:
+
+```text
+Plan value at 'munich-dev.aio-instance.parameters.aioConfigurationOverrides.observability.metrics.exportIntervalSeconds' contains an unresolved or unsupported template. Write `{{ site.<field> }}` or `{{ steps.<step>.outputs.<name> }}` with one space inside each pair of braces, and name a field the Site sets. Remove `{{` from text that is not a template.
+```
+
+The error code stays `operation-preparation.invalid`, so match the code
+rather than the text.
+
 ## To v1.0.0b7
 
 These changes affect workspaces, scripts and pipelines that worked with

docs/workspace-packages.md

@@ -35,6 +35,7 @@ python scripts\build-workspace-package.py `
   --require-feature manifest/v1 `
   --require-feature composition/v1 `
   --require-feature manifest-selection/v1 `
+  --require-feature typed-input-maps/v1 `
   --include docs `
   --include README.md `
   --license LICENSE `
@@ -121,7 +122,7 @@ its own package, compatibility range and licensing files:
       "package": "iot-operations.zip",
       "compatibility": {
         "siteops": ">=1.0.0b1,<2",
-        "requiredFeatures": ["manifest/v1", "composition/v1", "manifest-selection/v1"]
+        "requiredFeatures": ["manifest/v1", "composition/v1", "manifest-selection/v1", "typed-input-maps/v1"]
       },
       "include": ["docs", "README.md"],
       "licenses": ["LICENSE", "ThirdPartyNotices.txt"]
@@ -181,7 +182,9 @@ file's byte limit. Package names are unique portable ZIP filenames and reserve
 room for their proof names. Workspace and companion paths must exist
 in the selected commit. License paths must identify regular files. `include`
 is optional, and omitted `requiredFeatures` defaults to `manifest/v1`.
-The producer also records `compiled-templates/v1`.
+The producer also records `compiled-templates/v1`. It rejects a workspace
+whose input contract declares a `stringMap` input unless `requiredFeatures`
+includes `typed-input-maps/v1`.
 
 If a workspace contains either generated index file, both must be present and
 current for that exact source. Production preserves the existing generic or
@@ -295,10 +298,11 @@ Each record contains `path`, `sha256` and `size`. Companion files outside the
 workspace affect the archive identity, not the workspace tree identity.
 The metadata file is excluded from its own payload inventory.
 
-Supported required features are `manifest/v1`, `composition/v1` and
-`manifest-selection/v1`. Package production also requires
-`compiled-templates/v1`. Unsupported required features and incompatible
-engine versions are rejected. Compatibility describes the declared engine
+Supported required features are `manifest/v1`, `composition/v1`,
+`manifest-selection/v1` and `typed-input-maps/v1`. Package production also
+requires `compiled-templates/v1`, and `typed-input-maps/v1` when an input
+contract declares a `stringMap` input. Unsupported required features and
+incompatible engine versions are rejected. Compatibility describes the declared engine
 contract, not deployment or workload qualification.
 
 ## Template mapping