Ansible Galaxy

What is Ansible Galaxy

One of the big advantages of using Ansible is that there is a wealth of pre created and often very high quality roles that can be brought in as dependencies to your Ansible project. The place where you can search and find these roles is Ansible Galaxy. Most of the roles (if not all) are actually hosted in Github.

Any role that is listed on the Ansible Galaxy website can then be installed using the ansible-galaxy command which is included with your standard Ansible install.

This means that you don't have to do everything from scratch. You can also create and share your own roles on Ansible Galaxy which means you can easily add them as dependencies to your own projects and also get that nice warm feeling that comes with sharing your work with the world

In summary:

  • Ansible Galaxy is an online repository of Ansible roles that can be brought in as dependencies to your Ansible project.

  • ansible-galaxy is a command line tool for working with Ansible Galaxy. It can install dependencies to your project and also assists in creating and managing new roles.

The primary documentation is here:

http://docs.ansible.com/ansible/latest/galaxy.html

And you should also read this page:

https://galaxy.ansible.com/intro

ansible-galaxy CLI Tool

The CLI tool is what makes Ansible Galaxy so useful.

Here is the basic help from the command

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
joseph@joseph-thinkpad ansible-galaxy -h
Usage: ansible-galaxy [delete|import|info|init|install|list|login|remove|search|setup] [--help] [options] ...

Options:
  -h, --help            show this help message and exit
  -c, --ignore-certs    Ignore SSL certificate validation errors.
  -s API_SERVER, --server=API_SERVER
                        The API server destination
  -v, --verbose         verbose mode (-vvv for more, -vvvv to enable
                        connection debugging)
  --version             show program's version number and exit

 See 'ansible-galaxy <command> --help' for more information on a specific
command.

Authors of Note

Like any system of user contributed resources, some are much better than others

Here are some authors of note:

Geerlingguy

There are numerous authors on Galaxy, however one that clearly stands out as having a lot of downloads, a lot of packages and supporting a lot of distros is geerlingguy

https://galaxy.ansible.com/geerlingguy/

Has lots of roles that are relevant to our kinds of requirements. Seem well put together and very popular

Edmonds Commerce

Well of course, we're a bit biased, but our roles are the most relevant to our requirements

https://galaxy.ansible.com/edmondscommerce/

For Example, Creating an Akeneo Role

Here is a step by step guide to creating an Ansible role, based upon our Akeneo role

See our Akeneo for more information on Akeneo itself.

Init

To create a new role, we need to use the ansible-galaxy init command:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
joseph@joseph-thinkpad ansible-galaxy init --help
Usage: ansible-galaxy init [options] role_name

Options:
  --container-enabled   Initialize the skeleton role with default contents for
                        a Container Enabled role.
  -f, --force           Force overwriting an existing role
  -h, --help            show this help message and exit
  -c, --ignore-certs    Ignore SSL certificate validation errors.
  --init-path=INIT_PATH
                        The path in which the skeleton role will be created.
                        The default is the current working directory.
  --offline             Don't query the galaxy API when creating roles
  --role-skeleton=ROLE_SKELETON
                        The path to a role skeleton that the new role should
                        be based upon.
  -s API_SERVER, --server=API_SERVER
                        The API server destination
  -v, --verbose         verbose mode (-vvv for more, -vvvv to enable
                        connection debugging)
  --version             show program's version number and exit

 See 'ansible-galaxy <command> --help' for more information on a specific
command.

By default, init will create the role in the current directory. If you are in the project root and want to create it in the roles directory then use --init-path=roles Your role name will end up in the format edmondscommerce.role-name so we may as well start like that:

1
2
3
4
5
6
7
8
#cd into the ansible project root
cd ansible-project

#create roles directory if it doesn't already exist
mkdir -p roles

#init the role
ansible-galaxy init --init-path=roles edmondscommerce.akeneo

And you will see something like:

1
2
joseph@joseph-thinkpad ansible-galaxy init --init-path=roles edmondscommerce.akeneo
- edmondscommerce.akeneo was created successfully

