removed link to guide, and added more documentation and examples
This commit is contained in:
Ramon de la Fuente
parent
559a7e7a32
commit
35ec03ec00
1 changed files with 63 additions and 40 deletions
|
|
@ -5,12 +5,21 @@ DOCUMENTATION = '''
|
|||
module: deploy_helper
|
||||
version_added: "1.8"
|
||||
author: Ramon de la Fuente, Jasper N. Brouwer
|
||||
short_description: Manages the folders for deploy of a project
|
||||
short_description: Manages some of the steps common in deploying projects.
|
||||
description:
|
||||
- Manages some of the steps common in deploying projects.
|
||||
It creates a folder structure, cleans up old releases and manages a symlink for the current release.
|
||||
|
||||
For more information, see the :doc:`guide_deploy_helper`
|
||||
- The Deploy Helper manages some of the steps common in deploying software.
|
||||
It creates a folder structure, manages a symlink for the current release
|
||||
and cleans up old releases.
|
||||
- "Running it with the C(state=query) or C(state=present) will return the C(deploy_helper) fact.
|
||||
C(project_path), whatever you set in the path parameter,
|
||||
C(current_path), the path to the symlink that points to the active release,
|
||||
C(releases_path), the path to the folder to keep releases in,
|
||||
C(shared_path), the path to the folder to keep shared resources in,
|
||||
C(unfinished_filename), the file to check for to recognize unfinished builds,
|
||||
C(previous_release), the release the 'current' symlink is pointing to,
|
||||
C(previous_release_path), the full path to the 'current' symlink target,
|
||||
C(new_release), either the 'release' parameter or a generated timestamp,
|
||||
C(new_release_path), the path to the new release folder (not created by the module)."
|
||||
|
||||
options:
|
||||
path:
|
||||
|
|
@ -18,6 +27,7 @@ options:
|
|||
aliases: ['dest']
|
||||
description:
|
||||
- the root path of the project. Alias I(dest).
|
||||
Returned in the C(deploy_helper.project_path) fact.
|
||||
|
||||
state:
|
||||
required: false
|
||||
|
|
@ -26,23 +36,25 @@ options:
|
|||
description:
|
||||
- the state of the project.
|
||||
C(query) will only gather facts,
|
||||
C(present) will create the project,
|
||||
C(finalize) will create a symlink to the newly deployed release,
|
||||
C(present) will create the project I(root) folder, and in it the I(releases) and I(shared) folders,
|
||||
C(finalize) will remove the unfinished_filename file, create a symlink to the newly
|
||||
deployed release and optionally clean old releases,
|
||||
C(clean) will remove failed & old releases,
|
||||
C(absent) will remove the project folder (synonymous to M(file) with state=absent)
|
||||
C(absent) will remove the project folder (synonymous to the M(file) module with C(state=absent))
|
||||
|
||||
release:
|
||||
required: false
|
||||
description:
|
||||
- the release version that is being deployed (defaults to a timestamp %Y%m%d%H%M%S). This parameter is
|
||||
optional during C(state=present), but needs to be set explicitly for C(state=finalize). You can use the
|
||||
generated fact C(release={{ deploy_helper.new_release }})
|
||||
- the release version that is being deployed. Defaults to a timestamp format %Y%m%d%H%M%S (i.e. '20141119223359').
|
||||
This parameter is optional during C(state=present), but needs to be set explicitly for C(state=finalize).
|
||||
You can use the generated fact C(release={{ deploy_helper.new_release }}).
|
||||
|
||||
releases_path:
|
||||
required: false
|
||||
default: releases
|
||||
description:
|
||||
- the name of the folder that will hold the releases. This can be relative to C(path) or absolute.
|
||||
Returned in the C(deploy_helper.releases_path) fact.
|
||||
|
||||
shared_path:
|
||||
required: false
|
||||
|
|
@ -50,12 +62,14 @@ options:
|
|||
description:
|
||||
- the name of the folder that will hold the shared resources. This can be relative to C(path) or absolute.
|
||||
If this is set to an empty string, no shared folder will be created.
|
||||
Returned in the C(deploy_helper.shared_path) fact.
|
||||
|
||||
current_path:
|
||||
required: false
|
||||
default: current
|
||||
description:
|
||||
- the name of the symlink that is created when the deploy is finalized. Used in C(finalize) and C(clean).
|
||||
Returned in the C(deploy_helper.current_path) fact.
|
||||
|
||||
unfinished_filename:
|
||||
required: false
|
||||
|
|
@ -81,7 +95,7 @@ options:
|
|||
notes:
|
||||
- Facts are only returned for C(state=query) and C(state=present). If you use both, you should pass any overridden
|
||||
parameters to both calls, otherwise the second call will overwrite the facts of the first one.
|
||||
- When using C(state=clean), the releases are ordered by creation date. You should be able to switch to a
|
||||
- When using C(state=clean), the releases are ordered by I(creation date). You should be able to switch to a
|
||||
new naming strategy without problems.
|
||||
- Because of the default behaviour of generating the I(new_release) fact, this module will not be idempotent
|
||||
unless you pass your own release name with C(release). Due to the nature of deploying software, this should not
|
||||
|
|
@ -89,41 +103,50 @@ notes:
|
|||
'''
|
||||
|
||||
EXAMPLES = '''
|
||||
Example usage for the deploy_helper module.
|
||||
|
||||
tasks:
|
||||
# Typical usage:
|
||||
- deploy_helper: path=/path/to/root state=present
|
||||
...some_build_steps_here, like a git clone to {{ deploy_helper.new_release_path }} for example...
|
||||
- deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize
|
||||
# Typical usage:
|
||||
- name: Initialize the deploy root and gather facts
|
||||
deploy_helper: path=/path/to/root
|
||||
- name: Clone the project to the new release folder
|
||||
git: repo=git://foosball.example.org/path/to/repo.git dest={{ deploy.new_release_path }} version=v1.1.1"
|
||||
- name: Add an unfinished file, to allow cleanup on successful finalize
|
||||
file: path={{ deploy.new_release_path }}/{{ deploy.unfinished_filename }} state=touch
|
||||
- name: Perform some build steps, like running your dependency manager for example
|
||||
composer: command=install working_dir={{ deploy.new_release_path }}
|
||||
- name: Finalize the deploy, removing the unfinished file and switching the symlink
|
||||
deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize
|
||||
|
||||
# Gather information only
|
||||
- deploy_helper: path=/path/to/root state=query
|
||||
# Remember to set the 'release=' when you actually call state=present later
|
||||
- deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=present
|
||||
# Retrieving facts before running a deploy
|
||||
- name: Run query to gather facts without changing anything
|
||||
deploy_helper: path=/path/to/root state=query
|
||||
# Remember to set the 'release' parameter when you actually call state=present
|
||||
- name: Initialize the deploy root
|
||||
deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=present
|
||||
|
||||
# all paths can be absolute or relative (to 'path')
|
||||
- deploy_helper: path=/path/to/root
|
||||
# all paths can be absolute or relative (to the 'path' parameter)
|
||||
- deploy_helper: path=/path/to/root
|
||||
releases_path=/var/www/project/releases
|
||||
shared_path=/var/www/shared
|
||||
current_path=/var/www/active
|
||||
|
||||
# Using your own naming strategy:
|
||||
- deploy_helper: path=/path/to/root release=v1.1.1 state=present
|
||||
- deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize
|
||||
# Using your own naming strategy:
|
||||
- deploy_helper: path=/path/to/root release=v1.1.1 state=present
|
||||
- deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize
|
||||
|
||||
# Postponing the cleanup of older builds:
|
||||
- deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize clean=False
|
||||
...anything you do before actually deleting older releases...
|
||||
- deploy_helper: path=/path/to/root state=clean
|
||||
# Using a different unfinished_filename:
|
||||
- deploy_helper: path=/path/to/root
|
||||
unfinished_filename=README.md
|
||||
release={{ deploy_helper.new_release }}
|
||||
state=finalize
|
||||
|
||||
# Keeping more old releases:
|
||||
- deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize keep_releases=10
|
||||
# Or:
|
||||
- deploy_helper: path=/path/to/root state=clean keep_releases=10
|
||||
# Postponing the cleanup of older builds:
|
||||
- deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize clean=False
|
||||
- deploy_helper: path=/path/to/root state=clean
|
||||
|
||||
# Using a different unfinished_filename:
|
||||
- deploy_helper: path=/path/to/root unfinished_filename=README.md release={{ deploy_helper.new_release }} state=finalize
|
||||
# Keeping more old releases:
|
||||
- deploy_helper: path=/path/to/root release={{ deploy_helper.new_release }} state=finalize keep_releases=10
|
||||
# Or:
|
||||
- deploy_helper: path=/path/to/root state=clean keep_releases=10
|
||||
|
||||
'''
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue