From b742583ae5f23c663ddefe7cd0461a985192ab32 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" <179508745+promptless[bot]@users.noreply.github.com> Date: Thu, 12 Dec 2024 00:24:11 +0000 Subject: [PATCH] Documentation updates --- docs/3.0/automate/events/custom-triggers.mdx | 21 +++++++++++++ .../infrastructure-examples/serverless.mdx | 31 ++++++++++++++++++- docs/3.0/develop/blocks.mdx | 25 +++++++++++++++ docs/integrations/integrations.mdx | 7 +++++ docs/integrations/use-integrations.mdx | 25 +++++++++++++++ 5 files changed, 108 insertions(+), 1 deletion(-) diff --git a/docs/3.0/automate/events/custom-triggers.mdx b/docs/3.0/automate/events/custom-triggers.mdx index 1f2651b80d34..c7e3f1a6315f 100644 --- a/docs/3.0/automate/events/custom-triggers.mdx +++ b/docs/3.0/automate/events/custom-triggers.mdx @@ -190,6 +190,27 @@ The following configuration uses `after` to prevent this automation from firing ... ``` +#### Slack Integration + +You can configure your custom triggers to send notifications to Slack when certain events occur. To send a Slack message when an expected event satisfies the threshold, add an `actions` section to your trigger configuration. + +For example, to send a Slack notification when a flow run completes: + +```json +"expect": [ + "prefect.flow-run.Completed" +], +"actions": [ + { + "type": "slack_notification", + "channel": "#alerts", + "message": "Flow run has completed." + } +], +... +``` + +This configuration will send a message to the specified Slack channel whenever the expected event occurs. ### Evaluation strategy All of the previous examples were designed around a reactive `posture`; that is, count up events toward the diff --git a/docs/3.0/deploy/infrastructure-examples/serverless.mdx b/docs/3.0/deploy/infrastructure-examples/serverless.mdx index 2d70b6220bdb..24fbbcad0be8 100644 --- a/docs/3.0/deploy/infrastructure-examples/serverless.mdx +++ b/docs/3.0/deploy/infrastructure-examples/serverless.mdx @@ -503,6 +503,9 @@ This command speeds up your infrastructure setup process. As with the examples above, you need to have the related cloud CLI library installed and to be authenticated with your cloud provider. +==== +BEGIN CURRENT DOCUMENT CONTENT +==== ## Manual infrastructure provisioning If you prefer to set up your infrastructure manually, exclude the `--provision-infra` flag in the CLI command. @@ -567,8 +570,34 @@ In the examples below, you'll create a push work pool through the Prefect Cloud Copy the token ID and token secret and store them somewhere safe for use in the next section. - + + + To push work to Slack, you need a Slack App and an OAuth token. + + **Create a Slack App** + + 1. Go to the [Slack API Apps page](https://api.slack.com/apps). + 2. Click **Create New App** and choose **From scratch**. + 3. Provide an **App Name** and select your **Workspace**, then click **Create App**. + + **Add Scopes and Permissions** + + 1. In the left sidebar, navigate to **OAuth & Permissions**. + 2. Under **Scopes**, add the necessary **Bot Token Scopes** such as `chat:write`, `channels:read`, and any others required for your use case. + **Install the App** + + 1. Click **Install App to Workspace**. + 2. Review the permissions and click **Allow** to authorize the app. + + **Retrieve the OAuth Token** + + 1. After installation, you'll see a **Bot User OAuth Access Token**. Copy this token and store it somewhere safe for use in the next section. + + +==== +END CURRENT DOCUMENT CONTENT +==== ### Work pool configuration The push work pool stores information about what type of infrastructure the flow will run on, what default values to diff --git a/docs/3.0/develop/blocks.mdx b/docs/3.0/develop/blocks.mdx index 45cb33dc4bbe..23b5b992c1a1 100644 --- a/docs/3.0/develop/blocks.mdx +++ b/docs/3.0/develop/blocks.mdx @@ -295,6 +295,31 @@ print(aws_credentials_block) # aws_access_key_id='AKIAJKLJKLJKLJKLJKLJK' aws_secret_access_key=SecretStr('**********') aws_session_token=None profile_name=None region_name=None ``` +Here's another example of a `SlackCredentials` block that uses `SecretStr`: + +```python +from typing import Optional + +from prefect.blocks.core import Block +from pydantic import SecretStr # if pydantic version >= 2.0, use: from pydantic.v1 import SecretStr + +class SlackCredentials(Block): + slack_bot_token: Optional[SecretStr] = None + slack_signing_secret: Optional[SecretStr] = None +``` + +When using `SlackCredentials`, the secret fields `slack_bot_token` and `slack_signing_secret` are obfuscated when the object is logged: + +```python +slack_credentials_block = SlackCredentials( + slack_bot_token="xoxb-123456789012-ABCDEFGHIJKLMNO", + slack_signing_secret="8f742231b10e8888abcd99yyyzzz85a5" +) + +print(slack_credentials_block) +# slack_bot_token=SecretStr('**********') slack_signing_secret=SecretStr('**********') +``` + Prefect's `SecretDict` field type allows you to add a dictionary field to your block that automatically obfuscates values at all levels in the UI or in logs. This capability is useful for blocks where typing or structure of secret fields is not known until configuration time. diff --git a/docs/integrations/integrations.mdx b/docs/integrations/integrations.mdx index e794291abe85..5a48ed977f62 100644 --- a/docs/integrations/integrations.mdx +++ b/docs/integrations/integrations.mdx @@ -79,6 +79,13 @@ mode: "wide" Maintained by Prefect + + prefect-slack + + Maintained by Prefect + + + prefect-fivetran diff --git a/docs/integrations/use-integrations.mdx b/docs/integrations/use-integrations.mdx index 4d8cb4dcbe2e..1ff2f6430b7a 100644 --- a/docs/integrations/use-integrations.mdx +++ b/docs/integrations/use-integrations.mdx @@ -15,9 +15,16 @@ For example, to install `prefect-aws` you can: pip install prefect-aws ``` +Similarly, to install `prefect-slack`, you can: + +```bash +pip install prefect-slack +``` + - install the corresponding extra: ```bash pip install 'prefect[aws]' +pip install 'prefect[slack]' ``` See [the `setup.py`](https://github.com/PrefectHQ/prefect/blob/main/setup.py) for the full list of extras and the versions they specify. @@ -32,6 +39,12 @@ For example, to register the blocks available in `prefect-aws`: prefect block register -m prefect_aws ``` +To register the blocks available in `prefect-slack`: + +```bash +prefect block register -m prefect_slack +``` + To use a block's `load` method, you must have a block [saved](/latest/develop/blocks/#saving-blocks). [Learn more about blocks](/latest/develop/blocks). ## Use tasks and flows from an Integration @@ -56,6 +69,18 @@ def connect_to_database(): # Then, use secret_value to connect to a database ``` +Similarly, send a message to Slack with the `send_message` task using the following code: + +```python +from prefect import flow +from prefect_slack import SlackWebhook + +@flow +def notify_slack(): + slack_webhook = SlackWebhook.load("MY_SLACK_WEBHOOK") + slack_webhook.send_message(text="Hello from Prefect!") +``` + ## Customize tasks and flows from an integration To customize pre-configured tasks or flows use `with_options`. For example, configure retries for dbt Cloud jobs: