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

Galaxy 2.0 update

docs/man/man1/ansible-galaxy.1.asciidoc.in

@@ -12,7 +12,7 @@ ansible-galaxy - manage roles using galaxy.ansible.com
 
 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
@@ -20,7 +20,7 @@ DESCRIPTION
 
 *Ansible Galaxy* is a shared repository for Ansible 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
 --------------
@@ -29,7 +29,6 @@ COMMON OPTIONS
 
 Show a help message related to the given sub-command.
 
-
 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)
 
 
+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
 ------
 

docsite/rst/galaxy.rst

@@ -1,7 +1,7 @@
 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
 
@@ -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.
 
-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.
 
 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
 ----------------
 
-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
 
-.. _galaxy_cli_roles_path:
-
 roles_path
-===============
+==========
 
 You can specify a particular directory where you want the downloaded roles to be placed::
 
@@ -208,10 +220,6 @@ This returns everything found in Galaxy for the role:
         version:
         watchers_count: 1
 
-.. note::
-
-    The format of results pictured here is new in Ansible 2.0.
-
 
 List Installed Roles
 --------------------
@@ -259,6 +267,12 @@ As depicted above, the login command prompts for a GitHub username and password.
 
 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
 -------------
 
@@ -293,7 +307,9 @@ If the --no-wait option is present, the command will not wait for results. Resul
 
 .. 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
 -------------
@@ -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.
 
 .. 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
 --------------------------
@@ -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
 
-    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.
 
@@ -334,11 +352,13 @@ When you create your .travis.yml file add the following to cause Travis to notif
 
 .. 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:
 
@@ -356,7 +376,7 @@ Use the --list option to display your 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:
 
 ::
 

docsite/rst/intro_configuration.rst

@@ -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::
 
     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
+.

lib/ansible/cli/galaxy.py

@@ -48,50 +48,14 @@ except ImportError:
 
 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" )
+    VALID_ACTIONS = ("delete", "import", "info", "init", "install", "list", "login", "remove", "search", "setup")
     
     def __init__(self, args):
-        self.VALID_ACTIONS = self.available_commands.keys()
-        self.VALID_ACTIONS.sort()
         self.api = None
         self.galaxy = None
         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):
         ''' 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")
         elif self.action == "import":
             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.')
-            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)')
-            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.')
         elif self.action == "info":
             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]")
         elif self.action == "login":
             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.')
         elif self.action == "search":
             self.parser.add_option('--platforms', dest='platforms',
@@ -147,15 +111,14 @@ class GalaxyCLI(CLI):
                 help='GitHub 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":
-            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('-r', '--remove', dest='remove_id', default=None,
+            self.parser.set_usage("usage: %prog setup [options] source github_user github_repo secret")
+            self.parser.add_option('--remove', dest='remove_id', default=None,
                 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.')
 
         # 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,
                 help='The path to the directory containing your roles. '
                      'The default is the roles_path configured in your '
@@ -164,15 +127,13 @@ class GalaxyCLI(CLI):
         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,
                 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.')
 
         if self.action in ("init","install"):
             self.parser.add_option('-f', '--force', dest='force', action='store_true', default=False,
                 help='Force overwriting an existing role')
 
-        if self.action:
-            # get options, args and galaxy object
         self.options, self.args =self.parser.parse_args()
         display.verbosity = self.options.verbosity
         self.galaxy = Galaxy(self.options)
@@ -181,9 +142,6 @@ class GalaxyCLI(CLI):
 
     def run(self):
         
-        if not self.action:
-            return True
-
         super(GalaxyCLI, self).run()
 
         # if not offline, get connect to galaxy api
@@ -547,7 +505,7 @@ class GalaxyCLI(CLI):
             terms = []
             for i in range(len(self.args)):
                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:
             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 = ''
 
         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:
-            data += ("Found %d roles matching your search:\n" % response['count'])
+            data += ("\nFound %d roles matching your search:\n" % response['count'])
 
         max_len = []
         for role in response['results']:

lib/ansible/galaxy/api.py

@@ -48,16 +48,15 @@ class GalaxyAPI(object):
     SUPPORTED_VERSIONS = ['v1']
 
     def __init__(self, galaxy):
-
         self.galaxy = galaxy
         self.token = GalaxyToken()
         self._api_server = C.GALAXY_SERVER
-        self._validate_certs = C.GALAXY_IGNORE_CERTS
+        self._validate_certs = not C.GALAXY_IGNORE_CERTS
 
         # set validate_certs
-        if galaxy.options.validate_certs == False:
+        if galaxy.options.ignore_certs:
             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
         if galaxy.options.api_server != C.GALAXY_SERVER:
@@ -65,13 +64,12 @@ class GalaxyAPI(object):
         display.vvv("Connecting to galaxy_server: %s" % self._api_server)
 
         server_version = self.get_server_api_version()
+        if not server_version in self.SUPPORTED_VERSIONS:
+            raise AnsibleError("Unsupported Galaxy server API version: %s" % server_version)
 
-        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)
 
     def __auth_header(self):
         token = self.token.get()