Skip to content

[release/17.0] Allow structured Kubernetes manifest field values - #22107

Merged
Jose Perez Rodriguez (joperezr) merged 1 commit into
release/17.0from
ievangelist-kubernetes-fields-backport
Nov 11, 2026
Merged

Jose Perez Rodriguez (joperezr) merged 1 commit into
release/17.0from
ievangelist-kubernetes-fields-backport

Conversation

@IEvangelist

@IEvangelist David Pine (IEvangelist) commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

Description

Backport of #21824 to release/17.0.

Polyglot AppHosts can author custom Kubernetes manifests with nested objects and arrays, including CiliumNetworkPolicy ingress rules and selectors whose label keys contain dots and slashes. JSON numbers receive the same finite/range checks as CLR numeric values, including inside nested structures. Dot-separated paths and last-write-wins behavior are unchanged; no public CLR API is added.

This standalone backport applies the final merged squash commit dea22b13453b1703ace03f23c06bfd013017edb6, not the original multi-commit patch history. It applied cleanly to release tip cec195f2d0bf3f1d714badf74f205fa855fdf963 without conflict resolution or adaptations. It does not depend on or modify the abandoned stacked backports, including #22001.

Relates to #18080; this addresses structured manifest values only and does not close the umbrella issue.

User-facing usage

await api.publishAsKubernetesService(async (service) => {
    const policy = await service.addManifest("cilium.io/v2", "CiliumNetworkPolicy", "api-netpol");
    await policy.withField("spec.endpointSelector.matchLabels", {
        "app.kubernetes.io/component": "api"
    });
    await policy.withField("spec.ingress", [{
        fromEndpoints: [{
            matchLabels: { "app.kubernetes.io/component": "frontend" }
        }]
    }]);
});

Validation

Run against this release-branch backport on Windows:

  • .\restore.cmd - passed (0 errors, 18 NuGet vulnerability warnings).
  • dotnet test --project tests\Aspire.Hosting.RemoteHost.Tests\Aspire.Hosting.RemoteHost.Tests.csproj --no-launch-profile -- --filter-class "*.KubernetesManifestTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true" - passed, 13 tests; 0 failed/skipped.
  • dotnet test --project tests\Aspire.Hosting.Kubernetes.Tests\Aspire.Hosting.Kubernetes.Tests.csproj --no-launch-profile -- --filter-class "*.KubernetesPublisherTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true" - passed, 115 tests; 0 failed/skipped.
  • git diff --check HEAD^ HEAD - passed.
  • git diff HEAD^ HEAD | git patch-id --stable and git diff dea22b13453b1703ace03f23c06bfd013017edb6^ dea22b13453b1703ace03f23c06bfd013017edb6 | git patch-id --stable - passed equivalence check: both patch IDs are 26cc4688082766ec12213ef758509ce1b4153169.
  • git diff --exit-code and git status --short - passed/clean after tests; no snapshot changes accepted.

No local build/test blockers. Live AppHosts, Helm rendering, and Kubernetes/Cilium deployment were not rerun for this backport; CI was pending when the PR was created. The added test dependency is an explicit MSBuild project reference, with tests and snapshots in their owning project; no test-selection map changes are required.

Checklist

  • Is this feature complete?
    • Yes. Ready to ship.
    • No. Follow-up changes expected.
  • Are you including unit tests for the changes and scenario tests if relevant?
    • Yes
    • No
  • Did you add public API?
    • Yes
      • If yes, did you have an API Review for it?
        • Yes
        • No
      • Did you add <remarks /> and <code /> elements on your triple slash comments?
        • Yes
        • No
    • No
  • Does the change make any security assumptions or guarantees?
    • Yes
      • If yes, have you done a threat model and had a security review?
        • Yes
        • No
    • No

Customer Impact

Polyglot AppHosts, including Go, cannot author Kubernetes custom-resource fields containing nested objects or arrays, blocking scenarios such as CiliumNetworkPolicy rules and dotted/slashed label keys.

