Receive cluster notifications

This page shows you how to use Pub/Sub to receive notifications about your Google Kubernetes Engine (GKE) clusters.

Overview

When certain events occur that are relevant to your GKE clusters, such as important scheduled upgrades or available security bulletins, GKE publishes notifications about those events as messages to Pub/Sub topics that you configure. You can receive these notifications on a Pub/Sub subscription, integrate with third-party services, and filter for the notification types you want to receive.

To learn more about the benefits of cluster notifications, how notifications work, and why filtering is important, refer to Cluster notifications.

Before you begin

Before you start, make sure you have performed the following tasks:

• Ensure that you have enabled the Google Kubernetes Engine API.
Enable Google Kubernetes Engine API
• Ensure that you have installed the Cloud SDK.
• Set up default gcloud command-line tool settings for your project by using one of the following methods:
• Use gcloud init, if you want to be walked through setting project defaults.
• Use gcloud config, to individually set your project ID, zone, and region.

gcloud init

1. Run gcloud init and follow the directions:

   gcloud init

   If you are using SSH on a remote server, use the --console-only flag to prevent the command from launching a browser:

   gcloud init --console-only

2. Follow the instructions to authorize the gcloud tool to use your Google Cloud account.
3. Create a new configuration or select an existing one.
4. Choose a Google Cloud project.
5. Choose a default Compute Engine zone.
6. Choose a default Compute Engine region.

Note: You can override these default settings in the gcloud tool by using the --project, --zone, and --region flags.

gcloud config

1. Set your default project ID:

   gcloud config set project PROJECT_ID

2. Set your default Compute Engine region (for example, us-central1):

   gcloud config set compute/region COMPUTE_REGION

3. Set your default Compute Engine zone (for example, us-central1-c):

   gcloud config set compute/zone COMPUTE_ZONE

4. Update gcloud to the latest version:

   gcloud components update

Note: You can override these default settings in the gcloud tool by using the --project, --zone, and --region flags.

By setting default locations, you can avoid errors in gcloud tool like the following: One of [--zone, --region] must be supplied: Please specify location.

• Create a Pub/Sub topic in your project.

Enable cluster notifications on a new cluster

You can enable GKE cluster notifications on a new cluster using the gcloud command-line tool or Google Cloud Console.

gcloud

To enable cluster notifications on a new cluster, run the following command:

gcloud container clusters create CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --notification-config=pubsub=ENABLED,pubsub-topic=projects/PROJECT_ID/topics/TOPIC_NAME,filter=NOTIFICATION_TYPE

Replace the following:

• CLUSTER_NAME: the name of your new cluster.
• COMPUTE_REGION: the compute region for your new cluster. For zonal clusters, use --zone=COMPUTE_ZONE.
• PROJECT_ID: your Google Cloud project ID.
• TOPIC_NAME: the name of your Pub/Sub topic.

• NOTIFICATION_TYPE: a pipe (|) delimited list of the notification types you want to receive. For example, filter="UpgradeEvent|SecurityBulletinEvent" only sends UpgradeEvent and SecurityBulletinEvent notifications, ignoring all other types.

  Note: If you do not specify values for filter, you will receive all notifications that are applicable to your cluster configuration.

Console

To enable cluster notifications on a new cluster, perform the following:

1. Go to the **Google Kubernetes Engine** page in the Cloud Console. Go to Google Kubernetes Engine 1. Click **Create**.

1. On the Create cluster dialog, next to GKE Standard, click Configure.
2. In the navigation pane, in the Cluster section, click Automation.
3. Select the Enable notifications checkbox.
4. From the drop-down list, select the Pub/Sub topic you created.

5. To filter notifications, select the Filter notification types checkbox, and then select the notification types you want to receive.

   Note: If you do not select notification types to filter, you will receive all applicable notifications.

6. Continue to configure the cluster as desired.

7. Click Create.

After enabling notifications, create a Pub/Sub subscription for your topic.

Note: GKE has no restrictions on how you correlate topics with clusters, as long as the topics are in the same project as the clusters. You can choose to create one topic for all clusters, or create multiple topics for groups of clusters.

Enable cluster notifications on an existing cluster

You can enable GKE cluster notifications on an existing cluster using the gcloud command-line tool or Cloud Console.

gcloud

To enable cluster notifications on an existing cluster, run the following command:

gcloud container clusters update CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --notification-config=pubsub=ENABLED,pubsub-topic=projects/PROJECT_ID/topics/TOPIC_NAME,filter=NOTIFICATION_TYPE

Replace the following:

• CLUSTER_NAME: the name of your cluster.
• COMPUTE_REGION: the compute region for your new cluster. For zonal clusters, use --zone=COMPUTE_ZONE..
• PROJECT_ID: your Google Cloud project ID.
• TOPIC_NAME: the name of your Pub/Sub topic.

• NOTIFICATION_TYPE: a pipe (|) delimited list of the notification types you want to receive. For example, filter="UpgradeEvent|SecurityBulletinEvent" only sends UpgradeEvent and SecurityBulletinEvent notifications, ignoring all other types.

  Note: If you do not specify values for filter, you will receive all notifications that are applicable to your cluster configuration.

Console

To enable cluster notifications on an existing cluster, perform the following:

1. Go to the Google Kubernetes Engine page in Cloud Console.

   Go to Google Kubernetes Engine

2. Click the name of the cluster you want to modify.

3. In the Automation section, next to Notifications, click Edit notifications.

4. In the Edit notifications dialog, select the Enable notifications checkbox.

5. From the drop-down list, select the Pub/Sub topic you created.

6. To filter notifications, select the Filter notification types checkbox, and then select the notification types you want to receive.

   Note: If you do not select notification types to filter, you will receive all applicable notifications.

7. Click Save changes.

After enabling notifications, create a Pub/Sub subscription for your topic.

Note: GKE has no restrictions on how you correlate topics with clusters, as long as the topics are in the same project as the clusters. You can choose to create one topic for all clusters, or create multiple topics for groups of clusters

Filter cluster notifications

You can filter notifications by notification type to ensure that you receive notifications that you want.

You can choose to filter notifications using the following methods:

• GKE: Specify values for filter in the --notification-config flag, as shown in the previous examples for enabling cluster notifications.
• Pub/Sub: Configure your Pub/Sub subscription to filter messages when you create a subscription.

Note: We recommend that you filter using GKE. Filtering in GKE lets you modify the filters at any time and eliminates the undelivered message cost associated with Pub/Sub filters. To learn more about the differences between the filtering options, see Filtering notifications.

Modify existing filters in GKE

To modify your existing GKE cluster notification filters, follow the instructions in Enable notifications on an existing cluster and specify the new notification types to filter in the gcloud command or select the new types in Cloud Console.

Disable filters in GKE

You can disable your GKE notification filters and receive all notification types applicable to your cluster using the gcloud tool or Cloud Console.

gcloud

To disable filters using the gcloud tool, run the following command:

gcloud container clusters update CLUSTER_NAME \
  --region=COMPUTE_REGION \
  --notification-config=pubsub=ENABLED,pubsub-topic=projects/PROJECT_ID/topics/TOPIC_NAME

Console

To disable filters using Cloud Console, perform the following:

1. Go to the Google Kubernetes Engine page in Cloud Console.

   Go to Google Kubernetes Engine

2. Click the name of the cluster you want to modify.

3. In the Automation section, next to Notifications, click Edit notifications.

4. In the Edit notifications dialog, clear the Filter notification types checkbox.

5. Click Save changes.

Verify setup for cluster notifications

To verify that notifications are set up correctly for your cluster, you can initiate a node pool upgrade to see if an UpgradeEvent message is sent. You can only manually verify setup for the UpgradeEvent notification type. If your filters are configured to ignore this type, you won't see a message.

Caution: Manually upgrading your node pool ignores your configured maintenance windows and might cause disruptions to running workloads.

You can manually upgrade a specific node pool using the gcloud tool or Cloud Console. For instructions, refer to Manually upgrading a cluster or node pool. If you don't want to change the GKE version on your nodes, you can upgrade to the same version currently on the nodes.

After initiating the upgrade, check your Pub/Sub subscription for a notification message.

Disable cluster notifications

You can disable cluster notifications using the gcloud tool or Cloud Console.

gcloud

To disable notifications using the gcloud tool, run the following command:

gcloud container clusters update CLUSTER_NAME \
  --region=COMPUTE_REGION \
  --notification-config=pubsub=DISABLED

Console

To disable notifications using Cloud Console, perform the following:

1. Go to the Google Kubernetes Engine page in Cloud Console.

   Go to Google Kubernetes Engine

2. Click the name of the cluster you want to modify.

3. In the Automation section, next to Notifications, click Edit notifications.

4. In the Edit notifications dialog, clear the Enable notifications checkbox.

5. Click Save changes.

Optionally, delete the Pub/Sub topic you created for notifications.

What's next

• Learn more about cluster notifications.
• Learn about configuring Pub/Sub notifications.
• Learn how to configure cluster notifications for third-party services.