aRustyDev / aRustyDev/agents

feat(skills): add iac-ansible-roles-dev skill

Open
#813 0 comments 0 reactions 1 assignee Claimed by @aRustyDev View on GitHub
Dominant language
Jupyter Notebook
Stars
8
Forks
3
PR merge metrics
No merged PRs in 30d

Description

## Summary

Create a new skill `iac-ansible-roles-dev` for Ansible role development patterns, variable scoping, and common pitfalls.

## Context & Motivation

This skill gap was identified during a homelab Kubernetes cluster deployment using Ansible. During the implementation of a storage configuration role with LUKS encryption and etcd encryption at rest, several critical bugs were encountered that stemmed from Ansible-specific behavior that is not intuitive and not well-documented in common resources.

### The Triggering Incident

A bug caused `kube-apiserver` to fail repeatedly with the error:
```
secret is not of the expected length, got 512, expected one of [16 24 32]
```

The root cause was **variable pollution between `include_role` calls** in Ansible. A role that retrieves secrets from 1Password was called twice:
1. First to retrieve a LUKS keyfile (512 bytes)
2. Then to retrieve an etcd encryption key (32 bytes, base64 encoded to 44 chars)

Because the role used `set_fact` to store the retrieved value, and the second invocation had a conditional skip ("value already set"), the LUKS keyfile was incorrectly used as the etcd encryption key.

This class of bug:
- Is not obvious from reading the code
- Doesn't produce clear error messages pointing to the cause
- Requires understanding of Ansible's fact persistence across role invocations
- Is easily introduced when refactoring roles for reuse

### Additional Bug: Double Base64 Encoding

The same debugging session uncovered a second pattern: Ansible's `slurp` module base64-encodes file content, but this wasn't being decoded before use, resulting in double-encoding when the content was later base64-encoded for Kubernetes secrets.

## Use Cases

This skill should support:

1. **Role Development**
- Designing reusable roles with clean interfaces
- Understanding variable scope (play vars, role defaults, role vars, set_fact)
- Implementing idempotent role behavior
- Testing roles in isolation and in combination

2. **Debugging Role Interactions**
- Identifying variable pollution between role invocations
- Understanding fact persistence and clearing
- Debugging conditional execution logic
- Tracing variable values through complex plays

3. **Galaxy Collection Limitations**
- Identifying when a collection has limitations (e.g., `kubernetes.core.helm` limited to Helm 3 when Helm 4 is current)
- Checking for known issues in collection repositories
- Determining if fixes are underway (PRs, roadmap)
- Evaluating whether to:
- Wait for upstream fix
- Fork and patch locally
- Contribute upstream fix
- Work around the limitation
- Understanding collection versioning and compatibility

4. **Common Pitfalls & Patterns**
- `include_role` vs `import_role` behavior differences
- Variable precedence surprises
- Handler notification across roles
- Loop variable scoping
- Async task patterns
- Error handling and rescue blocks

## Key Requirements

### Must Include

1. **Variable Scope Reference**
- Complete precedence hierarchy with examples
- `set_fact` persistence behavior
- How to clear facts between role invocations
- When to use `vars:` vs role defaults vs play vars

2. **Role Design Patterns**
- State clearing at role entry points
- Defensive programming for shared variables
- Role interface design (inputs, outputs, side effects)
- Testing strategies for reusable roles

3. **Galaxy Collection Workflow**
- How to check collection issue trackers
- Evaluating PR/fix status
- Forking and local patching workflow
- Contributing back upstream
- Pinning collection versions

4. **Debugging Techniques**
- Using `-vvv` effectively
- Debug module patterns
- Fact inspection between tasks
- Tracing variable sources

5. **Anti-Patterns to Avoid**
- Relying on fact persistence without explicit clearing
- Conditional execution based on "already set" without validation
- Mixing `include_role` and `import_role` without understanding differences
- Not accounting for `slurp` base64 encoding

### References to Include

- Ansible documentation on variable precedence
- Galaxy collection development guide
- kubernetes.core collection repository
- Common collection issue patterns

### Templates/Examples

- Role skeleton with proper state management
- Reusable secret-retrieval role pattern
- Galaxy collection limitation workaround template
- Role testing playbook template

## Related Issues

- Part of skill gap detection from homelab K8s deployment session
- Related to #813 (homelab-k8s-ops) and #814 (secrets-1password-dev)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.