Proposed new module: deploy_helper

[ramondelafuente]

After a discussion on the ansible-project mailinglist, this module was formed to help lower the boilerplate needed to deploy web-projects.
See the thread here: https://groups.google.com/d/msg/ansible-project/R3Kr2uMYUt4/b-WLJ3m6L1AJ

There are tests to accompany this module: ansible/ansible#9567

This pull request is accompanied by an additional guide for the documentation: ansible/ansible#9566

Until both are merged, the documentation for this module contains an invalid link to doc:guide_deploy_helper

[mpdehaan]

bumping priority of this one. good stuff, thanks!

[ramondelafuente]

No prob. I added the link to the tests pull request in the description, in case you'd want those in as well.

[swalkinshaw]

@ramondelafuente this is awesome. Great addition to Ansible.

Not sure if this is the best place for discussion now, or that thread. But the only thing missing that I use from Capistrano is a simple deploy history log file. What do you think about making that part of the finalize state?

[beberlei]

• shared_state should be an array of folders, not just a single one.
• tests are missing?
• Can you add some examples how to actually use this? Would i use git to create a new release into the releases_path and then invoke deploy helper?

[ramondelafuente]

@beberlei
The shared_state in this case is only the folder containing shared state folders (the path to). It returns a deploy_helper.shared_path fact that you can use later. If you only refer to the fact later in your role, you can easily change the path by adding it to the deploy_helper call deploy_helper: path=/x shared_path=/y. The rest of your role would still work. This goes for all the paths, since they have default values.

As stated in the description: The tests are in a separate pull request because they are currently still in the Ansible main repo: ansible/ansible#9567

Usage examples are inside the module (but not so readable because it generates automatically to the docs). Basically it would be:

- deploy_helper: path=/some/path
  ...do your thing (including linking your own shared folders with the file module)...
- deploy_helper: path=/some/path release={{ deploy_helper.new_release }} state=finalize

So an example for the shared folders:

- name: Add symlinks from the new release to the shared folder
  file: path='{{ deploy_helper.new_release_path }}/{{ item.path }}'
         src='{{ deploy_helper.shared_path }}/{{ item.src }}'
         state=link
  with_items:
    - { path: "app/sessions", src: "sessions" }
    - { path: "web/uploads",  src: "uploads" }

[ramondelafuente]

@beberlei
Perhaps also a bit more clarifying (from the mailing list):

From the perspective of a consumer, I think a common deploy role looks something like this (following along the lines of a deploy procedure that uses releases and a ‘current’ symlink):
The numbers are a guess at the number of tasks it would take to complete the task.

1 create the project root folder
1 create a timestamp
1 create a releases folder
1 create the shared folder
~~~ clone, build, prepare ~~~ (outside of the scope of the module)
1 remove build in progress file
1 create a symlink
3 delete the old releases [find, filter, delete]

This should take about 9-ish tasks

When we take a “deploy_helper" module into account, it could look like this:

1 deploy state=present path=/path/to/root
- creates project root folder
- returns a timestamp
- creates the releases folder
- creates the shared folder (optional)
~~~ clone, build, prepare ~~~ (outside of the scope of the module)
1 deploy state=finalize
- removes build in progress file
- creates a symlink
- optionally does cleanup

This could be done in 2 tasks (+1 if we exclude the ‘shared' folder creation from the module)

[beberlei]

@ramondelafuente thanks for the detailed response

[ramondelafuente]

@swalkinshaw
I'm not quite familiar with the logging part of Capistrano. What we've currently started doing is adding a slack: msg='deployed project X' message to our #deployment channel in Slack after the finalize task...
but this could have been anything, and at any point in the role. That's why I'm a bit reluctant to add logging because that feels so particular to preference that I'm not sure where to write what.
Also, the way Ansible works, the module in state=finalize won't have any knowledge of the states that where called before.

[swalkinshaw]

@ramondelafuente yeah I definitely don't want to get into providing notifications since there's a million different services. Capistrano just appends a new line to a text file in your project root with this string:

Branch %{branch} (at %{sha}) deployed as release %{release} by %{user}

See https://github.com/capistrano/capistrano/blob/2860ad22acaeeabd7665bedd42080c3508c70abd/lib/capistrano/tasks/deploy.rake#L171-L178

I believe user is the local user of the person doing the deploy. This could be simplified a little as well but I think it's pretty useful. For example I have a WP plugin that just parses it to provide a nice deploy history UI.

But it's also easy to do on your own:

- name: Log deploys
  lineinfile: dest="{{ deploy_helper.project_path }}" line="{{ deploy_helper.new_release}} deployed by {{ lookup('env', 'USER') }}"

Although I just realized there's no direct way to get the deployed sha/branch/version. Capistrano captures either the version you specified, or the latest commit SHA1 that was deployed.

Not trying to bloat this module, just wondering about some things I'm used to in Capistrano.

[ramondelafuente]

Well, if you're deploying anything you probably already know the version (or at leasy you should). We developed this module for use within our galaxy role - and using that you provide the {{ project_version }} variable, for example a git tag like v1.20.3.

But precisely because it's so easy to log on your own, there is no default logging.

Also: thanks for providing feedback, I'm certainly no capistrano expert so I'l probably be surprised about what people are missing :-)

