Learn how to - How To Install Ansible AWX on Debian 11/10 Linux

Felix Williams Ansible Debian How to Linux Tutorials January 6, 2023

Learn how to – How To Install Ansible AWX on Debian 11/10 Linux.

Ansible AWX is a free and open source Ansible Management tool created to provide System Administrators and Developers with an easy to use, intuitive and powerful web-based user interface for managing Ansible playbooks, Secrets, inventories, and Automation cron jobs scheduled to run at certain intervals. This guide explains how to install Ansible AWX on Debian 11/10 Linux system.

For Vanilla Ansible installation: How To Install and Use Ansible on Debian

Step 1: Update Debian system

Update and upgrade your Debian System before you install Ansible AWX:

sudo apt update && sudo apt -y full-upgrade

If a reboot is required the system should be restarted.

[ -f /var/run/reboot-required ] && sudo reboot -f

Step 2: Install Single Node k3s Kubernetes

We will deploy a single node kubernetes using k3s lightweight tool. K3s is a certified Kubernetes distribution designed for production workloads in unattended, resource-constrained environments. The good thing with k3s is that you can add more Worker nodes at later stage if need arises.

Install K3s Kubernetes on your Debian system by running the following command:

curl -sfL https://get.k3s.io | bash -s - --write-kubeconfig-mode 644

Expected installation output – The process should complete in few seconds / minutes.

[INFO]  Finding release for channel stable
[INFO]  Using v1.24.4+k3s1 as release
[INFO]  Downloading hash https://github.com/k3s-io/k3s/releases/download/v1.24.4+k3s1/sha256sum-amd64.txt
[INFO]  Downloading binary https://github.com/k3s-io/k3s/releases/download/v1.24.4+k3s1/k3s
[INFO]  Verifying binary download
[INFO]  Installing k3s to /usr/local/bin/k3s
[INFO]  Skipping installation of SELinux RPM
[INFO]  Creating /usr/local/bin/kubectl symlink to k3s
[INFO]  Creating /usr/local/bin/crictl symlink to k3s
[INFO]  Creating /usr/local/bin/ctr symlink to k3s
[INFO]  Creating killall script /usr/local/bin/k3s-killall.sh
[INFO]  Creating uninstall script /usr/local/bin/k3s-uninstall.sh
[INFO]  env: Creating environment file /etc/systemd/system/k3s.service.env
[INFO]  systemd: Creating service file /etc/systemd/system/k3s.service
[INFO]  systemd: Enabling k3s unit
Created symlink /etc/systemd/system/multi-user.target.wants/k3s.service → /etc/systemd/system/k3s.service.
[INFO]  systemd: Starting k3s

After installation kubectl is configured for you, use it to check cluster details:

$ kubectl get nodes
NAME     STATUS   ROLES                  AGE   VERSION
debian   Ready    control-plane,master   33s   v1.24.4+k3s1

Step 3: Deploy AWX Operator on Kubernetes

The AWX Operator is used to manage one or more AWX instances in any namespace within the cluster.

Install git and make tools:

sudo apt update
sudo apt install git vim build-essential apparmor apparmor-utils -y

Install Kustomize:

curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh"  | bash
sudo mv kustomize /usr/local/bin

Confirm installation of Kustomize by checking the version:

$ kustomize version
{Version:kustomize/v4.5.7 GitCommit:56d82a8378dfc8dc3b3b1085e5a6e67b82966bd7 BuildDate:2022-08-02T16:35:54Z GoOs:linux GoArch:amd64}

Save the latest version from AWX Operator releases as RELEASE_TAG variable then checkout to the branch using git.

sudo apt update
sudo apt install curl jq -y
RELEASE_TAG=`curl -s https://api.github.com/repos/ansible/awx-operator/releases/latest | grep tag_name | cut -d '"' -f 4`
echo $RELEASE_TAG

Create a file called kustomization.yaml with the following content:

tee kustomization.yaml<<EOF
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  # Find the latest tag here: https://github.com/ansible/awx-operator/releases
  - github.com/ansible/awx-operator/config/default?ref=$RELEASE_TAG

# Set the image tags to match the git version from above
images:
  - name: quay.io/ansible/awx-operator

