Adds oci-javascript-mcp-server Kubernetes/Kata Isolation Provider by dustin-sale · Pull Request #431 · oracle/mcp

dustin-sale · 2026-09-03T16:38:10Z

Description

Extends the existing oci-javascript-mcp-server with a Kubernetes isolation provider while preserving Podman as the default. Provider and profile selection are trusted startup configuration, use exact accepted values, and fail closed without falling back to another runtime or credential source.

The Kubernetes provider includes:

Explicit local-development, in-cluster, and kata-in-cluster profiles behind a shared isolation-provider interface.
A fresh, credential-free Kubernetes pod for each JavaScript execution, connected to the trusted host over a bounded framed exec channel while OCI credentials and SDK clients remain on the host.
Fixed non-root pod security settings, disabled service-account token mounting and service links, bounded memory-backed temporary storage, and reviewed CPU, memory, and ephemeral-storage ranges.
Startup preflight checks for namespaces, exact RBAC permissions, admission-policy behavior, image digest pinning, and the Kata RuntimeClass and handler where applicable.
Fail-closed lifecycle handling with absolute deadlines, cancellation, bounded cleanup tails, concurrent channel shutdown and zero-grace pod deletion, and deletion confirmation.
A cleanup-only reconciler for expired managed pods with separately constrained permissions and per-candidate time bounds.
Hardened worker-channel validation and budgets for framing, RPC IDs, messages, logs, results, concurrency, egress, and transport backpressure.
Versioned standard Kubernetes and Kata manifests, container build assets, an OCI session-secret synchronization helper, local dry-run tooling, OpenSpec artifacts, deployment guidance, and security limitations.
Fake-API, provider, lifecycle, cancellation, reconciliation, hostile-channel, manifest, configuration, and optional real-cluster tests across all three profiles.

The motivation is to support cluster-managed execution and an optional Kata-backed deployment profile without weakening the server's trusted-host boundary or changing existing Podman deployments. The standard Kubernetes profiles provide container isolation only. The Kata profile is intentionally documented as a proof of concept and still requires deployment-specific runtime evidence and a current security review before it can be treated as a VM-grade boundary.

The implementation adds @kubernetes/client-node and its WebSocket type support. Kubernetes deployments require access to a compatible cluster, the documented namespaces and RBAC/admission/network controls, a digest-pinned runner image, and a reviewed Kata RuntimeClass for kata-in-cluster. The credential synchronization helper additionally requires Python 3 and an existing OCI CLI configuration. Podman remains the default and gains no new Kubernetes dependency at runtime. No downstream module changes are required.

Additional unit-test coverage identified and corrected four behavior defects:

Kubernetes readiness now requires an observed Running pod. Normal watch EOF
fails closed, and the initial readiness GET and watch both respect
cancellation and the absolute execution deadline.
OCI authentication selection now follows SDK profile inheritance, including
named profiles that inherit a DEFAULT security-token path and profiles that
explicitly override or clear that value.
Final JavaScript expression results are preserved when followed by comments,
with regression cases for strings, templates, regular expressions, postfix
division, and JavaScript line terminators.
discover_oci examples now represent required array fields as arrays,
including model arrays, while retaining bounded model expansion.

The suite also verifies concurrent RPC response correlation with reversed
replies and mixed success/failure outcomes, plus background reconciliation's
immediate execution, prevention of overlapping cycles, recovery after failure,
and idempotent stop behavior. These tests use fake APIs and controlled responses.
The RPC protocol and reconciliation shutdown contract are unchanged.

Type of change

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
This change requires a documentation update

How Has This Been Tested?

Run the following from src/oci-javascript-mcp-server:

npm run check — TypeScript validation passed.
npm run packcheck — npm package dry-run verification passed.
npm run check:kubernetes-manifests — all 14 standard and Kata Kubernetes manifest tests passed.
git diff --check 6633b602248bf44dbaf9aebe2e584c4a53622f1a...HEAD — passed with no whitespace errors.
npm run ci — 184 tests passed with 95.39% coverage

Additionally, I tested in both local-development and in-cluster kubernetes isolation provider profile modes.

Latest whole-server validation, run from the repository root:

