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.

…vider

gebhardtr · 2026-10-08T20:04:03Z

+  async deletePod(namespace: string, name: string, signal?: AbortSignal): Promise<void> {
+    try {
+      await this.#core.deleteNamespacedPod(
+        { name, namespace, gracePeriodSeconds: 0 },


nit: could this leave stuff running if the delete fails?

Yes, a failed DELETE can leave the pod present. Non-404 errors propagate and cause cleanup to fail; pod active deadlines and expiry reconciliation provide additional cleanup attempts.

I've clarified the README and architecture guide that zero-grace deletion and API NotFound confirm object removal, not that the process has stopped on its node. The safeguards depend on kubelet/control-plane availability and cannot prove termination during a node outage.

gebhardtr · 2026-10-08T20:07:13Z

+      timeout.unref();
+      void this.#watch.watch(
+        `/api/v1/namespaces/${encodeURIComponent(namespace)}/pods`,
+        { fieldSelector: `metadata.name=${name}` },


if a delete happens between the get and the watch, the watch can miss it and report a failure. you can connect them through resourceVersion.

gebhardtr · 2026-10-08T20:12:16Z

+          accepted?.destroy();
+          closeWebSocket(websocket);
+          await closeServer(server);
+          finish();


this resolves closed before the websocket close is confirmed.

Fixed. The deletion watch now starts from the resource version observed by the initial GET, closing that gap.

Expired watch versions trigger a fresh read and a filtered LIST to obtain the current collection version—a GET alone can still return the pod's old, compacted version. Recovery stays within the original deadline.

Added regressions for deletion between GET and watch establishment, compaction recovery with an unchanged pod version, repeated expiry, and cancellation during recovery.

gebhardtr · 2026-10-08T20:13:38Z

+  candidateTimeoutMs = 5_000
+): Promise<ReconciliationSummary> {
+  const summary: ReconciliationSummary = { deletedNames: [], failureCount: 0 };
+  const pods = await api.listManagedPods(namespace, profile);


this happens before deadline enforcement so it can hang reconciliation.

Fixed. Tunnel cleanup now waits for actual WebSocket closure separately from the execution outcome. Closing the local TCP socket or receiving a transport error no longer satisfies that cleanup wait.

The wait includes forwarding handles acquired after shutdown begins and remains bounded by the existing cleanup deadline. Added regressions for a WebSocket held in CLOSING, closure timeout, errors before closure, and late acquisition. A provider-level test also verifies that pod deletion proceeds while tunnel closure is stuck.

gebhardtr · 2026-10-08T20:22:42Z

+}
+
+if (
+  process.argv[1]


what's this for?

This is the direct-execution guard. It starts the server when invoked as the entry point while allowing tests to import startServer() and inject fake providers without automatically starting another server. realpathSync() makes the comparison work through symlinks, including npm executable links.

In short, it allows unit tests to import the server without starting it.

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

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

dustin-sale added 2 commits October 2, 2026 08:05

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

48281cc

…vider

fix(oci-javascript): close unit test gaps and correct runtime edge cases

75c1718

dustin-sale marked this pull request as ready for review October 2, 2026 17:16

gebhardtr reviewed Oct 8, 2026

View reviewed changes

addressing PR comments

a6e07b5

dustin-sale added 3 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

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 18 commits into
oracle:mainfrom
gebhardtr:dustin-sale/oci-javascript-k8s-isolation-provider

dustin-sale commented Sep 3, 2026 •

edited

Loading

Uh oh!

gebhardtr Oct 8, 2026

Uh oh!

dustin-sale Oct 8, 2026

Uh oh!

gebhardtr Oct 8, 2026

Uh oh!

gebhardtr Oct 8, 2026

Uh oh!

dustin-sale Oct 8, 2026

Uh oh!

gebhardtr Oct 8, 2026

Uh oh!

dustin-sale Oct 8, 2026

Uh oh!

gebhardtr Oct 8, 2026

Uh oh!

dustin-sale Oct 8, 2026

Uh oh!

dustin-sale Oct 8, 2026

Uh oh!

gebhardtr commented Oct 9, 2026 •

edited

Loading

Uh oh!

This branch has not been deployed

Reviewers

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dustin-sale commented Sep 3, 2026 •

edited

Loading

gebhardtr commented Oct 9, 2026 •

edited

Loading