# Specify a custom namespace in which to install AWX
namespace: awx
EOF

Install the manifests by running this:

$ kustomize build . | kubectl apply -f -
namespace/awx created
customresourcedefinition.apiextensions.k8s.io/awxbackups.awx.ansible.com created
customresourcedefinition.apiextensions.k8s.io/awxrestores.awx.ansible.com created
customresourcedefinition.apiextensions.k8s.io/awxs.awx.ansible.com created
serviceaccount/awx-operator-controller-manager created
role.rbac.authorization.k8s.io/awx-operator-awx-manager-role created
role.rbac.authorization.k8s.io/awx-operator-leader-election-role created
clusterrole.rbac.authorization.k8s.io/awx-operator-metrics-reader created
clusterrole.rbac.authorization.k8s.io/awx-operator-proxy-role created
rolebinding.rbac.authorization.k8s.io/awx-operator-awx-manager-rolebinding created
rolebinding.rbac.authorization.k8s.io/awx-operator-leader-election-rolebinding created
clusterrolebinding.rbac.authorization.k8s.io/awx-operator-proxy-rolebinding created
configmap/awx-operator-awx-manager-config created
service/awx-operator-controller-manager-metrics-service created
deployment.apps/awx-operator-controller-manager created

Set current context to value set in NAMESPACE variable:

$ kubectl config set-context --current --namespace=$NAMESPACE 
Context "default" modified.

After a few minutes awx-operator should be in a running status:

# kubectl get pods -n awx
NAME                                               READY   STATUS    RESTARTS   AGE
awx-operator-controller-manager-54787fcf67-swcbr   2/2     Running   0          96s

Uninstalling AWX Operator (just for reference)

You can always remove the operator and all associated CRDs by running the command below:

kustomize build . | kubectl delete -f -

Step 4: Deploy AWX on Debian on K3s Kubernetes

We need to persist Web Application data by creating a PVC – Reference AWX data persistence. Execute below commands in the terminal to initiate PersistentVolumeClaim creation:

cat <<EOF | kubectl create -f -
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: static-data-pvc
  namespace: awx
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: local-path
  resources:
    requests:
      storage: 5Gi
EOF

Create AWX deployment instance deployment YAML file:

tee awx-deploy.yml<<EOF
---
apiVersion: awx.ansible.com/v1beta1
kind: AWX
metadata:
  name: awx
spec:
  service_type: nodeport
EOF

Update the Kustomize file:

RELEASE_TAG=`curl -s https://api.github.com/repos/ansible/awx-operator/releases/latest | grep tag_name | cut -d '"' -f 4`
tee kustomization.yaml<<EOF
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  # Find the latest tag here: https://github.com/ansible/awx-operator/releases
  - github.com/ansible/awx-operator/config/default?ref=$RELEASE_TAG
  # Add this extra line:
  - awx-deploy.yml
# Set the image tags to match the git version from above
images:
  - name: quay.io/ansible/awx-operator

# Specify a custom namespace in which to install AWX
namespace: awx
EOF

Apply configuration to create required objects:

$ kustomize build . | kubectl apply -f -
namespace/awx unchanged
customresourcedefinition.apiextensions.k8s.io/awxbackups.awx.ansible.com unchanged
customresourcedefinition.apiextensions.k8s.io/awxrestores.awx.ansible.com unchanged
customresourcedefinition.apiextensions.k8s.io/awxs.awx.ansible.com unchanged
serviceaccount/awx-operator-controller-manager unchanged
role.rbac.authorization.k8s.io/awx-operator-awx-manager-role configured
role.rbac.authorization.k8s.io/awx-operator-leader-election-role unchanged
clusterrole.rbac.authorization.k8s.io/awx-operator-metrics-reader unchanged
clusterrole.rbac.authorization.k8s.io/awx-operator-proxy-role unchanged
rolebinding.rbac.authorization.k8s.io/awx-operator-awx-manager-rolebinding unchanged
rolebinding.rbac.authorization.k8s.io/awx-operator-leader-election-rolebinding unchanged
clusterrolebinding.rbac.authorization.k8s.io/awx-operator-proxy-rolebinding unchanged
configmap/awx-operator-awx-manager-config unchanged
service/awx-operator-controller-manager-metrics-service unchanged
deployment.apps/awx-operator-controller-manager configured
awx.awx.ansible.com/awx created

