Ansible Core

Ansible SkogAI

Comprehensive assistance with Ansible Core development and automation for SkogAI projects, combining official Ansible Core 2.19 documentation with SkogAI repository-specific knowledge.

When to Use This Skill

This skill should be triggered when:

Ansible SkogAI (General)

• Writing or debugging Ansible playbooks
• Creating or modifying Ansible modules and plugins
• Setting up Ansible inventories (INI, YAML, dynamic)
• Working with Ansible Vault for secrets management
• Developing Ansible collections
• Configuring automation workflows with ansible-playbook, ansible-pull, or ad-hoc commands
• Troubleshooting Ansible connection, privilege escalation, or module issues
• Converting manual infrastructure tasks into Ansible automation
• Implementing infrastructure as code with Ansible
• Learning Ansible best practices and design patterns

SkogAI Ansible Repository

• Working with files in ~/.ansible/ directory
• Questions about the repository structure or specific roles
• Creating or modifying Ansible roles in this repository
• Understanding the primitives-based architecture
• Questions about packages, ssh, git, chezmoi, cloudflared, zsh, or other implemented roles
• Working with vars files, vault encryption, or role configuration
• Using git worktrees with worktrunk for development

SkogAI Ansible Repository

Path: /home/skogix/.ansible/ Repository: SkogAI/skogansible

Core Documentation Files

All comprehensive documentation is in the repository:

• @/home/skogix/.ansible/CLAUDE.md - Complete project documentation, all features, usage patterns
• @/home/skogix/.ansible/FILESTRUCTURE.md - Complete file structure with descriptions
• @/home/skogix/.ansible/docs/primitives/ansible-core.md - 7 fundamental primitives reference
• @/home/skogix/.ansible/docs/primitives/system-inventory-by-primitives.md - Complete system roadmap

Role Documentation

Each role has comprehensive README:

• @/home/skogix/.ansible/roles/packages/README.md - Package management (pacman + AUR)
• @/home/skogix/.ansible/roles/ssh/README.md - SSH configuration and hardening
• @/home/skogix/.ansible/roles/git/README.md - Git configuration
• @/home/skogix/.ansible/roles/chezmoi/README.md - Dotfiles management
• @/home/skogix/.ansible/roles/cloudflared/README.md - Cloudflare Tunnel
• @/home/skogix/.ansible/roles/zsh/README.md - ZSH configuration

7 Fundamental Primitives

All automation breaks down into these patterns (see @docs/primitives/ansible-core.md for examples):

1. Task Composition - include_tasks for modularity
2. Package State - pacman module for official packages
3. AUR Packages - kewlfft.aur module with yay
4. User Management - user module for creating users
5. File Content - lineinfile for ensuring file contents
6. Path Queries - stat + register for checking existence
7. Git Repos - git module for cloning/syncing

Variable Organization

All role configuration in vars/ directory:

• vars/packages.yml - Package lists
• vars/ssh.yml, vars/ssh_vault.yml - SSH config (vault encrypted)
• vars/git.yml - Git configuration
• vars/chezmoi.yml - Chezmoi machine profile
• vars/cloudflared.yml, vars/cloudflared_vault.yml - Cloudflared config
• vars/zsh.yml - ZSH configuration
• vars/main.yml - Shared variables

Essential Commands

./bootstrap.sh              # Initial setup (venv + ansible)
./run.sh                    # Run all roles
./run.sh --check            # Dry-run
./run.sh --tags ROLE        # Run specific role
./run.sh --tags ROLE --ask-vault-pass  # With vault password

wt switch --create --base master NAME  # Create git worktree
wt step commit              # Commit with AI message
wt merge                    # Merge and cleanup worktree

Key Points

• Primitives-based: All tasks use the 7 fundamental patterns
• Vault encryption: Secrets in *_vault.yml files
• Git worktrees: Use worktrunk for isolated development
• Documentation: Everything documented in role READMEs and docs/
• Target: Arch Linux (adaptable to other distros)

Quick Reference

1. Basic Playbook Structure

A simple playbook with tasks, the fundamental building block of Ansible automation:

- name: My first play
  hosts: myhosts
  tasks:
    - name: Ping my hosts
      ansible.builtin.ping:

    - name: Print message
      ansible.builtin.debug:
        msg: Hello world

What it does: Defines a play that runs against hosts in the myhosts group, pings them to verify connectivity, and prints a debug message.

2. Inventory File (INI Format)

Organize your managed hosts into groups with variables:

[web]
host1
host2 ansible_port=222

[web:vars]
http_port=8080
myvar=23

[web:children]
apache
nginx

[apache]
tomcat1
tomcat2 myvar=34
tomcat3 mysecret="'03#pa33w0rd'"

[nginx]
jenkins1

[all:vars]
has_java = False

What it does: Defines host groups, assigns variables at group level, creates group hierarchies with :children, and sets host-specific overrides.

3. Using ansible-vault for Secrets

Encrypt sensitive data and use it in playbooks:

# Create encrypted file
ansible-vault create secrets.yml

# Use in playbook with password prompt
ansible-playbook site.yml --ask-vault-pass

# Use with password file
ansible-playbook site.yml --vault-password-file ~/.vault_pass.txt

# Use multiple vault IDs
ansible-playbook site.yml --vault-id dev@dev-password --vault-id prod@prompt

What it does: Encrypts sensitive variables, allows decryption at runtime with passwords from prompts, files, or scripts. Supports multiple vault IDs for different environments.

4. Installing Ansible and Creating a Project

Get started with Ansible quickly:

# Install ansible
pip install ansible

# Create project structure
mkdir ansible_quickstart && cd ansible_quickstart

# Run a playbook
ansible-playbook playbook.yaml

What it does: Installs Ansible via pip, creates a project directory for organizing automation content, and executes a playbook.

5. Ad-hoc Commands

Execute single tasks without writing a playbook:

# Run ad-hoc command on specific hosts
ansible -i inventory.ini myhosts -m ansible.builtin.ping

# Install package with privilege escalation
ansible localhost -m ansible.builtin.apt -a "name=apache2 state=present" -b -K

# Check disk space
ansible all -m ansible.builtin.shell -a "df -h"

What it does: Executes Ansible modules directly from CLI for quick tasks. -b enables become (sudo), -K prompts for privilege escalation password.

6. Module with Variables (include_vars)

Dynamically load variables from external files:

- name: Include vars of stuff.yaml into the 'stuff' variable
  ansible.builtin.include_vars:
    file: stuff.yaml
    name: stuff

- name: Load variables based on OS
  ansible.builtin.include_vars: "{{ lookup('ansible.builtin.first_found', params) }}"
  vars:
    params:
      files:
        - "{{ansible_distribution}}.yaml"
        - "{{ansible_os_family}}.yaml"
        - default.yaml
      paths:
        - "vars"

What it does: Loads YAML/JSON variables at runtime. Supports conditional loading based on facts, directory scanning, and namespace isolation.

7. Plugin Development Basics (Python)

Create a custom filter plugin:

from ansible.module_utils.common.text.converters import to_native

try:
    cause_an_exception()
except Exception as e:
    raise AnsibleError('Something happened, this was original exception: %s' % to_native(e))

What it does: Shows proper error handling in Ansible plugins using to_native() for Python 2/3 string compatibility and AnsibleError for user-friendly error messages.

8. String Encoding in Modules

Ensure proper Unicode handling in custom modules:

from ansible.module_utils.common.text.converters import to_text

result_string = to_text(result_string)

