"Fossies" - the Fresh Open Source Software Archive

Member "senlin-8.0.0/doc/source/contributor/receiver.rst" (16 Oct 2019, 10068 Bytes) of package /linux/misc/openstack/senlin-8.0.0.tar.gz:

As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the latest Fossies "Diffs" side-by-side code changes report for "receiver.rst": 7.0.0_vs_8.0.0.



A Receiver is an abstract resource created in Senlin engine to handle operation automation. You can create a receiver to trigger a specific action on a cluster on behalf of a user when some external alarms or events are fired.

A receiver can be of different types. The type of a receiver is specified when being created. Currently, two receiver types are supported: webhook and message. For a webhook receiver, a Webhook URI is generated for users or programs to trigger a cluster action by send a HTTP POST request. For a message receiver, a Zaqar queue is created for users or programs to trigger a cluster action by sending a message.

A receiver encapsulates the information needed for triggering an action. These information may include:

In the long term, senlin may support user-defined actions where action will be interpreted as the UUID or name of a user-defined action.

Creating a Receiver

Creating a webhook receiver

When a user requests to create a webhook receiver by invoking the openstack command, the request comes with at least three parameters: the receiver type which should be webhook, the targeted cluster and the intended action to invoke when the receiver is triggered. Optionally, the user can provide some additional parameters to use and/or the credentials of a different user.

When the Senlin API service receives the request, it does three things:

Finally, Senlin engine returns a dictionary containing the properties of the receiver object.

Creating a message receiver

When a user requests to create a message receiver by invoking openstack command, the receiver type message is the only parameter need to be specified.

When the Senlin API service receives the request, it does the following things:

Finally, Senlin engine returns a dictionary containing the properties of the receiver object.

Triggering a Receiver

Different types of receivers are triggered in different ways. For example, a webhook receiver is triggered via the alarm_url channel; a message queue receiver can be triggered via messages delivered in a shared queue.

Triggering a Webhook

When triggering a webhook, a user or a software sends a POST request to the receiver's alarm_url channel, which is a specially encoded URL. This request is first processed by the webhook middleware before arriving at the Senlin API service.

The webhook middleware checks this request and parses the format of the request URL. The middleware attempts to find the receiver record from Senlin database and see if the named receiver does exist. If the receiver is found, it then tries to load the saved credentials. An error code 404 will be returned if the receiver is not found.

After having retrieved the credentials, the middleware will proceed to get a Keystone token using credentials combined with Senlin service account info. Using this token, the triggering request can proceed along the pipeline of middlewares. An exception will be thrown if the authentication operation fails.

When the senlin engine service receives the webhook triggering request it creates an action based on the information stored in the receiver object. The newly created action is then dispatched and scheduled by a scheduler to perform the expected operation.

Triggering a Message Receiver

When triggering a message receiver, a user or a software needs to send message(s) to the Zaqar queue whose name can be found from the channel data of the receiver. Then the Zaqar service will notify the Senlin service for the message(s) by sending a HTTP POST request to the Senlin subscriber URL. Note: this POST request is sent using the Zaqar trustee user credential and the trust_id defined in the subscriber. Therefore, Senlin will recognize the requester as the receiver owner rather than the Zaqar service user.

Then Senlin API then receives this POST request, parses the authentication information and then makes a receiver_notify RPC call to the senlin engine.

The Senlin engine receives the RPC call, claims message(s) from Zaqar and then builds action(s) based on payload contained in the message body. A message will be ignored if any one of the following conditions is met:

Then those newly created action(s) will be scheduled to run to perform the expected operation.


Webhook Receiver

When requesting to create a webhook receiver, the requester can choose to provide some credentials by specifying the actor property of the receiver. This information will be used for invoking the webhook in the future. There are several options to provide these credentials.

If the credentials to use is explicitly specified, Senlin will save it in the receiver DB record. When the webhook is invoked later, the saved credentials will be used for authentication with Keystone. Senlin engine won't check if the provided credentials actually works when creating the receiver. The check is postponed to the moment when the receiver is triggered.

If the credentials to use is not explicitly provided, Senlin will assume that the receiver will be triggered in the future using the requester's credential. To make sure the future authentication succeeds, Senlin engine will extract the user ID from the invoking context and create a trust between the user and the senlin service account, just like the way how Senlin deals with other operations.

The requester must be either the owner of the targeted cluster or he/she has the admin role in the project. This is enforced by the policy middleware. If the requester is the admin of the project, Senlin engine will use the cluster owner's credentials (i.e. a trust with the Senlin user in this case).

Message Receiver

When requesting to create a message receiver, the requester does not need to provide any extra credentials. However, to enable token based authentication for Zaqar message notifications, Zaqar trustee user information like auth_type, auth_url, username, password, project_name, user_domain_name, project_domain_name, etc. must be configured in the Senlin configuration file. By default, Zaqar trustee user is the same as Zaqar service user, for example "zaqar". However, operators are also allowed to specify other dedicated user as Zaqar trustee user for message notifying. Therefore, please ensure Zaqar trustee user information defined in senlin.conf are identical to the ones defined in zaqar.conf.