moon run --no-actions oci-javascript-mcp-server:check oci-javascript-mcp-server:test
— native setup, protobuf compilation, TypeScript checking, and the c8 test
task passed.
326 tests passed, 6 skipped, 0 failed.
Aggregate coverage: 95.75% statements, 91.29% branches, 95.58% functions,
and 95.75% lines. All configured 90% coverage thresholds passed.
The four behavior fixes have regressions demonstrated failing before the
corrections and passing afterward. Additional review regressions cover
late readiness events and JavaScript source-preservation edge cases.
git diff --check passed.

--no-actions bypassed dependency setup/synchronization after npm dedupe
stalled; compilation, checking, tests, and coverage enforcement still ran.
These results validate the installed dependency environment. Fake API tests
do not establish real-cluster runtime or admission-policy behavior.

Test Configuration:

Firmware version: Not applicable
Hardware: Apple Silicon (arm64)
Toolchain: macOS 26.6.2; Node.js 22.14.0; npm 11.18.0; TypeScript 5.9.3
SDK: oci-sdk 2.132.x; @kubernetes/client-node 2.x; @modelcontextprotocol/sdk 1.29.x

Checklist:

My code follows the style guidelines of this project
I have performed a self-review of my own code
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation
My changes generate no new warnings
I have added tests that prove my fix is effective or that my feature works
New and existing unit tests pass locally with my changes
Any dependent changes have been merged and published in downstream modules

…cal development profiles

…r time

Resolve the Kubernetes isolation provider on the shared protobuf gRPC transport with mTLS and pod port-forwarding.

gebhardtr · 2026-10-09T15:20:02Z

Notes from the automated review:

It reintroduces runtime admission probing and “assurance” descriptors—the deployment-policy responsibility we previously moved out of the server. I’d keep those checks in deployment validation.
It carries gRPC through a Kubernetes port-forward tunnel, alongside an exec bootstrap channel. That preserves our RPC contract, but puts execution traffic through the Kubernetes control plane and adds tunnel lifecycle code. This deserves an explicit architecture decision.
Parser fixes, OCI profile inheritance changes, and native-install hardening should be separate contributions. They broaden review beyond Kubernetes support.
The provider factory eagerly imports Kubernetes dependencies even for Podman; loading them only when selected is a small, useful trim.

For 2, I'm thinking this is a bit more idiomatic Kube:

Create an execution-specific Secret containing only the runner’s TLS material.
Mount it read-only into that runner.
Start the runner normally; it reads the files and opens its gRPC listener.
Connect directly using mTLS, then clean up the pod and Secret afterward.

If we use Istio or Maistra, then we can mTLS for free.

…cript-k8s-isolation-provider # Conflicts: # src/oci-javascript-mcp-server/package-lock.json # src/oci-javascript-mcp-server/package.json

…issions

…vider

dustin-sale · 2026-10-19T14:45:49Z

@gebhardtr I have addressed items 1,2, and 4 from your prior comment.

Moved runtime admission policy checks to a separate deployment script.
Addressed the gRPC gaps:
Direct host-to-runner connections: The trusted host connects to each runner’s pod IP on TCP 50051, replacing exec bootstrap and port-forward tunnels. Workstation local-development keeps its tunnel path.
Per-execution mTLS Secrets: Each runner starts with a read-only TLS Secret containing its certificate/key and the host’s public certificate. OCI credentials and the host’s private key stay on the host.
Updated deployment controls: Host RBAC now grants Secret lifecycle operations instead of exec/port-forward access. Admission rules enforce the TLS mount, and NetworkPolicy permits gRPC ingress only from the trusted host.
Stronger cleanup and cancellation: Cleanup removes both the runner pod and TLS Secret, including orphaned Secrets. The latest tests verify cancellation after execution actually starts, and direct connections now support IPv6 runner addresses.
Provider factory now lazy loads the provider imports.

Signed-off-by: Dustin Sale <dustin.sale@oracle.com>

gebhardtr · 2026-11-04T16:34:01Z

