API Module

Overview

The API module is a stateless Go application that serves as a Kubernetes API extension. It provides enhanced functionality on top of the standard Kubernetes API, including data aggregation, filtering, sorting, and pagination.

The API module is the core backend service that powers most Dashboard features.

Module Architecture

Entry Point

The module starts in modules/api/main.go:

func main() {
    klog.InfoS("Starting Kubernetes Dashboard API", "version", environment.Version)
    
    // Initialize Kubernetes client
    client.Init(
        client.WithUserAgent(environment.UserAgent()),
        client.WithKubeconfig(args.KubeconfigPath()),
        client.WithMasterUrl(args.ApiServerHost()),
        client.WithInsecureTLSSkipVerify(args.ApiServerSkipTLSVerify()),
        client.WithCaBundle(args.ApiServerCaBundle()),
    )
    
    // Initialize integrations (metrics)
    integrationManager := integration.NewIntegrationManager()
    configureMetricsProvider(integrationManager)
    
    // Create HTTP API handler
    apiHandler, err := handler.CreateHTTPAPIHandler(integrationManager)
    
    // Serve HTTPS or HTTP
    if certs != nil {
        serveTLS(certs)
    } else {
        serve()
    }
}

Reference: modules/api/main.go:39-93

Package Structure

modules/api/pkg/
├── args/              # Command-line argument parsing
├── environment/       # Version and build information
├── handler/           # HTTP request handlers and routing
│   ├── apihandler.go # Main API handler with all routes
│   ├── filter.go     # Request filtering logic
│   ├── metrics.go    # Metrics endpoint handlers
│   ├── terminal.go   # WebSocket terminal handlers
│   └── parser/       # Request parameter parsing
├── integration/       # Integration manager for external services
│   ├── manager.go    # Integration lifecycle management
│   ├── metric/       # Metrics integration
│   └── api/          # Integration API types
├── resource/          # Kubernetes resource handlers (38 packages)
│   ├── pod/
│   ├── deployment/
│   ├── service/
│   └── ...
├── scaling/           # Resource scaling operations
└── validation/        # Input validation

Core Responsibilities

1. Resource Aggregation

The API module aggregates related data from multiple Kubernetes resources:

// Returns pod details with associated events and metrics
func GetPodDetail(client kubernetes.Interface, 
                  namespace, name string) (*PodDetail, error) {
    
    // Get pod
    pod := getPod(client, namespace, name)
    
    // Get events for pod
    events := getEvents(client, namespace, pod.UID)
    
    // Get metrics from integration
    metrics := getMetrics(namespace, name)
    
    return &PodDetail{
        Pod:     pod,
        Events:  events,
        Metrics: metrics,
    }
}

2. Filtering and Sorting

Implements server-side data selection through the dataselect package:

// Query parameters supported
type DataSelectQuery struct {
    FilterQuery   *FilterQuery   // filterBy=propertyName,filterValue
    SortQuery     *SortQuery     // sortBy=columnName
    PaginationQuery *PaginationQuery // page=1&itemsPerPage=10
}

Example Usage:

GET /api/v1/pod?filterBy=status,Running&sortBy=creationTimestamp&page=1&itemsPerPage=25

3. Pagination

Reduces response payload size for large clusters:

type PaginationQuery struct {
    ItemsPerPage int // Number of items per page
    Page         int // Current page number
}

type ListMeta struct {
    TotalItems int // Total number of items available
}

4. Terminal Access

Provides exec and shell access to containers via WebSocket:

// Terminal session endpoint
GET /api/v1/pod/{namespace}/{pod}/shell/{container}

// Returns session ID for WebSocket connection
type TerminalResponse struct {
    ID string `json:"id"` // Session identifier
}

WebSocket endpoint: /api/sockjs/ Reference: modules/api/pkg/handler/terminal.go

API Routes

