Add initial project structure with configuration files and playbooks for infrastructure management. Introduce .ansible-lint-ignore to manage linting exceptions for vault files. Create README.md and documentation for setup guides, including Tailscale and monitoring roles. Establish Makefile commands for streamlined execution of playbooks and tasks. Update inventory structure for better organization of hosts and variables.
This commit is contained in:
parent
4621ea4674
commit
cd12b02147
8
.ansible-lint-ignore
Normal file
8
.ansible-lint-ignore
Normal file
@ -0,0 +1,8 @@
|
||||
# Ignore document-start issues for encrypted vault files
|
||||
inventories/production/host_vars/bottom.yml yaml[document-start]
|
||||
inventories/production/host_vars/debianDesktopVM.yml yaml[document-start]
|
||||
inventories/production/host_vars/dev01.yml yaml[document-start]
|
||||
inventories/production/host_vars/giteaVM.yml yaml[document-start]
|
||||
inventories/production/host_vars/homepageVM.yml yaml[document-start]
|
||||
inventories/production/host_vars/portainerVM.yml yaml[document-start]
|
||||
inventories/production/group_vars/all/vault.yml yaml[document-start]
|
||||
267
.cursorrules
Normal file
267
.cursorrules
Normal file
@ -0,0 +1,267 @@
|
||||
# Ansible Infrastructure Project Rules
|
||||
|
||||
## Project Context
|
||||
This is an Ansible infrastructure automation project managing multiple hosts including development machines, service VMs, and Proxmox infrastructure. The project uses Makefile for task automation and Ansible Vault for secrets management.
|
||||
|
||||
## Code Style & Conventions
|
||||
|
||||
### Ansible YAML Files
|
||||
- Use 2 spaces for indentation (no tabs)
|
||||
- Always include `name:` for tasks with descriptive names
|
||||
- Use `become: true` at play level when most tasks need sudo
|
||||
- Group related tasks with block statements
|
||||
- Always use fully qualified module names (e.g., `ansible.builtin.package`)
|
||||
- Use handlers for service restarts
|
||||
|
||||
### Variable Naming
|
||||
- Prefix vault variables with `vault_` (e.g., `vault_tailscale_auth_key`)
|
||||
- Use snake_case for all variables
|
||||
- Define defaults in `roles/*/defaults/main.yml`
|
||||
- Override in `group_vars/` or `host_vars/`
|
||||
- Document variables with comments
|
||||
|
||||
### Role Structure
|
||||
```
|
||||
roles/role_name/
|
||||
├── defaults/main.yml # Default variables
|
||||
├── handlers/main.yml # Service handlers
|
||||
├── tasks/main.yml # Main tasks
|
||||
├── templates/ # Jinja2 templates
|
||||
├── files/ # Static files
|
||||
├── vars/main.yml # Role variables (rarely used)
|
||||
└── README.md # Role documentation
|
||||
```
|
||||
|
||||
### Task Best Practices
|
||||
```yaml
|
||||
# Good
|
||||
- name: Install required packages
|
||||
ansible.builtin.package:
|
||||
name: "{{ item }}"
|
||||
state: present
|
||||
loop: "{{ required_packages }}"
|
||||
when: required_packages is defined
|
||||
|
||||
# Bad
|
||||
- package:
|
||||
name: vim
|
||||
state: present
|
||||
```
|
||||
|
||||
## File Organization
|
||||
|
||||
### Documentation
|
||||
- Place all documentation in `docs/` directory
|
||||
- Use `docs/guides/` for how-to guides
|
||||
- Use `docs/reference/` for technical references
|
||||
- Keep README.md concise with links to detailed docs
|
||||
|
||||
### Playbook Organization
|
||||
- One playbook per major function (dev, local, maintenance, etc.)
|
||||
- Use tags for selective execution
|
||||
- Import roles in logical order (base → specific)
|
||||
|
||||
### Inventory
|
||||
- Group hosts logically in `hosts` file
|
||||
- Use group_vars for shared configuration
|
||||
- Use host_vars for host-specific settings
|
||||
|
||||
## Security Practices
|
||||
|
||||
### Vault Usage
|
||||
- ALWAYS encrypt sensitive data with Ansible Vault
|
||||
- Store vault password in `~/.ansible-vault-pass`
|
||||
- Never commit unencrypted secrets
|
||||
- Use `make create-vault` and `make edit-vault` commands
|
||||
|
||||
### SSH Security
|
||||
- Use SSH keys only (no passwords)
|
||||
- Implement fail2ban on all hosts
|
||||
- Configure UFW firewall
|
||||
- Use Tailscale for additional security layer
|
||||
|
||||
## Makefile Conventions
|
||||
|
||||
### Target Naming
|
||||
- Use lowercase with hyphens (e.g., `tailscale-status`)
|
||||
- Include help text with `##` comment
|
||||
- Group related targets together
|
||||
- Provide usage examples in help text
|
||||
|
||||
### Common Patterns
|
||||
```makefile
|
||||
target: ## Description (usage: make target [VAR=value])
|
||||
@echo "Executing target..."
|
||||
$(ANSIBLE_PLAYBOOK) playbook.yml $(ANSIBLE_ARGS)
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Before Making Changes
|
||||
1. Test connectivity: `make ping`
|
||||
2. Check current state: `make facts`
|
||||
3. Review existing configuration in host_vars
|
||||
|
||||
### Making Changes
|
||||
1. Edit role or playbook
|
||||
2. Test with check mode: `make check`
|
||||
3. Apply to single host first: `make dev HOST=testhost`
|
||||
4. Apply to group/all: `make apply`
|
||||
|
||||
### Testing
|
||||
- Always use `--check` mode first
|
||||
- Test on single host before group
|
||||
- Use `--diff` to see changes
|
||||
- Verify idempotency (run twice, expect no changes)
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Installing Packages
|
||||
```yaml
|
||||
- name: Install packages
|
||||
ansible.builtin.package:
|
||||
name:
|
||||
- package1
|
||||
- package2
|
||||
state: present
|
||||
become: true
|
||||
```
|
||||
|
||||
### Managing Services
|
||||
```yaml
|
||||
- name: Ensure service is running
|
||||
ansible.builtin.systemd:
|
||||
name: service_name
|
||||
state: started
|
||||
enabled: true
|
||||
daemon_reload: true
|
||||
become: true
|
||||
```
|
||||
|
||||
### Using Templates
|
||||
```yaml
|
||||
- name: Deploy configuration
|
||||
ansible.builtin.template:
|
||||
src: config.j2
|
||||
dest: /etc/service/config
|
||||
owner: root
|
||||
group: root
|
||||
mode: '0644'
|
||||
become: true
|
||||
notify: restart service
|
||||
```
|
||||
|
||||
### Conditional Execution
|
||||
```yaml
|
||||
- name: Task for Debian family
|
||||
ansible.builtin.package:
|
||||
name: package
|
||||
state: present
|
||||
when: ansible_os_family == "Debian"
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Issues
|
||||
1. **Vault password issues**: Check `~/.ansible-vault-pass`
|
||||
2. **SSH connection failed**: Verify SSH keys with `make copy-ssh-key`
|
||||
3. **Sudo password required**: Configure passwordless sudo or use `--ask-become-pass`
|
||||
4. **Python not found**: Set `ansible_python_interpreter` in inventory
|
||||
|
||||
### Debugging
|
||||
- Use `make debug` for verbose output
|
||||
- Add `debugger: on_failed` to tasks
|
||||
- Check logs in `/var/log/ansible/` on targets
|
||||
- Use `ansible -m setup` to gather facts
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Ansible Configuration
|
||||
- Set appropriate `forks` value in ansible.cfg
|
||||
- Use `pipelining = True` for SSH optimization
|
||||
- Cache facts when appropriate
|
||||
- Use `serial` for rolling updates
|
||||
|
||||
### Task Optimization
|
||||
- Minimize `command` and `shell` usage
|
||||
- Use native modules when available
|
||||
- Batch operations with `loop` or `with_items`
|
||||
- Use `async` for long-running tasks
|
||||
|
||||
## Documentation Standards
|
||||
|
||||
### Role Documentation
|
||||
Each role must have a README.md with:
|
||||
- Purpose and description
|
||||
- Required variables
|
||||
- Optional variables with defaults
|
||||
- Example usage
|
||||
- Dependencies
|
||||
|
||||
### Playbook Documentation
|
||||
Include header comment with:
|
||||
```yaml
|
||||
---
|
||||
# Playbook: name
|
||||
# Purpose: what it does
|
||||
# Targets: which hosts
|
||||
# Tags: available tags
|
||||
# Usage: make command examples
|
||||
```
|
||||
|
||||
## Git Practices
|
||||
|
||||
### Commit Messages
|
||||
- Use present tense ("Add feature" not "Added feature")
|
||||
- Reference issue numbers when applicable
|
||||
- Keep first line under 50 characters
|
||||
- Add detailed description if needed
|
||||
|
||||
### Branch Strategy
|
||||
- `master`: Stable, tested code
|
||||
- `develop`: Integration branch
|
||||
- `feature/*`: New features
|
||||
- `fix/*`: Bug fixes
|
||||
- `hotfix/*`: Urgent production fixes
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Regular Tasks
|
||||
- Update packages monthly: `make maintenance`
|
||||
- Review and rotate vault passwords quarterly
|
||||
- Audit SSH keys semi-annually
|
||||
- Update Ansible and collections annually
|
||||
|
||||
### Monitoring
|
||||
- Check service status: `make tailscale-status`
|
||||
- Review logs regularly
|
||||
- Monitor system health
|
||||
- Track system resources
|
||||
|
||||
## Support & Resources
|
||||
|
||||
### Internal Documentation
|
||||
- `/docs/guides/` - How-to guides
|
||||
- `/docs/reference/` - Technical references
|
||||
- Role README files
|
||||
- Makefile help: `make help`
|
||||
|
||||
### External Resources
|
||||
- Ansible documentation: https://docs.ansible.com
|
||||
- Ansible Galaxy: https://galaxy.ansible.com
|
||||
- Tailscale docs: https://tailscale.com/kb
|
||||
- Project issues tracker
|
||||
|
||||
## AI Assistant Guidelines
|
||||
|
||||
When working with this project:
|
||||
1. Always check existing patterns before suggesting changes
|
||||
2. Maintain consistent style with existing code
|
||||
3. Test all changes with check mode first
|
||||
4. Update documentation when adding features
|
||||
5. Use Makefile commands instead of direct ansible-playbook calls
|
||||
6. Encrypt sensitive data with Ansible Vault
|
||||
7. Follow security best practices
|
||||
8. Consider idempotency in all tasks
|
||||
9. Provide clear task names and comments
|
||||
10. Group related changes logically
|
||||
17
.editorconfig
Normal file
17
.editorconfig
Normal file
@ -0,0 +1,17 @@
|
||||
root = true
|
||||
|
||||
[*]
|
||||
charset = utf-8
|
||||
end_of_line = lf
|
||||
insert_final_newline = true
|
||||
trim_trailing_whitespace = true
|
||||
|
||||
[*.{yml,yaml}]
|
||||
indent_style = space
|
||||
indent_size = 2
|
||||
|
||||
[*.md]
|
||||
trim_trailing_whitespace = false
|
||||
|
||||
[Makefile]
|
||||
indent_style = tab
|
||||
4
.gitignore
vendored
4
.gitignore
vendored
@ -22,4 +22,6 @@ __pycache__/
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
.ansible/facts/
|
||||
.ansible/facts/
|
||||
|
||||
node_modules/
|
||||
16
.yamllint
Normal file
16
.yamllint
Normal file
@ -0,0 +1,16 @@
|
||||
---
|
||||
extends: default
|
||||
|
||||
rules:
|
||||
line-length:
|
||||
max: 120
|
||||
comments:
|
||||
min-spaces-from-content: 1
|
||||
comments-indentation: false
|
||||
braces:
|
||||
max-spaces-inside: 1
|
||||
octal-values:
|
||||
forbid-implicit-octal: true
|
||||
forbid-explicit-octal: true
|
||||
truthy:
|
||||
allowed-values: ['true', 'false', 'yes', 'no']
|
||||
219
Makefile
219
Makefile
@ -1,4 +1,4 @@
|
||||
.PHONY: help bootstrap lint test check apply dev local clean status tailscale tailscale-check tailscale-dev tailscale-status create-vault create-vm monitoring backup
|
||||
.PHONY: help bootstrap lint test check apply dev local clean status tailscale tailscale-check tailscale-dev tailscale-status create-vault create-vm monitoring
|
||||
.DEFAULT_GOAL := help
|
||||
|
||||
## Colors for output
|
||||
@ -9,6 +9,27 @@ YELLOW := \033[33m
|
||||
BLUE := \033[34m
|
||||
RESET := \033[0m
|
||||
|
||||
# Playbook paths
|
||||
PLAYBOOK_SITE := playbooks/site.yml
|
||||
PLAYBOOK_DEV := playbooks/development.yml
|
||||
PLAYBOOK_LOCAL := playbooks/local.yml
|
||||
PLAYBOOK_MAINTENANCE := playbooks/maintenance.yml
|
||||
PLAYBOOK_TAILSCALE := playbooks/tailscale.yml
|
||||
PLAYBOOK_PROXMOX := playbooks/infrastructure/proxmox-vm.yml
|
||||
|
||||
# Collection and requirement paths
|
||||
COLLECTIONS_REQ := collections/requirements.yml
|
||||
PYTHON_REQ := requirements.txt
|
||||
|
||||
# Inventory paths
|
||||
INVENTORY := inventories/production
|
||||
INVENTORY_HOSTS := $(INVENTORY)/hosts
|
||||
|
||||
# Common ansible-playbook command with options
|
||||
ANSIBLE_PLAYBOOK := ansible-playbook -i $(INVENTORY)
|
||||
ANSIBLE_ARGS := --vault-password-file ~/.ansible-vault-pass
|
||||
# Note: sudo passwords are in vault files as ansible_become_password
|
||||
|
||||
## Auto-detect current host to exclude from remote operations
|
||||
CURRENT_IP := $(shell hostname -I | awk '{print $$1}')
|
||||
CURRENT_HOST := $(shell ansible-inventory --list | jq -r '._meta.hostvars | to_entries[] | select(.value.ansible_host == "$(CURRENT_IP)") | .key' 2>/dev/null | head -1)
|
||||
@ -34,21 +55,69 @@ help: ## Show this help message
|
||||
@echo " make maintenance-verbose GROUP=dev # Verbose maintenance on dev group"
|
||||
@echo ""
|
||||
|
||||
bootstrap: ## Install required collections and dependencies
|
||||
@echo "$(BOLD)Installing Dependencies$(RESET)"
|
||||
bootstrap: ## Install all project dependencies from requirements files
|
||||
@echo "$(BOLD)Installing Project Dependencies$(RESET)"
|
||||
@echo ""
|
||||
@echo "$(YELLOW)Ansible Collections:$(RESET)"
|
||||
@ansible-galaxy collection install -r collections/requirements.yml 2>&1 | grep -E "(Installing|Skipping|ERROR)" | while read line; do \
|
||||
if echo "$$line" | grep -q "Installing"; then \
|
||||
collection=$$(echo "$$line" | awk '{print $$2}' | sed 's/:.*//'); \
|
||||
printf " $(GREEN)✓ %-30s$(RESET) Installed\n" "$$collection"; \
|
||||
elif echo "$$line" | grep -q "Skipping"; then \
|
||||
collection=$$(echo "$$line" | awk '{print $$2}' | sed 's/,.*//'); \
|
||||
printf " $(BLUE)- %-30s$(RESET) Already installed\n" "$$collection"; \
|
||||
elif echo "$$line" | grep -q "ERROR"; then \
|
||||
printf " $(RED)✗ Error: $$line$(RESET)\n"; \
|
||||
@echo "$(YELLOW)Python Requirements ($(PYTHON_REQ)):$(RESET)"
|
||||
@if [ -f "$(PYTHON_REQ)" ]; then \
|
||||
if command -v pipx >/dev/null 2>&1; then \
|
||||
printf " %-30s " "Installing with pipx"; \
|
||||
if pipx install -r $(PYTHON_REQ) >/dev/null 2>&1; then \
|
||||
echo "$(GREEN)✓ Installed$(RESET)"; \
|
||||
else \
|
||||
echo "$(YELLOW)⚠ Some packages may have failed$(RESET)"; \
|
||||
fi; \
|
||||
elif command -v pip3 >/dev/null 2>&1; then \
|
||||
printf " %-30s " "Installing with pip3 --user"; \
|
||||
if pip3 install --user -r $(PYTHON_REQ) >/dev/null 2>&1; then \
|
||||
echo "$(GREEN)✓ Installed$(RESET)"; \
|
||||
else \
|
||||
printf " %-30s " "Trying with --break-system-packages"; \
|
||||
if pip3 install --break-system-packages -r $(PYTHON_REQ) >/dev/null 2>&1; then \
|
||||
echo "$(GREEN)✓ Installed$(RESET)"; \
|
||||
else \
|
||||
echo "$(RED)✗ Failed$(RESET)"; \
|
||||
fi; \
|
||||
fi; \
|
||||
else \
|
||||
printf " %-30s " "Python packages"; \
|
||||
echo "$(YELLOW)⚠ Skipped (pip3/pipx not found)$(RESET)"; \
|
||||
fi; \
|
||||
done || ansible-galaxy collection install -r collections/requirements.yml
|
||||
else \
|
||||
printf " %-30s " "$(PYTHON_REQ)"; \
|
||||
echo "$(RED)✗ File not found$(RESET)"; \
|
||||
fi
|
||||
@echo ""
|
||||
@echo "$(YELLOW)Node.js Dependencies (package.json):$(RESET)"
|
||||
@if [ -f "package.json" ] && command -v npm >/dev/null 2>&1; then \
|
||||
printf " %-30s " "Installing npm packages"; \
|
||||
if npm install >/dev/null 2>&1; then \
|
||||
echo "$(GREEN)✓ Installed$(RESET)"; \
|
||||
else \
|
||||
echo "$(RED)✗ Failed$(RESET)"; \
|
||||
fi; \
|
||||
else \
|
||||
printf " %-30s " "npm packages"; \
|
||||
echo "$(YELLOW)⚠ Skipped (package.json or npm not found)$(RESET)"; \
|
||||
fi
|
||||
@echo ""
|
||||
@echo "$(YELLOW)Ansible Collections ($(COLLECTIONS_REQ)):$(RESET)"
|
||||
@if [ -f "$(COLLECTIONS_REQ)" ]; then \
|
||||
ansible-galaxy collection install -r $(COLLECTIONS_REQ) 2>&1 | grep -E "(Installing|Skipping|ERROR)" | while read line; do \
|
||||
if echo "$$line" | grep -q "Installing"; then \
|
||||
collection=$$(echo "$$line" | awk '{print $$2}' | sed 's/:.*//'); \
|
||||
printf " $(GREEN)✓ %-30s$(RESET) Installed\n" "$$collection"; \
|
||||
elif echo "$$line" | grep -q "Skipping"; then \
|
||||
collection=$$(echo "$$line" | awk '{print $$2}' | sed 's/,.*//'); \
|
||||
printf " $(BLUE)- %-30s$(RESET) Already installed\n" "$$collection"; \
|
||||
elif echo "$$line" | grep -q "ERROR"; then \
|
||||
printf " $(RED)✗ Error: $$line$(RESET)\n"; \
|
||||
fi; \
|
||||
done || ansible-galaxy collection install -r $(COLLECTIONS_REQ); \
|
||||
else \
|
||||
printf " %-30s " "$(COLLECTIONS_REQ)"; \
|
||||
echo "$(RED)✗ File not found$(RESET)"; \
|
||||
fi
|
||||
@echo ""
|
||||
|
||||
lint: ## Run ansible-lint on all playbooks and roles
|
||||
@ -56,11 +125,11 @@ lint: ## Run ansible-lint on all playbooks and roles
|
||||
ansible-lint
|
||||
@echo "$(GREEN)✓ Linting completed$(RESET)"
|
||||
|
||||
test-syntax: ## Run syntax check only
|
||||
@echo "$(BOLD)Syntax Testing$(RESET)"
|
||||
test-syntax: ## Run comprehensive syntax and validation checks
|
||||
@echo "$(BOLD)Comprehensive Testing$(RESET)"
|
||||
@echo ""
|
||||
@echo "$(YELLOW)Playbook Syntax:$(RESET)"
|
||||
@for playbook in dev-playbook.yml local-playbook.yml maintenance-playbook.yml tailscale-playbook.yml; do \
|
||||
@for playbook in $(PLAYBOOK_DEV) $(PLAYBOOK_LOCAL) $(PLAYBOOK_MAINTENANCE) $(PLAYBOOK_TAILSCALE); do \
|
||||
if [ -f "$$playbook" ]; then \
|
||||
printf " %-25s " "$$playbook"; \
|
||||
if ansible-playbook "$$playbook" --syntax-check >/dev/null 2>&1; then \
|
||||
@ -71,6 +140,75 @@ test-syntax: ## Run syntax check only
|
||||
fi; \
|
||||
done
|
||||
@echo ""
|
||||
@echo "$(YELLOW)Infrastructure Playbooks:$(RESET)"
|
||||
@for playbook in playbooks/infrastructure/*.yml; do \
|
||||
if [ -f "$$playbook" ]; then \
|
||||
printf " %-25s " "$$playbook"; \
|
||||
if ansible-playbook "$$playbook" --syntax-check >/dev/null 2>&1; then \
|
||||
echo "$(GREEN)✓ OK$(RESET)"; \
|
||||
else \
|
||||
echo "$(RED)✗ FAIL$(RESET)"; \
|
||||
fi; \
|
||||
fi; \
|
||||
done
|
||||
@echo ""
|
||||
@echo "$(YELLOW)Role Test Playbooks:$(RESET)"
|
||||
@for test_playbook in roles/*/tests/test.yml; do \
|
||||
if [ -f "$$test_playbook" ]; then \
|
||||
role_name=$$(echo "$$test_playbook" | cut -d'/' -f2); \
|
||||
printf " %-25s " "roles/$$role_name/test"; \
|
||||
if ansible-playbook "$$test_playbook" --syntax-check >/dev/null 2>&1; then \
|
||||
echo "$(GREEN)✓ OK$(RESET)"; \
|
||||
else \
|
||||
echo "$(RED)✗ FAIL$(RESET)"; \
|
||||
fi; \
|
||||
fi; \
|
||||
done
|
||||
@echo ""
|
||||
@echo "$(YELLOW)Markdown Validation:$(RESET)"
|
||||
@if [ -f "package.json" ] && command -v npm >/dev/null 2>&1; then \
|
||||
printf " %-25s " "Markdown syntax"; \
|
||||
if npm run test:markdown >/dev/null 2>&1; then \
|
||||
echo "$(GREEN)✓ OK$(RESET)"; \
|
||||
else \
|
||||
echo "$(YELLOW)⚠ Issues$(RESET)"; \
|
||||
fi; \
|
||||
else \
|
||||
printf " %-25s " "Markdown syntax"; \
|
||||
echo "$(YELLOW)⚠ npm/package.json not available$(RESET)"; \
|
||||
fi
|
||||
@echo ""
|
||||
@echo "$(YELLOW)Documentation Links:$(RESET)"
|
||||
@if [ -f "package.json" ] && command -v npm >/dev/null 2>&1; then \
|
||||
printf " %-25s " "Link validation"; \
|
||||
if npm run test:links >/dev/null 2>&1; then \
|
||||
echo "$(GREEN)✓ OK$(RESET)"; \
|
||||
else \
|
||||
echo "$(YELLOW)⚠ Issues$(RESET)"; \
|
||||
fi; \
|
||||
else \
|
||||
printf " %-25s " "Link validation"; \
|
||||
echo "$(YELLOW)⚠ npm/package.json not available$(RESET)"; \
|
||||
fi
|
||||
@echo ""
|
||||
@echo "$(YELLOW)Configuration Validation:$(RESET)"
|
||||
@for yaml_file in inventories/production/group_vars/all/main.yml; do \
|
||||
if [ -f "$$yaml_file" ]; then \
|
||||
printf " %-25s " "$$yaml_file (YAML)"; \
|
||||
if python3 -c "import yaml; yaml.safe_load(open('$$yaml_file'))" >/dev/null 2>&1; then \
|
||||
echo "$(GREEN)✓ OK$(RESET)"; \
|
||||
else \
|
||||
echo "$(RED)✗ FAIL$(RESET)"; \
|
||||
fi; \
|
||||
fi; \
|
||||
done
|
||||
@printf " %-25s " "ansible.cfg (INI)"; \
|
||||
if python3 -c "import configparser; c=configparser.ConfigParser(); c.read('ansible.cfg')" >/dev/null 2>&1; then \
|
||||
echo "$(GREEN)✓ OK$(RESET)"; \
|
||||
else \
|
||||
echo "$(RED)✗ FAIL$(RESET)"; \
|
||||
fi
|
||||
@echo ""
|
||||
|
||||
test: ## Run all tests (lint + syntax check if available)
|
||||
@if command -v ansible-lint >/dev/null 2>&1; then \
|
||||
@ -82,19 +220,23 @@ test: ## Run all tests (lint + syntax check if available)
|
||||
|
||||
check: ## Dry-run the development playbook (--check mode)
|
||||
@echo "$(YELLOW)Running dry-run on development hosts...$(RESET)"
|
||||
ansible-playbook dev-playbook.yml --check --diff
|
||||
$(ANSIBLE_PLAYBOOK) $(PLAYBOOK_DEV) --check --diff
|
||||
|
||||
check-local: ## Dry-run the local playbook
|
||||
@echo "$(YELLOW)Running dry-run on localhost...$(RESET)"
|
||||
ansible-playbook local-playbook.yml --check --diff -K
|
||||
$(ANSIBLE_PLAYBOOK) $(PLAYBOOK_LOCAL) --check --diff -K
|
||||
|
||||
apply: ## Run the development playbook on all dev hosts
|
||||
@echo "$(YELLOW)Applying development playbook...$(RESET)"
|
||||
ansible-playbook dev-playbook.yml
|
||||
$(ANSIBLE_PLAYBOOK) $(PLAYBOOK_DEV)
|
||||
|
||||
site: ## Run the complete site playbook
|
||||
@echo "$(YELLOW)Running complete site deployment...$(RESET)"
|
||||
$(ANSIBLE_PLAYBOOK) $(PLAYBOOK_SITE)
|
||||
|
||||
local: ## Run the local playbook on localhost
|
||||
@echo "$(YELLOW)Applying local playbook...$(RESET)"
|
||||
ansible-playbook local-playbook.yml -K
|
||||
$(ANSIBLE_PLAYBOOK) $(PLAYBOOK_LOCAL) -K
|
||||
|
||||
# Host-specific targets
|
||||
dev: ## Run on specific host (usage: make dev HOST=dev01)
|
||||
@ -104,12 +246,12 @@ ifndef HOST
|
||||
@exit 1
|
||||
endif
|
||||
@echo "$(YELLOW)Running on host: $(HOST)$(RESET)"
|
||||
ansible-playbook dev-playbook.yml --limit $(HOST)
|
||||
$(ANSIBLE_PLAYBOOK) $(PLAYBOOK_DEV) --limit $(HOST)
|
||||
|
||||
# Tag-based execution
|
||||
security: ## Run only security-related roles
|
||||
@echo "$(YELLOW)Running security roles...$(RESET)"
|
||||
ansible-playbook dev-playbook.yml --tags security
|
||||
$(ANSIBLE_PLAYBOOK) $(PLAYBOOK_DEV) --tags security
|
||||
|
||||
# Unified maintenance target with intelligent parameter detection
|
||||
maintenance: ## Run maintenance (usage: make maintenance [GROUP=dev] [HOST=dev01] [SERIAL=1] [CHECK=true] [VERBOSE=true])
|
||||
@ -118,7 +260,7 @@ maintenance: ## Run maintenance (usage: make maintenance [GROUP=dev] [HOST=dev01
|
||||
_maintenance-run:
|
||||
@# Determine target and build command
|
||||
@TARGET="all"; \
|
||||
ANSIBLE_CMD="ansible-playbook maintenance-playbook.yml"; \
|
||||
ANSIBLE_CMD="$(ANSIBLE_PLAYBOOK) $(PLAYBOOK_MAINTENANCE)"; \
|
||||
DESCRIPTION="all hosts"; \
|
||||
NEED_SUDO=""; \
|
||||
\
|
||||
@ -178,15 +320,15 @@ maintenance-verbose: ## Run maintenance with verbose output (usage: make mainten
|
||||
|
||||
docker: ## Install/configure Docker only
|
||||
@echo "$(YELLOW)Running Docker setup...$(RESET)"
|
||||
ansible-playbook dev-playbook.yml --tags docker
|
||||
$(ANSIBLE_PLAYBOOK) $(PLAYBOOK_DEV) --tags docker
|
||||
|
||||
shell: ## Configure shell only
|
||||
@echo "$(YELLOW)Running shell configuration...$(RESET)"
|
||||
ansible-playbook dev-playbook.yml --tags shell
|
||||
$(ANSIBLE_PLAYBOOK) $(PLAYBOOK_DEV) --tags shell
|
||||
|
||||
apps: ## Install applications only
|
||||
@echo "$(YELLOW)Installing applications...$(RESET)"
|
||||
ansible-playbook dev-playbook.yml --tags apps
|
||||
$(ANSIBLE_PLAYBOOK) $(PLAYBOOK_DEV) --tags apps
|
||||
|
||||
# Connectivity targets
|
||||
ping: ## Ping hosts with colored output (usage: make ping [GROUP=dev] [HOST=dev01])
|
||||
@ -254,11 +396,11 @@ clean: ## Clean up ansible artifacts
|
||||
# Debug targets
|
||||
debug: ## Run with debug output enabled
|
||||
@echo "$(YELLOW)Running with debug output...$(RESET)"
|
||||
ansible-playbook dev-playbook.yml -e "ansible_debug_output=true"
|
||||
$(ANSIBLE_PLAYBOOK) $(PLAYBOOK_DEV) -e "ansible_debug_output=true"
|
||||
|
||||
verbose: ## Run with verbose output
|
||||
@echo "$(YELLOW)Running with verbose output...$(RESET)"
|
||||
ansible-playbook dev-playbook.yml -vv
|
||||
$(ANSIBLE_PLAYBOOK) $(PLAYBOOK_DEV) -vv
|
||||
|
||||
# Quick development workflow
|
||||
quick: test check ## Quick test and check before applying
|
||||
@ -267,17 +409,17 @@ quick: test check ## Quick test and check before applying
|
||||
# Tailscale management
|
||||
tailscale: ## Install Tailscale on all machines
|
||||
@echo "$(YELLOW)Installing Tailscale on all machines...$(RESET)"
|
||||
ansible-playbook -i hosts tailscale-playbook.yml
|
||||
$(ANSIBLE_PLAYBOOK) $(PLAYBOOK_TAILSCALE)
|
||||
@echo "$(GREEN)✓ Tailscale installation complete$(RESET)"
|
||||
|
||||
tailscale-check: ## Check Tailscale installation (dry-run)
|
||||
@echo "$(YELLOW)Checking Tailscale installation...$(RESET)"
|
||||
ansible-playbook -i hosts tailscale-playbook.yml --check --diff
|
||||
$(ANSIBLE_PLAYBOOK) $(PLAYBOOK_TAILSCALE) --check --diff
|
||||
@echo "$(GREEN)✓ Tailscale check complete$(RESET)"
|
||||
|
||||
tailscale-dev: ## Install Tailscale on dev machines only
|
||||
@echo "$(YELLOW)Installing Tailscale on dev machines...$(RESET)"
|
||||
ansible-playbook -i hosts tailscale-playbook.yml --limit dev
|
||||
$(ANSIBLE_PLAYBOOK) $(PLAYBOOK_TAILSCALE) --limit dev
|
||||
@echo "$(GREEN)✓ Tailscale installation on dev machines complete$(RESET)"
|
||||
|
||||
tailscale-status: ## Check Tailscale status on all machines
|
||||
@ -286,7 +428,7 @@ tailscale-status: ## Check Tailscale status on all machines
|
||||
echo "$(BLUE)Auto-excluding current host: $(CURRENT_HOST) ($(CURRENT_IP))$(RESET)"; \
|
||||
fi
|
||||
@echo ""
|
||||
@ansible all -i hosts -m shell -a "tailscale status --json | jq -r '.Self.DNSName + \" (\" + .Self.TailscaleIPs[0] + \") - \" + .BackendState'" --become $(EXCLUDE_CURRENT) 2>/dev/null | while read line; do \
|
||||
@ansible all -m shell -a "tailscale status --json | jq -r '.Self.DNSName + \" (\" + .Self.TailscaleIPs[0] + \") - \" + .BackendState'" --become $(EXCLUDE_CURRENT) 2>/dev/null | while read line; do \
|
||||
host=$$(echo "$$line" | cut -d' ' -f1); \
|
||||
status=$$(echo "$$line" | grep -o "Running\|Stopped\|NeedsLogin" || echo "Unknown"); \
|
||||
ip=$$(echo "$$line" | grep -o "100\.[0-9.]*" || echo "No IP"); \
|
||||
@ -296,7 +438,7 @@ tailscale-status: ## Check Tailscale status on all machines
|
||||
elif echo "$$line" | grep -q "FAILED\|UNREACHABLE"; then \
|
||||
printf " $(RED)✗ %-20s$(RESET) Not available\n" "$$host"; \
|
||||
fi; \
|
||||
done || ansible all -i hosts -m shell -a "tailscale status" --become $(EXCLUDE_CURRENT) 2>/dev/null | grep -E "(SUCCESS|FAILED)" | while read line; do \
|
||||
done || ansible all -m shell -a "tailscale status" --become $(EXCLUDE_CURRENT) 2>/dev/null | grep -E "(SUCCESS|FAILED)" | while read line; do \
|
||||
host=$$(echo "$$line" | cut -d' ' -f1); \
|
||||
if echo "$$line" | grep -q "SUCCESS"; then \
|
||||
printf " $(GREEN)✓ %-20s$(RESET) Connected\n" "$$host"; \
|
||||
@ -376,15 +518,10 @@ create-vault: ## Create encrypted vault file for secrets (passwords, auth keys,
|
||||
|
||||
create-vm: ## Create Ansible controller VM on Proxmox
|
||||
@echo "$(YELLOW)Creating Ansible controller VM on Proxmox...$(RESET)"
|
||||
ansible-playbook proxmox-create-vm.yml --ask-vault-pass
|
||||
$(ANSIBLE_PLAYBOOK) $(PLAYBOOK_PROXMOX) --ask-vault-pass
|
||||
@echo "$(GREEN)✓ VM creation complete$(RESET)"
|
||||
|
||||
monitoring: ## Install monitoring tools on all machines
|
||||
@echo "$(YELLOW)Installing monitoring tools...$(RESET)"
|
||||
ansible-playbook -i hosts dev-playbook.yml --tags monitoring
|
||||
$(ANSIBLE_PLAYBOOK) $(PLAYBOOK_DEV) --tags monitoring
|
||||
@echo "$(GREEN)✓ Monitoring installation complete$(RESET)"
|
||||
|
||||
backup: ## Set up automated backups on all machines
|
||||
@echo "$(YELLOW)Setting up automated backups...$(RESET)"
|
||||
ansible-playbook -i hosts dev-playbook.yml --tags backup
|
||||
@echo "$(GREEN)✓ Backup setup complete$(RESET)"
|
||||
620
README.md
620
README.md
@ -1,508 +1,178 @@
|
||||
# Ansible Infrastructure Management
|
||||
|
||||
This Ansible project provides comprehensive infrastructure automation for development environments, server management, and VM provisioning across multiple machines and platforms.
|
||||
Comprehensive infrastructure automation for development environments, server management, and VM provisioning.
|
||||
|
||||
## 🏗️ Architecture
|
||||
## 📊 **Current Status**
|
||||
|
||||
### Host Groups
|
||||
- `dev`: Development machines (dev01, bottom, debianDesktopVM)
|
||||
- `gitea`: Gitea server (Alpine Linux)
|
||||
- `portainer`: Portainer container management (Alpine Linux)
|
||||
- `homepage`: Homepage dashboard (Debian)
|
||||
- `ansible`: Ansible control node
|
||||
- `local`: Local machine management
|
||||
### ✅ **Completed Infrastructure**
|
||||
- **Core System**: Base packages, SSH hardening, user management
|
||||
- **Development Environment**: Git, Node.js, Python, Docker, modern CLI tools
|
||||
- **Shell Configuration**: Zsh + Oh My Zsh + Powerlevel10k + plugins
|
||||
- **Applications**: VS Code, Cursor, Brave, LibreOffice, desktop tools
|
||||
- **Monitoring**: System monitoring tools + custom scripts (`sysinfo`, `netinfo`)
|
||||
- **VPN Mesh**: Tailscale integration with automated auth keys
|
||||
- **Security**: UFW firewall, fail2ban, SSH hardening
|
||||
- **Maintenance**: Automated package updates and system cleanup
|
||||
|
||||
### Roles
|
||||
### 🎯 **Next Priorities**
|
||||
1. **Enhanced monitoring**: Grafana + Prometheus dashboard
|
||||
2. **Security hardening**: ClamAV antivirus, Lynis auditing, vulnerability scanning
|
||||
3. **Centralized logging**: ELK stack for log aggregation
|
||||
4. **CI/CD pipeline**: GitLab Runner or Jenkins integration
|
||||
5. **Advanced security**: Intrusion detection, automated patching
|
||||
|
||||
#### Core Infrastructure Roles
|
||||
- **`maintenance`**: System updates, package cleanup, and automated reboots
|
||||
- **`base`**: Core system packages, security tools, and system hardening
|
||||
- **`ssh`**: SSH server hardening and firewall configuration
|
||||
- **`user`**: User management and configuration
|
||||
## 🚀 Quick Start
|
||||
|
||||
#### Development & Shell Roles
|
||||
- **`development`**: Development tools (git, nodejs, build-essential, python3)
|
||||
- **`shell`**: Shell configuration (zsh + oh-my-zsh + powerlevel10k)
|
||||
- **`docker`**: Docker CE installation and user configuration
|
||||
|
||||
#### Application Roles
|
||||
- **`applications`**: Desktop applications (Brave, LibreOffice, Redshift, Evince)
|
||||
- **`snap`**: Snap daemon and snap applications (VSCode, Cursor)
|
||||
|
||||
#### Network & Monitoring Roles
|
||||
- **`tailscale`**: VPN mesh networking across all machines
|
||||
- **`monitoring`**: System monitoring tools and scripts
|
||||
- **`backup`**: Automated backup solutions (✨ NEW)
|
||||
|
||||
#### Infrastructure Roles
|
||||
- **`proxmox_vm`**: Proxmox VM creation and management (✨ NEW)
|
||||
|
||||
## 🚀 Usage
|
||||
|
||||
### Quick Start with Makefile (Recommended)
|
||||
```bash
|
||||
# Setup dependencies
|
||||
# Install dependencies
|
||||
make bootstrap
|
||||
|
||||
# Test everything
|
||||
# Set up secrets management
|
||||
make create-vault
|
||||
|
||||
# Test configuration (comprehensive)
|
||||
make test
|
||||
|
||||
# Dry run to see what would change
|
||||
# Deploy to all hosts (dry run first)
|
||||
make check
|
||||
|
||||
# Apply to all development hosts
|
||||
make apply
|
||||
|
||||
# Run on specific host
|
||||
make dev HOST=dev01
|
||||
|
||||
# Run locally
|
||||
make local
|
||||
```
|
||||
|
||||
### New Infrastructure Features
|
||||
## 📚 Documentation
|
||||
|
||||
#### Proxmox VM Creation (✨ NEW)
|
||||
```bash
|
||||
# Create new VMs on Proxmox
|
||||
make create-vm
|
||||
### Getting Started
|
||||
- [**Initial Setup Guide**](docs/guides/setup.md) - First-time setup instructions
|
||||
- [**Ansible Vault Guide**](docs/guides/vault.md) - Managing secrets securely
|
||||
- [**Tailscale VPN Setup**](docs/guides/tailscale.md) - Mesh networking configuration
|
||||
|
||||
# Or manually:
|
||||
ansible-playbook proxmox-create-vm.yml
|
||||
### Reference
|
||||
- [**Installed Applications**](docs/reference/applications.md) - Complete software inventory
|
||||
- [**Makefile Commands**](docs/reference/makefile.md) - All available make targets
|
||||
- [**Architecture Overview**](docs/reference/architecture.md) - System design and structure
|
||||
|
||||
## 🏗️ Project Structure
|
||||
|
||||
```
|
||||
ansible/
|
||||
├── Makefile # Task automation
|
||||
├── ansible.cfg # Ansible configuration
|
||||
├── hosts # Inventory file
|
||||
├── collections/
|
||||
│ └── requirements.yml # Galaxy dependencies
|
||||
├── group_vars/ # Global variables
|
||||
│ ├── all.yml
|
||||
│ └── all/vault.yml # Encrypted secrets
|
||||
├── host_vars/ # Host-specific configs
|
||||
├── roles/ # Ansible roles
|
||||
│ ├── base/ # Core system setup
|
||||
│ ├── development/ # Dev tools
|
||||
│ ├── docker/ # Container platform
|
||||
│ ├── monitoring/ # System monitoring
|
||||
│ ├── tailscale/ # VPN networking
|
||||
│ └── ... # Additional roles
|
||||
├── playbooks/
|
||||
│ ├── dev-playbook.yml # Development setup
|
||||
│ ├── local-playbook.yml # Local machine
|
||||
│ ├── maintenance-playbook.yml
|
||||
│ └── tailscale-playbook.yml
|
||||
└── docs/ # Documentation
|
||||
├── guides/ # How-to guides
|
||||
└── reference/ # Technical reference
|
||||
```
|
||||
|
||||
#### Automated Backups (✨ NEW)
|
||||
```bash
|
||||
# Deploy backup system
|
||||
make backup
|
||||
|
||||
# Includes:
|
||||
# - Daily home directory backups (2:00 AM)
|
||||
# - Daily system config backups (2:30 AM)
|
||||
# - 7-day retention for home, 30-day for system
|
||||
# - Automated cleanup and logging
|
||||
```
|
||||
|
||||
#### System Monitoring (✨ NEW)
|
||||
```bash
|
||||
# Deploy monitoring tools
|
||||
make monitoring
|
||||
|
||||
# Includes:
|
||||
# - Advanced system monitoring (btop, iotop, nethogs)
|
||||
# - Custom monitoring scripts
|
||||
# - System information dashboards
|
||||
# - Tailscale network status integration
|
||||
```
|
||||
|
||||
#### Tailscale VPN Network
|
||||
```bash
|
||||
# Deploy Tailscale across all machines
|
||||
make tailscale
|
||||
|
||||
# Check Tailscale status
|
||||
make tailscale-status
|
||||
|
||||
# Deploy to development machines only
|
||||
make tailscale-dev
|
||||
```
|
||||
|
||||
### Prerequisites (Manual Setup)
|
||||
```bash
|
||||
# Install required collections
|
||||
ansible-galaxy collection install -r collections/requirements.yml
|
||||
```
|
||||
|
||||
### Vault Password Setup
|
||||
Host variables and sensitive data are encrypted with Ansible Vault:
|
||||
|
||||
#### Option 1: Vault Password File (Recommended)
|
||||
```bash
|
||||
# Create the vault password file
|
||||
echo "your_vault_password" > ~/.ansible-vault-pass
|
||||
chmod 600 ~/.ansible-vault-pass
|
||||
```
|
||||
|
||||
#### Option 2: Interactive Password Prompt
|
||||
Use `--ask-vault-pass` with each command.
|
||||
|
||||
### Vault Configuration
|
||||
Create vault files with encrypted secrets:
|
||||
```bash
|
||||
# Create/edit vault files
|
||||
make create-vault
|
||||
make edit-vault HOST=dev01
|
||||
|
||||
# Required vault variables:
|
||||
# - vault_tailscale_auth_key: "tskey-auth-your-key"
|
||||
# - vault_proxmox_host: "proxmox-server-ip"
|
||||
# - vault_proxmox_user: "root@pam"
|
||||
# - vault_proxmox_password: "proxmox-password"
|
||||
# - vault_vm_cipassword: "vm-user-password"
|
||||
# - vault_ssh_public_key: "ssh-ed25519 AAAA..."
|
||||
```
|
||||
|
||||
### Selective Execution with Tags
|
||||
|
||||
#### Using Makefile (Recommended)
|
||||
```bash
|
||||
# Infrastructure roles
|
||||
make security # Security-related roles only
|
||||
make monitoring # Monitoring tools only
|
||||
make backup # Backup system only
|
||||
|
||||
# Development tools
|
||||
make docker # Docker installation only
|
||||
make shell # Shell configuration only
|
||||
make apps # Applications only
|
||||
|
||||
# Network services
|
||||
make tailscale # VPN network setup
|
||||
make tailscale-status # Check VPN status
|
||||
|
||||
# Maintenance (unified system)
|
||||
make maintenance # All hosts
|
||||
make maintenance GROUP=dev # Specific group
|
||||
make maintenance HOST=dev01 # Specific host
|
||||
make maintenance CHECK=true # Dry-run all hosts
|
||||
make maintenance GROUP=dev SERIAL=1 # Serial execution
|
||||
|
||||
# Infrastructure management
|
||||
make create-vm # Create new Proxmox VMs
|
||||
make status # Check connectivity
|
||||
make facts # Gather system facts
|
||||
```
|
||||
|
||||
#### Manual Commands
|
||||
```bash
|
||||
# Security-related roles only
|
||||
ansible-playbook dev-playbook.yml --tags security
|
||||
|
||||
# Development tools only
|
||||
ansible-playbook dev-playbook.yml --tags development,docker
|
||||
|
||||
# Network services
|
||||
ansible-playbook tailscale-playbook.yml
|
||||
|
||||
# Infrastructure provisioning
|
||||
ansible-playbook proxmox-create-vm.yml
|
||||
|
||||
# Skip maintenance
|
||||
ansible-playbook dev-playbook.yml --skip-tags maintenance
|
||||
```
|
||||
|
||||
### Playbook Overview
|
||||
- **`dev-playbook.yml`**: Complete development environment setup
|
||||
- **`local-playbook.yml`**: Local machine configuration
|
||||
- **`tailscale-playbook.yml`**: VPN network deployment
|
||||
- **`proxmox-create-vm.yml`**: VM provisioning on Proxmox
|
||||
- **`maintenance-playbook.yml`**: System maintenance operations
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
### Global Variables (`group_vars/all.yml`)
|
||||
- `timezone`: System timezone (default: UTC)
|
||||
- `locale`: System locale (default: en_US.UTF-8)
|
||||
- `ansible_debug_output`: Show debug information (default: false)
|
||||
- `fail2ban_bantime`: Ban duration in seconds
|
||||
- `fail2ban_findtime`: Time window for failures
|
||||
- `fail2ban_maxretry`: Max failures before ban
|
||||
|
||||
### Tailscale Configuration
|
||||
- `tailscale_auth_key`: Authentication key (stored in vault)
|
||||
- `tailscale_accept_routes`: Accept subnet routes (default: true)
|
||||
- `tailscale_accept_dns`: Accept DNS settings (default: true)
|
||||
- `tailscale_ssh`: Enable SSH access through Tailscale (default: true)
|
||||
|
||||
### Backup Configuration (`roles/backup/defaults/main.yml`)
|
||||
- `backup_enable_cron`: Enable automated backups (default: true)
|
||||
- `backup_retention_days_home`: Home backup retention (default: 7)
|
||||
- `backup_retention_days_system`: System backup retention (default: 30)
|
||||
- `backup_users`: Users to backup (default: ['master', 'beast', 'ladmin', 'user'])
|
||||
|
||||
### SSH Configuration (`roles/ssh/defaults/main.yml`)
|
||||
Comprehensive security hardening:
|
||||
- `ssh_port`: SSH port (default: 22)
|
||||
- `ssh_permit_root_login`: Root login setting (default: 'no')
|
||||
- `ssh_password_authentication`: Password auth (default: 'no')
|
||||
- `ssh_max_auth_tries`: Authentication attempts (default: 3)
|
||||
- `ssh_allowed_users`: Restrict to specific users (default: [])
|
||||
- `ssh_allowed_groups`: Restrict to specific groups (default: ['sudo', 'ssh'])
|
||||
|
||||
### Proxmox VM Configuration (`roles/proxmox_vm/defaults/main.yml`)
|
||||
- `vm_memory`: RAM allocation (default: 8192MB)
|
||||
- `vm_cores`: CPU cores (default: 2)
|
||||
- `vm_disk_size`: Disk size (default: 20G)
|
||||
- `vm_iso`: Ubuntu Server ISO (default: ubuntu-24.04-live-server-amd64.iso)
|
||||
- `vm_ciuser`: Default user (default: master)
|
||||
|
||||
## 🛡️ Security Features
|
||||
|
||||
### Comprehensive SSH Hardening
|
||||
- Modern cryptographic algorithms (ChaCha20-Poly1305, AES-256-GCM)
|
||||
- Secure key exchange (Curve25519, DH Group 16)
|
||||
- Disabled password authentication
|
||||
- Connection rate limiting and timeouts
|
||||
- User/group access restrictions
|
||||
- Configuration validation and automatic backup
|
||||
|
||||
### Fail2ban Integration
|
||||
- SSH brute force protection
|
||||
- Configurable ban times and retry limits
|
||||
- Email notifications
|
||||
|
||||
### UFW Firewall
|
||||
- Deny-by-default policy
|
||||
- SSH access allowed
|
||||
- Automatic enablement
|
||||
|
||||
### Tailscale VPN Security
|
||||
- Zero-trust mesh networking
|
||||
- End-to-end encryption
|
||||
- SSH access through secure tunnel
|
||||
- Subnet routing capabilities
|
||||
|
||||
## 📦 Installed Packages
|
||||
|
||||
### Base System
|
||||
- **Core utilities**: `curl`, `wget`, `unzip`, `xclip`, `tree`
|
||||
- **Network/Security**: `net-tools`, `ufw`, `fail2ban`, `mailutils`
|
||||
- **Monitoring**: `iotop`, `nethogs`, `logwatch`, `btop` (via snap)
|
||||
- **Modern CLI**: `jq`, `yq` (via snap), `ripgrep`, `fd-find`
|
||||
|
||||
### Development Tools
|
||||
- `git`, `nodejs`, `npm`
|
||||
- `build-essential`, `python3`, `python3-pip`
|
||||
|
||||
### Applications
|
||||
- `brave-browser`, `libreoffice`, `evince`, `redshift`
|
||||
- `code` (VSCode), `cursor` (via snap)
|
||||
|
||||
### Docker & Containers
|
||||
- Docker CE with all components
|
||||
- Docker Compose
|
||||
- User added to docker group
|
||||
|
||||
### Backup Tools (✨ NEW)
|
||||
- `rsync`, `borgbackup`, `rclone`, `restic`
|
||||
- Automated backup scripts and cron jobs
|
||||
|
||||
### Monitoring Tools (✨ NEW)
|
||||
- `htop`, `iotop`, `nethogs`, `btop`
|
||||
- Custom system information scripts
|
||||
- Network monitoring utilities
|
||||
|
||||
### VPN & Network
|
||||
- `tailscale` - Mesh VPN networking
|
||||
- Network utilities and monitoring
|
||||
|
||||
## 🔧 Modern CLI Tools
|
||||
|
||||
The base role installs modern replacements for traditional Unix tools:
|
||||
|
||||
### Available Commands
|
||||
```bash
|
||||
# Fast searching
|
||||
rg "pattern" files/ # ripgrep - faster than grep
|
||||
fd "filename" # fd-find - intuitive find replacement
|
||||
|
||||
# Data processing
|
||||
jq '.key' file.json # JSON processor and formatter
|
||||
yq '.key' file.yaml # YAML processor and formatter
|
||||
|
||||
# System monitoring
|
||||
btop # Modern system monitor (better than htop)
|
||||
tree directory/ # Directory structure visualization
|
||||
|
||||
# File operations
|
||||
tree -L 2 # Limit tree depth
|
||||
rg -i "case insensitive" # Case-insensitive search
|
||||
fd -e yml # Find only YAML files
|
||||
jq -r '.items[].name' # Raw JSON output
|
||||
```
|
||||
|
||||
## 🔄 Maintenance & Operations
|
||||
|
||||
### Unified Maintenance System
|
||||
```bash
|
||||
# Basic usage
|
||||
make maintenance # Run on all hosts
|
||||
make maintenance GROUP=dev # Run on specific group
|
||||
make maintenance HOST=dev01 # Run on specific host
|
||||
|
||||
# Advanced options
|
||||
make maintenance CHECK=true # Dry-run (safe testing)
|
||||
make maintenance GROUP=dev SERIAL=1 # One host at a time
|
||||
make maintenance GROUP=local # Local machine (auto-sudo)
|
||||
```
|
||||
|
||||
### Backup Operations (✨ NEW)
|
||||
```bash
|
||||
# Deploy backup system
|
||||
make backup
|
||||
|
||||
# Manual backup operations
|
||||
sudo /opt/backups/scripts/backup-home.sh # Run home backup
|
||||
sudo /opt/backups/scripts/backup-system.sh # Run system backup
|
||||
|
||||
# Check backup logs
|
||||
tail -f /var/log/backups/home.log
|
||||
tail -f /var/log/backups/system.log
|
||||
```
|
||||
|
||||
### Monitoring Operations (✨ NEW)
|
||||
```bash
|
||||
# Deploy monitoring tools
|
||||
make monitoring
|
||||
|
||||
# Use monitoring scripts
|
||||
/usr/local/bin/monitoring/sysinfo # System information dashboard
|
||||
/usr/local/bin/monitoring/netinfo # Network information
|
||||
|
||||
# System monitoring
|
||||
btop # Interactive system monitor
|
||||
```
|
||||
|
||||
### Tailscale Network Management
|
||||
```bash
|
||||
# Deploy VPN network
|
||||
make tailscale
|
||||
|
||||
# Check status across all machines
|
||||
make tailscale-status
|
||||
|
||||
# Manual Tailscale commands
|
||||
tailscale status # Check connection status
|
||||
tailscale ip # Show Tailscale IP
|
||||
tailscale netcheck # Network connectivity check
|
||||
```
|
||||
|
||||
### Infrastructure Provisioning (✨ NEW)
|
||||
```bash
|
||||
# Create new VMs on Proxmox
|
||||
make create-vm
|
||||
|
||||
# Custom VM creation
|
||||
ansible-playbook proxmox-create-vm.yml -e "vm_name=new-server vm_id=111"
|
||||
```
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **SSH Connection Issues**
|
||||
- Check `ansible.cfg` SSH settings
|
||||
- Verify host keys and user permissions
|
||||
- Test Tailscale connectivity: `tailscale ping hostname`
|
||||
|
||||
2. **Vault Access Issues**
|
||||
- Verify vault password file: `~/.ansible-vault-pass`
|
||||
- Test vault decryption: `ansible-vault view host_vars/hostname.yml`
|
||||
|
||||
3. **Tailscale Connection Issues**
|
||||
- Check service status: `sudo systemctl status tailscaled`
|
||||
- Verify auth key in vault
|
||||
- Check firewall: `sudo ufw status`
|
||||
|
||||
4. **Proxmox VM Creation Issues**
|
||||
- Verify Proxmox credentials in vault
|
||||
- Check ISO availability: `pvesm list local --content iso`
|
||||
- Ensure sufficient resources on Proxmox node
|
||||
|
||||
5. **Backup Issues**
|
||||
- Check backup directories: `ls -la /opt/backups/`
|
||||
- Review logs: `tail -f /var/log/backups/*.log`
|
||||
- Verify cron jobs: `sudo crontab -l`
|
||||
|
||||
### Debug Commands
|
||||
```bash
|
||||
# Using Makefile
|
||||
make status # Test connectivity to all hosts
|
||||
make facts # Gather facts from all hosts
|
||||
make debug # Run with debug output
|
||||
make verbose # Run with verbose output
|
||||
|
||||
# Manual commands
|
||||
ansible dev -m ping # Test connectivity
|
||||
ansible dev -m setup # Check facts
|
||||
ansible-playbook dev-playbook.yml --tags base # Run specific role
|
||||
|
||||
# Verify installations
|
||||
ansible dev -m shell -a "tailscale status" # Check Tailscale
|
||||
ansible dev -m shell -a "docker --version" # Check Docker
|
||||
ansible dev -m shell -a "sudo sshd -t" # Validate SSH config
|
||||
```
|
||||
|
||||
## 🛠️ Makefile Workflows
|
||||
|
||||
### Development Workflow
|
||||
```bash
|
||||
make bootstrap # Install collections
|
||||
make test # Lint + syntax check
|
||||
make check # Dry run
|
||||
make apply # Deploy to all hosts
|
||||
```
|
||||
## 🎯 Key Features
|
||||
|
||||
### Infrastructure Management
|
||||
- **Automated Provisioning**: Proxmox VM creation and configuration
|
||||
- **Configuration Management**: Consistent setup across all machines
|
||||
- **Network Security**: Tailscale VPN mesh networking
|
||||
- **System Maintenance**: Automated updates and cleanup
|
||||
|
||||
### Development Environment
|
||||
- **Shell Environment**: Zsh + Oh My Zsh + Powerlevel10k
|
||||
- **Container Platform**: Docker CE with Compose
|
||||
- **Development Tools**: Node.js, Python, Git, build tools
|
||||
- **Code Editors**: VS Code, Cursor IDE
|
||||
|
||||
### Security & Monitoring
|
||||
- **SSH Hardening**: Modern crypto, key-only auth, fail2ban
|
||||
- **Firewall**: UFW with sensible defaults
|
||||
- **Monitoring Tools**: btop, iotop, nethogs, custom dashboards
|
||||
|
||||
## 🧪 Testing & Validation
|
||||
|
||||
### Comprehensive Testing
|
||||
```bash
|
||||
make create-vm # Provision new VMs
|
||||
make tailscale # Deploy VPN network
|
||||
make monitoring # Deploy monitoring
|
||||
make backup # Deploy backup system
|
||||
make test # Full test suite (lint + syntax + validation)
|
||||
make test-syntax # Syntax and configuration validation only
|
||||
make lint # Ansible-lint only
|
||||
```
|
||||
|
||||
### Host-Specific Operations
|
||||
### Testing Coverage
|
||||
- **Playbook syntax**: All main playbooks and infrastructure playbooks
|
||||
- **Role validation**: All role test playbooks
|
||||
- **Configuration files**: YAML and INI file validation
|
||||
- **Documentation**: Markdown syntax and link checking (installed via `make bootstrap`)
|
||||
- **Linting**: Full Ansible best practices validation
|
||||
|
||||
## 🖥️ Managed Hosts
|
||||
|
||||
| Host | Type | OS | Purpose |
|
||||
|------|------|-----|---------|
|
||||
| dev01 | Physical | Debian | Primary development |
|
||||
| bottom | Physical | Debian | Secondary development |
|
||||
| debianDesktopVM | VM | Debian | Desktop environment |
|
||||
| giteaVM | VM | Alpine | Git repository hosting |
|
||||
| portainerVM | VM | Alpine | Container management |
|
||||
| homepageVM | VM | Debian | Service dashboard |
|
||||
|
||||
## 🔧 Common Tasks
|
||||
|
||||
```bash
|
||||
make dev HOST=dev01 # Deploy to specific host
|
||||
make edit-vault HOST=dev01 # Edit encrypted host variables
|
||||
make tailscale-dev # Deploy Tailscale to dev hosts only
|
||||
# System Maintenance
|
||||
make maintenance # Update all systems
|
||||
make maintenance HOST=dev01 # Update specific host
|
||||
|
||||
# Development Setup
|
||||
make docker # Install Docker
|
||||
make shell # Configure shell
|
||||
make apps # Install applications
|
||||
|
||||
# Network & Security
|
||||
make tailscale # Deploy VPN
|
||||
make security # Security hardening
|
||||
make monitoring # Deploy monitoring
|
||||
|
||||
# Infrastructure
|
||||
make create-vm # Create new VM
|
||||
make status # Check connectivity
|
||||
make facts # Gather system info
|
||||
```
|
||||
|
||||
### Maintenance and Utilities
|
||||
```bash
|
||||
make clean # Clean up artifacts
|
||||
make status # Check host connectivity
|
||||
make install-tools # Install recommended CLI tools locally
|
||||
```
|
||||
## 🛠️ Requirements
|
||||
|
||||
Run `make help` for the complete list of available commands.
|
||||
### Control Machine (where you run Ansible)
|
||||
- Python 3.x with `pipx` (recommended) or `pip3`
|
||||
- Node.js and `npm` (for documentation testing)
|
||||
- SSH access to target hosts
|
||||
- Ansible Vault password (for secrets)
|
||||
|
||||
## 📝 File Structure
|
||||
ansible/
|
||||
├── ansible.cfg # Enhanced Ansible configuration
|
||||
├── Makefile # Workflow automation with unified maintenance
|
||||
├── hosts # Inventory file
|
||||
├── dev-playbook.yml # Main development playbook
|
||||
├── local-playbook.yml # Local machine setup
|
||||
├── tailscale-playbook.yml # VPN network deployment
|
||||
├── proxmox-create-vm.yml # VM provisioning playbook
|
||||
├── maintenance-playbook.yml # Dedicated maintenance playbook
|
||||
├── collections/
|
||||
│ └── requirements.yml # Required Ansible collections
|
||||
├── group_vars/
|
||||
│ └── all.yml # Global variables and Tailscale config
|
||||
├── host_vars/ # Host-specific variables (encrypted)
|
||||
└── roles/
|
||||
├── maintenance/ # System maintenance
|
||||
├── base/ # Core system setup
|
||||
├── development/ # Development tools
|
||||
├── shell/ # Shell configuration (zsh + oh-my-zsh)
|
||||
├── docker/ # Docker installation
|
||||
├── ssh/ # SSH hardening and configuration
|
||||
├── user/ # User management
|
||||
├── applications/ # Desktop applications
|
||||
├── snap/ # Snap applications
|
||||
├── tailscale/ # VPN mesh networking
|
||||
├── monitoring/ # System monitoring tools
|
||||
├── backup/ # Automated backup solutions
|
||||
└── proxmox_vm/ # VM provisioning on Proxmox
|
||||
### Target Hosts
|
||||
- SSH server running
|
||||
- Python 3.x
|
||||
- `sudo` access for the Ansible user
|
||||
|
||||
### Dependency Management
|
||||
All project dependencies are managed through standard requirements files:
|
||||
- **`requirements.txt`** - Python packages (ansible, ansible-lint, etc.)
|
||||
- **`package.json`** - Node.js packages (markdown tools)
|
||||
- **`collections/requirements.yml`** - Ansible collections
|
||||
|
||||
## 🤝 Contributing
|
||||
**Setup**: Run `make bootstrap` to install all dependencies automatically.
|
||||
|
||||
1. Test changes with `--check` first
|
||||
2. Update documentation for new roles/tasks
|
||||
3. Use proper handlers for service restarts
|
||||
4. Follow existing naming conventions
|
||||
5. Encrypt sensitive data with ansible-vault
|
||||
6. Test across different OS distributions (Ubuntu, Debian, Alpine)
|
||||
## 📝 Contributing
|
||||
|
||||
1. Test changes with `make check` (dry run)
|
||||
2. Follow existing patterns and naming conventions
|
||||
3. Update documentation for new features
|
||||
4. Encrypt sensitive data with Ansible Vault
|
||||
@ -1,61 +0,0 @@
|
||||
# Simple Tailscale Setup
|
||||
|
||||
## What you need:
|
||||
1. A Tailscale account (free at https://tailscale.com)
|
||||
2. An auth key from your Tailscale admin console
|
||||
|
||||
## 3-Step Setup:
|
||||
|
||||
### Step 1: Get your auth key
|
||||
1. Go to https://login.tailscale.com/admin/settings/keys
|
||||
2. Click "Generate auth key"
|
||||
3. Make it **Reusable** and set expiration to **90 days** (or longer)
|
||||
4. Copy the key (starts with `tskey-auth-`)
|
||||
|
||||
### Step 2: Store the key securely
|
||||
```bash
|
||||
make create-vault
|
||||
```
|
||||
When prompted, add this content:
|
||||
```yaml
|
||||
---
|
||||
vault_tailscale_auth_key: "tskey-auth-your-actual-key-here"
|
||||
```
|
||||
Save and exit.
|
||||
|
||||
### Step 3: Install Tailscale everywhere
|
||||
```bash
|
||||
# Check what will happen (dry run)
|
||||
make tailscale-check
|
||||
|
||||
# Install on all machines
|
||||
make tailscale
|
||||
```
|
||||
|
||||
That's it! Your machines should now be connected to your Tailscale network.
|
||||
|
||||
## Check if it worked:
|
||||
```bash
|
||||
make tailscale-status
|
||||
```
|
||||
|
||||
## How the vault connects to your settings:
|
||||
|
||||
The `group_vars/all.yml` file now contains:
|
||||
```yaml
|
||||
tailscale_auth_key: "{{ vault_tailscale_auth_key | default('') }}"
|
||||
```
|
||||
|
||||
This tells Ansible: "Look for `vault_tailscale_auth_key` in the encrypted vault file, and if it's not there, use an empty string."
|
||||
|
||||
So when you put your real auth key in the vault, it automatically gets used!
|
||||
|
||||
## The confusing variables explained:
|
||||
|
||||
- `tailscale_auth_key`: **YOU NEED THIS** - your authentication key
|
||||
- `tailscale_ssh`: **USEFUL** - lets you SSH through Tailscale network
|
||||
- `tailscale_accept_routes`: **USEFUL** - access other networks through Tailscale
|
||||
- `tailscale_hostname`: **OPTIONAL** - custom name (defaults to your server names)
|
||||
- `tailscale_advertise_routes`: **ADVANCED** - share your local network with others
|
||||
- `tailscale_shields_up`: **SECURITY** - blocks incoming connections
|
||||
- Everything else: **IGNORE** unless you have specific enterprise needs
|
||||
@ -1,108 +0,0 @@
|
||||
# Tailscale Setup Guide
|
||||
|
||||
This guide will help you deploy Tailscale across all your machines using Ansible.
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. **Get your Tailscale auth key**:
|
||||
- Go to https://login.tailscale.com/admin/settings/keys
|
||||
- Generate a new auth key (preferably reusable and non-expiring for automation)
|
||||
|
||||
2. **Store the auth key securely**:
|
||||
```bash
|
||||
make create-vault
|
||||
```
|
||||
Add this content to the vault file:
|
||||
```yaml
|
||||
---
|
||||
vault_tailscale_auth_key: "tskey-auth-your-actual-key-here"
|
||||
```
|
||||
|
||||
3. **Install Tailscale on all machines**:
|
||||
```bash
|
||||
# Dry run first to check what will happen
|
||||
make tailscale-check
|
||||
|
||||
# Install on all machines
|
||||
make tailscale
|
||||
```
|
||||
|
||||
## Available Commands
|
||||
|
||||
- `make tailscale` - Install Tailscale on all machines
|
||||
- `make tailscale-check` - Dry run to see what changes will be made
|
||||
- `make tailscale-dev` - Install only on dev machines
|
||||
- `make tailscale-status` - Check Tailscale status on all machines
|
||||
|
||||
## Manual Installation Options
|
||||
|
||||
### Install on specific machines:
|
||||
```bash
|
||||
ansible-playbook -i hosts tailscale-playbook.yml --limit "devVM,bottom"
|
||||
```
|
||||
|
||||
### Install with custom auth key:
|
||||
```bash
|
||||
ansible-playbook -i hosts tailscale-playbook.yml --extra-vars "tailscale_auth_key=your-key-here"
|
||||
```
|
||||
|
||||
### Install as part of existing playbooks:
|
||||
The Tailscale role has been added to both `dev-playbook.yml` and `local-playbook.yml` with the tag `tailscale`.
|
||||
|
||||
Run only Tailscale tasks:
|
||||
```bash
|
||||
ansible-playbook -i hosts dev-playbook.yml --tags tailscale
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
You can customize Tailscale behavior by setting these variables in `group_vars/all.yml` or `host_vars/hostname.yml`:
|
||||
|
||||
```yaml
|
||||
tailscale_auth_key: "{{ vault_tailscale_auth_key }}" # Auth key from vault
|
||||
tailscale_hostname: "{{ inventory_hostname }}" # Custom hostname
|
||||
tailscale_accept_routes: true # Accept subnet routes
|
||||
tailscale_accept_dns: true # Accept DNS settings
|
||||
tailscale_ssh: true # Enable SSH server
|
||||
tailscale_advertise_routes: "192.168.1.0/24" # Advertise subnets
|
||||
tailscale_shields_up: false # Block incoming connections
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Check if Tailscale is running:
|
||||
```bash
|
||||
make tailscale-status
|
||||
```
|
||||
|
||||
### Manual connection (if auth key wasn't provided):
|
||||
```bash
|
||||
# SSH to the machine and run:
|
||||
sudo tailscale up
|
||||
```
|
||||
|
||||
### Reset connection:
|
||||
```bash
|
||||
ansible-playbook -i hosts tailscale-playbook.yml --extra-vars "tailscale_reset=true"
|
||||
```
|
||||
|
||||
### View logs:
|
||||
```bash
|
||||
# On the target machine:
|
||||
sudo journalctl -u tailscaled -f
|
||||
```
|
||||
|
||||
## Security Notes
|
||||
|
||||
- Store your Tailscale auth key in Ansible Vault for security
|
||||
- Consider using ephemeral auth keys for one-time setups
|
||||
- The role enables SSH by default - disable if not needed
|
||||
- Machines will need to be authorized in your Tailscale admin console
|
||||
|
||||
## Supported Operating Systems
|
||||
|
||||
- Ubuntu (focal, jammy, noble)
|
||||
- Debian (bullseye, bookworm, trixie)
|
||||
- Alpine Linux (all versions)
|
||||
|
||||
The role automatically detects the OS and uses the appropriate package manager (apt for Ubuntu/Debian, apk for Alpine).
|
||||
@ -1,76 +0,0 @@
|
||||
# How Ansible Vault Works
|
||||
|
||||
## The Problem:
|
||||
You need to store secrets (like Tailscale auth keys) but don't want them visible in your code.
|
||||
|
||||
## The Solution:
|
||||
Ansible Vault encrypts files so secrets are hidden but still usable.
|
||||
|
||||
## Here's how it works:
|
||||
|
||||
### 1. Create the encrypted vault file:
|
||||
```bash
|
||||
make create-vault
|
||||
```
|
||||
This creates `group_vars/all/vault.yml` (encrypted) and asks for a password.
|
||||
|
||||
### 2. Add your secrets to the vault:
|
||||
When the editor opens, add:
|
||||
```yaml
|
||||
---
|
||||
vault_tailscale_auth_key: "tskey-auth-your-actual-key-here"
|
||||
vault_database_password: "super-secret-password"
|
||||
vault_api_key: "another-secret"
|
||||
```
|
||||
|
||||
### 3. Reference secrets in your code:
|
||||
In any playbook or role, use:
|
||||
```yaml
|
||||
tailscale_auth_key: "{{ vault_tailscale_auth_key }}"
|
||||
```
|
||||
|
||||
## File Structure:
|
||||
```
|
||||
group_vars/
|
||||
├── all.yml # Plain text settings (everyone can see)
|
||||
└── all/
|
||||
└── vault.yml # Encrypted secrets (protected)
|
||||
```
|
||||
|
||||
## How Ansible finds the auth key:
|
||||
|
||||
1. **Playbook runs** → looks for `tailscale_auth_key` variable
|
||||
2. **Checks `all.yml`** → finds reference to `{{ vault_tailscale_auth_key }}`
|
||||
3. **Checks `all/vault.yml`** → finds the encrypted auth key
|
||||
4. **Decrypts and uses it** → connects to Tailscale
|
||||
|
||||
## Commands:
|
||||
```bash
|
||||
# Create new vault
|
||||
make create-vault
|
||||
|
||||
# Edit existing vault
|
||||
ansible-vault edit group_vars/all/vault.yml
|
||||
|
||||
# View vault contents (decrypted)
|
||||
ansible-vault view group_vars/all/vault.yml
|
||||
|
||||
# Run playbooks (will ask for vault password)
|
||||
make tailscale
|
||||
# OR provide password file
|
||||
ansible-playbook -i hosts tailscale-playbook.yml --vault-password-file ~/.vault_pass
|
||||
```
|
||||
|
||||
## No code changes needed!
|
||||
The playbook already looks for `vault_tailscale_auth_key` - just put your real key in the vault and it works automatically.
|
||||
|
||||
## What's NOT in the vault:
|
||||
- Regular settings (in `all.yml`)
|
||||
- Non-sensitive configuration
|
||||
- Public information
|
||||
|
||||
## What IS in the vault:
|
||||
- Auth keys
|
||||
- Passwords
|
||||
- Private keys
|
||||
- Any sensitive data
|
||||
@ -1,5 +1,5 @@
|
||||
[defaults]
|
||||
inventory = hosts
|
||||
inventory = inventories/production
|
||||
roles_path = roles
|
||||
host_key_checking = False
|
||||
stdout_callback = yaml
|
||||
@ -15,7 +15,8 @@ forks = 20
|
||||
pipelining = True
|
||||
callbacks_enabled = profile_tasks,timer
|
||||
vault_password_file = ~/.ansible-vault-pass
|
||||
become_ask_pass = True
|
||||
# become_ask_pass = True # Use --ask-become-pass in Makefile instead
|
||||
ansible_managed = Ansible managed: {file} modified on %Y-%m-%d %H:%M:%S
|
||||
|
||||
[ssh_connection]
|
||||
ssh_args = -o ControlMaster=auto -o ControlPersist=60s
|
||||
|
||||
@ -1,28 +0,0 @@
|
||||
- name: Configure development environment
|
||||
hosts: dev
|
||||
become: true
|
||||
|
||||
roles:
|
||||
- { role: maintenance, tags: ['maintenance'] }
|
||||
- { role: base, tags: ['base', 'security'] }
|
||||
- { role: user, tags: ['user'] }
|
||||
- { role: ssh, tags: ['ssh', 'security'] }
|
||||
- { role: shell, tags: ['shell'] }
|
||||
- { role: development, tags: ['development', 'dev'] }
|
||||
- { role: docker, tags: ['docker'] }
|
||||
- { role: applications, tags: ['applications', 'apps'] }
|
||||
- { role: snap, tags: ['snap', 'apps'] }
|
||||
- { role: tailscale, tags: ['tailscale', 'vpn'] }
|
||||
- { role: monitoring, tags: ['monitoring'] }
|
||||
# - { role: backup, tags: ['backup'] }
|
||||
|
||||
pre_tasks:
|
||||
- name: Update apt cache
|
||||
ansible.builtin.apt:
|
||||
update_cache: true
|
||||
|
||||
tasks:
|
||||
# Additional tasks can be added here if needed
|
||||
- name: Display completion message
|
||||
ansible.builtin.debug:
|
||||
msg: "Development environment setup completed successfully!"
|
||||
236
docs/guides/setup.md
Normal file
236
docs/guides/setup.md
Normal file
@ -0,0 +1,236 @@
|
||||
# Initial Setup Guide
|
||||
|
||||
Complete guide for setting up your Ansible infrastructure management system.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Control Machine Requirements:**
|
||||
- Linux/macOS/WSL
|
||||
- Python 3.x installed
|
||||
- Git installed
|
||||
- SSH client
|
||||
|
||||
- **Target Machine Requirements:**
|
||||
- SSH server running
|
||||
- Python 3.x installed
|
||||
- User with sudo privileges
|
||||
|
||||
## Step 1: Clone Repository
|
||||
|
||||
```bash
|
||||
git clone <your-repo-url>
|
||||
cd ansible
|
||||
```
|
||||
|
||||
## Step 2: Install Ansible
|
||||
|
||||
### Ubuntu/Debian
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install ansible python3-pip
|
||||
```
|
||||
|
||||
### macOS
|
||||
```bash
|
||||
brew install ansible
|
||||
```
|
||||
|
||||
### Python pip
|
||||
```bash
|
||||
pip3 install ansible
|
||||
```
|
||||
|
||||
## Step 3: Install Dependencies
|
||||
|
||||
```bash
|
||||
# Install required Ansible collections
|
||||
make bootstrap
|
||||
|
||||
# Or manually:
|
||||
ansible-galaxy collection install -r collections/requirements.yml
|
||||
```
|
||||
|
||||
## Step 4: Configure Inventory
|
||||
|
||||
Edit `hosts` file to match your infrastructure:
|
||||
|
||||
```ini
|
||||
[dev]
|
||||
dev01 ansible_host=192.168.1.100
|
||||
bottom ansible_host=192.168.1.101
|
||||
debianDesktopVM ansible_host=192.168.1.102
|
||||
|
||||
[local]
|
||||
localhost ansible_connection=local
|
||||
|
||||
[gitea]
|
||||
giteaVM ansible_host=192.168.1.110
|
||||
|
||||
[portainer]
|
||||
portainerVM ansible_host=192.168.1.111
|
||||
```
|
||||
|
||||
## Step 5: Set Up SSH Access
|
||||
|
||||
### Generate SSH Key (if needed)
|
||||
```bash
|
||||
ssh-keygen -t ed25519 -C "ansible@control"
|
||||
```
|
||||
|
||||
### Copy Key to Hosts
|
||||
```bash
|
||||
ssh-copy-id user@dev01
|
||||
ssh-copy-id user@bottom
|
||||
# Repeat for all hosts
|
||||
```
|
||||
|
||||
### Test Connection
|
||||
```bash
|
||||
make status
|
||||
# Or:
|
||||
ansible all -m ping
|
||||
```
|
||||
|
||||
## Step 6: Configure Vault
|
||||
|
||||
Vault stores sensitive data like passwords and API keys.
|
||||
|
||||
### Create Vault Password
|
||||
```bash
|
||||
# Option 1: Password file (recommended)
|
||||
echo "your-secure-password" > ~/.ansible-vault-pass
|
||||
chmod 600 ~/.ansible-vault-pass
|
||||
|
||||
# Option 2: Use interactive prompt (add --ask-vault-pass to commands)
|
||||
```
|
||||
|
||||
### Create Vault File
|
||||
```bash
|
||||
make create-vault
|
||||
```
|
||||
|
||||
### Add Required Secrets
|
||||
Add these variables when the editor opens:
|
||||
```yaml
|
||||
---
|
||||
# Tailscale (if using VPN)
|
||||
vault_tailscale_auth_key: "tskey-auth-..."
|
||||
|
||||
# Proxmox (if creating VMs)
|
||||
vault_proxmox_host: "192.168.1.10"
|
||||
vault_proxmox_user: "root@pam"
|
||||
vault_proxmox_password: "proxmox-password"
|
||||
vault_vm_cipassword: "vm-default-password"
|
||||
|
||||
# SSH Keys
|
||||
vault_ssh_public_key: "ssh-ed25519 AAAA..."
|
||||
```
|
||||
|
||||
## Step 7: Configure Variables
|
||||
|
||||
### Global Settings
|
||||
Edit `group_vars/all.yml`:
|
||||
```yaml
|
||||
# Timezone and locale
|
||||
timezone: "America/New_York" # Your timezone
|
||||
locale: "en_US.UTF-8"
|
||||
|
||||
# User configuration
|
||||
default_user: "your-username"
|
||||
default_shell: "/usr/bin/zsh"
|
||||
|
||||
# Security settings
|
||||
ssh_port: 22
|
||||
ssh_permit_root_login: "no"
|
||||
```
|
||||
|
||||
### Host-Specific Settings
|
||||
Create/edit `host_vars/hostname.yml` for host-specific configuration.
|
||||
|
||||
## Step 8: Test Configuration
|
||||
|
||||
Always test before applying changes:
|
||||
|
||||
```bash
|
||||
# Dry run on all hosts
|
||||
make check
|
||||
|
||||
# Dry run on specific host
|
||||
make check HOST=dev01
|
||||
|
||||
# Check specific role
|
||||
ansible-playbook dev-playbook.yml --check --tags docker
|
||||
```
|
||||
|
||||
## Step 9: Deploy
|
||||
|
||||
### Full Deployment
|
||||
```bash
|
||||
# Deploy to all development hosts
|
||||
make apply
|
||||
|
||||
# Deploy to specific host
|
||||
make dev HOST=dev01
|
||||
```
|
||||
|
||||
### Selective Deployment
|
||||
```bash
|
||||
# Install only Docker
|
||||
make docker
|
||||
|
||||
# Configure only shell
|
||||
make shell
|
||||
|
||||
# Deploy Tailscale VPN
|
||||
make tailscale
|
||||
```
|
||||
|
||||
## Step 10: Verify Installation
|
||||
|
||||
```bash
|
||||
# Check system status
|
||||
make status
|
||||
|
||||
# Gather facts
|
||||
make facts
|
||||
|
||||
# Check specific services
|
||||
ansible dev -m shell -a "docker --version"
|
||||
ansible dev -m shell -a "tailscale status"
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
|
||||
### SSH Connection Failed
|
||||
- Verify SSH keys are copied: `ssh-copy-id user@host`
|
||||
- Check SSH service: `ssh user@host`
|
||||
- Verify inventory file has correct IP/hostname
|
||||
|
||||
### Vault Password Issues
|
||||
- Check vault password file exists and has correct permissions
|
||||
- Verify password is correct: `ansible-vault view group_vars/all/vault.yml`
|
||||
|
||||
### Python Not Found
|
||||
- Install Python on target: `sudo apt install python3`
|
||||
- Set Python interpreter in inventory:
|
||||
```ini
|
||||
dev01 ansible_host=192.168.1.100 ansible_python_interpreter=/usr/bin/python3
|
||||
```
|
||||
|
||||
### Sudo Password Required
|
||||
- Configure passwordless sudo for automation user
|
||||
- Or use `--ask-become-pass` flag
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. [Configure Tailscale VPN](./tailscale.md) for secure networking
|
||||
2. [Set up security hardening](./security.md)
|
||||
3. [Deploy monitoring](./monitoring.md)
|
||||
4. [Create custom roles](./custom-roles.md) for your specific needs
|
||||
|
||||
## Getting Help
|
||||
|
||||
- Run `make help` for available commands
|
||||
- Check role README files in `roles/*/README.md`
|
||||
- Review example playbooks in repository
|
||||
- Check Ansible documentation at https://docs.ansible.com
|
||||
129
docs/guides/tailscale.md
Normal file
129
docs/guides/tailscale.md
Normal file
@ -0,0 +1,129 @@
|
||||
# Tailscale VPN Setup Guide
|
||||
|
||||
Tailscale provides secure mesh networking across all your machines with zero-config VPN connectivity.
|
||||
|
||||
## Prerequisites
|
||||
- Tailscale account (free at https://tailscale.com)
|
||||
- Auth key from Tailscale admin console
|
||||
|
||||
## Quick Setup (3 Steps)
|
||||
|
||||
### 1. Get Your Auth Key
|
||||
1. Visit https://login.tailscale.com/admin/settings/keys
|
||||
2. Click "Generate auth key"
|
||||
3. Configure key:
|
||||
- **Reusable**: Yes (for multiple machines)
|
||||
- **Expiration**: 90 days or longer
|
||||
4. Copy the key (starts with `tskey-auth-`)
|
||||
|
||||
### 2. Store Key Securely
|
||||
```bash
|
||||
make create-vault
|
||||
```
|
||||
Add this content when prompted:
|
||||
```yaml
|
||||
---
|
||||
vault_tailscale_auth_key: "tskey-auth-your-actual-key-here"
|
||||
```
|
||||
|
||||
### 3. Deploy Tailscale
|
||||
```bash
|
||||
# Preview changes (dry run)
|
||||
make tailscale-check
|
||||
|
||||
# Install on all machines
|
||||
make tailscale
|
||||
|
||||
# Check status
|
||||
make tailscale-status
|
||||
```
|
||||
|
||||
## Deployment Options
|
||||
|
||||
### Target Specific Machines
|
||||
```bash
|
||||
# Development machines only
|
||||
make tailscale-dev
|
||||
|
||||
# Specific hosts
|
||||
ansible-playbook tailscale-playbook.yml --limit "dev01,bottom"
|
||||
```
|
||||
|
||||
### Manual Installation
|
||||
```bash
|
||||
# With custom auth key (not recommended - use vault instead)
|
||||
ansible-playbook tailscale-playbook.yml -e "tailscale_auth_key=your-key"
|
||||
|
||||
# As part of existing playbooks
|
||||
ansible-playbook dev-playbook.yml --tags tailscale
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Global Settings (`group_vars/all.yml`)
|
||||
```yaml
|
||||
tailscale_auth_key: "{{ vault_tailscale_auth_key }}" # From vault
|
||||
tailscale_accept_routes: true # Accept subnet routes
|
||||
tailscale_accept_dns: true # Accept DNS settings
|
||||
tailscale_ssh: true # Enable SSH over Tailscale
|
||||
```
|
||||
|
||||
### Host-Specific Settings (`host_vars/hostname.yml`)
|
||||
```yaml
|
||||
tailscale_hostname: "custom-name" # Override hostname
|
||||
tailscale_advertise_routes: "192.168.1.0/24" # Share local subnet
|
||||
tailscale_shields_up: false # Block incoming connections
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Check Service Status
|
||||
```bash
|
||||
# Via Ansible
|
||||
make tailscale-status
|
||||
|
||||
# On target machine
|
||||
sudo systemctl status tailscaled
|
||||
tailscale status
|
||||
```
|
||||
|
||||
### View Logs
|
||||
```bash
|
||||
sudo journalctl -u tailscaled -f
|
||||
```
|
||||
|
||||
### Manual Connection
|
||||
If auth key wasn't provided during setup:
|
||||
```bash
|
||||
sudo tailscale up
|
||||
```
|
||||
|
||||
### Reset Connection
|
||||
```bash
|
||||
ansible-playbook tailscale-playbook.yml -e "tailscale_reset=true"
|
||||
```
|
||||
|
||||
## Security Best Practices
|
||||
- Always use Ansible Vault for auth keys
|
||||
- Consider ephemeral keys for one-time setups
|
||||
- Authorize machines in Tailscale admin console
|
||||
- Review SSH settings if enabling Tailscale SSH
|
||||
|
||||
## Supported Platforms
|
||||
- **Ubuntu**: focal, jammy, noble
|
||||
- **Debian**: bullseye, bookworm, trixie
|
||||
- **Alpine Linux**: all versions
|
||||
|
||||
The role automatically detects OS and uses appropriate package manager.
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Playbook runs** → looks for `tailscale_auth_key`
|
||||
2. **Checks `all.yml`** → finds `{{ vault_tailscale_auth_key }}`
|
||||
3. **Decrypts vault** → retrieves actual auth key
|
||||
4. **Installs Tailscale** → configures with your settings
|
||||
5. **Connects to network** → machine appears in admin console
|
||||
|
||||
## Related Documentation
|
||||
- [Ansible Vault Guide](./vault.md) - Managing secrets securely
|
||||
- [Network Architecture](../reference/network.md) - Overall network design
|
||||
125
docs/guides/vault.md
Normal file
125
docs/guides/vault.md
Normal file
@ -0,0 +1,125 @@
|
||||
# Ansible Vault Guide
|
||||
|
||||
Ansible Vault encrypts sensitive data like passwords and API keys while keeping them usable in playbooks.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Create Vault
|
||||
```bash
|
||||
make create-vault
|
||||
```
|
||||
|
||||
### Add Secrets
|
||||
When editor opens, add your secrets:
|
||||
```yaml
|
||||
---
|
||||
# Authentication Keys
|
||||
vault_tailscale_auth_key: "tskey-auth-..."
|
||||
vault_proxmox_password: "super-secret"
|
||||
|
||||
# API Keys
|
||||
vault_github_token: "ghp_..."
|
||||
vault_docker_hub_token: "dckr_..."
|
||||
|
||||
# Passwords
|
||||
vault_db_password: "complex-password"
|
||||
vault_vm_cipassword: "vm-user-password"
|
||||
|
||||
# SSH Keys
|
||||
vault_ssh_public_key: "ssh-ed25519 AAAA..."
|
||||
```
|
||||
|
||||
### Use in Playbooks
|
||||
Reference vault variables with `{{ vault_variable_name }}`:
|
||||
```yaml
|
||||
tailscale_auth_key: "{{ vault_tailscale_auth_key }}"
|
||||
database_password: "{{ vault_db_password }}"
|
||||
```
|
||||
|
||||
## File Structure
|
||||
```
|
||||
group_vars/
|
||||
├── all.yml # Plain text configuration
|
||||
└── all/
|
||||
└── vault.yml # Encrypted secrets (created by make create-vault)
|
||||
|
||||
host_vars/
|
||||
├── dev01.yml # Host-specific plain text
|
||||
└── dev01/
|
||||
└── vault.yml # Host-specific secrets
|
||||
```
|
||||
|
||||
## Common Commands
|
||||
|
||||
```bash
|
||||
# Create new vault
|
||||
make create-vault
|
||||
|
||||
# Edit existing vault
|
||||
make edit-vault # Global vault
|
||||
make edit-vault HOST=dev01 # Host-specific vault
|
||||
|
||||
# View decrypted contents
|
||||
ansible-vault view group_vars/all/vault.yml
|
||||
|
||||
# Change vault password
|
||||
ansible-vault rekey group_vars/all/vault.yml
|
||||
```
|
||||
|
||||
## Password Management
|
||||
|
||||
### Option 1: Password File (Recommended for Automation)
|
||||
```bash
|
||||
echo "your-vault-password" > ~/.ansible-vault-pass
|
||||
chmod 600 ~/.ansible-vault-pass
|
||||
```
|
||||
|
||||
### Option 2: Interactive (More Secure)
|
||||
Add `--ask-vault-pass` to commands or let Makefile handle it.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### What to Encrypt
|
||||
✅ **Put in Vault:**
|
||||
- API keys and tokens
|
||||
- Passwords and passphrases
|
||||
- Private keys and certificates
|
||||
- Database credentials
|
||||
- Any sensitive configuration
|
||||
|
||||
❌ **Keep in Plain Text:**
|
||||
- Non-sensitive configuration
|
||||
- Default settings
|
||||
- Public information
|
||||
- Documentation
|
||||
|
||||
### Naming Convention
|
||||
Prefix vault variables with `vault_` for clarity:
|
||||
- `vault_db_password` → encrypted in vault
|
||||
- `db_host` → plain text in all.yml
|
||||
|
||||
### Security Tips
|
||||
1. Never commit unencrypted secrets
|
||||
2. Use different vault passwords per environment
|
||||
3. Rotate vault passwords periodically
|
||||
4. Limit vault file access (chmod 600)
|
||||
5. Use git-crypt or similar for additional protection
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Attempting to decrypt but no vault secrets found"
|
||||
- Ensure vault password file exists: `~/.ansible-vault-pass`
|
||||
- Check file permissions: `chmod 600 ~/.ansible-vault-pass`
|
||||
|
||||
### "ERROR! Decryption failed"
|
||||
- Wrong password - verify vault password
|
||||
- Corrupted vault file - recreate from secure storage
|
||||
|
||||
### Variables not being replaced
|
||||
- Check variable naming matches exactly
|
||||
- Ensure vault file is in correct location
|
||||
- Verify vault file is properly encrypted
|
||||
|
||||
## Related Documentation
|
||||
- [Tailscale Setup](./tailscale.md) - Uses vault for auth keys
|
||||
- [Security Best Practices](../reference/security.md) - Overall security guidelines
|
||||
169
docs/reference/applications.md
Normal file
169
docs/reference/applications.md
Normal file
@ -0,0 +1,169 @@
|
||||
# Installed Applications Reference
|
||||
|
||||
Complete inventory of applications and tools deployed by Ansible playbooks.
|
||||
|
||||
## Application Categories
|
||||
|
||||
### 🔧 System Tools
|
||||
| Package | Description | Source | Role |
|
||||
|---------|-------------|--------|------|
|
||||
| curl | Command line HTTP client | apt | base |
|
||||
| wget | Network downloader | apt | base |
|
||||
| unzip | Archive extraction | apt | base |
|
||||
| xclip | Clipboard utility | apt | base |
|
||||
| tree | Directory tree viewer | apt | base |
|
||||
| net-tools | Network utilities | apt | base |
|
||||
| jq | JSON processor | apt | base |
|
||||
| yq | YAML processor | snap | base |
|
||||
| ripgrep | Fast text search | apt | base |
|
||||
| fd-find | Fast file finder | apt | base |
|
||||
|
||||
### 🔒 Security Tools
|
||||
| Package | Description | Source | Role |
|
||||
|---------|-------------|--------|------|
|
||||
| ufw | Uncomplicated Firewall | apt | ssh |
|
||||
| fail2ban | Intrusion prevention | apt | monitoring |
|
||||
| openssh-server | SSH daemon | apt | ssh |
|
||||
| mailutils | Mail utilities | apt | base |
|
||||
| nmap | Network scanner | apt | monitoring |
|
||||
| tcpdump | Packet analyzer | apt | monitoring |
|
||||
| wireshark-common | Protocol analyzer | apt | monitoring |
|
||||
|
||||
### 💻 Development Tools
|
||||
| Package | Description | Source | Role |
|
||||
|---------|-------------|--------|------|
|
||||
| git | Version control | apt | development |
|
||||
| nodejs | JavaScript runtime | apt | development |
|
||||
| npm | Node package manager | apt | development |
|
||||
| build-essential | Compilation tools | apt | development |
|
||||
| python3 | Python interpreter | apt | development |
|
||||
| python3-pip | Python package manager | apt | development |
|
||||
|
||||
### 🐳 Container Platform
|
||||
| Package | Description | Source | Role |
|
||||
|---------|-------------|--------|------|
|
||||
| docker-ce | Docker Community Edition | docker | docker |
|
||||
| docker-ce-cli | Docker CLI | docker | docker |
|
||||
| containerd.io | Container runtime | docker | docker |
|
||||
| docker-buildx-plugin | Multi-platform builds | docker | docker |
|
||||
| docker-compose-plugin | Multi-container apps | docker | docker |
|
||||
|
||||
### 🖥️ Shell Environment
|
||||
| Package | Description | Source | Role |
|
||||
|---------|-------------|--------|------|
|
||||
| zsh | Z shell | apt | shell |
|
||||
| tmux | Terminal multiplexer | apt | shell |
|
||||
| fzf | Fuzzy finder | apt | shell |
|
||||
| oh-my-zsh | Zsh framework | git | shell |
|
||||
| powerlevel10k | Zsh theme | git | shell |
|
||||
| zsh-syntax-highlighting | Syntax highlighting | git | shell |
|
||||
| zsh-autosuggestions | Command suggestions | git | shell |
|
||||
|
||||
### 📊 Monitoring Tools
|
||||
| Package | Description | Source | Role |
|
||||
|---------|-------------|--------|------|
|
||||
| htop | Process viewer | apt | monitoring |
|
||||
| btop | Modern system monitor | snap | monitoring |
|
||||
| iotop | I/O monitor | apt | monitoring |
|
||||
| nethogs | Network usage monitor | apt | monitoring |
|
||||
| iftop | Bandwidth monitor | apt | monitoring |
|
||||
| bandwhich | Network utilization | snap | monitoring |
|
||||
| ncdu | Disk usage analyzer | apt | monitoring |
|
||||
| dstat | System statistics | apt | monitoring |
|
||||
| sysstat | Performance tools | apt | monitoring |
|
||||
| atop | Advanced monitor | apt | monitoring |
|
||||
| logwatch | Log analyzer | apt | monitoring |
|
||||
|
||||
|
||||
### 🌐 Network Tools
|
||||
| Package | Description | Source | Role |
|
||||
|---------|-------------|--------|------|
|
||||
| tailscale | Mesh VPN client | tailscale | tailscale |
|
||||
| tailscaled | Tailscale daemon | tailscale | tailscale |
|
||||
|
||||
### 🖱️ Desktop Applications
|
||||
| Package | Description | Source | Role |
|
||||
|---------|-------------|--------|------|
|
||||
| brave-browser | Privacy-focused browser | brave | applications |
|
||||
| libreoffice | Office suite | apt | applications |
|
||||
| evince | PDF viewer | apt | applications |
|
||||
| redshift | Blue light filter | apt | applications |
|
||||
|
||||
### 📝 Code Editors
|
||||
| Package | Description | Source | Role |
|
||||
|---------|-------------|--------|------|
|
||||
| code | Visual Studio Code | snap | snap |
|
||||
| cursor | AI-powered editor | snap | snap |
|
||||
|
||||
## Installation by Playbook
|
||||
|
||||
### dev-playbook.yml
|
||||
Installs all roles for development machines:
|
||||
- All system tools
|
||||
- Development environment
|
||||
- Docker platform
|
||||
- Shell configuration
|
||||
- Desktop applications
|
||||
- Monitoring tools
|
||||
- Tailscale VPN
|
||||
|
||||
### local-playbook.yml
|
||||
Installs for local machine management:
|
||||
- Core system tools
|
||||
- Shell environment
|
||||
- Development basics
|
||||
- Selected applications
|
||||
|
||||
### maintenance-playbook.yml
|
||||
Maintains existing installations:
|
||||
- System updates
|
||||
- Package cleanup
|
||||
- Security updates
|
||||
|
||||
## Custom Scripts
|
||||
|
||||
### System Information
|
||||
- `/usr/local/bin/monitoring/sysinfo` - System overview dashboard
|
||||
- `/usr/local/bin/monitoring/netinfo` - Network information
|
||||
|
||||
|
||||
## Package Sources
|
||||
|
||||
| Source | Description | Configuration |
|
||||
|--------|-------------|---------------|
|
||||
| apt | Debian/Ubuntu packages | System default |
|
||||
| snap | Snap packages | snapd daemon |
|
||||
| docker | Docker repository | Docker GPG key + repo |
|
||||
| tailscale | Tailscale repository | Tailscale GPG key + repo |
|
||||
| brave | Brave browser repository | Brave GPG key + repo |
|
||||
| git | Git repositories | Direct clone |
|
||||
|
||||
## Services Enabled
|
||||
|
||||
| Service | Description | Management |
|
||||
|---------|-------------|------------|
|
||||
| docker | Container runtime | systemctl |
|
||||
| tailscaled | VPN daemon | systemctl |
|
||||
| ufw | Firewall | systemctl |
|
||||
| fail2ban | Intrusion prevention | systemctl |
|
||||
| sshd | SSH server | systemctl |
|
||||
| snapd | Snap daemon | systemctl |
|
||||
| sysstat | System statistics | systemctl |
|
||||
|
||||
## Version Management
|
||||
|
||||
Most packages are installed from distribution repositories and update with system updates. Exceptions:
|
||||
- **Docker**: Tracks Docker CE stable channel
|
||||
- **Node.js**: Latest LTS from NodeSource
|
||||
- **Tailscale**: Latest stable from Tailscale repository
|
||||
|
||||
## Total Count: 65+ Applications
|
||||
|
||||
- **System & Security**: 20+ tools
|
||||
- **Development**: 6+ tools
|
||||
- **Shell Environment**: 7+ components
|
||||
- **Monitoring**: 15+ tools
|
||||
- **Container Platform**: 5 components
|
||||
- **Desktop Applications**: 6+ apps
|
||||
- **Network**: 2+ tools
|
||||
- **Custom Scripts**: 4+ scripts
|
||||
279
docs/reference/architecture.md
Normal file
279
docs/reference/architecture.md
Normal file
@ -0,0 +1,279 @@
|
||||
# Architecture Overview
|
||||
|
||||
Technical architecture and design of the Ansible infrastructure management system.
|
||||
|
||||
## System Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Control Machine |
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Ansible │ │ Makefile │ │ Vault │ │
|
||||
│ │ Engine │ │ Automation │ │ Secrets │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│ SSH + Tailscale VPN
|
||||
┌─────────────────┴──────────────────────────────┐
|
||||
│ │
|
||||
┌───▼────────┐ ┌──────────────┐ ┌─────────────────▼────────┐
|
||||
│ Dev │ │ Service │ │ Infrastructure │
|
||||
│ Machines │ │ VMs │ │ VMs │
|
||||
├────────────┤ ├──────────────┤ ├──────────────────────────┤
|
||||
│ • dev01 │ │ • giteaVM │ │ • Proxmox Controller │
|
||||
│ • bottom │ │ • portainerVM│ │ • Future VMs │
|
||||
│ • desktop │ │ • homepageVM │ │ │
|
||||
└────────────┘ └──────────────┘ └──────────────────────────┘
|
||||
```
|
||||
|
||||
## Network Topology
|
||||
|
||||
### Physical Network
|
||||
- **LAN**: 192.168.1.0/24 (typical home/office network)
|
||||
- **Proxmox Host**: Hypervisor for VM management
|
||||
- **Physical Machines**: Direct network access
|
||||
|
||||
### Tailscale Overlay Network
|
||||
- **Mesh VPN**: Secure peer-to-peer connections
|
||||
- **100.x.x.x**: Tailscale IP range
|
||||
- **Zero-config**: Automatic NAT traversal
|
||||
- **End-to-end encryption**: WireGuard protocol
|
||||
|
||||
## Host Groups
|
||||
|
||||
### Development (`dev`)
|
||||
**Purpose**: Developer workstations and environments
|
||||
- **Hosts**: dev01, bottom, debianDesktopVM
|
||||
- **OS**: Debian/Ubuntu
|
||||
- **Roles**: Full development stack
|
||||
|
||||
### Services
|
||||
**Purpose**: Self-hosted services and applications
|
||||
|
||||
#### Gitea (`gitea`)
|
||||
- **Host**: giteaVM
|
||||
- **OS**: Alpine Linux (lightweight)
|
||||
- **Service**: Git repository hosting
|
||||
|
||||
#### Portainer (`portainer`)
|
||||
- **Host**: portainerVM
|
||||
- **OS**: Alpine Linux
|
||||
- **Service**: Container management UI
|
||||
|
||||
#### Homepage (`homepage`)
|
||||
- **Host**: homepageVM
|
||||
- **OS**: Debian
|
||||
- **Service**: Service dashboard
|
||||
|
||||
### Infrastructure (`ansible`)
|
||||
**Purpose**: Ansible control and automation
|
||||
- **Host**: Ansible controller VM
|
||||
- **OS**: Ubuntu Server
|
||||
- **Service**: Infrastructure automation
|
||||
|
||||
### Local (`local`)
|
||||
**Purpose**: Local machine management
|
||||
- **Host**: localhost
|
||||
- **Connection**: Local (no SSH)
|
||||
|
||||
## Playbook Architecture
|
||||
|
||||
### Core Playbooks
|
||||
|
||||
```yaml
|
||||
dev-playbook.yml # Development environment setup
|
||||
├── roles/maintenance # System updates
|
||||
├── roles/base # Core packages
|
||||
├── roles/ssh # SSH hardening
|
||||
├── roles/user # User management
|
||||
├── roles/development # Dev tools
|
||||
├── roles/shell # Shell config
|
||||
├── roles/docker # Container platform
|
||||
├── roles/applications # Desktop apps
|
||||
├── roles/snap # Snap packages
|
||||
├── roles/tailscale # VPN setup
|
||||
├── roles/monitoring # Monitoring tools
|
||||
|
||||
local-playbook.yml # Local machine
|
||||
├── roles/base
|
||||
├── roles/shell
|
||||
├── roles/development
|
||||
└── roles/tailscale
|
||||
|
||||
maintenance-playbook.yml # System maintenance
|
||||
└── roles/maintenance
|
||||
|
||||
tailscale-playbook.yml # VPN deployment
|
||||
└── roles/tailscale
|
||||
|
||||
proxmox-create-vm.yml # VM provisioning
|
||||
└── roles/proxmox_vm
|
||||
```
|
||||
|
||||
### Role Dependencies
|
||||
|
||||
```
|
||||
base
|
||||
├── Required by: all other roles
|
||||
├── Provides: core utilities, security tools
|
||||
└── Dependencies: none
|
||||
|
||||
ssh
|
||||
├── Required by: secure access
|
||||
├── Provides: hardened SSH, firewall
|
||||
└── Dependencies: base
|
||||
|
||||
user
|
||||
├── Required by: system access
|
||||
├── Provides: user accounts, sudo
|
||||
└── Dependencies: base
|
||||
|
||||
development
|
||||
├── Required by: coding tasks
|
||||
├── Provides: git, nodejs, python
|
||||
└── Dependencies: base
|
||||
|
||||
docker
|
||||
├── Required by: containerization
|
||||
├── Provides: Docker CE, compose
|
||||
└── Dependencies: base
|
||||
|
||||
tailscale
|
||||
├── Required by: secure networking
|
||||
├── Provides: mesh VPN
|
||||
└── Dependencies: base
|
||||
```
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Configuration Management
|
||||
1. **Variables** → group_vars/all.yml (global)
|
||||
2. **Secrets** → group_vars/all/vault.yml (encrypted)
|
||||
3. **Host Config** → host_vars/hostname.yml (specific)
|
||||
4. **Role Defaults** → roles/*/defaults/main.yml
|
||||
5. **Tasks** → roles/*/tasks/main.yml
|
||||
6. **Templates** → roles/*/templates/*.j2
|
||||
7. **Handlers** → roles/*/handlers/main.yml
|
||||
|
||||
### Execution Flow
|
||||
```
|
||||
make command
|
||||
↓
|
||||
Makefile target
|
||||
↓
|
||||
ansible-playbook
|
||||
↓
|
||||
Inventory + Variables
|
||||
↓
|
||||
Role execution
|
||||
↓
|
||||
Task processing
|
||||
↓
|
||||
Handler notification
|
||||
↓
|
||||
Result reporting
|
||||
```
|
||||
|
||||
## Security Architecture
|
||||
|
||||
### Defense in Depth
|
||||
|
||||
#### Network Layer
|
||||
- **Tailscale VPN**: Encrypted mesh network
|
||||
- **UFW Firewall**: Default deny, explicit allow
|
||||
- **SSH Hardening**: Key-only, rate limiting
|
||||
|
||||
#### Application Layer
|
||||
- **Fail2ban**: Intrusion prevention
|
||||
- **Package signing**: GPG verification
|
||||
- **Service isolation**: Docker containers
|
||||
|
||||
#### Data Layer
|
||||
- **Ansible Vault**: Encrypted secrets
|
||||
- **SSH Keys**: Ed25519 cryptography
|
||||
|
||||
### Access Control
|
||||
|
||||
```
|
||||
User → SSH Key → Jump Host → Tailscale → Target Host
|
||||
↓ ↓ ↓ ↓
|
||||
Ed25519 Bastion WireGuard Firewall
|
||||
Encryption Rules
|
||||
```
|
||||
|
||||
## Storage Architecture
|
||||
|
||||
|
||||
### Configuration Storage
|
||||
```
|
||||
/etc/ # System configuration
|
||||
/opt/ # Application data
|
||||
/usr/local/ # Custom scripts
|
||||
/var/log/ # Logs and audit trails
|
||||
```
|
||||
|
||||
## Monitoring Architecture
|
||||
|
||||
### System Monitoring
|
||||
- **btop/htop**: Process monitoring
|
||||
- **iotop**: I/O monitoring
|
||||
- **nethogs**: Network per-process
|
||||
- **Custom dashboards**: sysinfo, netinfo
|
||||
|
||||
### Log Management
|
||||
- **logwatch**: Daily summaries
|
||||
- **journald**: System logs
|
||||
- **fail2ban**: Security logs
|
||||
|
||||
## Scalability Considerations
|
||||
|
||||
### Horizontal Scaling
|
||||
- Add hosts to inventory groups
|
||||
- Parallel execution with ansible forks
|
||||
- Role reusability across environments
|
||||
|
||||
### Vertical Scaling
|
||||
- Proxmox VM resource adjustment
|
||||
- Docker resource limits
|
||||
- Service-specific tuning
|
||||
|
||||
## Technology Stack
|
||||
|
||||
### Core Technologies
|
||||
- **Ansible**: 2.9+ (Configuration management)
|
||||
- **Python**: 3.x (Ansible runtime)
|
||||
- **Jinja2**: Templating engine
|
||||
- **YAML**: Configuration format
|
||||
|
||||
### Target Platforms
|
||||
- **Debian**: 11+ (Bullseye, Bookworm)
|
||||
- **Ubuntu**: 20.04+ (Focal, Jammy, Noble)
|
||||
- **Alpine**: 3.x (Lightweight containers)
|
||||
|
||||
### Service Technologies
|
||||
- **Docker**: Container runtime
|
||||
- **Tailscale**: Mesh VPN
|
||||
- **SystemD**: Service management
|
||||
- **UFW**: Firewall management
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Code Organization
|
||||
1. One role = one responsibility
|
||||
2. Idempotent tasks
|
||||
3. Proper handler usage
|
||||
4. Template for configuration
|
||||
5. Defaults for flexibility
|
||||
|
||||
### Security
|
||||
1. Vault for all secrets
|
||||
2. Least privilege principle
|
||||
3. Regular updates
|
||||
4. Audit logging
|
||||
5. Network segmentation
|
||||
|
||||
### Operations
|
||||
1. Test in check mode
|
||||
2. Use tags for selective runs
|
||||
3. Document changes
|
||||
4. Version control everything
|
||||
5. Monitor and alert
|
||||
178
docs/reference/makefile.md
Normal file
178
docs/reference/makefile.md
Normal file
@ -0,0 +1,178 @@
|
||||
# Makefile Commands Reference
|
||||
|
||||
Complete reference for all available `make` commands in the Ansible project.
|
||||
|
||||
## Core Commands
|
||||
|
||||
### Setup & Testing
|
||||
| Command | Description | Usage |
|
||||
|---------|-------------|-------|
|
||||
| `help` | Show all available commands | `make help` |
|
||||
| `bootstrap` | Install required collections and dependencies | `make bootstrap` |
|
||||
| `test` | Run all tests (lint + syntax check) | `make test` |
|
||||
| `test-syntax` | Run syntax check only | `make test-syntax` |
|
||||
| `lint` | Run ansible-lint on playbooks and roles | `make lint` |
|
||||
| `check` | Dry-run the development playbook | `make check` |
|
||||
| `check-local` | Dry-run the local playbook | `make check-local` |
|
||||
|
||||
### Deployment
|
||||
| Command | Description | Usage |
|
||||
|---------|-------------|-------|
|
||||
| `apply` | Run development playbook on all dev hosts | `make apply` |
|
||||
| `local` | Run local playbook on localhost | `make local` |
|
||||
| `dev` | Run on specific host | `make dev HOST=dev01` |
|
||||
| `quick` | Quick test and check before applying | `make quick` |
|
||||
|
||||
## Feature-Specific Commands
|
||||
|
||||
### System Maintenance
|
||||
| Command | Description | Usage |
|
||||
|---------|-------------|-------|
|
||||
| `maintenance` | Run system maintenance | `make maintenance [GROUP=dev] [HOST=dev01]` |
|
||||
| | | Options: `SERIAL=1 CHECK=true VERBOSE=true` |
|
||||
| `maintenance-dev` | Run maintenance on dev group | `make maintenance-dev` |
|
||||
| `maintenance-all` | Run maintenance on all hosts | `make maintenance-all` |
|
||||
| `maintenance-check` | Dry-run maintenance | `make maintenance-check [GROUP=dev]` |
|
||||
| `maintenance-verbose` | Maintenance with verbose output | `make maintenance-verbose [GROUP=dev]` |
|
||||
|
||||
### Security & Networking
|
||||
| Command | Description | Usage |
|
||||
|---------|-------------|-------|
|
||||
| `security` | Run only security-related roles | `make security` |
|
||||
| `tailscale` | Install Tailscale on all machines | `make tailscale` |
|
||||
| `tailscale-check` | Check Tailscale installation (dry-run) | `make tailscale-check` |
|
||||
| `tailscale-dev` | Install Tailscale on dev machines only | `make tailscale-dev` |
|
||||
| `tailscale-status` | Check Tailscale status on all machines | `make tailscale-status` |
|
||||
|
||||
### Applications & Tools
|
||||
| Command | Description | Usage |
|
||||
|---------|-------------|-------|
|
||||
| `docker` | Install/configure Docker only | `make docker` |
|
||||
| `shell` | Configure shell only | `make shell` |
|
||||
| `apps` | Install applications only | `make apps` |
|
||||
| `monitoring` | Install monitoring tools | `make monitoring` |
|
||||
|
||||
## Infrastructure Management
|
||||
|
||||
### VM & Host Management
|
||||
| Command | Description | Usage |
|
||||
|---------|-------------|-------|
|
||||
| `create-vm` | Create Ansible controller VM on Proxmox | `make create-vm` |
|
||||
| `ping` | Ping hosts with colored output | `make ping [GROUP=dev] [HOST=dev01]` |
|
||||
| `facts` | Gather facts from all hosts | `make facts` |
|
||||
| `test-connectivity` | Test network and SSH access | `make test-connectivity` |
|
||||
| `show-current` | Show current host (auto-excluded) | `make show-current` |
|
||||
|
||||
### SSH & Vault Management
|
||||
| Command | Description | Usage |
|
||||
|---------|-------------|-------|
|
||||
| `copy-ssh-key` | Copy SSH key to specific host | `make copy-ssh-key HOST=giteaVM` |
|
||||
| `create-vault` | Create encrypted vault file | `make create-vault` |
|
||||
| `edit-vault` | Edit encrypted host vars | `make edit-vault HOST=dev01` |
|
||||
|
||||
## Utility Commands
|
||||
|
||||
### Debugging & Cleanup
|
||||
| Command | Description | Usage |
|
||||
|---------|-------------|-------|
|
||||
| `debug` | Run with debug output enabled | `make debug` |
|
||||
| `verbose` | Run with verbose output | `make verbose` |
|
||||
| `clean` | Clean up ansible artifacts | `make clean` |
|
||||
|
||||
## Command Options
|
||||
|
||||
### Common Variables
|
||||
Many commands accept these optional variables:
|
||||
|
||||
| Variable | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `HOST` | Target specific host | `HOST=dev01` |
|
||||
| `GROUP` | Target specific group | `GROUP=dev` |
|
||||
| `CHECK` | Run in check mode (dry-run) | `CHECK=true` |
|
||||
| `VERBOSE` | Enable verbose output | `VERBOSE=true` |
|
||||
| `SERIAL` | Run on hosts one at a time | `SERIAL=1` |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Deploy to specific host
|
||||
make dev HOST=bottom
|
||||
|
||||
# Maintenance with options
|
||||
make maintenance GROUP=dev SERIAL=1 CHECK=true
|
||||
|
||||
# Test connectivity to specific group
|
||||
make ping GROUP=gitea
|
||||
|
||||
# Edit vault for specific host
|
||||
make edit-vault HOST=portainerVM
|
||||
|
||||
# Dry-run on production
|
||||
make check GROUP=prod
|
||||
```
|
||||
|
||||
## Workflow Examples
|
||||
|
||||
### Initial Setup
|
||||
```bash
|
||||
make bootstrap
|
||||
make create-vault
|
||||
make test
|
||||
make check
|
||||
make apply
|
||||
```
|
||||
|
||||
### Adding New Host
|
||||
```bash
|
||||
make copy-ssh-key HOST=newhost
|
||||
make edit-vault HOST=newhost
|
||||
make dev HOST=newhost
|
||||
```
|
||||
|
||||
### System Maintenance
|
||||
```bash
|
||||
make maintenance-check
|
||||
make maintenance GROUP=dev
|
||||
make maintenance-all
|
||||
```
|
||||
|
||||
### Feature Deployment
|
||||
```bash
|
||||
# Deploy specific features
|
||||
make docker
|
||||
make tailscale
|
||||
make monitoring
|
||||
```
|
||||
|
||||
### Troubleshooting
|
||||
```bash
|
||||
make test-connectivity
|
||||
make facts
|
||||
make ping GROUP=dev
|
||||
make debug
|
||||
```
|
||||
|
||||
## Tips & Best Practices
|
||||
|
||||
1. **Always test first**: Use `check` commands before applying changes
|
||||
2. **Use groups**: Target specific groups instead of all hosts
|
||||
3. **Verbose for debugging**: Add `VERBOSE=true` when troubleshooting
|
||||
4. **Serial for safety**: Use `SERIAL=1` for critical changes
|
||||
5. **Check mode**: Use `CHECK=true` to preview changes
|
||||
|
||||
## Environment Variables
|
||||
|
||||
The Makefile respects these environment variables:
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `ANSIBLE_CONFIG` | Ansible configuration file | `./ansible.cfg` |
|
||||
| `ANSIBLE_VAULT_PASSWORD_FILE` | Vault password file | `~/.ansible-vault-pass` |
|
||||
| `ANSIBLE_HOST_KEY_CHECKING` | SSH host key checking | `False` |
|
||||
|
||||
## Getting Help
|
||||
|
||||
- Run `make help` to see all available commands
|
||||
- Commands with `##` comments appear in help output
|
||||
- Check individual role documentation in `roles/*/README.md`
|
||||
- Review playbook files for available tags
|
||||
32
inventories/production/group_vars/all/main.yml
Normal file
32
inventories/production/group_vars/all/main.yml
Normal file
@ -0,0 +1,32 @@
|
||||
---
|
||||
# Common variables for all hosts
|
||||
timezone: America/Toronto
|
||||
locale: en_US.UTF-8
|
||||
ansible_python_interpreter: /usr/bin/python3
|
||||
|
||||
# Debug settings
|
||||
ansible_debug_output: false
|
||||
|
||||
# Security settings
|
||||
fail2ban_bantime: 3600
|
||||
fail2ban_findtime: 600
|
||||
fail2ban_maxretry: 3
|
||||
|
||||
# Maintenance settings
|
||||
maintenance_default_serial: "100%" # Default serial execution for maintenance
|
||||
maintenance_reboot_timeout: 300 # Reboot timeout in seconds
|
||||
maintenance_pre_reboot_delay: 5 # Delay before reboot in seconds
|
||||
|
||||
# Global variables for all hosts
|
||||
|
||||
# Tailscale configuration
|
||||
# Store your actual auth key in vault_tailscale_auth_key using ansible-vault
|
||||
# Example: ansible-vault create group_vars/all/vault.yml
|
||||
# vault_tailscale_auth_key: "tskey-auth-your-actual-key-here"
|
||||
|
||||
# Default Tailscale settings - these tell the playbook to use your vault key
|
||||
tailscale_auth_key: "{{ vault_tailscale_auth_key | default('') }}"
|
||||
tailscale_accept_routes: true
|
||||
tailscale_accept_dns: true
|
||||
tailscale_ssh: true
|
||||
tailscale_hostname: "{{ inventory_hostname }}"
|
||||
10
inventories/production/group_vars/all/vault.yml
Normal file
10
inventories/production/group_vars/all/vault.yml
Normal file
@ -0,0 +1,10 @@
|
||||
$ANSIBLE_VAULT;1.1;AES256
|
||||
36376666313464366432353635643532663733656664336632626633616465313834323563613965
|
||||
3261643434373638623932373531366333393736636165620a306437366133343435626639396361
|
||||
30373765343339626464336538303634336135316431653264363831643264373636303161616334
|
||||
6231326138306564310a343135303362326664653061666363366364376335343431393330643334
|
||||
32336263623437636266383730666562303234633438646330313163323232623961613665613031
|
||||
65643630623235356164303839663938343238336432663462363431363062623764326536396562
|
||||
32613331366135646133373165646634356337376463393530343264386531393837303263353033
|
||||
31646238393165613331623164613265613332623933343136623739316262646237323739666434
|
||||
6238
|
||||
@ -1,28 +0,0 @@
|
||||
- name: Setup local development environment
|
||||
hosts: localhost
|
||||
connection: local
|
||||
become: true
|
||||
|
||||
roles:
|
||||
- { role: maintenance, tags: ['maintenance'] }
|
||||
- { role: base, tags: ['base', 'security'] }
|
||||
- { role: user, tags: ['user'] }
|
||||
- { role: ssh, tags: ['ssh', 'security'] }
|
||||
- { role: shell, tags: ['shell'] }
|
||||
- { role: development, tags: ['development', 'dev'] }
|
||||
- { role: docker, tags: ['docker'] }
|
||||
- { role: applications, tags: ['applications', 'apps'] }
|
||||
- { role: snap, tags: ['snap', 'apps'] }
|
||||
- { role: tailscale, tags: ['tailscale', 'vpn'] }
|
||||
- { role: monitoring, tags: ['monitoring'] }
|
||||
# - { role: backup, tags: ['backup'] }
|
||||
|
||||
pre_tasks:
|
||||
- name: Update apt cache
|
||||
ansible.builtin.apt:
|
||||
update_cache: true
|
||||
|
||||
tasks:
|
||||
- name: Display completion message
|
||||
ansible.builtin.debug:
|
||||
msg: "Local development environment setup completed successfully!"
|
||||
2163
package-lock.json
generated
Normal file
2163
package-lock.json
generated
Normal file
File diff suppressed because it is too large
Load Diff
25
package.json
Normal file
25
package.json
Normal file
@ -0,0 +1,25 @@
|
||||
{
|
||||
"name": "ansible-infrastructure",
|
||||
"version": "1.0.0",
|
||||
"description": "Ansible infrastructure automation project",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"test:markdown": "markdownlint-cli2 README.md 'docs/**/*.md'",
|
||||
"test:links": "markdown-link-check README.md docs/**/*.md"
|
||||
},
|
||||
"devDependencies": {
|
||||
"markdown-link-check": "^3.13.7",
|
||||
"markdownlint-cli2": "^0.18.1"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=22.0.0",
|
||||
"npm": ">=10.0.0"
|
||||
},
|
||||
"keywords": [
|
||||
"ansible",
|
||||
"infrastructure",
|
||||
"automation",
|
||||
"devops"
|
||||
],
|
||||
"license": "MIT"
|
||||
}
|
||||
28
playbooks/development.yml
Normal file
28
playbooks/development.yml
Normal file
@ -0,0 +1,28 @@
|
||||
---
|
||||
- name: Configure development environment
|
||||
hosts: dev
|
||||
become: true
|
||||
|
||||
roles:
|
||||
- {role: maintenance, tags: ['maintenance']}
|
||||
- {role: base, tags: ['base', 'security']}
|
||||
- {role: user, tags: ['user']}
|
||||
- {role: ssh, tags: ['ssh', 'security']}
|
||||
- {role: shell, tags: ['shell']}
|
||||
- {role: development, tags: ['development', 'dev']}
|
||||
- {role: docker, tags: ['docker']}
|
||||
- {role: applications, tags: ['applications', 'apps']}
|
||||
- {role: snap, tags: ['snap', 'apps']}
|
||||
- {role: tailscale, tags: ['tailscale', 'vpn']}
|
||||
- {role: monitoring, tags: ['monitoring']}
|
||||
|
||||
pre_tasks:
|
||||
- name: Update apt cache
|
||||
ansible.builtin.apt:
|
||||
update_cache: true
|
||||
|
||||
tasks:
|
||||
# Additional tasks can be added here if needed
|
||||
- name: Display completion message
|
||||
ansible.builtin.debug:
|
||||
msg: "Development environment setup completed successfully!"
|
||||
@ -49,7 +49,7 @@
|
||||
VM {{ vm_name }} ({{ vm_id }}): {{ 'Already exists' if vm_check.status is defined else 'Will be created' }}
|
||||
|
||||
roles:
|
||||
- { role: proxmox_vm, when: vm_check.status is not defined }
|
||||
- {role: proxmox_vm, when: vm_check.status is not defined}
|
||||
|
||||
post_tasks:
|
||||
- name: Wait for VM to be accessible via SSH
|
||||
28
playbooks/local.yml
Normal file
28
playbooks/local.yml
Normal file
@ -0,0 +1,28 @@
|
||||
---
|
||||
- name: Setup local development environment
|
||||
hosts: localhost
|
||||
connection: local
|
||||
become: true
|
||||
|
||||
roles:
|
||||
- {role: maintenance, tags: ['maintenance']}
|
||||
- {role: base, tags: ['base', 'security']}
|
||||
- {role: user, tags: ['user']}
|
||||
- {role: ssh, tags: ['ssh', 'security']}
|
||||
- {role: shell, tags: ['shell']}
|
||||
- {role: development, tags: ['development', 'dev']}
|
||||
- {role: docker, tags: ['docker']}
|
||||
- {role: applications, tags: ['applications', 'apps']}
|
||||
- {role: snap, tags: ['snap', 'apps']}
|
||||
- {role: tailscale, tags: ['tailscale', 'vpn']}
|
||||
- {role: monitoring, tags: ['monitoring']}
|
||||
|
||||
pre_tasks:
|
||||
- name: Update apt cache
|
||||
ansible.builtin.apt:
|
||||
update_cache: true
|
||||
|
||||
tasks:
|
||||
- name: Display completion message
|
||||
ansible.builtin.debug:
|
||||
msg: "Local development environment setup completed successfully!"
|
||||
@ -29,7 +29,7 @@
|
||||
when: maintenance_update_cache | bool
|
||||
|
||||
roles:
|
||||
- { role: maintenance, tags: ['maintenance'] }
|
||||
- {role: maintenance, tags: ['maintenance']}
|
||||
|
||||
post_tasks:
|
||||
- name: Display maintenance completion
|
||||
15
playbooks/site.yml
Normal file
15
playbooks/site.yml
Normal file
@ -0,0 +1,15 @@
|
||||
---
|
||||
# Master playbook for complete infrastructure deployment
|
||||
# Usage: ansible-playbook playbooks/site.yml
|
||||
|
||||
- name: Complete infrastructure setup
|
||||
import_playbook: maintenance.yml
|
||||
tags: ['maintenance']
|
||||
|
||||
- name: Development environment setup
|
||||
import_playbook: development.yml
|
||||
tags: ['development']
|
||||
|
||||
- name: Tailscale VPN deployment
|
||||
import_playbook: tailscale.yml
|
||||
tags: ['tailscale']
|
||||
@ -16,7 +16,7 @@
|
||||
when: ansible_os_family == "Debian"
|
||||
|
||||
roles:
|
||||
- { role: tailscale, tags: ['tailscale', 'vpn'] }
|
||||
- {role: tailscale, tags: ['tailscale', 'vpn']}
|
||||
|
||||
post_tasks:
|
||||
- name: Display Tailscale installation completion
|
||||
17
requirements.txt
Normal file
17
requirements.txt
Normal file
@ -0,0 +1,17 @@
|
||||
# Ansible and related tools
|
||||
ansible>=6.0.0
|
||||
ansible-lint>=6.0.0
|
||||
yamllint>=1.26.0
|
||||
|
||||
# Testing and validation
|
||||
molecule>=4.0.0
|
||||
molecule-docker>=2.0.0
|
||||
jmespath>=1.0.0
|
||||
PyYAML>=6.0 # For YAML validation in make test-syntax
|
||||
|
||||
# For Proxmox integration
|
||||
proxmoxer>=1.3.0
|
||||
requests>=2.25.0
|
||||
|
||||
# Python package management
|
||||
pip>=21.0.0 # Ensure modern pip for reliable installs
|
||||
46
roles/applications/README.md
Normal file
46
roles/applications/README.md
Normal file
@ -0,0 +1,46 @@
|
||||
# Role: applications
|
||||
|
||||
## Description
|
||||
Installs desktop applications for development and productivity including browsers, office suites, and utilities.
|
||||
|
||||
## Requirements
|
||||
- Ansible 2.9+
|
||||
- Debian/Ubuntu with desktop environment
|
||||
- Internet access for package downloads
|
||||
|
||||
## Installed Applications
|
||||
- **Brave Browser**: Privacy-focused web browser
|
||||
- **LibreOffice**: Complete office suite
|
||||
- **Evince**: PDF document viewer
|
||||
- **Redshift**: Blue light filter for eye comfort
|
||||
|
||||
## Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `applications_install_brave` | `true` | Install Brave browser |
|
||||
| `applications_install_libreoffice` | `true` | Install LibreOffice suite |
|
||||
| `applications_install_evince` | `true` | Install PDF viewer |
|
||||
| `applications_install_redshift` | `true` | Install blue light filter |
|
||||
|
||||
## Dependencies
|
||||
- `base` role (for package management)
|
||||
|
||||
## Example Playbook
|
||||
|
||||
```yaml
|
||||
- hosts: desktop
|
||||
roles:
|
||||
- { role: applications, applications_install_brave: false }
|
||||
```
|
||||
|
||||
## Tags
|
||||
- `applications`: All application installations
|
||||
- `apps`: Alias for applications
|
||||
- `browser`: Browser installation only
|
||||
- `office`: Office suite installation only
|
||||
|
||||
## Notes
|
||||
- Adds external repositories for Brave browser
|
||||
- Requires desktop environment for GUI applications
|
||||
- Applications are installed system-wide
|
||||
@ -1,10 +0,0 @@
|
||||
---
|
||||
# Backup role defaults
|
||||
backup_enable_cron: true
|
||||
backup_retention_days_home: 7
|
||||
backup_retention_days_system: 30
|
||||
backup_users:
|
||||
- master
|
||||
- beast
|
||||
- ladmin
|
||||
- user
|
||||
@ -1,50 +0,0 @@
|
||||
---
|
||||
- name: Install backup tools
|
||||
ansible.builtin.apt:
|
||||
name:
|
||||
- rsync
|
||||
- borgbackup
|
||||
- rclone
|
||||
- restic
|
||||
state: present
|
||||
|
||||
- name: Create backup directories
|
||||
ansible.builtin.file:
|
||||
path: "{{ item }}"
|
||||
state: directory
|
||||
mode: '0755'
|
||||
loop:
|
||||
- /opt/backups
|
||||
- /opt/backups/scripts
|
||||
- /var/log/backups
|
||||
|
||||
- name: Deploy backup script for home directories
|
||||
ansible.builtin.template:
|
||||
src: backup-home.sh.j2
|
||||
dest: /opt/backups/scripts/backup-home.sh
|
||||
mode: '0755'
|
||||
|
||||
- name: Deploy backup script for system configs
|
||||
ansible.builtin.template:
|
||||
src: backup-system.sh.j2
|
||||
dest: /opt/backups/scripts/backup-system.sh
|
||||
mode: '0755'
|
||||
|
||||
- name: Create backup cron jobs
|
||||
ansible.builtin.cron:
|
||||
name: "{{ item.name }}"
|
||||
job: "{{ item.job }}"
|
||||
minute: "{{ item.minute }}"
|
||||
hour: "{{ item.hour }}"
|
||||
day: "{{ item.day | default('*') }}"
|
||||
user: root
|
||||
loop:
|
||||
- name: "Daily home backup"
|
||||
job: "/opt/backups/scripts/backup-home.sh >> /var/log/backups/home.log 2>&1"
|
||||
minute: "0"
|
||||
hour: "2"
|
||||
- name: "Daily system config backup"
|
||||
job: "/opt/backups/scripts/backup-system.sh >> /var/log/backups/system.log 2>&1"
|
||||
minute: "30"
|
||||
hour: "2"
|
||||
when: backup_enable_cron | default(true) | bool
|
||||
@ -1,31 +0,0 @@
|
||||
#!/bin/bash
|
||||
# Home directory backup script
|
||||
# Generated by Ansible
|
||||
|
||||
DATE=$(date +%Y%m%d_%H%M%S)
|
||||
BACKUP_DIR="/opt/backups/home"
|
||||
LOG_FILE="/var/log/backups/home.log"
|
||||
|
||||
echo "$(date): Starting home backup" >> "$LOG_FILE"
|
||||
|
||||
# Create backup directory
|
||||
mkdir -p "$BACKUP_DIR"
|
||||
|
||||
# Backup each user's home directory
|
||||
{% for user in backup_users | default(['master', 'beast', 'ladmin', 'user']) %}
|
||||
if [ -d "/home/{{ user }}" ]; then
|
||||
echo "$(date): Backing up /home/{{ user }}" >> "$LOG_FILE"
|
||||
rsync -av --delete \
|
||||
--exclude='.cache' \
|
||||
--exclude='.local/share/Trash' \
|
||||
--exclude='snap' \
|
||||
--exclude='.docker' \
|
||||
/home/{{ user }}/ \
|
||||
"$BACKUP_DIR/{{ user }}_$DATE/" >> "$LOG_FILE" 2>&1
|
||||
fi
|
||||
{% endfor %}
|
||||
|
||||
# Keep only last 7 days of backups
|
||||
find "$BACKUP_DIR" -type d -name "*_20*" -mtime +7 -exec rm -rf {} \; 2>/dev/null
|
||||
|
||||
echo "$(date): Home backup completed" >> "$LOG_FILE"
|
||||
@ -1,43 +0,0 @@
|
||||
#!/bin/bash
|
||||
# System configuration backup script
|
||||
# Generated by Ansible
|
||||
|
||||
DATE=$(date +%Y%m%d_%H%M%S)
|
||||
BACKUP_DIR="/opt/backups/system"
|
||||
LOG_FILE="/var/log/backups/system.log"
|
||||
|
||||
echo "$(date): Starting system backup" >> "$LOG_FILE"
|
||||
|
||||
# Create backup directory
|
||||
mkdir -p "$BACKUP_DIR/$DATE"
|
||||
|
||||
# Backup important system directories
|
||||
for dir in /etc /var/lib/dpkg /var/lib/apt/extended_states; do
|
||||
if [ -d "$dir" ]; then
|
||||
echo "$(date): Backing up $dir" >> "$LOG_FILE"
|
||||
rsync -av "$dir" "$BACKUP_DIR/$DATE/" >> "$LOG_FILE" 2>&1
|
||||
fi
|
||||
done
|
||||
|
||||
# Backup crontabs
|
||||
if [ -d /var/spool/cron/crontabs ]; then
|
||||
cp -r /var/spool/cron/crontabs "$BACKUP_DIR/$DATE/"
|
||||
fi
|
||||
|
||||
# Create system info snapshot
|
||||
{
|
||||
echo "=== System Info ==="
|
||||
uname -a
|
||||
lsb_release -a 2>/dev/null
|
||||
echo ""
|
||||
echo "=== Installed Packages ==="
|
||||
dpkg --get-selections
|
||||
echo ""
|
||||
echo "=== Services ==="
|
||||
systemctl list-unit-files --type=service --state=enabled
|
||||
} > "$BACKUP_DIR/$DATE/system-info.txt"
|
||||
|
||||
# Keep only last 30 days of system backups
|
||||
find "$BACKUP_DIR" -type d -name "20*" -mtime +30 -exec rm -rf {} \; 2>/dev/null
|
||||
|
||||
echo "$(date): System backup completed" >> "$LOG_FILE"
|
||||
@ -1,13 +1,50 @@
|
||||
---
|
||||
- name: Install development packages
|
||||
- name: Install basic development packages
|
||||
ansible.builtin.apt:
|
||||
name:
|
||||
# Development tools
|
||||
- git
|
||||
- nodejs
|
||||
- npm
|
||||
# Build tools
|
||||
- build-essential
|
||||
- python3
|
||||
- python3-pip
|
||||
state: present
|
||||
become: true
|
||||
|
||||
- name: Check if NodeSource Node.js is installed
|
||||
ansible.builtin.command: node --version
|
||||
register: node_version_check
|
||||
failed_when: false
|
||||
changed_when: false
|
||||
|
||||
- name: Add NodeSource GPG key
|
||||
ansible.builtin.get_url:
|
||||
url: https://deb.nodesource.com/gpgkey/nodesource.gpg.key
|
||||
dest: /etc/apt/keyrings/nodesource.asc
|
||||
mode: '0644'
|
||||
become: true
|
||||
when: node_version_check.rc != 0 or not node_version_check.stdout.startswith('v2')
|
||||
|
||||
- name: Add NodeSource repository
|
||||
ansible.builtin.apt_repository:
|
||||
repo: "deb [signed-by=/etc/apt/keyrings/nodesource.asc] https://deb.nodesource.com/node_22.x nodistro main"
|
||||
state: present
|
||||
update_cache: true
|
||||
become: true
|
||||
when: node_version_check.rc != 0 or not node_version_check.stdout.startswith('v2')
|
||||
|
||||
- name: Install Node.js 22 from NodeSource
|
||||
ansible.builtin.apt:
|
||||
name: nodejs
|
||||
state: present
|
||||
become: true
|
||||
when: node_version_check.rc != 0 or not node_version_check.stdout.startswith('v2')
|
||||
|
||||
- name: Verify Node.js installation
|
||||
ansible.builtin.command: node --version
|
||||
register: final_node_version
|
||||
changed_when: false
|
||||
|
||||
- name: Display Node.js version
|
||||
ansible.builtin.debug:
|
||||
msg: "Node.js version installed: {{ final_node_version.stdout }}"
|
||||
|
||||
61
roles/monitoring/README.md
Normal file
61
roles/monitoring/README.md
Normal file
@ -0,0 +1,61 @@
|
||||
# Role: monitoring
|
||||
|
||||
## Description
|
||||
Installs comprehensive system monitoring tools and custom monitoring scripts for performance analysis and security monitoring.
|
||||
|
||||
## Requirements
|
||||
- Ansible 2.9+
|
||||
- Debian/Ubuntu systems
|
||||
- Sufficient disk space for logs
|
||||
|
||||
## Installed Tools
|
||||
- **htop/btop**: Interactive process viewers
|
||||
- **iotop**: I/O monitoring
|
||||
- **nethogs**: Network usage per process
|
||||
- **iftop**: Network bandwidth monitoring
|
||||
- **ncdu**: Disk usage analyzer
|
||||
- **fail2ban**: Intrusion prevention
|
||||
- **logwatch**: Log analysis and reporting
|
||||
|
||||
## Custom Scripts
|
||||
- `/usr/local/bin/monitoring/sysinfo`: System overview dashboard
|
||||
- `/usr/local/bin/monitoring/netinfo`: Network monitoring script
|
||||
|
||||
## Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `monitoring_install_htop` | `true` | Install htop process viewer |
|
||||
| `monitoring_install_fail2ban` | `true` | Install intrusion prevention |
|
||||
| `monitoring_install_logwatch` | `true` | Install log analysis |
|
||||
| `monitoring_custom_scripts` | `true` | Install custom monitoring scripts |
|
||||
|
||||
## Dependencies
|
||||
- `base` role (for basic packages)
|
||||
|
||||
## Example Playbook
|
||||
|
||||
```yaml
|
||||
- hosts: servers
|
||||
roles:
|
||||
- role: monitoring
|
||||
monitoring_install_fail2ban: false
|
||||
```
|
||||
|
||||
## Tags
|
||||
- `monitoring`: All monitoring tasks
|
||||
- `tools`: Tool installation only
|
||||
- `scripts`: Custom script deployment
|
||||
- `security`: Security monitoring tools
|
||||
|
||||
## Fail2ban Configuration
|
||||
- **SSH protection**: Enabled by default
|
||||
- **Ban time**: 10 minutes
|
||||
- **Find time**: 10 minutes
|
||||
- **Max retry**: 5 attempts
|
||||
|
||||
## Notes
|
||||
- Creates monitoring user directories
|
||||
- Configures fail2ban with custom rules
|
||||
- Installs both CLI and snap-based tools
|
||||
- Custom scripts require manual execution
|
||||
64
roles/proxmox_vm/README.md
Normal file
64
roles/proxmox_vm/README.md
Normal file
@ -0,0 +1,64 @@
|
||||
# Role: proxmox_vm
|
||||
|
||||
## Description
|
||||
Creates and configures virtual machines on Proxmox VE hypervisor with cloud-init support and automated provisioning.
|
||||
|
||||
## Requirements
|
||||
- Ansible 2.9+
|
||||
- Proxmox VE server
|
||||
- `community.general` collection
|
||||
- Valid Proxmox credentials in vault
|
||||
|
||||
## Features
|
||||
- Automated VM creation with cloud-init
|
||||
- Configurable CPU, memory, and disk resources
|
||||
- Network configuration with DHCP or static IP
|
||||
- SSH key injection for passwordless access
|
||||
- Ubuntu Server template support
|
||||
|
||||
## Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `vm_memory` | `8192` | RAM allocation in MB |
|
||||
| `vm_cores` | `2` | Number of CPU cores |
|
||||
| `vm_disk_size` | `20G` | Disk size |
|
||||
| `vm_iso` | `ubuntu-24.04-live-server-amd64.iso` | Installation ISO |
|
||||
| `vm_ciuser` | `master` | Default cloud-init user |
|
||||
| `vm_storage` | `local-lvm` | Proxmox storage backend |
|
||||
|
||||
## Vault Variables (Required)
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `vault_proxmox_host` | Proxmox server IP/hostname |
|
||||
| `vault_proxmox_user` | Proxmox username (e.g., root@pam) |
|
||||
| `vault_proxmox_password` | Proxmox password |
|
||||
| `vault_vm_cipassword` | VM default user password |
|
||||
| `vault_ssh_public_key` | SSH public key for VM access |
|
||||
|
||||
## Dependencies
|
||||
- Proxmox VE server with API access
|
||||
- ISO images uploaded to Proxmox storage
|
||||
|
||||
## Example Playbook
|
||||
|
||||
```yaml
|
||||
- hosts: localhost
|
||||
roles:
|
||||
- role: proxmox_vm
|
||||
vm_name: "test-vm"
|
||||
vm_id: 999
|
||||
vm_memory: 4096
|
||||
```
|
||||
|
||||
## Tags
|
||||
- `proxmox`: All Proxmox operations
|
||||
- `vm`: VM creation tasks
|
||||
- `infrastructure`: Infrastructure provisioning
|
||||
|
||||
## Notes
|
||||
- Requires Proxmox API credentials in vault
|
||||
- VM IDs must be unique on Proxmox cluster
|
||||
- Cloud-init requires compatible ISO images
|
||||
- VMs are created but not started by default
|
||||
@ -1,38 +1,46 @@
|
||||
Role Name
|
||||
=========
|
||||
# Role: shell
|
||||
|
||||
A brief description of the role goes here.
|
||||
## Description
|
||||
Configures modern shell environment with Zsh, Oh My Zsh, and Powerlevel10k theme for enhanced terminal experience.
|
||||
|
||||
Requirements
|
||||
------------
|
||||
## Requirements
|
||||
- Ansible 2.9+
|
||||
- Debian/Ubuntu target systems
|
||||
- Internet access for downloading themes and plugins
|
||||
|
||||
Any pre-requisites that may not be covered by Ansible itself or the role should be mentioned here. For instance, if the role uses the EC2 module, it may be a good idea to mention in this section that the boto package is required.
|
||||
## Features
|
||||
- Installs and configures Zsh as default shell
|
||||
- Sets up Oh My Zsh framework
|
||||
- Installs Powerlevel10k theme
|
||||
- Adds useful plugins: syntax highlighting, autosuggestions
|
||||
- Configures tmux and fzf for enhanced productivity
|
||||
|
||||
Role Variables
|
||||
--------------
|
||||
## Variables
|
||||
|
||||
A description of the settable variables for this role should go here, including any variables that are in defaults/main.yml, vars/main.yml, and any variables that can/should be set via parameters to the role. Any variables that are read from other roles and/or the global scope (ie. hostvars, group vars, etc.) should be mentioned here as well.
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `shell_user` | `{{ ansible_user }}` | User to configure shell for |
|
||||
| `shell_install_ohmyzsh` | `true` | Whether to install Oh My Zsh |
|
||||
| `shell_install_p10k` | `true` | Whether to install Powerlevel10k theme |
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
## Dependencies
|
||||
- `base` role (for basic packages)
|
||||
|
||||
A list of other roles hosted on Galaxy should go here, plus any details in regards to parameters that may need to be set for other roles, or variables that are used from other roles.
|
||||
## Example Playbook
|
||||
|
||||
Example Playbook
|
||||
----------------
|
||||
```yaml
|
||||
- hosts: dev
|
||||
roles:
|
||||
- { role: shell, shell_user: "myuser" }
|
||||
```
|
||||
|
||||
Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
|
||||
## Tags
|
||||
- `shell`: All shell configuration tasks
|
||||
- `zsh`: Zsh installation and configuration
|
||||
- `ohmyzsh`: Oh My Zsh framework setup
|
||||
- `theme`: Theme and plugin configuration
|
||||
|
||||
- hosts: servers
|
||||
roles:
|
||||
- { role: username.rolename, x: 42 }
|
||||
|
||||
License
|
||||
-------
|
||||
|
||||
BSD
|
||||
|
||||
Author Information
|
||||
------------------
|
||||
|
||||
An optional section for the role authors to include contact information, or a website (HTML is not allowed).
|
||||
## Notes
|
||||
- Changes default shell to zsh for the target user
|
||||
- Downloads themes and plugins from GitHub
|
||||
- Requires logout/login to see changes
|
||||
@ -21,8 +21,8 @@
|
||||
become: true
|
||||
become_user: "{{ shell_target_user }}"
|
||||
loop:
|
||||
- { name: "zsh-syntax-highlighting", repo: "https://github.com/zsh-users/zsh-syntax-highlighting.git" }
|
||||
- { name: "zsh-autosuggestions", repo: "https://github.com/zsh-users/zsh-autosuggestions.git" }
|
||||
- {name: "zsh-syntax-highlighting", repo: "https://github.com/zsh-users/zsh-syntax-highlighting.git"}
|
||||
- {name: "zsh-autosuggestions", repo: "https://github.com/zsh-users/zsh-autosuggestions.git"}
|
||||
|
||||
- name: Set zsh as default shell for user
|
||||
ansible.builtin.user:
|
||||
|
||||
47
roles/snap/README.md
Normal file
47
roles/snap/README.md
Normal file
@ -0,0 +1,47 @@
|
||||
# Role: snap
|
||||
|
||||
## Description
|
||||
Installs and configures Snap package manager and essential snap applications for development.
|
||||
|
||||
## Requirements
|
||||
- Ansible 2.9+
|
||||
- Ubuntu/Debian systems
|
||||
- Internet access for snap store
|
||||
|
||||
## Installed Snap Applications
|
||||
- **Visual Studio Code**: Popular code editor
|
||||
- **Cursor**: AI-powered code editor
|
||||
- **yq**: YAML processor
|
||||
- **btop**: Modern system monitor
|
||||
- **bandwhich**: Network utilization monitor
|
||||
|
||||
## Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `snap_install_vscode` | `true` | Install VS Code via snap |
|
||||
| `snap_install_cursor` | `true` | Install Cursor editor |
|
||||
| `snap_install_yq` | `true` | Install yq YAML processor |
|
||||
| `snap_install_btop` | `true` | Install btop system monitor |
|
||||
|
||||
## Dependencies
|
||||
- `base` role (for system packages)
|
||||
|
||||
## Example Playbook
|
||||
|
||||
```yaml
|
||||
- hosts: dev
|
||||
roles:
|
||||
- { role: snap, snap_install_cursor: false }
|
||||
```
|
||||
|
||||
## Tags
|
||||
- `snap`: All snap-related tasks
|
||||
- `apps`: Application installations
|
||||
- `editors`: Code editor installations
|
||||
|
||||
## Notes
|
||||
- Enables universe repository for snap support
|
||||
- Waits for snap system to be ready before installing
|
||||
- Some snaps may require additional permissions
|
||||
- Classic confinement used for development tools
|
||||
@ -4,10 +4,10 @@
|
||||
name: openssh-server
|
||||
state: present
|
||||
|
||||
- name: Backup original SSH configuration
|
||||
- name: Create safety copy of original SSH configuration
|
||||
ansible.builtin.copy:
|
||||
src: /etc/ssh/sshd_config
|
||||
dest: /etc/ssh/sshd_config.backup
|
||||
dest: /etc/ssh/sshd_config.original
|
||||
remote_src: true
|
||||
mode: '0600'
|
||||
force: false
|
||||
@ -27,7 +27,7 @@
|
||||
port: "{{ ssh_port }}"
|
||||
proto: tcp
|
||||
|
||||
- name: Configure firewalls - allow SSH by name (backup)
|
||||
- name: Configure firewalls - allow SSH by name (fallback)
|
||||
community.general.ufw:
|
||||
rule: allow
|
||||
name: OpenSSH
|
||||
|
||||
63
roles/tailscale/README.md
Normal file
63
roles/tailscale/README.md
Normal file
@ -0,0 +1,63 @@
|
||||
# Role: tailscale
|
||||
|
||||
## Description
|
||||
Installs and configures Tailscale VPN mesh networking for secure connectivity across all managed hosts.
|
||||
|
||||
## Requirements
|
||||
- Ansible 2.9+
|
||||
- Debian/Ubuntu/Alpine Linux
|
||||
- Tailscale account and auth key
|
||||
- Internet connectivity
|
||||
|
||||
## Features
|
||||
- Cross-platform support (Debian, Ubuntu, Alpine)
|
||||
- Automatic OS detection and package installation
|
||||
- Secure auth key management via vault
|
||||
- Configurable network settings
|
||||
- SSH over Tailscale support
|
||||
|
||||
## Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `tailscale_auth_key` | `{{ vault_tailscale_auth_key }}` | Auth key from vault |
|
||||
| `tailscale_hostname` | `{{ inventory_hostname }}` | Custom hostname |
|
||||
| `tailscale_accept_routes` | `true` | Accept subnet routes |
|
||||
| `tailscale_accept_dns` | `true` | Accept DNS settings |
|
||||
| `tailscale_ssh` | `true` | Enable SSH server |
|
||||
| `tailscale_shields_up` | `false` | Block incoming connections |
|
||||
|
||||
## Vault Variables (Required)
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `vault_tailscale_auth_key` | Tailscale authentication key |
|
||||
|
||||
## Dependencies
|
||||
- Valid Tailscale account
|
||||
- Auth key stored in Ansible vault
|
||||
|
||||
## Example Playbook
|
||||
|
||||
```yaml
|
||||
- hosts: all
|
||||
roles:
|
||||
- role: tailscale
|
||||
tailscale_accept_routes: false
|
||||
```
|
||||
|
||||
## Tags
|
||||
- `tailscale`: All Tailscale tasks
|
||||
- `vpn`: VPN configuration
|
||||
- `network`: Network setup
|
||||
|
||||
## Supported Platforms
|
||||
- **Debian**: bullseye, bookworm, trixie
|
||||
- **Ubuntu**: focal, jammy, noble
|
||||
- **Alpine**: all versions
|
||||
|
||||
## Notes
|
||||
- Requires Tailscale auth key in vault
|
||||
- Machines need approval in Tailscale admin console
|
||||
- Supports both reusable and ephemeral keys
|
||||
- Automatic logout/re-auth on key changes
|
||||
@ -15,7 +15,7 @@
|
||||
|
||||
- name: Parse Tailscale status
|
||||
ansible.builtin.set_fact:
|
||||
tailscale_connected: "{{ (tailscale_status.stdout | from_json).BackendState == 'Running' if tailscale_status.rc == 0 else false }}"
|
||||
tailscale_connected: "{{ (tailscale_status.stdout | from_json).BackendState == 'Running' if tailscale_status.rc == 0 and tailscale_status.stdout != '' else false }}"
|
||||
|
||||
- name: Reset Tailscale if requested
|
||||
ansible.builtin.command: tailscale logout
|
||||
@ -27,7 +27,7 @@
|
||||
|
||||
- name: Connect to Tailscale network
|
||||
ansible.builtin.command: >
|
||||
tailscale up
|
||||
tailscale up --reset
|
||||
{{ '--auth-key=' + tailscale_auth_key if tailscale_auth_key else '' }}
|
||||
{{ '--hostname=' + tailscale_hostname if tailscale_hostname else '' }}
|
||||
{{ '--advertise-routes=' + tailscale_advertise_routes if tailscale_advertise_routes else '' }}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user