> For the complete documentation index, see [llms.txt](https://docs.acecloud.ai/knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.acecloud.ai/knowledge-base/cli/networking/routers.md).

# Routers

Routers connect VPC subnets to each other and to external networks. Attach an external gateway to give your instances internet access through a floating IP, or connect multiple subnets within the same VPC.

**Command:** `ace vpc router`

## Create a Router

```bash
ace vpc router create --name <name> [flags]
```

### Flags

| Flag                | Required | Description                                       |
| ------------------- | -------- | ------------------------------------------------- |
| `--name`            | Yes      | Router name                                       |
| `--gateway-network` | No       | External gateway network ID to attach at creation |

### Examples

```bash
# Create a router
ace vpc router create --name prod-router

# Create a router with an external gateway
ace vpc router create --name prod-router --gateway-network <external-network-id>
```

### Sample Output

```
Router created.
  Router ID:       b2c3d4e5-f6a7-8901-bcde-f12345678901
  Name:            prod-router
  Status:          ACTIVE
```

***

## List Routers

```bash
ace vpc router list
```

**Alias:** `ace vpc router ls`

### Sample Output

```
ID                                     NAME                      STATUS     ADMIN    GATEWAY NETWORK
b2c3d4e5-f6a7-8901-bcde-f12345678901  prod-router               ACTIVE     UP       c3d4e5f6-a7b8-9012...
a1b2c3d4-e5f6-7890-abcd-ef1234567890  dev-router                ACTIVE     UP       -
```

***

## Get Router Details

```bash
ace vpc router get <router-id>
```

**Alias:** `ace vpc router show`

### Sample Output

```
  ID:                       b2c3d4e5-f6a7-8901-bcde-f12345678901
  Name:                     prod-router
  Status:                   ACTIVE
  Admin State:              UP
  Gateway Network:          c3d4e5f6-a7b8-9012-cdef-234567890abc
  Created:                  2025-01-15T10:30:00Z
  Updated:                  2025-01-15T10:35:00Z
```

***

## Delete Routers

```bash
ace vpc router delete <router-id> [router-id...]
```

**Alias:** `ace vpc router rm`

Remove all interfaces and the external gateway from a router before deleting it.

### Example

```bash
ace vpc router delete b2c3d4e5-f6a7-8901-bcde-f12345678901
```

```
Deleted 1 router(s).
```

***

## Gateway Management

### Set Gateway

Attach an external network as the router's gateway. This enables outbound internet access for instances in subnets connected to this router.

```bash
ace vpc router set-gateway --router <router-id> --network <external-network-id>
```

#### Flags

| Flag        | Required | Description         |
| ----------- | -------- | ------------------- |
| `--router`  | Yes      | Router ID           |
| `--network` | Yes      | External network ID |

#### Example

```bash
ace vpc router set-gateway \
  --router b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  --network c3d4e5f6-a7b8-9012-cdef-234567890abc
```

```
Gateway attached to router.
```

### Remove Gateway

Detach the external gateway from a router.

```bash
ace vpc router remove-gateway --router <router-id>
```

#### Example

```bash
ace vpc router remove-gateway --router b2c3d4e5-f6a7-8901-bcde-f12345678901
```

```
Gateway removed from router.
```

***

## Interface Management

Interfaces connect subnets to the router, enabling traffic routing between subnets and to external networks.

### Add Interface

Attach a subnet to a router.

```bash
ace vpc router add-interface --router <router-id> --subnet <subnet-id>
```

#### Flags

| Flag       | Required | Description         |
| ---------- | -------- | ------------------- |
| `--router` | Yes      | Router ID           |
| `--subnet` | Yes      | Subnet ID to attach |

#### Example

```bash
ace vpc router add-interface \
  --router b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  --subnet f6e5d4c3-b2a1-0987-fedc-ba0987654321
```

```
Interface added to router.
  Port ID:         d4e5f6a7-b8c9-0123-def0-456789abcdef
  Subnet ID:       f6e5d4c3-b2a1-0987-fedc-ba0987654321
```

### Remove Interface

Detach an interface from a router. You can specify either a `--subnet` (the CLI will look up the matching port) or pass interface IDs as positional arguments.

```bash
# By subnet ID
ace vpc router remove-interface --router <router-id> --subnet <subnet-id>

# By interface (port) ID
ace vpc router remove-interface --router <router-id> <interface-id>
```

#### Flags

| Flag       | Required | Description                                          |
| ---------- | -------- | ---------------------------------------------------- |
| `--router` | Yes      | Router ID                                            |
| `--subnet` | No       | Subnet ID (finds and removes the matching interface) |

#### Examples

```bash
# Remove by subnet
ace vpc router remove-interface \
  --router b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  --subnet f6e5d4c3-b2a1-0987-fedc-ba0987654321

# Remove by interface ID
ace vpc router remove-interface \
  --router b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  d4e5f6a7-b8c9-0123-def0-456789abcdef
```

```
Removed 1 interface(s) from router.
```

### List Interfaces

List all interfaces attached to a router.

```bash
ace vpc router interfaces --router <router-id>
```

#### Sample Output

```
PORT ID                                STATUS     IP ADDRESS         SUBNET ID
d4e5f6a7-b8c9-0123-def0-456789abcdef  ACTIVE     10.0.0.1           f6e5d4c3-b2a1-0987-fedc-ba0987654321
e5f6a7b8-c9d0-1234-ef01-56789abcdef0  ACTIVE     10.0.1.1           a7b8c9d0-e1f2-3456-7890-abcdef012345
```

***

## Command Summary

| Command                           | Description                       |
| --------------------------------- | --------------------------------- |
| `ace vpc router create`           | Create a router                   |
| `ace vpc router list`             | List all routers                  |
| `ace vpc router get <id>`         | Get router details                |
| `ace vpc router delete <id>`      | Delete router(s)                  |
| `ace vpc router set-gateway`      | Attach an external gateway        |
| `ace vpc router remove-gateway`   | Detach the external gateway       |
| `ace vpc router add-interface`    | Attach a subnet to a router       |
| `ace vpc router remove-interface` | Detach interface(s) from a router |
| `ace vpc router interfaces`       | List interfaces on a router       |