expand/awx-on-k3s
1
0
Fork 0
mirror of https://github.com/Expand-sys/awx-on-k3s synced 2025-12-16 05:52:15 +11:00
Code Issues Projects Releases Packages Wiki Activity Actions
awx-on-k3s/README.md
kurokobo 435a171af1 fix: add note for restoration
2021-09-05 08:46:39 -04:00

382 lines
13 KiB
Markdown
Raw Blame History

<!-- omit in toc -->
# AWX on Single Node K3s
An example implementation of AWX on single node K3s using AWX Operator, with easy-to-use simplified configuration with ownership of data and passwords.
- Accesible over HTTPS from remote host
- All data will be stored under `/data`
- Fixed (configurable) passwords for AWX and PostgreSQL
- Fixed (configurable) versions of AWX and PostgreSQL
<!-- omit in toc -->
## Table of Contents
- [Environment](#environment)
- [References](#references)
- [Procedure](#procedure)
- [Prepare CentOS 8 host](#prepare-centos-8-host)
- [Install K3s](#install-k3s)
- [Install AWX Operator](#install-awx-operator)
- [Prepare required files](#prepare-required-files)
- [Deploy AWX](#deploy-awx)
- [Backing up and Restoring using AWX Operator](#backing-up-and-restoring-using-awx-operator)
- [Backing up using AWX Operator](#backing-up-using-awx-operator)
- [Prepare for Backup](#prepare-for-backup)
- [Invoke Manual Backup](#invoke-manual-backup)
- [Restoring using AWX Operator](#restoring-using-awx-operator)
- [Prepare for Restore](#prepare-for-restore)
- [Invoke Manual Restore](#invoke-manual-restore)
- [Additional Guides](#additional-guides)
## Environment
- Tested on:
- CentOS 8 (Minimal)
- Products that will be deployed:
- AWX Operator 0.13.0
- AWX 19.3.0
- PostgreSQL 12
## References
- [K3s - Lightweight Kubernetes](https://rancher.com/docs/k3s/latest/en/)
- [INSTALL.md on ansible/awx](https://github.com/ansible/awx/blob/19.3.0/INSTALL.md) @19.3.0
- [README.md on ansible/awx-operator](https://github.com/ansible/awx-operator/blob/0.13.0/README.md) @0.13.0
## Procedure
### Prepare CentOS 8 host
Disable Firewalld. This is [recommended by K3s](https://rancher.com/docs/k3s/latest/en/advanced/#additional-preparation-for-red-hat-centos-enterprise-linux).
```bash
sudo systemctl disable firewalld --now
```
### Install K3s
Install K3s with `--write-kubeconfig-mode 644` to make config file (`/etc/rancher/k3s/k3s.yaml`) readable by non-root user.
```bash
curl -sfL https://get.k3s.io | sh -s - --write-kubeconfig-mode 644
```
### Install AWX Operator
Install specified version of AWX Operator.
> **⚠️ NOTE ⚠️**
> An issue has been reported ([ansible/awx#10883](https://github.com/ansible/awx/issues/10883)) about LDAP authentication in AWX `19.3.0` which is mapped to AWX Operator `0.13.0`.
> Use `0.12.0` (or a future release version with the problem fixed) instead of `0.13.0` if you plan to use LDAP authentication.
```bash
kubectl apply -f https://raw.githubusercontent.com/ansible/awx-operator/0.13.0/deploy/awx-operator.yaml
```
### Prepare required files
Clone this repository and change directory.
```bash
git clone https://github.com/kurokobo/awx-on-k3s.git
cd awx-on-k3s
```
Generate a Self-Signed Certificate. Note that IP address can't be specified.
```bash
AWX_HOST="awx.example.com"
openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -out ./base/tls.crt -keyout ./base/tls.key -subj "/CN=${AWX_HOST}/O=${AWX_HOST}" -addext "subjectAltName = DNS:${AWX_HOST}"
```
Modify `hostname` in `base/awx.yaml`.
```yaml
...
spec:
ingress_type: ingress
ingress_tls_secret: awx-secret-tls
hostname: awx.example.com 👈👈👈
...
```
Modify two `password`s in `base/kustomization.yaml`.
```yaml
...
- name: awx-postgres-configuration
type: Opaque
literals:
- host=awx-postgres
- port=5432
- database=awx
- username=awx
- password=Ansible123! 👈👈👈
- type=managed
- name: awx-admin-password
type: Opaque
literals:
- password=Ansible123! 👈👈👈
...
```
Prepare directories for Persistent Volumes defined in `base/pv.yaml`.
```bash
sudo mkdir -p /data/postgres
sudo mkdir -p /data/projects
sudo chown 1000:0 /data/projects
```
### Deploy AWX
Deploy AWX, this takes few minutes to complete.
```bash
kubectl apply -k base
```
Once this completed, the logs of `deployment/awx-operator` end with:
```txt
$ kubectl logs -f deployment/awx-operator
...
--------------------------- Ansible Task Status Event StdOut -----------------
PLAY RECAP *********************************************************************
localhost : ok=54 changed=0 unreachable=0 failed=0 skipped=37 rescued=0 ignored=0
-------------------------------------------------------------------------------
```
Required objects has been deployed in `awx` namespace.
```bash
$ kubectl -n awx get awx,all,ingress,secrets
NAME AGE
awx.awx.ansible.com/awx 4m19s
NAME READY STATUS RESTARTS AGE
pod/awx-postgres-0 1/1 Running 0 4m27s
pod/awx-59ff55b5b-qdk9p 4/4 Running 0 4m19s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/awx-postgres ClusterIP None <none> 5432/TCP 4m27s
service/awx-service ClusterIP 10.43.209.222 <none> 80/TCP 4m21s
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/awx 1/1 1 1 4m19s
NAME DESIRED CURRENT READY AGE
replicaset.apps/awx-59ff55b5b 1 1 1 4m19s
NAME READY AGE
statefulset.apps/awx-postgres 1/1 7m27s
NAME CLASS HOSTS ADDRESS PORTS AGE
ingress.networking.k8s.io/awx-ingress <none> awx.example.com 192.168.0.100 80, 443 4m20s
NAME TYPE DATA AGE
secret/default-token-lxj9h kubernetes.io/service-account-token 3 5m36s
secret/awx-admin-password Opaque 1 4m45s
secret/awx-broadcast-websocket Opaque 1 4m45s
secret/awx-secret-tls kubernetes.io/tls 2 4m45s
secret/awx-postgres-configuration Opaque 6 4m45s
secret/awx-secret-key Opaque 1 4m45s
secret/awx-app-credentials Opaque 3 4m23s
secret/awx-token-6s7rj kubernetes.io/service-account-token 3 4m22s
```
Now your AWX is available at `https://awx.example.com/` or the hostname you specified.
At this point, however, AWX can be accessed via HTTP as well as HTTPS. If you want to redirect HTTP to HTTPS, see [the additional tips](tips/https-redirection.md).
## Backing up and Restoring using AWX Operator
The AWX Operator `0.10.0` or later has the ability to backup and restore AWX in easy way.
### Backing up using AWX Operator
#### Prepare for Backup
Prepare directories for Persistent Volumes to store backup files that defined in `backup/pv.yaml`.
```bash
sudo mkdir -p /data/backup
```
Then deploy Persistent Volume and Persistent Volume Claim.
```bash
kubectl apply -k backup
```
#### Invoke Manual Backup
Modify the name of the AWXBackup object in `backup/awxbackup.yaml`.
```yaml
...
kind: AWXBackup
metadata:
name: awxbackup-2021-06-06 👈👈👈
namespace: awx
...
```
Then invoke backup by applying this manifest file.
```bash
kubectl apply -f backup/awxbackup.yaml
```
Once this completed, the logs of `deployment/awx-operator` end with:
```txt
$ kubectl logs -f deployment/awx-operator
--------------------------- Ansible Task Status Event StdOut -----------------
PLAY RECAP *********************************************************************
localhost : ok=4 changed=0 unreachable=0 failed=0 skipped=7 rescued=0 ignored=0
-------------------------------------------------------------------------------
```
This will create AWXBackup object in the namespace and also create backup files in the Persistent Volume. In this example those files are available at `/data/backup`.
```bash
$ kubectl -n awx get awxbackup
NAME AGE
awxbackup-2021-06-06 6m47s
```
```bash
$ ls -l /data/backup/
total 0
drwxr-xr-x. 2 root root 59 Jun 5 06:51 tower-openshift-backup-2021-06-06-10:51:49
$ ls -l /data/backup/tower-openshift-backup-2021-06-06-10\:51\:49/
total 736
-rw-r--r--. 1 root root 749 Jun 6 06:51 awx_object
-rw-r--r--. 1 root root 482 Jun 6 06:51 secrets.yml
-rw-------. 1 systemd-coredump root 745302 Jun 6 06:51 tower.db
```
Note that if you are using AWX Operator `0.12.0` or earlier, the contents of the Secret that passed through `ingress_tls_secret` parameter will not be included in this backup files. If necessary, get a dump of this Secret, or keep original certificate file and key file. In `0.13.0` or later, this secret is included in the backup file.
```bash
kubectl get secret awx-secret-tls -n awx -o yaml > awx-secret-tls.yaml
```
### Restoring using AWX Operator
To perfom restoration, you need to have AWX Operator running on Kubernetes. If you are planning to restore to a new environment, first prepare Kubernetes and AWX Operator by referring to the instructions on this page.
It is strongly recommended that the version of AWX Operator is the same as the version when the backup was taken. This is because the structure of the backup files differs between versions and may not be compatible. If you have upgraded AWX Operator after taking the backup, it is recommended to downgrade it for the restore.
#### Prepare for Restore
If your PV, PVC, and Secret still exist, no preparation is required.
If you are restoring the entire AWX to a new environment, create the PVs and PVCs first to be restored.
```bash
sudo mkdir -p /data/postgres
sudo mkdir -p /data/projects
sudo chown 1000:0 /data/projects
```
Then deploy Persistent Volume and Persistent Volume Claim.
```bash
kubectl apply -k restore
```
#### Invoke Manual Restore
Modify the name of the AWXRestore object in `restore/awxrestore.yaml`.
```yaml
...
kind: AWXRestore
metadata:
name: awxrestore-2021-06-06 👈👈👈
namespace: awx
...
```
If you want to restore from AWXBackup object, specify its name in `restore/awxrestore.yaml`.
```yaml
...
# Parameters to restore from AWXBackup object
backup_pvc_namespace: awx
backup_name: awxbackup-2021-06-06 👈👈👈
...
```
If the AWXBackup object no longer exists, place the backup files and specify the name of the PVC and directory in `restore/awxrestore.yaml`.
```yaml
...
# Parameters to restore from existing files on PVC (without AWXBackup object)
backup_pvc_namespace: awx
backup_pvc: awx-backup-claim 👈👈👈
backup_dir: /backups/tower-openshift-backup-2021-06-06-10:51:49 👈👈👈
...
```
Then invoke restore by applying this manifest file.
```bash
kubectl apply -f restore/awxrestore.yaml
```
Once this completed, the logs of `deployment/awx-operator` end with:
```txt
$ kubectl logs -f deployment/awx-operator
--------------------------- Ansible Task Status Event StdOut -----------------
PLAY RECAP *********************************************************************
localhost : ok=56 changed=0 unreachable=0 failed=0 skipped=35 rescued=0 ignored=0
-------------------------------------------------------------------------------
```
This will create AWXRestore object in the namespace, and now your AWX is restored.
```bash
$ kubectl -n awx get awxrestore
NAME AGE
awxrestore-2021-06-06 137m
```
Note that if you are using AWX Operator `0.12.0` or earlier, the Secret for TLS should be manually restored (or create newly using original certificate and key file). This is not required for `0.13.0` or later.
```bash
kubectl apply -f awx-secret-tls.yaml
```
## Additional Guides
- [📁 **Deploy Private Git Repository on Kubernetes**](git)
- To use AWX with SCM, this repository includes the manifests to deploy [Gitea](https://gitea.io/en-us/).
- See [📝`git/README.md`](git) for instructions.
- [📁 **Deploy Private Container Registry on Kubernetes**](registry)
- To use Execution Environments in AWX (AWX-EE), we have to push the container image built with `ansible-builder` to the container registry.
- If we don't want to push our container images to Docker Hub or other cloud services, we can deploy a private container registry on K3s.
- See [📝`registry/README.md`](registry) for instructions.
- [📁 **Deploy Private Galaxy NG on Docker or Kubernetes** (Experimental)](galaxy)
- Deploy our own Galaxy NG instance.
- **Note that the containerized implementation of Galaxy NG is not supported at this time.**
- **All information on the page is for development, testing and study purposes only.**
- See [📝`galaxy/README.md`](galaxy) for instructions.
- [📁 **Use Ansible Builder**](builder)
- Use Ansible Builder to build our own Execution Environment.
- See [📝`builder/README.md`](builder) for instructions.
- [📁 **Use Ansible Runner**](runner)
- Use Ansible Runner to run playbook using Execution Environment.
- See [📝`runner/README.md`](runner) for instructions.
- [📁 **Use Customized Pod Specification for your Execution Environment**](containergroup)
- We can customize the specification of the Pod of the Execution Environment using **Container Group**.
- See [📝`containergroup/README.md`](containergroup) for instructions.
- [📁 **Tips**](tips)
- [📝Expose `/etc/hosts` to Pods on K3s](tips/expose-hosts.md)
- [📝Redirect HTTP to HTTPS](tips/https-redirection.md)
- [📝Uninstall deployed resouces](tips/uninstall.md)
Reference in a new issue View git blame Copy permalink