And this has created:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
joseph@joseph-thinkpad tree roles/edmondscommerce.akeneo/
roles/edmondscommerce.akeneo/
├── defaults
│   └── main.yml
├── files
├── handlers
│   └── main.yml
├── meta
│   └── main.yml
├── README.md
├── tasks
│   └── main.yml
├── templates
├── tests
│   ├── inventory
│   └── test.yml
└── vars
    └── main.yml

As you can see, this creates a selection of files and folder. Some of these files will need to be removed, others will need to be edited.

Ones that you will definitely keep and edit are:

  • README.md - this needs to be edited to properly reflect the role
  • meta/main.yml - this one is required by Ansible Galaxy

The other folders and files are optional, however we will keep them until we are sure we don't need them.

README.md

The README file is, as you would expect, the first page of documentation for the role.

It is what will be displayed on the home page on Github and also on the README page in Ansible Galaxy.

The default file has preset headings which are good and should simply be filled out with content.

You should add a link back to Edmonds Commerce for a tiny bit of SEO/Marketing benefit

meta/main.yml

This file is required by Ansible Galaxy itself

The file is well commented and so filling it out is quite straight forwards.

Be aware that changes to the Ansible Galaxy works means that you have to add in the role_name to allow the role to have a sensible name Here is our Akeneo file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
galaxy_info:
  author: edmondscommerce
  description: A role to install all Akeneo dependencies and then the platform itself
  company: Edmonds Commerce
  license: MIT
  min_ansible_version: 2.0
  # You need to manually add this node
  role_name: akeneo

  # platforms is a list of platforms, and each platform has a name and a list of versions.
  #
  # platforms:
  # - name: Fedora
  #   versions:
  #   - all
  #   - 25
  # - name: SomePlatform
  #   versions:
  #   - all
  #   - 1.0
  #   - 7
  #   - 99.99
  platforms:
  - name: Centos
    versions:
      - 7

  galaxy_tags:
    - akeneo
    - php
    - pim
    - magento
    # List tags for your role here, one per line. A tag is a keyword that describes
    # and categorizes the role. Users find roles by searching for tags. Be sure to
    # remove the '[]' above, if you add tags to this list.
    #
    # NOTE: A tag is limited to a single word comprised of alphanumeric characters.
    #       Maximum 20 tags per role.

dependencies: []
  # List your role dependencies here, one per line. Be sure to remove the '[]' above,
  # if you add dependencies to this list.

Create Github Repo

Our next step is to create a repo on Github and then push this role into it

First, sign into Github and hit the + icon in the top right and select "create new repository"

The repository name should be in the format ansible-role-rolename, so for Akeneo it will be ansible-role-akeneo

Note

If you have not added in the role_name in the meta/main.yml file then the role will have the same name as the repo. We want to prefix it with ansible-role to make it abundantly clear what it is.

Github Create Repo

Then click to create the repo.

Add Github Remote

Now we need to connect your local repo up to the Github repo so that you can push changes

Update .gitignore

First of all, we need to make sure that the contents of your roles directory is not tracked by git.

For that purpose in your main ansible project folder, we need to add the following to your .gitignore file:

1
roles/*

For example:

1
2
cd ansible-project
echo 'roles/*' >> .gitignore

Note

If you do want to track a role in this folder, you can add an exclusion to your .gitignore file such as !roles/my-custom-role

Init Git Repo on Role and Add Remote

Now we need to intialise a git repository in our new role and then add github as a remote

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# cd into the role folder
cd ansible-role/roles/edmondscommerce.akeneo

# init as a git repo
git init .

# add all contents of role to git
git add -A

# create initial commit
git commit -m 'Initial commit'

# add the github remote - Update this line the URL of your new repository
git remote add github git@github.com:edmondscommerce/ansible-role-my-repository.git

# push the commit up to github, using force
git push github master --force

Warning

Notice the user of --force on the git push. This is one of the very few times a force push is appropriate.

Once this has completed, then if you visit the Github page, for example https://github.com/edmondscommerce/ansible-role-akeneo, then you will see the contents of your repo and also the contents of your README.md file displayed on the repo home page.

Add Other Role Dependencies

For our Akeneo role, we are not going to create everything from scratch. Instead, we are going to bring in other roles as dependencies

This is quite straight forwards and involves

  • Updating the meta/main.yml file *