Skip to content

Commit 724f0c5

Browse files
pau-hedgehogpau-hedgehog
committed
feat(reference): Update and expand reference CLI sections
Updated hhfabctl section. Added hhfab section. Signed-off-by: Pau Capdevila <pau@githedgehog.com>
1 parent a00c0ea commit 724f0c5

File tree

3 files changed

+333
-12
lines changed

3 files changed

+333
-12
lines changed

‎docs/reference/.pages

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
11
nav:
22
- Fabric API: api.md
3+
- Fabric CLI: cli.md
4+
- Fabricator CLI: hhfab-cli.md
35
- ...

‎docs/reference/cli.md

Lines changed: 184 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
1-
# Fabric CLI
21

3-
!!! warning ""
4-
Under construction.
2+
# Fabric CLI Reference
53

64
Currently Fabric CLI is represented by a kubectl plugin `kubectl-fabric` automatically installed on the Control Node.
75
It is a wrapper around `kubectl` and Kubernetes client which allows to manage Fabric resources in a more convenient way.
86
Fabric CLI only provides a subset of the functionality available via Fabric API and is focused on simplifying objects
97
creation and some manipulation with the already existing objects while main get/list/update operations are expected to
108
be done using `kubectl`.
119

10+
## Usage
11+
1212
```bash
1313
core@control-1 ~ $ kubectl fabric
1414
NAME:
@@ -35,24 +35,196 @@ GLOBAL OPTIONS:
3535
--version, -V print the version
3636
```
3737

38-
## VPC
38+
## Commands and Options
39+
40+
| Command | Subcommand | Options | Description |
41+
|---------|------------|---------|-------------|
42+
| **vpc** | create | `--name`, `--subnet` (required), `--vlan` (required), `--dhcp`, `--dhcp-range-start`, `--dhcp-range-end`, `--print` | Create a new VPC. |
43+
| | attach | `--name`, `--vpc-subnet` (required), `--connection` (required), `--print` | Attach VPC to a server connection. |
44+
| | peer | `--name`, `--vpc` (required), `--remote`, `--print` | Peer two VPCs. |
45+
| | wipe | `--yes` | Delete all VPCs and peerings. |
46+
| **switch** | ip | `--name`, `--username`, `--verbose` | Get switch management IP address. |
47+
| | ssh | `--name`, `--username`, `--verbose` | SSH into the switch. |
48+
| | serial | `--name`, `--username`, `--verbose` | Run serial console for the switch. |
49+
| | reboot | `--name`, `--yes`, `--verbose` | Reboot the switch. |
50+
| | power-reset | `--name`, `--yes`, `--verbose` | Power reset the switch. |
51+
| | reinstall | `--name`, `--yes`, `--verbose` | Reinstall the switch. |
52+
| **connection** | get | `--type` | Get details of existing connections. |
53+
| **switchgroup** | create | `--name`, `--print` | Create a new switch group. |
54+
| **external** | create | `--name`, `--ipv4-namespace`, `--inbound-community`, `--outbound-community`, `--print` | Create a new external connection. |
55+
| | peer | `--vpc`, `--external`, `--vpc-subnet`, `--external-prefix`, `--print` | Peer external and VPC. |
56+
| **wiring** | export | `--vpcs`, `--externals`, `--switch-profiles` | Export wiring diagram. |
57+
| **inspect** | fabric | `--verbose`, `--output` (default: "text") | Inspect overall Fabric state. |
58+
| | switch | `--name`, `--output` (default: "text") | Inspect switch status and ports. |
59+
| | port | `--name`, `--output` (default: "text") | Inspect switch port status. |
60+
| | server | `--name`, `--output` (default: "text") | Inspect server status. |
61+
| | connection | `--name`, `--output` (default: "text") | Inspect connection details. |
62+
| | vpc | `--name`, `--subnet`, `--output` (default: "text") | Inspect VPC details. |
63+
| | bgp | `--switch-name`, `--strict` | Inspect BGP neighbors. |
64+
| | lldp | `--switch-name`, `--strict`, `--fabric`, `--external`, `--server` | Inspect LLDP neighbors. |
65+
| | ip | `--address` | Inspect IP details. |
66+
| | mac | `--address` | Inspect MAC details. |
67+
| | access | `--source`, `--destination` | Inspect connectivity. |
68+
69+
---
70+
71+
## Command Details
72+
73+
### `vpc`
74+
VPC management commands.
75+
76+
#### `create`
77+
Create a VPC:
78+
79+
```bash
80+
kubectl fabric vpc create --name vpc-1 --subnet 10.0.1.0/24 --vlan 1001 --dhcp --dhcp-start 10.0.1.10 --dhcp-end 10.0.1.100
81+
```
82+
83+
84+
**Options:**
85+
- `--name` – VPC name.
86+
- `--subnet` – Subnet in CIDR format (**required**).
87+
- `--vlan` – VLAN ID (**required**).
88+
- `--dhcp` – Enable DHCP.
89+
- `--dhcp-range-start` – Start of DHCP range.
90+
- `--dhcp-range-end` – End of DHCP range.
91+
- `--print` – Print object as YAML.
3992

