diff --git a/docs/reference/.pages b/docs/reference/.pages index 832fd9ce..b84a6311 100644 --- a/docs/reference/.pages +++ b/docs/reference/.pages @@ -1,3 +1,5 @@ nav: - Fabric API: api.md + - Fabric CLI: cli.md + - Fabricator CLI: hhfab-cli.md - ... diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 743f10d1..931e506a 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -1,7 +1,5 @@ -# Fabric CLI -!!! warning "" - Under construction. +# Fabric CLI Reference Currently Fabric CLI is represented by a kubectl plugin `kubectl-fabric` automatically installed on the Control Node. It is a wrapper around `kubectl` and Kubernetes client which allows to manage Fabric resources in a more convenient way. @@ -9,6 +7,8 @@ Fabric CLI only provides a subset of the functionality available via Fabric API creation and some manipulation with the already existing objects while main get/list/update operations are expected to be done using `kubectl`. +## Usage + ```bash core@control-1 ~ $ kubectl fabric NAME: @@ -35,24 +35,206 @@ GLOBAL OPTIONS: --version, -V print the version ``` -## VPC +## Commands and Options + +| Command | Subcommand | Options | Description | +|---------|------------|---------|-------------| +| **vpc** | create | `--name`, `--subnet` (required), `--vlan` (required), `--dhcp`, `--dhcp-range-start`, `--dhcp-range-end`, `--print` | Create a new VPC. | +| | attach | `--name`, `--vpc-subnet` (required), `--connection` (required), `--print` | Attach VPC to a server connection. | +| | peer | `--name`, `--vpc` (required), `--remote`, `--print` | Peer two VPCs. | +| | wipe | `--yes` | Delete all VPCs and peerings. | +| **switch** | ip | `--name`, `--username`, `--verbose` | Get switch management IP address. | +| | ssh | `--name`, `--username`, `--verbose` | SSH into the switch. | +| | serial | `--name`, `--username`, `--verbose` | Run serial console for the switch. | +| | reboot | `--name`, `--yes`, `--verbose` | Reboot the switch. | +| | power-reset | `--name`, `--yes`, `--verbose` | Power reset the switch. | +| | reinstall | `--name`, `--yes`, `--verbose` | Reinstall the switch. | +| **connection** | get | `--type` | Get details of existing connections. | +| **switchgroup** | create | `--name`, `--print` | Create a new switch group. | +| **external** | create | `--name`, `--ipv4-namespace`, `--inbound-community`, `--outbound-community`, `--print` | Create a new external connection. | +| | peer | `--vpc`, `--external`, `--vpc-subnet`, `--external-prefix`, `--print` | Peer external and VPC. | +| **wiring** | export | `--vpcs`, `--externals`, `--switch-profiles` | Export wiring diagram. | +| **inspect** | fabric | `--verbose`, `--output` (default: "text") | Inspect overall Fabric state. | +| | switch | `--name`, `--output` (default: "text") | Inspect switch status and ports. | +| | port | `--name`, `--output` (default: "text") | Inspect switch port status. | +| | server | `--name`, `--output` (default: "text") | Inspect server status. | +| | connection | `--name`, `--output` (default: "text") | Inspect connection details. | +| | vpc | `--name`, `--subnet`, `--output` (default: "text") | Inspect VPC details. | +| | bgp | `--switch-name`, `--strict` | Inspect BGP neighbors. | +| | lldp | `--switch-name`, `--strict`, `--fabric`, `--external`, `--server` | Inspect LLDP neighbors. | +| | ip | `--address` | Inspect IP details. | +| | mac | `--address` | Inspect MAC details. | +| | access | `--source`, `--destination` | Inspect connectivity. | + +--- + +## Command Details + +### `vpc` +VPC management commands. + +#### `create` +Create a VPC: + +```bash +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 +``` + + +**Options:** + +- `--name` – VPC name. +- `--subnet` – Subnet in CIDR format (**required**). +- `--vlan` – VLAN ID (**required**). +- `--dhcp` – Enable DHCP. +- `--dhcp-range-start` – Start of DHCP range. +- `--dhcp-range-end` – End of DHCP range. +- `--print` – Print object as YAML. + +#### `attach` +Attach a VPC to a connection: + +```bash +kubectl fabric vpc attach --vpc-subnet vpc-1/default --connection server-01 +``` + + +**Options:** + +- `--vpc-subnet` – VPC subnet name (**required**). +- `--connection` – Connection name (**required**). + +#### `peer` +Create a peering between VPCs: + +```bash +kubectl fabric vpc peer --vpc vpc-1 --vpc vpc-2 +``` + + +**Options:** -Create VPC named `vpc-1` with subnet `10.0.1.0/24` and VLAN `1001` with DHCP enabled and DHCP range starting from -`10.0.1.10` (optional): +- `--vpc` – VPC names (**required**). + +#### `wipe` +Delete all VPCs: ```bash -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 +kubectl fabric vpc wipe --yes ``` -Attach previously created VPC to the server `server-01` (which is connected to the Fabric using the -`server-01--mclag--leaf-01--leaf-02` Connection): + +**Options:** +- `--yes` – Confirm deletion. + +--- + +### `switch` +Switch management commands. + +#### `ip` +Get switch IP: ```bash -core@control-1 ~ $ kubectl fabric vpc attach --vpc-subnet vpc-1/default --connection server-01--mclag--leaf-01--leaf-02 +kubectl fabric switch ip --name switch-01 ``` -To peer VPC with another VPC (e.g. `vpc-2`) use the following command: + +**Options:** + +- `--name` – Switch name. +- `--username` – SSH username (default: "admin"). + +#### `reboot` +Reboot the switch: ```bash -core@control-1 ~ $ kubectl fabric vpc peer --vpc vpc-1 --vpc vpc-2 +kubectl fabric switch reboot --name switch-01 --yes ``` + + +**Options:** + +- `--name` – Switch name. +- `--yes` – Confirm reboot. + +--- + +### `connection` +Get connection details: + +```bash +kubectl fabric connection get management +``` + + +**Options:** + +- `--type` – Connection type (`management`, `fabric`, `vpc-loopback`). + +--- + +### `switchgroup` +Create a switch group: + +```bash +kubectl fabric switchgroup create --name sg-01 +``` + + +**Options:** + +- `--name` – Switch group name. + +--- + +### `external` +Create an external connection: + +```bash +kubectl fabric external create --name ext-01 --ipv4-namespace default +``` + + +**Options:** + +- `--name` – External name. +- `--ipv4-namespace` – IPv4 namespace. + +--- + +### `wiring` +Export wiring diagram: + +```bash +kubectl fabric wiring export --vpcs --externals +``` + + +**Options:** + +- `--vpcs` – Include VPCs (default: true). +- `--externals` – Include externals (default: true). + +--- + +### `inspect` +Inspect Fabric objects: + +```bash +kubectl fabric inspect fabric --output text +``` + + +**Options:** + +- `--output` – Output format (`text`, `yaml`, `json`). + +--- + +## Global Options +- `--verbose`, `-v` – Enable verbose output (includes debug). +- `--help`, `-h` – Show help. +- `--version`, `-V` – Display version information. +- `--yes`, `-y` – Confirm potentially dangerous actions. + diff --git a/docs/reference/hhfab-cli.md b/docs/reference/hhfab-cli.md new file mode 100644 index 00000000..97fa781e --- /dev/null +++ b/docs/reference/hhfab-cli.md @@ -0,0 +1,152 @@ + +# Fabricator CLI Reference + +The `hhfab` CLI is the Hedgehog Fabricator command-line tool for building, installing, and managing Hedgehog Fabric environments. + +## Usage + +```bash +hhfab [global options] command [command options] +``` + +## Version + +Check the version with: + +```bash +hhfab --version +``` + +## Commands and Options + +| Command | Subcommand | Options | Description | +|---------|------------|---------|-------------| +| **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. | +| **validate** | — | `--hydrate-mode` *(default: "if-not-present")* | Validate configuration and wiring files. | +| **diagram** | — | `--format` *(default: "drawio")*, `--style` *(default: "hedgehog")* | Generate network topology diagrams. | +| **versions** | — | — | Print versions of all components. | +| **build** | — | `--mode` *(default: "iso")* | Build installers. | +| **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. | +| | 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. | +| | ssh | `--name` | SSH to a VLAB VM or hardware. | +| | serial | `--name` | Get serial console of a VLAB VM or hardware. | +| | seriallog | `--name` | Get serial console log of a VLAB VM or hardware. | +| | show-tech | — | Collect diagnostic information from all VLAB devices. | +| | 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. | +| | setup-peerings | `--wait-switches-ready` *(default: true)* | Setup VPC and external peerings. | +| | 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. | +| | wait-switches | — | Wait for switches to be ready. | +| | inspect-switches | `--wait-applied-for` *(default: 120)*, `--strict` *(default: true)* | Wait for readiness and inspect switches. | +| **switch** | reinstall | `--name`, `--mode` *(default: "hard-reset")*, `--wait-ready`, `--switch-username`, `--switch-password`, `--pdu-username`, `--pdu-password` | Reboot/reset and reinstall NOS on switches. | +| | power | `--name`, `--action` *(default: "cycle")*, `--pdu-username`, `--pdu-password` | Manage switch power state using the PDU. | +| **_helpers** | setup-taps | `--count` *(max: 100)* | Setup tap devices and a bridge for VLAB. | +| | vfio-pci-bind | — | Bind devices to vfio-pci driver for passthrough. | +| | kill-stale-vms | — | Kill stale VLAB VMs. | + +## Command Details + +### `init` +Initializes working directory and configuration files. + +**Usage:** +```bash +hhfab init [options] +``` + +**Options:** + +- `--registry-repo` – Download artifacts from specific registry repository. +- `--registry-prefix` – Prepend artifact names with specific prefix. +- `--config` – Use existing config file. +- `--force` – Overwrite existing files. +- `--wiring` – Include wiring diagram file. +- `--fabric-mode` *(default: "spine-leaf")* – Set fabric mode. +- `--tls-san` – IPs and DNS names used to access the API. +- `--default-authorized-keys` – Default authorized keys. +- `--default-password-hash` – Default password hash. +- `--dev` – Use default dev credentials (unsafe). +- `--include-onie` – Include ONIE updaters for supported switches. +- `--import-host-upstream` – Import host repo/prefix as an upstream registry mode. +- `--control-node-mgmt-link` – Control node management link. +- `--gateway` – Add and enable gateway node. + +--- + +### `validate` +Validates the configuration and wiring files. + +**Usage:** +```bash +hhfab validate [options] +``` + +**Options:** + +- `--hydrate-mode` *(default: "if-not-present")* – Set hydrate mode. + +--- + +### `diagram` +Generate network topology diagrams. + +**Usage:** +```bash +hhfab diagram [options] +``` + +**Options:** + +- `--format` *(default: "drawio")* – Diagram format. +- `--style` *(default: "hedgehog")* – Diagram style. + +--- + +### `versions` +Print versions of all components. + +**Usage:** +```bash +hhfab versions +``` + +--- + +### `build` +Build Hedgehog installer. + +**Usage:** +```bash +hhfab build [options] +``` + +**Options:** + +- `--mode` *(default: "iso")* – Build mode (iso, qcow2, raw). + +--- + +### `switch reinstall` +Reinstall the OS on switches. + +**Usage:** +```bash +hhfab switch reinstall [options] +``` + +**Options:** + +- `--name` – Switch name. +- `--mode` *(default: "hard-reset")* – Restart mode. +- `--wait-ready` – Wait until switch is ready. +- `--switch-username` – Switch username for reboot mode. +- `--switch-password` – Switch password for reboot mode. + +--- + +## Global Options +- `--workdir` – Specify working directory. +- `--cache-dir` – Specify cache directory. +- `--verbose`, `-v` – Verbose output (includes debug). +- `--brief`, `-b` – Brief output (only warnings and errors). +- `--yes`, `-y` – Assume "yes" for potentially dangerous operations. + diff --git a/docs/reference/profiles.md b/docs/reference/profiles.md index 7724f6bd..cca52c48 100644 --- a/docs/reference/profiles.md +++ b/docs/reference/profiles.md @@ -107,6 +107,59 @@ Label column is a port label on a physical switch. | E1/33 | 33 | Direct | | 10G | 1G, 10G | +## Celestica DS4101 + +Profile Name (to use in switch.spec.profile): **celestica-ds4101** + +**Supported features:** + +- Subinterfaces: false +- VXLAN: false +- ACLs: true + +**Available Ports:** + +Label column is a port label on a physical switch. + +| Port | Label | Type | Group | Default | Supported | +|------|-------|------|-------|---------|-----------| +| M1 | | Management | | | | +| E1/1 | 1 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/2 | 2 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/3 | 3 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/4 | 4 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/5 | 5 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/6 | 6 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/7 | 7 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/8 | 8 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/9 | 9 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/10 | 10 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/11 | 11 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/12 | 12 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/13 | 13 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/14 | 14 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/15 | 15 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/16 | 16 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/17 | 17 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/18 | 18 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/19 | 19 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/20 | 20 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/21 | 21 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/22 | 22 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/23 | 23 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/24 | 24 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/25 | 25 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/26 | 26 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/27 | 27 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/28 | 28 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/29 | 29 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/30 | 30 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/31 | 31 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/32 | 32 | Breakout | | 2x400G | 1x100G, 1x200G, 1x400G, 2x100G, 2x200G, 2x400G, 2x40G, 4x100G, 4x200G, 4x50G, 8x100G, 8x10G, 8x25G, 8x50G | +| E1/33 | M1 | Direct | | 10G | 1G, 10G | +| E1/34 | M2 | Direct | | 10G | 1G, 10G | + + ## Dell S5232F-ON Profile Name (to use in switch.spec.profile): **dell-s5232f-on**