What it does: Converts strings to Unicode (Python 3's str type) ensuring Jinja2 compatibility and preventing encoding errors.

9. Convert Data to YAML (Filter)

Transform Ansible variables into YAML format in templates:

# dump variable in a template to create a YAML document
{{ github_workflow | to_nice_yaml }}

# with custom indentation and sorting
{{ my_dict | to_nice_yaml(indent=4, sort_keys=False) }}

What it does: Uses the to_nice_yaml filter to serialize Ansible variables as YAML strings, useful for generating config files or debugging.

10. Testing List Relationships

Use Jinja2 test plugins to validate data:

big: [1, 2, 3, 4, 5]
small: [3, 4]
issmallinbig: "{{ small is subset(big) }}"

What it does: Tests if one list is a subset of another. Useful for conditional logic in playbooks based on list membership.

Key Concepts

Playbooks

YAML files defining automation workflows. Contain plays (ordered lists of tasks) that run against inventory groups. Each task invokes a module with specific parameters.

Inventory

Lists of managed hosts organized into groups. Can be static (INI/YAML files) or dynamic (scripts/plugins). Supports host and group variables, parent-child relationships.

Modules

Reusable units of code executed on managed nodes. Ansible ships with hundreds of modules (ansible.builtin collection). Use FQCN (Fully Qualified Collection Name) like ansible.builtin.copy for clarity.

Plugins

Extend Ansible's core functionality. Types include filters, tests, callbacks, connections, inventory, lookup, and vars plugins. Execute on the control node (unlike modules).

Collections

Packaging format for Ansible content (modules, plugins, roles, playbooks). Use ansible-galaxy collection install to add community collections.

Ansible Vault

Encryption system for sensitive data. Encrypts entire files or individual variables. Supports multiple vault passwords with vault IDs for different environments (dev, prod, etc.).

FQCN (Fully Qualified Collection Name)

Full path to a module/plugin: namespace.collection.plugin_name. Example: ansible.builtin.copy. Prevents naming conflicts and improves clarity.

Facts

System information gathered automatically from managed nodes. Access with ansible_facts variable. Disable with gather_facts: no in playbooks.

Handlers

Special tasks triggered by notify directive. Run once at the end of a play, even if notified multiple times. Common for service restarts.

Reference Files

This skill includes comprehensive documentation in references/:

• getting_started.md (9 pages) - Installation, first playbook, basic concepts, quickstart guide
• installation.md - Installation methods for various operating systems, pip, package managers
• inventory.md (19 pages) - INI/YAML inventory syntax, dynamic inventory, host patterns, variables
• playbooks.md (72 pages) - Playbook syntax, plays, tasks, conditionals, loops, roles, imports
• modules.md (52 pages) - Module development, parameters, return values, shell plugins
• collections.md (319 pages) - Collection structure, ansible.builtin modules/plugins, filters, tests
• vault.md (4 pages) - Encrypting files/variables, vault IDs, password management
• commands.md (6 pages) - CLI tools: ansible, ansible-playbook, ansible-galaxy, ansible-vault, ansible-console
• development.md - Plugin development, module development, Python coding standards
• porting.md - Porting guides for upgrading between Ansible versions
• os_specific.md - Platform-specific modules and configurations (Windows, BSD, etc.)
• community.md (12 pages) - Contributing guidelines, code review, community resources
• other.md - Miscellaneous topics not fitting other categories

Use the reference files when you need:

• Detailed API documentation for specific modules or plugins
• Complete parameter lists with all options and defaults
• Advanced use cases and edge case handling
• Version-specific information about features and deprecations

Working with This Skill

For Beginners

1. Start with getting_started.md - Learn Ansible basics, create your first playbook, understand inventory
2. Review Quick Reference examples - Copy and adapt the patterns above
3. Read inventory.md - Understand how to organize and manage your hosts
4. Explore commands.md - Master the CLI tools for running playbooks and ad-hoc tasks

First steps:

• Install Ansible: pip install ansible
• Create a simple inventory file with your test hosts
• Write a hello-world playbook using the Quick Reference example #1
• Run it: ansible-playbook -i inventory.ini playbook.yml

For Intermediate Users

1. Deep dive into playbooks.md - Learn advanced playbook features (conditionals, loops, handlers, roles)
2. Explore collections.md - Discover available modules and plugins for your use cases
3. Master vault.md - Secure sensitive data in your automation
4. Study modules.md - Understand module parameters and return values for precise control

Focus areas:

• Organize automation with roles and collections
• Implement proper error handling and idempotency
• Use variables effectively (group_vars, host_vars, facts)
• Leverage filters and tests for data transformation

For Advanced Users / Plugin Developers

1. Study development.md - Learn to write custom modules and plugins
2. Review community.md - Understand contribution guidelines and best practices
3. Check porting.md - Stay updated on version changes and deprecations
4. Explore os_specific.md - Handle platform-specific automation needs

Advanced topics:

• Develop custom modules in Python for domain-specific tasks
• Create collection with reusable automation content
• Implement custom inventory plugins for dynamic infrastructure
• Build callback plugins for custom logging and notifications
• Contribute to ansible-core or community collections

Navigation Tips

• Looking for a specific module? Search collections.md (319 pages) - it's indexed
• Debugging connection issues? Check commands.md for SSH options and connection troubleshooting
• Need to encrypt data? vault.md has all encryption patterns
• Writing Python code? development.md covers coding standards and best practices
• Platform-specific task? os_specific.md covers Windows, BSD, and other OS peculiarities

Common Patterns

Pattern 1: Conditional Task Execution

- name: Install package
  ansible.builtin.apt:
    name: nginx
    state: present
  when: ansible_os_family == "Debian"

Pattern 2: Loop Over Items

- name: Create multiple users
  ansible.builtin.user:
    name: "{{ item }}"
    state: present
  loop:
    - alice
    - bob
    - charlie

Pattern 3: Handler for Service Restart

tasks:
  - name: Update config
    ansible.builtin.copy:
      src: nginx.conf
      dest: /etc/nginx/nginx.conf
    notify: restart nginx

handlers:
  - name: restart nginx
    ansible.builtin.service:
      name: nginx
      state: restarted

Pattern 4: Register and Use Task Output

- name: Check if file exists
  ansible.builtin.stat:
    path: /etc/myapp/config
  register: config_stat

- name: Create config if missing
  ansible.builtin.copy:
    src: default-config
    dest: /etc/myapp/config
  when: not config_stat.stat.exists

Best Practices

1. Always use FQCN - ansible.builtin.copy instead of copy for clarity
2. Name all tasks and plays - Makes debugging and logs readable
3. Use --check mode - Test playbooks without making changes
4. Implement idempotency - Ensure playbooks can run multiple times safely
5. Encrypt secrets with vault - Never commit plain-text passwords or keys
6. Use roles for organization - Group related tasks, vars, and handlers
7. Document with comments - Explain complex logic in playbooks
8. Test with --diff - See what changes before applying them
9. Use version control - Track playbook changes in git
10. Follow YAML syntax strictly - Use consistent indentation (2 spaces)

Troubleshooting

Connection issues:

# Test connectivity
ansible all -m ping -i inventory.ini

# Use verbose mode
ansible-playbook playbook.yml -vvv

# Check SSH configuration
ansible all -m shell -a "whoami" --ask-pass

Variable debugging:

- name: Debug variable value
  ansible.builtin.debug:
    var: my_variable
    verbosity: 0

Syntax validation:

# Check playbook syntax
ansible-playbook playbook.yml --syntax-check

# Lint with ansible-lint (if installed)
ansible-lint playbook.yml

Resources

Official Documentation

• Ansible Core Docs: https://docs.ansible.com/ansible-core/2.19/
• Module Index: Browse collections.md reference file
• Getting Started Guide: getting_started.md reference file

Community

• Ansible Galaxy: https://galaxy.ansible.com/ - Browse and install collections
• GitHub: https://github.com/ansible/ansible - Source code and issues
• Community Forum: https://forum.ansible.com/ - Ask questions and share knowledge

Learning Resources

• Ansible Examples: https://github.com/ansible/ansible-examples
• Workshops: https://ansible.github.io/workshops/
• Interactive Labs: Multiple providers offer hands-on Ansible training

Notes

• This skill was automatically generated from official Ansible Core 2.19 documentation
• Enhanced with SkogAI repository-specific context and primitives-based architecture
• Reference files preserve structure and examples from source documentation
• Code examples use proper language detection for syntax highlighting
• Quick reference patterns are extracted from real-world usage examples
• All module/plugin names use FQCN format for clarity and future compatibility