Skip to content

Latest commit

 

History

History
156 lines (107 loc) · 5.96 KB

INSTALL.md

File metadata and controls

156 lines (107 loc) · 5.96 KB
Raw

Table of Contents

Installing AWX

⚠️ NOTE
If you're installing an older release of AWX (prior to 18.0), these instructions have changed. Take a look at your version specific instructions, e.g., for AWX 17.0.1, see: https://github.com/ansible/awx/blob/17.0.1/INSTALL.md
If you're attempting to migrate an older Docker-based AWX installation, see: Migrating Data from Local Docker

The AWX Operator

Starting in version 18.0, the AWX Operator is the preferred way to install AWX.

AWX can also alternatively be installed and run in Docker, but this install path is only recommended for development/test-oriented deployments, and has no official published release.

Quickstart with minikube

If you don't have an existing OpenShift or Kubernetes cluster, minikube is a fast and easy way to get up and running.

To install minikube, follow the steps in their documentation.

⚠️ NOTE
If you're about to install minikube or have already installed it, please be sure you're using Minikube v1.18.1. There's a bug right now that will not allow you to run it using Minikube v1.19.x.

Starting minikube

Once you have installed minikube, run the following command to start it. You may wish to customize these options.

$ minikube start --cpus=4 --memory=8g --addons=ingress

Deploying the AWX Operator

For a comprehensive overview of features, see README.md in the awx-operator repo. The following steps are the bare minimum to get AWX up and running.

Start by going to https://github.com/ansible/awx-operator/releases and making note of the latest release. Replace <tag> in the URL below with the version you are deploying:

$ minikube kubectl -- apply -f https://raw.githubusercontent.com/ansible/awx-operator/<tag>/deploy/awx-operator.yaml
Verifying the Operator Deployment

After a few seconds, the operator should be up and running. Verify it by running the following command:

$ minikube kubectl get pods
NAME                           READY   STATUS    RESTARTS   AGE
awx-operator-7c78bfbfd-xb6th   1/1     Running   0          11s

Deploy AWX

Once the Operator is running, you can now deploy AWX by creating a simple YAML file:

$ cat myawx.yml
---
apiVersion: awx.ansible.com/v1beta1
kind: AWX
metadata:
  name: awx
spec:
  tower_ingress_type: Ingress

If a custom AWX image is needed, see these docs on how to build and use it.

And then creating the AWX object in the Kubernetes API:

$ minikube kubectl apply -- -f myawx.yml
awx.awx.ansible.com/awx created

After creating the AWX object in the Kubernetes API, the operator will begin running its reconciliation loop.

To see what's going on, you can tail the logs of the operator pod (note that your pod name will be different):

$ minikube kubectl logs -- -f awx-operator-7c78bfbfd-xb6th

After a few seconds, you will see the database and application pods show up. On a fresh system, it may take a few minutes for the container images to download.

$ minikube kubectl get pods
NAME                           READY   STATUS    RESTARTS   AGE
awx-5ffbfd489c-bvtvf           3/3     Running   0          2m54s
awx-operator-7c78bfbfd-xb6th   1/1     Running   0          6m42s
awx-postgres-0                 1/1     Running   0          2m58s
Accessing AWX

To access the AWX UI, you'll need to grab the service url from minikube:

$ minikube service awx-service --url
http://192.168.59.2:31868

On fresh installs, you will see the "AWX is currently upgrading." page until database migrations finish.

Once you are redirected to the login screen, you can now log in by obtaining the generated admin password (note: do not copy the trailing %):

$ minikube kubectl -- get secret awx-admin-password -o jsonpath='{.data.password}' | base64 --decode
b6ChwVmqEiAsil2KSpH4xGaZPeZvWnWj%

Now you can log in at the URL above with the username "admin" and the password above. Happy Automating!

Installing the AWX CLI

awx is the official command-line client for AWX. It:

  • Uses naming and structure consistent with the AWX HTTP API
  • Provides consistent output formats with optional machine-parsable formats
  • To the extent possible, auto-detects API versions, available endpoints, and feature support across multiple versions of AWX.

Potential uses include:

  • Configuring and launching jobs/playbooks
  • Checking on the status and output of job runs
  • Managing objects like organizations, users, teams, etc...

The preferred way to install the AWX CLI is through pip directly from PyPI:

pip3 install awxkit
awx --help

Building the CLI Documentation

To build the docs, spin up a real AWX server, pip3 install sphinx sphinxcontrib-autoprogram, and run:

~ cd awxkit/awxkit/cli/docs
~ TOWER_HOST=https://awx.example.org TOWER_USERNAME=example TOWER_PASSWORD=secret make clean html
~ cd build/html/ && python -m http.server
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ..