# Ansible Repository - AWX and GitLab Bootstrap

Automated setup of two independent single-VM services on Rocky Linux:

- **AWX**, deployed via the AWX Operator on a single-node k3s cluster
- **GitLab CE**, deployed via the official Omnibus package

Each service is meant to run on its own dedicated, otherwise-blank VM.

## Requirements

```bash
ansible-galaxy collection install -r requirements.yml
```

Target hosts: Rocky Linux 9 (minimal install), reachable via SSH with an
administrative sudo-capable account, with outbound internet access
(both roles pull packages/manifests from public sources at install time).

### Sizing recommendations

| Host | Minimum | Recommended |
|---|---|---|
| AWX (k3s + operator) | 2 vCPU / 4 GB RAM | 4 vCPU / 8 GB RAM |
| GitLab CE | 2 vCPU / 4 GB RAM (with `gitlab_install_reduce_memory_footprint: true`) | 4 vCPU / 8 GB RAM |

`common_min_memory_mb` in group_vars enforces a baseline check before
either install proceeds.

## Getting started

1. Update `inventories/production/hosts.ini` with real hostnames/IPs.
2. Review `inventories/production/group_vars/all.yml`,
   `group_vars/awx_servers.yml`, and `group_vars/gitlab_servers.yml`.
3. Check the current release tags before rollout - both are pinned on
   purpose for reproducibility and should not be left at whatever was
   current when this repo was written:
   - k3s: https://github.com/k3s-io/k3s/releases (`k3s_version`)
   - AWX Operator: https://github.com/ansible/awx-operator/releases (`awx_operator_version`)
4. Set up secrets:
   ```bash
   cp vault/secrets.yml.example vault/secrets.yml
   # fill in awx_admin_password and gitlab_root_password
   ansible-vault encrypt vault/secrets.yml
   ```
5. Store the vault password in `.vault_pass` (chmod 600, do not commit it).

## Running

```bash
# Both services
ansible-playbook playbooks/site.yml --ask-vault-pass

# AWX only
ansible-playbook playbooks/awx.yml --ask-vault-pass

# GitLab only
ansible-playbook playbooks/gitlab.yml --ask-vault-pass
```

AWX deployment can take 10-20 minutes after the operator applies the
custom resource (image pulls, database init); the role waits for the web
deployment to become available with a generous timeout, but a first run
on a slow connection can still take longer.

## Quality checks

```bash
ansible-lint
ansible-playbook playbooks/site.yml --syntax-check
```

## Role overview

| Role | Purpose |
|---|---|
| `common` | Base packages, time sync, hostname, firewalld, memory check |
| `k3s_install` | Single-node k3s cluster, kernel/sysctl prerequisites, Python kubernetes client |
| `awx_operator` | AWX Operator + AWX custom resource via k3s |
| `gitlab_install` | GitLab CE Omnibus package, `gitlab.rb`, firewall, health check |

## Access after rollout

- **AWX**: `http://<awx-host>:<awx_operator_nodeport>` (default port 30080), user
  `admin`, password from `vault/secrets.yml` (`awx_admin_password`).
- **GitLab**: `<gitlab_install_external_url>`, user `root`, password from
  `vault/secrets.yml` (`gitlab_root_password`) - change it on first login.

## Open items before rollout

- Pin and verify `k3s_version` and `awx_operator_version` against current
  upstream releases (see links above).
- The GitLab yum repository definition (`roles/gitlab_install/tasks/main.yml`)
  uses the primary GitLab GPG key; cross-check against
  https://packages.gitlab.com/gitlab/gitlab-ce/install if package
  verification fails on first run.
- AWX is exposed via plain HTTP NodePort by default
  (`awx_operator_service_type`/`awx_operator_nodeport`) - put a reverse proxy or load
  balancer with TLS in front of it for anything beyond initial testing.
- GitLab's `external_url` defaults to `https://` with
  `gitlab_install_letsencrypt_enabled: false`, so Omnibus will auto-generate a
  self-signed certificate on first `reconfigure`. Enable Let's Encrypt or
  supply real certificates before using this beyond initial testing.
- Both roles assume outbound internet access on the target VM (k3s
  install script, AWX operator manifests from GitHub, GitLab packages).
  Air-gapped rollout would need a different distribution mechanism and is
  not covered here.
- `gitlab_install_version` is unpinned by default (installs latest) - pin it for
  reproducible deployments once you've qualified a specific version.
- No backup/restore automation is included for either service - both
  hold state (AWX: Postgres in a k3s PVC; GitLab: `/var/opt/gitlab`) that
  needs its own backup strategy before production use.