Update workflow_labels_annotations.py (flyteorg#194)

* Update workflow_labels_annotations.py * Update cookbook/core/containerization/workflow_labels_annotations.py Co-authored-by: Yee Hing Tong <[email protected]> * Update cookbook/core/containerization/workflow_labels_annotations.py Co-authored-by: Yee Hing Tong <[email protected]> * Update cookbook/core/containerization/workflow_labels_annotations.py Co-authored-by: Yee Hing Tong <[email protected]> * Update workflow_labels_annotations.py * Update cookbook/core/containerization/workflow_labels_annotations.py Co-authored-by: Yee Hing Tong <[email protected]> Co-authored-by: Yee Hing Tong <[email protected]>
eapolinario · May 21, 2021 · fe6e67e · fe6e67e
1 parent aa33443
commit fe6e67e
Showing 1 changed file with 56 additions and 4 deletions.
diff --git a/cookbook/core/containerization/workflow_labels_annotations.py b/cookbook/core/containerization/workflow_labels_annotations.py
@@ -1,8 +1,60 @@
 """
 Adding Workflow Labels and Annotations
----------------------------------------
+--------------------------------------
 
-.. NOTE::
+In Flyte, workflow executions are created as Kubernetes resources. These can be extended with
+`labels <https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/>`__ and
+`annotations <https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/>`__.
 
-    Coming soon 🛠
-"""
+**Labels** and **annotations** are key value pairs which can be used to identify workflows for your own uses.
+
+.. Warning::
+   Note that adding labels and annotations to your K8s resources may have side-effects depending on webhook behavior on your execution clusters.
+
+Labels are meant to be used as identifying attributes, whereas annotations are arbitrary, *non-identifying* metadata.
+
+Using labels and annotations is entirely optional. They can be used to categorize and identify workflow executions.
+
+Labels and annotations are optional parameters to launch plan and execution invocations. When an execution
+defines labels and/or annotations *and* the launch plan does as well, the execution spec values will be preferred.
+
+Launch Plan Usage Example
+#########################
+
+.. code:: python
+
+    from flytekit.models.common import Labels, Annotations
+
+    @workflow
+    class MyWorkflow(object):
+        ...
+
+    my_launch_plan = MyWorkflow.create_launch_plan(
+        labels=Labels({"myexecutionlabel": "bar", ...}),
+        annotations=Annotations({"region": "SEA", ...}),
+        ...
+    )
+
+    my_launch_plan.execute(...)
+
+Execution Example
+#################
+
+.. code:: python
+
+    from flytekit.models.common import Labels, Annotations
+
+    @workflow
+    class MyWorkflow(object):
+        ...
+
+    my_launch_plan = MyWorkflow.create_launch_plan(...)
+
+    my_launch_plan.execute(
+        labels=Labels({"myexecutionlabel": "bar", ...}),
+        annotations=Annotations({"region": "SEA", ...}),
+        ...
+    )
+
+
+"""