0
# Configuration and Authentication
1

2
Configuration management and authentication for Kubernetes cluster access. The library supports multiple authentication methods, flexible configuration loading, and various cloud provider integrations.
3

4
## Capabilities
5

6
### KubeConfig Class
7

8
Central configuration class for managing Kubernetes cluster connections, user credentials, and contexts.
9

10
```typescript { .api }
11
/**
12
 * Main configuration class for Kubernetes cluster access
13
 */
14
class KubeConfig {
15
  /** Load configuration from default locations (kubeconfig file, environment, in-cluster) */
16
  loadFromDefault(options?: Partial<ConfigOptions>): void;
17
  
18
  /** Load configuration from a specific kubeconfig file */
19
  loadFromFile(file: string, opts?: Partial<ConfigOptions>): void;
20
  
21
  /** Load configuration from a YAML string */
22
  loadFromString(config: string, opts?: Partial<ConfigOptions>): void;
23
  
24
  /** Load in-cluster service account configuration */
25
  loadFromCluster(): void;
26
  
27
  /** Load configuration from options object */
28
  loadFromOptions(options: any): void;
29
  
30
  /** Create a typed API client instance */
31
  makeApiClient<T>(apiClientType: ApiType<T>): T;
32
  
33
  /** Apply authentication to HTTPS request options */
34
  applyToHTTPSOptions(opts: https.RequestOptions | WebSocket.ClientOptions): Promise<void>;
35
  
36
  /** Apply authentication to fetch options */
37
  applyToFetchOptions(opts: https.RequestOptions): Promise<RequestInit>;
38
  
39
  /** Available clusters */
40
  clusters: Cluster[];
41
  
42
  /** Available users */
43
  users: User[];
44
  
45
  /** Available contexts */
46
  contexts: Context[];
47
  
48
  /** Active context name */
49
  currentContext: string;
50
  
51
  /** Get all contexts */
52
  getContexts(): Context[];
53
  
54
  /** Get all clusters */
55
  getClusters(): Cluster[];
56
  
57
  /** Get all users */
58
  getUsers(): User[];
59
  
60
  /** Get current context name */
61
  getCurrentContext(): string;
62
  
63
  /** Set current context */
64
  setCurrentContext(context: string): void;
65
  
66
  /** Get context object by name */
67
  getContextObject(name: string): Context | null;
68
  
69
  /** Get current cluster */
70
  getCurrentCluster(): Cluster | null;
71
  
72
  /** Get cluster by name */
73
  getCluster(name: string): Cluster | null;
74
  
75
  /** Get current user */
76
  getCurrentUser(): User | null;
77
  
78
  /** Get user by name */
79
  getUser(name: string): User | null;
80
}
81
```
82

83
**Usage Examples:**
84

85
```typescript
86
import { KubeConfig, CoreV1Api } from '@kubernetes/client-node';
87

88
// Load from default location
89
const kc = new KubeConfig();
90
kc.loadFromDefault();
91

92
// Load from specific file
93
kc.loadFromFile('/path/to/kubeconfig');
94

95
// Load from YAML string
96
const yamlConfig = `
97
apiVersion: v1
98
clusters:
99
- cluster:
100
    server: https://k8s.example.com
101
  name: my-cluster
102
contexts:
103
- context:
104
    cluster: my-cluster
105
    user: my-user
106
  name: my-context
107
current-context: my-context
108
users:
109
- name: my-user
110
  user:
111
    token: my-token
112
`;
113
kc.loadFromString(yamlConfig);
114

115
// Load in-cluster config (for pods running in Kubernetes)
116
kc.loadFromCluster();
117

118
// Create API client
119
const k8sApi = kc.makeApiClient(CoreV1Api);
120
```
121

122
### Configuration Types
123

124
Type definitions for cluster, user, and context configuration.
125

126
```typescript { .api }
127
interface ConfigOptions {
128
  /** How to handle invalid configuration entries */
129
  onInvalidEntry: ActionOnInvalid;
130
}
131

132
interface Cluster {
133
  /** Cluster name */
134
  name: string;
135
  /** API server URL */
136
  server: string;
137
  /** Certificate authority data (base64) */
138
  caData?: string;
139
  /** Certificate authority file path */
140
  caFile?: string;
141
  /** TLS server name for SNI */
142
  tlsServerName?: string;
143
  /** Skip TLS verification */
144
  skipTLSVerify: boolean;
145
  /** Proxy URL for cluster access */
146
  proxyUrl?: string;
147
}
148

149
interface User {
150
  /** User name */
151
  name: string;
152
  /** Authentication token */
153
  token?: string;
154
  /** Client certificate data (base64) */
155
  certData?: string;
156
  /** Client certificate file path */
157
  certFile?: string;
158
  /** Client key data (base64) */
159
  keyData?: string;
160
  /** Client key file path */
161
  keyFile?: string;
162
  /** Username for basic auth */
163
  username?: string;
164
  /** Password for basic auth */
165
  password?: string;
166
  /** Authentication provider configuration */
167
  authProvider?: any;
168
  /** Exec credential configuration */
169
  exec?: any;
170
  /** Impersonate user */
171
  impersonateUser?: string;
172
}
173

174
interface Context {
175
  /** Context name */
176
  name: string;
177
  /** Cluster name to use */
178
  cluster: string;
179
  /** User name to use */
180
  user: string;
181
  /** Default namespace */
182
  namespace?: string;
183
}
184

185
const ActionOnInvalid = {
186
  THROW: 'throw',
187
  FILTER: 'filter'
188
} as const;
189

190
type ActionOnInvalid = typeof ActionOnInvalid[keyof typeof ActionOnInvalid];
191
```
192

