0
# Kubernetes Client Node
1

2
The Kubernetes Client Node library provides a comprehensive TypeScript/JavaScript client for interacting with Kubernetes clusters from Node.js applications. It offers complete Kubernetes API coverage through auto-generated client code, high-level convenience classes for common operations, and robust authentication support for various cloud providers.
3

4
## Package Information
5

6
- **Package Name**: @kubernetes/client-node
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @kubernetes/client-node`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  KubeConfig, 
16
  CoreV1Api, 
17
  AppsV1Api,
18
  Watch,
19
  Log,
20
  Exec,
21
  Attach,
22
  PortForward,
23
  Metrics
24
} from '@kubernetes/client-node';
25
```
26

27
For CommonJS:
28

29
```javascript
30
const { 
31
  KubeConfig, 
32
  CoreV1Api, 
33
  AppsV1Api,
34
  Watch,
35
  Log,
36
  Exec,
37
  Attach,
38
  PortForward,
39
  Metrics
40
} = require('@kubernetes/client-node');
41
```
42

43
## Basic Usage
44

45
```typescript
46
import { KubeConfig, CoreV1Api } from '@kubernetes/client-node';
47

48
// Load configuration
49
const kc = new KubeConfig();
50
kc.loadFromDefault();
51

52
// Create API client
53
const k8sApi = kc.makeApiClient(CoreV1Api);
54

55
// List pods in default namespace
56
try {
57
  const res = await k8sApi.listNamespacedPod('default');
58
  console.log('Found pods:', res.body.items.map(pod => pod.metadata?.name));
59
} catch (err) {
60
  console.error('Error:', err);
61
}
62
```
63

64
## Architecture
65

66
The Kubernetes Client Node library is organized around several key components:
67

68
- **Configuration System**: `KubeConfig` class handles cluster connection, authentication, and context management
69
- **Generated API Clients**: Complete coverage of all Kubernetes API groups with type-safe methods
70
- **High-Level Operations**: Convenience classes for common tasks like exec, attach, port forwarding, and log streaming  
71
- **Monitoring Tools**: Watch, Informer, and Metrics classes for real-time cluster observation
72
- **Authentication Providers**: Support for various auth methods including OIDC, Azure AD, Google Cloud, and more
73
- **Utilities**: YAML processing, health checking, caching, and object management tools
74

75
## Capabilities
76

77
### Configuration and Authentication
78

79
Core configuration management and authentication for Kubernetes cluster access. Supports multiple authentication methods and flexible configuration loading.
80

81
```typescript { .api }
82
class KubeConfig {
83
  loadFromDefault(options?: ConfigOptions): void;
84
  loadFromFile(file: string): void;
85
  loadFromString(config: string): void;
86
  loadFromCluster(): void;
87
  makeApiClient<T>(apiClientType: ApiType<T>): T;
88
}
89
```
90

91
[Configuration and Authentication](./configuration.md)
92

93
### Generated API Clients
94

95
Complete Kubernetes API coverage with type-safe client classes for all API groups. Provides full CRUD operations for all Kubernetes resources.
96

97
```typescript { .api }
98
class CoreV1Api {
99
  listNamespacedPod(namespace: string, options?: object): Promise<KubernetesListObject<V1Pod>>;
100
  createNamespacedPod(namespace: string, body: V1Pod, options?: object): Promise<V1Pod>;
101
  deleteNamespacedPod(name: string, namespace: string, options?: object): Promise<V1Status>;
102
}
103

104
class AppsV1Api {
105
  listNamespacedDeployment(namespace: string, options?: object): Promise<KubernetesListObject<V1Deployment>>;
106
  createNamespacedDeployment(namespace: string, body: V1Deployment, options?: object): Promise<V1Deployment>;
107
}
108
```
109

110
[Generated API Clients](./api-clients.md)
111

112
### Pod Operations
113

114
High-level classes for interactive pod operations including command execution, container attachment, port forwarding, and file transfer.
115

