About

Welcome to Ansible Galaxy

Ansible Galaxy is Ansible’s official community hub for sharing Ansible roles. A role is the Ansible way of bundling automation content and making it reusable.

If you're not familiar with the Ansible role concept, think of include files used in a programming language. An include file allows the programmer to organize code into reusable modules. Code can be organized into smaller files and grouped by subject matter or function. These discrete pieces of code can then be included as needed into larger programs like building blocks.

A role is similar. Instead of creating giant playbooks with hundreds of tasks we can use roles to organize tasks, breaking them apart into smaller more discrete units of work. But a role is more than just an include file. A role is all the tasks, variables and handlers needed to complete the unit of work. This allows a role to be completely self contained or encapsulated and completely reusable.

Using roles also allows us to think about node configuration in terms of modeling. For example, given a set of nodes that should be web servers we can simply apply a web server role to them. We don't have to think about or write all the tasks needed to configure web servers. All the details are already encapsulated in a web server role - a role you downloaded from Galaxy.

Download Roles

You can find the most popular roles and recently added roles on the Explore page, or use Browse Roles to search all roles available on Galaxy.

Once you find a role you're interested in, you can download it using the ansible-galaxy command that comes bundled with Ansible.

For example:

$ ansible-galaxy install username.rolename

Be aware that Ansible downloads roles to ANSIBLE_ROLES_PATH, which defaults to /etc/ansible/roles. You can override this by setting the environment variable in your session, defining roles_path in an ansible.cfg file, or by using the --roles-path option.

Here's an example of using --roles-path to install the role into the current directory:

$ ansible-galaxy install --roles-path . username.rolename

Download Multiple Roles

A list of roles can be specified in a file. Provide roles one per line in the format username.rolename[,version].

For example:

# roles.txt
user1.role1,v1.0.0
user2.role2,v0.5
user2.role3

Install the roles:

$ ansible-galaxy install -r roles.txt

Advanced Downloading

Starting in Ansible 1.8 you can download roles from sources other than Galaxy, and control the install path and installed name. To use these features you will need to create a Yaml file with a .yml extension

For example:

# install_roles.yml

# from galaxy
- src: yatesr.timezone

# from github
- src: https://github.com/bennojoy/nginx

# from github, overriding the name and specifying a specific tag
- src: https://github.com/bennojoy/nginx
  version: master
  name: nginx_role

# from a webserver, where the role is packaged in a tar.gz
- src: https://some.webserver.example.com/files/master.tar.gz
  name: http-role

# from bitbucket, if bitbucket happens to be operational right now :)
- src: git+http://bitbucket.org/willthames/git-ansible-galaxy
  version: v1.4

# from bitbucket, alternative syntax and caveats
- src: http://bitbucket.org/willthames/hg-ansible-galaxy
  scm: hg

Install the roles:

$ ansible-galaxy install -r install_roles.yml

Star, Watch and Count

There are multiple ways to gauge the goodness and popularity of a role, and you can use them all to let the community know what you think.

Found a role you really like? Click the GitHub Star button. Your click increases the role's stargazer count, which appears on Galaxy and on GitHub.

In addition to starring a role, you can also watch a role. Click the Watch button to become a watcher and receive updates from GitHub whenever there is an update to the role. Your click increases the watchers count on Galaxy and on GitHub.

We're also tracking downloads. Each time a role is downloaded and installed with the ansible-galaxy command line tool the download count on Galaxy rises. The count is limited to one per IP address. It's not a perfect measurement, but it gives you a feel for how popular a role is.

Create and Share

Roles can be used for automating a wide variety tasks, anything from the steps in your CI/CD workflow to packaging and distributing a product your company makes. To demonstrate the process of creating and sharing a role, as well as highlight some best practices to follow when creating roles, let's go through the steps to create a simple role called acme that will install the Acme web server.

First, create a new repository on GitHub called ansible-role-acme. Once created, clone the repository locally:

$ git clone https://username@github.com/username/ansible-role-acme.git acme

