Skip to content

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

Closed
Mitch Denny (mitchdenny) wants to merge 1 commit into
mitchdenny-backport-17-0-03-pr21288from
mitchdenny-backport-17-0-04-pr21824
Closed

Mitch Denny (mitchdenny) wants to merge 1 commit into
mitchdenny-backport-17-0-03-pr21288from
mitchdenny-backport-17-0-04-pr21824

Conversation

@mitchdenny

Copy link
Copy Markdown
Member

Description

Backport of #21824 to release/17.0 (cherry-picked from dea22b1 with no modifications). Layer 4 of 55 in the release/17.0 backport stack; stacked on #22000.

Backport recommendation: Yes — Polyglot Kubernetes WithField could not take nested values; small API-shape fix (17.0 milestone).

Backport of #21824

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

## 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

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 7652d12.

@mitchdenny
Mitch Denny (mitchdenny) marked this pull request as ready for review November 10, 2026 04:10
@mitchdenny

Copy link
Copy Markdown
Member Author

Approved for inclusion in release/17.0. Do not merge yet.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

Jose Perez Rodriguez (joperezr) pushed a commit that referenced this pull request Nov 11, 2026
)

## 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

```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" }
        }]
    }]);
});
```

### 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
dea22b1^
dea22b1 | 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?
  - [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

## 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.

Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants