ansible/infra-automation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation for PRIVATE submodules structure

Browse Source 
📚 Documentation Update - Repository Security Enhancement

Changes:
1. Updated README.md:
   - Clarified submodule structure (both PRIVATE)
   - Updated Quick Start with submodule commands
   - Updated Project Structure diagram
   - Added SSH agent initialization

2. Created docs/submodule-workflow.md:
   - Comprehensive submodule usage guide
   - Clone, update, and workflow procedures
   - Security considerations for both submodules
   - Troubleshooting section
   - Best practices and compliance notes

3. Made ansible-inventories PRIVATE:
   - Protects internal network topology
   - Protects IP addresses and hostnames
   - Updated all documentation to reflect PRIVATE status

4. Updated inventories submodule reference:
   - Points to latest commit with security updates

Security Rationale:
- inventories → PRIVATE: Protects network topology, IP addresses
- secrets → PRIVATE: Protects SSH keys, vault files
- Main repo → PUBLIC: Playbooks and roles only

Repository Structure:
├── infra-automation (PUBLIC)
├── inventories (PRIVATE)
└── secrets (PRIVATE)

Benefits:
✅ Network topology protection
✅ Sensitive data isolation
✅ Proper access controls
✅ Independent version control
✅ Security-first approach

Documentation:
- docs/submodule-workflow.md: Complete submodule guide
- docs/git-ssh-setup.md: SSH configuration
- README.md: Updated project structure

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
ansible
2025-11-11 14:47:12 +01:00
parent be33603856
commit 7e89e93c9f
3 changed files with 451 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

400
docs/submodule-workflow.md Normal file
View File

