Welcome to our guide on how to install Ansible AWX on CentOS 7 / RHEL 7 using Kubernetes k3s distribution. If you have a separate Kubernetes cluster the installation process should just work fine. In this setup we shall use the operator meant to provide a more Kubernetes-native installation method for AWX via an AWX Custom Resource Definition (CRD).
What is AWX?
AWX is the upstream project from which the Red Hat Ansible Tower which provides a web-based user interface, REST API, and task engine built on top of Ansible. It is the upstream project for Tower, a commercial derivative of AWX. This is an open source community project, sponsored by Red Hat, that enables users to better control their Ansible project use in IT environments. The AWX source code is available under the Apache License 2.0.
Install Ansible AWX on CentOS 7 / RHEL 7
We have some setup requirements to run Ansible AWX on CentOS 7 / RHEL 7 Linux system.
- Kubernetes Cluster / Docker
- CentOS 7 / RHEL 7 server
- User with sudo access
- Minimum of 8GB of RAM – if you have more memory the better
- Minimum of 4vcpus
- 25GB minimum disk space
Step 1: Disable SELinux and firewalld
Let’s ensure our system is updated.
sudo yum -y update
Once the update is successful perform a system reboot
sudo reboot
Disable SELinux or put it in permissive mode to ensure no issues are experienced during the deployment:
sudo setenforce 0
sudo sed -i 's/^SELINUX=.*/SELINUX=permissive/g' /etc/selinux/config
cat /etc/selinux/config | grep SELINUX=
Disable Firewalld since it’s a recommendation by K3s.
sudo systemctl disable firewalld --now
Step 2: Install K3s Kubernetes Distribution
All recent releases of AWX can run as a containerized application using Docker images deployed on Kubernetes, OpenShift cluster, or using docker-compose. In this guide we shall focus on the installation of Ansible AWX on CentOS 7 / RHEL 7 using k3s Kubernetes distribution.
But first we need to install k3s. This can be done by running the commands below in your terminal.
curl -sfL https://get.k3s.io | sudo bash -
sudo chmod 644 /etc/rancher/k3s/k3s.yaml
After installation check the status of k3s service.
$ systemctl status k3s.service
● k3s.service - Lightweight Kubernetes
Loaded: loaded (/etc/systemd/system/k3s.service; enabled; vendor preset: disabled)
Active: active (running) since Thu 2023-08-24 14:49:12 UTC; 8s ago
Docs: https://k3s.io
Process: 22104 ExecStartPre=/sbin/modprobe overlay (code=exited, status=0/SUCCESS)
Process: 22098 ExecStartPre=/sbin/modprobe br_netfilter (code=exited, status=0/SUCCESS)
Process: 22095 ExecStartPre=/bin/sh -xc ! /usr/bin/systemctl is-enabled --quiet nm-cloud-setup.service (code=exited, status=0/SUCCESS)
Main PID: 22107 (k3s-server)
Tasks: 35
Memory: 551.2M
CGroup: /system.slice/k3s.service
├─22107 /usr/local/bin/k3s server
└─22128 containerd -c /var/lib/rancher/k3s/agent/etc/containerd/config.toml -a /run/k3s/containerd/containerd.sock --state /run/k3s/containerd --root /var/lib/rancher/k3s/agent/contain...
....
Copy Kubectl configuration.
mkdir ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
Test that your k3s installation works.
$ kubectl get nodes
NAME STATUS ROLES AGE VERSION
cent7.mylab.io Ready control-plane,master 6m2s v1.27.4+k3s1
Kubernetes server and client versions can be checked with the commands;
# kubectl version --short
Client Version: v1.27.4+k3s1
Kustomize Version: v5.0.1
Server Version: v1.27.4+k3s1
Step 3: Deploy AWX Operator on k3s Kubernetes
Install git and make tools required in this setup.
sudo yum -y install jq git make
We’ll need to deploy Kubernetes Operator used to manage one or more AWX instances in any namespace. Clone deployment code from Github:
git clone https://github.com/ansible/awx-operator.git
Create namespace called awx where an operator and AWX instance will be deployed.
export NAMESPACE=awx
kubectl create ns ${NAMESPACE}
Navigate to the awx-operator directory:
cd awx-operator/
Get the latest version of AWX operator from AWX Operator releases and save as RELEASE_TAG variable.
RELEASE_TAG=`curl -s https://api.github.com/repos/ansible/awx-operator/releases/latest | grep tag_name | cut -d '"' -f 4`
echo $RELEASE_TAG
Checkout to the branch using git command:
git checkout $RELEASE_TAG
Deploy AWX Operator into your cluster with the make deploy
commands:
export NAMESPACE=awx
make deploy
Command execution terminal output:
namespace/awx configured
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
Wait a few minutes and awx-operator should be running:
$ kubectl get pods -n awx
NAME READY STATUS RESTARTS AGE
awx-operator-controller-manager-557589c5f4-wm2h5 2/2 Running 0 42s
Step 4: Install AWX on CentOS 7 / RHEL 7 using operator
With the operator running we can proceed to deploy AWX instance in the cluster. But first create a PVC for data persistence in the cluster.
Create a file named public-static-pvc.yaml:
vi public-static-pvc.yaml
Paste and modify the contents below to your liking.
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: public-static-data-pvc
spec:
accessModes:
- ReadWriteOnce
storageClassName: local-path
resources:
requests:
storage: 8Gi
Apply the settings with kubectl apply
commands:
$ kubectl apply -f public-static-pvc.yaml -n awx
persistentvolumeclaim/public-static-data-pvc created
Notice that the PVC won’t be bound at this time. A running Pod is needed for binding to be created.
$ kubectl get pvc -n awx
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
public-static-data-pvc Pending local-path 32s
Create AWX instance deployment YAML file contents:
vi awx-instance-deployment.yml
Paste below contents to the file created.
---
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: public-static-data-pvc
Deploy AWX on CentOS 7 / RHEL 7 Linux machine.
$ kubectl apply -f awx-instance-deployment.yml -n awx
awx.awx.ansible.com/awx created
Wait for the Pods status to change to running
$ kubectl get pods -l "app.kubernetes.io/managed-by=awx-operator" -n awx -w
NAME READY STATUS RESTARTS AGE
awx-postgres-0 1/1 Running 0 2m58s
awx-75698588d6-qz2gf 4/4 Running 0 2m42s
Logs of the deployment progress can be checked using commands shared below.
kubectl logs -f deployments/awx-operator-controller-manager -c awx-manager -n awx
Extra PVCs are created automatically during AWX deployment.
$ kubectl get pvc -n awx
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
postgres-awx-postgres-0 Bound pvc-c67f0695-fd13-4ca5-a742-7e85bdcdd05e 8Gi RWO local-path 3m42s
awx-projects-claim Bound pvc-af9d7b38-a508-46ae-ae22-8a74e612a33d 8Gi RWO local-path 2m45s
public-static-data-pvc Bound pvc-8162895a-ae35-4d3d-bb37-50edef756fbf 8Gi RWO local-path 6m42s
List of Pods created in awx namespace:
$ kubectl get pods -n awx
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
postgres-13-awx-postgres-13-0 Bound pvc-4f1873ca-4726-4550-897f-3186019d19fa 8Gi RWO local-path 6m44s
public-static-data-pvc Bound pvc-5af86274-dbcb-4f70-b318-8e93c3328df3 8Gi RWO local-path 7m36s
awx-projects-claim Bound pvc-634b3abf-1fdf-4efb-ba1f-da0560112c1d 8Gi RWO local-path 6m5s
Step 5: How to Check AWX Container’s logs
The AWX will have below deployments.
- awx-web
- awx-task
- awx-operator-controller-manager
As can be seen from below command output:
$ kubectl get deploy -n awx
NAME READY UP-TO-DATE AVAILABLE AGE
awx-operator-controller-manager 1/1 1 1 9m19s
awx-task 1/1 1 1 6m52s
awx-web 1/1 1 1 6m
$ kubectl -n awx logs deploy/awx-web
...
2023-08-24 15:05:31,077 INFO success: nginx entered RUNNING state, process has stayed up for > than 30 seconds (startsecs)
2023-08-24 15:05:31,077 INFO success: nginx entered RUNNING state, process has stayed up for > than 30 seconds (startsecs)
2023-08-24 15:05:31,078 INFO success: uwsgi entered RUNNING state, process has stayed up for > than 30 seconds (startsecs)
2023-08-24 15:05:31,078 INFO success: uwsgi entered RUNNING state, process has stayed up for > than 30 seconds (startsecs)
2023-08-24 15:05:31,078 INFO success: daphne entered RUNNING state, process has stayed up for > than 30 seconds (startsecs)
2023-08-24 15:05:31,078 INFO success: daphne entered RUNNING state, process has stayed up for > than 30 seconds (startsecs)
2023-08-24 15:05:31,078 INFO success: awx-cache-clear entered RUNNING state, process has stayed up for > than 30 seconds (startsecs)
2023-08-24 15:05:31,078 INFO success: awx-cache-clear entered RUNNING state, process has stayed up for > than 30 seconds (startsecs)
2023-08-24 15:05:31,078 INFO success: ws-heartbeat entered RUNNING state, process has stayed up for > than 30 seconds (startsecs)
2023-08-24 15:05:31,078 INFO success: ws-heartbeat entered RUNNING state, process has stayed up for > than 30 seconds (startsecs)
Specify the name of the container for which you need to check its logs.
kubectl -n awx logs deploy/<deployment> -c <container>
Or use:
kubectl -n awx logs pod/<podName> -c <containerName>
List all Pods
$ kubectl get pod -n awx
NAME READY STATUS RESTARTS AGE
awx-operator-controller-manager-564f8dc4fc-wspln 2/2 Running 0 12m
awx-postgres-13-0 1/1 Running 0 10m
awx-task-84ff8bcf7b-2ddv4 4/4 Running 0 10m
awx-web-799d8f444f-kfzvl 3/3 Running 0 9m22s
List containers in each pod.
$ kubectl -n awx get pod awx-web-799d8f444f-kfzvl -o jsonpath='{.spec.containers[*].name}';echo
redis awx-web awx-rsyslog
$ kubectl -n awx get pod awx-task-84ff8bcf7b-2ddv4 -o jsonpath='{.spec.containers[*].name}';echo
redis awx-task awx-ee awx-rsyslog
Step 6: Accessing AWX Pod container shell
Commands used to check the logs of each container. See examples below.
kubectl -n awx exec -ti deploy/awx-web -c redis -- /bin/bash
kubectl -n awx exec -ti deploy/awx-web -c awx-rsyslog -- /bin/bash
To get out of the shell, just type exit
bash-5.1$ exit
exit
Step 7: Access AWX Web Interface
Get the AWX Web service port:
$ kubectl get service -n awx
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
awx-operator-controller-manager-metrics-service ClusterIP 10.43.151.146 <none> 8443/TCP 19m
awx-postgres-13 ClusterIP None <none> 5432/TCP 17m
awx-service NodePort 10.43.197.41 <none> 80:30614/TCP 16m
From the output we can confirm service node port is 30614. Access AWX web console using your k3s server IP address and service nodeport.
http://k3s-server-ip-address:30080
Welcome to AWX page will be displayed.
The login username is admin with the password as output of the following command:
kubectl -n awx 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: ZMXFxKxPpDq10iZDyZNhY2cBLxs32Ohu
Login with the admin username and decoded password from above commands:
Once the authentication is successful, you’ll get to AWX administration dashboard.
Therein, there is a lot of stuff to do. Take your time to explore and refer to official AWX documentation for detailed user guides.
Step 8: 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
Step 9: How to Upgrade AWX instance on Kubernetes
Follow the guide in the following link to upgrade your AWX operator and instance deployed in a Kubernetes cluster.
Step 10: Uninstalling AWX Operator (Only for reference)
The operator and all associated CRDs can be uninstalled by running the commands below:
# export NAMESPACE=awx
# make undeploy
/root/awx-operator/bin/kustomize build config/default | kubectl delete -f -
namespace "awx" deleted
customresourcedefinition.apiextensions.k8s.io "awxbackups.awx.ansible.com" deleted
customresourcedefinition.apiextensions.k8s.io "awxrestores.awx.ansible.com" deleted
customresourcedefinition.apiextensions.k8s.io "awxs.awx.ansible.com" deleted
serviceaccount "awx-operator-controller-manager" deleted
role.rbac.authorization.k8s.io "awx-operator-leader-election-role" deleted
role.rbac.authorization.k8s.io "awx-operator-manager-role" deleted
clusterrole.rbac.authorization.k8s.io "awx-operator-metrics-reader" deleted
clusterrole.rbac.authorization.k8s.io "awx-operator-proxy-role" deleted
rolebinding.rbac.authorization.k8s.io "awx-operator-leader-election-rolebinding" deleted
rolebinding.rbac.authorization.k8s.io "awx-operator-manager-rolebinding" deleted
clusterrolebinding.rbac.authorization.k8s.io "awx-operator-proxy-rolebinding" deleted
configmap "awx-operator-manager-config" deleted
service "awx-operator-controller-manager-metrics-service" deleted
deployment.apps "awx-operator-controller-manager" deleted
Wrapping Up
To this point we have shown you how to install and use AWX on CentOS 7 / RHEL 7 Linux system. AWX is created to help teams, both small and large in management of complex multi-tier deployments by knowledge, adding control, and delegation to Ansible-powered environments.
Similar: