Skip to main content

​
Overview

The Deployments API provides endpoints for listing, viewing, and managing Kubernetes Deployments.

​
Endpoints

​
List Deployments

GET /api/deployments
Query Parameters:
ParameterTypeRequiredDescription
namespacestringYesKubernetes namespace
contextstringNoKubeconfig context
Example Request: 
curl "http://localhost:3000/api/deployments?namespace=default"
Example Response: 
{
  "deployments": [
    {
      "name": "nginx",
      "namespace": "default",
      "replicas": {
        "desired": 3,
        "ready": 3,
        "available": 3,
        "unavailable": 0
      },
      "status": "Available",
      "age": "5d",
      "images": ["nginx:1.21"],
      "labels": {
        "app": "nginx",
        "tier": "frontend"
      },
      "createdAt": "2025-01-23T10:00:00Z"
    }
  ]
}

​
Get Deployment Details

GET /api/deployments/[name]
Path Parameters:
ParameterTypeRequiredDescription
namestringYesDeployment name
Query Parameters:
ParameterTypeRequiredDescription
namespacestringYesKubernetes namespace
contextstringNoKubeconfig context
Example Request: 
curl "http://localhost:3000/api/deployments/nginx?namespace=default"
Example Response: 
{
  "name": "nginx",
  "namespace": "default",
  "uid": "abc123...",
  "replicas": {
    "desired": 3,
    "ready": 3,
    "available": 3,
    "unavailable": 0,
    "updated": 3
  },
  "status": "Available",
  "conditions": [
    {
      "type": "Available",
      "status": "True",
      "lastUpdateTime": "2025-01-23T10:05:00Z",
      "lastTransitionTime": "2025-01-23T10:05:00Z",
      "reason": "MinimumReplicasAvailable",
      "message": "Deployment has minimum availability."
    },
    {
      "type": "Progressing",
      "status": "True",
      "lastUpdateTime": "2025-01-23T10:05:00Z",
      "lastTransitionTime": "2025-01-23T10:00:00Z",
      "reason": "NewReplicaSetAvailable",
      "message": "ReplicaSet \"nginx-abc123\" has successfully progressed."
    }
  ],
  "strategy": {
    "type": "RollingUpdate",
    "rollingUpdate": {
      "maxSurge": 1,
      "maxUnavailable": 0
    }
  },
  "selector": {
    "matchLabels": {
      "app": "nginx"
    }
  },
  "template": {
    "metadata": {
      "labels": {
        "app": "nginx"
      }
    },
    "spec": {
      "containers": [
        {
          "name": "nginx",
          "image": "nginx:1.21",
          "ports": [
            {
              "containerPort": 80,
              "protocol": "TCP"
            }
          ],
          "resources": {
            "requests": {
              "cpu": "100m",
              "memory": "128Mi"
            },
            "limits": {
              "cpu": "500m",
              "memory": "512Mi"
            }
          }
        }
      ]
    }
  },
  "createdAt": "2025-01-23T10:00:00Z",
  "labels": {
    "app": "nginx",
    "tier": "frontend"
  },
  "annotations": {
    "deployment.kubernetes.io/revision": "1"
  }
}

​
Restart Deployment

POST /api/deployments/[name]/restart
Path Parameters:
ParameterTypeRequiredDescription
namestringYesDeployment name
Request Body: 
{
  "namespace": "default"
}
Example Request: 
curl -X POST "http://localhost:3000/api/deployments/nginx/restart" \
  -H "Content-Type: application/json" \
  -d '{"namespace":"default"}'
Example Response: 
{
  "success": true,
  "message": "Deployment restarted successfully",
  "deployment": "nginx",
  "namespace": "default",
  "timestamp": "2025-01-28T10:00:00Z"
}
How it works: Adds kubectl.kubernetes.io/restartedAt annotation to pod template, triggering rolling restart.

​
Get Deployment Pods

GET /api/deployments/[name]/pods
Path Parameters:
ParameterTypeRequiredDescription
namestringYesDeployment name
Query Parameters:
ParameterTypeRequiredDescription
namespacestringYesKubernetes namespace
contextstringNoKubeconfig context
Example Request: 
curl "http://localhost:3000/api/deployments/nginx/pods?namespace=default"
Example Response: 
{
  "pods": [
    {
      "name": "nginx-abc123-xyz",
      "namespace": "default",
      "status": "Running",
      "phase": "Running",
      "nodeName": "node-1",
      "podIP": "10.244.1.5",
      "containers": [
        {
          "name": "nginx",
          "image": "nginx:1.21",
          "ready": true,
          "restartCount": 0,
          "state": {
            "running": {
              "startedAt": "2025-01-23T10:00:00Z"
            }
          }
        }
      ],
      "createdAt": "2025-01-23T10:00:00Z"
    }
  ]
}

​
Get Deployment Events

GET /api/deployments/[name]/events
Path Parameters:
ParameterTypeRequiredDescription
namestringYesDeployment name
Query Parameters:
ParameterTypeRequiredDescription
namespacestringYesKubernetes namespace
contextstringNoKubeconfig context
Example Request: 
curl "http://localhost:3000/api/deployments/nginx/events?namespace=default"
Example Response: 
{
  "events": [
    {
      "type": "Normal",
      "reason": "ScalingReplicaSet",
      "message": "Scaled up replica set nginx-abc123 to 3",
      "count": 1,
      "firstTimestamp": "2025-01-23T10:00:00Z",
      "lastTimestamp": "2025-01-23T10:00:00Z",
      "involvedObject": {
        "kind": "Deployment",
        "name": "nginx",
        "namespace": "default"
      }
    }
  ]
}

​
Error Responses

​
400 Bad Request

{
  "error": "Namespace parameter is required",
  "code": "BAD_REQUEST"
}

​
403 Forbidden

{
  "error": "Forbidden: User cannot get resource \"deployments\" in API group \"apps\" in namespace \"default\"",
  "code": "FORBIDDEN",
  "statusCode": 403
}

​
404 Not Found

{
  "error": "Deployment not found",
  "code": "NOT_FOUND",
  "deployment": "nginx",
  "namespace": "default"
}

​
500 Internal Server Error

{
  "error": "Failed to fetch deployments",
  "code": "INTERNAL_ERROR",
  "details": "Connection timeout"
}

​
Usage Examples

​
JavaScript/TypeScript

// List deployments
async function listDeployments(namespace: string) {
  const res = await fetch(`/api/deployments?namespace=${namespace}`)
  if (!res.ok) throw new Error('Failed to fetch deployments')
  return res.json()
}

// Get deployment
async function getDeployment(name: string, namespace: string) {
  const res = await fetch(`/api/deployments/${name}?namespace=${namespace}`)
  if (!res.ok) throw new Error('Failed to fetch deployment')
  return res.json()
}

// Restart deployment
async function restartDeployment(name: string, namespace: string) {
  const res = await fetch(`/api/deployments/${name}/restart`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ namespace })
  })
  if (!res.ok) throw new Error('Failed to restart deployment')
  return res.json()
}

​
React Query Hook

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'

export function useDeployments(namespace: string) {
  return useQuery({
    queryKey: ['deployments', namespace],
    queryFn: () => listDeployments(namespace),
    enabled: !!namespace,
    refetchInterval: 30000,
  })
}

export function useRestartDeployment() {
  const queryClient = useQueryClient()
  
  return useMutation({
    mutationFn: ({ name, namespace }: { name: string; namespace: string }) =>
      restartDeployment(name, namespace),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['deployments'] })
    },
  })
}

​
Next Steps

Pods API

Pod management endpoints

Nodes API

Node monitoring endpoints

Events API

Event tracking endpoints

Real-time API

Live updates with SSE