Wait a few minutes then check AWX instance deployed:

$ kubectl -n awx get pods -l "app.kubernetes.io/managed-by=awx-operator"
NAME                   READY   STATUS    RESTARTS   AGE
awx-postgres-0         1/1     Running   0          75s
awx-7c5d846c88-mjlvm   4/4     Running   0          64s

If you experience any issues with the Pods starting check deployment logs:

kubectl logs -f deployments/awx-operator-controller-manager -c awx-manager

The database data will be persistent as they are stored in a persistent volume:

# kubectl get pvc
NAME                            STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
postgres-13-awx-postgres-13-0   Bound    pvc-998f2911-fa1d-4d84-acbb-445bf6837292   8Gi        RWO            local-path     11s

Volumes are created using local-path-provisioner and host path

$ ls /var/lib/rancher/k3s/storage/
pvc-998f2911-fa1d-4d84-acbb-445bf6837292_awx_postgres-13-awx-postgres-13-0

List all available services and check awx-service Nodeport

$ kubectl get svc -l "app.kubernetes.io/managed-by=awx-operator"
NAME           TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)        AGE
awx-postgres   ClusterIP   None           <none>        5432/TCP       2m5s
awx-service    NodePort    10.43.182.53   <none>        80:30080/TCP   116s

You can edit the Node Port and set to figure of your preference

$ kubectl edit svc awx-service
....
ports:
  - name: http
    nodePort: <value>
    port: 80
    protocol: TCP
    targetPort: 8052

If you have an Ingress controller in the Cluster you can create a route for AWX application to access the app over Domain name.

Access AWX Container’s Shell

Here is how to access each container’s shell:

kubectl exec -ti deploy/awx  -c  awx-task -- /bin/bash
kubectl exec -ti deploy/awx  -c  awx-web -- /bin/bash
kubectl exec -ti deploy/awx  -c  awx-ee -- /bin/bash
kubectl exec -ti deploy/awx  -c  redis -- /bin/bash

Checking AWX Container’s logs

The awx-xxx-yyy pod will have four containers, namely:

redis
awx-web
awx-task
awx-ee

As can be seen from below command output:

# kubectl get deploy
NAME                              READY   UP-TO-DATE   AVAILABLE   AGE
awx-operator-controller-manager   1/1     1            1           9m58s
awx                              1/1     1            1           7m47s

# kubectl -n awx  logs deploy/awx
error: a container name must be specified for pod awx-66596c8fcb-s28tw, choose one of: [redis awx-web awx-task awx-ee] or one of the init containers: [database-check init]

You’ll need to provide container name after the pod:

kubectl -n awx  logs deploy/awx -c redis
kubectl -n awx  logs deploy/awx -c awx-web
kubectl -n awx  logs deploy/awx -c awx-task
kubectl -n awx  logs deploy/awx -c awx-ee

Upgrading AWX Operator and instance

We have created a dedicated guide for upgrading the Operator and AWX instance:

How to upgrade Ansible AWX running in Kubernetes

Step 5: Access Ansible AWX Dashboard

Ansible AWX web portal is now accessible on http://hostip_or_hostname:30080.

How To Install Ansible AWX on Ubuntu 20.04|18.04 Linux 1

Obtain admin user password by decoding the secret with the password value:

kubectl get secret awx-admin-password -o go-template='{{range $k,$v := .data}}{{printf "%s: " $k}}{{if not $v}}{{$v}}{{else}}{{$v | base64decode}}{{end}}{{"n"}}{{end}}'

Sample output:

password: LkyWUKDwKdnhiEcvFe0zRQ9jOJCz7eMS

How To Install Ansible AWX on Ubuntu 20.04|18.04 Linux 2

There you have AWX Administration interface. Start adding inventory, importing Ansible roles and automate your Infrastructure and Applications deployment.

How To Install Ansible AWX on Ubuntu 20.04|18.04 Linux 3

Step 6: Configure Ingress for AWX

If you would like to access your AWX using domain names and SSL, check out our ingress articles:

Related guides.

Cart

Learn how to – How To Install Ansible AWX on Debian 11/10 Linux