runpod_sdk/model/pod.rs
1use serde::{Deserialize, Serialize};
2
3use super::common::*;
4
5/// A Pod resource representing a containerized compute instance on RunPod.
6///
7/// Pods are the fundamental compute units in RunPod, providing either GPU or CPU-based
8/// computing resources. They can be configured with various specifications including
9/// compute type, memory, storage, networking, and environment settings.
10///
11/// # Examples
12///
13/// ```rust
14/// use runpod_sdk::model::Pod;
15///
16/// // Pod instances are typically obtained from API responses
17/// // when listing, creating, or retrieving pods
18/// ```
19#[derive(Debug, Clone, Serialize, Deserialize)]
20#[serde(rename_all = "camelCase")]
21pub struct Pod {
22 /// A unique string identifying the Pod.
23 pub id: String,
24 /// A user-defined name for the Pod. The name does not need to be unique.
25 pub name: Option<String>,
26 /// The image tag for the container run on the Pod.
27 pub image: Option<String>,
28 /// A unique string identifying the RunPod user who rents the Pod.
29 pub consumer_user_id: Option<String>,
30 /// A unique string identifying the host machine the Pod is running on.
31 pub machine_id: Option<String>,
32 /// The current expected status of the Pod.
33 pub desired_status: Option<PodStatus>,
34 /// The cost in RunPod credits per hour of running the Pod.
35 /// Note that the actual cost may be lower if Savings Plans are applied.
36 #[serde(default)]
37 pub cost_per_hr: f64,
38 /// The effective cost in RunPod credits per hour of running the Pod,
39 /// adjusted by active Savings Plans.
40 #[serde(default)]
41 pub adjusted_cost_per_hr: f64,
42 /// The number of GPUs attached to the Pod (if it's a GPU Pod).
43 pub gpu_count: Option<i32>,
44 /// The number of virtual CPUs attached to the Pod.
45 #[serde(default)]
46 pub vcpu_count: f64,
47 /// The amount of RAM, in gigabytes (GB), attached to the Pod.
48 #[serde(default)]
49 pub memory_in_gb: f64,
50 /// The amount of disk space, in gigabytes (GB), allocated on the container disk.
51 /// The data on the container disk is wiped when the Pod restarts.
52 #[serde(default)]
53 pub container_disk_in_gb: i32,
54 /// The amount of disk space, in gigabytes (GB), allocated on the Pod volume.
55 /// The data on the Pod volume is persisted across Pod restarts.
56 pub volume_in_gb: Option<i32>,
57 /// The absolute path where the network volume is mounted in the filesystem.
58 pub volume_mount_path: Option<String>,
59 /// Whether the local network volume of the Pod is encrypted.
60 /// Can only be set when creating a Pod.
61 #[serde(default)]
62 pub volume_encrypted: bool,
63 /// A list of ports exposed on the Pod. Each port is formatted as
64 /// `[port number]/[protocol]`. Protocol can be either `http` or `tcp`.
65 pub ports: Option<Vec<String>>,
66 /// A mapping of internal ports to public ports on the Pod.
67 /// For example, `{"22": 10341}` means that port 22 on the Pod is mapped
68 /// to port 10341 and is publicly accessible at `[public ip]:10341`.
69 pub port_mappings: Option<PortMappings>,
70 /// The public IP address of the Pod. If the Pod is still initializing,
71 /// this IP is not yet determined and will be empty.
72 pub public_ip: Option<String>,
73 /// Environment variables for the Pod container.
74 pub env: Option<EnvVars>,
75 /// If specified, overrides the ENTRYPOINT for the Docker image run on the Pod.
76 /// If empty, uses the ENTRYPOINT defined in the image.
77 pub docker_entrypoint: Option<Vec<String>>,
78 /// If specified, overrides the start CMD for the Docker image run on the Pod.
79 /// If empty, uses the start CMD defined in the image.
80 pub docker_start_cmd: Option<Vec<String>>,
81 /// Describes how the Pod is rented. An interruptible Pod can be rented at
82 /// a lower cost but can be stopped at any time to free up resources for
83 /// another Pod. A reserved Pod is rented at a higher cost but runs until
84 /// it exits or is manually stopped.
85 #[serde(default)]
86 pub interruptible: bool,
87 /// Whether the Pod is locked. Locking a Pod disables stopping or resetting it.
88 #[serde(default)]
89 pub locked: bool,
90 /// GPU information if the Pod has GPUs attached.
91 pub gpu: Option<GpuInfo>,
92 /// If the Pod is a CPU Pod, the unique string identifying the CPU flavor
93 /// the Pod is running on.
94 pub cpu_flavor_id: Option<String>,
95 /// The GPU type ID if the Pod has GPUs attached.
96 pub gpu_type_id: Option<String>,
97 /// If the Pod is created with a template, the unique string identifying that template.
98 pub template_id: Option<String>,
99 /// The unique string identifying the network volume attached to the Pod, if any.
100 pub network_volume_id: Option<String>,
101 /// If the Pod is created with a container registry auth, the unique string
102 /// identifying that container registry auth.
103 pub container_registry_auth_id: Option<String>,
104 /// If the Pod is a Serverless worker, a unique string identifying the
105 /// associated endpoint.
106 pub endpoint_id: Option<String>,
107 /// Synonym for `endpoint_id` (legacy name).
108 pub ai_api_id: Option<String>,
109 /// If the Pod is a Serverless worker, the version of the associated endpoint.
110 pub sls_version: Option<i32>,
111 /// The UTC timestamp when the Pod was last started.
112 pub last_started_at: Option<String>,
113 /// A string describing the last lifecycle event on the Pod.
114 pub last_status_change: Option<String>,
115 /// Information about the machine the Pod is running on.
116 pub machine: Option<Machine>,
117 /// If a network volume is attached to the Pod, information about the network volume.
118 pub network_volume: Option<NetworkVolume>,
119 /// The list of active Savings Plans applied to the Pod. If none are applied, the list is empty.
120 pub savings_plans: Option<Vec<SavingsPlan>>,
121}
122
123/// List of pods.
124pub type Pods = Vec<Pod>;
125
126/// Input parameters for creating a new Pod.
127///
128/// This struct contains all the configuration options available when creating a Pod,
129/// including compute specifications, networking, storage, and deployment preferences.
130/// Most fields are optional and will use RunPod defaults if not specified.
131///
132/// # Examples
133///
134/// ```rust
135/// use runpod_sdk::model::{PodCreateInput, ComputeType, CloudType};
136///
137/// let create_input = PodCreateInput {
138/// name: Some("my-pod".to_string()),
139/// image_name: Some("runpod/pytorch:latest".to_string()),
140/// compute_type: Some(ComputeType::Gpu),
141/// cloud_type: Some(CloudType::Secure),
142/// ..Default::default()
143/// };
144/// ```
145#[derive(Debug, Clone, Default, Serialize, Deserialize)]
146#[serde(rename_all = "camelCase")]
147pub struct PodCreateInput {
148 /// If the created Pod is a GPU Pod, a list of acceptable CUDA versions.
149 /// If not set, any CUDA version is acceptable.
150 #[serde(skip_serializing_if = "Option::is_none")]
151 pub allowed_cuda_versions: Option<Vec<CudaVersion>>,
152 /// Set to `SECURE` to create the Pod in Secure Cloud. Set to `COMMUNITY`
153 /// to create the Pod in Community Cloud.
154 #[serde(skip_serializing_if = "Option::is_none")]
155 pub cloud_type: Option<CloudType>,
156 /// Set to `GPU` to create a GPU Pod. Set to `CPU` to create a CPU Pod.
157 /// If set to `CPU`, the Pod will not have a GPU attached and GPU-related
158 /// properties will be ignored.
159 #[serde(skip_serializing_if = "Option::is_none")]
160 pub compute_type: Option<ComputeType>,
161 /// The amount of disk space, in gigabytes (GB), to allocate on the container disk.
162 /// The data on the container disk is wiped when the Pod restarts.
163 #[serde(skip_serializing_if = "Option::is_none")]
164 pub container_disk_in_gb: Option<i32>,
165 /// Registry credentials ID for private container registries.
166 #[serde(skip_serializing_if = "Option::is_none")]
167 pub container_registry_auth_id: Option<String>,
168 /// A list of country codes where the created Pod can be located.
169 /// If not set, the Pod can be located in any country.
170 #[serde(skip_serializing_if = "Option::is_none")]
171 pub country_codes: Option<Vec<String>>,
172 /// If the created Pod is a CPU Pod, a list of RunPod CPU flavors which
173 /// can be attached to the Pod. The order determines the rental priority.
174 #[serde(skip_serializing_if = "Option::is_none")]
175 pub cpu_flavor_ids: Option<Vec<CpuFlavorId>>,
176 /// If the created Pod is a CPU Pod, set to `availability` to respond to
177 /// current CPU flavor availability. Set to `custom` to always try to rent
178 /// CPU flavors in the order specified in `cpu_flavor_ids`.
179 #[serde(skip_serializing_if = "Option::is_none")]
180 pub cpu_flavor_priority: Option<String>,
181 /// A list of RunPod data center IDs where the created Pod can be located.
182 #[serde(skip_serializing_if = "Option::is_none")]
183 pub data_center_ids: Option<Vec<DataCenterId>>,
184 /// Set to `availability` to respond to current machine availability.
185 /// Set to `custom` to always try to rent machines from data centers
186 /// in the order specified in `data_center_ids`.
187 #[serde(skip_serializing_if = "Option::is_none")]
188 pub data_center_priority: Option<String>,
189 /// If specified, overrides the ENTRYPOINT for the Docker image.
190 /// If empty, uses the ENTRYPOINT defined in the image.
191 #[serde(skip_serializing_if = "Option::is_none")]
192 pub docker_entrypoint: Option<Vec<String>>,
193 /// If specified, overrides the start CMD for the Docker image.
194 /// If empty, uses the start CMD defined in the image.
195 #[serde(skip_serializing_if = "Option::is_none")]
196 pub docker_start_cmd: Option<Vec<String>>,
197 /// Environment variables for the Pod container.
198 #[serde(skip_serializing_if = "Option::is_none")]
199 pub env: Option<EnvVars>,
200 /// Set to true to enable global networking for the created Pod.
201 /// Currently only available for On-Demand GPU Pods on some Secure Cloud data centers.
202 #[serde(skip_serializing_if = "Option::is_none")]
203 pub global_networking: Option<bool>,
204 /// If the created Pod is a GPU Pod, the number of GPUs attached to the Pod.
205 #[serde(skip_serializing_if = "Option::is_none")]
206 pub gpu_count: Option<i32>,
207 /// If the created Pod is a GPU Pod, a list of RunPod GPU types which
208 /// can be attached to the Pod. The order determines the rental priority.
209 #[serde(skip_serializing_if = "Option::is_none")]
210 pub gpu_type_ids: Option<Vec<GpuTypeId>>,
211 /// If the created Pod is a GPU Pod, set to `availability` to respond to
212 /// current GPU type availability. Set to `custom` to always try to rent
213 /// GPU types in the order specified in `gpu_type_ids`.
214 #[serde(skip_serializing_if = "Option::is_none")]
215 pub gpu_type_priority: Option<String>,
216 /// The image tag for the container run on the created Pod.
217 #[serde(skip_serializing_if = "Option::is_none")]
218 pub image_name: Option<String>,
219 /// Set to true to create an interruptible or spot Pod. An interruptible Pod
220 /// can be rented at a lower cost but can be stopped at any time to free up
221 /// resources for another Pod.
222 #[serde(skip_serializing_if = "Option::is_none")]
223 pub interruptible: Option<bool>,
224 /// Set to true to lock the Pod. Locking a Pod disables stopping or resetting it.
225 #[serde(skip_serializing_if = "Option::is_none")]
226 pub locked: Option<bool>,
227 /// The minimum disk bandwidth, in megabytes per second (MBps), for the created Pod.
228 #[serde(skip_serializing_if = "Option::is_none")]
229 pub min_disk_bandwidth_m_bps: Option<f64>,
230 /// The minimum download speed, in megabits per second (Mbps), for the created Pod.
231 #[serde(skip_serializing_if = "Option::is_none")]
232 pub min_download_mbps: Option<f64>,
233 /// If the created Pod is a GPU Pod, the minimum amount of RAM, in gigabytes (GB),
234 /// allocated to the Pod for each GPU attached.
235 #[serde(skip_serializing_if = "Option::is_none")]
236 pub min_ram_per_gpu: Option<i32>,
237 /// The minimum upload speed, in megabits per second (Mbps), for the created Pod.
238 #[serde(skip_serializing_if = "Option::is_none")]
239 pub min_upload_mbps: Option<f64>,
240 /// If the created Pod is a GPU Pod, the minimum number of virtual CPUs
241 /// allocated to the Pod for each GPU attached.
242 #[serde(skip_serializing_if = "Option::is_none")]
243 pub min_vcpu_per_gpu: Option<i32>,
244 /// A user-defined name for the created Pod. The name does not need to be unique.
245 #[serde(skip_serializing_if = "Option::is_none")]
246 pub name: Option<String>,
247 /// The unique string identifying the network volume to attach to the created Pod.
248 /// If attached, a network volume replaces the Pod network volume.
249 #[serde(skip_serializing_if = "Option::is_none")]
250 pub network_volume_id: Option<String>,
251 /// A list of ports exposed on the created Pod. Each port is formatted as
252 /// `[port number]/[protocol]`. Protocol can be either `http` or `tcp`.
253 #[serde(skip_serializing_if = "Option::is_none")]
254 pub ports: Option<Vec<String>>,
255 /// If the created Pod is on Community Cloud, set to true if you need the Pod
256 /// to expose a public IP address. On Secure Cloud, the Pod will always have
257 /// a public IP address.
258 #[serde(skip_serializing_if = "Option::is_none")]
259 pub support_public_ip: Option<bool>,
260 /// If the Pod is created with a template, the unique string identifying that template.
261 #[serde(skip_serializing_if = "Option::is_none")]
262 pub template_id: Option<String>,
263 /// If the created Pod is a CPU Pod, the number of vCPUs allocated to the Pod.
264 #[serde(skip_serializing_if = "Option::is_none")]
265 pub vcpu_count: Option<i32>,
266 /// The amount of disk space, in gigabytes (GB), to allocate on the Pod volume.
267 /// The data on the Pod volume is persisted across Pod restarts.
268 #[serde(skip_serializing_if = "Option::is_none")]
269 pub volume_in_gb: Option<i32>,
270 /// The absolute path where the network volume will be mounted in the filesystem.
271 #[serde(skip_serializing_if = "Option::is_none")]
272 pub volume_mount_path: Option<String>,
273}
274
275/// Input parameters for updating an existing Pod.
276///
277/// This struct contains the configuration options that can be modified for
278/// an existing Pod. Note that updating a Pod will trigger a reset.
279///
280/// # Examples
281///
282/// ```rust
283/// use runpod_sdk::model::PodUpdateInput;
284///
285/// let update_input = PodUpdateInput {
286/// name: Some("updated-pod-name".to_string()),
287/// locked: Some(true),
288/// ..Default::default()
289/// };
290/// ```
291#[derive(Debug, Clone, Default, Serialize, Deserialize)]
292#[serde(rename_all = "camelCase")]
293pub struct PodUpdateInput {
294 /// The amount of disk space, in gigabytes (GB), to allocate on the container disk.
295 /// The data on the container disk is wiped when the Pod restarts.
296 #[serde(skip_serializing_if = "Option::is_none")]
297 pub container_disk_in_gb: Option<i32>,
298 /// Registry credentials ID for private container registries.
299 #[serde(skip_serializing_if = "Option::is_none")]
300 pub container_registry_auth_id: Option<String>,
301 /// If specified, overrides the ENTRYPOINT for the Docker image.
302 /// If empty, uses the ENTRYPOINT defined in the image.
303 #[serde(skip_serializing_if = "Option::is_none")]
304 pub docker_entrypoint: Option<Vec<String>>,
305 /// If specified, overrides the start CMD for the Docker image.
306 /// If empty, uses the start CMD defined in the image.
307 #[serde(skip_serializing_if = "Option::is_none")]
308 pub docker_start_cmd: Option<Vec<String>>,
309 /// Environment variables for the Pod container.
310 #[serde(skip_serializing_if = "Option::is_none")]
311 pub env: Option<EnvVars>,
312 /// Set to true to enable global networking for the Pod.
313 /// Currently only available for On-Demand GPU Pods on some Secure Cloud data centers.
314 #[serde(skip_serializing_if = "Option::is_none")]
315 pub global_networking: Option<bool>,
316 /// The image tag for the container run on the Pod.
317 #[serde(skip_serializing_if = "Option::is_none")]
318 pub image_name: Option<String>,
319 /// Set to true to lock the Pod. Locking a Pod disables stopping or resetting it.
320 #[serde(skip_serializing_if = "Option::is_none")]
321 pub locked: Option<bool>,
322 /// A user-defined name for the Pod. The name does not need to be unique.
323 #[serde(skip_serializing_if = "Option::is_none")]
324 pub name: Option<String>,
325 /// A list of ports exposed on the Pod. Each port is formatted as
326 /// `[port number]/[protocol]`. Protocol can be either `http` or `tcp`.
327 #[serde(skip_serializing_if = "Option::is_none")]
328 pub ports: Option<Vec<String>>,
329 /// The amount of disk space, in gigabytes (GB), to allocate on the Pod volume.
330 /// The data on the Pod volume is persisted across Pod restarts.
331 #[serde(skip_serializing_if = "Option::is_none")]
332 pub volume_in_gb: Option<i32>,
333 /// The absolute path where the network volume will be mounted in the filesystem.
334 #[serde(skip_serializing_if = "Option::is_none")]
335 pub volume_mount_path: Option<String>,
336}
337
338/// Query parameters for filtering and configuring Pod list operations.
339///
340/// This struct provides various filters and options for customizing the
341/// response when listing Pods.
342///
343/// # Examples
344///
345/// ```rust
346/// use runpod_sdk::model::{ListPodsQuery, ComputeType, PodStatus};
347///
348/// let query = ListPodsQuery {
349/// compute_type: Some(ComputeType::Gpu),
350/// desired_status: Some(PodStatus::Running),
351/// include_machine: Some(true),
352/// ..Default::default()
353/// };
354/// ```
355#[derive(Debug, Clone, Default, Serialize)]
356#[serde(rename_all = "camelCase")]
357pub struct ListPodsQuery {
358 /// Filter to only GPU or only CPU Pods.
359 #[serde(skip_serializing_if = "Option::is_none")]
360 pub compute_type: Option<ComputeType>,
361 /// Filter to CPU Pods with any of the listed CPU flavors.
362 #[serde(skip_serializing_if = "Option::is_none")]
363 pub cpu_flavor_id: Option<Vec<CpuFlavorId>>,
364 /// Filter to Pods located in any of the provided RunPod data centers.
365 #[serde(skip_serializing_if = "Option::is_none")]
366 pub data_center_id: Option<Vec<DataCenterId>>,
367 /// Filter to Pods currently in the provided state.
368 #[serde(skip_serializing_if = "Option::is_none")]
369 pub desired_status: Option<PodStatus>,
370 /// Filter to workers on the provided Serverless endpoint.
371 /// Note that endpoint workers are not included in the response by default.
372 #[serde(skip_serializing_if = "Option::is_none")]
373 pub endpoint_id: Option<String>,
374 /// Filter to Pods with any of the listed GPU types attached.
375 #[serde(skip_serializing_if = "Option::is_none")]
376 pub gpu_type_id: Option<Vec<GpuTypeId>>,
377 /// Filter to a specific Pod.
378 #[serde(skip_serializing_if = "Option::is_none")]
379 pub id: Option<String>,
380 /// Filter to Pods created with the provided image.
381 #[serde(skip_serializing_if = "Option::is_none")]
382 pub image_name: Option<String>,
383 /// Include information about the machine the Pod is running on.
384 #[serde(skip_serializing_if = "Option::is_none")]
385 pub include_machine: Option<bool>,
386 /// Include information about the network volume attached to the Pod, if any.
387 #[serde(skip_serializing_if = "Option::is_none")]
388 pub include_network_volume: Option<bool>,
389 /// Include information about the savings plans applied to the Pod.
390 #[serde(skip_serializing_if = "Option::is_none")]
391 pub include_savings_plans: Option<bool>,
392 /// Include information about the template the Pod uses, if any.
393 #[serde(skip_serializing_if = "Option::is_none")]
394 pub include_template: Option<bool>,
395 /// Set to true to also list Pods which are Serverless workers.
396 #[serde(skip_serializing_if = "Option::is_none")]
397 pub include_workers: Option<bool>,
398 /// Filter to Pods with the provided name.
399 #[serde(skip_serializing_if = "Option::is_none")]
400 pub name: Option<String>,
401 /// Filter to Pods with the provided network volume attached.
402 #[serde(skip_serializing_if = "Option::is_none")]
403 pub network_volume_id: Option<String>,
404 /// Filter to Pods created from the provided template.
405 #[serde(skip_serializing_if = "Option::is_none")]
406 pub template_id: Option<String>,
407}
408
409/// Query parameters for retrieving a single Pod.
410///
411/// This struct provides options for customizing the response when retrieving
412/// a specific Pod by ID.
413///
414/// # Examples
415///
416/// ```rust
417/// use runpod_sdk::model::GetPodQuery;
418///
419/// let query = GetPodQuery {
420/// include_machine: Some(true),
421/// include_network_volume: Some(true),
422/// include_savings_plans: Some(true),
423/// ..Default::default()
424/// };
425/// ```
426#[derive(Debug, Clone, Default, Serialize)]
427#[serde(rename_all = "camelCase")]
428pub struct GetPodQuery {
429 /// Include information about the machine the Pod is running on.
430 #[serde(skip_serializing_if = "Option::is_none")]
431 pub include_machine: Option<bool>,
432 /// Include information about the network volume attached to the returned Pod, if any.
433 #[serde(skip_serializing_if = "Option::is_none")]
434 pub include_network_volume: Option<bool>,
435 /// Include information about the savings plans applied to the Pod.
436 #[serde(skip_serializing_if = "Option::is_none")]
437 pub include_savings_plans: Option<bool>,
438 /// Include information about the template the Pod uses, if any.
439 #[serde(skip_serializing_if = "Option::is_none")]
440 pub include_template: Option<bool>,
441 /// Set to true to also list Pods which are Serverless workers.
442 #[serde(skip_serializing_if = "Option::is_none")]
443 pub include_workers: Option<bool>,
444}
445
446#[cfg(test)]
447mod tests {
448 use super::*;
449
450 #[test]
451 fn test_pod_deserialization_from_partial_json() {
452 let pod_json = r#"{"id": "pod-123"}"#;
453 let pod: Pod = serde_json::from_str(pod_json).expect("Failed to deserialize Pod");
454 assert_eq!(pod.id, "pod-123");
455 assert!(pod.image.is_none());
456 assert!(pod.consumer_user_id.is_none());
457 assert!(pod.machine_id.is_none());
458 assert!(pod.desired_status.is_none());
459 assert_eq!(pod.cost_per_hr, 0.0);
460 }
461}