+  }
+
+  async preflight(options: { startReconciliation?: boolean } = {}): Promise<void> {
+    this.#ready = false;


Need checks for namespace, identity, RBAC, admission behavior, RuntimeClass, and node-profile evidence

You requested that I move the admission probing out of the server in this comment, do I need to add it back?

gebhardtr · 2026-11-04T16:35:42Z

+    if (user.exec != null || user.authProvider != null) {
+      throw new ValidationInputError("Kubeconfig exec and auth-provider helpers are unsupported; use token or client-certificate credentials");
+    }
+    if (options.impersonate) {


This only sets user but groups are checked in https://github.com/oracle/mcp/pull/431/changes#diff-b1ef2b28e669d81493b73032a6be965ef2050f70d50b1d3968e26c0663b2bc26R247 (lines 247-255)

This relies on Kubernetes’ service-account impersonation behavior: when Impersonate-User names a service account and no Impersonate-Group headers are supplied, the API server derives its normal service-account groups and adds system:authenticated. See the upstream implementation.

The check below verifies the effective identity returned by SelfSubjectReview, including those groups, rather than assuming impersonation succeeded. Missing or unexpected groups fail validation.

I think the current approach is valid, but it deserves an explanatory comment and verification against our target Kubernetes release—the fake-API tests alone don’t establish that behavior.

gebhardtr · 2026-11-04T16:44:12Z

+        () => api.selfCan({ resource, subresource, verb, namespace: options.config.namespace }, signal),
+        passed => ({ passed, detail: "Required execution permission must be allowed" }))) return report;
+    }
+    const policy = runtimePolicyFor(options.config);


should we also have an exact Kata profile and a dedicated execution worker pool check here?

and does the policy validation here have to be code that checks individual properties? or do we just hash/version the policy yaml and verify the deployed policy and binding against that version?

dustin-sale added 5 commits August 25, 2026 12:11

initial kubernetes isolation provider with kata, standard k8s, and lo…

42f443f

…cal development profiles

fix: bound sandbox cleanup and disable OCI retries

f0210f3

adding openspec artifacts, will integrate it into full repo at a late…

42da490

…r time

harden kubernetes and rpc channel, update kubernetes examples

fe07508

sync and archive harden-kubernetes-and-rpc-channel openspec change

c14853e

oracle-contributor-agreement Bot added the OCA Verified All contributors have signed the Oracle Contributor Agreement. label Sep 3, 2026

dustin-sale changed the title ~~Dustin sale/oci javascript k8s isolation provider~~ Adds oci-javascript-mcp-server Kubernetes/Kata Isolation Provider Sep 3, 2026

dustin-sale force-pushed the dustin-sale/oci-javascript-k8s-isolation-provider branch 2 times, most recently from a5b46e4 to 0fa9f5b Compare September 3, 2026 19:43

unit test fixes and expanded coverage

a652aab

dustin-sale force-pushed the dustin-sale/oci-javascript-k8s-isolation-provider branch from 0fa9f5b to a652aab Compare September 3, 2026 19:52

updated continerfiles to use ol9 base images

e576b6d

dustin-sale force-pushed the dustin-sale/oci-javascript-k8s-isolation-provider branch from e576b6d to 2f92241 Compare September 4, 2026 14:39

dustin-sale marked this pull request as ready for review September 4, 2026 18:21

dustin-sale requested review from AlaaShaker, gebhardtr and krisrice as code owners September 4, 2026 18:21

dustin-sale marked this pull request as draft September 4, 2026 19:05

dustin-sale marked this pull request as ready for review September 4, 2026 20:09

dustin-sale force-pushed the dustin-sale/oci-javascript-k8s-isolation-provider branch from 2f92241 to 831ae23 Compare September 16, 2026 13:03

dustin-sale marked this pull request as draft September 30, 2026 13:24

dustin-sale force-pushed the dustin-sale/oci-javascript-k8s-isolation-provider branch 3 times, most recently from b7aebd3 to d5f71a4 Compare September 30, 2026 16:49

Merge origin/main into dustin-sale/oci-javascript-k8s-isolation-provider

055ac40

Resolve the Kubernetes isolation provider on the shared protobuf gRPC transport with mTLS and pod port-forwarding.

dustin-sale force-pushed the dustin-sale/oci-javascript-k8s-isolation-provider branch from d5f71a4 to 055ac40 Compare September 30, 2026 17:14

dustin-sale added 4 commits October 1, 2026 08:20

initial updates for k8s isolation provider and gRPC handling

da8eb7b

