initial commit

README.md

@@ -0,0 +1,112 @@
+# 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.