Skip to content

Commit daa16ec

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 <[email protected]>
1 parent a00c0ea commit daa16ec

File tree

3 files changed

+330
-36
lines changed

3 files changed

+330
-36
lines changed

‎docs/reference/.pages

+2
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

+181-36
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,203 @@
1-
# Fabric CLI
21

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

6-
Currently Fabric CLI is represented by a kubectl plugin `kubectl-fabric` automatically installed on the Control Node.
7-
It is a wrapper around `kubectl` and Kubernetes client which allows to manage Fabric resources in a more convenient way.
8-
Fabric CLI only provides a subset of the functionality available via Fabric API and is focused on simplifying objects
9-
creation and some manipulation with the already existing objects while main get/list/update operations are expected to
10-
be done using `kubectl`.
4+
The `hhfabctl` CLI is the Hedgehog Fabricator command-line interface (CLI) for managing Fabric resources.
5+
It provides an efficient way to create, manage, and inspect Fabric objects through a simplified CLI interface.
6+
This document serves as a reference guide for all available commands and options.
7+
8+
## Usage
9+
10+
```bash
11+
hhfabctl [global options] command [command options]
12+
```
13+
14+
## Version
15+
16+
Check the version with:
17+
18+
```bash
19+
hhfabctl --version
20+
```
21+
22+
## Commands and Options
23+
24+
| Command | Subcommand | Options | Description |
25+
|---------|------------|---------|-------------|
26+
| **vpc** | create | `--name`, `--subnet` (required), `--vlan` (required), `--dhcp`, `--dhcp-range-start`, `--dhcp-range-end`, `--print` | Create a new VPC. |
27+
| | attach | `--name`, `--vpc-subnet` (required), `--connection` (required), `--print` | Attach VPC to a server connection. |
28+
| | peer | `--name`, `--vpc` (required), `--remote`, `--print` | Peer two VPCs. |
29+
| | wipe | `--yes` | Delete all VPCs and peerings. |
30+
| **switch** | ip | `--name`, `--username`, `--verbose` | Get switch management IP address. |
31+
| | ssh | `--name`, `--username`, `--verbose` | SSH into the switch. |
32+
| | serial | `--name`, `--username`, `--verbose` | Run serial console for the switch. |
33+
| | reboot | `--name`, `--yes`, `--verbose` | Reboot the switch. |
34+
| | power-reset | `--name`, `--yes`, `--verbose` | Power reset the switch. |
35+
| | reinstall | `--name`, `--yes`, `--verbose` | Reinstall the switch. |
36+
| **connection** | get | `--type` | Get details of existing connections. |
37+
| **switchgroup** | create | `--name`, `--print` | Create a new switch group. |
38+
| **external** | create | `--name`, `--ipv4-namespace`, `--inbound-community`, `--outbound-community`, `--print` | Create a new external connection. |
39+
| | peer | `--vpc`, `--external`, `--vpc-subnet`, `--external-prefix`, `--print` | Peer external and VPC. |
40+
| **wiring** | export | `--vpcs`, `--externals`, `--switch-profiles` | Export wiring diagram. |
41+
| **inspect** | fabric | `--verbose`, `--output` (default: "text") | Inspect overall Fabric state. |
42+
| | switch | `--name`, `--output` (default: "text") | Inspect switch status and ports. |
43+
| | port | `--name`, `--output` (default: "text") | Inspect switch port status. |
44+
| | server | `--name`, `--output` (default: "text") | Inspect server status. |
45+
| | connection | `--name`, `--output` (default: "text") | Inspect connection details. |
46+
| | vpc | `--name`, `--subnet`, `--output` (default: "text") | Inspect VPC details. |
47+
| | bgp | `--switch-name`, `--strict` | Inspect BGP neighbors. |
48+
| | lldp | `--switch-name`, `--strict`, `--fabric`, `--external`, `--server` | Inspect LLDP neighbors. |
49+
| | ip | `--address` | Inspect IP details. |
50+
| | mac | `--address` | Inspect MAC details. |
51+
| | access | `--source`, `--destination` | Inspect connectivity. |
52+
53+
---
54+
55+
## Command Details
56+
57+
### `vpc`
58+
VPC management commands.
59+
60+
#### `create`
61+
Create a VPC:
1162

1263
```bash
13-
core@control-1 ~ $ kubectl fabric
14-
NAME:
15-
kubectl fabric - Hedgehog Fabric API kubectl plugin
64+
hhfabctl 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
65+
```
66+
67+
Options:
68+
- `--name` – VPC name.
69+
- `--subnet` – Subnet in CIDR format (**required**).
70+
- `--vlan` – VLAN ID (**required**).
71+
- `--dhcp` – Enable DHCP.
72+
- `--dhcp-range-start` – Start of DHCP range.
73+
- `--dhcp-range-end` – End of DHCP range.
74+
- `--print` – Print object as YAML.
1675

