@phala/cloud 0.2.0 → 0.2.1-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,47 +1,112 @@
1
1
  import { z } from "zod";
2
2
  import { type Client } from "../../client";
3
3
  /**
4
- * Provision a CVM (Confidential Virtual Machine)
4
+ * Provision a CVM
5
5
  *
6
- * This action provisions a new CVM on a specified node, returning the app_id, encryption public key, and other metadata required for secure deployment.
6
+ * Performs a pre-deployment eligibility check, validating whether the requested resources
7
+ * are available and the user has sufficient permissions to deploy. Returns provision data
8
+ * including `app_id`, encryption public key (`app_env_encrypt_pubkey`), and `compose_hash`
9
+ * required for the subsequent `commitCvmProvision` call.
10
+ *
11
+ * ## Automatic Resource Selection
12
+ *
13
+ * The new matching engine automatically selects optimal resources based on your requirements:
14
+ * - **Node Selection**: Specify `node_id` or `region`, or omit both for automatic best-match selection
15
+ * - **OS Image**: Specify exact image name or let system choose the latest stable version
16
+ * - **KMS**: Choose KMS type via `kms` parameter (defaults to PHALA) or specify `kms_id` directly
7
17
  *
8
18
  * @example
9
19
  * ```typescript
10
- * import { createClient, getAvailableNodes, provisionCvm } from '@phala/cloud'
20
+ * import { createClient, provisionCvm, commitCvmProvision } from '@phala/cloud'
11
21
  *
12
22
  * const client = createClient();
13
- * const nodes = await getAvailableNodes(client);
14
- * const node = nodes.nodes[0];
15
23
  *
16
- * const docker_compose = `
17
- *version: '3'
18
- *services:
19
- * demo:
20
- * image: leechael/phala-cloud-bun-starter:latest
21
- * container_name: demo
22
- * ports:
23
- * - "3000:3000"
24
- * volumes:
25
- * - /var/run/tappd.sock:/var/run/tappd.sock
26
- *`;
27
- *
28
- * const app_compose = {
29
- * name: 'my-app',
30
- * node_id: node.node_id,
31
- * image: node.images[0].name,
32
- * vcpu: 1,
33
- * memory: 1024,
34
- * disk_size: 10,
24
+ * // Example 1: Minimal configuration with auto-selection
25
+ * const provision = await provisionCvm(client, {
26
+ * name: 'my-app', // Unique in workspace level
27
+ * instance_type: 'tdx.small',
35
28
  * compose_file: {
36
- * docker_compose_file: docker_compose,
37
- * name: '', // Internal field, use empty string
29
+ * docker_compose_file: `
30
+ * services:
31
+ * demo:
32
+ * image: leechael/phala-cloud-bun-starter:latest
33
+ * ports:
34
+ * - "80:3000"
35
+ * volumes:
36
+ * - /var/run/dstack.sock:/var/run/dstack.sock
37
+ * `,
38
38
  * },
39
- * };
39
+ * });
40
+ *
41
+ * // Example 2: With region preference
42
+ * const provision = await provisionCvm(client, {
43
+ * name: 'my-app',
44
+ * instance_type: 'tdx.medium',
45
+ * region: 'us-east', // Filter by region
46
+ * compose_file: { /* ... *\/ },
47
+ * });
48
+ *
49
+ * // Example 3: With specific node and KMS type
50
+ * const provision = await provisionCvm(client, {
51
+ * name: 'my-app',
52
+ * node_id: 123, // Specific node
53
+ * kms: 'PHALA', // KMS type (PHALA, BASE, ETHERUEM)
54
+ * disk_size: 40,
55
+ * image: 'dstack-0.5.5',
56
+ * compose_file: { /* ... *\/ },
57
+ * });
40
58
  *
41
- * const result = await provisionCvm(client, app_compose);
42
- * console.log(result.app_id);
59
+ * console.log(provision.app_id);
60
+ * console.log(provision.compose_hash); // Required for commitCvmProvision
43
61
  * ```
44
62
  *
63
+ * ## Required Parameters
64
+ *
65
+ * - **name**: CVM instance name
66
+ * - **compose_file**: Docker Compose configuration with `docker_compose_file` field
67
+ *
68
+ * ## Optional Parameters
69
+ *
70
+ * ### Instance Type
71
+ * - **instance_type**: Instance type identifier (default: "tdx.small")
72
+ * - Use `listAllInstanceTypeFamilies()` or `listFamilyInstanceTypes()` to discover available types
73
+ * - Examples: "tdx.small", "tdx.medium", "tdx.large"
74
+ * - Omit to use the default small instance type
75
+ *
76
+ * ### Node Selection (all optional - system auto-selects if omitted)
77
+ * - **node_id**: Specific node ID to deploy on
78
+ * - **region**: Region preference (e.g., "us-east", "eu-west")
79
+ * - If both omitted, system automatically selects the best available node
80
+ *
81
+ * ### OS Image Selection
82
+ * - **image**: OS image name (optional)
83
+ * - Omit to let the system automatically select the latest stable image
84
+ * - Specify a specific image name if needed (e.g., "dstack-0.5.5")
85
+ *
86
+ * ### KMS Configuration
87
+ * - **kms**: KMS type - "PHALA" (default), "ETHEREUM", or "BASE"
88
+ * - **kms_contract**: (Advanced) Specific KMS contract address
89
+ * - Omit to let the system automatically select an appropriate KMS contract
90
+ * - Specify only when: migrating KMS contracts, or selecting a specific contract on networks with multiple deployments
91
+ *
92
+ * ### Other Options
93
+ * - **disk_size**: Disk size in GB (optional)
94
+ * - Each instance type has a default disk size
95
+ * - Specify only if you need a different size than the default
96
+ * - **env_keys**: List of allowed environment variable keys
97
+ * - **listed**: Whether the CVM is publicly listed (default: true)
98
+ *
99
+ * ## Returns
100
+ *
101
+ * Provision data object containing:
102
+ * - **app_id**: Application identifier (required for commit step)
103
+ * - **app_env_encrypt_pubkey**: Public key for encrypting environment variables
104
+ * - **compose_hash**: Hash identifying this provision (required for commit step)
105
+ * - **device_id**: Device identifier for attestation
106
+ * - **fmspc**: Firmware Security Patch Configuration value
107
+ * - **os_image_hash**: Hash of the selected OS image
108
+ * - **instance_type**: The matched instance type identifier
109
+ *
45
110
  * ## Safe Version
46
111
  *
47
112
  * Use `safeProvisionCvm` for error handling without exceptions:
@@ -50,6 +115,7 @@ import { type Client } from "../../client";
50
115
  * const result = await safeProvisionCvm(client, app_compose);
51
116
  * if (result.success) {
52
117
  * console.log(result.data.app_id);
118
+ * console.log(result.data.compose_hash);
53
119
  * } else {
54
120
  * console.error('Failed to provision CVM:', result.error.message);
55
121
  * }
@@ -62,6 +128,7 @@ export declare const ProvisionCvmSchema: z.ZodEffects<z.ZodObject<{
62
128
  fmspc: z.ZodOptional<z.ZodNullable<z.ZodString>>;
63
129
  device_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
64
130
  os_image_hash: z.ZodOptional<z.ZodNullable<z.ZodString>>;
131
+ instance_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
65
132
  teepod_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
66
133
  node_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
67
134
  kms_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -72,6 +139,7 @@ export declare const ProvisionCvmSchema: z.ZodEffects<z.ZodObject<{
72
139
  fmspc: z.ZodOptional<z.ZodNullable<z.ZodString>>;
73
140
  device_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
74
141
  os_image_hash: z.ZodOptional<z.ZodNullable<z.ZodString>>;
142
+ instance_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
75
143
  teepod_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
76
144
  node_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
77
145
  kms_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -82,6 +150,7 @@ export declare const ProvisionCvmSchema: z.ZodEffects<z.ZodObject<{
82
150
  fmspc: z.ZodOptional<z.ZodNullable<z.ZodString>>;
83
151
  device_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
84
152
  os_image_hash: z.ZodOptional<z.ZodNullable<z.ZodString>>;
153
+ instance_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
85
154
  teepod_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
86
155
  node_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
87
156
  kms_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -92,6 +161,7 @@ export declare const ProvisionCvmSchema: z.ZodEffects<z.ZodObject<{
92
161
  fmspc: z.ZodOptional<z.ZodNullable<z.ZodString>>;
93
162
  device_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
94
163
  os_image_hash: z.ZodOptional<z.ZodNullable<z.ZodString>>;
164
+ instance_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
95
165
  teepod_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
96
166
  node_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
97
167
  kms_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -102,6 +172,7 @@ export declare const ProvisionCvmSchema: z.ZodEffects<z.ZodObject<{
102
172
  fmspc: z.ZodOptional<z.ZodNullable<z.ZodString>>;
103
173
  device_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
104
174
  os_image_hash: z.ZodOptional<z.ZodNullable<z.ZodString>>;
175
+ instance_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
105
176
  teepod_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
106
177
  node_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
107
178
  kms_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -110,23 +181,25 @@ export type ProvisionCvm = z.infer<typeof ProvisionCvmSchema>;
110
181
  export declare const ProvisionCvmRequestSchema: z.ZodObject<{
111
182
  node_id: z.ZodOptional<z.ZodNumber>;
112
183
  teepod_id: z.ZodOptional<z.ZodNumber>;
184
+ region: z.ZodOptional<z.ZodString>;
113
185
  name: z.ZodString;
114
- image: z.ZodString;
115
- vcpu: z.ZodNumber;
116
- memory: z.ZodNumber;
117
- disk_size: z.ZodNumber;
186
+ instance_type: z.ZodDefault<z.ZodString>;
187
+ image: z.ZodOptional<z.ZodString>;
188
+ vcpu: z.ZodOptional<z.ZodNumber>;
189
+ memory: z.ZodOptional<z.ZodNumber>;
190
+ disk_size: z.ZodOptional<z.ZodNumber>;
118
191
  compose_file: z.ZodObject<{
119
192
  allowed_envs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
120
193
  pre_launch_script: z.ZodOptional<z.ZodString>;
121
194
  docker_compose_file: z.ZodOptional<z.ZodString>;
122
- name: z.ZodOptional<z.ZodString>;
195
+ name: z.ZodDefault<z.ZodOptional<z.ZodString>>;
123
196
  kms_enabled: z.ZodOptional<z.ZodBoolean>;
124
197
  public_logs: z.ZodOptional<z.ZodBoolean>;
125
198
  public_sysinfo: z.ZodOptional<z.ZodBoolean>;
126
199
  gateway_enabled: z.ZodOptional<z.ZodBoolean>;
127
200
  tproxy_enabled: z.ZodOptional<z.ZodBoolean>;
128
201
  }, "strip", z.ZodTypeAny, {
129
- name?: string | undefined;
202
+ name: string;
130
203
  public_sysinfo?: boolean | undefined;
131
204
  public_logs?: boolean | undefined;
132
205
  docker_compose_file?: string | undefined;
@@ -147,29 +220,32 @@ export declare const ProvisionCvmRequestSchema: z.ZodObject<{
147
220
  tproxy_enabled?: boolean | undefined;
148
221
  }>;
149
222
  listed: z.ZodOptional<z.ZodBoolean>;
150
- instance_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
151
223
  kms_id: z.ZodOptional<z.ZodString>;
224
+ kms: z.ZodOptional<z.ZodEnum<["PHALA", "ETHEREUM", "BASE"]>>;
225
+ kms_contract: z.ZodOptional<z.ZodString>;
152
226
  env_keys: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
153
227
  }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
154
228
  node_id: z.ZodOptional<z.ZodNumber>;
155
229
  teepod_id: z.ZodOptional<z.ZodNumber>;
230
+ region: z.ZodOptional<z.ZodString>;
156
231
  name: z.ZodString;
157
- image: z.ZodString;
158
- vcpu: z.ZodNumber;
159
- memory: z.ZodNumber;
160
- disk_size: z.ZodNumber;
232
+ instance_type: z.ZodDefault<z.ZodString>;
233
+ image: z.ZodOptional<z.ZodString>;
234
+ vcpu: z.ZodOptional<z.ZodNumber>;
235
+ memory: z.ZodOptional<z.ZodNumber>;
236
+ disk_size: z.ZodOptional<z.ZodNumber>;
161
237
  compose_file: z.ZodObject<{
162
238
  allowed_envs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
163
239
  pre_launch_script: z.ZodOptional<z.ZodString>;
164
240
  docker_compose_file: z.ZodOptional<z.ZodString>;
165
- name: z.ZodOptional<z.ZodString>;
241
+ name: z.ZodDefault<z.ZodOptional<z.ZodString>>;
166
242
  kms_enabled: z.ZodOptional<z.ZodBoolean>;
167
243
  public_logs: z.ZodOptional<z.ZodBoolean>;
168
244
  public_sysinfo: z.ZodOptional<z.ZodBoolean>;
169
245
  gateway_enabled: z.ZodOptional<z.ZodBoolean>;
170
246
  tproxy_enabled: z.ZodOptional<z.ZodBoolean>;
171
247
  }, "strip", z.ZodTypeAny, {
172
- name?: string | undefined;
248
+ name: string;
173
249
  public_sysinfo?: boolean | undefined;
174
250
  public_logs?: boolean | undefined;
175
251
  docker_compose_file?: string | undefined;
@@ -190,29 +266,32 @@ export declare const ProvisionCvmRequestSchema: z.ZodObject<{
190
266
  tproxy_enabled?: boolean | undefined;
191
267
  }>;
192
268
  listed: z.ZodOptional<z.ZodBoolean>;
193
- instance_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
194
269
  kms_id: z.ZodOptional<z.ZodString>;
270
+ kms: z.ZodOptional<z.ZodEnum<["PHALA", "ETHEREUM", "BASE"]>>;
271
+ kms_contract: z.ZodOptional<z.ZodString>;
195
272
  env_keys: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
196
273
  }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
197
274
  node_id: z.ZodOptional<z.ZodNumber>;
198
275
  teepod_id: z.ZodOptional<z.ZodNumber>;
276
+ region: z.ZodOptional<z.ZodString>;
199
277
  name: z.ZodString;
200
- image: z.ZodString;
201
- vcpu: z.ZodNumber;
202
- memory: z.ZodNumber;
203
- disk_size: z.ZodNumber;
278
+ instance_type: z.ZodDefault<z.ZodString>;
279
+ image: z.ZodOptional<z.ZodString>;
280
+ vcpu: z.ZodOptional<z.ZodNumber>;
281
+ memory: z.ZodOptional<z.ZodNumber>;
282
+ disk_size: z.ZodOptional<z.ZodNumber>;
204
283
  compose_file: z.ZodObject<{
205
284
  allowed_envs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
206
285
  pre_launch_script: z.ZodOptional<z.ZodString>;
207
286
  docker_compose_file: z.ZodOptional<z.ZodString>;
208
- name: z.ZodOptional<z.ZodString>;
287
+ name: z.ZodDefault<z.ZodOptional<z.ZodString>>;
209
288
  kms_enabled: z.ZodOptional<z.ZodBoolean>;
210
289
  public_logs: z.ZodOptional<z.ZodBoolean>;
211
290
  public_sysinfo: z.ZodOptional<z.ZodBoolean>;
212
291
  gateway_enabled: z.ZodOptional<z.ZodBoolean>;
213
292
  tproxy_enabled: z.ZodOptional<z.ZodBoolean>;
214
293
  }, "strip", z.ZodTypeAny, {
215
- name?: string | undefined;
294
+ name: string;
216
295
  public_sysinfo?: boolean | undefined;
217
296
  public_logs?: boolean | undefined;
218
297
  docker_compose_file?: string | undefined;
@@ -233,11 +312,12 @@ export declare const ProvisionCvmRequestSchema: z.ZodObject<{
233
312
  tproxy_enabled?: boolean | undefined;
234
313
  }>;
235
314
  listed: z.ZodOptional<z.ZodBoolean>;
236
- instance_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
237
315
  kms_id: z.ZodOptional<z.ZodString>;
316
+ kms: z.ZodOptional<z.ZodEnum<["PHALA", "ETHEREUM", "BASE"]>>;
317
+ kms_contract: z.ZodOptional<z.ZodString>;
238
318
  env_keys: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
239
319
  }, z.ZodTypeAny, "passthrough">>;
240
- export type ProvisionCvmRequest = z.infer<typeof ProvisionCvmRequestSchema> & {
320
+ export type ProvisionCvmRequest = z.input<typeof ProvisionCvmRequestSchema> & {
241
321
  node_id?: number;
242
322
  teepod_id?: number;
243
323
  compose_file?: {
@@ -254,6 +334,7 @@ declare const provisionCvm: {
254
334
  fmspc: z.ZodOptional<z.ZodNullable<z.ZodString>>;
255
335
  device_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
256
336
  os_image_hash: z.ZodOptional<z.ZodNullable<z.ZodString>>;
337
+ instance_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
257
338
  teepod_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
258
339
  node_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
259
340
  kms_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -272,6 +353,7 @@ declare const provisionCvm: {
272
353
  fmspc: z.ZodOptional<z.ZodNullable<z.ZodString>>;
273
354
  device_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
274
355
  os_image_hash: z.ZodOptional<z.ZodNullable<z.ZodString>>;
356
+ instance_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
275
357
  teepod_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
276
358
  node_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
277
359
  kms_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -15,7 +15,7 @@ export { getKmsList, safeGetKmsList, GetKmsListSchema, GetKmsListRequestSchema,
15
15
  export { nextAppIds, safeNextAppIds, NextAppIdsSchema, NextAppIdsRequestSchema, type NextAppIdsRequest, type NextAppIds, } from "./kms/next_app_ids";
16
16
  export { listWorkspaces, safeListWorkspaces, WorkspaceResponseSchema, ListWorkspacesSchema, PaginationMetadataSchema, type WorkspaceResponse, type ListWorkspaces, type PaginationMetadata, type ListWorkspacesRequest, } from "./workspaces/list_workspaces";
17
17
  export { getWorkspace, safeGetWorkspace, } from "./workspaces/get_workspace";
18
- export { listInstanceTypes, safeListInstanceTypes, PaginatedInstanceTypesSchema, InstanceTypeSchema, type PaginatedInstanceTypes, type InstanceType, type ListInstanceTypesRequest, ListInstanceTypesRequestSchema, } from "./list-instance-types";
18
+ export { listAllInstanceTypeFamilies, safeListAllInstanceTypeFamilies, listFamilyInstanceTypes, safeListFamilyInstanceTypes, AllFamiliesResponseSchema, FamilyInstanceTypesResponseSchema, FamilyGroupSchema, InstanceTypeSchema, ListFamilyInstanceTypesRequestSchema, type AllFamiliesResponse, type FamilyInstanceTypesResponse, type FamilyGroup, type InstanceType, type ListFamilyInstanceTypesRequest, } from "./list-instance-types";
19
19
  export { startCvm, safeStartCvm, StartCvmRequestSchema, type StartCvmRequest, } from "./cvms/start_cvm";
20
20
  export { shutdownCvm, safeShutdownCvm, ShutdownCvmRequestSchema, type ShutdownCvmRequest, } from "./cvms/shutdown_cvm";
21
21
  export { stopCvm, safeStopCvm, StopCvmRequestSchema, type StopCvmRequest, } from "./cvms/stop_cvm";
@@ -61,8 +61,6 @@ export declare const GetKmsListSchema: z.ZodObject<{
61
61
  page_size: z.ZodNumber;
62
62
  pages: z.ZodNumber;
63
63
  }, "strict", z.ZodTypeAny, {
64
- page: number;
65
- page_size: number;
66
64
  items: z.objectOutputType<{
67
65
  id: z.ZodString;
68
66
  slug: z.ZodNullable<z.ZodString>;
@@ -73,10 +71,10 @@ export declare const GetKmsListSchema: z.ZodObject<{
73
71
  gateway_app_id: z.ZodEffects<z.ZodNullable<z.ZodString>, `0x${string}`, string | null>;
74
72
  }, z.ZodTypeAny, "passthrough">[];
75
73
  total: number;
76
- pages: number;
77
- }, {
78
74
  page: number;
79
75
  page_size: number;
76
+ pages: number;
77
+ }, {
80
78
  items: z.objectInputType<{
81
79
  id: z.ZodString;
82
80
  slug: z.ZodNullable<z.ZodString>;
@@ -87,6 +85,8 @@ export declare const GetKmsListSchema: z.ZodObject<{
87
85
  gateway_app_id: z.ZodEffects<z.ZodNullable<z.ZodString>, `0x${string}`, string | null>;
88
86
  }, z.ZodTypeAny, "passthrough">[];
89
87
  total: number;
88
+ page: number;
89
+ page_size: number;
90
90
  pages: number;
91
91
  }>;
92
92
  export type GetKmsListRequest = z.infer<typeof GetKmsListRequestSchema>;