How To Install Ansible AWX on Debian 12/11/10

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 12/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.27.4+k3s1 as release
[INFO]  Downloading hash https://github.com/k3s-io/k3s/releases/download/v1.27.4+k3s1/sha256sum-amd64.txt
[INFO]  Downloading binary https://github.com/k3s-io/k3s/releases/download/v1.27.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.27.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
v5.1.1

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:

# export NAMESPACE=awx
# 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
  projects_persistence: true
  projects_storage_access_mode: ReadWriteOnce
  web_extra_volume_mounts: |
    - name: static-data
      mountPath: /var/lib/projects
  extra_volumes: |
    - name: static-data
      persistentVolumeClaim:
        claimName: static-data-pvc
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-13-0          1/1     Running   0          3m34s
awx-task-58cbc7bdc-s7dfq   4/4     Running   0          2m49s
awx-web-56cdd7bdcf-mczsg   3/3     Running   0          102s

Listing deployments.

$ kubectl get deployments -n awx
NAME                              READY   UP-TO-DATE   AVAILABLE   AGE
awx-operator-controller-manager   1/1     1            1           7m54s
awx-task                          1/1     1            1           5m22s
awx-web                           1/1     1            1           4m15s

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

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

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

List deployments.

$ kubectl get deploy -n awx
NAME                              READY   UP-TO-DATE   AVAILABLE   AGE
awx-operator-controller-manager   1/1     1            1           6m47s
awx-task                          1/1     1            1           5m39s
awx-web                           1/1     1            1           3m37s

Listing containers

Here is how to access each container’s shell:

kubectl exec -ti deploy/awx-web -c redis -- /bin/bash
kubectl exec -ti deploy/awx-web  -c  awx-web -- /bin/bash
kubectl exec -ti awx-postgres-13-0  -c  postgres -- /bin/bash

Checking AWX Container’s logs

List deployments.

# kubectl get deploy -n awx
NAME                              READY   UP-TO-DATE   AVAILABLE   AGE
awx-operator-controller-manager   1/1     1            1           13m
awx-task                          1/1     1            1           12m
awx-web                           1/1     1            1           10m

List Pods.

# kubectl get pods  -n awx
NAME                                               READY   STATUS    RESTARTS   AGE
awx-operator-controller-manager-77d4cc4746-phx7l   2/2     Running   0          16m
awx-postgres-13-0                                  1/1     Running   0          15m
awx-task-56599458d6-5rb8m                          4/4     Running   0          15m
awx-web-75dfc8f8d7-4mgsk                           3/3     Running   0          13m

List containers in each pod.

$ kubectl -n awx get pod awx-task-56599458d6-5rb8m -o jsonpath='{.spec.containers[*].name}';echo
redis awx-task awx-ee awx-rsyslog

$ kubectl -n awx get pod awx-web-75dfc8f8d7-4mgsk -o jsonpath='{.spec.containers[*].name}';echo
redis awx-task awx-ee awx-rsyslog

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

• redis
• awx-task
• awx-ee
• awx-rsyslog

As can be seen from below command output:

# kubectl -n awx  logs deploy/<deployment-name>

Syntax for checking container logs.

kubectl -n awx  logs deploy/<deployment> -c <container>
# OR kubectl -n awx logs pod/<podName> -c <containerName>

See below examples.

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

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.

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

Login with user admin and decoded password:

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

Step 6: Configure Ingress for AWX

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

• How To Expose Ansible AWX Service using Traefik Ingress route
• How To Expose Ansible AWX Service using Nginx Ingress

Related guides.

• Install Ansible AWX on Ubuntu
• How To Install and Configure Ansible Tower on CentOS 7
• Install Ansible AWX on CentOS 7 / Fedora
• Semaphore – Manage Ansible Tasks from A Web UI