40-
Create VPC named `vpc-1` with subnet `10.0.1.0/24` and VLAN `1001` with DHCP enabled and DHCP range starting from
41-
`10.0.1.10` (optional):
93+
#### `attach`
94+
Attach a VPC to a connection:
4295

4396
```bash
44-
core@control-1 ~ $ kubectl fabric vpc create --name vpc-1 --subnet 10.0.1.0/24 --vlan 1001 --dhcp --dhcp-start 10.0.1.10
97+
kubectl fabric vpc attach --vpc-subnet vpc-1/default --connection server-01
4598
```
4699

47-
Attach previously created VPC to the server `server-01` (which is connected to the Fabric using the
48-
`server-01--mclag--leaf-01--leaf-02` Connection):
100+
101+
**Options:**
102+
- `--vpc-subnet` – VPC subnet name (**required**).
103+
- `--connection` – Connection name (**required**).
104+
105+
#### `peer`
106+
Create a peering between VPCs:
49107

50108
```bash
51-
core@control-1 ~ $ kubectl fabric vpc attach --vpc-subnet vpc-1/default --connection server-01--mclag--leaf-01--leaf-02
109+
kubectl fabric vpc peer --vpc vpc-1 --vpc vpc-2
52110
```
53111

54-
To peer VPC with another VPC (e.g. `vpc-2`) use the following command:
112+
113+
**Options:**
114+
- `--vpc` – VPC names (**required**).
115+
116+
#### `wipe`
117+
Delete all VPCs:
55118

56119
```bash
57-
core@control-1 ~ $ kubectl fabric vpc peer --vpc vpc-1 --vpc vpc-2
120+
kubectl fabric vpc wipe --yes
58121
```
122+
123+
124+
**Options:**
125+
- `--yes` – Confirm deletion.
126+
127+
---
128+
129+
### `switch`
130+
Switch management commands.
131+
132+
#### `ip`
133+
Get switch IP:
134+
135+
```bash
136+
kubectl fabric switch ip --name switch-01
137+
```
138+
139+
140+
**Options:**
141+
- `--name` – Switch name.
142+
- `--username` – SSH username (default: "admin").
143+
144+
#### `reboot`
145+
Reboot the switch:
146+
147+
```bash
148+
kubectl fabric switch reboot --name switch-01 --yes
149+
```
150+
151+
152+
**Options:**
153+
- `--name` – Switch name.
154+
- `--yes` – Confirm reboot.
155+
156+
---
157+
158+
### `connection`
159+
Get connection details:
160+
161+
```bash
162+
kubectl fabric connection get management
163+
```
164+
165+
166+
**Options:**
167+
- `--type` – Connection type (`management`, `fabric`, `vpc-loopback`).
168+
169+
---
170+
171+
### `switchgroup`
172+
Create a switch group:
173+
174+
```bash
175+
kubectl fabric switchgroup create --name sg-01
176+
```
177+
178+
179+
**Options:**
180+
- `--name` – Switch group name.
181+
182+
---
183+
184+
### `external`
185+
Create an external connection:
186+
187+
```bash
188+
kubectl fabric external create --name ext-01 --ipv4-namespace default
189+
```
190+
191+
192+
**Options:**
193+
- `--name` – External name.
194+
- `--ipv4-namespace` – IPv4 namespace.
195+
196+
---
197+
198+
### `wiring`
199+
Export wiring diagram:
200+
201+
```bash
202+
kubectl fabric wiring export --vpcs --externals
203+
```
204+
205+
206+
**Options:**
207+
- `--vpcs` – Include VPCs (default: true).
208+
- `--externals` – Include externals (default: true).
209+
210+
---
211+
212+
### `inspect`
213+
Inspect Fabric objects:
214+
215+
```bash
216+
kubectl fabric inspect fabric --output text
217+
```
218+
219+
220+
**Options:**
221+
- `--output` – Output format (`text`, `yaml`, `json`).
222+
223+
---
224+
225+
## Global Options
226+
- `--verbose`, `-v` – Enable verbose output (includes debug).
227+
- `--help`, `-h` – Show help.
228+
- `--version`, `-V` – Display version information.
229+
- `--yes`, `-y` – Confirm potentially dangerous actions.
230+