Next, use ansible-galaxy to create the role scaffolding:

$ ansible-galaxy init acme --force

This creates the directory structure needed for organizing your code:

acme/
    .travis.yml
    README.md
    defaults/
    files/
    handlers/
    meta/
    tasks/
    templates/
    tests/
    vars/
 

For more about developing a role and the details behind each of the above components see the Roles chapter at the Ansible Docs site.

Good Practices

When developing a role there are a few practices you should always follow to help potential users discover your role and make it easy for them to get started:

  • Provide clear documentation in the README.md.
  • Give accurate information in meta/main.yml.
  • Include dependencies in meta/main.yml.
  • Prefix variable names with the role name.
  • Integrate your roles with Travis CI. See how.

Sticking to these practices will help you create great roles. The community will love you, and you'll be a hero!

README.md

The init command provides a template README.md file. Tailor it to fit by providing a summary of the tasks the role performs, possible use cases, parameters and defaults, and any information users will need in order to successfully run the role

The file is composed in GitHub markdown. Make modifications using markdown to ensure the document looks good on Galaxy and on GitHub.

For example:

# README.md
# Ansible Role: Acme 2.x

An Ansible role that installs Acme 2.x on Centos 7.x

## Requirements

If you are using SSL/TLS, you will need to provide your own certificate and key files. You can generate a self-signed certificate with a command like `openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout example.key -out example.crt`.

## Role Variables

Available variables are listed below, along with default values:

    acme_listen_port: 80
    acme_listen_port_ssl: 443

## Dependencies

- username.iptables - configure the firewall and block all ports except those needed for the web server and ssh access.
- username.common - perform common server configuration

## Example Playbook

    - hosts: webservers
      roles:
        - { role: username.acme }

## License

MIT

Meta Data - meta/main.yml

In meta/main.yml is where you provide a description, a list of supported platforms, a minimum required Ansible version, a list of search tags, and any dependencies. All this information will appear on Galaxy. If it's not accurate, users may not be able to find your role.

Using ansible-galaxy init provides a template file for you to modify. It's written in YAML, so be sure to follow the YAML standard as you make changes.

An example for the acme role might look like the following:

---
galaxy_info:
  author: John Doe
  description: Quick and easy acme web installer.
  company: Acme
  license: MIT
  min_ansible_version: 1.9
  platforms:
  - name: EL
    versions:
    - all
  galaxy_tags:
    - acme
    - installer
    - web
dependencies:
  - { role: username.common, some_parameter: 3 }
  - { role: username.iptables, open_port: 80 }

Tags

Provide any tag values you feel will help users find your role. The number of tags imported by Galaxy is limited to 20, and values containing non-alphanumeric characters will be ignored.

Values containing a : will be split into multiple tags. For example, cloud:ec2 will become two tags: cloud and ec2.

The idea behind tags of course is to help users find your role, so to that end include broad terms such as database or networking as well as more specific keywords like: MySql, Cisco, ASR, TFTP, etc.

Dependencies

Add any roles that your role depends on. Ansible will download and execute dependencies before running your role. Specify role names by providing the Galaxy author's username and the name of the role in the format username.rolename.

For example:

dependencies:
  - { role: stouts.elasticsearch }

Parameters can also be passed to the role:

dependencies:
  - { role: stouts.elasticsearch, elasticsearch_home: "{{ install_path_variable }}", elasticsearch_http_port: 8900 }

For more on adding dependencies, see Role Dependencies on the Ansible docs site..

Variable Names

Variables are defined in defaults/main.yml and vars/main.yml Always prefix variable names with the role name. This prevents variable name collision between roles. For example, use acme_foo rather than just foo

Test It

The actual work to be performed gets added as playbook tasks to tasks/main.yml. Once you've added some tasks, create a playbook to test the role and insure it works. Here's a simple playbook to execute your new role:

# test.yml
# test playbook
- hosts: example
  roles:
  - { role: acme }