The API module exposes comprehensive RESTful endpoints at /api/v1/*:

Workload Resources

Pods

GET /api/v1/pod - List all pods
GET /api/v1/pod/{namespace} - List pods in namespace
GET /api/v1/pod/{namespace}/{pod} - Get pod details
GET /api/v1/pod/{namespace}/{pod}/event - Get pod events
GET /api/v1/pod/{namespace}/{pod}/shell/{container} - Exec into container

Deployments

GET /api/v1/deployment - List all deployments
GET /api/v1/deployment/{namespace}/{deployment} - Get deployment details
PUT /api/v1/deployment/{namespace}/{deployment}/pause - Pause deployment
PUT /api/v1/deployment/{namespace}/{deployment}/resume - Resume deployment
PUT /api/v1/deployment/{namespace}/{deployment}/restart - Restart deployment
PUT /api/v1/deployment/{namespace}/{deployment}/rollback - Rollback deployment

StatefulSets, DaemonSets, ReplicaSets

GET /api/v1/statefulset/{namespace}/{statefulset}
GET /api/v1/daemonset/{namespace}/{daemonset}
GET /api/v1/replicaset/{namespace}/{replicaset}
Similar patterns for events, pods, services

Configuration and Storage

ConfigMaps: /api/v1/configmap/*
Secrets: /api/v1/secret/*
PersistentVolumes: /api/v1/persistentvolume/*
PersistentVolumeClaims: /api/v1/persistentvolumeclaim/*
StorageClasses: /api/v1/storageclass/*

Cluster Resources

Nodes: /api/v1/node/*
Namespaces: /api/v1/namespace/*
Events: /api/v1/event/*

RBAC

ClusterRoles: /api/v1/clusterrole/*
ClusterRoleBindings: /api/v1/clusterrolebinding/*
Roles: /api/v1/role/*
RoleBindings: /api/v1/rolebinding/*
ServiceAccounts: /api/v1/serviceaccount/*

Reference: modules/api/pkg/handler/apihandler.go:95-1200

Integration Manager

The Integration Manager handles communication with external services:

Metrics Integration

type Manager interface {
    GetState(id api.IntegrationID) (*api.IntegrationState, error)
    Metric() metric.MetricManager
}

// Configure sidecar metrics provider
func configureMetricsProvider(integrationManager integration.Manager) {
    switch metricsProvider := args.MetricsProvider(); metricsProvider {
    case "sidecar":
        integrationManager.Metric().ConfigureSidecar(args.SidecarHost()).
            EnableWithRetry(integrationapi.SidecarIntegrationID, 
                          time.Duration(args.MetricClientHealthCheckPeriod()))
    case "none":
        klog.Info("Metrics provider disabled")
    }
}

Reference:

modules/api/pkg/integration/manager.go
modules/api/main.go:122-135

Integration Health Checks

type IntegrationState struct {
    Connected   bool      // Connection status
    Error       error     // Last error if any
    LastChecked time.Time // Last health check time
}

Request Handling Flow

OpenAPI Documentation

When enabled, the API module generates OpenAPI/Swagger documentation:

if args.IsOpenAPIEnabled() {
    klog.Info("Enabling OpenAPI endpoint on /apidocs.json")
    configureOpenAPI(apiHandler)
}

func enrichOpenAPIObject(swo *spec.Swagger) {
    swo.Info = &spec.Info{
        InfoProps: spec.InfoProps{
            Title:   "Kubernetes Dashboard API",
            Version: environment.Version,
        },
    }
}

Access at: GET /apidocs.json Reference: modules/api/main.go:70-153

Resource Scaling

Generic scaling endpoints support any scalable resource:

// Scale resource to specific replica count
PUT /api/v1/scale/{kind}/{namespace}/{name}?scaleBy=5

// Get current replica count
GET /api/v1/scale/{kind}/{namespace}/{name}

type ReplicaCounts struct {
    DesiredReplicas int32
    ActualReplicas  int32
}

Supports: Deployments, ReplicaSets, StatefulSets, ReplicationControllers Reference: modules/api/pkg/scaling/

CSRF Protection

// Generate CSRF token for action
GET /api/v1/csrftoken/{action}

type Response struct {
    Token string `json:"token"`
}

CSRF tokens must be included in headers for:

POST requests (create resources)
PUT requests (update resources)
DELETE requests (delete resources)

Configuration Arguments

Key command-line arguments (via pkg/args):

Argument	Description	Default
`--kubeconfig`	Path to kubeconfig file	In-cluster config
`--apiserver-host`	Kubernetes API server URL	Auto-detected
`--insecure-bind-address`	HTTP bind address	`0.0.0.0:9090`
`--bind-address`	HTTPS bind address	`0.0.0.0:8443`
`--metrics-provider`	Metrics provider (sidecar/none)	`sidecar`
`--sidecar-host`	Metrics scraper URL	`http://localhost:8000`
`--enable-openapi`	Enable OpenAPI endpoint	`false`

Prometheus Metrics

The API module exposes Prometheus metrics:

http.Handle("/metrics", promhttp.Handler())

Endpoint: GET /metrics Metrics include:

Request count and latency
Go runtime metrics
Custom business metrics

Error Handling

Consistent error responses across all endpoints:

{
  "status": "error",
  "code": 404,
  "message": "Pod not found",
  "errors": []
}

Reference: modules/common/errors/

Testing

The API module includes comprehensive tests:

# Run API module tests
cd modules/api
go test ./...

# Run with coverage
go test -cover ./...

Proxy Mode

The API module can run in proxy mode for development:

--proxy-enabled=true

In proxy mode:

No in-cluster client connections
Metrics integration disabled
Useful for frontend development without K8s cluster

Reference: modules/api/main.go:50-63

Deployment

Helm chart deployment configuration:

api:
  image:
    repository: kubernetesui/dashboard-api
    tag: v1.0.0
  containers:
    args:
      - --metrics-provider=sidecar
      - --sidecar-host=http://kubernetes-dashboard-metrics-scraper:8000
  scaling:
    replicas: 1

Reference: charts/kubernetes-dashboard/templates/deployments/api.yaml

Integration Manager

Learn about service integrations

Metrics Scraper

How metrics are collected and served

Auth Module

Authentication and CSRF protection

Resource Handlers

Source: modules/api/pkg/resource/

Get Started

User Guide

Architecture

Configuration

Overview

Module Architecture

Entry Point

Package Structure

Core Responsibilities

1. Resource Aggregation

2. Filtering and Sorting

4. Terminal Access

API Routes

Workload Resources

Configuration and Storage

Cluster Resources

RBAC

Integration Manager

Metrics Integration

Integration Health Checks

Request Handling Flow

OpenAPI Documentation

Resource Scaling

CSRF Protection

Configuration Arguments

Prometheus Metrics

Error Handling

Testing

Proxy Mode

Deployment

Integration Manager

Metrics Scraper

Auth Module

Resource Handlers

Build docs developers (and LLMs) love

Get Started

User Guide

Architecture

Configuration

​Overview

​Module Architecture

​Entry Point

​Package Structure

​Core Responsibilities

​1. Resource Aggregation

​2. Filtering and Sorting

​3. Pagination

​4. Terminal Access

​API Routes

​Workload Resources

​Configuration and Storage

​Cluster Resources

​RBAC

​Integration Manager

​Metrics Integration

​Integration Health Checks

​Request Handling Flow

​OpenAPI Documentation

​Resource Scaling

​CSRF Protection

​Configuration Arguments

​Prometheus Metrics

​Error Handling

​Testing

​Proxy Mode

​Deployment

​Related Resources

Integration Manager

Metrics Scraper

Auth Module

Resource Handlers

Build docs developers (and LLMs) love

Overview

Module Architecture

Entry Point

Package Structure

Core Responsibilities

1. Resource Aggregation

2. Filtering and Sorting

3. Pagination

4. Terminal Access

API Routes

Workload Resources

Configuration and Storage

Cluster Resources

RBAC

Integration Manager

Metrics Integration

Integration Health Checks

Request Handling Flow

OpenAPI Documentation

Resource Scaling

CSRF Protection

Configuration Arguments

Prometheus Metrics

Error Handling

Testing

Proxy Mode

Deployment

Related Resources