Skip to content


About this guide

This guide is streigh forward, step-by-step tutorial for deploying AWX on a single node k3s Kubernetes cluster. Ideal for Linux and cloud engineers looking to integrate AWX with Kubernetes for enhanced automation.

What you will get ?

This guide will setup user, install k3s, install AWX operator and deploy AWX instance with persistent storage.

What you will need ?

  • 1x Linux server with 4 CPU cores and 4G Ram minimal or the deployment will fail.
  • This guide
  • Basic Linux knowledge

OS setup


This is not a guide on how to setup your Linux server as whole but the basic steps I did before installing k3s and AWX.

Oracle Linux 8

My preffered Linux distribution is Oracle Linux 8. I like it because it is free, stable and has great support for Docker and Kubernetes. You can use any Linux distribution you want, but I will be using Oracle Linux 8 in this guide.

You can get it here: Oracle Linux

Install Oracle Linux 8 with minimal install. Once you are in console switch to root

sudo su -

Do update and upgrade of the OS

# Add the Oracle Linux 8 EPEL repo for additional packages
dnf install oracle-epel-release-el8 -y
# Update the OS
dnf update -y
# Install some basic packages
dnf install -y jq git make
Just to be sure, reboot the server


When back in console switch to root again

sudo su -

And turn off selinux

# This command will turn off selinux for this session
setenforce 0
# This command will turn off selinux permanently
sed -i 's/^SELINUX=.*/SELINUX=disabled/g' /etc/selinux/config
Disable firewall

systemctl disable firewalld  --now
systemctl stop firewalld

Installing k3s

Install k3s the normal way

Assuming you have your Linux server ready and internet connection is working, we can start with the installation.

I personally prefer Ubuntu or Oracle Linux, but I think you can use any Linux distribution you want. Just do the classic update and upgrade of the OS, reboot etc first...


Switch to root, I did everything under root to avoid issues. ( In production you would use custom user, never run stuff under root in the wild.)

curl -sfL | sh -

This will install k3s and start it. You can check if its running with:

systemctl status k3s

Also you can check if the k3s is running with:

kubectl get nodes

This should return something like:

root@control01:~# kubectl get nodes
NAME         STATUS   ROLES                  AGE   VERSION
control01    Ready    control-plane,master   12d   v1.20.2+k3s1

Congratulations, you have k3s running on your server.

Install AirGap k3s

If you have the misfortune of not having internet connection on your server, you can still install k3s, but you need to do it in AirGap mode.


This works fine but you will need to have locally availible image repository later on for any other images you want to use. We will provide k3s images during install so you will have working k3s cluster.

Here is the original guide from k3s: AirGap Install

curl -L -o && chmod +x

Copy the to the server you want to install k3s on.

From get k3s and k3s-airgap-images-amd64.tar latest files. Maybe look for something that is not tagged as "pre-release"

Copy the k3s and k3s-airgap-images-amd64.tar to the server you want to install k3s on.

# cd to the folder where you have the files
mv k3s /usr/local/bin/ && chmod +x /usr/local/bin/k3s
mkdir -p /var/lib/rancher/k3s/agent/images/
cp k3s-airgap-images-amd64.tar /var/lib/rancher/k3s/agent/images/
dnf install -y container-selinux

This will install k3s and start it. You can check if its running the same way as in normal install above.

Installing AWX Operator

Next we need to install AWX operator. This is the thing that will take care of installing AWX for us.


This is not the same as AWX itself. This is just the operator that will install AWX for us. And if you are on AirGap install you need to have the images availible locally or on accessible repository. Also on AirGap install you do the git clone on your workstation and copy the files to the server.

git clone
export NAMESPACE=awx
kubectl create ns ${NAMESPACE}
cd awx-operator/
RELEASE_TAG=`curl -s | grep tag_name | cut -d '"' -f 4`
git checkout $RELEASE_TAG
# If you are on AirGap install, copy the files to the server now and cd to the folder. Then continue.
export NAMESPACE=awx
make deploy

Give it some time to install, you can check the status with:

kubectl get pods -n awx

Installing AWX

Now we can install AWX itself. This is the actual AWX that will run on our k3s cluster.

Create two files public-static-pvc.yaml and awx-instance-deployment.yml with the content below.


apiVersion: v1
kind: PersistentVolumeClaim
  name: public-static-data-pvc
    - ReadWriteOnce
  storageClassName: local-path
      storage: 20Gi


kind: AWX
  name: awx
  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
        claimName: public-static-data-pvc

Now we can apply the config and check the status:

kubectl apply -f public-static-pvc.yaml -n awx
kubectl apply -f awx-instance-deployment.yml -n awx
kubectl get pods -n awx

Operator will create the AWX instance for us.

You can watch the progress with:


This will take some time, so be patient. To quit the watch press CTRL+C

kubectl get pods -l "" -n awx -w

This will return something like:

[root@awx-server vladoportos]# kubectl get pods -l "" -n awx -w
NAME                        READY   STATUS    RESTARTS       AGE
awx-postgres-13-0           1/1     Running   5 (50d ago)    196d
awx-task-7f748db66c-sp2zp   4/4     Running   16 (50d ago)   129d
awx-web-6784b4f88b-tsptm    3/3     Running   12 (50d ago)   129d

Accessing AWX

Now we need to find out the IP and port on which our AWX instance is running. We can do that with:

kubectl get svc -n awx

This will return something like:

[root@awx-server vladoportos]# kubectl get svc -n awx
NAME                                              TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
awx-operator-controller-manager-metrics-service   ClusterIP   <none>        8443/TCP       195d
awx-postgres-13                                   ClusterIP   None            <none>        5432/TCP       195d
awx-service                                       NodePort   <none>        80:30080/TCP   195d

awx-service is there with external IP and port 30080, nice!`

The port might not be 30080, it can be something else. You can however change it, but not to 443 or 80, those are reserved for k3s / traefik.

Change the port

If you want to change the port you can just pathch the service with:

kubectl patch svc awx-service -n awx --type='json' -p='[{"op": "replace", "path": "/spec/ports/0/nodePort", "value": 30080}]'

Get the admin password

Now we also need to get the admin password for AWX. We can do that with:

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}}'

Installations of AWX on k3s is done. You can now access your AWX on the IP and port you found out above. There are more aspects for setting up AWX, but this is out of scope of this installation guide. Check my other guides for more info.

If this guide has been beneficial to you, and you're in the mood to spread some goodwill, how about a coffee for me? Your support means a lot and fuels the creation of more helpful guides and resources for folks like us. Fancy buying me a coffee? Just a click away – your generosity is a huge encouragement. Thank you and enjoy your well-earned break!