Merge pull request #13501 from chouseknecht/galaxy-2.0-update

Galaxy 2.0 update
pull/13589/head
James Cammarata 9 years ago
commit 76b4b9ed2c

@ -12,7 +12,7 @@ ansible-galaxy - manage roles using galaxy.ansible.com
SYNOPSIS SYNOPSIS
-------- --------
ansible-galaxy [init|info|install|list|remove] [--help] [options] ... ansible-galaxy [delete|import|info|init|install|list|login|remove|search|setup] [--help] [options] ...
DESCRIPTION DESCRIPTION
@ -20,7 +20,7 @@ DESCRIPTION
*Ansible Galaxy* is a shared repository for Ansible roles. *Ansible Galaxy* is a shared repository for Ansible roles.
The ansible-galaxy command can be used to manage these roles, The ansible-galaxy command can be used to manage these roles,
or by creating a skeleton framework for roles you'd like to upload to Galaxy. or for creating a skeleton framework for roles you'd like to upload to Galaxy.
COMMON OPTIONS COMMON OPTIONS
-------------- --------------
@ -29,7 +29,6 @@ COMMON OPTIONS
Show a help message related to the given sub-command. Show a help message related to the given sub-command.
INSTALL INSTALL
------- -------
@ -145,6 +144,204 @@ The path to the directory containing your roles. The default is the *roles_path*
configured in your *ansible.cfg* file (/etc/ansible/roles if not configured) configured in your *ansible.cfg* file (/etc/ansible/roles if not configured)
SEARCH
------
The *search* sub-command returns a filtered list of roles found on the remote
server.
USAGE
~~~~~
$ ansible-galaxy search [options] [searchterm1 searchterm2]
OPTIONS
~~~~~~~
*--galaxy-tags*::
Provide a comma separated list of Galaxy Tags on which to filter.
*--platforms*::
Provide a comma separated list of Platforms on which to filter.
*--author*::
Specify the username of a Galaxy contributor on which to filter.
*-c*, *--ignore-certs*::
Ignore TLS certificate errors.
*-s*, *--server*::
Override the default server https://galaxy.ansible.com.
INFO
----
The *info* sub-command shows detailed information for a specific role.
Details returned about the role included information from the local copy
as well as information from galaxy.ansible.com.
USAGE
~~~~~
$ ansible-galaxy info [options] role_name[, version]
OPTIONS
~~~~~~~
*-p* 'ROLES_PATH', *--roles-path=*'ROLES_PATH'::
The path to the directory containing your roles. The default is the *roles_path*
configured in your *ansible.cfg* file (/etc/ansible/roles if not configured)
*-c*, *--ignore-certs*::
Ignore TLS certificate errors.
*-s*, *--server*::
Override the default server https://galaxy.ansible.com.
LOGIN
-----
The *login* sub-command is used to authenticate with galaxy.ansible.com.
Authentication is required to use the import, delete and setup commands.
It will authenticate the user, retrieve a token from Galaxy, and store it
in the user's home directory.
USAGE
~~~~~
$ ansible-galaxy login [options]
The *login* sub-command prompts for a *GitHub* username and password. It does
NOT send your password to Galaxy. It actually authenticates with GitHub and
creates a personal access token. It then sends the personal access token to
Galaxy, which in turn verifies that you are you and returns a Galaxy access
token. After authentication completes the *GitHub* personal access token is
destroyed.
If you do not wish to use your GitHub password, or if you have two-factor
authentication enabled with GitHub, use the *--github-token* option to pass a
personal access token that you create. Log into GitHub, go to Settings and
click on Personal Access Token to create a token.
OPTIONS
~~~~~~~
*-c*, *--ignore-certs*::
Ignore TLS certificate errors.
*-s*, *--server*::
Override the default server https://galaxy.ansible.com.
*--github-token*::
Authenticate using a *GitHub* personal access token rather than a password.
IMPORT
------
Import a role from *GitHub* to galaxy.ansible.com. Requires the user first
authenticate with galaxy.ansible.com using the *login* subcommand.
USAGE
~~~~~
$ ansible-galaxy import [options] github_user github_repo
OPTIONS
~~~~~~~
*-c*, *--ignore-certs*::
Ignore TLS certificate errors.
*-s*, *--server*::
Override the default server https://galaxy.ansible.com.
*--branch*::
Provide a specific branch to import. When a branch is not specified the
branch found in meta/main.yml is used. If no branch is specified in
meta/main.yml, the repo's default branch (usually master) is used.
DELETE
------
The *delete* sub-command will delete a role from galaxy.ansible.com. Requires
the user first authenticate with galaxy.ansible.com using the *login* subcommand.
USAGE
~~~~~
$ ansible-galaxy delete [options] github_user github_repo
OPTIONS
~~~~~~~
*-c*, *--ignore-certs*::
Ignore TLS certificate errors.
*-s*, *--server*::
Override the default server https://galaxy.ansible.com.
SETUP
-----
The *setup* sub-command creates an integration point for *Travis CI*, enabling
galaxy.ansible.com to receive notifications from *Travis* on build completion.
Requires the user first authenticate with galaxy.ansible.com using the *login*
subcommand.
USAGE
~~~~~
$ ansible-galaxy setup [options] source github_user github_repo secret
* Use *travis* as the source value. In the future additional source values may
be added.
* Provide your *Travis* user token as the secret. The token is not stored by
galaxy.ansible.com. A hash is created using github_user, github_repo
and your token. The hash value is what actually gets stored.
OPTIONS
~~~~~~~
*-c*, *--ignore-certs*::
Ignore TLS certificate errors.
*-s*, *--server*::
Override the default server https://galaxy.ansible.com.
--list::
Show your configured integrations. Provids the ID of each integration
which can be used with the remove option.
--remove::
Remove a specific integration. Provide the ID of the integration to
be removed.
AUTHOR AUTHOR
------ ------

@ -1,7 +1,7 @@
Ansible Galaxy Ansible Galaxy
++++++++++++++ ++++++++++++++
"Ansible Galaxy" can either refer to a website for sharing and downloading Ansible roles, or a command line tool that helps work with roles. "Ansible Galaxy" can either refer to a website for sharing and downloading Ansible roles, or a command line tool for managing and creating roles.
.. contents:: Topics .. contents:: Topics
@ -10,26 +10,38 @@ The Website
The website `Ansible Galaxy <https://galaxy.ansible.com>`_, is a free site for finding, downloading, and sharing community developed Ansible roles. Downloading roles from Galaxy is a great way to jumpstart your automation projects. The website `Ansible Galaxy <https://galaxy.ansible.com>`_, is a free site for finding, downloading, and sharing community developed Ansible roles. Downloading roles from Galaxy is a great way to jumpstart your automation projects.
You can sign up with social auth and use the download client 'ansible-galaxy' which is included in Ansible 1.4.2 and later. Access the Galaxy web site using GitHub OAuth, and to install roles use the 'ansible-galaxy' command line tool included in Ansible 1.4.2 and later.
Read the "About" page on the Galaxy site for more information. Read the "About" page on the Galaxy site for more information.
The ansible-galaxy command line tool The ansible-galaxy command line tool
```````````````````````````````````` ````````````````````````````````````
The command line ansible-galaxy has many different subcommands. The ansible-galaxy command has many different sub-commands for managing roles both locally and at `galaxy.ansible.com <https://galaxy.ansible.com>`_.
.. note::
The search, login, import, delete, and setup commands in the Ansible 2.0 version of ansible-galaxy require access to the
2.0 Beta release of the Galaxy web site available at `https://galaxy-qa.ansible.com <https://galaxy-qa.ansible.com>`_.
Use the ``--server`` option to access the beta site. For example::
$ ansible-galaxy search --server https://galaxy-qa.ansible.com mysql --author geerlingguy
Additionally, you can define a server in ansible.cfg::
[galaxy]
server=https://galaxy-qa.ansible.com
Installing Roles Installing Roles
---------------- ----------------
The most obvious is downloading roles from the Ansible Galaxy website:: The most obvious use of the ansible-galaxy command is downloading roles from `the Ansible Galaxy website <https://galaxy.ansible.com>`_::
$ ansible-galaxy install username.rolename $ ansible-galaxy install username.rolename
.. _galaxy_cli_roles_path:
roles_path roles_path
=============== ==========
You can specify a particular directory where you want the downloaded roles to be placed:: You can specify a particular directory where you want the downloaded roles to be placed::
@ -164,7 +176,7 @@ The search command will return a list of the first 1000 results matching your se
.. note:: .. note::
The format of results pictured here is new in Ansible 2.0. The format of results pictured here is new in Ansible 2.0.
Get More Information About a Role Get More Information About a Role
--------------------------------- ---------------------------------
@ -208,10 +220,6 @@ This returns everything found in Galaxy for the role:
version: version:
watchers_count: 1 watchers_count: 1
.. note::
The format of results pictured here is new in Ansible 2.0.
List Installed Roles List Installed Roles
-------------------- --------------------
@ -257,7 +265,13 @@ To use the import, delete and setup commands authentication with Galaxy is requi
As depicted above, the login command prompts for a GitHub username and password. It does NOT send your password to Galaxy. It actually authenticates with GitHub and creates a personal access token. It then sends the personal access token to Galaxy, which in turn verifies that you are you and returns a Galaxy access token. After authentication completes the GitHub personal access token is destroyed. As depicted above, the login command prompts for a GitHub username and password. It does NOT send your password to Galaxy. It actually authenticates with GitHub and creates a personal access token. It then sends the personal access token to Galaxy, which in turn verifies that you are you and returns a Galaxy access token. After authentication completes the GitHub personal access token is destroyed.
If you do not wish to use your GitHub password, or if you have two-factor authentication enabled with GitHub, use the --github-token option to pass a personal access token that you create. Log into GitHub, go to Settings and click on Personal Access Token to create a token. If you do not wish to use your GitHub password, or if you have two-factor authentication enabled with GitHub, use the --github-token option to pass a personal access token that you create. Log into GitHub, go to Settings and click on Personal Access Token to create a token.
.. note::
The login command in Ansible 2.0 requires using the Galaxy 2.0 Beta site. Use the ``--server`` option to access
`https://galaxy-qa.ansible.com <https://galaxy-qa.ansible.com>`_. You can also add a *server* definition in the [galaxy]
section of your ansible.cfg file.
Import a Role Import a Role
------------- -------------
@ -293,7 +307,9 @@ If the --no-wait option is present, the command will not wait for results. Resul
.. note:: .. note::
The import command is only available in Ansible 2.0. The import command in Ansible 2.0 requires using the Galaxy 2.0 Beta site. Use the ``--server`` option to access
`https://galaxy-qa.ansible.com <https://galaxy-qa.ansible.com>`_. You can also add a *server* definition in the [galaxy]
section of your ansible.cfg file.
Delete a Role Delete a Role
------------- -------------
@ -302,13 +318,15 @@ Remove a role from the Galaxy web site using the delete command. You can delete
:: ::
ansible-galaxy delete github_user github_repo $ ansible-galaxy delete github_user github_repo
This only removes the role from Galaxy. It does not impact the actual GitHub repo. This only removes the role from Galaxy. It does not impact the actual GitHub repo.
.. note:: .. note::
The delete command is only available in Ansible 2.0. The delete command in Ansible 2.0 requires using the Galaxy 2.0 Beta site. Use the ``--server`` option to access
`https://galaxy-qa.ansible.com <https://galaxy-qa.ansible.com>`_. You can also add a *server* definition in the [galaxy]
section of your ansible.cfg file.
Setup Travis Integerations Setup Travis Integerations
-------------------------- --------------------------
@ -319,7 +337,7 @@ Using the setup command you can enable notifications from `travis <http://travis
$ ansible-galaxy setup travis github_user github_repo xxxtravistokenxxx $ ansible-galaxy setup travis github_user github_repo xxxtravistokenxxx
Added integration for travis chouseknecht/ansible-role-sendmail Added integration for travis github_user/github_repo
The setup command requires your Travis token. The Travis token is not stored in Galaxy. It is used along with the GitHub username and repo to create a hash as described in `the Travis documentation <https://docs.travis-ci.com/user/notifications/>`_. The calculated hash is stored in Galaxy and used to verify notifications received from Travis. The setup command requires your Travis token. The Travis token is not stored in Galaxy. It is used along with the GitHub username and repo to create a hash as described in `the Travis documentation <https://docs.travis-ci.com/user/notifications/>`_. The calculated hash is stored in Galaxy and used to verify notifications received from Travis.
@ -334,11 +352,13 @@ When you create your .travis.yml file add the following to cause Travis to notif
.. note:: .. note::
The setup command is only available in Ansible 2.0. The setup command in Ansible 2.0 requires using the Galaxy 2.0 Beta site. Use the ``--server`` option to access
`https://galaxy-qa.ansible.com <https://galaxy-qa.ansible.com>`_. You can also add a *server* definition in the [galaxy]
section of your ansible.cfg file.
List Travis Integrtions List Travis Integrations
======================= ========================
Use the --list option to display your Travis integrations: Use the --list option to display your Travis integrations:
@ -356,7 +376,7 @@ Use the --list option to display your Travis integrations:
Remove Travis Integrations Remove Travis Integrations
========================== ==========================
Use the --remove option to disable a Travis integration: Use the --remove option to disable and remove a Travis integration:
:: ::