‎docs/reference/hhfab-cli.md

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
2+
# Fabricator CLI Reference
3+
4+
The `hhfab` CLI is the Hedgehog Fabricator command-line tool for building, installing, and managing Hedgehog Fabric environments.
5+
6+
## Usage
7+
8+
```bash
9+
hhfab [global options] command [command options]
10+
```
11+
12+
## Version
13+
14+
Check the version with:
15+
16+
```bash
17+
hhfab --version
18+
```
19+
20+
## Commands and Options
21+
22+
| Command | Subcommand | Options | Description |
23+
|---------|------------|---------|-------------|
24+
| **init** | — | `--registry-repo`, `--registry-prefix`, `--config`, `--force`, `--wiring`, `--fabric-mode`, `--tls-san`, `--default-authorized-keys`, `--default-password-hash`, `--dev`, `--include-onie`, `--import-host-upstream`, `--control-node-mgmt-link`, `--gateway` | Initialize working directory and create `fab.yaml` and other files. |
25+
| **validate** | — | `--hydrate-mode` *(default: "if-not-present")* | Validate configuration and wiring files. |
26+
| **diagram** | — | `--format` *(default: "drawio")*, `--style` *(default: "hedgehog")* | Generate network topology diagrams. |
27+
| **versions** | — | — | Print versions of all components. |
28+
| **build** | — | `--mode` *(default: "iso")* | Build installers. |
29+
| **vlab** | generate | `--spines-count`, `--fabric-links-count`, `--mclag-leafs-count`, `--eslag-leaf-groups`, `--orphan-leafs-count`, `--mclag-session-links`, `--mclag-peer-links`, `--vpc-loopbacks`, `--mclag-servers`, `--eslag-servers`, `--unbundled-servers`, `--bundled-servers`, `--no-switches`, `--gateway-uplinks` *(default: 2)* | Generate VLAB wiring diagram. |
30+
| | up | `--recreate`, `--kill-stale` *(default: true)*, `--controls-restricted` *(default: true)*, `--servers-restricted` *(default: true)*, `--build-mode` *(default: "iso")*, `--control-upgrade`, `--fail-fast` *(default: true)*, `--ready`, `--collect-show-tech` | Start the Virtual Lab environment. |
31+
| | ssh | `--name` | SSH to a VLAB VM or hardware. |
32+
| | serial | `--name` | Get serial console of a VLAB VM or hardware. |
33+
| | seriallog | `--name` | Get serial console log of a VLAB VM or hardware. |
34+
| | show-tech | — | Collect diagnostic information from all VLAB devices. |
35+
| | setup-vpcs | `--wait-switches-ready` *(default: true)*, `--force-cleanup`, `--vlanns` *(default: "default")*, `--ipns` *(default: "default")*, `--servers-per-subnet` *(default: 1)*, `--subnets-per-vpc` *(default: 1)*, `--dns-servers`, `--time-servers`, `--interface-mtu` | Setup VPCs and VPCAttachments. |
36+
| | setup-peerings | `--wait-switches-ready` *(default: true)* | Setup VPC and external peerings. |
37+
| | test-connectivity | `--wait-switches-ready` *(default: true)*, `--pings` *(default: 5)*, `--iperfs` *(default: 10)*, `--iperfs-speed` *(default: 8500)*, `--curls` *(default: 3)*, `--source`, `--destination` | Test connectivity between servers. |
38+
| | wait-switches | — | Wait for switches to be ready. |
39+
| | inspect-switches | `--wait-applied-for` *(default: 120)*, `--strict` *(default: true)* | Wait for readiness and inspect switches. |
40+
| **switch** | reinstall | `--name`, `--mode` *(default: "hard-reset")*, `--wait-ready`, `--switch-username`, `--switch-password`, `--pdu-username`, `--pdu-password` | Reboot/reset and reinstall NOS on switches. |
41+
| | power | `--name`, `--action` *(default: "cycle")*, `--pdu-username`, `--pdu-password` | Manage switch power state using the PDU. |
42+
| **_helpers** | setup-taps | `--count` *(max: 100)* | Setup tap devices and a bridge for VLAB. |
43+
| | vfio-pci-bind | — | Bind devices to vfio-pci driver for passthrough. |
44+
| | kill-stale-vms | — | Kill stale VLAB VMs. |
45+
46+
## Command Details
47+
48+
### `init`
49+
Initializes working directory and configuration files.
50+
51+
**Usage:**
52+
```bash
53+
hhfab init [options]
54+
```
55+
56+
**Options:**
57+
- `--registry-repo` – Download artifacts from specific registry repository.
58+
- `--registry-prefix` – Prepend artifact names with specific prefix.
59+
- `--config` – Use existing config file.
60+
- `--force` – Overwrite existing files.
61+
- `--wiring` – Include wiring diagram file.
62+
- `--fabric-mode` *(default: "spine-leaf")* – Set fabric mode.
63+
- `--tls-san` – IPs and DNS names used to access the API.
64+
- `--default-authorized-keys` – Default authorized keys.
65+
- `--default-password-hash` – Default password hash.
66+
- `--dev` – Use default dev credentials (unsafe).
67+
- `--include-onie` – Include ONIE updaters for supported switches.
68+
- `--import-host-upstream` – Import host repo/prefix as an upstream registry mode.
69+
- `--control-node-mgmt-link` – Control node management link.
70+
- `--gateway` – Add and enable gateway node.
71+
72+
---
73+
74+
### `validate`
75+
Validates the configuration and wiring files.
76+
77+
**Usage:**
78+
```bash
79+
hhfab validate [options]
80+
```
81+
82+
**Options:**
83+
- `--hydrate-mode` *(default: "if-not-present")* – Set hydrate mode.
84+
85+
---
86+
87+
### `diagram`
88+
Generate network topology diagrams.
89+
90+
**Usage:**
91+
```bash
92+
hhfab diagram [options]
93+
```
94+
95+
**Options:**
96+
- `--format` *(default: "drawio")* – Diagram format.
97+
- `--style` *(default: "hedgehog")* – Diagram style.
98+
99+
---
100+
101+
### `versions`
102+
Print versions of all components.
103+
104+
**Usage:**
105+
```bash
106+
hhfab versions
107+
```
108+
109+
---
110+
111+
### `build`
112+
Build Hedgehog installer.
113+
114+
**Usage:**
115+
```bash
116+
hhfab build [options]
117+
```
118+
119+
**Options:**
120+
- `--mode` *(default: "iso")* – Build mode (iso, qcow2, raw).
121+
122+
---
123+
124+
### `switch reinstall`
125+
Reinstall the OS on switches.
126+
127+
**Usage:**
128+
```bash
129+
hhfab switch reinstall [options]
130+
```
131+
132+
**Options:**
133+
- `--name` – Switch name.
134+
- `--mode` *(default: "hard-reset")* – Restart mode.
135+
- `--wait-ready` – Wait until switch is ready.
136+
- `--switch-username` – Switch username for reboot mode.
137+
- `--switch-password` – Switch password for reboot mode.
138+
139+
---
140+
141+
## Global Options
142+
- `--workdir` – Specify working directory.
143+
- `--cache-dir` – Specify cache directory.
144+
- `--verbose`, `-v` – Verbose output (includes debug).
145+
- `--brief`, `-b` – Brief output (only warnings and errors).
146+
- `--yes`, `-y` – Assume "yes" for potentially dangerous operations.
147+

0 commit comments

Comments
 (0)