From 3de3fa7808e3055c562a2ba6fbdfde287f0ab1d1 Mon Sep 17 00:00:00 2001
From: David Grove <dgrove-oss@users.noreply.github.com>
Date: Wed, 15 Jan 2025 13:45:44 -0500
Subject: [PATCH] Improve documentation of samples (#303)

* Improve samples
  + Add README to highlight podSet inference
  + Add LeaderWorkerSet example

* fix formatting

* editing pass
---
 samples/README.md                      | 33 +++++++++++++++++++
 samples/wrapped-leader-worker-set.yaml | 44 ++++++++++++++++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 samples/README.md
 create mode 100644 samples/wrapped-leader-worker-set.yaml

diff --git a/samples/README.md b/samples/README.md
new file mode 100644
index 0000000..6769a1d
--- /dev/null
+++ b/samples/README.md
@@ -0,0 +1,33 @@
+# Sample AppWrappers
+
+This directory contains a number of example yamls showing how to wrap
+different Pod-creating Kubernetes resources in an AppWrapper.
+AppWrappers can be used to wrap one or more instances of
+any Kubernetes Kind that uses `PodSpecTemplate` to define its Pods.
+An AppWrapper must contain at least one such Pod-creating resource in addition
+to zero or more non-Pod-creating resources.
+
+An AppWrapper contains a`components` array containing the wrapped resources.
+Each component has two main pieces: a `template` that defines the wrapped resource
+and a `podSets` array that gives the `replicas` and `path` within the template
+for each `PodSpecTemplate`.   For correct operation of the AppWrapper, it is
+required that the provided `path` and `replicas` information correctly represent
+the Pod creating behavior of the wrapped resource.  For resources that do not
+created Pods (eg `Services` or `Secrets`) `podSets` should be empty and thus omitted.
+
+To simplify the user experience, for a selection of commonly-used Kubernetes
+resource Kinds, the AppWrapper controller can automatically infer the `podSets`
+array if it is not provided. For these same Kinds, the AppWrapper controller
+will validate that any explicitly provided `podSet` entries do in fact match the
+definitions in `template`.
+The current set of automatically inferred Kinds is:
+   + v1 Pod
+   + apps/v1 Deployment
+   + apps/v1 StatefulSet
+   + batch/v1 Job
+   + kubeflow.org/v1 PyTorchJob
+   + ray.io/v1 RayCluster
+   + ray.io/v1 RayJob
+
+In all of the examples, if `podSets` inference is supported for the wrapped Kind,
+then `podSets` is omitted from the sample yaml.
diff --git a/samples/wrapped-leader-worker-set.yaml b/samples/wrapped-leader-worker-set.yaml
new file mode 100644
index 0000000..24977a3
--- /dev/null
+++ b/samples/wrapped-leader-worker-set.yaml
@@ -0,0 +1,44 @@
+apiVersion: workload.codeflare.dev/v1beta2
+kind: AppWrapper
+metadata:
+  name: sample-lws
+  labels:
+    kueue.x-k8s.io/queue-name: default-queue
+spec:
+  components:
+  - podSets:
+    - path: "template.spec.leaderWorkerTemplate.leaderTemplate"
+      replicas: 2
+    - path: "template.spec.leaderWorkerTemplate.workerTemplate"
+      replicas: 3
+    template:
+      apiVersion: leaderworkerset.x-k8s.io/v1
+      kind: LeaderWorkerSet
+      metadata:
+        name: nginx-leaderworkerset
+        labels:
+          app: nginx
+      spec:
+        replicas: 2
+        leaderWorkerTemplate:
+          leaderTemplate:
+            spec:
+              containers:
+              - name: nginx-leader
+                image: registry.k8s.io/nginx-slim:0.27
+                resources:
+                  requests:
+                    cpu: "100m"
+                ports:
+                - containerPort: 80
+          size: 3
+          workerTemplate:
+            spec:
+              containers:
+              - name: nginx-worker
+                image: nginx:1.14.2
+                resources:
+                  requests:
+                    cpu: "200m"
+                ports:
+                - containerPort: 80