runpod_sdk/model/
template.rs

1use serde::{Deserialize, Serialize};
2
3use super::common::*;
4
5/// Compute category classification for templates.
6///
7/// Templates are categorized based on their primary compute requirements,
8/// which helps with resource allocation, pricing, and filtering in the RunPod ecosystem.
9///
10/// # Categories
11///
12/// - **NVIDIA**: Templates optimized for NVIDIA GPU acceleration
13/// - **AMD**: Templates optimized for AMD GPU acceleration
14/// - **CPU**: Templates for CPU-only compute workloads
15#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
16pub enum TemplateCategory {
17    /// NVIDIA GPU-accelerated compute template.
18    /// Optimized for workloads requiring NVIDIA CUDA capabilities,
19    /// such as deep learning, scientific computing, and graphics processing.
20    #[serde(rename = "NVIDIA")]
21    #[default]
22    Nvidia,
23
24    /// AMD GPU-accelerated compute template.
25    /// Optimized for workloads utilizing AMD GPU acceleration,
26    /// including ROCm-based machine learning and compute applications.
27    #[serde(rename = "AMD")]
28    Amd,
29
30    /// CPU-only compute template.
31    /// Designed for general-purpose computing tasks that don't require
32    /// GPU acceleration, such as web services, data processing, and development.
33    #[serde(rename = "CPU")]
34    Cpu,
35}
36
37/// Template resource containing deployment configuration and metadata.
38///
39/// A Template is a reusable configuration that defines how Pods and Serverless endpoints
40/// should be deployed, including Docker image, resource requirements, environment variables,
41/// and networking settings.
42///
43/// # Template Lifecycle
44///
45/// 1. **Creation**: Define template with [`TemplateCreateInput`]
46/// 2. **Usage**: Reference template when creating Pods or Serverless endpoints
47/// 3. **Updates**: Modify template with [`TemplateUpdateInput`] (triggers rolling releases)
48/// 4. **Sharing**: Make public to share with community and earn revenue
49/// 5. **Management**: Track usage statistics and earnings through template metadata
50///
51/// # Revenue Model
52///
53/// Public templates can generate revenue for their creators:
54///
55/// - Users pay standard RunPod rates for compute resources
56/// - Template creators earn a percentage of compute costs
57/// - Earnings are tracked in the `earned` field
58#[derive(Debug, Clone, Serialize, Deserialize)]
59#[serde(rename_all = "camelCase")]
60pub struct Template {
61    /// A unique string identifying the template.
62    /// This ID is used to reference the template when creating Pods or Serverless endpoints.
63    pub id: String,
64
65    /// A user-defined name for the template.
66    /// The name must be unique within your account and should be descriptive
67    /// of the template's purpose or use case.
68    pub name: String,
69
70    /// The Docker image tag for containers deployed from this template.
71    /// Can reference public images from Docker Hub, private registry images,
72    /// or images from other container registries with appropriate authentication.
73    pub image_name: String,
74
75    /// Whether the template is visible to other RunPod users.
76    /// - `true`: Template is public and can be used by any RunPod user
77    /// - `false`: Template is private and only accessible to the creator
78    pub is_public: bool,
79
80    /// Whether this is an official template managed by RunPod.
81    /// Official templates are curated, maintained, and optimized by the RunPod team
82    /// for popular frameworks and use cases.
83    pub is_runpod: bool,
84
85    /// Whether the template is designed for Serverless workers or Pods.
86    /// - `true`: Template creates Serverless workers (auto-scaling, event-driven)
87    /// - `false`: Template creates Pods (persistent, long-running instances)
88    pub is_serverless: bool,
89
90    /// The compute category of resources defined by this template.
91    /// Determines the type of hardware acceleration available to deployed instances.
92    pub category: Option<TemplateCategory>,
93
94    /// The amount of disk space, in gigabytes (GB), allocated on the container disk.
95    /// Container disk provides fast local storage but data is wiped when instances restart.
96    /// Use for temporary files, caches, and application data that doesn't need persistence.
97    pub container_disk_in_gb: i32,
98
99    /// The unique identifier for container registry authentication.
100    /// Required when the template uses private Docker images that need authentication
101    /// to pull from protected container registries.
102    pub container_registry_auth_id: Option<String>,
103
104    /// Override for the Docker image ENTRYPOINT.
105    /// If specified, replaces the ENTRYPOINT defined in the Docker image.
106    /// If `None` or empty, uses the ENTRYPOINT from the Docker image.
107    pub docker_entrypoint: Option<Vec<String>>,
108
109    /// Override for the Docker image start command.
110    /// If specified, replaces the CMD defined in the Docker image.
111    /// If `None` or empty, uses the CMD from the Docker image.
112    pub docker_start_cmd: Option<Vec<String>>,
113
114    /// The total RunPod credits earned by the template creator.
115    /// Represents cumulative earnings from all Pods and Serverless workers
116    /// created from this template by other users. Only applies to public templates.
117    pub earned: Option<f64>,
118
119    /// Environment variables to be set in containers deployed from this template.
120    /// These variables are available to the running application and can be used
121    /// for configuration, secrets management, and runtime customization.
122    pub env: Option<EnvVars>,
123
124    /// A list of ports exposed on deployed Pods or Serverless workers.
125    /// Each port is formatted as `[port number]/[protocol]` where protocol
126    /// can be either `http` or `tcp`. Example: `["8888/http", "22/tcp"]`
127    pub ports: Option<Vec<String>>,
128
129    /// Markdown-formatted documentation for the template.
130    /// Displayed in the RunPod UI when users browse or select templates.
131    /// Should include usage instructions, requirements, and configuration details.
132    pub readme: Option<String>,
133
134    /// Runtime statistics for the template (in minutes).
135    /// Tracks total runtime across all instances deployed from this template.
136    /// Used for usage analytics and optimization insights.
137    pub runtime_in_min: Option<i32>,
138
139    /// The amount of disk space, in gigabytes (GB), allocated on the local Pod volume.
140    /// Pod volume provides persistent local storage that survives instance restarts.
141    /// Use for data, models, and files that need to persist across restarts.
142    pub volume_in_gb: i32,
143
144    /// The absolute filesystem path where the Pod volume is mounted.
145    /// This is where the persistent storage will be accessible within the container.
146    /// Common paths include `/workspace`, `/data`, or `/app/storage`.
147    pub volume_mount_path: String,
148}
149
150/// Collection of template records.
151///
152/// This type alias represents the standard response format when listing templates,
153/// containing an array of [`Template`] instances with applied filters and access controls.
154pub type Templates = Vec<Template>;
155
156/// Input parameters for creating new templates.
157///
158/// Use this struct to define all aspects of a new template, from basic identification
159/// to detailed runtime configuration. All fields except `name` and `image_name` are optional,
160/// allowing for flexible template creation with sensible defaults.
161///
162/// # Required Fields
163///
164/// - `name`: Unique, descriptive template name
165/// - `image_name`: Docker image for container deployment
166///
167/// # Default Behavior
168///
169/// When optional fields are omitted:
170/// - `category`: Defaults to `TemplateCategory::Nvidia`
171/// - `container_disk_in_gb`: Defaults to 50 GB
172/// - `volume_in_gb`: Defaults to 20 GB
173/// - `volume_mount_path`: Defaults to "/workspace"
174/// - `is_public`: Defaults to `false` (private template)
175/// - `is_serverless`: Defaults to `false` (Pod template)
176/// - `ports`: Defaults to `["8888/http", "22/tcp"]`
177///
178/// # Examples
179///
180/// ```rust
181/// use runpod_sdk::model::{TemplateCreateInput, TemplateCategory};
182///
183/// let basic_template = TemplateCreateInput {
184///     name: "My Basic Template".to_string(),
185///     image_name: "python:3.9".to_string(),
186///     ..Default::default()
187/// };
188/// ```
189#[derive(Debug, Default, Clone, Serialize, Deserialize)]
190#[serde(rename_all = "camelCase")]
191pub struct TemplateCreateInput {
192    /// A user-defined name for the template.
193    /// Must be unique within your account. Choose a descriptive name that
194    /// clearly identifies the template's purpose or use case.
195    pub name: String,
196
197    /// The Docker image tag for containers deployed from this template.
198    /// Can be a public image (e.g., "python:3.9") or private image with
199    /// appropriate `container_registry_auth_id` for authentication.
200    pub image_name: String,
201
202    /// The compute category for this template.
203    /// Determines the type of hardware acceleration available.
204    /// Defaults to `TemplateCategory::Nvidia` if not specified.
205    #[serde(skip_serializing_if = "Option::is_none")]
206    pub category: Option<TemplateCategory>,
207
208    /// The amount of disk space in GB to allocate for the container disk.
209    /// Container disk provides fast local storage but data is wiped on restart.
210    /// Defaults to 50 GB if not specified.
211    #[serde(skip_serializing_if = "Option::is_none")]
212    pub container_disk_in_gb: Option<i32>,
213
214    /// The unique identifier for container registry authentication.
215    /// Required when using private Docker images that need authentication.
216    /// Reference the ID from a previously created container registry auth.
217    #[serde(skip_serializing_if = "Option::is_none")]
218    pub container_registry_auth_id: Option<String>,
219
220    /// Override for the Docker image ENTRYPOINT.
221    /// If specified, replaces the ENTRYPOINT defined in the Docker image.
222    /// Leave empty to use the image's default ENTRYPOINT.
223    #[serde(skip_serializing_if = "Option::is_none")]
224    pub docker_entrypoint: Option<Vec<String>>,
225
226    /// Override for the Docker image start command.
227    /// If specified, replaces the CMD defined in the Docker image.
228    /// Leave empty to use the image's default CMD.
229    #[serde(skip_serializing_if = "Option::is_none")]
230    pub docker_start_cmd: Option<Vec<String>>,
231
232    /// Environment variables for containers deployed from this template.
233    /// These variables are set in the container environment and available
234    /// to the running application for configuration and customization.
235    #[serde(skip_serializing_if = "Option::is_none")]
236    pub env: Option<EnvVars>,
237
238    /// Whether the template should be visible to other RunPod users.
239    /// - `true`: Template is public and can generate revenue when used by others
240    /// - `false`: Template is private and only accessible to you (default)
241    #[serde(skip_serializing_if = "Option::is_none")]
242    pub is_public: Option<bool>,
243
244    /// Whether the template is designed for Serverless workers or Pods.
245    /// - `true`: Creates auto-scaling Serverless workers for event-driven workloads
246    /// - `false`: Creates persistent Pods for long-running workloads (default)
247    #[serde(skip_serializing_if = "Option::is_none")]
248    pub is_serverless: Option<bool>,
249
250    /// A list of ports to expose on deployed instances.
251    /// Each port is formatted as `[port]/[protocol]` (e.g., "8888/http", "22/tcp").
252    /// Defaults to `["8888/http", "22/tcp"]` if not specified.
253    #[serde(skip_serializing_if = "Option::is_none")]
254    pub ports: Option<Vec<String>>,
255
256    /// Markdown-formatted documentation describing the template.
257    /// Displayed in the RunPod UI and should include usage instructions,
258    /// requirements, configuration details, and examples.
259    #[serde(skip_serializing_if = "Option::is_none")]
260    pub readme: Option<String>,
261
262    /// The amount of disk space in GB to allocate on the local Pod volume.
263    /// Pod volume provides persistent storage that survives instance restarts.
264    /// Defaults to 20 GB if not specified.
265    #[serde(skip_serializing_if = "Option::is_none")]
266    pub volume_in_gb: Option<i32>,
267
268    /// The absolute path where the Pod volume will be mounted in the container.
269    /// This is where persistent storage will be accessible within the container.
270    /// Defaults to "/workspace" if not specified.
271    #[serde(skip_serializing_if = "Option::is_none")]
272    pub volume_mount_path: Option<String>,
273}
274
275/// Input parameters for updating existing templates.
276///
277/// Use this struct to modify template configuration. Template updates automatically
278/// trigger rolling releases for any associated Serverless endpoints, ensuring
279/// deployed instances use the latest configuration.
280///
281/// # Rolling Release Behavior
282///
283/// When a template is updated:
284/// 1. New instances are created with the updated configuration
285/// 2. Traffic is gradually shifted to new instances
286/// 3. Old instances are gracefully terminated
287/// 4. The process ensures zero-downtime updates for Serverless endpoints
288///
289/// # Partial Updates
290///
291/// All fields are optional, allowing for partial updates. Only specified fields
292/// will be changed; unspecified fields retain their current values.
293///
294/// # Examples
295///
296/// ```rust
297/// use runpod_sdk::model::TemplateUpdateInput;
298///
299/// // Update only the Docker image
300/// let image_update = TemplateUpdateInput {
301///     image_name: Some("myapp:v2.0.0".to_string()),
302///     ..Default::default()
303/// };
304///
305/// // Update storage allocation and environment variables
306/// let config_update = TemplateUpdateInput {
307///     container_disk_in_gb: Some(100),
308///     volume_in_gb: Some(50),
309///     env: Some({
310///         let mut env = std::collections::HashMap::new();
311///         env.insert("MODEL_VERSION".to_string(), "v2.0".to_string());
312///         env.insert("BATCH_SIZE".to_string(), "32".to_string());
313///         env
314///     }),
315///     ..Default::default()
316/// };
317/// ```
318#[derive(Debug, Clone, Default, Serialize, Deserialize)]
319#[serde(rename_all = "camelCase")]
320pub struct TemplateUpdateInput {
321    /// Update the amount of disk space in GB for the container disk.
322    /// Container disk provides fast local storage but data is wiped on restart.
323    #[serde(skip_serializing_if = "Option::is_none")]
324    pub container_disk_in_gb: Option<i32>,
325
326    /// Update the container registry authentication ID.
327    /// Use when changing to a private image that requires different credentials.
328    #[serde(skip_serializing_if = "Option::is_none")]
329    pub container_registry_auth_id: Option<String>,
330
331    /// Update the Docker image ENTRYPOINT override.
332    /// Specify new entrypoint commands or set to empty to use image default.
333    #[serde(skip_serializing_if = "Option::is_none")]
334    pub docker_entrypoint: Option<Vec<String>>,
335
336    /// Update the Docker image start command override.
337    /// Specify new start commands or set to empty to use image default.
338    #[serde(skip_serializing_if = "Option::is_none")]
339    pub docker_start_cmd: Option<Vec<String>>,
340
341    /// Update environment variables for the template.
342    /// Completely replaces existing environment variables with the provided set.
343    #[serde(skip_serializing_if = "Option::is_none")]
344    pub env: Option<EnvVars>,
345
346    /// Update the Docker image tag for the template.
347    /// This is commonly updated to deploy new versions of applications.
348    /// Triggers rolling release for associated Serverless endpoints.
349    #[serde(skip_serializing_if = "Option::is_none")]
350    pub image_name: Option<String>,
351
352    /// Update the template's public visibility.
353    /// - `true`: Make template public (enables revenue sharing)
354    /// - `false`: Make template private (restricts access to creator)
355    #[serde(skip_serializing_if = "Option::is_none")]
356    pub is_public: Option<bool>,
357
358    /// Update the template name.
359    /// New name must be unique within your account.
360    #[serde(skip_serializing_if = "Option::is_none")]
361    pub name: Option<String>,
362
363    /// Update the list of exposed ports.
364    /// Each port is formatted as `[port]/[protocol]` (e.g., "8000/http").
365    /// Completely replaces existing port configuration.
366    #[serde(skip_serializing_if = "Option::is_none")]
367    pub ports: Option<Vec<String>>,
368
369    /// Update the template documentation.
370    /// Provide new markdown-formatted description, usage instructions,
371    /// and configuration details for the template.
372    #[serde(skip_serializing_if = "Option::is_none")]
373    pub readme: Option<String>,
374
375    /// Update the amount of disk space in GB for the Pod volume.
376    /// Pod volume provides persistent storage that survives instance restarts.
377    #[serde(skip_serializing_if = "Option::is_none")]
378    pub volume_in_gb: Option<i32>,
379
380    /// Update the Pod volume mount path.
381    /// The absolute path where persistent storage will be accessible
382    /// within containers deployed from this template.
383    #[serde(skip_serializing_if = "Option::is_none")]
384    pub volume_mount_path: Option<String>,
385}
386
387/// Query parameters for listing templates with filtering options.
388///
389/// Control which templates are included in the response based on their
390/// type, visibility, and binding status. All parameters are optional
391/// and default to `false`, meaning only your private templates are returned by default.
392///
393/// # Filtering Strategy
394///
395/// Templates are categorized into different groups:
396/// - **Private Templates**: Your own private templates (always included)
397/// - **Public Templates**: Community-created public templates
398/// - **RunPod Templates**: Official templates maintained by RunPod
399/// - **Endpoint-bound Templates**: Templates currently used by Serverless endpoints
400///
401/// # Examples
402///
403/// ```rust
404/// use runpod_sdk::model::ListTemplatesQuery;
405///
406/// // Get all available templates (private + public + official)
407/// let all_templates = ListTemplatesQuery {
408///     include_public_templates: Some(true),
409///     include_runpod_templates: Some(true),
410///     include_endpoint_bound_templates: Some(true),
411/// };
412///
413/// // Get only official RunPod templates
414/// let official_only = ListTemplatesQuery {
415///     include_runpod_templates: Some(true),
416///     ..Default::default()
417/// };
418/// ```
419#[derive(Debug, Clone, Default, Serialize)]
420#[serde(rename_all = "camelCase")]
421pub struct ListTemplatesQuery {
422    /// Include templates that are currently bound to Serverless endpoints.
423    /// These templates are actively in use and may have restrictions on modification.
424    /// Defaults to `false` if not specified.
425    #[serde(skip_serializing_if = "Option::is_none")]
426    pub include_endpoint_bound_templates: Option<bool>,
427
428    /// Include community-made public templates in the response.
429    /// Public templates can be used by anyone and may generate revenue for their creators.
430    /// Defaults to `false` if not specified.
431    #[serde(skip_serializing_if = "Option::is_none")]
432    pub include_public_templates: Option<bool>,
433
434    /// Include official RunPod templates in the response.
435    /// These are curated, maintained, and optimized templates provided by RunPod
436    /// for popular frameworks and common use cases.
437    /// Defaults to `false` if not specified.
438    #[serde(skip_serializing_if = "Option::is_none")]
439    pub include_runpod_templates: Option<bool>,
440}
441
442/// Query parameters for retrieving individual templates with filtering options.
443///
444/// Similar to [`ListTemplatesQuery`] but for single template retrieval.
445/// Controls access to templates based on their type and visibility.
446/// Useful when you need to access a specific template that might be public or official.
447///
448/// # Access Control
449///
450/// By default, only your own private templates are accessible. To access
451/// public or official templates, you must explicitly enable the corresponding flags.
452///
453/// # Examples
454///
455/// ```rust
456/// use runpod_sdk::model::GetTemplateQuery;
457///
458/// // Access any type of template
459/// let query = GetTemplateQuery {
460///     include_public_templates: Some(true),
461///     include_runpod_templates: Some(true),
462///     include_endpoint_bound_templates: Some(true),
463/// };
464/// ```
465#[derive(Debug, Clone, Default, Serialize)]
466#[serde(rename_all = "camelCase")]
467pub struct GetTemplateQuery {
468    /// Include templates bound to Serverless endpoints in the search scope.
469    /// Required if the target template is currently bound to an endpoint.
470    /// Defaults to `false` if not specified.
471    #[serde(skip_serializing_if = "Option::is_none")]
472    pub include_endpoint_bound_templates: Option<bool>,
473
474    /// Include public templates in the search scope.
475    /// Required if the target template is a community-created public template.
476    /// Defaults to `false` if not specified.
477    #[serde(skip_serializing_if = "Option::is_none")]
478    pub include_public_templates: Option<bool>,
479
480    /// Include official RunPod templates in the search scope.
481    /// Required if the target template is an official RunPod template.
482    /// Defaults to `false` if not specified.
483    #[serde(skip_serializing_if = "Option::is_none")]
484    pub include_runpod_templates: Option<bool>,
485}
runpod_sdk/model/template.rs

runpod_sdk/model/
template.rs