193
### Configuration Utilities
194

195
Utility functions for working with configuration objects.
196

197
```typescript { .api }
198
/**
199
 * Create cluster array from configuration data
200
 */
201
function newClusters(a: any, opts?: Partial<ConfigOptions>): Cluster[];
202

203
/**
204
 * Create user array from configuration data
205
 */
206
function newUsers(a: any, opts?: Partial<ConfigOptions>): User[];
207

208
/**
209
 * Create context array from configuration data
210
 */
211
function newContexts(a: any, opts?: Partial<ConfigOptions>): Context[];
212

213
/**
214
 * Export cluster to configuration format
215
 */
216
function exportCluster(cluster: Cluster): any;
217

218
/**
219
 * Export user to configuration format
220
 */
221
function exportUser(user: User): any;
222

223
/**
224
 * Export context to configuration format
225
 */
226
function exportContext(context: Context): any;
227

228
/**
229
 * Make an absolute file path
230
 */
231
function makeAbsolutePath(root: string, file: string): string;
232

233
/**
234
 * Load buffer from file or string
235
 */
236
function bufferFromFileOrString(file?: string, data?: string): Buffer | null;
237

238
/**
239
 * Find user home directory
240
 */
241
function findHomeDir(platform?: string): string | null;
242

243
/**
244
 * Find named object in list
245
 */
246
function findObject<T>(list: T[], name: string, key: string): T | null;
247
```
248

249
### Authentication Providers
250

251
The library includes support for various authentication providers through the `Authenticator` interface.
252

253
```typescript { .api }
254
interface Authenticator {
255
  /** Check if this authenticator handles the user configuration */
256
  isAuthProvider(user: User): boolean;
257
  
258
  /** Apply authentication to request options */
259
  applyAuthentication(user: User, opts: any): Promise<void>;
260
}
261
```
262

263
**Available Authentication Providers:**
264

265
- **AzureAuth**: Azure Active Directory authentication
266
- **GoogleCloudPlatformAuth**: Google Cloud authentication
267
- **OpenIDConnectAuth**: OIDC authentication
268
- **ExecAuth**: External command authentication
269
- **FileAuth**: File-based token authentication
270

271
**Usage Example:**
272

273
```typescript
274
import { KubeConfig, GoogleCloudPlatformAuth } from '@kubernetes/client-node';
275

276
const kc = new KubeConfig();
277
kc.loadFromDefault();
278

279
// Authentication is automatically handled when making API calls
280
const k8sApi = kc.makeApiClient(CoreV1Api);
281
const pods = await k8sApi.listNamespacedPod('default');
282
```
283

284
### In-Cluster Configuration
285

286
For applications running inside Kubernetes pods, the library can automatically load service account credentials.
287

288
```typescript
289
import { KubeConfig } from '@kubernetes/client-node';
290

291
// This loads the service account token and CA certificate
292
// from the standard locations: /var/run/secrets/kubernetes.io/serviceaccount/
293
const kc = new KubeConfig();
294
kc.loadFromCluster();
295

296
const k8sApi = kc.makeApiClient(CoreV1Api);
297
```
298

299
### Error Handling
300

301
Authentication errors and configuration issues are reported through standard JavaScript errors.
302

303
```typescript
304
import { KubeConfig } from '@kubernetes/client-node';
305

306
try {
307
  const kc = new KubeConfig();
308
  kc.loadFromFile('/invalid/path/kubeconfig');
309
} catch (error) {
310
  console.error('Configuration error:', error.message);
311
}
312
```
313

314
### Configuration Examples
315

316
**Multi-cluster configuration:**
317

318
```typescript
319
const kc = new KubeConfig();
320
kc.loadFromDefault();
321

322
// Switch between contexts
323
kc.currentContext = 'production-cluster';
324
const prodApi = kc.makeApiClient(CoreV1Api);
325

326
kc.currentContext = 'staging-cluster';
327
const stagingApi = kc.makeApiClient(CoreV1Api);
328
```
329

330
**Custom authentication:**
331

332
```typescript
333
const kc = new KubeConfig();
334
kc.loadFromOptions({
335
  clusters: [{
336
    name: 'my-cluster',
337
    server: 'https://k8s.example.com',
338
    skipTLSVerify: false
339
  }],
340
  users: [{
341
    name: 'my-user',
342
    token: 'bearer-token-here'
343
  }],
344
  contexts: [{
345
    name: 'my-context',
346
    cluster: 'my-cluster',
347
    user: 'my-user',
348
    namespace: 'my-namespace'
349
  }],
350
  currentContext: 'my-context'
351
});
352
```