116
```typescript { .api }
117
class Exec {
118
  exec(
119
    namespace: string,
120
    podName: string,
121
    containerName: string,
122
    command: string | string[],
123
    stdout: stream.Writable | null,
124
    stderr: stream.Writable | null,
125
    stdin: stream.Readable | null,
126
    tty: boolean,
127
    statusCallback?: (status: V1Status) => void
128
  ): Promise<WebSocket.WebSocket>;
129
}
130

131
class PortForward {
132
  portForward(
133
    namespace: string,
134
    podName: string,
135
    targetPorts: number[],
136
    output: stream.Writable,
137
    err: stream.Writable | null,
138
    input: stream.Readable,
139
    retryCount?: number
140
  ): Promise<WebSocket.WebSocket | (() => WebSocket.WebSocket | null)>;
141
}
142
```
143

144
[Pod Operations](./pod-operations.md)
145

146
### Monitoring and Observability
147

148
Real-time monitoring tools for watching resource changes, streaming logs, collecting metrics, and implementing the informer pattern for efficient resource caching.
149

150
```typescript { .api }
151
class Watch {
152
  watch(
153
    path: string,
154
    queryParams: Record<string, string | number | boolean | undefined>,
155
    callback: (phase: string, apiObj: any, watchObj?: any) => void,
156
    done: (err: any) => void
157
  ): Promise<AbortController>;
158
}
159

160
class Log {
161
  log(
162
    namespace: string,
163
    podName: string,
164
    containerName: string,
165
    stream: Writable,
166
    options?: LogOptions
167
  ): Promise<AbortController>;
168
}
169

170
class Metrics {
171
  getNodeMetrics(): Promise<NodeMetricsList>;
172
  getPodMetrics(namespace?: string): Promise<PodMetricsList>;
173
}
174
```
175

176
[Monitoring and Observability](./monitoring.md)
177

178
### Object Management and Utilities
179

180
Generic object management, YAML processing, health checking, and utility functions for working with Kubernetes resources and cluster operations.
181

182
```typescript { .api }
183
class KubernetesObjectApi {
184
  static makeApiClient(kc: KubeConfig): KubernetesObjectApi;
185
  create(obj: KubernetesObject, options?: object): Promise<KubernetesObject>;
186
  delete(obj: KubernetesObject, options?: object): Promise<V1Status>;
187
  read(obj: KubernetesObject): Promise<KubernetesObject>;
188
  patch(obj: KubernetesObject, patch: object, options?: object): Promise<KubernetesObject>;
189
  replace(obj: KubernetesObject, options?: object): Promise<KubernetesObject>;
190
}
191

192
function loadYaml<T>(data: string, opts?: yaml.LoadOptions): T;
193
function dumpYaml(object: any, opts?: yaml.DumpOptions): string;
194
```
195

196
[Object Management and Utilities](./utilities.md)
197

198
## Types
199

200
```typescript { .api }
201
interface KubernetesObject {
202
  apiVersion?: string;
203
  kind?: string;
204
  metadata?: V1ObjectMeta;
205
}
206

207
interface KubernetesListObject<T> {
208
  apiVersion?: string;
209
  kind?: string;
210
  metadata?: V1ListMeta;
211
  items: T[];
212
}
213

214
interface ConfigOptions {
215
  onInvalidEntry?: ActionOnInvalid;
216
}
217

218
interface LogOptions {
219
  follow?: boolean;
220
  limitBytes?: number;
221
  pretty?: boolean;
222
  previous?: boolean;
223
  sinceSeconds?: number;
224
  sinceTime?: string;
225
  tailLines?: number;
226
  timestamps?: boolean;
227
}
228

229
type IntOrString = number | string;
230

231
interface ApiType<T = any> {
232
  new(config?: Configuration): T;
233
}
234

235
type KubernetesApiAction = 'create' | 'delete' | 'patch' | 'read' | 'list' | 'replace';
236

237
interface RequestOptions {
238
  /** Request timeout in milliseconds */
239
  timeout?: number;
240
  /** Additional headers */
241
  headers?: Record<string, string>;
242
}
243

244
interface ConfigurationOptions {
245
  /** Base path for API requests */
246
  basePath?: string;
247
  /** HTTP timeout in milliseconds */
248
  timeout?: number;
249
  /** Additional headers */
250
  headers?: Record<string, string>;
251
  /** Request middleware */
252
  middleware?: any[];
253
}
254

255
interface ApiException extends Error {
256
  /** HTTP status code */
257
  code?: number;
258
  /** Response body */
259
  body?: any;
260
  /** Response headers */
261
  headers?: any;
262
}
263
```