Early-Access Infrastructure-as-Code for UniFi controllers Version: v2.1.0-SUBSTRATE Status: Experimental / Proof-of-Concept (Meta-GitOps Paradigm)
!!! danger "Enterprise Readiness Advisory" This collection is not suitable for production use in enterprise environments. - Test coverage is currently ~24% (target: 85%). - Security rules are partially suppressed (S603, S310) for rapid development. - Single-controller architecture only; no multi-controller support. - RTO validation is conditional and not fully verified for all environments.
rylanlabs.common is an experimental Ansible collection for infrastructure automation, specifically targeting UniFi controllers running the latest updates.
It serves as a platform for testing standardized tasks (Identity, Audit, Hardening), custom modules (UniFi API), and plugins.
This is a proof-of-concept and should not be used in critical production environments without extensive validation.
While we strive for idempotency and "junior-at-3-AM" deployability, these features are still in active development.
Objectives:
- Centralize reusable code to eliminate duplication across domain repos.
- Enforce infrastructure-as-code best practices in every role/module.
- Support high availability with built-in safety handlers.
- Support modular workflows for bootstrap, validation, and hardening.
| Category | Status | Risk | Expected Resolution |
|---|---|---|---|
| Test Coverage | 24.37% | High | Q2 2026 (Target 85%) |
| Security Linting | Partially Suppressed | Critical | Q3 2026 (S603/S310 remediation) |
| Multi-Controller | Not Supported | Medium | Q4 2026 |
| Secret Management | ENV-based (Experimental) | High | Transition to Ansible Vault in progress |
| Audit Immutability | Native Filesystem | Medium | Loki/Grafana integration pending |
- Idempotency: Roles use pre-checks for safe re-runs.
- Error Handling: Fail loud with context; remediation in docs.
- Audit Logging: Structured logs to
.audit/for every execution. - Trinity 7-Task Pattern: All production playbooks follow a standardized workflow (Gather, Process, Apply, Verify, Compliance, Report, Finalize).
- Documentation Clarity: FQCN examples; junior-readable guides in
docs/. - Safety Constraints: Built-in limits for firewall rules and VLANs to prevent overload.
Execution Alignment:
- Identity:
identity_managementrole bootstraps auth services. - Audit:
infrastructure_verifyenforces linting and state validation. - Hardening:
hardening_managementapplies firewall and isolation policies.
rylan-labs-common/
├── .audit/ # Structured JSON audit logs
├── .github/ # CI/CD workflows and GitHub Actions
├── docs/ # Documentation files
│ ├── GITOPS-SUBSTRATE-PARADIGM.md # 🆕 Master doc: Meta-GitOps architecture
│ ├── INTEGRATION_GUIDE.md # Tandem setup and ansible.cfg
│ ├── SEVEN_PILLARS.md # [Absorbed] Compliance framework
│ ├── EMERGENCY_RESPONSE.md # [Absorbed] Incident recovery
│ └── TANDEM_WORKFLOW.md # [Absorbed] Execution philosophy
├── meta/ # Collection metadata
│ └── runtime.yml # Ansible reqs and dependencies
├── playbooks/ # Example playbooks
│ ├── example-bootstrap.yml # Complete sequence demo (Identity -> Audit -> Hardening)
│ ├── example-identity.yml # Identity management role demonstration
│ ├── example-verify.yml # Audit and verification role demonstration
│ ├── example-harden.yml # Security hardening role demonstration
│ ├── example-vlan-bootstrap.yml # Network: VLAN infrastructure provisioning
│ └── example-firewall-rules.yml # Hardening: Experimental firewall rules
├── plugins/ # Custom extensions
│ ├── modules/ # Python modules
│ │ └── unifi_api.py # UniFi API queries
│ ├── inventory/ # Inventory plugins
│ │ └── unifi_dynamic_inventory.py # Dynamic UniFi inventory
│ └── module_utils/ # Shared utils
│ └── rylan_utils.py # Audit/rollback helpers
├── roles/ # Reusable roles
│ ├── infrastructure_verify/ # Verification tasks
│ │ ├── defaults/ # main.yml with vars
│ │ ├── tasks/ # main.yml
│ │ └── handlers/ # Service restarts
│ ├── hardening_management/ # Hardening tasks
│ │ ├── defaults/ # main.yml
│ │ ├── tasks/ # main.yml
│ │ └── handlers/ # Rollbacks
│ └── identity_management/ # Identity tasks
│ ├── defaults/ # main.yml
│ ├── tasks/ # main.yml
│ └── handlers/ # Audits
├── scripts/ # Validation utilities
├── tests/ # Unit/integration tests (skeleton)
├── .gitignore # Ignore builds/tests
├── .pre-commit-config.yaml # Hooks (ansible-lint, etc.)
├── .yamllint # YAML rules
├── CHANGELOG.md # Version history
├── galaxy.yml # Collection metadata
├── LICENSE # MIT
├── Makefile # Build/validate tasks
├── pyproject.toml # Python linting
├── rylanlab-common-1.2.1.tar.gz # Built archive (v1.2.1)
└── README.md # This file
```bash
---
## Features
### Core Roles
#### identity_management
- **Purpose**: Bootstrap centralized identity services (RADIUS, LDAP).
- **Defaults** (`defaults/main.yml`):
```yaml
identity_management_enabled: false
identity_providers: []
identity_management_audit_enabled: false- Tasks: Install packages, configure authentication, audit events.
-
Purpose: Validate configuration, run linting, and audit logging.
-
Defaults:
infrastructure_verify_enabled: false infrastructure_verify_audit_enabled: true infrastructure_loki_endpoint: "" infrastructure_log_retention_days: 90
-
Tasks: Run validation checks and log auditing.
-
Purpose: Firewall rules, VLAN isolation, and security enforcement.
-
Defaults:
hardening_management_enabled: false hardening_management_firewall_rules: [] hardening_management_vlan_configs: []
-
Tasks: Configure security policies and enforce infrastructure isolation.
- Queries UniFi for topology/WLAN/clients.
- Generates inventory from UniFi controller.
- Shared: Logging, validation, rollback.
Via Galaxy:
ansible-galaxy install rylanlabs.common
```bash
From Source:
```bash
git clone https://github.com/RylanLabs/rylan-labs-common.git
cd rylan-labs-common
ansible-galaxy collection install . --force
# Or install the packaged tarball directly (from repo root):
# ansible-galaxy collection install rylanlab-common-1.2.1.tar.gz --force
```bash
---
## Standards & Validation
This collection follows high-standard development practices for infrastructure automation.
**Key Features**:
- Linting configs synchronized with production standards.
- Pre-commit hooks enforce modular patterns and YAML best practices.
- Validators run locally to ensure CI parity.
- Architectural disciplines documented in `docs/disciplines/`.
**For Developers**:
```bash
# Install environment and dependencies
make setup
# Run validators manually
make validate📚 Full Documentation: docs/GITOPS-SUBSTRATE-PARADIGM.md
RylanLabs has pioneered Meta-GitOps: The Makefile reconciles how code enters Git itself, treating codebase evolution as declaratively managed state. This unified GitOps workflow automates validation, branching, and PR creation while enforcing the Seven Pillars.
# Standard workflow (Stage -> Commit -> Push -> PR)
make publish msg="feat(api): add client group normalization"
# Draft for early review
make publish-draft msg="wip: experimental zone matrix refactor"
# Hotfix with auto-merge (requires auto-merge enabled on repo)
make publish-merge msg="fix(critical): resolve VLAN 90 isolation breach"Workflow Phases:
- Phase 0 (Bauer): Pre-flight assessment via
make validate. - Phase 1 (Carter): Provisioning of a timestamped feature branch (
feat/YYYYMMDD-HHmmss). - Phase 2 (Audit): Signed commit (
git commit -S) and state capture. - Phase 3 (Hardening): Push to origin and PR creation via
ghCLI. - Audit: Lifecycle captured in
.audit/make-history.log.
For Maintainers: See docs/ for architecture and validation manifests.
This collection aims to implement the Seven Pillars as follows (Work in Progress):
- Idempotency: All roles support
--checkmode. Many tasks are validated to be idempotent, though complex UniFi API states may require manual verification. - Error Handling: Uses
block/rescuefor critical operations. Rollback handlers are being added and currently cover ~30% of critical tasks. - Audit Logging: Structured JSON trails generated in
.audit/. Centralized Loki integration is planned for Q3 2026. - Security: Firewalls and VLAN isolation are configurable. Security posture validation scripts are available but in beta.
Target RTO: < 15 minutes for all incidents (Experimental Target).
| Scenario | Recovery Strategy | Target |
|---|---|---|
| Collection Missing | ansible-galaxy collection install . --force |
2 min |
| Task Failure | Identify tags via -vvv and re-run specific tags |
5 min |
| Service Down | Check reachability; fallback to static credentials | 8 min |
| Full Reset | Run scripts/example-recovery.yml with domain tags |
15 min |
!!! warning "Target Realism" RTO targets are theoretical and based on ideal network conditions. Actual recovery times may vary significantly.
For detailed runbooks, see docs/EMERGENCY_RESPONSE.md (Canonical Link).
- name: Bootstrap Infrastructure
hosts: all
roles:
- rylanlabs.common.identity_management
- rylanlabs.common.infrastructure_verify
- rylanlabs.common.hardening_management
```bash
### Dynamic Inventory
Configure `unifi_inventory.yml`; use `-i unifi_inventory.yml`.
### Playbooks (playbooks/)
- `example-bootstrap.yml`: Complete sequence.
- `example-identity.yml`: Identity management.
- `example-verify.yml`: Audit and verification.
- `example-harden.yml`: Security hardening.
---
## Tandem Integration
With `rylan-canon-library`: Bootstrap hooks/validators.
With `rylan-inventory`: Dynamic plugin pulls manifests.
**Architecture Flowchart**:
```mermaid
graph TD
A[rylan-canon-library<br/>Doctrine/Templates] -->|Bootstrap Hooks| B[rylan-labs-common<br/>Roles/Modules/Plugins]
B -->|ansible-galaxy install| C[Domain Repos<br/>e.g., rylan-labs-iac]
D[rylan-inventory<br/>Manifests/Data] -->|Dynamic Plugin| B
B -->|Playbooks/Roles| E[Deployment<br/>3-Domain Sequence]
subgraph "Tandem Ecosystem"
A --> B --> C
D --> B
end
```bash
---
## Quality Assurance
Local: `make ci-local` (`ansible-lint`, `ruff`, `mypy`, etc.).
Pre-commit: `make pre-commit-install`.
---
## Seven Pillars Compliance (Target State)
- **Idempotency**: Partial. Pre-checks implemented in 80% of roles.
- **Error Handling**: Partial. `failed_when` clauses and basic rescue blocks present.
- **Audit Logging**: Local only. JSON trails in `.audit/`.
- **Documentation**: On-going. Extensive `docs/` exist but may lag behind rapid changes.
- **Validation**: Local only. `Makefile` targets for linting.
- **Reversibility**: Beta. Basic rollback handlers for identity and hardening roles.
- **Observability**: Minimal. Basic reachability checks; no Prometheus/Grafana integration.
---
## Emergency Response (Experimental)
| Scenario | Domain | Action | Target RTO |
| --- | --- | --- | --- |
| Install Fail | Audit | `--force install` | 2min |
| Role Drift | Identity | Validate-only playbook | 5min |
| Hardening Breach | Hardening | Recovery playbook `--tags hardening` | 10min |
| Full Reset | Recovery | `eternal-resurrect.sh --common` | 15min |
---
## Documentation
- INTEGRATION_GUIDE.md: Setup/ansible.cfg.
- SEVEN_PILLARS.md: Framework.
- TANDEM_WORKFLOW.md: Dataflow.
- EMERGENCY_RESPONSE.md: Procedures.
---
## Versioning
SemVer: MAJOR.MINOR.PATCH. CHANGELOG.md tracks.
---
## License
MIT. See LICENSE.
---
## Authors
RylanLabs Team <team@rylanlabs.com>
---
## Support & Contribution
Issues: <https://github.com/RylanLabs/rylan-labs-common/issues>.
PRs follow Seven Pillars.
---
**Last Updated**: 2026-02-03
**Status**: Experimental (v2.0.0-beta) — PR branch `master`
**Infrastructure-as-Code requires discipline. All experimental changes must be validated.**