f5e32afd81
Some checks failed
CI / lint-and-test (pull_request) Failing after 1m20s
CI / ansible-validation (pull_request) Successful in 6m40s
CI / secret-scanning (pull_request) Successful in 2m36s
CI / dependency-scan (pull_request) Successful in 6m12s
CI / sast-scan (pull_request) Successful in 6m48s
CI / license-check (pull_request) Successful in 1m16s
CI / vault-check (pull_request) Failing after 6m13s
CI / playbook-test (pull_request) Successful in 6m34s
CI / container-scan (pull_request) Successful in 6m57s
CI / sonar-analysis (pull_request) Failing after 1m10s
CI / workflow-summary (pull_request) Successful in 1m11s
- Add roles/pote: Python/venv deployment role with PostgreSQL, cron jobs - Add playbooks/app/: Proxmox app stack provisioning and configuration - Add roles/app_setup: Generic app deployment role (Node.js/systemd) - Add roles/base_os: Base OS hardening role - Enhance roles/proxmox_vm: Split LXC/KVM tasks, improve error handling - Add IP uniqueness validation: Preflight check for duplicate IPs within projects - Add Proxmox-side IP conflict detection: Check existing LXC net0 configs - Update inventories/production/group_vars/all/main.yml: Add pote project config - Add vault.example.yml: Template for POTE secrets (git key, DB, SMTP) - Update .gitignore: Exclude deploy keys, backup files, and other secrets - Update documentation: README, role docs, execution flow guides Security: - All secrets stored in encrypted vault.yml (never committed in plaintext) - Deploy keys excluded via .gitignore - IP conflict guardrails prevent accidental duplicate IP assignments
183 lines
6.1 KiB
Markdown
183 lines
6.1 KiB
Markdown
# 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` |
|
|
| `proxmox-info` | Show Proxmox guest info (LXC/VM) | `make proxmox-info [PROJECT=projectA] [ALL=true] [TYPE=lxc\|qemu\|all]` |
|
|
| `app-provision` | Provision app project guests on Proxmox | `make app-provision PROJECT=projectA` |
|
|
| `app-configure` | Configure OS + app on project guests | `make app-configure PROJECT=projectA` |
|
|
| `app` | Provision + configure app project guests | `make app PROJECT=projectA` |
|
|
| `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` |
|
|
| `edit-group-vault` | Edit encrypted group vars (production inventory) | `make edit-group-vault` |
|
|
|
|
## 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 |