resolves a handful of findings from a local review

c5811db

updates to containerfiles for smoother builds

f225817

Merge origin/main into dustin-sale/oci-javascript-k8s-isolation-provider

7abd65f

addressing PR comments

a6e07b5

dustin-sale added 13 commits October 9, 2026 12:30

Merge remote-tracking branch 'origin/main' into dustin-sale/oci-javas…

b0ad446

…cript-k8s-isolation-provider # Conflicts: # src/oci-javascript-mcp-server/package-lock.json # src/oci-javascript-mcp-server/package.json

updated agent context

fba4dca

lazy load isolation provider adapters

8771845

creates deployment validation script

968ee18

moves k8s policy validation out of server startup

f68536f

feat: support fixed TLS file bootstrap for runners

57b730b

feat: model execution TLS Secrets and direct pod endpoints

2164bef

feat: use direct execution-scoped mTLS for in-cluster runners

116e008

feat: reconcile execution Secrets and preflight direct transport perm…

4f9f0db

…issions

feat: constrain direct runner networking and TLS mounts

b1ef50f

docs: document direct Kubernetes gRPC deployment and validation

e786d99

fix: support IPv6 runners and validate running cancellation

ae850f6

Merge branch 'main' into dustin-sale/oci-javascript-k8s-isolation-pro…

e9ae1fd

…vider

updates local-in-cluster.yaml with new image shas

7db9790

This was referenced Nov 2, 2026

fix(oci-javascript): use supported Podman network cleanup #544

Open

fix(oci-javascript): bound Podman cleanup and await process exit #547

Open

Merge origin/main into dustin-sale/oci-javascript-k8s-isolation-provider

aa81ea8

Signed-off-by: Dustin Sale <dustin.sale@oracle.com>

dustin-sale requested review from irfan-ahmed and robander as code owners November 3, 2026 21:14

gebhardtr reviewed Nov 4, 2026

View reviewed changes

Comment thread src/oci-javascript-mcp-server/examples/kata-kubernetes/v1/06-admission-policy.yaml Resolved

gebhardtr reviewed Nov 4, 2026

View reviewed changes

Comment thread src/oci-javascript-mcp-server/examples/kata-kubernetes/v1/05-runtime-class.yaml Resolved

dustin-sale added 3 commits November 4, 2026 13:41

updated kata example and kata manifest tests

f199ee8

adds explicit deployment property checks

02930e0

Merge origin/main into dustin-sale/oci-javascript-k8s-isolation-provider

8c15d06

Navigation Menu

Repository navigation

Adds oci-javascript-mcp-server Kubernetes/Kata Isolation Provider - #431

Adds oci-javascript-mcp-server Kubernetes/Kata Isolation Provider#431
dustin-sale wants to merge 33 commits into
oracle:mainfrom
gebhardtr:dustin-sale/oci-javascript-k8s-isolation-provider

dustin-sale commented Sep 3, 2026 •

edited

Loading

Uh oh!

gebhardtr commented Oct 9, 2026 •

edited

Loading

Uh oh!

dustin-sale commented Oct 19, 2026

Uh oh!

Uh oh!

gebhardtr Nov 4, 2026

Uh oh!

dustin-sale Nov 4, 2026 •

edited

Loading

Uh oh!

gebhardtr Nov 4, 2026

Uh oh!

dustin-sale Nov 4, 2026

Uh oh!

gebhardtr Nov 4, 2026 •

edited

Loading

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

dustin-sale commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

How Has This Been Tested?

Checklist:

Uh oh!

gebhardtr commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dustin-sale commented Oct 19, 2026

Uh oh!

Uh oh!

gebhardtr Nov 4, 2026

Choose a reason for hiding this comment

Uh oh!

dustin-sale Nov 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gebhardtr Nov 4, 2026

Choose a reason for hiding this comment

Uh oh!

dustin-sale Nov 4, 2026

Choose a reason for hiding this comment

Uh oh!

gebhardtr Nov 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dustin-sale commented Sep 3, 2026 •

edited

Loading

gebhardtr commented Oct 9, 2026 •

edited

Loading

dustin-sale Nov 4, 2026 •

edited

Loading

gebhardtr Nov 4, 2026 •

edited

Loading