Feature: Add Kubernetes Multi-Cloud Service Discovery Plugin

[tnaum-ms]

Add Kubernetes Multi-Cloud Service Discovery Plugin

Background

DocumentDB for VS Code includes an open Service Discovery architecture that allows plugins to authenticate with a vendor environment, navigate its resource hierarchy, discover database services, and surface connection strings back to the extension. Today, the available plugins target Azure-hosted environments:

• Azure Cosmos DB for MongoDB (RU)
• Azure DocumentDB (vCore)
• Azure VMs (DocumentDB)

A fourth plugin for MongoDB Atlas discovery is in progress (see #531).

This issue proposes a new Kubernetes Service Discovery plugin so users running DocumentDB-compatible databases on Kubernetes — regardless of cloud or cluster provider — can discover and connect to them without manually copying connection strings or service endpoints. The plugin works with any reachable Kubernetes cluster: AKS, EKS, GKE, OpenShift, on-premises, local (minikube, kind, k3s), and any other conformant distribution.

Prior Work

There is no Kubernetes-specific code in the extension today. The Kubernetes API access layer does not exist yet and is out of scope for this issue. It will need to be introduced as part of this work, relying on an external Kubernetes client library (e.g., @kubernetes/client-node) rather than anything built into the extension.

This issue therefore covers:

1. Selecting and integrating an appropriate external Kubernetes client package.
2. Building the Discovery View integration, user-facing wizards, and tree view experience on top of it.

⚠️ Dependency footprint is a first-class concern. See Extension Size & Memory Impact below.

Goal

Users should be able to:

1. Enable the Kubernetes plugin from the Service Discovery panel, the same way they enable existing providers.
2. Authenticate via the Manage Credentials entry point. The user selects one or more kubeconfig contexts (local file or pasted kubeconfig YAML), each representing a cluster. Credentials are stored securely in VS Code's secret storage.
3. Browse their Kubernetes estate in the Discovery tree view — Contexts (clusters), Namespaces, and individual Service resources that expose a DocumentDB-compatible port — with cluster provider, namespace, and service type (ClusterIP / LoadBalancer / NodePort) visible at a glance.
4. Filter visible resources via the Filter entry point to narrow which contexts and/or namespaces appear, mirroring how Azure plugins filter by tenant and subscription.
5. Select a service to have its connection endpoint resolved and added to the Connections view.

UX Expectations

• Follow the same UX patterns established by existing plugins — use the existing service discovery plugin infrastructure, including the DiscoveryProvider registration, the Manage Credentials entry point, and the Filter entry point.
• Credential management wizard should let users:
  • Enable or disable kubeconfig contexts from ~/.kube/config or a custom path — rather than importing or copying credentials, the wizard could simply present all contexts discovered in the user's kubeconfig file(s) and let them toggle which ones the extension should monitor. This is worth exploring as the primary flow since kubeconfig is already the standard Kubernetes credential store; the UX question is how to surface the concept of "showing a context in DocumentDB" without asking users to paste or re-enter anything.
  • Name or alias each enabled context for display in the tree (the raw kubeconfig context name is often opaque).
  • Remove or disable previously enabled contexts.
  • Unlike Azure plugins (which delegate to the VS Code Azure account), this plugin surfaces the user's existing kubeconfig material — the UX should make that clear and guide users who do not yet have a kubeconfig set up.
• Filter wizard should let users scope which kubeconfig contexts and namespaces are visible in the tree, similar to how Azure plugins filter by tenant / subscription.
• Tree items should have the same affordances as existing plugins: refresh, retry on error, learn more link.
• See Managing Azure Discovery (docs/user-manual/managing-azure-discovery.md) for the credential and filter UX to use as inspiration..

Proposed Tree Structure

Kubernetes Discovery (root)
└── context: my-aks-cluster (AKS / eastus)
    ├── namespace: default
    │   ├── svc: documentdb-primary  [LoadBalancer :27017]
    │   └── svc: documentdb-replica  [ClusterIP :27017]
    └── namespace: staging
        └── svc: documentdb-staging  [NodePort :30017]
└── context: local-kind (kind / localhost)
    └── namespace: dev
        └── svc: mongo-dev  [ClusterIP :27017]

Connection String Resolution

The exact strategy for each service type, and the port-forward lifecycle, should be confirmed during implementation (see "Exploration Needed" below).

Exploration Needed

The following questions should be investigated as part of this work:

• Kubernetes client library selection — Evaluate @kubernetes/client-node and any lighter alternatives. Consider bundle size, tree-shakeability, in-cluster vs. out-of-cluster support, and maintenance status.
• Service discovery heuristics — How should the plugin decide which Service objects are DocumentDB-compatible? Options: user-defined label selectors, or an annotation convention (e.g., documentdb.vscode.extension/discovery: "true")?
• Multi-kubeconfig sources — Beyond ~/.kube/config, should the plugin support in-cluster service accounts (for users running VS Code inside a pod), or KUBECONFIG environment variable paths? What is the priority order?
• Port-forward lifecycle — If a port-forward tunnel is opened for a ClusterIP service, when should it be torn down? On disconnection, on extension deactivation, or on explicit user action?
• Credential secret convention — Is there a de-facto standard annotation or label for pointing a Service at a credential Secret? Should the plugin support multiple conventions (e.g., Helm chart defaults) or require an explicit annotation?
• Cluster identification — kubeconfig contexts do not always carry human-readable cloud-provider metadata. What information is feasible to surface (provider type, region) without making extra API calls?
• Minimum RBAC — What Kubernetes RBAC permissions are required for read-only discovery? The plugin should document the minimum ClusterRole or Role + RoleBinding users need to create, and ideally link to a copy-pasteable manifest.

Extension Size & Memory Impact

Adding a Kubernetes client library is a non-trivial dependency. Unlike the Azure plugins — which reuse @azure/* libraries already bundled in the extension — a Kubernetes client would be new weight added to every install, even for users who never use Kubernetes discovery.

This issue includes a soft requirement to measure and evaluate the impact:

• Profile the compiled VSIX size before and after adding the Kubernetes client dependency.
• Measure VS Code extension host memory at idle and during active Kubernetes discovery.
• Identify whether the client (or large parts of it) can be lazily loaded — i.e., only require()'d when the Kubernetes plugin is first activated by the user.

Expected outcome: either a validated lightweight architecture (e.g., lazy import() at plugin activation time, with acceptable overhead), or a follow-up issue that introduces a general dynamic plugin activation mechanism for all service discovery providers — allowing plugins to load their dependencies on demand rather than at extension startup. This would benefit the Atlas plugin and any future provider that brings its own SDK.

Out of Scope

• Building a general dynamic plugin activation mechanism (may become a follow-up).
• Kubernetes cluster management features beyond discovery (scaling, deployments, secrets management).
• Changes to the core discovery plugin interface.
• Support for non-Kubernetes container runtimes (Docker Compose, Podman) — those may be addressed by a separate plugin.

References

• Existing plugin UX patterns: src/plugins/service-azure-vm/ and src/plugins/api-shared/azure/
• Credential management infrastructure: src/plugins/api-shared/azure/credentialsManagement/
• Filter infrastructure: src/plugins/api-shared/azure/subscriptionFiltering/
• MongoDB Atlas discovery issue (sister issue for non-Azure non-Kubernetes cloud): Feature: MongoDB Atlas Service Discovery (UX) #531
• Service Discovery overview: docs/user-manual/service-discovery.md
• Managing Azure Discovery (UX to emulate): docs/user-manual/managing-azure-discovery.md
• Kubernetes API reference — Service
• Kubernetes RBAC documentation