auberge 0.6.15

CLI tool for managing self-hosted infrastructure with Ansible
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

# SSH Configuration

## Overview

Auberge uses a three-tier SSH key resolution system for backup operations, following CLI best practices.

## Resolution Hierarchy

**Precedence**: `--ssh-key` flag > `host.ssh_key` config > default derivation

### Tier 1: Ad-hoc Override (--ssh-key flag)

Use for one-time key overrides:

```bash
auberge backup create --host myhost --ssh-key /path/to/custom/key
```

### Tier 2: Configured Key (hosts.toml)

Configure persistent SSH keys per host:

```bash
# During host creation
auberge host add myhost --address 10.0.0.1 --ssh-key ~/.ssh/custom_key

# Or edit existing host
auberge host edit myhost
```

Configuration stored in: `~/.config/auberge/hosts.toml`

Example:

```toml
[[hosts]]
name = "myhost"
address = "10.0.0.1"
user = "ansible"
port = 22
ssh_key = "~/.ssh/identities/custom_key"
```

### Tier 3: Default Derivation

If no override or config exists, derives path:

- Pattern: `~/.ssh/identities/{user}_{hostname}`
- Example: `~/.ssh/identities/ansible_myhost`

Generate default key:

```bash
auberge ssh keygen --host myhost --user ansible
```

### Interactive Fallback

If the default key doesn't exist, Auberge will:

1. Scan `~/.ssh/` and `~/.ssh/identities/` for available keys
2. Present an interactive selector to choose a key
3. Optionally save your selection to the host configuration

This provides a smooth experience when working with existing keys or migrating infrastructure.

## Importing from SSH Config

When adding a host interactively, you can import from your existing `~/.ssh/config`:

```bash
auberge host add

# If ~/.ssh/config exists, shows:
Found 3 host(s) in ~/.ssh/config

? Import from SSH config or enter manually?:
  > Enter manually
    ansible-old (203.0.113.10)
    myserver (10.0.0.1)
```

Selecting a host from SSH config auto-fills:

- Host name
- Address (HostName)
- User
- Port
- SSH key (IdentityFile)

This eliminates re-entering connection details you already have configured.

## Best Practices

1. **Fresh installs**: Use Tier 3 (default derivation)
2. **Existing infrastructure**: Use Tier 2 (configure once)
3. **Testing/debugging**: Use Tier 1 (ad-hoc override)

## Troubleshooting

### "No SSH keys found"

If you see this error, you have no SSH keys available:

1. Generate a new key: `auberge ssh keygen --host <host>`
2. Or copy existing keys to `~/.ssh/` or `~/.ssh/identities/`

### "Default SSH key not found"

The tool will automatically offer interactive key selection:

1. Shows all available SSH keys in `~/.ssh/` and `~/.ssh/identities/`
2. Select the key you want to use
3. Optionally save it to the host configuration for future use

### "Configured SSH key not found"

- Tool falls back to default derivation with warning
- If default doesn't exist, falls back to interactive selection
- Update config: `auberge host edit <host>`

### Permission warnings

Fix with: `chmod 600 /path/to/key`

## hosts.toml vs inventory.yml

- **hosts.toml**: User-specific hosts (backup operations)
  - Location: `~/.config/auberge/hosts.toml`
  - Not version controlled
  - Managed via `auberge host` commands

- **inventory.yml**: Ansible playbooks (shared infrastructure)
  - Location: `ansible/inventory.yml`
  - Version controlled
  - Used by `auberge ansible` commands