Testing

On this release-branch backport, KubernetesManifestTests passed 13 tests and KubernetesPublisherTests passed 115 tests. The patch exactly matches the merged source, with no snapshot updates. Exact commands and results are recorded above.

Risk

Low. Localized manifest-value handling with unchanged CLR signature, capability ID, field paths, and replacement behavior.

Regression?

Unknown. The source PR does not establish a regression.

## Description

Polyglot AppHosts can now author custom Kubernetes manifests with nested
objects and arrays, including CiliumNetworkPolicy ingress rules and
selectors whose label keys contain dots and slashes.

Remove the scalar-only `AspireUnion` restriction from
`KubernetesManifestResource.WithField`. The CLR signature remains
`WithField(string, object)` and the existing normalization/YAML paths
handle the structured values. JSON numbers now use the same finite/range
checks as CLR numeric values, including inside nested objects and
arrays.

Dot-separated paths and last-write-wins replacement are unchanged.
Supply dotted keys inside a map subtree rather than adding path escape
syntax. Manifest metadata still uses dedicated APIs.

Part of #18080: addresses the remaining structured-manifest limitation
(bug 2). The Go Configure callback panic and integer union handling (bug
1) were already fixed by merged #21188 and are not changed here.

### User-facing usage

```typescript
await api.publishAsKubernetesService(async (service) => {
    const policy = await service.addManifest("cilium.io/v2", "CiliumNetworkPolicy", "api-netpol");
    await policy.withField("spec.endpointSelector.matchLabels", {
        "app.kubernetes.io/component": "api"
    });
    await policy.withField("spec.ingress", [{
        fromEndpoints: [{
            matchLabels: { "app.kubernetes.io/component": "frontend" }
        }]
    }]);
});
```

C# AppHosts continue to use `AdditionalResources` with a
`BaseKubernetesResource` subclass for typed custom resources; no public
CLR API is added.

### Generated SDK compatibility

Focused snapshots cover the real Kubernetes capability in all five
generators: Go `any` without the scalar union guard, TypeScript `any`,
Python `typing.Any`, Java `Object`, and Rust `&Value`. Java's transport
still unwraps existing `AspireUnion` arguments, so existing source calls
remain usable after regeneration. The CLR signature and capability ID
are unchanged. No generator implementation, shared runtime, or release
API baseline files are edited.

### Validation

- `.\restore.cmd` - passed; repository-wide restore reported 17 NuGet
vulnerability warnings.
- `dotnet test --project
tests\Aspire.Hosting.RemoteHost.Tests\Aspire.Hosting.RemoteHost.Tests.csproj
--no-launch-profile -- --filter-class "*.KubernetesManifestTests"
--filter-class "*.CapabilityDispatcherTests" --filter-class
"*.AtsMarshallerTests" --filter-not-trait "quarantined=true"
--filter-not-trait "outerloop=true"` - passed, 278 tests.
- `dotnet test --project
tests\Aspire.Hosting.RemoteHost.Tests\Aspire.Hosting.RemoteHost.Tests.csproj
--no-launch-profile -- --filter-class "*.KubernetesManifestTests"
--filter-not-trait "quarantined=true" --filter-not-trait
"outerloop=true"` - passed, 10 tests after normalizing trailing
whitespace in generated snapshots.
- `dotnet test --project
tests\Aspire.Hosting.Kubernetes.Tests\Aspire.Hosting.Kubernetes.Tests.csproj
--no-launch-profile -- --filter-class "*.KubernetesPublisherTests"
--filter-not-trait "quarantined=true" --filter-not-trait
"outerloop=true"` - passed, 74 tests.
- `dotnet test --project
tests\Aspire.Hosting.RemoteHost.Tests\Aspire.Hosting.RemoteHost.Tests.csproj
--no-launch-profile -- --filter-method
"*.WithField_DispatchesStructuredValuesToPublishedYaml"
--filter-not-trait "quarantined=true" --filter-not-trait
"outerloop=true"` with the original scalar union temporarily restored -
failed as expected with `requires handle of type 'String | Double |
Boolean', got 'object'`. The fix was restored before the passing runs.
- `git diff --check` - passed.

