service-alerts-client

README

Service Alerts Client

Service Alerts Client allows service authors to send alert emails via the Cloud Foundry Notifications Service to all users with the SpaceDeveloper role in the configured Cloud Foundry space.

Installation

Clone the git repository at $GOPATH/src/github.com/pivotal-cf and compile it with go install github.com/pivotal-cf/service-alerts-client/cmd/send-service-alert.

Cloud Foundry set up

The tool requires:

• A CF user (with SpaceAuditor role as a minimum) to query the CF API.
• A UAA client (with the notifications.write authority as a minimum) to invoke the CF notifications service.

Here is an example setup:

CF space auditor

We recommend creating a CF user with least privilege to query the CF API and provide their credentials in the config file. They need to have a space role in the configured space:

cf target -o CF_ORG -s CF_SPACE
cf create-user SPACE_AUDITOR_USERNAME SPACE_AUDITOR_PASSWORD
cf set-space-role SPACE_AUDITOR_USERNAME CF_ORG CF_SPACE SpaceAuditor

Service alert recipient

Only CF users with the space developer role in the configured space will receive emails.

cf set-space-role SPACE_DEV_USERNAME CF_ORG CF_SPACE SpaceDeveloper

UAA client

We recommend creating a UAA client with the least privilege to send notifications to a space. A full list of related permissions can be found in the CF notifications service documentation.

uaac client add CLIENT_NAME \
  --secret CLIENT_SECRET \
  --authorized_grant_types client_credentials \
  --authorities notifications.write

Usage

As a library

There is an example go program that calls the service-alerts-client here. The config values are redacted so ensure to fill with values of your set up. Make sure the space you use has a user with an email address.

On the command line

send-service-alert \
  -config <config file path> \
  -product <product name> \
  -service-instance <OPTIONAL: service instance ID> \
  -subject <email subject> \
  -content <email content>

The format of the config file:

cloud_controller:
  url: <Cloud Foundry API URL>
  user: <Cloud Foundry username with SpaceAuditor role in cf_space>
  password: <Cloud Foundry password>
notifications:
  service_url: <Cloud Foundry notification service URL>
  cf_org: <Cloud Foundry org name>
  cf_space: <Cloud Foundry space name>
  reply_to: <OPTIONAL: email reply-to address. This is required for some SMTP servers>
  client_id: <UAA client ID with authorities to send notifications>
  client_secret: <UAA client secret>
timeout_seconds: <OPTIONAL: default is 60>
skip_ssl_validation: <OPTIONAL: ignore TLS certification verification errors>

HTTP retry strategy

HTTP requests will be retried if they fail due to a network error, a response status code of 5xx, or 404 from the Cloud Foundry Router. HTTP requests will be attempted with exponential back-off between attempts.

The timeout refers to a global maximum time to send a service alert, not a timeout per HTTP request.

Email content

The email that is sent will have the subject CF Notification: [Service Alert][<product>] <subject>. The body is plain text only.

When the service-instance flag is set, the body will be in the following format:

You received this message because you belong to the "<org>" space in the "<space>" organization.
Alert from <product>, service instance <service instance ID>:

<content>

[Alert generated at <RFC 3339 datetime>]

When service-instance flag is not set, the body will be in the following format:

Alert from <product>:

<content>

[Alert generated at <RFC 3339 datetime>]