@ -897,3 +897,19 @@ The normal behaviour is for operations to copy the existing context or use the u
The default list is: nfs,vboxsf,fuse,ramfs:: The default list is: nfs,vboxsf,fuse,ramfs::
special_context_filesystems = nfs,vboxsf,fuse,ramfs,myspecialfs special_context_filesystems = nfs,vboxsf,fuse,ramfs,myspecialfs
Galaxy Settings
---------------
The following options can be set in the [galaxy] section of ansible.cfg:
server
======
Override the default Galaxy server value of https://galaxy.ansible.com. Useful if you have a hosted version of the Galaxy web app or want to point to the testing site https://galaxy-qa.ansible.com. It does not work against private, hosted repos, which Galaxy can use for fetching and installing roles.
ignore_certs
============
If set to *yes*, ansible-galaxy will not validate TLS certificates. Handy for testing against a server with a self-signed certificate
.

@ -48,50 +48,14 @@ except ImportError:
class GalaxyCLI(CLI): class GalaxyCLI(CLI):
available_commands = {
"delete": "remove a role from Galaxy",
"import": "add a role contained in a GitHub repo to Galaxy",
"info": "display details about a particular role",
"init": "create a role directory structure in your roles path",
"install": "download a role into your roles path",
"list": "enumerate roles found in your roles path",
"login": "authenticate with Galaxy API and store the token",
"remove": "delete a role from your roles path",
"search": "query the Galaxy API",
"setup": "add a TravisCI integration to Galaxy",
}
SKIP_INFO_KEYS = ("name", "description", "readme_html", "related", "summary_fields", "average_aw_composite", "average_aw_score", "url" ) SKIP_INFO_KEYS = ("name", "description", "readme_html", "related", "summary_fields", "average_aw_composite", "average_aw_score", "url" )
VALID_ACTIONS = ("delete", "import", "info", "init", "install", "list", "login", "remove", "search", "setup")
def __init__(self, args): def __init__(self, args):
self.VALID_ACTIONS = self.available_commands.keys()
self.VALID_ACTIONS.sort()
self.api = None self.api = None
self.galaxy = None self.galaxy = None
super(GalaxyCLI, self).__init__(args) super(GalaxyCLI, self).__init__(args)
def set_action(self):
"""
Get the action the user wants to execute from the sys argv list.
"""
for i in range(0,len(self.args)):
arg = self.args[i]
if arg in self.VALID_ACTIONS:
self.action = arg
del self.args[i]
break
if not self.action:
self.show_available_actions()
def show_available_actions(self):
# list available commands
display.display(u'\n' + "usage: ansible-galaxy COMMAND [--help] [options] ...")
display.display(u'\n' + "availabe commands:" + u'\n\n')
for key in self.VALID_ACTIONS:
display.display(u'\t' + "%-12s %s" % (key, self.available_commands[key]))
display.display(' ')
def parse(self): def parse(self):
''' create an options parser for bin/ansible ''' ''' create an options parser for bin/ansible '''
@ -107,11 +71,11 @@ class GalaxyCLI(CLI):
self.parser.set_usage("usage: %prog delete [options] github_user github_repo") self.parser.set_usage("usage: %prog delete [options] github_user github_repo")
elif self.action == "import": elif self.action == "import":
self.parser.set_usage("usage: %prog import [options] github_user github_repo") self.parser.set_usage("usage: %prog import [options] github_user github_repo")
self.parser.add_option('-n', '--no-wait', dest='wait', action='store_false', default=True, self.parser.add_option('--no-wait', dest='wait', action='store_false', default=True,
help='Don\'t wait for import results.') help='Don\'t wait for import results.')
self.parser.add_option('-b', '--branch', dest='reference', self.parser.add_option('--branch', dest='reference',
help='The name of a branch to import. Defaults to the repository\'s default branch (usually master)') help='The name of a branch to import. Defaults to the repository\'s default branch (usually master)')
self.parser.add_option('-t', '--status', dest='check_status', action='store_true', default=False, self.parser.add_option('--status', dest='check_status', action='store_true', default=False,
help='Check the status of the most recent import request for given github_user/github_repo.') help='Check the status of the most recent import request for given github_user/github_repo.')
elif self.action == "info": elif self.action == "info":
self.parser.set_usage("usage: %prog info [options] role_name[,version]") self.parser.set_usage("usage: %prog info [options] role_name[,version]")
@ -136,7 +100,7 @@ class GalaxyCLI(CLI):
self.parser.set_usage("usage: %prog list [role_name]") self.parser.set_usage("usage: %prog list [role_name]")
elif self.action == "login": elif self.action == "login":
self.parser.set_usage("usage: %prog login [options]") self.parser.set_usage("usage: %prog login [options]")
self.parser.add_option('-g','--github-token', dest='token', default=None, self.parser.add_option('--github-token', dest='token', default=None,
help='Identify with github token rather than username and password.') help='Identify with github token rather than username and password.')
elif self.action == "search": elif self.action == "search":
self.parser.add_option('--platforms', dest='platforms', self.parser.add_option('--platforms', dest='platforms',
@ -147,15 +111,14 @@ class GalaxyCLI(CLI):
help='GitHub username') help='GitHub username')
self.parser.set_usage("usage: %prog search [searchterm1 searchterm2] [--galaxy-tags galaxy_tag1,galaxy_tag2] [--platforms platform1,platform2] [--author username]") self.parser.set_usage("usage: %prog search [searchterm1 searchterm2] [--galaxy-tags galaxy_tag1,galaxy_tag2] [--platforms platform1,platform2] [--author username]")
elif self.action == "setup": elif self.action == "setup":
self.parser.set_usage("usage: %prog setup [options] source github_user github_repo secret" + self.parser.set_usage("usage: %prog setup [options] source github_user github_repo secret")
u'\n\n' + "Create an integration with travis.") self.parser.add_option('--remove', dest='remove_id', default=None,
self.parser.add_option('-r', '--remove', dest='remove_id', default=None,
help='Remove the integration matching the provided ID value. Use --list to see ID values.') help='Remove the integration matching the provided ID value. Use --list to see ID values.')
self.parser.add_option('-l', '--list', dest="setup_list", action='store_true', default=False, self.parser.add_option('--list', dest="setup_list", action='store_true', default=False,
help='List all of your integrations.') help='List all of your integrations.')
# options that apply to more than one action # options that apply to more than one action
if not self.action in ("config","import","init","login","setup"): if not self.action in ("delete","import","init","login","setup"):
self.parser.add_option('-p', '--roles-path', dest='roles_path', default=C.DEFAULT_ROLES_PATH, self.parser.add_option('-p', '--roles-path', dest='roles_path', default=C.DEFAULT_ROLES_PATH,
help='The path to the directory containing your roles. ' help='The path to the directory containing your roles. '
'The default is the roles_path configured in your ' 'The default is the roles_path configured in your '
@ -164,26 +127,21 @@ class GalaxyCLI(CLI):
if self.action in ("import","info","init","install","login","search","setup","delete"): if self.action in ("import","info","init","install","login","search","setup","delete"):
self.parser.add_option('-s', '--server', dest='api_server', default=C.GALAXY_SERVER, self.parser.add_option('-s', '--server', dest='api_server', default=C.GALAXY_SERVER,
help='The API server destination') help='The API server destination')
self.parser.add_option('-c', '--ignore-certs', action='store_false', dest='validate_certs', default=True, self.parser.add_option('-c', '--ignore-certs', action='store_true', dest='ignore_certs', default=False,
help='Ignore SSL certificate validation errors.') help='Ignore SSL certificate validation errors.')
if self.action in ("init","install"): if self.action in ("init","install"):
self.parser.add_option('-f', '--force', dest='force', action='store_true', default=False, self.parser.add_option('-f', '--force', dest='force', action='store_true', default=False,
help='Force overwriting an existing role') help='Force overwriting an existing role')
if self.action: self.options, self.args =self.parser.parse_args()
# get options, args and galaxy object display.verbosity = self.options.verbosity
self.options, self.args =self.parser.parse_args() self.galaxy = Galaxy(self.options)
display.verbosity = self.options.verbosity
self.galaxy = Galaxy(self.options)
return True return True
def run(self): def run(self):
if not self.action:
return True
super(GalaxyCLI, self).run() super(GalaxyCLI, self).run()
# if not offline, get connect to galaxy api # if not offline, get connect to galaxy api
@ -547,7 +505,7 @@ class GalaxyCLI(CLI):
terms = [] terms = []
for i in range(len(self.args)): for i in range(len(self.args)):
terms.append(self.args.pop()) terms.append(self.args.pop())
search = '+'.join(terms) search = '+'.join(terms[::-1])
if not search and not self.options.platforms and not self.options.tags and not self.options.author: if not search and not self.options.platforms and not self.options.tags and not self.options.author:
raise AnsibleError("Invalid query. At least one search term, platform, galaxy tag or author must be provided.") raise AnsibleError("Invalid query. At least one search term, platform, galaxy tag or author must be provided.")
@ -562,9 +520,9 @@ class GalaxyCLI(CLI):
data = '' data = ''
if response['count'] > page_size: if response['count'] > page_size:
data += ("Found %d roles matching your search. Showing first %s.\n" % (response['count'], page_size)) data += ("\nFound %d roles matching your search. Showing first %s.\n" % (response['count'], page_size))
else: else:
data += ("Found %d roles matching your search:\n" % response['count']) data += ("\nFound %d roles matching your search:\n" % response['count'])
max_len = [] max_len = []
for role in response['results']: for role in response['results']:

@ -48,16 +48,15 @@ class GalaxyAPI(object):
SUPPORTED_VERSIONS = ['v1'] SUPPORTED_VERSIONS = ['v1']
def __init__(self, galaxy): def __init__(self, galaxy):
self.galaxy = galaxy self.galaxy = galaxy
self.token = GalaxyToken() self.token = GalaxyToken()
self._api_server = C.GALAXY_SERVER self._api_server = C.GALAXY_SERVER
self._validate_certs = C.GALAXY_IGNORE_CERTS self._validate_certs = not C.GALAXY_IGNORE_CERTS
# set validate_certs # set validate_certs
if galaxy.options.validate_certs == False: if galaxy.options.ignore_certs:
self._validate_certs = False self._validate_certs = False
display.vvv('Check for valid certs: %s' % self._validate_certs) display.vvv('Validate TLS certificates: %s' % self._validate_certs)
# set the API server # set the API server
if galaxy.options.api_server != C.GALAXY_SERVER: if galaxy.options.api_server != C.GALAXY_SERVER:
@ -65,14 +64,13 @@ class GalaxyAPI(object):
display.vvv("Connecting to galaxy_server: %s" % self._api_server) display.vvv("Connecting to galaxy_server: %s" % self._api_server)
server_version = self.get_server_api_version() server_version = self.get_server_api_version()
if not server_version in self.SUPPORTED_VERSIONS:
if server_version in self.SUPPORTED_VERSIONS:
self.baseurl = '%s/api/%s' % (self._api_server, server_version)
self.version = server_version # for future use
display.vvv("Base API: %s" % self.baseurl)
else:
raise AnsibleError("Unsupported Galaxy server API version: %s" % server_version) raise AnsibleError("Unsupported Galaxy server API version: %s" % server_version)
self.baseurl = '%s/api/%s' % (self._api_server, server_version)
self.version = server_version # for future use
display.vvv("Base API: %s" % self.baseurl)
def __auth_header(self): def __auth_header(self):
token = self.token.get() token = self.token.get()
if token is None: if token is None:

Loading…
Cancel
Save