[swalkinshaw]

@ramondelafuente I'm good with this 👍. A lot of people just keep master as their "deployable" branch without explicit releases but I can always just capture the latest git commit and record the variable to use in the log/notifications.

[beberlei]

Any news on this one? It would be super useful to have it.

[kingcrunch]

Hi @ramondelafuente
I'm still interested too. :)

[bcoca]

sorry for the delay, I'll be reviewing this soon

[sergeifilippov]

+1 for this PR.

If this is included, many people will ditch Capistrano(like tools) from their already busy lives. =]

[ramondelafuente]

This PR is now without P* label. Is that a good or a bad sign?

[tersmitten]

@ramondelafuente: I think good, see

[ramondelafuente]

I assumed the P* where priority labels, it was initially P3, then bumped to P2 - but now P-less so I was just wondering what that meant :-)

[gregdek]

LOL -- this looks very popular. :)

And since @ramondelafuente is also an owner of other Extras modules, I'm adding the "owner_pr" tag as well.

[gregdek]

If we can find one more official reviewer to give this a +1, we can merge. Boilerplate of new official policy follows:

---

Thanks for submitting your module to Ansible Extras. Our policy is that each new module needs to be reviewed and approved by at least two official module reviewers, the list of whom can be found here: https://github.com/ansible/ansible-modules-extras/blob/devel/REVIEWERS.md

Because you’re already an approved reviewer, we assume that you’ve reviewed your own module; you just need to find one other person to review, and you’re all set.

To ensure that your module has the best chance of being approved, please double-check that you adhere to the Ansible module guidelines: http://docs.ansible.com/developing_modules.html#module-checklist

[ramondelafuente]

I've rebased this with devel, still looks good to go. But I'll go though it one last time to see if there's anything outdated there, besides the version_added.

I'll join one of the community hangouts if I can to talk about getting that +1, because I don't seem to know any of the other maintainers :-)

[gregdek]

Yeah, I think we're going to try to have some explicit review-a-thons soon. Thanks for your patience.

[MikeParkin]

Any news on this one? Would be great to have it!

[robynbergeron]

Hi @ramondelafuente -- Adding new process. We will be evaluating all new module PRs according to this process, effective immediately.

Thanks for submitting this new module to Ansible Extras! This module is now in community review, a process that is open to all Ansible users. In order for this module to be approved, it must gain the following votes:

“works_for_me”: If you have tested the module thoroughly, including testing of all of the module’s options, and if the module works for you, please add “works_for_me” in the comments.

“passes_guidelines”: If you have gone through the module guidelines and the module meets all of the requirements, please add “passes_guidelines” in the comments. Guidelines are available here: http://docs.ansible.com/developing_modules.html#module-checklist

“needs_revision”: If the module fails to work for you, or if it doesn’t meet guidelines, please add “needs_revision” in the comments with details about what needs to be fixed.

When a module has both “works_for_me” and “passes_guidelines” tags, we will promote the module for inclusion in Ansible Extras. At this point, you will be expected to maintain the module by fixing bugs and evaluating pull requests in a timely manner.

Thanks again for submitting your Ansible module!

[robynbergeron]

Also, hi, @kingcrunch @MikeParkin @swalkinshaw @beberlei -- the above info on new process means that if you'd like to test this out and provide reviews to help get it approved and merged, you can do so :) It looks like lots of people have interest in this one so hopefully the interested folks can lend a hand and review! :)

[ramondelafuente]

@robynbergeron I have rebased this PR on devel, and updated (I believe) to the new module guidelines.
I thinks it's good to go now.

[robynbergeron]

@ramondelafuente -- awesome, thank you! And thanks for sticking with this one -- I am hopeful that we will get this approved before we have to buy it a birthday cake. :)

Attention, @MikeParkin @beberlei @kingcrunch @swalkinshaw (and adding @bcoca, who I know is busy but did express interest previously!) -- in case you missed the previous comment.... YOU, yes you, are able to provide the necessary reviews to get this module included in extras. Read on for more info!

**

This module is now in community review, a process that is open to all Ansible users. In order for this module to be approved, it must gain the following votes:

“works_for_me”: If you have tested the module thoroughly, including testing of all of the module’s options, and if the module works for you, please add “works_for_me” in the comments.

“passes_guidelines”: If you have gone through the module guidelines and the module meets all of the requirements, please add “passes_guidelines” in the comments. Guidelines are available here: http://docs.ansible.com/developing_modules.html#module-checklist

“needs_revision”: If the module fails to work for you, or if it doesn’t meet guidelines, please add “needs_revision” in the comments with details about what needs to be fixed.

When a module has both “works_for_me” and “passes_guidelines” tags, we will promote the module for inclusion in Ansible Extras.

[swalkinshaw]

works_for_me

[resmo]

passes_guidelines