{"__v":16,"_id":"56f462ff757a450e0072d67d","category":{"__v":14,"_id":"55c6bec2b9aa4e0d0016c2c7","pages":["55c6bec3b9aa4e0d0016c2c9","55c8f451b79cb30d005b3e49","55ccea804906d12f001226e4","56c14ca9f203270d00d6c546","56c3bbeb2d97560d00e23ccf","56cce248ca43550b002814db","56cceaacd98d851d00c0c376","56cceefc723ad71d00cae46d","56ccef4e8fa8b01b00b8200e","56cd03e8723ad71d00cae4af","56cd03f2723ad71d00cae4b1","56cd061eca43550b0028151c","56cd07e4d98d851d00c0c3ba","56df35fbef8c1b320047c2d5"],"project":"55c6bec1b9aa4e0d0016c2c3","version":"55c6bec1b9aa4e0d0016c2c6","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-08-09T02:45:22.223Z","from_sync":false,"order":0,"slug":"documentation","title":"Guides"},"parentDoc":null,"project":"55c6bec1b9aa4e0d0016c2c3","user":"55c8f42fb79cb30d005b3e48","version":{"__v":8,"_id":"55c6bec1b9aa4e0d0016c2c6","project":"55c6bec1b9aa4e0d0016c2c3","createdAt":"2015-08-09T02:45:21.683Z","releaseDate":"2015-08-09T02:45:21.683Z","categories":["55c6bec2b9aa4e0d0016c2c7","56c14bc5826df10d00e82230","56cceed8723ad71d00cae46c","56ccf29a431ada1f00e85aae","56ccf3c28fa8b01b00b82018","56ce1e6ee538330b0021ac5d","56f97e9a4c612020008f2eaf","5734fafd146eb82000597261"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":["573130584245100e001743f8","58ad07233a0f8a2300c1fd68"],"next":{"pages":[],"description":""},"createdAt":"2016-03-24T21:58:23.222Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"Out of the box, Spinnaker allows you to configure the following types of notifications:\n\n* Email\n* HipChat\n* Slack\n* SMS ( via Twilio )\n\nThis is discussed in the Configuring Notifications section below.\n\nAdditionally, Spinnaker allows you to set webhooks for git triggers. See the [http://www.spinnaker.io/docs/notifications-and-events-guide#section-setting-up-git-triggers-in-spinnaker] section.  \n\nYou can also set Spinnaker to stream all its events to a downstream listener. See the [Add a Webhook to Spinnaker](http://www.spinnaker.io/docs/notifications-and-events-guide#section-add-a-listening-webhook-to-spinnaker) section.\n\nAdditionally, Spinnaker is capable of handling cron-based triggers and detect changes in Jenkins builds and Docker images. This functionality will be documented at a later time. \n\n# Configuring Notifications\n\nNotification configurations are set in echo.yml and settings.js. On a single instance virtual machine installation, notification values can also be set in spinnaker-local.yml, which will pass the details to echo.yml and settings.js.\n\nYou will need to set the `spinnaker.baseUrl` configuration value which is used by spinnaker templates. This should point back to the url for your spinnaker's UI ( deck ) instance. This url is used in notifications to link back to your spinnaker instance.\n\n## Email\n\nEmail in spinnaker is provided by [Spring Boot Mail starter](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-email.html). The following is an example of using Gmail to send notifications.\n\nin echo.yml\n```\nmail:\n  enabled: true\n  from: xxxx:::at:::gmail.com\nspring:\n  mail:\n    host: smtp.gmail.com\n    username: xxxx@gmail.com\n    password: [ App Password - https://support.google.com/accounts/answer/185833?hl=en ]\n    properties:\n      mail:\n        smtp:\n          auth: true\n          ssl:\n            enable: true\n          socketFactory:\n            port: 465\n            class: javax.net.ssl.SSLSocketFactory\n            fallback: false\n```\nin settings.js (deck)\n```\nwindow.spinnakerSettings = {\n// ...\n  notifications: {\n    email: {\n      enabled: true\n    },\n// ...\n```\n\n\n## HipChat\n\nFor Hipchat, you will need to create a hipchat [authentication token](https://www.hipchat.com/docs/apiv2/auth) that is able to post messages. \n\nin echo.yml\n```\nhipchat:\n  enabled: true\n  baseUrl: https://xxx.hipchat.com\n  token: <authToken>\n```\nin settings.js (deck)\n```\nwindow.spinnakerSettings = {\n// ...\n  notifications: {\n    hipchat: {\n      enabled: true,\n      botName: '<username of bot>'\n    },\n// ...\n```\n\n\nNote: your users will need to invite the hipchat bot to private rooms that want to be notified.\n\n## Slack\n\nFor slack, you will need to create a custom bot user (https://api.slack.com/bot-users#how_do_i_create_custom_bot_users_for_my_team), then get the access token associated with the new bot user. \n\nin echo.yml\n```\nslack:\n  enabled: true\n  token: <API token for bot>\n```\n\nin settings.js (deck)\n```\nwindow.spinnakerSettings = {\n// ...\n  notifications: {\n    slack: {\n      enabled: true,\n      botName: '<username of bot>'\n    },\n// ...\n```\n\nNote: your users will need to invite the slack bot to private rooms that want to be notified.\n\n## Twilio\n\nFor twilio, you need to add your account [credentials](https://www.twilio.com/help/faq/twilio-basics/what-is-the-auth-token-and-how-can-i-change-it). \n\nin echo.yml\n```\ntwilio:\n  enabled: true\n  baseUrl: https://api.twilio.com/\n  account: xxx\n  token: xxx\n  from: +18sp-inn-aker\n```\nin settings.js (deck)\n```\nwindow.spinnakerSettings = {\n// ...\n  notifications: {\n    sms: {\n      enabled: true\n    },\n// ...\n```\n\n## Using Notifications\n\nOnce notifications have been configured, you can use them to send changes in pipelines and in the manual judgment stage in Spinnaker.\n\nTo set up an application-wide notification, go to Application -> Config -> Notifications, \n\nClick on 'Add Notification'\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/vXfUsGmzRKLpVCp7vebc_Screen%20Shot%202016-03-28%20at%2012.10.02%20PM.png\",\n        \"Screen Shot 2016-03-28 at 12.10.02 PM.png\",\n        \"1246\",\n        \"646\",\n        \"#4cacc4\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nEnter your notification details. \n\nYou can also set Notifications at the Pipeline level ( under configuration ) and at the stage level ( by clicking on the [ ] Send Notifications for this stage checkbox. \n\n# Setting up Git Triggers in Spinnaker\n\nInstead of listening for events from Github like in the Docker and Jenkins case, direct triggering from git requires a webhook endpoint to be set up in the corresponding VCS. \n\n## Github\n\n### Using Github as a Trigger\n\nGo to your project's Webhooks page, i.e, https://github.com/spinnaker/igor/settings/hooks\n\nClick \"Add webhook\"\n\nenter http://[spinnakerapi]/webhooks/git/github in the Payload URL where spinnakerapi is the location of your gate installation.\n\nselect \"Just the push event\"\n\nmake it active\n\nClick \"Add Webhook\" button\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/OXu6D9gSFiCLIbLlTVcN_github.png\",\n        \"github.png\",\n        \"1184\",\n        \"1220\",\n        \"#6aba4e\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n## Stash\n\nGo to settings / hooks for your repository\n\nAdd a Post Receive webhook\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/abwVq2txSl62VMfqVNGV_stash.png\",\n        \"stash.png\",\n        \"1648\",\n        \"528\",\n        \"#7ea5cc\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nAdd the following URL: http://[gate url]/webhooks/git/stash where gate url is the url to your spinnaker api.\n\nYou are now ready to receive events from this repository.\n\n## BitBucket Cloud\n\nGo to settings / webhooks for your repository\n\nClick 'Add webhook'\n\nAdd a 'Repository Push' or 'Pull Request Merged' webhook\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/2d974bb-BitBucket_Cloud_-_Add_WebHook.png\",\n        \"BitBucket Cloud - Add WebHook.png\",\n        1464,\n        1546,\n        \"#e3e0d8\"\n      ]\n    }\n  ]\n}\n[/block]\nAdd the following URL: http://[gate url]/webhooks/git/bitbucket where gate url is the url to your spinnaker api.\n\nYou are now ready to receive events from this repository.\n\n### Add Git Trigger in Pipeline:\n\nGo to Pipeline > Configuration\n\nSelect Trigger Type to be Git \n\nSet Repository Type to be github, stash, or bitbucket\n\nEnter your Repository organization / user\n\nEnter your Repository name\n\nSave your pipeline\n\n### Notes\n\nYou can access the hash of the build via expression ```${trigger.hash}```\n\n# Add a listening webhook to spinnaker\n\nThe [echo-rest](https://github.com/spinnaker/echo/tree/master/echo-rest) module in spinnaker allows you to set downstream listeners keeping track of Spinnaker events. \n\nWhenever Spinnaker receives an event from Orca, igor, or echo, it will forward these events to the webhooks registered.\n\nA useful pattern is to have an intermediate service that will filter and convert events you care about into the format you expect. \n\n## Configuration in echo.yml\n\n```\nrest:\n  enabled: true\n  endpoints:\n    - \n      wrap: false\n      url: http://listener.com\n    - \n      wrap: false\n      url: http://listener2.com\n```\n\nThis will post every event to listener and listener2\n\n## Wrapping \n\nIf your endpoint expects events of the form \n\n```\n\t{ \"eventName\" : \"abc\", \"payload\" : \"[event json]\"}\n```\n\nyou can wrap the event via this configuration:\n\n```\n  - \n      wrap: true\n      flatten: true\n      url: http://listener3\n      eventName: spinnaker_events\n      fieldName: payload\n```\n\nThe flatten setting will simply make the json in content and details ( see below ) into a json String. \n\n# Event types\n\nHere is an example event:\n\n```\n{\n    \"details\": {\n      \"source\": \"orca\",\n      \"type\": \"orca:task:complete\",\n      \"created\": \"1422487582294\",\n      \"organization\": null,\n      \"project\": null,\n      \"application\": \"asgard\",\n      \"_content_id\": null\n    },\n    \"content\": {\n      \"standalone\": true,\n      \"context\": {\n        \"asgName\": \"asgard-staging-v048\",\n        \"credentials\": \"test\",\n        \"deploy.account.name\": \"test\",\n        \"deploy.server.groups\": {},\n        \"kato.last.task.id\": {\n          \"id\": \"19351\"\n        },\n        \"kato.task.id\": {\n          \"id\": \"19351\"\n        },\n        \"kato.tasks\": [\n          {\n            \"history\": [\n            ],\n            \"id\": \"19351\",\n            \"resultObjects\": []\n          }\n        ],\n        \"notification.type\": \"enableasg\",\n        \"regions\": [\"us-west-1\"],\n        \"targetop.asg.enableAsg.name\": \"asgard-staging-v048\",\n        \"targetop.asg.enableAsg.regions\": [\"us-west-1\"],\n        \"user\": \"clin@netflix.com\",\n        \"zones\": [\"us-west-1a\", \"us-west-1c\"]\n      },\n      \"execution\": ...\n      \"executionId\": \"62ca5574-0629-419a-b9ac-fb873aa165b2\",\n      \"taskName\": \"f92239a7-b57a-408d-9d72-3a77484e050b.enableAsg.monitorAsg.9568e7e5-3c37-4699-9e93-f62118adc7c6\"\n    }\n  }\n```\n\nEvents have a details, which will always be the same.\n\n### details.type\n\nThe type of the event will outline where the event is coming from:\n\n* orca:[task type]:[status] - where task type is either 'pipeline', 'stage' or 'task' and status is 'starting', 'completed', 'failed'\n* build - from igor Jenkins events\n* docker - from igor Docker events\n* git - from git web triggers\n\n### details.application\n\nThe application involved in the execution, this will only exist for orca: type events.\n\n### content.execution\n\nFor orca type events, this is the corrent execution that has the entire pipeline execution.","excerpt":"This page describes how to set up and use the notifications mechanism available in Spinnaker","slug":"notifications-and-events-guide","type":"basic","title":"Notifications and Events Guide"}

Notifications and Events Guide

This page describes how to set up and use the notifications mechanism available in Spinnaker

Out of the box, Spinnaker allows you to configure the following types of notifications: * Email * HipChat * Slack * SMS ( via Twilio ) This is discussed in the Configuring Notifications section below. Additionally, Spinnaker allows you to set webhooks for git triggers. See the [http://www.spinnaker.io/docs/notifications-and-events-guide#section-setting-up-git-triggers-in-spinnaker] section. You can also set Spinnaker to stream all its events to a downstream listener. See the [Add a Webhook to Spinnaker](http://www.spinnaker.io/docs/notifications-and-events-guide#section-add-a-listening-webhook-to-spinnaker) section. Additionally, Spinnaker is capable of handling cron-based triggers and detect changes in Jenkins builds and Docker images. This functionality will be documented at a later time. # Configuring Notifications Notification configurations are set in echo.yml and settings.js. On a single instance virtual machine installation, notification values can also be set in spinnaker-local.yml, which will pass the details to echo.yml and settings.js. You will need to set the `spinnaker.baseUrl` configuration value which is used by spinnaker templates. This should point back to the url for your spinnaker's UI ( deck ) instance. This url is used in notifications to link back to your spinnaker instance. ## Email Email in spinnaker is provided by [Spring Boot Mail starter](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-email.html). The following is an example of using Gmail to send notifications. in echo.yml ``` mail: enabled: true from: xxxx@gmail.com spring: mail: host: smtp.gmail.com username: xxxx@gmail.com password: [ App Password - https://support.google.com/accounts/answer/185833?hl=en ] properties: mail: smtp: auth: true ssl: enable: true socketFactory: port: 465 class: javax.net.ssl.SSLSocketFactory fallback: false ``` in settings.js (deck) ``` window.spinnakerSettings = { // ... notifications: { email: { enabled: true }, // ... ``` ## HipChat For Hipchat, you will need to create a hipchat [authentication token](https://www.hipchat.com/docs/apiv2/auth) that is able to post messages. in echo.yml ``` hipchat: enabled: true baseUrl: https://xxx.hipchat.com token: <authToken> ``` in settings.js (deck) ``` window.spinnakerSettings = { // ... notifications: { hipchat: { enabled: true, botName: '<username of bot>' }, // ... ``` Note: your users will need to invite the hipchat bot to private rooms that want to be notified. ## Slack For slack, you will need to create a custom bot user (https://api.slack.com/bot-users#how_do_i_create_custom_bot_users_for_my_team), then get the access token associated with the new bot user. in echo.yml ``` slack: enabled: true token: <API token for bot> ``` in settings.js (deck) ``` window.spinnakerSettings = { // ... notifications: { slack: { enabled: true, botName: '<username of bot>' }, // ... ``` Note: your users will need to invite the slack bot to private rooms that want to be notified. ## Twilio For twilio, you need to add your account [credentials](https://www.twilio.com/help/faq/twilio-basics/what-is-the-auth-token-and-how-can-i-change-it). in echo.yml ``` twilio: enabled: true baseUrl: https://api.twilio.com/ account: xxx token: xxx from: +18sp-inn-aker ``` in settings.js (deck) ``` window.spinnakerSettings = { // ... notifications: { sms: { enabled: true }, // ... ``` ## Using Notifications Once notifications have been configured, you can use them to send changes in pipelines and in the manual judgment stage in Spinnaker. To set up an application-wide notification, go to Application -> Config -> Notifications, Click on 'Add Notification' [block:image] { "images": [ { "image": [ "https://files.readme.io/vXfUsGmzRKLpVCp7vebc_Screen%20Shot%202016-03-28%20at%2012.10.02%20PM.png", "Screen Shot 2016-03-28 at 12.10.02 PM.png", "1246", "646", "#4cacc4", "" ] } ] } [/block] Enter your notification details. You can also set Notifications at the Pipeline level ( under configuration ) and at the stage level ( by clicking on the [ ] Send Notifications for this stage checkbox. # Setting up Git Triggers in Spinnaker Instead of listening for events from Github like in the Docker and Jenkins case, direct triggering from git requires a webhook endpoint to be set up in the corresponding VCS. ## Github ### Using Github as a Trigger Go to your project's Webhooks page, i.e, https://github.com/spinnaker/igor/settings/hooks Click "Add webhook" enter http://[spinnakerapi]/webhooks/git/github in the Payload URL where spinnakerapi is the location of your gate installation. select "Just the push event" make it active Click "Add Webhook" button [block:image] { "images": [ { "image": [ "https://files.readme.io/OXu6D9gSFiCLIbLlTVcN_github.png", "github.png", "1184", "1220", "#6aba4e", "" ] } ] } [/block] ## Stash Go to settings / hooks for your repository Add a Post Receive webhook [block:image] { "images": [ { "image": [ "https://files.readme.io/abwVq2txSl62VMfqVNGV_stash.png", "stash.png", "1648", "528", "#7ea5cc", "" ] } ] } [/block] Add the following URL: http://[gate url]/webhooks/git/stash where gate url is the url to your spinnaker api. You are now ready to receive events from this repository. ## BitBucket Cloud Go to settings / webhooks for your repository Click 'Add webhook' Add a 'Repository Push' or 'Pull Request Merged' webhook [block:image] { "images": [ { "image": [ "https://files.readme.io/2d974bb-BitBucket_Cloud_-_Add_WebHook.png", "BitBucket Cloud - Add WebHook.png", 1464, 1546, "#e3e0d8" ] } ] } [/block] Add the following URL: http://[gate url]/webhooks/git/bitbucket where gate url is the url to your spinnaker api. You are now ready to receive events from this repository. ### Add Git Trigger in Pipeline: Go to Pipeline > Configuration Select Trigger Type to be Git Set Repository Type to be github, stash, or bitbucket Enter your Repository organization / user Enter your Repository name Save your pipeline ### Notes You can access the hash of the build via expression ```${trigger.hash}``` # Add a listening webhook to spinnaker The [echo-rest](https://github.com/spinnaker/echo/tree/master/echo-rest) module in spinnaker allows you to set downstream listeners keeping track of Spinnaker events. Whenever Spinnaker receives an event from Orca, igor, or echo, it will forward these events to the webhooks registered. A useful pattern is to have an intermediate service that will filter and convert events you care about into the format you expect. ## Configuration in echo.yml ``` rest: enabled: true endpoints: - wrap: false url: http://listener.com - wrap: false url: http://listener2.com ``` This will post every event to listener and listener2 ## Wrapping If your endpoint expects events of the form ``` { "eventName" : "abc", "payload" : "[event json]"} ``` you can wrap the event via this configuration: ``` - wrap: true flatten: true url: http://listener3 eventName: spinnaker_events fieldName: payload ``` The flatten setting will simply make the json in content and details ( see below ) into a json String. # Event types Here is an example event: ``` { "details": { "source": "orca", "type": "orca:task:complete", "created": "1422487582294", "organization": null, "project": null, "application": "asgard", "_content_id": null }, "content": { "standalone": true, "context": { "asgName": "asgard-staging-v048", "credentials": "test", "deploy.account.name": "test", "deploy.server.groups": {}, "kato.last.task.id": { "id": "19351" }, "kato.task.id": { "id": "19351" }, "kato.tasks": [ { "history": [ ], "id": "19351", "resultObjects": [] } ], "notification.type": "enableasg", "regions": ["us-west-1"], "targetop.asg.enableAsg.name": "asgard-staging-v048", "targetop.asg.enableAsg.regions": ["us-west-1"], "user": "clin@netflix.com", "zones": ["us-west-1a", "us-west-1c"] }, "execution": ... "executionId": "62ca5574-0629-419a-b9ac-fb873aa165b2", "taskName": "f92239a7-b57a-408d-9d72-3a77484e050b.enableAsg.monitorAsg.9568e7e5-3c37-4699-9e93-f62118adc7c6" } } ``` Events have a details, which will always be the same. ### details.type The type of the event will outline where the event is coming from: * orca:[task type]:[status] - where task type is either 'pipeline', 'stage' or 'task' and status is 'starting', 'completed', 'failed' * build - from igor Jenkins events * docker - from igor Docker events * git - from git web triggers ### details.application The application involved in the execution, this will only exist for orca: type events. ### content.execution For orca type events, this is the corrent execution that has the entire pipeline execution.