Incorporating Google Chat into K9 process

Overview

Our K9 process includes an optional feature where Google Chat can be integrated with Jenkins so that upon build success, failure, or abortion a message is sent to a predetermined Google Chat channel. The high-level mechanism behind this feature is as follows:

  1. Jenkins installs the google-chat-notification plugin automatically.

  2. The user chooses a Google Chat channel where messages will be posted and creates a webhook for that channel.

  3. The user creates a secret in AWS Secrets Manager that contains the webhook url.

  4. The user modifies the post section within the Jenkinsfiles for the application to customize the messages and the conditions by which they are sent.

  5. When the Jenkinsfiles are run by Jenkins, the k9 process will automatically find the secret created in step 3 and will create a secret in Jenkins. This secret in Jenkins will be used by the google-chat-notification Jenkins plugin to connect with the Google Chat channel.

Manual Steps

To enable this process, several manual steps need to be performed as listed below. Note that this process needs to be done only once per application (which includes both service and ui).

  1. Create or identify a Google Chat channel to use for the integration.

  2. Once a channel has been specified, create a webhook for it. Note that the following steps will need to be done on either a web browser or a desktop application, as webhooks cannot be created on mobile applications.

  • Go to the channel to which you want to add a webhook.

  • At the top next to the channel title, click the dropdown arrow followed by Manage webhooks.

  • If this space already contains other webhooks, click the Add another button. Otherwise move on to the next step.

  • For the Name field enter a sensible and unique name for the webhook. A recommended value is {{appName}}-notifier, where {{appName}} is replaced by the name of the application.

  • For the Avatar URL field enter the URL of an appropriate avatar for the integration. The recommended avatar can be found here.

  • Click the Save button at the bottom.

  • Click the copy button (icon looks like pages) to copy the webhook URL.

  • Write or save this URL somewhere else. It will be needed in later steps.

  • Click outside the Incoming webhooks dialog box to close it.

  1. Navigate to the AWS Secrets Manager in the AWS web console in the account that contains the clusters you want to deploy into.

  2. Create a new secret.

  • Click on Store a new secret.

  • Click on Other type of secret.

  • Enter “url” as the key.

  • Enter the copied webhook url as the value.

  • Click on Next.

  • Under secret name, type the following: {{appName}}-google-chat-cred, where {{appName}} is replaced by the application name.

  • Click Next followed by Next followed by Store

  1. Inspect the Jenkinsfiles for your application and make any changes if necessary to the post section. This section contains the google-chat-notification invocation that is run to post messages to the specified channel.

  • The aborted keyword can be added if the user wishes to be notified upon build abortion.

  • The url field should NOT be modified. This field corresponds to the secret in Jenkins (which is ultimately pulled from the secret created in step 4). If anything is modified in this field after the “id:”, a new secret with a name that matches this new value will need to be created (containing the webhook URL).

  • To modify the message being sent to the channel, modify the message parameter. A set of formatters can be used to format the message.

A deeper dive into K9

The k9 cli performs several steps behind the scenes to integrate Google Chat with Jenkins.

  1. It tries to find the user created secret in AWS Secrets Manager for the webhook url.

  • If it is unable to find the secret, it will notify the user that it was unable to find it and will skip all the following steps. Then It is upon the user to check whether the secret exists.

  1. It will copy the webhook url, connect to Jenkins, and create a secret text secret in Jenkins. This webhook url is used by the google-chat-notification plugin to post messages in the specified channel.

A note on the google-chat-notification plugin

The plugin relies on the url field to get the webhook url so that it can communicate with Google Chat. The “id:” prefix specifies to the plugin that anything afterwards in that string is the name of a secret created in Jenkins that contains the webhook URL. Again this section should not be modified because it has been automatically formatted to align with the secret naming.

Deleting the webhook

Sometimes it is beneficial to deactivate a webhook. An example is the deletion of an application from Jenkins. In this case, the following steps should be followed.

  1. Delete the secret in Jenkins (same name as the one created in AWS Secrets Manager)

  • Log into Jenkins

  • On the left hand side, click Manage Jenkins

  • Under “Security” click Manage Credentials

  • Find your secret in the list and click the name of the secret

  • On the left hand side, click Delete

  • Click the confirmation button if applicable

  1. Delete the webhook in the specified channel

  • Go to the channel to which you want to delete a webhook.

  • At the top next to the channel title, click the dropdown arrow followed by Manage webhooks.

  • Beside the webhook you want to delete, click the three vertical dots followed by Delete. Your webhook is now deleted.

  • Click outside the Incoming webhooks dialog box to close it.

Note that when running k9 delete service or k9 delete ui, the webhook secrets in Jenkins are not deleted because the commands are run separately. If the webhook secret is deleted for the service but the ui is not deleted, the integration would no longer work for the ui. The deletion of the secret in Jenkins and the webhook in Google Chat needs to be done manually by the user.