@@ -0,0 +1,400 @@
# Git Submodule Workflow
This repository uses git submodules to separate concerns and follow CLAUDE.md guidelines.
## Repository Structure
```
infra-automation/ # Main repository (PUBLIC)
├── inventories/ # → ansible-inventories submodule (PUBLIC)
├── secrets/ # → secrets submodule (PRIVATE)
├── playbooks/
├── roles/
└── docs/
```
## Submodules
### 1. inventories (PRIVATE)
- **URL:** `ssh://git@git.mymx.me:2222/ansible/ansible-inventories.git`
- **Type:** PRIVATE repository
- **Contents:** Dynamic inventories, host/group variables (may contain internal IPs/hostnames)
- **Purpose:** Separate inventory management from infrastructure code, protect internal network topology
### 2. secrets (PRIVATE)
- **URL:** `ssh://git@git.mymx.me:2222/ansible/secrets.git`
- **Type:** PRIVATE repository
- **Contents:** SSH keys, vault files, sensitive data
- **Purpose:** Security isolation, separate access control
## Initial Clone
### Option 1: Clone with submodules (recommended)
```bash
git clone --recurse-submodules ssh://git@git.mymx.me:2222/ansible/infra-automation.git
cd infra-automation
```
### Option 2: Clone then initialize submodules
```bash
git clone ssh://git@git.mymx.me:2222/ansible/infra-automation.git
cd infra-automation
git submodule init
git submodule update
```
## Working with Submodules
### Update All Submodules
```bash
# Update to latest commits from remote
git submodule update --remote
# Commit submodule updates in main repository
git add inventories secrets
git commit -m "Update submodule references"
git push
```
### Update Specific Submodule
```bash
# Update only inventories
git submodule update --remote inventories
# Update only secrets
git submodule update --remote secrets
```
### Making Changes in Submodules
#### Method 1: Work inside submodule
```bash
# Navigate to submodule
cd inventories
# Ensure on correct branch
git checkout master
# Make changes
vim production/libvirt.yml
# Commit and push from submodule
git add production/libvirt.yml
git commit -m "Update libvirt inventory configuration"
git push origin master
# Update parent repository reference
cd ..
git add inventories
git commit -m "Update inventories submodule"
git push
```
#### Method 2: Direct submodule update
```bash
# Make changes, commit, and push in one workflow
cd inventories
git pull origin master
# Make changes
git add .
git commit -m "Changes"
git push origin master
cd ..
git add inventories
git commit -m "Update inventories"
git push
```
### Checking Submodule Status
```bash
# View submodule status
git submodule status
# View detailed info
git submodule
# Check for uncommitted changes in submodules
git submodule foreach git status
```
## Common Workflows
### Workflow 1: Update Inventory Configuration
```bash
# 1. Navigate to inventories
cd inventories
# 2. Pull latest changes
git pull origin master
# 3. Make changes
vim production/group_vars/all.yml
# 4. Commit and push
git add production/group_vars/all.yml
git commit -m "Update production variables"
git push origin master
# 5. Update parent repository
cd ..
git add inventories
git commit -m "Update inventories submodule reference"
git push origin master
```
### Workflow 2: Add New SSH Key to Secrets
```bash
# 1. Navigate to secrets
cd secrets
# 2. Pull latest (important for private repo)
git pull origin master
# 3. Add new key
ssh-keygen -t ed25519 -f ssh/newkey -C "description"
# 4. Document in README
vim ssh/README.md
# 5. Commit and push
git add ssh/
git commit -m "Add new SSH key: newkey"
git push origin master
# 6. Update parent
cd ..
git add secrets
git commit -m "Update secrets submodule"
git push origin master
```
### Workflow 3: Clone Project on New Machine
```bash
# 1. Clone with submodules
git clone --recurse-submodules ssh://git@git.mymx.me:2222/ansible/infra-automation.git
cd infra-automation
# 2. Verify submodules initialized
git submodule status
# Should show: ebe29b6... inventories (heads/master)
# 8def011... secrets (heads/master)
# 3. Set up SSH agent for git operations
source .ssh-agent-init
# 4. Verify inventory works
ansible-inventory -i inventories/production/libvirt.yml --list
# 5. Ready to use!
```
## Troubleshooting
### Submodule Not Initialized
**Problem:** Submodule directory exists but is empty
```bash
# Solution
git submodule init
git submodule update
```
### Submodule Detached HEAD
**Problem:** Submodule is in detached HEAD state
```bash
# Solution: checkout master branch
cd submodule_name
git checkout master
git pull origin master
cd ..
git add submodule_name
git commit -m "Update submodule to track master"
```
### Submodule Changes Not Showing
**Problem:** Made changes in submodule but parent doesn't show update
```bash
# Solution: Stage submodule in parent
git add submodule_name
git commit -m "Update submodule reference"
```
### Permission Denied on Private Submodule
**Problem:** Cannot clone/update secrets submodule
```bash
# Solution: Ensure SSH key is loaded
source /opt/ansible/.ssh-agent-init
ssh-add -l
# Verify access
ssh -T git@git.mymx.me -p 2222
# Try update again
git submodule update --init
```
### Accidentally Committed Changes to Detached HEAD
**Problem:** Made commits in submodule while in detached HEAD
```bash
# Solution: Create branch from detached commits
cd submodule_name
git branch temp-branch
git checkout master
git merge temp-branch
git push origin master
git branch -d temp-branch
```
## Best Practices
### 1. Always Work on Branches
```bash
cd inventories
git checkout master
# Never work in detached HEAD
```
### 2. Pull Before Push
```bash
cd secrets
git pull origin master
# Make changes
git push origin master
```
### 3. Update Parent After Submodule Changes
```bash
# After pushing submodule changes
cd ..
git add submodule_name
git commit -m "Update submodule"
git push
```
### 4. Regular Submodule Updates
```bash
# Weekly: update all submodules
git submodule update --remote
git add inventories secrets
git commit -m "Update submodules to latest"
git push
```
### 5. Document Submodule Changes
```bash
# Use descriptive commit messages
git commit -m "Update inventories: Add staging environment configuration"
```
## Security Considerations
### Secrets Submodule (PRIVATE)
- ⚠️ Never make secrets repository public
- ⚠️ Verify .gitignore before committing
- ⚠️ Use SSH key authentication only
- ⚠️ Regular access audits
- ⚠️ Rotate keys according to schedule
### Inventories Submodule (PRIVATE)
- ⚠️ Private repository - protects network topology
- ⚠️ Contains internal IPs, hostnames, network structure
- ✅ Use vault references for passwords/secrets
- ✅ Document all group/host variables
- ✅ Controlled team access only
## Advanced Operations
### Reset Submodule to Specific Commit
```bash
cd inventories
git checkout <commit-hash>
cd ..
git add inventories
git commit -m "Pin inventories to specific version"
```
### Remove Submodule
```bash
# 1. Deinitialize
git submodule deinit -f inventories
# 2. Remove from git
git rm -f inventories
# 3. Remove module directory
rm -rf .git/modules/inventories
# 4. Commit
git commit -m "Remove inventories submodule"
```
### Change Submodule URL
```bash
# Update .gitmodules
git config --file=.gitmodules submodule.inventories.url <new-url>
# Sync
git submodule sync
git submodule update --init --recursive
# Commit
git add .gitmodules
git commit -m "Update submodule URL"
```
## Quick Reference
| Action | Command |
|--------|---------|
| Clone with submodules | `git clone --recurse-submodules <url>` |
| Init submodules | `git submodule init` |
| Update submodules | `git submodule update` |
| Update to latest | `git submodule update --remote` |
| Check status | `git submodule status` |
| Foreach command | `git submodule foreach <command>` |
| Work in submodule | `cd submodule && git checkout master` |
| Update parent reference | `git add submodule && git commit` |
## Related Documentation
- [Git SSH Setup](git-ssh-setup.md) - SSH key configuration
- [CLAUDE.md](../CLAUDE.md) - Repository structure guidelines
- [ansible-inventories README](https://git.mymx.me/ansible/ansible-inventories) - Inventory documentation
- [secrets README](https://git.mymx.me/ansible/secrets) - Secrets management (PRIVATE)
## Compliance
This submodule structure follows CLAUDE.md requirements with security enhancements:
- ✅ `./inventories` in PRIVATE repository (protects network topology)
- ✅ `./secrets` in PRIVATE repository (protects sensitive data)
- ✅ Separation of concerns
- ✅ Independent version control
- ✅ Proper access controls
- ✅ Network topology protection
---
**Last Updated:** 2025-11-11
**Workflow Version:** 1.0