The behavioral test dispatches real `addManifest`/`withField`
capabilities through publishing and snapshots CiliumNetworkPolicy YAML:
arrays of objects, dotted/slashed keys, empty arrays, booleans,
replacement semantics, and fluent return identity. Rejection tests cover
resource handles, nested non-finite JSON numbers, invalid dictionary
keys, unsupported CLR objects, and non-finite CLR numbers, including
preservation of existing fields on failure.

Evaluated MSBuild items/project references represent the new tests,
snapshots, shared initializer, and Kubernetes dependency; no loose-input
routing or workflow changes are needed.

### Live Go Preview validation

Used the Linux x64 CLI archive and portable `built-nugets` from [CI run
42116251464](https://github.com/microsoft/aspire/actions/runs/42116251464),
both matching head `3603a49c38bd7de8336c971cc16352992ffe4669`. CLI
version: `17.0.0-pr.21824.g3603a49c`. Ran in the existing
`aspire-go-e2e-6972:latest` Docker image with Go `1.26.10`, GCC
`13.3.0`, and a live Docker engine `29.9.2`. No repository fixtures or
shared Go runtime files were changed.

Exact commands inside the container (all passed):

```bash
/state/pr-cli/aspire new aspire-go-empty --name ManifestPreview --output /workspace/live-manifest --version 17.0.0-pr.21824.g3603a49c --source /workspace/portable-packages/Debug/Shipping --localhost-tld false --suppress-agent-init --use-config-source false --non-interactive
# Added Aspire.Hosting.Kubernetes 17.0.0-pr.21824.g3603a49c to the scratch aspire.config.json.
cd /workspace/live-manifest
/state/pr-cli/aspire restore --apphost apphost.go --non-interactive
go build ./...
(cd .aspire/modules && go build ./...)
/state/pr-cli/aspire publish --apphost apphost.go --output-path /workspace/published --non-interactive --include-exception-details
python3 /workspace/verify-output.py
```

The compile covers the complete generated Go module, not only the
focused projection snapshot. Its generated `WithField(path string, value
any)` accepts native Go maps/slices. The scratch AppHost uses
`PublishAsKubernetesService` and the `AddManifest` Configure callback to
author a CiliumNetworkPolicy. Publishing succeeded with **10/10 pipeline
steps**; a complete-output equality assertion verified
`templates/api/policy.yaml`, including nested endpoint/port arrays,
`app.kubernetes.io/component` and `app.kubernetes.io/name` keys,
`egress: []`, `ingress: true`, and integer `revision: 3`.

The initial attempt without explicit version/source selected stable
`13.6.4` and failed because `Aspire.Hosting.Go` has no matching stable
package; the successful run above uses explicit matching PR artifacts.
This does not claim default stable Go scaffolding is validated.

Not run: live TypeScript/Python/Java/Rust AppHosts or generated SDK
compilation in those languages, Helm rendering, or deployment to a
Kubernetes/Cilium cluster. Negative-value coverage remains the automated
production dispatch/CLR tests, not live Go rejection scenarios.
Callback-release and disconnect/`os.Exit` lifecycle redesigns are
outside this change and this validation makes no new lifecycle
guarantees.

## Checklist

- Is this feature complete?
  - [x] Yes. Ready to ship.
  - [ ] No. Follow-up changes expected.
- Are you including unit tests for the changes and scenario tests if
relevant?
  - [x] Yes
  - [ ] No
- Did you add public API?
  - [ ] Yes
    - If yes, did you have an API Review for it?
      - [ ] Yes
      - [ ] No
- Did you add `<remarks />` and `<code />` elements on your triple slash
comments?
      - [ ] Yes
      - [ ] No
  - [x] No
- Does the change make any security assumptions or guarantees?
  - [ ] Yes
    - If yes, have you done a threat model and had a security review?
      - [ ] Yes
      - [ ] No
  - [x] No

Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
(cherry picked from commit dea22b1)
@github-actions

Copy link
Copy Markdown
Contributor

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 22107

Or

  • Run remotely in PowerShell:
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 22107"

@aspire-repo-bot
aspire-repo-bot Bot requested a balanced review from Copilot November 10, 2026 22:02
@github-actions github-actions Bot added the needs-area-label An area label is needed to ensure this gets routed to the appropriate area owners label Nov 10, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Tests selector

7 / 101 PR test projects · 2 PR jobs, from 10 changed files.

Selected PR test projects (7 / 101)

Aspire.Cli.EndToEnd.Tests, Aspire.Hosting.Azure.Kubernetes.Tests, Aspire.Hosting.CodeGeneration.Python.Tests, Aspire.Hosting.CodeGeneration.TypeScript.Tests, Aspire.Hosting.Docker.Tests, Aspire.Hosting.Kubernetes.Tests, Aspire.Hosting.RemoteHost.Tests

Selected PR jobs (2)

polyglot, typescript-api-compat


How these were chosen — grouped by what changed

🔧 src/Aspire.Hosting.Kubernetes/KubernetesManifestResource.cs (changed source)
→ 1 directly: Aspire.Hosting.Kubernetes.Tests
→ 4 via the project graph: Aspire.Hosting.Azure.Kubernetes.Tests (2 hops), Aspire.Hosting.CodeGeneration.Python.Tests (2 hops), Aspire.Hosting.CodeGeneration.TypeScript.Tests, Aspire.Hosting.Docker.Tests

📦 affected project Aspire.Hosting.Kubernetes
→ 1 test: Aspire.Cli.EndToEnd.Tests

🧪 tests/Aspire.Hosting.Kubernetes.Tests/KubernetesPublisherTests.cs (changed test)
→ 1 directly: Aspire.Hosting.Kubernetes.Tests

🧪 tests/Aspire.Hosting.RemoteHost.Tests/Aspire.Hosting.RemoteHost.Tests.csproj (changed test)
→ 1 directly: Aspire.Hosting.RemoteHost.Tests

🧪 tests/Aspire.Hosting.RemoteHost.Tests/KubernetesManifestTests.cs (changed test)
→ 1 directly: Aspire.Hosting.RemoteHost.Tests

🧪 tests/Aspire.Hosting.RemoteHost.Tests/Snapshots/KubernetesManifestTests.WithField_DispatchesStructuredValuesToPublishedYaml.verified.yaml (changed test)
→ 1 directly: Aspire.Hosting.RemoteHost.Tests

🧪 tests/Aspire.Hosting.RemoteHost.Tests/Snapshots/KubernetesManifestTests.WithField_GeneratedSdkAcceptsStructuredValues_language=Go.verified.go (changed test)
→ 1 directly: Aspire.Hosting.RemoteHost.Tests

🧪 tests/Aspire.Hosting.RemoteHost.Tests/Snapshots/KubernetesManifestTests.WithField_GeneratedSdkAcceptsStructuredValues_language=Java.verified.java (changed test)
→ 1 directly: Aspire.Hosting.RemoteHost.Tests

🧪 tests/Aspire.Hosting.RemoteHost.Tests/Snapshots/KubernetesManifestTests.WithField_GeneratedSdkAcceptsStructuredValues_language=Python.verified.py (changed test)
→ 1 directly: Aspire.Hosting.RemoteHost.Tests

🧪 tests/Aspire.Hosting.RemoteHost.Tests/Snapshots/KubernetesManifestTests.WithField_GeneratedSdkAcceptsStructuredValues_language=Rust.verified.rs (changed test)
→ 1 directly: Aspire.Hosting.RemoteHost.Tests

🧪 tests/Aspire.Hosting.RemoteHost.Tests/Snapshots/KubernetesManifestTests.WithField_GeneratedSdkAcceptsStructuredValues_language=TypeScript.verified.ts (changed test)
→ 1 directly: Aspire.Hosting.RemoteHost.Tests

Job reasons

Job Triggered by
polyglot • affected project Aspire.Hosting.Kubernetes
• affected project Aspire.Hosting.Azure.Provisioning.ContainerService
typescript-api-compat affected project Aspire.Hosting.Kubernetes

Selection computed for commit 705fa69.

Copilot AI left a comment

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.

🟢 Approval recommended

No active review issues remain for the change enabling nested Kubernetes manifest values in polyglot AppHosts.

No open issues 🎉

What changed in this PR

Backports #21824 to release/17.0, enabling polyglot AppHosts to define nested Kubernetes manifest values. This addresses the structured-value limitation in #18080 without adding a public CLR API or changing dot-separated paths and last-write-wins behavior.

Changes:

  • Allows objects and arrays in WithField, preserving dotted label keys within supplied objects.
  • Applies numeric validation to nested JSON values and rejects resource handles.
  • Adds dispatch, YAML, and five-language SDK snapshot coverage, plus usage documentation.
File Description
tests/​Aspire.Hosting.RemoteHost.Tests/​Snapshots/​KubernetesManifestTests.WithField_GeneratedSdkAcceptsStructuredValues_language=TypeScript.verified.ts Captures the TypeScript any parameter.
tests/​Aspire.Hosting.RemoteHost.Tests/​Snapshots/​KubernetesManifestTests.WithField_GeneratedSdkAcceptsStructuredValues_language=Rust.verified.rs Captures the Rust &Value parameter.
tests/​Aspire.Hosting.RemoteHost.Tests/​Snapshots/​KubernetesManifestTests.WithField_GeneratedSdkAcceptsStructuredValues_language=Python.verified.py Captures the Python typing.Any parameter.
tests/​Aspire.Hosting.RemoteHost.Tests/​Snapshots/​KubernetesManifestTests.WithField_GeneratedSdkAcceptsStructuredValues_language=Java.verified.java Captures the Java Object parameter.
tests/​Aspire.Hosting.RemoteHost.Tests/​Snapshots/​KubernetesManifestTests.WithField_GeneratedSdkAcceptsStructuredValues_language=Go.verified.go Captures Go structured-value support without the scalar guard.
tests/​Aspire.Hosting.RemoteHost.Tests/​Snapshots/​KubernetesManifestTests.WithField_DispatchesStructuredValuesToPublishedYaml.verified.yaml Records nested CiliumNetworkPolicy YAML output.
tests/​Aspire.Hosting.RemoteHost.Tests/​KubernetesManifestTests.cs Tests dispatch, validation, replacement, and generated SDK signatures.
tests/​Aspire.Hosting.RemoteHost.Tests/​Aspire.Hosting.RemoteHost.Tests.csproj Adds Kubernetes and snapshot-testing dependencies.
tests/​Aspire.Hosting.Kubernetes.Tests/​KubernetesPublisherTests.cs Tests invalid-value rejection and preservation of existing fields.
src/​Aspire.Hosting.Kubernetes/​README.md Documents structured custom manifests and supported values.
src/​Aspire.Hosting.Kubernetes/​KubernetesManifestResource.cs Removes the scalar restriction and strengthens JSON value validation.

Review effort: Balanced

@joperezr
Jose Perez Rodriguez (joperezr) merged commit 4bd95b2 into release/17.0 Nov 11, 2026
184 checks passed
@aspire-repo-bot

Copy link
Copy Markdown
Contributor

✅ No documentation update needed.

excluded → base_branch_is_release, title_release_prefix, body_backport_marker. This is a backport of #21824 to release/17.0; docs belong with the original forward PR. Triggered signals: integration_readme_changed, pr_body_has_cli_flag_mention, pr_body_has_security_marker, pr_body_has_user_facing_section.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-area-label An area label is needed to ensure this gets routed to the appropriate area owners

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants