Create an API endpoint for Zuul

Registered by Julien Vey on 2014-01-30

We need an unauthenticated API endpoint which someone can post to to trigger the zuul workflow

A trigger is applied on a plan. In order to avoid potentially exposing the plan_id to the outside world, a trigger_id should be generated when a plan is created.
1) Register a plan
2) This will generate a trigger_id which will be returned to the user
3) User would use this id and construct the POST url within the git hook
4) When users push their code to their git repo, POST would be sent to /v1/public/triggers/{trigger_id}
5) Solum would retrieve the plan corresponding to the trigger id and handing the request over to Zuul

Notes :
1. The endpoint has to be unauthenticated so that any git repo can POST to this endpoint.
2. Git server-side hooks are private to the repo administrator. This means the POST url can not be stolen easily and used for DDOS.
3. Optionally, we could have a "trigger_enable attribute on a plan to switch on/off the possibility to remote trigger a change on the plan
see http://git-scm.com/book/en/Customizing-Git-Git-Hooks#Server-Side-Hooks

Blueprint information

Status:
Complete
Approver:
Adrian Otto
Priority:
Undefined
Drafter:
Julien Vey
Direction:
Needs approval
Assignee:
Julien Vey
Definition:
Approved
Series goal:
None
Implementation:
Implemented
Milestone target:
None
Started by
Angus Salkeld on 2014-05-26
Completed by
Angus Salkeld on 2014-05-26

Related branches

Sprints

Whiteboard

(devdatta): The user steps involved would be the following:
1) Register a plan
2) This will generate an application id which will be returned to the user
3) User would use this id and construct the POST url within the git hook
4) When users push their code to their git repo, POST would be sent to /v1/trigger/{application_id}

Is the git hook typically checked in within the repository? If so, and if the repository is public, then
it would be possible for anyone to see the application specific trigger URL and DOS it.

(julienvey): this will be a server-side hook (http://git-scm.com/book/en/Customizing-Git-Git-Hooks#Server-Side-Hooks) not visible to anyone other than the repo administrator. It is not included in a 'git clone', neither are any other hooks. Citation from the above link : "it’s important to note that these scripts aren’t transferred during a clone"

(devdatta): When you say it is not included in 'git clone', are you saying that the hook is not checked in with the code? (julienvey: Yes) If so, that is good. Even if the repository is public, this won't be an issue if the hook is not stored with the code.
Btw, do you mind putting a reference to documentation on git hook where what you mentioned above is identified?

Gerrit topic: https://review.openstack.org/#q,topic:bp/zuul-endpoint-3,n,z

Addressed by: https://review.openstack.org/70975
    Create an API endpoint for Zuul

---------------------

(paulmo): I have some recommendations for Zuul trigger endpoint security:

* Require SSL to activate the Zuul trigger

* The Zuul trigger should have a VERY quick and low resource method of performing a sanity check to validate that a previous authenticated user action set up a proper event to process. Trying to help eliminate some DoS attack potential.

* Add backoff times to Zuul triggers to help mitigate brute forcing URLs (might be >=M2)

* Should not use plan_id for trigger_id

* Make sure that a high quality PRNG is being used to generate the trigger_id

* User should have a way to changing trigger_id if they suspect that the id may be compromised (this is probably >=M2)

* Would recommend that Zuul triggers can be disabled at the operator level (system-wide) and at the user level (whatever that might be since we didn't define our RBAC completely yet).

* Would recommend that Zuul triggers are disabled by default (secure by default) and add a Solum control plane log message that Zuul triggers are enabled (just a slightly less secure configuration potentially).

Gerrit topic: https://review.openstack.org/#q,topic:bp/zuul-endpoint,n,z

Addressed by: https://review.openstack.org/71296
    Check plan existence when a trigger is posted

Addressed by: https://review.openstack.org/71025
    Add trigger_id attribute to the 'plan' db object

Gerrit topic: https://review.openstack.org/#q,topic:bp/zuul-endpoint-hook,n,z

Addressed by: https://review.openstack.org/77177
    Remove get_by_uuid method from assembly

(?)

Work Items

This blueprint contains Public information 
Everyone can see this information.