How to install dependencies and configure macOS workstation for running Ansible deployments¶

For several projects such as Grails application ansible deployment or HR Ansible Infrastructure, Ansible is being used to deploy apps to the on-premise infrastructure. The standard method for running Ansible is through the script ./run-ansible-playbook.sh, which is included in every Ansible project. This script is a wrapper that helps to prepare environment, fetch secrets and run ansible-playbook inside docker container.

This document outlines the steps required to configure a macOS workstation for running the Ansible deployment script.

Install dependencies on macOS¶

Docker¶

To install Docker on macOS, follow these steps:

Download Docker Desktop for Mac:

Go to the Docker Desktop download page. Click on Download Docker Desktop. Select your architecture.
Install Docker Desktop:

Once the .dmg file is downloaded, double-click it to open the installer. Drag the Docker icon into the Applications folder.
Run Docker Desktop:

Open the Applications folder and launch Docker. Docker may prompt you to enter your system password to allow the installation of system components (like network management tools). The Docker icon should appear in your menu bar once it has started.
Verify Installation Open a terminal and run the following command to ensure Docker is installed and running:
```
docker --version
```
This should return the installed version of Docker.

1Password CLI¶

The typical UIS DevOps Ansible project uses secrets for ansible-vault stored in 1Password. The 1Password CLI tool op is one of the dependecies. To install 1Password CLI with homebrew:

Run brew install 1password-cli
Check that 1Password CLI installed successfully:
```
op --version
```

Coreutils¶

The Ansible deployment script uses sha256sum which is absent by default on macOS. It can be installed as part of the package called coreutils. To install coreutils with homebrew:

Run brew install coreutils
Check that the package installed successfully:
```
sha256sum --version
```

Configure macOS host¶

Configure access to University Developers' Hub docker registry¶

The Ansible deployment script uses docker images specially built for this purpose. Those images are stored in the University Developers' Hub docker registry. To let docker to access the registry you need to allow docker to login there. For this, perform the following steps:

Login to the the University Developers' Hub.
Go to your account's Personal Access Tokens page.
Click "Add new token".
Set the name for the new token and limit scope to read_registry.
Configure expiration date. By default personal tokens are valid for short amount of time. It makes sense to set it to maximum expiration date available.
Using new token, run
```
docker login registry.gitlab.developers.cam.ac.uk -u $GITLAB_USER -p $GITLAB_TOKEN
```
where $GITLAB_USER is your username and $GITLAB_TOKEN is a newly generated personal access token.

Verify the image is now can be pulled by running the following command:

docker pull registry.gitlab.developers.cam.ac.uk/uis/devops/infra/dockerimages/ansible-playbook:7

Configure ssh agent¶

The Ansible deployment script needs to have SSH access to the target hosts. For this it's necessary to load your private SSH key into the SSH agent and store it in the macOS keychain, enabling automatic SSH authentication when connecting to remote servers. This can be achieved by running the following command:

ssh-add -K $PATH_TO_PRIVATE_KEY

where $PATH_TO_PRIVATE_KEY is a path to the private ssh key e.g.:

ssh-add -K ~/.ssh/id_rsa

Public part of the key must be added to the remote host.

Summary¶

In this how to, you learned how to prepare macOS workstation for running Ansible deployment script including instructions for dependencies installation and host configuration.