From 773a54187b84b4e2039b2cb09697ff7351bffecd Mon Sep 17 00:00:00 2001 From: SandraGH5 <80421934+SandraGH5@users.noreply.github.com> Date: Wed, 19 May 2021 15:44:38 -0700 Subject: [PATCH] Update lp_notifications.py (#212) * Update lp_notifications.py * update lp_notifications.py (#215) Signed-off-by: Samhita Alla Co-authored-by: Samhita Alla --- .../deployment/workflow/lp_notifications.py | 120 +++++++++++++++--- 1 file changed, 99 insertions(+), 21 deletions(-) diff --git a/cookbook/deployment/workflow/lp_notifications.py b/cookbook/deployment/workflow/lp_notifications.py index 80a405beec..585245f3c4 100644 --- a/cookbook/deployment/workflow/lp_notifications.py +++ b/cookbook/deployment/workflow/lp_notifications.py @@ -1,16 +1,29 @@ """ - -Getting notifications on workflow termination -------------------------------------------------- - -For background on launch plans, refer to :any:`launch_plans`. - -For up-to-date documentation on notifications see the `official docs `_ +############################################### +Receiving Notifications on Workflow Termination +############################################### """ # %% -# Let's consider the following example workflow: +# When a workflow is completed, users can be notified through: +# +# * email +# * `pagerduty `__ +# * `slack `__ +# +# The content of these notifications is configurable at the platform level. +# +# ************ +# Code Example +# ************ +# +# When a workflow reaches a specified `terminal workflow execution phase `__, +# the :py:class:`flytekit:flytekit.Email`, :py:class:`flytekit:flytekit.PagerDuty`, or :py:class:`flytekit:flytekit.Slack` +# objects can be used in the construction of a :py:class:`flytekit:flytekit.LaunchPlan`. + +# %% +# Consider the following example workflow: from flytekit import Email, LaunchPlan, task, workflow from flytekit.models.core.execution import WorkflowExecutionPhase @@ -25,11 +38,13 @@ def int_doubler_wf(a: int) -> str: doubled = double_int_and_print(a=a) return doubled - -# This launch plan triggers email notifications when the workflow execution it triggered reaches the phase `SUCCEEDED`. -int_doubler_wf_lp = LaunchPlan.create( - "int_doubler_wf", - int_doubler_wf, +# %% +# Here are three scenarios that can help deepen your understanding of how notifications work: +# +# 1. Launch Plan triggers email notifications when the workflow execution reaches the ``SUCCEEDED`` phase. +int_doubler_wf_lp = LaunchPlan.get_or_create( + name="int_doubler_wf", + workflow=int_doubler_wf, default_inputs={"a": 4}, notifications=[ Email( @@ -40,14 +55,14 @@ def int_doubler_wf(a: int) -> str: ) # %% -# Notifications shine when used for scheduled workflows to alert on failures: +# 2. Notifications shine when used for scheduled workflows to alert for failures. from datetime import timedelta from flytekit import FixedRate, PagerDuty -int_doubler_wf_scheduled_lp = LaunchPlan.create( - "int_doubler_wf_scheduled", - int_doubler_wf, +int_doubler_wf_scheduled_lp = LaunchPlan.get_or_create( + name="int_doubler_wf_scheduled", + workflow=int_doubler_wf, default_inputs={"a": 4}, notifications=[ PagerDuty( @@ -60,12 +75,12 @@ def int_doubler_wf(a: int) -> str: # %% -# If you desire you can combine notifications with different permutations of terminal phases and recipient targets: +# 3. Notifications can be combined with different permutations of terminal phases and recipient targets. from flytekit import Slack -wacky_int_doubler_lp = LaunchPlan.create( - "wacky_int_doubler", - int_doubler_wf, +wacky_int_doubler_lp = LaunchPlan.get_or_create( + name="wacky_int_doubler", + workflow=int_doubler_wf, default_inputs={"a": 4}, notifications=[ Email( @@ -86,3 +101,66 @@ def int_doubler_wf(a: int) -> str: ), ], ) + +# %% +# Future work +# =========== +# Work is ongoing to support a generic event egress system that can be used to publish events for tasks, workflows, and +# workflow nodes. When this is complete, generic event subscribers can asynchronously process these events for a rich +# and fully customizable experience. +# +# ****************************** +# Platform Configuration Changes +# ****************************** +# +# The ``notifications`` top-level portion of the Flyteadmin config specifies how to handle notifications. +# +# As in schedules, the handling of notifications is composed of two parts— one part handles enqueuing notifications asynchronously. The other part handles processing pending notifications and sends out emails and alerts. +# +# This is only supported for Flyte instances running on AWS. +# +# Config +# ====== +# +# To publish notifications, you'll need to set up an `SNS topic `_. +# +# To process notifications, you'll need to set up an `AWS SQS `_ queue to consume notification events. This queue must be configured as a subscription to your SNS topic you created above. +# +# To publish notifications, you'll need a `verified SES email address `_ which will be used to send notification emails and alerts using email APIs. +# +# The role you use to run Flyteadmin must have permissions to read and write to your SNS topic and SQS queue. +# +# Let's look into the following config section and explain what each value represents: +# +# .. code-block:: bash +# +# notifications: +# type: "aws" +# region: "us-east-1" +# publisher: +# topicName: "arn:aws:sns:us-east-1:{{ YOUR ACCOUNT ID }}:{{ YOUR TOPIC }}" +# processor: +# queueName: "{{ YOUR QUEUE NAME }}" +# accountId: "{{ YOUR ACCOUNT ID }}" +# emailer: +# subject: "Notice: Execution \"{{ workflow.name }}\" has {{ phase }} in \"{{ domain }}\"." +# sender: "flyte-notifications@company.com" +# body: > +# Execution \"{{ workflow.name }} [{{ name }}]\" has {{ phase }} in \"{{ domain }}\". View details at +# +# http://flyte.company.com/console/projects/{{ project }}/domains/{{ domain }}/executions/{{ name }}. {{ error }} +# +# * **type**: AWS is the only cloud back-end supported for executing scheduled workflows; hence ``"aws"`` is the only valid value. By default, the no-op executor is used. +# * **region**: Specifies the region AWS clients should use when creating SNS and SQS clients. +# * **publisher**: Handles pushing notification events to your SNS topic. +# * **topicName**: This is the arn of your SNS topic. +# * **processor**: Handles recording notification events and enqueueing them to be processed asynchronously. +# * **queueName**: Name of the SQS queue which will capture pending notification events. +# * **accountId**: AWS `account id `_. +# * **emailer**: Encloses config details for sending and formatting emails used as notifications. +# * **subject**: Configurable subject line used in notification emails. +# * **sender**: Your verified SES email sender. +# * **body**: Configurable email body used in notifications. +# +# The complete set of parameters that can be used for email templating are checked in `here `_. +