Stage 4 · Provision
Roles & Collections
Building an Internal Library
Company-wide roles, versioning, and a private Galaxy.
Designing an Internal Library
An internal Ansible library packages your organization's automation knowledge into reusable roles and collections. It standardizes how services are deployed, configured, and managed across teams.
ansible-library/
collections/
company/
infrastructure/
galaxy.yml
roles/
common/
nginx/
postgresql/
docker/
monitoring/
plugins/
modules/
filter/
playbooks/
site.yml
deploy.yml
requirements.yml
docs/
getting-started.md
role-catalog.md
tests/
molecule/
ci/Organize by namespace and collection. This mirrors Ansible's own structure and makes the library discoverable.
Naming Conventions
| Element | Convention | Example |
|---|---|---|
| Collection | company.collection_name | company.infrastructure |
| Role | Descriptive, hyphenated | nginx-hardened |
| Variable | role_name_verb_noun | nginx_worker_connections |
| Task | Action-oriented verb phrase | Install nginx packages |
Versioning Strategy
---
namespace: company
name: infrastructure
version: 2.4.1
license: MIT
description: Company infrastructure automation
authors:
- Platform Team
dependencies:
community.general: ">=7.0.0"
repository: https://github.com/company/ansible-infrastructureUse semantic versioning: MAJOR.MINOR.PATCH. MAJOR for breaking changes, MINOR for new features, PATCH for bug fixes.
# Tag a release
git tag -a v2.4.1 -m "Release 2.4.1"
git push origin v2.4.1
# Install specific version
ansible-galaxy collection install company.infrastructure:2.4.1
# Update requirements.yml
# version: ">=2.4.0,<3.0.0"Tag releases in git. Reference specific versions in requirements.yml for reproducible deployments.
Private Galaxy Server
For internal content that should not be public, host a private Galaxy server or use a Git-based distribution model.
---
roles:
- name: common
src: https://github.com/company/ansible-common.git
version: main
- name: nginx-hardened
src: https://gitlab.company.com/platform/ansible-nginx.git
version: v2.4.1
collections:
- name: company.infrastructure
source: https://galaxy.company.com/api/
version: ">=2.0.0"Private Galaxy servers require authentication. Use API tokens and store them securely, not in requirements.yml.
For smaller teams, git submodules can distribute roles without a Galaxy server. Add the library as a submodule in each project's roles/ directory.
Sharing Across Teams
- Publish to a private Galaxy server for discoverability
- Use Git repos with tagged releases for version control
- Provide a README with usage examples for every role
- Maintain a role catalog documenting available automation
- Use CI/CD to test and publish library updates automatically
Treat your internal Ansible library as a product. Version it, document it, test it, and provide support. Teams that consume it are your customers.
Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.