Add sample dags and update doc for RedshiftClusterSensor, RedshiftPau…

…seClusterOperator and RedshiftResumeClusterOperator (#22128)

airflow/providers/amazon/aws/example_dags/example_redshift_cluster.py

@@ -0,0 +1,71 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+from datetime import datetime
+from os import getenv
+
+from airflow import DAG
+from airflow.models.baseoperator import chain
+from airflow.providers.amazon.aws.operators.redshift_cluster import (
+    RedshiftPauseClusterOperator,
+    RedshiftResumeClusterOperator,
+)
+from airflow.providers.amazon.aws.sensors.redshift_cluster import RedshiftClusterSensor
+
+REDSHIFT_CLUSTER_IDENTIFIER = getenv("REDSHIFT_CLUSTER_IDENTIFIER", "redshift-cluster-1")
+
+with DAG(
+    dag_id="example_redshift_cluster",
+    start_date=datetime(2021, 1, 1),
+    schedule_interval=None,
+    catchup=False,
+    tags=['example'],
+) as dag:
+    # [START howto_sensor_redshift_cluster]
+    task_wait_cluster_available = RedshiftClusterSensor(
+        task_id='sensor_redshift_cluster_available',
+        cluster_identifier=REDSHIFT_CLUSTER_IDENTIFIER,
+        target_status='available',
+        poke_interval=5,
+        timeout=60 * 15,
+    )
+    # [END howto_sensor_redshift_cluster]
+
+    # [START howto_operator_redshift_pause_cluster]
+    task_pause_cluster = RedshiftPauseClusterOperator(
+        task_id='redshift_pause_cluster',
+        cluster_identifier=REDSHIFT_CLUSTER_IDENTIFIER,
+    )
+    # [END howto_operator_redshift_pause_cluster]
+
+    task_wait_cluster_paused = RedshiftClusterSensor(
+        task_id='sensor_redshift_cluster_paused',
+        cluster_identifier=REDSHIFT_CLUSTER_IDENTIFIER,
+        target_status='paused',
+        poke_interval=5,
+        timeout=60 * 15,
+    )
+
+    # [START howto_operator_redshift_resume_cluster]
+    task_resume_cluster = RedshiftResumeClusterOperator(
+        task_id='redshift_resume_cluster',
+        cluster_identifier=REDSHIFT_CLUSTER_IDENTIFIER,
+    )
+    # [END howto_operator_redshift_resume_cluster]
+
+    chain(task_wait_cluster_available, task_pause_cluster, task_wait_cluster_paused, task_resume_cluster)

airflow/providers/amazon/aws/sensors/redshift_cluster.py

@@ -27,6 +27,10 @@ class RedshiftClusterSensor(BaseSensorOperator):
     """
     Waits for a Redshift cluster to reach a specific status.
 
+    .. seealso::
+        For more information on how to use this sensor, take a look at the guide:
+        :ref:`howto/sensor:RedshiftClusterSensor`
+
     :param cluster_identifier: The identifier for the cluster being pinged.
     :param target_status: The cluster status desired.
     """

docs/apache-airflow-providers-amazon/operators/redshift_cluster.rst

@@ -15,30 +15,67 @@
     specific language governing permissions and limitations
     under the License.
 
-Redshift cluster management operators
-=====================================
+Amazon Redshift Operators
+=========================
 
-.. contents::
-  :depth: 1
-  :local:
+`Amazon Redshift <https://aws.amazon.com/redshift/>`__ manages all the work of setting up, operating, and scaling a data warehouse:
+provisioning capacity, monitoring and backing up the cluster, and applying patches and upgrades to
+the Amazon Redshift engine. You can focus on using your data to acquire new insights for your
+business and customers.
+
+Airflow provides operators to manage your Redshift clusters.
+
+Prerequisite Tasks
+^^^^^^^^^^^^^^^^^^
+
+.. include:: _partials/prerequisite_tasks.rst
+
+Manage Amazon Redshift Clusters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. _howto/sensor:RedshiftClusterSensor:
+
+Amazon Redshift Cluster Sensor
+""""""""""""""""""""""""""""""
+
+To check the state of an Amazon Redshift Cluster until it reaches the target state or another terminal
+state you can use :class:`~airflow.providers.amazon.aws.sensors.redshift_cluster.RedshiftClusterSensor`.
+
+.. exampleinclude:: /../../airflow/providers/amazon/aws/example_dags/example_redshift_cluster.py
+    :language: python
+    :dedent: 4
+    :start-after: [START howto_sensor_redshift_cluster]
+    :end-before: [END howto_sensor_redshift_cluster]
 
 .. _howto/operator:RedshiftResumeClusterOperator:
 
-Resume a Redshift Cluster
-"""""""""""""""""""""""""
+Resume an Amazon Redshift Cluster
+"""""""""""""""""""""""""""""""""
 
-To resume a 'paused' AWS Redshift Cluster you can use
+To resume a 'paused' Amazon Redshift Cluster you can use
 :class:`RedshiftResumeClusterOperator <airflow.providers.amazon.aws.operators.redshift_cluster>`
 
-This Operator leverages the AWS CLI
-`resume-cluster <https://docs.aws.amazon.com/cli/latest/reference/redshift/resume-cluster.html>`__ API
+.. exampleinclude:: /../../airflow/providers/amazon/aws/example_dags/example_redshift_cluster.py
+    :language: python
+    :dedent: 4
+    :start-after: [START howto_operator_redshift_resume_cluster]
+    :end-before: [END howto_operator_redshift_resume_cluster]
 
 .. _howto/operator:RedshiftPauseClusterOperator:
 
-Pause a Redshift Cluster
-""""""""""""""""""""""""
+Pause an Amazon Redshift Cluster
+""""""""""""""""""""""""""""""""
 
-To pause an 'available' AWS Redshift Cluster you can use
+To pause an 'available' Amazon Redshift Cluster you can use
 :class:`RedshiftPauseClusterOperator <airflow.providers.amazon.aws.operators.redshift_cluster>`
-This Operator leverages the AWS CLI
-`pause-cluster <https://docs.aws.amazon.com/cli/latest/reference/redshift/pause-cluster.html>`__ API
+
+.. exampleinclude:: /../../airflow/providers/amazon/aws/example_dags/example_redshift_cluster.py
+    :language: python
+    :dedent: 4
+    :start-after: [START howto_operator_redshift_pause_cluster]
+    :end-before: [END howto_operator_redshift_pause_cluster]
+
+Reference
+^^^^^^^^^
+
+* `AWS boto3 Library Documentation for Amazon Redshift <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/redshift.html>`__