Senlin/webhook
Webhook
Webhook is used to trigger a specific action of a senlin entity, typically scaling out/in action of a cluster.
Design
Workflow
1. User create a webhook through webhook API. User need to specify what action and which senlin entity this webhook is linked to. Also for some specific actions, user can define the parameters they want to use when invoking the cluster action API, e.g. the adjustment of scaling operation; User also HAVE TO specify the credential they want to use for triggering the webhook and this credential will be used by Senlin service later to execute the real action, e.g. cluster scaling.
2. Senlin service receives the request and 1)Create a webhook object and generate a webhook url, like webhooks/$webhook_id/trigger; 2)Encrypt the credential information to ensure it won't be hacked;
3. User get the url of webhook back from Senlin service.
4. User trigger the webhook by sending a post request to its url. No any extra credential is needed here.
5. Webhook middleware of Senlin service handles this post request and decrypt the credential and then tries to validate the credential from keystone. If succeed, the credential token will be added to this post request and then send to next middleware in pipeline, usually keystone auth_token. If not, an exception will be raised and this webhook triggering fail.
6. Senlin engine receives the webhook triggering request and generates action based on the webhook, e.g. obj_type, obj_id and action name;
7. Action is scheduled by Senlin scheduler and finish the real scaling operation, e.g. cluster scale out;
Implementation
DB model
A webhook DB object includes the following properties:
- id: the uuid of webhook
- name: the name of webhook (optional)
- user: the id of user who created the webhook
- project: the project id of user who created the webhook.
- domain: the domain of the user who created the webhook
- created_time
- deleted_time
- obj_id: the id of senlin entity(cluster, or node) the webhook bound to
- obj_type: the type of senlin entity(cluster, or node) the webhook bound to
- action: action(scalingin, scalingout) of the target the webhook bound to
- credential: credential the will be used to invoke target action API, e.g. clusters/$cluster_id/action
- params: parameters that will be included when invoke the target action API, e.g. adjustment of scaling operation
How to use
1. Create a cluster;
2. Attach a ScalingPolicy to the cluster;
3. Create a webhook and specify the *clusterID* as obj_id, *cluster* as obj_type and *CLUSTER_SCALE_OUT* or *CLUSTER_SCALE_IN* as the action. Senlin service will return the webhook information with its webhook_url. User can use this url to trigger the cluster's scale_out or scale_in action;
Note: The webhook_url can only be got at the first time the webhook is created. Anyone who has the webhook_url can trigger the cluster scaling action. The webhook url can be used in two different ways:
1. Simply sending a POST request to this url without any headers and body. e.g. curl -i -X 'POST' $WEBHOOK_URL. This will directly trigger a cluster scaling operation and the scaling result depends on the ScalingPolicy that attached to the cluster; If no ScalingPolicy is attached to the cluster, default 1 node will be added/deleted;
2. Send a POST request with parameter in the body, e.g. curl -i -X 'POST' $WEBHOOK_URL -H 'Content-type: application/json' --data '{"params": {"count": 2}}'. Using this way, user can specify how much nodes they want to add/delete during this scaling progress. If a ScalingPolicy has been attached to cluster, the *count* will be checked to ensure it doesn't break the rule defined in policy, e.g. max/min size limitation. If no ScalingPolicy is attached to cluster, the exact number of nodes will be added/deleted from cluster.