17-
USAGE:
18-
kubectl fabric [global options] command [command options]
76+
#### `attach`
77+
Attach a VPC to a connection:
78+
79+
```bash
80+
hhfabctl vpc attach --vpc-subnet vpc-1/default --connection server-01
81+
```
1982

20-
VERSION:
21-
v0.53.1
83+
Options:
84+
- `--vpc-subnet` – VPC subnet name (**required**).
85+
- `--connection` – Connection name (**required**).
2286

23-
COMMANDS:
24-
vpc VPC commands
25-
switch, sw Switch commands
26-
connection, conn Connection commands
27-
switchgroup, sg SwitchGroup commands
28-
external, ext External commands
29-
inspect, i Inspect Fabric API Objects and Primitives
30-
help, h Shows a list of commands or help for one command
87+
#### `peer`
88+
Create a peering between VPCs:
3189

32-
GLOBAL OPTIONS:
33-
--verbose, -v verbose output (includes debug) (default: true)
34-
--help, -h show help
35-
--version, -V print the version
90+
```bash
91+
hhfabctl vpc peer --vpc vpc-1 --vpc vpc-2
3692
```
3793

38-
## VPC
94+
Options:
95+
- `--vpc` – VPC names (**required**).
3996

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):
97+
#### `wipe`
98+
Delete all VPCs:
4299

43100
```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
101+
hhfabctl vpc wipe --yes
45102
```
46103

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):
104+
Options:
105+
- `--yes` – Confirm deletion.
106+
107+
---
108+
109+
### `switch`
110+
Switch management commands.
111+
112+
#### `ip`
113+
Get switch IP:
49114

50115
```bash
51-
core@control-1 ~ $ kubectl fabric vpc attach --vpc-subnet vpc-1/default --connection server-01--mclag--leaf-01--leaf-02
116+
hhfabctl switch ip --name switch-01
52117
```
53118

54-
To peer VPC with another VPC (e.g. `vpc-2`) use the following command:
119+
Options:
120+
- `--name` – Switch name.
121+
- `--username` – SSH username (default: "admin").
122+
123+
#### `reboot`
124+
Reboot the switch:
55125

56126
```bash
57-
core@control-1 ~ $ kubectl fabric vpc peer --vpc vpc-1 --vpc vpc-2
127+
hhfabctl switch reboot --name switch-01 --yes
58128
```
129+
130+
Options:
131+
- `--name` – Switch name.
132+
- `--yes` – Confirm reboot.
133+
134+
---
135+
136+
### `connection`
137+
Get connection details:
138+
139+
```bash
140+
hhfabctl connection get management
141+
```
142+
143+
Options:
144+
- `--type` – Connection type (`management`, `fabric`, `vpc-loopback`).
145+
146+
---
147+
148+
### `switchgroup`
149+
Create a switch group:
150+
151+
```bash
152+
hhfabctl switchgroup create --name sg-01
153+
```
154+
155+
Options:
156+
- `--name` – Switch group name.
157+
158+
---
159+
160+
### `external`
161+
Create an external connection:
162+
163+
```bash
164+
hhfabctl external create --name ext-01 --ipv4-namespace default
165+
```
166+
167+
Options:
168+
- `--name` – External name.
169+
- `--ipv4-namespace` – IPv4 namespace.
170+
171+
---
172+
173+
### `wiring`
174+
Export wiring diagram:
175+
176+
```bash
177+
hhfabctl wiring export --vpcs --externals
178+
```
179+
180+
Options:
181+
- `--vpcs` – Include VPCs (default: true).
182+
- `--externals` – Include externals (default: true).
183+
184+
---
185+
186+
### `inspect`
187+
Inspect Fabric objects:
188+
189+
```bash
190+
hhfabctl inspect fabric --output text
191+
```
192+
193+
Options:
194+
- `--output` – Output format (`text`, `yaml`, `json`).
195+
196+
---
197+
198+
## Global Options
199+
- `--verbose`, `-v` – Enable verbose output (includes debug).
200+
- `--help`, `-h` – Show help.
201+
- `--version`, `-V` – Display version information.
202+
- `--yes`, `-y` – Confirm potentially dangerous actions.
203+

‎docs/reference/hhfab-cli.md

+147
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
2+
# hhfab CLI Reference Guide
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)