headlamp-polaris-plugin/docs/architecture/adr/002-service-proxy-data-source.md

ADR-002: Service Proxy as Single Data Source

Status: Accepted Date: 2026-03-05 Deciders: Plugin maintainers

Context

The Polaris plugin needs audit data from the Polaris dashboard. Polaris dashboard exposes a /results.json endpoint containing pre-computed audit results for all workloads in the cluster.

Several approaches were considered for obtaining this data:

1. Query Kubernetes resources directly and re-implement Polaris audit logic
2. Use the Polaris CLI as a sidecar container
3. Use the Polaris dashboard's REST API via Kubernetes service proxy
4. Embed Polaris as a Go/JS library

The service proxy approach uses the Kubernetes API server's built-in service proxy capability to reach the Polaris dashboard at /api/v1/namespaces/polaris/services/polaris-dashboard:80/proxy/results.json. This means the plugin receives pre-computed audit results without needing to understand Polaris internals.

Constraints:

• Headlamp plugins can make API calls via ApiProxy.request() (proxied through the Headlamp backend) or direct fetch() for external URLs
• The Polaris dashboard service name, namespace, and port may vary across cluster setups
• Some users may run Polaris externally (not in-cluster)

Requirements:

• Retrieve all audit data in a single API call
• Support configurable endpoint URL for different cluster configurations
• Support external Polaris instances via full HTTP/HTTPS URLs
• Work through existing Kubernetes RBAC without additional configuration

Decision

Use ApiProxy.request() to fetch from the Polaris dashboard service proxy as the single data source for all audit data.

Implementation:

• Default endpoint: /api/v1/namespaces/polaris/services/polaris-dashboard:80/proxy/results.json
• URL is configurable via plugin settings stored in localStorage (key: polaris-plugin-dashboard-url)
• For full URLs starting with http:// or https://, use browser fetch() directly to support external Polaris instances
• getPolarisApiPath() in polaris.ts resolves the configured URL, with isFullUrl() determining the fetch strategy
• Single fetch shared across all views via PolarisDataProvider (see ADR-001)

Consequences

Positive

• ✅ Single API call gets all audit data - One request to /results.json returns scores for every workload
• ✅ No need to understand Polaris internals - Plugin receives pre-computed results, no audit logic duplication
• ✅ Works through existing K8s RBAC - Service proxy uses standard Kubernetes RBAC (get on services/proxy)
• ✅ Configurable endpoint - Users can customize namespace, service name, or point to an external instance
• ✅ Minimal plugin complexity - No CRD watches, no custom controllers, no library dependencies

Negative

• ❌ Requires Polaris dashboard to be deployed and accessible - Plugin has no data without the dashboard
  • Mitigated by: Clear error messages guiding users to install Polaris (404/503 → install guidance)
• ❌ Single point of failure - If the dashboard service is down, the plugin shows no data
  • Mitigated by: Status-code-specific error messages (403 → RBAC guidance, 404/503 → deployment guidance)
• ❌ Dashboard must be running continuously - Unlike CRD-based approaches where data persists
  • Mitigated by: Polaris dashboard is typically deployed as a long-running service

Neutral

• The Polaris dashboard is a lightweight Go service with minimal resource requirements
• Service proxy is a standard Kubernetes pattern used by many tools (kubectl port-forward, dashboard proxying)
• The configurable URL approach supports both in-cluster and external Polaris deployments

Alternatives Considered

Option 1: Query Polaris CRDs Directly

Pros:

• No dependency on Polaris dashboard being running
• Data persists in CRDs even if dashboard restarts

Cons:

• Polaris audit logic is complex and would need to be duplicated in the plugin
• Would require watching multiple CRD types
• Plugin would need to be updated whenever Polaris changes its audit rules

Decision: Rejected (would duplicate Polaris internals, maintenance burden)

Option 2: Use Polaris CLI as a Sidecar

Pros:

• CLI has full audit capability
• Could run audits on-demand

Cons:

• Adds operational complexity (sidecar container management)
• Not suitable for a browser-based plugin (CLI runs server-side)
• Would require a separate backend service to bridge CLI output to the plugin

Decision: Rejected (operational complexity, not suitable for plugin architecture)

Option 3: Embed Polaris as a Library

Pros:

• Full control over audit execution
• No external service dependency

Cons:

• Polaris is a Go library, not available in JavaScript/TypeScript plugin runtime
• Would massively increase bundle size
• Would duplicate the entire Polaris engine

Decision: Rejected (not available in plugin runtime, massive dependency)

References

• Kubernetes Service Proxy
• Polaris Dashboard
• Plugin Implementation
• Data Context

Revision History

Date	Author	Change
2026-03-05	Plugin Team	Initial decision