$ ansible-playbook test.yml

Testing your role is a good practice, and to make it easier, you can automate with Travis CI. See the Automated Testing with Travis CI section for a guide on how to connect your role to Travis.

Upload to Galaxy

Once you finish development, push your changes to GitHub by running the following from within the project directory:

$ git commit -a
$ git push

Next, log into Galaxy and click on My Roles, and you will see a list of your GitHub repositories. If you don't see the nrew repository, click the refresh button:

Uploading a role is as simple as flipping a switch. Just toggle the switch to the left of the repository name so that you see a check mark, and the import process will start.

To see the status and detailed output, click the button to the right of the name.

That's all there is to it. Pretty simple. As you iterate on your role, you can trigger a new import by going to either My Roles or My Imports and clicking

Versions

If you applied any tags to your repository, Galaxy will automatically display a “version” for each tag. This means users can choose the version (tag) to download.

The default behavior, if there are no tags, is to make the “HEAD” version available. This means users downloading the role will always get the latest from the github repository.

To import new tags, trigger a new import by visiting either My Roles or My Imports and clicking

Automated Testing

Testing your roles is a great practice. Automated testing is even better, and we've made it easy for you to add Travis CI to your roles.

Enable the repo on your Travis profile page:

Add a .travis.yml file to your repo that includes a notifications section with webhooks pointed to the galaxy server as pictured below:

notifications:
    webhooks: https://galaxy.ansible.com/api/v1/notifications/

NOTE: For a full .travis.yml example run ansible-galaxy init. Starting in Ansible 2.0 the generated scaffolding includes a working .travis.yml file and related tests folder.

Push the changes to your GitHub repo. This will kick-off a Travis build. When the build completes, Travis will notify Galaxy, and your role will be automatically imported into Galaxy with a Travis badge:

Specify a Branch

Notifications from Travis will be accepted for the GitHub repo's default branch (usually master). If you want to set a specific branch that notifications will be accepted from, define github_branch in meta/main.yml:
galaxy_info:
    galaxy_info:
    author: Me
    description: Testing role imports.
    ...

    github_branch: release
    
    ...

NEW: Role Types

The release of Ansible Container 0.2.0 introduces two new role types to Galaxy. Ansible Container brings the power and flexibility of Ansible to managing and orchestrating containers, and the new role types make it easy to build and share container applications.

Container Enabled

Want to spend less time deciphering READMEs and Dockerfiles, and more time building your app? Now you can. Just let a Container Enabled role auto-install its service into your Ansible Container project, build, and go.

The role is a building block for an Ansible Container project. Projects typically define multiple services that work together to form an application. Rather than building each service from scratch or attempting to figure out how to use and connect pre-built images, let a container enabled role install itself into your project.

When a role is installed using ansible-container install it automatically updates the project's container.yml with the new service, updates main.yml with a call to the role, and adds the role to requirements.yml. All the work is done for you. All you have to do is adjust any default settings surfaced in your project's container.yml and main.yml files. No more reading, and no more guess work. Now you can get back to building your app.

Container App

Want to really jump-start the process of building a containerized app? Now you can. With a Container App role you start from a complete working app. Just download and use it as is or use it as a starting point to build your next app.

The role contains a complete Ansible Container application, everything from the ansible directory to the source code is included. Download it by running the ansible-container init command.

For example:

    $ mkdir example
    $ cd example
    $ ansible-container init <role name>
    $ ansible-container build
    $ ansible-container run
    

That's it! With a Container App it's now easier than ever to distribute applications, jump-start projects, and get work done!

For more information about Ansible Container, visit the project repo, or check out the doc site.

Questions?

If you have unanswered Galaxy questions, feel free to ask on the Ansible mailing list. Found a bug or have a suggestion? Let us know at Galaxy Issues.

NOTE: Contents, usage and bugs related to specific roles will not be supported on the mailing list. Contact the role author via GitHub. The role details provided in Galaxy include a link to the GitHub repository, and when available, the issue tracker.