merge pod template content, update page filenames

cosmicBboy · cosmicBboy · commit 493fd8043261 · 2025-12-22T13:48:13.000-05:00
Signed-off-by: Niels Bantilan &lt;niels.bantilan@gmail.com&gt;
diff --git a/content/user-guide/task-configuration/pod-templates.md b/content/user-guide/task-configuration/pod-templates.md
@@ -6,46 +6,251 @@ variants: +flyte +serverless +byoc +selfmanaged
 
 # Pod templates
 
-The `pod_template` parameter in `TaskEnvironment` (and in the @env.task decorator, if you are overriding) allows you to customize the Kubernetes pod specification that will be used to run your tasks.
-This provides fine-grained control over the underlying Kubernetes resources, enabling you to configure advanced pod settings like image pull secrets, environment variables, labels, annotations, and other pod-level configurations.
+Flyte is built on Kubernetes and leverages its powerful container orchestration capabilities. A Kubernetes [pod](https://kubernetes.io/docs/concepts/workloads/pods/) is a group of one or more containers that share storage and network resources. While Flyte automatically runs your task code in a container, pod templates let you customize the entire pod specification for advanced use cases.
 
-## Overview
+The `pod_template` parameter in `TaskEnvironment` allows you to:
 
-Pod templates in Flyte allow you to:
+- **Add sidecar containers**: Run metrics exporters, service proxies, or specialized services alongside your task
+- **Mount volumes**: Attach persistent storage or cloud storage like GCS or S3
+- **Configure metadata**: Set custom labels and annotations for monitoring, routing, or cluster policies
+- **Manage resources**: Configure resource requests, limits, and affinities
+- **Inject configuration**: Add secrets, environment variables, or config maps
+- **Access private registries**: Specify image pull secrets
 
-- **Configure pod metadata**: Set custom labels and annotations for your pods.
-- **Specify image pull secrets**: Access private container registries.
-- **Set environment variables**: Configure container-level environment variables.
-- **Customize pod specifications**: Define advanced Kubernetes pod settings.
-- **Control container configurations**: Specify primary container settings.
+## How it works
 
-The `pod_template` parameter accepts either a string reference or a `PodTemplate` object that defines the complete pod specification.
+When you define a pod template:
+
+1. **Primary container**: Flyte automatically injects your task code into the container specified by `primary_container_name` (default: `"primary"`)
+2. **Automatic monitoring**: Flyte watches the primary container and exits the entire pod when it completes
+3. **Image handling**: The image for your task environment is built automatically by Flyte; images for sidecar containers must be provided by you
+4. **Local execution**: When running locally, only the task code executes—additional containers are not started
+
+## Requirements
+
+To use pod templates, install the Kubernetes Python client:
+
+```bash
+pip install kubernetes
+```
+
+Or add it to your image dependencies:
+
+```python
+image = flyte.Image.from_debian_base().with_pip_packages("kubernetes")
+```
 
 ## Basic usage
 
-Here's a complete example showing how to use pod templates with a `TaskEnvironment`:
+Here's a complete example showing how to configure labels, annotations, environment variables, and image pull secrets:
 
 {{< code file="/external/unionai-examples/v2/user-guide/task-configuration/pod-templates/pod_template.py" fragment="pod-template" lang="python" >}}
 
-## PodTemplate components
+## PodTemplate parameters
+
+The `PodTemplate` class provides the following parameters:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `primary_container_name` | `str` | Name of the container where task code runs (default: `"primary"`). Must match a container in `pod_spec`. |
+| `pod_spec` | `V1PodSpec` | Kubernetes pod specification for configuring containers, volumes, security contexts, and more. |
+| `labels` | `dict[str, str]` | Pod labels for organization and selection by Kubernetes selectors. |
+| `annotations` | `dict[str, str]` | Pod annotations for metadata and integrations (doesn't affect scheduling). |
+
+## Volume mounts
+
+Pod templates are commonly used to mount volumes for persistent storage or cloud storage access:
+
+```python
+from kubernetes.client import (
+    V1Container,
+    V1PodSpec,
+    V1Volume,
+    V1VolumeMount,
+    V1CSIVolumeSource,
+)
+import flyte
+
+pod_template = flyte.PodTemplate(
+    primary_container_name="primary",
+    pod_spec=V1PodSpec(
+        containers=[
+            V1Container(
+                name="primary",
+                volume_mounts=[
+                    V1VolumeMount(
+                        name="data-volume",
+                        mount_path="/mnt/data",
+                        read_only=False,
+                    )
+                ],
+            )
+        ],
+        volumes=[
+            V1Volume(
+                name="data-volume",
+                csi=V1CSIVolumeSource(
+                    driver="your-csi-driver",
+                    volume_attributes={"key": "value"},
+                ),
+            )
+        ],
+    ),
+)
+
+env = flyte.TaskEnvironment(
+    name="volume-example",
+    pod_template=pod_template,
+    image=flyte.Image.from_debian_base(),
+)
+
+@env.task
+async def process_data() -> str:
+    # Access mounted volume
+    with open("/mnt/data/input.txt", "r") as f:
+        data = f.read()
+    return f"Processed {len(data)} bytes"
+```
+
+### GCS/S3 volume mounts
+
+Mount cloud storage directly into your pod for efficient data access:
+
+```python
+from kubernetes.client import V1Container, V1PodSpec, V1Volume, V1VolumeMount, V1CSIVolumeSource
+import flyte
+
+# GCS example with CSI driver
+pod_template = flyte.PodTemplate(
+    primary_container_name="primary",
+    annotations={
+        "gke-gcsfuse/volumes": "true",
+        "gke-gcsfuse/cpu-limit": "2",
+        "gke-gcsfuse/memory-limit": "1Gi",
+    },
+    pod_spec=V1PodSpec(
+        containers=[
+            V1Container(
+                name="primary",
+                volume_mounts=[V1VolumeMount(name="gcs", mount_path="/mnt/gcs")],
+            )
+        ],
+        volumes=[
+            V1Volume(
+                name="gcs",
+                csi=V1CSIVolumeSource(
+                    driver="gcsfuse.csi.storage.gke.io",
+                    volume_attributes={"bucketName": "my-bucket"},
+                ),
+            )
+        ],
+    ),
+)
+```
+
+## Sidecar containers
+
+Add sidecar containers to run alongside your task. Common use cases include:
+
+- **Metrics exporters**: Prometheus, Datadog agents
+- **Service proxies**: Istio, Linkerd sidecars
+- **Data services**: Databases, caches, or specialized services like Nvidia NIMs
+
+```python
+from kubernetes.client import V1Container, V1PodSpec
+import flyte
+
+pod_template = flyte.PodTemplate(
+    primary_container_name="primary",
+    pod_spec=V1PodSpec(
+        containers=[
+            # Primary container (where your task code runs)
+            V1Container(name="primary"),
+
+            # Sidecar container
+            V1Container(
+                name="metrics-sidecar",
+                image="prom/pushgateway:latest",
+                ports=[{"containerPort": 9091}],
+            ),
+        ],
+    ),
+)
+
+env = flyte.TaskEnvironment(
+    name="sidecar-example",
+    pod_template=pod_template,
+    image=flyte.Image.from_debian_base().with_pip_packages("requests"),
+)
+
+@env.task
+async def task_with_metrics() -> str:
+    import requests
+
+    # Send metrics to sidecar
+    requests.post("http://localhost:9091/metrics", data="my_metric 42")
+
+    # Your task logic
+    return "Task completed with metrics"
+```
+
+## Image pull secrets
 
-The `PodTemplate` class provides the following parameters for customizing your pod configuration:
+Configure private registry access:
 
 ```python
+from kubernetes.client import V1Container, V1PodSpec, V1LocalObjectReference
+import flyte
+
 pod_template = flyte.PodTemplate(
-    primary_container_name: str = "primary",
-    pod_spec: Optional[V1PodSpec] = None,
-    labels: Optional[Dict[str, str]] = None,
-    annotations: Optional[Dict[str, str]] = None
+    primary_container_name="primary",
+    pod_spec=V1PodSpec(
+        containers=[V1Container(name="primary")],
+        image_pull_secrets=[V1LocalObjectReference(name="my-registry-secret")],
+    ),
 )
 ```
 
-### Parameters
+## Cluster-specific configuration
+
+Pod templates are often used to configure Kubernetes-specific settings required by your cluster, even when not using multiple containers:
+
+```python
+import flyte
+
+pod_template = flyte.PodTemplate(
+    primary_container_name="primary",
+    annotations={
+        "iam.amazonaws.com/role": "my-task-role",  # AWS IAM role
+        "cluster-autoscaler.kubernetes.io/safe-to-evict": "false",
+    },
+    labels={
+        "cost-center": "ml-team",
+        "project": "recommendations",
+    },
+)
+```
+
+## Important notes
+
+1. **Local execution**: Pod templates only apply to remote execution. When running locally, only your task code executes.
+
+2. **Image building**: Flyte automatically builds and manages the image for your task environment. Images for sidecar containers must be pre-built and available in a registry.
+
+3. **Primary container**: Your task code is automatically injected into the container matching `primary_container_name`. This container must be defined in the `pod_spec.containers` list.
+
+4. **Lifecycle management**: Flyte monitors the primary container and terminates the entire pod when it exits, ensuring sidecar containers don't run indefinitely.
 
-- **`primary_container_name`** (`str`, default: `"primary"`): Specifies the name of the main container that will run your task code. This must match the container name defined in your pod specification.
+## Best practices
 
-- **`pod_spec`** (`Optional[V1PodSpec]`): A standard Kubernetes `V1PodSpec` object that defines the complete pod specification. This allows you to configure any pod-level setting including containers, volumes, security contexts, node selection, and more.
+1. **Start simple**: Begin with basic labels and annotations before adding complex sidecars
+2. **Test locally first**: Verify your task logic works locally before adding pod customizations
+3. **Use environment-specific templates**: Different environments (dev, staging, prod) may need different pod configurations
+4. **Set resource limits**: Always set resource requests and limits for sidecars to prevent cluster issues
+5. **Security**: Use image pull secrets and least-privilege service accounts
 
-- **`labels`** (`Optional[Dict[str, str]]`): Key-value pairs used for organizing and selecting pods. Labels are used by Kubernetes selectors and can be queried to filter and manage pods.
+## Learn more
 
-- **`annotations`** (`Optional[Dict[str, str]]`): Additional metadata attached to the pod that doesn't affect pod scheduling or selection. Annotations are typically used for storing non-identifying information like deployment revisions, contact information, or configuration details.
+- [Kubernetes Pods Documentation](https://kubernetes.io/docs/concepts/workloads/pods/)
+- [Kubernetes Python Client](https://github.com/kubernetes-client/python)
+- [V1PodSpec Reference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#podspec-v1-core)
diff --git a/content/user-guide/task-configuration/task-plugins.md b/content/user-guide/task-configuration/task-plugins.md
@@ -1,6 +1,6 @@
 ---
 title: Plugins
-weight: 3
+weight: 20
 variants: +flyte +serverless +byoc +selfmanaged
 ---
 
diff --git a/content/user-guide/task-programming/files-and-directories.md b/content/user-guide/task-programming/files-and-directories.md
@@ -1,6 +1,6 @@
 ---
 title: Files and directories
-weight: 90
+weight: 60
 variants: +flyte +serverless +byoc +selfmanaged
 ---
 
diff --git a/content/user-guide/task-programming/other-features.md b/content/user-guide/task-programming/other-features.md
@@ -1,6 +1,6 @@
 ---
 title: Other features
-weight: 9
+weight: 200
 variants: +flyte +serverless +byoc +selfmanaged
 ---
 
diff --git a/content/user-guide/task-programming/pod_templates.md b/content/user-guide/task-programming/pod_templates.md
diff --git a/content/user-guide/task-programming/unit-testing.md b/content/user-guide/task-programming/unit-testing.md
