How to run AWX on Minishift

The upstream version of Red Hat's Ansible Tower product is AWX. It's a containerized solution, which means you need a container orchestrator to run and look after it. A neat local installation option is Minishift, which runs OKD, Red Hat's version of Minikube, which makes it easier to run Kubernetes locally.

If you're already using Minishift…

First, to ensure things go smoothly, blow away any old Minishift instances.

$ minishift stop && minishift delete
$ rm -rf ~/.minishift ~/.kube

Also delete any old minishift-addons you may have lying around.

Download and install Minishift

Download the latest version of Minishift from its GitHub repository. (As this was published, that's v1.25.0, and I'm using it for MacOS in combination with VirtualBox.)

$ tar zxfv the download and put the minishift-* binary somewhere on your path. I used /usr/local/bin/minishift.

The biggest issues I've had with Minishift are around upgrades, where a conflicting older Minishift or oc binary can cause issues. (oc is OKD's command-line interface.)

AWX needs at least four cores with 8GB to install, so set up some limits (give it more power if you can).

$ minishift config set vm-driver virtualbox
$ minishift config set cpus 4
$ minishift config set memory 8gb
$ minishift config view

Make sure the default add-ons are installed as we need 'admin-user' so we can make cluster level changes

$ minishift addons install --defaults
$ minishift addons enable admin-user
$ minishift addons list
​$ minishift start

Wait for it to download and install. This can take a while if your broadband is like mine!

A few more steps…

There are a couple of other things to set up before installing AWX.

First, make sure to pick the right oc binary—or things might get weird.

$ eval $(minishift docker-env)

The normal user (in this example, "developer") needs extra rights to do things at the cluster level.

$ oc login -u admin -p admin --as=system:admin
$ oc adm policy add-cluster-role-to-user cluster-admin developer --as=system:admin

The AWX playbook installation creates a project, but it doesn't hurt to create it ahead of time so you have a persistent storage volume (PV) for the database.

$ oc new-project awx

Create a file called pvc.yml with this content:

$ cat > pvc.yml <<EOF
apiVersion: "v1"
kind: "PersistentVolumeClaim"
metadata:
 name: "postgresql"
spec:
 accessModes:
  - "ReadWriteMany"
 resources:
  requests:
   storage: "20Gi"
 volumeName: pv0001
EOF

Minishift creates a number of PVs as part of the installation; just make a claim for one of them.

$ oc get pv

To view them and pick a free one, replace the volume name ("pv0001" in the example above) if it's already taken. For example,

$ oc create -f pvc.yml

will make a claim on the PV, be picked up by the installer, and be used as a PV for the Postgres database.

$ oc get pvc 

Check the output shows the PV as Bound:

Install AWX

Finally it's time to install AWX. Enter:

$ git clone https://github.com/ansible/awx.git
$ cd awx/installer

Make changes to the inventory file so things will suit your environment.

$ cp inventory inventory.old

The following works for my inventory file:

$ cat > inventory <<EOF
localhost ansible_connection=local ansible_python_interpreter="/usr/bin/env python"


[all:vars]


dockerhub_base=ansible
dockerhub_version=latest


openshift_host=192.168.99.100:8443
openshift_project=awx
openshift_user=developer
openshift_skip_tls_verify=True
openshift_pg_emptydir=False


postgres_data_dir=/tmp/pgdocker
host_port=80
docker_compose_dir=/var/lib/awx


pg_username=awx
pg_password=awxpass
pg_database=awx
pg_port=5432

rabbitmq_password=awxpass
rabbitmq_erlang_cookie=cookiemonster

admin_user=admin
admin_password=password
secret_key=awxsecret
EOF

You might need to change the openshift_host IP. Check yours by running:

$ minishift ip

Now you're ready to go!

$ ansible-playbook -i inventory install.yml -e openshift_password=developer -e docker_registry_password=$(oc whoami -t)

The playbook will fire off all sorts of tasks; some might fail (if they do, they'll show up in red). This is normally fine. My install took around 5-6 mins as a guide.

Log into the Minishift console using the command:

$ minishift console

and the credentials developer/developer to see what's happening under the covers.

Select the awx project from the GUI, and pods and containers will start to be created.

Note that the ansible-tower-management pod will come and go once the Postgres database is set up. TASK [kubernetes: Migrate database] does this from the playbook run.

After a few minutes, you should get a summary, such as:

< PLAY RECAP >

 ------------

    \ ^__^

     \ (oo)\_______

      (__)\   )\/\

        ||----w |

        ||  ||



localhost         : ok=35 changed=17 unreachable=0  failed=0

As long as unreachable=0 and failed=0, you should be set.

Click on the route under the awx resource in the GUI, and you should be able to log into the AWX GUI admin/password (from the inventory file above).

Make sure the pod circle is blue and therefore "ready."

Two potential gotchas

Minishift or oc binaries are not in sync with the release used. Even though it seems to work (to a degree), when in doubt, blow away the old config!

PVC claim seemed to capture the quotes around pv0001 and wouldn't bind, so I removed them and it worked. This may have been a copy and paste error. 

The original version of this article was published on LinkedIn and is reprinted with the author's permission.