expand/awx-on-k3s
1
0
Fork 0
mirror of https://github.com/Expand-sys/awx-on-k3s synced 2025-12-15 21:42:15 +11:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull request #313 from neofright/readme-edits

Browse source 
Readme edits
This commit is contained in:
kurokobo 2024-03-14 13:24:13 +09:00 committed by GitHub
commit 50a9fc62a0
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 46 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
README.md
View file

@ -69,7 +69,7 @@ sudo systemctl disable nm-cloud-setup.service nm-cloud-setup.timer
sudo reboot
```
Install required packages to deploy AWX Operator and AWX.
Install the required packages to deploy AWX Operator and AWX.
```bash
sudo dnf install -y git curl
@ -77,7 +77,7 @@ sudo dnf install -y git curl
### Install K3s
Install specific version of K3s with `--write-kubeconfig-mode 644` to make config file (`/etc/rancher/k3s/k3s.yaml`) readable by non-root user.
Install a specific version of K3s with `--write-kubeconfig-mode 644` to make the config file (`/etc/rancher/k3s/k3s.yaml`) readable by non-root users.
```bash
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.28.6+k3s2 sh -s - --write-kubeconfig-mode 644
@ -86,11 +86,11 @@ curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.28.6+k3s2 sh -s - --write-
### Install AWX Operator
> [!WARNING]
> If you are planning that creating backup of your AWX instance using AWX Operator by referring [the backup guide](backup), AWX Operator 2.12.2 is not recommended due to [a known issue for backup](https://github.com/ansible/awx-operator/issues/1734). Use the older version of AWX Operator like [2.12.1](https://github.com/kurokobo/awx-on-k3s/tree/2.12.1) instead.
> If you are planning that creating backup of your AWX instance using AWX Operator by referring to [the backup guide](backup), AWX Operator 2.12.2 is not recommended due to [a known issue for backup](https://github.com/ansible/awx-operator/issues/1734). Use an older version of AWX Operator like [2.12.1](https://github.com/kurokobo/awx-on-k3s/tree/2.12.1) instead.
Clone this repository and change directory.
If you want to use files suitable for the specific version of AWX Operator, [refer tags in this repository](https://github.com/kurokobo/awx-on-k3s/tags) and specify desired tag in `git checkout`. Especially for `0.13.0` or earlier version of AWX Operator, refer to [📝Tips: Deploy older version of AWX Operator](tips/deploy-older-operator.md).
If you want to use files suitable for a specific version of AWX Operator, [refer to tags in this repository](https://github.com/kurokobo/awx-on-k3s/tags) and specify the desired tag in `git checkout`. Especially for `0.13.0` or earlier versions of AWX Operator, refer to [📝Tips: Deploy older version of AWX Operator](tips/deploy-older-operator.md).
```bash
cd ~
@ -124,7 +124,7 @@ replicaset.apps/awx-operator-controller-manager-68d787cfbd 1 1
### Prepare required files to deploy AWX
Generate a Self-Signed certificate. Note that IP address can't be specified. If you want to use a certificate from public ACME CA such as Let's Encrypt or ZeroSSL instead of Self-Signed certificate, follow the guide on [📁 **Use SSL Certificate from Public ACME CA**](acme) first and come back to this step when done.
Generate a Self-Signed certificate. Note that an IP address can't be specified. If you want to use a certificate from a public ACME CA such as Let's Encrypt or ZeroSSL instead of a Self-Signed certificate, follow the guide on [📁 **Use SSL Certificate from Public ACME CA**](acme) first and come back to this step when done.
```bash
AWX_HOST="awx.example.com"
@ -144,7 +144,7 @@ spec:
...
```
Modify two `password`s in `base/kustomization.yaml`. Note that the `password` under `awx-postgres-configuration` should not contain single or double quotes (`'`, `"`) or backslashes (`\`) to avoid any issues during deployment, backup or restoration.
Modify the two `password` entries in `base/kustomization.yaml`. Note that the `password` under `awx-postgres-configuration` should not contain single or double quotes (`'`, `"`) or backslashes (`\`) to avoid any issues during deployment, backup or restoration.
```yaml
...
@ -188,7 +188,7 @@ To monitor the progress of the deployment, check the logs of `deployments/awx-op
kubectl -n awx logs -f deployments/awx-operator-controller-manager
```
When the deployment completes successfully, the logs end with:
If the deployment completes successfully, the logs end with:
```txt
$ kubectl -n awx logs -f deployments/awx-operator-controller-manager
@ -198,7 +198,7 @@ PLAY RECAP *********************************************************************
localhost : ok=85 changed=1 unreachable=0 failed=0 skipped=78 rescued=0 ignored=1
```
Required objects has been deployed next to AWX Operator in `awx` namespace.
The required objects should now have been deployed next to AWX Operator in the `awx` namespace.
```bash
$ kubectl -n awx get awx,all,ingress,secrets
@ -246,7 +246,7 @@ secret/awx-receptor-work-signing Opaque 2 5m33s
Now your AWX is available at `https://awx.example.com/` or the hostname you specified.
Note that you have to access via hostname that you specified in `base/awx.yaml`, instead of IP address, since this guide uses Ingress. So you should configure your DNS or `hosts` file on your client where the browser is running.
Note that you have to access via the hostname that you specified in `base/awx.yaml`, instead of by IP address, since this guide uses Ingress. So you should configure your DNS or `hosts` file on your client where the browser is running.
At this point, AWX can be accessed via HTTP as well as HTTPS. If you want to force users to use HTTPS, see [📝Tips: Enable HTTP Strict Transport Security (HSTS)](tips/enable-hsts.md).

28
backup/ansible/README.md
View file

@ -38,7 +38,7 @@ An example simple playbook for Ansible is also provided in this repository. This
<!-- markdownlint-enable MD033 -->
Note that this playbook enables `clean_backup_on_delete` by default that only works with AWX Operator `0.24.0` and later. This option makes that your actual backup data in your PVC is deleted at the same time the AWXBackup resource is deleted. You can disable this feature by explicitly specifying `clean_backup_on_delete: false`. Refer [the official documentation](https://github.com/ansible/awx-operator/tree/devel/roles/backup) for detail.
Note that this playbook enables `clean_backup_on_delete` by default that only works with AWX Operator `0.24.0` and later. This option makes it so that your actual backup data in your PVC is deleted at the same time the AWXBackup resource is deleted. You can disable this feature by explicitly specifying `clean_backup_on_delete: false`. Refer to [the official documentation](https://github.com/ansible/awx-operator/tree/devel/roles/backup) for detail.
## Preparation
@ -59,18 +59,18 @@ rolebinding.rbac.authorization.k8s.io/awx-backup created
Since you have complete control over `spec` of `AWXBackup` via `awxbackup_spec` variables, whether or not this step is required depends on your environment. Check [the official documentation](https://github.com/ansible/awx-operator/tree/devel/roles/backup) and prepare as needed.
If your AWX was deployed by referring [the main guide on this repository](../../README.md), preparing backup storage by following [the basic backup guide](../README.md#prepare-for-backup) is good starting point.
If your AWX was deployed by referencing [the main guide on this repository](../../README.md), preparing backup storage by following [the basic backup guide](../README.md#prepare-for-backup) is a good starting point.
## Use with Ansible
Export required environment variables.
Export the required environment variables.
```bash
export K8S_AUTH_HOST="https://<Your K3s Host>:6443/"
export K8S_AUTH_VERIFY_SSL=no
```
Obtain and export the API Token which required to authenticate the Kubernetes API.
Obtain and export the API Token which is required to authenticate to the Kubernetes API.
```bash
# For Kubernetes 1.24 or later:
@ -93,9 +93,9 @@ ansible-playbook project/backup.yml \
## Use with Ansible Runner
Refer [the guide for Ansible Runner](../../runner) for the basic usage.
Refer to [the guide for Ansible Runner](../../runner) for the basic usage.
Modify following files as needed. Note that the EE `quay.io/ansible/awx-ee:latest` contains required modules and collections by default.
Modify the following files as needed. Note that the EE `quay.io/ansible/awx-ee:latest` contains required modules and collections by default.
- [📝`env/settings`](env/settings): Configure your Execution Environment
- [📝`env/envvars`](env/envvars): Specify your K3s host and API Token
@ -113,10 +113,10 @@ This playbook can also be run through Job Templates on AWX. Of course Schedules
This is the way to make the backup of the AWX itself where the Job Template for the backup is configured.
In this case, the PostgreSQL will be dumped while the job is running, so complete logs of the job itself is not part of the backup. Therefore, after restoration, **the last backup job will be shown as failed** since the AWX can't determine the result of the job, but this can be safely ignored.
In this case, the PostgreSQL db will be dumped while the job is running, so complete logs of the job itself is not a part of the backup. Therefore, after restoration, **the last backup job will be shown as failed** the AWX can't determine the result of the job, but this can be safely ignored.
1. Add new Container Group to make the API token usable inside the EE.
- Enable `Customize pod specification` and put following YAML string. `serviceAccountName` and `automountServiceAccountToken` are important to make the API token usable inside the EE.
1. Add a new Container Group to make the API token usable inside the EE.
- Enable `Customize pod specification` and put the following YAML string. `serviceAccountName` and `automountServiceAccountToken` are important to make the API token usable inside the EE.
```yaml
apiVersion: v1
@ -139,16 +139,16 @@ In this case, the PostgreSQL will be dumped while the job is running, so complet
memory: 100Mi
```
2. Add new Project including the playbook.
2. Add a new Project including the playbook.
- You can specify this repository (`https://github.com/kurokobo/awx-on-k3s.git`) directly, but use with caution. The playbook in this repository is subject to change without notice. You can use [Tag](https://github.com/kurokobo/awx-on-k3s/tags) or [Commit](https://github.com/kurokobo/awx-on-k3s/commits/main) to fix the version to be used.
3. Add new Job Template which use the playbook.
- Select appropriate `Inventory`. The bundled `Demo Inventory` is enough to use. If you specify your own inventory, ensure `localhost` is defined in the inventory and following variables are enabled for `localhost`.
3. Add a new Job Template which uses the playbook.
- Select the appropriate `Inventory`. The bundled `Demo Inventory` is enough to use. If you specify your own inventory, ensure `localhost` is defined in the inventory and the following variables are enabled for `localhost`.
- `ansible_connection: local`
- `ansible_python_interpreter: '{{ ansible_playbook_python }}'`
- Select appropriate `Execution Environment`. The default `AWX EE (latest)` (`quay.io/ansible/awx-ee:latest`) contains required collections and modules by default, so it's good for the first choice.
- Select the appropriate `Execution Environment`. The default `AWX EE (latest)` (`quay.io/ansible/awx-ee:latest`) contains required collections and modules by default, so it's good for the first choice.
- Select your `backup.yml` as `Playbook`.
- Specify `Variables` as needed.
- Select your Container Group created in the above step as `Instance Group`.
4. (Optional) Add new Schedules for periodic backup.
If you want to make the backup of another AWX on different namespace of different cluster, create new Credential with `OpenShift or Kubernetes API Bearer Token` type instead of Container Group and then specify the Credential in the Job Template. To obtain the API token, refer [_"Use with Ansible"_](#use-with-ansible) section.
If you want to make the backup of another AWX on a different namespace of different cluster, create a new Credential with `OpenShift or Kubernetes API Bearer Token` type instead of Container Group and then specify the Credential in the Job Template. To obtain the API token, refer to the [_"Use with Ansible"_](#use-with-ansible) section.

46
builder/README.md
View file

@ -23,24 +23,24 @@ This page mainly shows you how to build and use your own custom Execution Enviro
## Introduction
When the Job Template launched on AWX, the playbook runs on the Execution Environment (EE), which is a containerized environment completely isolated from your K3s host.
When the Job Template is launched on AWX, the playbook runs on the Execution Environment (EE), which is a containerized environment completely isolated from your K3s host.
- [What's new in Ansible Automation Platform 2: automation execution environments](https://www.ansible.com/blog/whats-new-in-ansible-automation-platform-2-automation-execution-environments)
The default EE, [quay.io/ansible/awx-ee:latest](https://quay.io/repository/ansible/awx-ee), has some typical collections, Pip modules, and RPM packages by default, but sometimes your playbooks require additional (non-default) collections, modules or packages.
In such cases, you need to add Ansible collections, Python packages, and RPM packages to EE. There are two ways you can choose to achieve this.
In such cases, you need to add Ansible collections, Python packages, and RPM packages to the EE. There are two ways you can choose to achieve this.
1. **Build and use your own Execution Environment**
- This method is used when additional Pip or RPM packages are required in addition to the Ansible collection.
- Follow whole of this page to build and use custom EE.
- Follow the whole of this page to build and use a custom EE.
2. **Place `collections/requirements.yml` in your project**
- This is useful if you simply need additional Ansible collections only, and no additional Pip or RPM packages are required. However, this method cannot be used if your project type on AWX is Manual.
- See [_Use Ansible collections without custom EE_](#use-ansible-collections-without-custom-ee) at the bottom of this page for instructions.
## Build your own custom EE
To build custom EE, there is a tool called Ansible Builder. You can build your own custom EE with any Ansible collections, Python packages, and RPM packages added.
To build a custom EE, there is a tool called Ansible Builder. You can build your own custom EE with any Ansible collections, Python packages, and RPM packages added.
- [ansible/ansible-builder](https://github.com/ansible/ansible-builder)
- [Introduction to Ansible Builder — ansible-builder documentation](https://ansible.readthedocs.io/projects/builder/en/latest/)
@ -70,33 +70,33 @@ python3 -m pip install ansible-builder
### Prepare Required Files
At least, the file `execution-environment.yml` is required to build EE.
At least, the file `execution-environment.yml` is required to build an EE.
This repository contains [`execution-environment.yml` as a minimal ready-to-use example](execution-environment.yml). This file is made to achieve following requirements.
This repository contains [`execution-environment.yml`](execution-environment.yml) as a minimal ready-to-use example. This file is made to achieve the following requirements.
- Use `quay.io/centos/centos:stream9-minimal` as the base image
- Use Python `3.11` as Python interpreter
- Use Ansible `2.15.*` and Ansible Runner `2.3.*` to run playbooks on EE
- Add RPM Packages that listed in [`dependencies/bindep.txt`](dependencies/bindep.txt) for basic remote connection and debugging
- Add Python packages that listed in [`dependencies/requirements.txt`](ependencies/requirements.txt)
- Add Ansible collections that listed in [`dependencies/requirements.yml`](dependencies/requirements.yml)
- Customize configuration for `ansible-galaxy` (`additional_build_files` and `additional_build_steps`)
- Add customized `ansible.cfg` to the context (`additional_build_files`)
- Place customized file as `~/.ansible.cfg` for the stage that `ansible-galaxy` is invoked (`prepend_galaxy` under `additional_build_steps`)
- Use Python `3.11` as the Python interpreter
- Use Ansible `2.15.*` and Ansible Runner `2.3.*` to run playbooks on the EE
- Add RPM Packages that are listed in [`dependencies/bindep.txt`](dependencies/bindep.txt) for basic remote connection and debugging
- Add Python packages that are listed in [`dependencies/requirements.txt`](ependencies/requirements.txt)
- Add Ansible collections that are listed in [`dependencies/requirements.yml`](dependencies/requirements.yml)
- Customize the configuration for `ansible-galaxy` (`additional_build_files` and `additional_build_steps`)
- Add a customized `ansible.cfg` to the context (`additional_build_files`)
- Place the customized file as `~/.ansible.cfg` for the stage that `ansible-galaxy` is invoked (`prepend_galaxy` under `additional_build_steps`)
- Run additional commands during build steps (`additional_build_steps`)
- To allow the hard-coded interpreter name (`python3`) passed by AWX, `alternatives` command is appended under `append_base` to make the binary `/usr/bin/python3.11` executable as command `python3`
- To allow the hard-coded interpreter name (`python3`) to be passed by AWX, the `alternatives` command is appended under `append_base` to make the binary `/usr/bin/python3.11` executable as command `python3`
Note that since this example uses `*-minimal` image as the base image and added only few packages for SSH connection and debugging, there should be still missing packages and modules for some modules and collections.
Note that since this example uses the `*-minimal` image as the base image and added only a few packages for SSH connection and debugging, there should still be missing packages and modules for some modules and collections.
You can review and modify [`execution-environment.yml`](execution-environment.yml) and any files referenced from this file to suit your requirements.
The syntax of `requirements.yml` is [the same as for Ansible Galaxy](https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#install-multiple-collections-with-a-requirements-file). The syntax of `requirements.txt` is [the same as for Pip](https://pip.pypa.io/en/stable/reference/requirements-file-format/), and `bindep.txt` is [for Bindep](https://docs.opendev.org/opendev/bindep/latest/readme.html).
Other customization is possible besides this. Refer to [the official Ansible Builder documentation](https://ansible-builder.readthedocs.io/en/stable/) for details.
Other customizations are possible besides this. Refer to [the official Ansible Builder documentation](https://ansible-builder.readthedocs.io/en/stable/) for details.
### Build EE
Once your files are ready, run `ansible-builder build` command to build EE as a container image according to the definition in `execution-environment.yml`. Specify a tag (`--tag`) to suit your requirements.
Once your files are ready, run `ansible-builder build` command to build an EE as a container image according to the definition in `execution-environment.yml`. Specify a tag (`--tag`) to suit your requirements.
```bash
ansible-builder build --tag registry.example.com/ansible/ee:2.15-custom --container-runtime docker --verbosity 3
@ -165,7 +165,7 @@ Then you can specify `registry.example.com/ansible/ee:2.15-custom` as your own c
#### Use EE in AWX without container registry
The EEs in AWX are just Pods on Kubernetes. When executing a Job Template in AWX, AWX instructs Kubernetes to create a Pod using specified EE image. Of course Kubernetes requires the specified container image when creating the Pod. So while creating the Pod, Kubernetes usually pulls specified image from the container registry.
The EEs in AWX are just Pods on Kubernetes. When executing a Job Template in AWX, AWX instructs Kubernetes to create a Pod using the specified EE image. Of course Kubernetes requires the specified container image when creating the Pod. So while creating the Pod, Kubernetes usually pulls the specified image from the container registry.
But this happens only if the image is not cached on the container runtime for Kubernetes. If Kubernetes has the cache of the specified image, Kubernetes never pulls the image from the container registry (Technically, this is the default behavior and stated as `imagePullPolicy` is `IfNotPresent`).
@ -195,7 +195,7 @@ In AWX, you can change the policy of pulling the image in `Edit` page of your EE
### Use EE in Ansible Runner
Refer [the guide for Ansible Runner on this repository](../runner).
Refer to [the guide for Ansible Runner on this repository](../runner).
## Tips
@ -203,7 +203,7 @@ Some additional information around Ansible Builder and EE.
### Get the `Dockerfile` of your custom EE
The `Dockerfile` is generated and stored under the `context` directory once your `ansible-builder build` command is completed.
The `Dockerfile` is generated and stored under the `context` directory once your `ansible-builder build` command has completed.
```bash
$ cat context/Dockerfile
@ -227,7 +227,7 @@ FROM base as final
...
```
If you want to create `Dockerfile` without building image, you can use `ansible-builder create` command.
If you want to create `Dockerfile` without building an image, you can use the `ansible-builder create` command.
```bash
$ ansible-builder create --verbosity 3
@ -250,7 +250,7 @@ Complete! The build context can be found at: /home/********/awx-on-k3s/builder/c
If you simply need additional Ansible collections only, and no additional Pip or RPM packages are required, this method is the simplest way. However, this method can't be applied for Manual type projects. If you want to add your project as Manual type, you should build custom EE.
The procedure is quite simple, create and place `collections/requirements.yml` on your project root including the list of the collections which you want to use.
The procedure is quite simple, create and place `collections/requirements.yml` in your project root including the list of the collections that you want to use.
The format of `collections/requirements.yml` is the same as [the `requirements.yml` for ansible-galaxy](https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#install-multiple-collections-with-a-requirements-file).