Restructured Documentation
This commit is contained in:
@ -0,0 +1,162 @@
|
||||
**Purpose**:
|
||||
Deploying a Rancher RKE2 Cluster-based Ansible AWX Operator server. This can scale to a larger more enterprise environment if needed.
|
||||
|
||||
!!! note Prerequisites
|
||||
This document assumes you are running **Ubuntu Server 22.04** or later with at least 16GB of memory, 8 CPU cores, and 64GB of storage.
|
||||
|
||||
## Deploy Rancher RKE2 Cluster
|
||||
You will need to deploy a [Rancher RKE2 Cluster](https://docs.bunny-lab.io/Containers/Kubernetes/Rancher%20RKE2/Rancher%20RKE2%20Cluster/) on an Ubuntu Server-based virtual machine. After this phase, you can focus on the Ansible AWX-specific deployment. A single ControlPlane node is all you need to set up AWX, additional infrastructure can be added after-the-fact.
|
||||
|
||||
!!! tip
|
||||
If this is a virtual machine, after deploying the RKE2 cluster and validating it functions, now would be the best time to take a checkpoint / snapshot of the VM before moving forward, in case you need to perform rollbacks of the server(s) if you accidentally misconfigure something during deployment.
|
||||
|
||||
## Server Configuration
|
||||
The AWX deployment will consist of 3 yaml files that configure the containers for AWX as well as the NGINX ingress networking-side of things. You will need all of them in the same folder for the deployment to be successful. For the purpose of this example, we will put all of them into a folder located at `/awx`.
|
||||
|
||||
``` sh
|
||||
# Make the deployment folder
|
||||
mkdir -p /awx
|
||||
cd /awx
|
||||
```
|
||||
|
||||
We need to increase filesystem access limits:
|
||||
Temporarily Set the Limits Now:
|
||||
``` sh
|
||||
sudo sysctl fs.inotify.max_user_watches=524288
|
||||
sudo sysctl fs.inotify.max_user_instances=512
|
||||
```
|
||||
|
||||
Permanently Set the Limits for Later:
|
||||
```jsx title="/etc/sysctl.conf"
|
||||
# <End of File>
|
||||
fs.inotify.max_user_watches = 524288
|
||||
fs.inotify.max_user_instances = 512
|
||||
```
|
||||
|
||||
Apply the Settings:
|
||||
``` sh
|
||||
sudo sysctl -p
|
||||
```
|
||||
|
||||
### Create AWX Deployment Donfiguration Files
|
||||
You will need to create these files all in the same directory using the content of the examples below. Be sure to replace values such as the `spec.host=awx.bunny-lab.io` in the `awx-ingress.yml` file to a hostname you can point a DNS server / record to.
|
||||
|
||||
=== "awx.yml"
|
||||
|
||||
```jsx title="/awx/awx.yml"
|
||||
apiVersion: awx.ansible.com/v1beta1
|
||||
kind: AWX
|
||||
metadata:
|
||||
name: awx
|
||||
spec:
|
||||
service_type: ClusterIP
|
||||
```
|
||||
|
||||
=== "ingress.yml"
|
||||
|
||||
```jsx title="/awx/ingress.yml"
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
name: ingress
|
||||
spec:
|
||||
rules:
|
||||
- host: awx.bunny-lab.io
|
||||
http:
|
||||
paths:
|
||||
- pathType: Prefix
|
||||
path: "/"
|
||||
backend:
|
||||
service:
|
||||
name: awx-service
|
||||
port:
|
||||
number: 80
|
||||
```
|
||||
|
||||
=== "kustomization.yml"
|
||||
|
||||
```jsx title="/awx/kustomization.yml"
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
resources:
|
||||
- github.com/ansible/awx-operator/config/default?ref=2.10.0
|
||||
- awx.yml
|
||||
- ingress.yml
|
||||
images:
|
||||
- name: quay.io/ansible/awx-operator
|
||||
newTag: 2.10.0
|
||||
namespace: awx
|
||||
```
|
||||
|
||||
## Ensure the Kubernetes Cluster is Ready
|
||||
Check that the status of the cluster is ready by running the following commands, it should appear similar to the [Rancher RKE2 Example](https://docs.bunny-lab.io/Containers/Kubernetes/Rancher%20RKE2/Rancher%20RKE2%20Cluster/#install-helm-rancher-certmanager-jetstack-rancher-and-longhorn):
|
||||
```
|
||||
export KUBECONFIG=/etc/rancher/rke2/rke2.yaml
|
||||
kubectl get pods --all-namespaces
|
||||
```
|
||||
|
||||
## Deploy AWX using Kustomize
|
||||
Now it is time to tell Kubernetes to read the configuration files using Kustomize (*built-in to newer versions of Kubernetes*) to deploy AWX into the cluster.
|
||||
!!! warning "Be Patient"
|
||||
The AWX deployment process can take a while. Use the commands in the [Troubleshooting](https://docs.bunny-lab.io/Containers/Kubernetes/Rancher%20RKE2/AWX%20Operator/Ansible%20AWX%20Operator/#troubleshooting) section if you want to track the progress after running the commands below.
|
||||
|
||||
If you get an error that looks like the below, re-run the `kubectl apply -k .` command a second time after waiting about 10 seconds. The second time the error should be gone.
|
||||
``` sh
|
||||
error: resource mapping not found for name: "awx" namespace: "awx" from ".": no matches for kind "AWX" in version "awx.ansible.com/v1beta1"
|
||||
ensure CRDs are installed first
|
||||
```
|
||||
|
||||
To check on the progress of the deployment, you can run the following command: `kubectl get pods -n awx`
|
||||
You will know that AWX is ready to be accessed in the next step if the output looks like below:
|
||||
```
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
awx-operator-controller-manager-7b9ccf9d4d-cnwhc 2/2 Running 2 (3m41s ago) 9m41s
|
||||
awx-postgres-13-0 1/1 Running 0 6m12s
|
||||
awx-task-7b5f8cf98c-rhrpd 4/4 Running 0 4m46s
|
||||
awx-web-6dbd7df9f7-kn8k2 3/3 Running 0 93s
|
||||
```
|
||||
|
||||
``` sh
|
||||
cd /awx
|
||||
kubectl apply -k .
|
||||
```
|
||||
|
||||
## Access the AWX WebUI behind Ingress Controller
|
||||
After you have deployed AWX into the cluster, it will not be immediately accessible to the host's network (such as your personal computer) unless you set up a DNS record pointing to it. In the example above, you would have an `A` or `CNAME` DNS record pointing to the internal IP address of the Rancher RKE2 Cluster host.
|
||||
|
||||
The RKE2 Cluster will translate `awx.bunny-lab.io` to the AWX web-service container(s) automatically. SSL certificates are not covered in this documentation, but suffice to say, the can be configured on another reverse proxy such as Traefik or via Cert-Manager / JetStack. The process of setting this up goes outside the scope of this document.
|
||||
|
||||
!!! success "Accessing the AWX WebUI"
|
||||
If you have gotten this far, you should now be able to access AWX via the WebUI and log in.
|
||||
|
||||
- AWX WebUI: https://awx.bunny-lab.io
|
||||
|
||||
You may see a prompt about "AWX is currently upgrading. This page will refresh when complete". Be patient, let it finish. When it's done, it will take you to a login page.
|
||||
AWX will generate its own secure password the first time you set up AWX. Username is `admin`. You can run the following command to retrieve the password:
|
||||
```
|
||||
kubectl get secret awx-admin-password -n awx -o jsonpath="{.data.password}" | base64 --decode ; echo
|
||||
```
|
||||
|
||||
## Change Admin Password
|
||||
You will want to change the admin password straight-away. Use the following navigation structure to find where to change the password:
|
||||
``` mermaid
|
||||
graph LR
|
||||
A[AWX Dashboard] --> B[Access]
|
||||
B --> C[Users]
|
||||
C --> D[admin]
|
||||
D --> E[Edit]
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
You may wish to want to track the deployment process to verify that it is actually doing something. There are a few Kubernetes commands that can assist with this listed below.
|
||||
|
||||
!!! failure "Nested Reverse Proxy Issues"
|
||||
My homelab environment primarily uses a Traefik reverse proxy to handle all communications, but AWX currently has issues running behind Traefik/NGINX, and documentation outlining how to fix this does not exist here yet. For the time being, when you create the DNS record, use an `A` record pointing directly to the IP address of the Virtual Machine running the Rancher / AWX Operator cluster.
|
||||
|
||||
### AWX-Manager Deployment Logs
|
||||
You may want to track the internal logs of the `awx-manager` container which is responsible for the majority of the automated deployment of AWX. You can do so by running the command below.
|
||||
```
|
||||
kubectl logs -n awx awx-operator-controller-manager-6c58d59d97-qj2n2 -c awx-manager
|
||||
```
|
||||
!!! note
|
||||
The `-6c58d59d97-qj2n2` noted at the end of the Kubernetes "Pod" mentioned in the command above is randomized. You will need to change it based on the name shown when running the `kubectl get pods -n awx` command.
|
||||
@ -0,0 +1,68 @@
|
||||
**Purpose**: Once AWX is deployed, you will want to connect Gitea at https://git.bunny-lab.io. The reason for this is so we can pull in our playbooks, inventories, and templates automatically into AWX, making it more stateless overall and more resilient to potential failures of either AWX or the underlying Kubernetes Cluster hosting it.
|
||||
|
||||
## Obtain Gitea Token
|
||||
You already have this documented in Vaultwarden's password notes for awx.bunny-lab.io, but in case it gets lost, go to the [Gitea Token Page](https://git.bunny-lab.io/user/settings/applications) to set up an application token with read-only access for AWX, with a descriptive name.
|
||||
|
||||
## Create Gitea Credentials
|
||||
Before you make move on and make the project, you need to associate the Gitea token with an AWX "Credential". Navigate to **Resources > Credentials > Add**
|
||||
|
||||
| **Field** | **Value** |
|
||||
| :--- | :--- |
|
||||
| Credential Name | `git.bunny-lab.io` |
|
||||
| Description | `Gitea` |
|
||||
| Organization | `Default` *(Click the Magnifying Lens)* |
|
||||
| Credential Type | `Source Control` |
|
||||
| Username | `Gitea Username` *(e.g. `nicole`)* |
|
||||
| Password | `<Gitea Token>` |
|
||||
|
||||
## Create an AWX Project
|
||||
In order to link AWX to Gitea, you have to connect the two of them together with an AWX "Project". Navigate to **Resources > Projects > Add**
|
||||
|
||||
**Project Variables**:
|
||||
|
||||
| **Field** | **Value** |
|
||||
| :--- | :--- |
|
||||
| Project Name | `Bunny-Lab` |
|
||||
| Description | `Homelab Environment` |
|
||||
| Organization | `Default` |
|
||||
| Execution Environment | `AWX EE (latest)` *(Click the Magnifying Lens)* |
|
||||
| Source Control Type | `Git` |
|
||||
|
||||
**Gitea-specific Variables**:
|
||||
|
||||
| **Field** | **Value** |
|
||||
| :--- | :--- |
|
||||
| Source Control URL | `https://git.bunny-lab.io/GitOps/awx.bunny-lab.io.git` |
|
||||
| Source Control Branch/Tag/Commit | `main` |
|
||||
| Source Control Credential | `git.bunny-lab.io` *(Click the Magnifying Lens)* |
|
||||
|
||||
## Add Playbooks
|
||||
AWX automatically imports any playbooks it finds from the project, and makes them available for templates operating within the same project-space. (e.g. "Bunny-Lab"). This means no special configuration is needed for the playbooks.
|
||||
|
||||
## Create an Inventory
|
||||
You will want to associate an inventory with the Gitea project now. Navigate to **Resources > Inventories > Add**
|
||||
|
||||
| **Field** | **Value** |
|
||||
| :--- | :--- |
|
||||
| Inventory Name | `Homelab` |
|
||||
| Description | `Homelab Inventory` |
|
||||
| Organization | `Default` |
|
||||
|
||||
### Add Gitea Inventory Source
|
||||
Now you will want to connect this inventory to the inventory file(s) hosted in the aforementioned Gitea repository. Navigate to **Resources > Inventories > Homelab > Sources > Add**
|
||||
|
||||
| **Field** | **Value** |
|
||||
| :--- | :--- |
|
||||
| Source Name | `git.bunny-lab.io` |
|
||||
| Description | `Gitea` |
|
||||
| Execution Environment | `AWX EE (latest)` *(Click the Magnifying Lens)* |
|
||||
| Source | `Sourced from a Project` |
|
||||
| Project | `Bunny-Lab` |
|
||||
| Inventory File | `inventories/homelab.ini` |
|
||||
|
||||
Check the box at the bottom named "**Update on Launch**". This will pull the latest inventory each time a job is run. It may slightly slow down jobs, but it ensures that everything is updated every time a job is ran.
|
||||
|
||||
|
||||
|
||||
## Webhooks
|
||||
Optionally, set up webhooks in Gitea to trigger inventory updates in AWX upon changes in the repository. This section is not documented yet, but will eventually be documented.
|
||||
@ -0,0 +1,28 @@
|
||||
# WinRM (Kerberos)
|
||||
**Name**: "Kerberos WinRM"
|
||||
|
||||
```jsx title="Input Configuration"
|
||||
fields:
|
||||
- id: username
|
||||
type: string
|
||||
label: Username
|
||||
- id: password
|
||||
type: string
|
||||
label: Password
|
||||
secret: true
|
||||
- id: krb_realm
|
||||
type: string
|
||||
label: Kerberos Realm (Domain)
|
||||
required:
|
||||
- username
|
||||
- password
|
||||
- krb_realm
|
||||
```
|
||||
|
||||
```jsx title="Injector Configuration"
|
||||
extra_vars:
|
||||
ansible_user: '{{ username }}'
|
||||
ansible_password: '{{ password }}'
|
||||
ansible_winrm_transport: kerberos
|
||||
ansible_winrm_kerberos_realm: '{{ krb_realm }}'
|
||||
```
|
||||
@ -0,0 +1,36 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
# AWX Credential Types
|
||||
When interacting with devices via Ansible Playbooks, you need to provide the playbook with credentials to connect to the device with. Examples are domain credentials for Windows devices, and local sudo user credentials for Linux.
|
||||
|
||||
## Windows-based Credentials
|
||||
### NTLM
|
||||
NTLM-based authentication is not exactly the most secure method of remotely running playbooks on Windows devices, but it is still encrypted using SSL certificates created by the device itself when provisioned correctly to enable WinRM functionality.
|
||||
```jsx title="(NTLM) nicole.rappe@MOONGATE.LOCAL"
|
||||
Credential Type: Machine
|
||||
Username: nicole.rappe@MOONGATE.LOCAL
|
||||
Password: <Encrypted>
|
||||
Privilege Escalation Method: runas
|
||||
Privilege Escalation Username: nicole.rappe@MOONGATE.LOCAL
|
||||
```
|
||||
### Kerberos
|
||||
Kerberos-based authentication is generally considered the most secure method of authentication with Windows devices, but can be trickier to set up since it requires additional setup inside of AWX in the cluster for it to function properly. At this time, there is no working Kerberos documentation.
|
||||
```jsx title="(Kerberos WinRM) nicole.rappe"
|
||||
Credential Type: Kerberos WinRM
|
||||
Username: nicole.rappe
|
||||
Password: <Encrypted>
|
||||
Kerberos Realm (Domain): MOONGATE.LOCAL
|
||||
```
|
||||
## Linux-based Credentials
|
||||
```jsx title="(LINUX) nicole"
|
||||
Credential Type: Machine
|
||||
Username: nicole
|
||||
Password: <Encrypted>
|
||||
Privilege Escalation Method: sudo
|
||||
Privilege Escalation Username: root
|
||||
```
|
||||
|
||||
:::note
|
||||
`WinRM / Kerberos` based credentials do not currently work as-expected. At this time, use either `Linux` or `NTLM` based credentials.
|
||||
:::
|
||||
@ -0,0 +1,39 @@
|
||||
# Host Inventories
|
||||
When you are deploying playbooks, you target hosts that exist in "Inventories". These inventories consist of a list of hosts and their corresponding IP addresses, as well as any host-specific variables that may be necessary to declare to run the playbook.
|
||||
|
||||
```jsx title="(NTLM) MOON-HOST-01"
|
||||
Name: (NTLM) MOON-HOST-01
|
||||
Host(s): MOON-HOST-01 @ 192.168.3.4
|
||||
|
||||
Variables:
|
||||
---
|
||||
ansible_connection: winrm
|
||||
ansible_winrm_kerberos_delegation: false
|
||||
ansible_port: 5986
|
||||
ansible_winrm_transport: ntlm
|
||||
ansible_winrm_server_cert_validation: ignore
|
||||
```
|
||||
|
||||
```jsx title="(NTLM) CyberStrawberry - Windows Hosts"
|
||||
Name: (NTLM) CyberStrawberry - Windows Hosts
|
||||
Host(s): MOON-HOST-01 @ 192.168.3.4
|
||||
Host(s): MOON-HOST-02 @ 192.168.3.5
|
||||
|
||||
Variables:
|
||||
---
|
||||
ansible_connection: winrm
|
||||
ansible_winrm_kerberos_delegation: false
|
||||
ansible_port: 5986
|
||||
ansible_winrm_transport: ntlm
|
||||
ansible_winrm_server_cert_validation: ignore
|
||||
```
|
||||
|
||||
```jsx title="(LINUX) Unsorted Devices"
|
||||
Name: (LINUX) Unsorted Devices
|
||||
Host(s): CLSTR-COMPUTE-01 @ 192.168.3.50
|
||||
Host(s): CLSTR-COMPUTE-02 @ 192.168.3.51
|
||||
|
||||
Variables:
|
||||
---
|
||||
None
|
||||
```
|
||||
@ -0,0 +1,16 @@
|
||||
# AWX Projects
|
||||
When you want to run playbooks on host devices in your inventory files, you need to host the playbooks in a "Project". Projects can be as simple as a connection to Gitea/Github to store playbooks in a repository.
|
||||
|
||||
```jsx title="Ansible Playbooks (Gitea)"
|
||||
Name: Ansible Playbooks (Gitea)
|
||||
Source Control Type: Git
|
||||
Source Control URL: https://git.cyberstrawberry.net/nicole.rappe/ansible.git
|
||||
Source Control Credential: CyberStrawberry Gitea
|
||||
```
|
||||
|
||||
```jsx title="Resources > Credentials > CyberStrawberry Gitea"
|
||||
Name: CyberStrawberry Gitea
|
||||
Credential Type: Source Control
|
||||
Username: nicole.rappe
|
||||
Password: <Encrypted> #If you use MFA on Gitea/Github, use an App Password instead for the project.
|
||||
```
|
||||
@ -0,0 +1,21 @@
|
||||
# Templates
|
||||
Templates are basically pre-constructed groups of devices, playbooks, and credentials that perform a specific kind of task against a predefined group of hosts or device inventory.
|
||||
|
||||
```jsx title="Deploy Hyper-V VM"
|
||||
Name: Deploy Hyper-V VM
|
||||
Inventory: (NTLM) MOON-HOST-01
|
||||
Playbook: playbooks/Windows/Hyper-V/Deploy-VM.yml
|
||||
Credentials: (NTLM) nicole.rappe@MOONGATE.local
|
||||
Execution Environment: AWX EE (latest)
|
||||
Project: Ansible Playbooks (Gitea)
|
||||
|
||||
Variables:
|
||||
---
|
||||
random_number: "{{ lookup('password', '/dev/null chars=digits length=4') }}"
|
||||
random_letters: "{{ lookup('password', '/dev/null chars=ascii_uppercase length=4') }}"
|
||||
vm_name: "NEXUS-TEST-{{ random_number }}{{ random_letters }}"
|
||||
vm_memory: "8589934592" #Measured in Bytes (e.g. 8GB)
|
||||
vm_storage: "68719476736" #Measured in Bytes (e.g. 64GB)
|
||||
iso_path: "C:\\ubuntu-22.04-live-server-amd64.iso"
|
||||
vm_folder: "C:\\Virtual Machines\\{{ vm_name_fact }}"
|
||||
```
|
||||
BIN
Docker & Kubernetes/Servers/AWX/AWX Operator/awx.png
Normal file
BIN
Docker & Kubernetes/Servers/AWX/AWX Operator/awx.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 122 KiB |
Reference in New Issue
Block a user