Version Compatibility

Compatibility matrix, version requirements, and upgrade guides for arillso collections and tools.

Supported Versions 

Current Release Status 

Component	Current Version	Status	End of Life
arillso.system	1.0.x	Supported	TBD
arillso.container	1.0.x	Supported	TBD
arillso.agent	1.0.x	Supported	TBD
arillso/ansible (container)	latest	Supported	Rolling
go.ansible (library)	1.x	Supported	TBD
action.playbook (GitHub Action)	1.2.x	Supported	TBD

Version Support Policy 

Major versions (1.0.0 → 2.0.0): Supported for 12 months after next major release
Minor versions (1.0.0 → 1.1.0): Supported for 6 months after next minor release
Patch versions (1.0.0 → 1.0.1): Always upgrade to latest patch
Security fixes: Backported to all supported versions

Requirements 

Ansible Requirements 

arillso Collection	Minimum Ansible	Recommended Ansible
arillso.system 1.x	2.15.0	2.16.0+
arillso.container 1.x	2.15.0	2.16.0+
arillso.agent 1.x	2.15.0	2.16.0+

Check your Ansible version:

ansible --version

Upgrade Ansible:

# Using pip
pip install --upgrade ansible

# Using pipx (recommended)
pipx upgrade ansible

Python Requirements 

Component	Minimum Python	Recommended Python
Ansible Control Node	3.9	3.11+
Managed Nodes	3.6	3.9+
go.ansible	N/A (Go)	N/A (Go)

Check Python version:

# Control node
python3 --version

# Managed nodes
ansible all -m ansible.builtin.command -a "python3 --version"

Operating System Support 

Control Node (Where Ansible Runs)

OS	Status	Notes
Ubuntu 20.04, 22.04, 24.04	✅ Supported	Recommended
Debian 11, 12	✅ Supported
RHEL/Rocky/Alma 8, 9	✅ Supported
macOS 12+	✅ Supported	With Homebrew
Windows 10/11	⚠️ Limited	WSL2 only
Alpine Linux	❌ Not Supported	Use container image

Managed Nodes (Target Hosts)

arillso.system

OS	Status	Notes
Ubuntu 20.04, 22.04, 24.04	✅ Fully Supported	Primary platform
Debian 11, 12	✅ Fully Supported
RHEL/Rocky/Alma 8, 9	✅ Fully Supported
Fedora 38+	⚠️ Best Effort	Community supported
Alpine Linux	⚠️ Limited	Container roles only
Arch Linux	❌ Not Supported
Windows	❌ Not Supported	Use arillso.system on Linux

arillso.container

OS	Status	Notes
Ubuntu 20.04, 22.04, 24.04	✅ Fully Supported
Debian 11, 12	✅ Fully Supported
RHEL/Rocky/Alma 8, 9	✅ Fully Supported
Alpine Linux	✅ Supported	K3s, Docker
Raspberry Pi OS	✅ Supported	ARM64

arillso.agent

OS	Status	Notes
Ubuntu 20.04, 22.04, 24.04	✅ Fully Supported
Debian 11, 12	✅ Fully Supported
RHEL/Rocky/Alma 8, 9	✅ Fully Supported

Architecture Support 

Architecture	Support Status	Notes
x86_64 (amd64)	✅ Fully Supported	Primary
ARM64 (aarch64)	✅ Fully Supported	Tested on Pi, Graviton
ARMv7	⚠️ Limited	Basic roles only
x86 (32-bit)	❌ Not Supported

Collection Compatibility 

Inter-Collection Compatibility 

Collection	arillso.system	arillso.container	arillso.agent
arillso.system	1.x	Any	Any
arillso.container	Any	1.x	Any
arillso.agent	Any	Any	1.x

All arillso collections are designed to work together seamlessly.

Community Collections 

arillso collections depend on these community collections:

# Automatically installed as dependencies
dependencies:
  - ansible.posix (>= 1.5.0)
  - community.general (>= 8.0.0)

Verify dependencies:

ansible-galaxy collection list

Third-Party Tool Versions 

Container Runtimes 

Docker

Docker Version	arillso.container	Notes
20.10.x	✅ Supported	Minimum
23.0.x	✅ Supported
24.0.x	✅ Supported
25.0.x+	✅ Supported	Recommended

Kubernetes (K3s)

K3s Version	arillso.container	Notes
v1.26.x	✅ Supported	Minimum
v1.27.x	✅ Supported
v1.28.x	✅ Supported	Recommended
v1.29.x+	✅ Supported

Customize K3s version:

# In your vars
# renovate: datasource=github-releases depName=k3s-io/k3s
k3s_version: "v1.28.0+k3s1"

Monitoring Tools 

Grafana Alloy

Alloy Version	arillso.agent	Notes
v1.0.x	✅ Supported	Latest stable

Tailscale

Tailscale Version	arillso.agent	Notes
Latest stable	✅ Supported	Auto-updated

Upgrade Guides 

Upgrading Collections 

Minor Version Upgrades (1.0.x → 1.1.x)

Minor upgrades are backward compatible:

# Update to latest minor version
ansible-galaxy collection install arillso.system --upgrade

# Test with check mode
ansible-playbook site.yml --check

# Deploy
ansible-playbook site.yml

Major Version Upgrades (1.x → 2.x)

Major upgrades may include breaking changes:

Review Changelog:

# View changelog
ansible-doc-collection arillso.system

# Or visit GitHub
curl https://github.com/arillso/ansible.system/blob/main/CHANGELOG.md

Update in test environment first:

# Test environment
ansible-galaxy collection install arillso.system:2.0.0 \
  -p ./test-collections

# Test playbooks
ansible-playbook -i test-inventory site.yml

Update variable names if needed:

# Example breaking change (hypothetical)
# v1.x
firewall:  # Old structure
  - table:
      family: inet

# v2.x (hypothetical)
firewall_tables:  # New structure
  inet:
    chains: []

Deploy to production:

ansible-galaxy collection install arillso.system:2.0.0 --force
ansible-playbook site.yml

Migration Paths 

From Other Collections 

From geerlingguy.* roles

# Before (geerlingguy)
- hosts: all
  roles:
    - geerlingguy.docker

# After (arillso)
- hosts: all
  tasks:
    - name: Install Docker
      ansible.builtin.include_role:
        name: arillso.container.docker

From ansible.builtin modules

# Before
- name: Install packages
  ansible.builtin.package:
    name:
      - nginx
      - htop

# After (more features)
- name: Install packages
  ansible.builtin.include_role:
    name: arillso.system.packages
  vars:
    packages_list:
      - name: nginx
        state: present
      - name: htop
        state: present

From Manual Configuration 

Converting shell scripts to playbooks:

# Before (shell script)
#!/bin/bash
apt-get update
apt-get install -y nginx
systemctl enable nginx
systemctl start nginx

# After (Ansible)
---
- name: Setup web server
  hosts: webservers
  become: true
  tasks:
    - name: Install nginx
      ansible.builtin.include_role:
        name: arillso.system.packages
      vars:
        packages_list:
          - name: nginx
            state: present

Breaking Changes 

Version 1.x Breaking Changes 

arillso.system 1.0.0

Initial release - no breaking changes

arillso.container 1.0.0

Initial release - no breaking changes

arillso.agent 1.0.0

Initial release - no breaking changes

Planned Deprecations 

No deprecations planned for 1.x series.

Version Pinning 

Best Practices 

Use version ranges in requirements.yml:

---
collections:
  # Allow patch updates
  - name: arillso.system
    version: ">=1.0.0,<1.1.0"

  # Allow minor updates
  - name: arillso.container
    version: ">=1.0.0,<2.0.0"

  # Pin exact version (not recommended)
  - name: arillso.agent
    version: "1.0.0"

Renovate auto-updates:

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "github>arillso/.github:renovate-ansible"
  ]
}

Lock Files 

Create a lock file for reproducibility:

# Generate lock file
ansible-galaxy collection list --format yaml > collections-lock.yml

# Install from lock file
ansible-galaxy collection install -r collections-lock.yml

Compatibility Testing 

Testing Different Versions 

# molecule/default/requirements.yml
---
collections:
  - name: arillso.system
    version: "1.0.0"  # Test specific version

# Test with molecule
molecule test

Matrix Testing 

Test multiple versions in CI/CD:

# .github/workflows/test.yml
strategy:
  matrix:
    ansible:
      - "2.15"
      - "2.16"
    collection:
      - "1.0.0"
      - "latest"

Known Issues 

Current Known Issues 

Issue	Description	Workaround
None	No known issues	N/A

Version-Specific Issues 

Issues are tracked per version in GitHub Issues.

See: https://github.com/arillso/ansible.*/issues

Compatibility Checklist 

Before Upgrading 

✅ Pre-upgrade checklist:

[ ] Review CHANGELOG for breaking changes
[ ] Test in non-production environment
[ ] Backup configuration files
[ ] Update requirements.yml
[ ] Run playbooks with --check mode
[ ] Update CI/CD pipelines
[ ] Document any custom changes needed
[ ] Plan rollback procedure

After Upgrading 

✅ Post-upgrade verification:

[ ] Verify collection versions installed
[ ] Run full playbook in test environment
[ ] Check all roles function correctly
[ ] Verify monitoring still works
[ ] Review logs for errors
[ ] Test rollback procedure
[ ] Update documentation
[ ] Deploy to production

Getting Help 

Release Calendar 

Release Schedule 

Major releases (x.0.0): Annually
Minor releases (1.x.0): Quarterly
Patch releases (1.0.x): As needed

Subscribe to releases:

GitHub: Watch → Custom → Releases
RSS: https://github.com/arillso/ansible.*/releases.atom

Next Steps 

Review Quick Start Guide for getting started
Check Complete Examples for version-specific examples
Read Troubleshooting & FAQ for upgrade issues
Explore Contributing for version requirements