IP Reservations

Reserve IP addresses for future use

Rackd provides IP reservation functionality for planning and managing IP address allocations before devices are provisioned.

Overview

IP reservations allow you to:

• Reserve IPs for future use
• Plan IP allocations during infrastructure planning
• Prevent accidental IP conflicts
• Track reservation purposes and owners
• Auto-expire unused reservations

Reservation Model

Reservation Status

API Endpoints

List Reservations

GET /api/pools/{pool_id}/reservations

Query parameters:

• status - Filter by status (active/expired/claimed/released)
• reserved_by - Filter by user

Response:

[
  {
    "id": "res-abc123",
    "pool_id": "pool-1",
    "ip_address": "192.168.1.50",
    "purpose": "New database server",
    "reserved_by": "admin",
    "status": "active",
    "expires_at": "2024-03-30T00:00:00Z",
    "created_at": "2024-02-27T10:00:00Z"
  }
]

Get Reservation

GET /api/pools/{pool_id}/reservations/{ip}

Create Reservation

POST /api/pools/{pool_id}/reservations

Request body:

{
  "ip_address": "192.168.1.50",
  "purpose": "New database server - ticket #12345",
  "reserved_by": "john.doe",
  "expires_at": "2024-03-30T00:00:00Z"
}

If ip_address is omitted, the next available IP is automatically assigned.

Update Reservation

PUT /api/pools/{pool_id}/reservations/{ip}

Release Reservation

DELETE /api/pools/{pool_id}/reservations/{ip}

Marks the reservation as released and frees the IP.

Claim Reservation

When creating a device with a reserved IP, the reservation is automatically claimed:

POST /api/devices

{
  "hostname": "db-server-01",
  "ip_address": "192.168.1.50"
}

CLI Commands

List Reservations

# List reservations for a pool
rackd reservation list --pool pool-1

# Filter by status
rackd reservation list --pool pool-1 --status active

# Output as JSON
rackd reservation list --pool pool-1 --output json

Get Reservation

rackd reservation get --pool pool-1 --ip 192.168.1.50

Create Reservation

# Reserve specific IP
rackd reservation create \
  --pool pool-1 \
  --ip 192.168.1.50 \
  --purpose "Database server - ticket #12345" \
  --reserved-by "john.doe"

# Reserve next available IP
rackd reservation create \
  --pool pool-1 \
  --purpose "Load balancer" \
  --expires "2024-03-30"

Update Reservation

rackd reservation update \
  --pool pool-1 \
  --ip 192.168.1.50 \
  --purpose "Updated purpose"

Release Reservation

rackd reservation release --pool pool-1 --ip 192.168.1.50

Delete Reservation

rackd reservation delete --pool pool-1 --ip 192.168.1.50

Web UI

Reservations are managed within pool details at /pools/{id}.

Pool Heatmap

The pool heatmap displays reservations with distinct styling:

• Blue: Reserved IPs
• Green: Assigned IPs
• Orange: Conflicted IPs
• Gray: Available IPs

Reservation List

View all reservations for a pool with:

• IP address
• Purpose
• Reserved by
• Status badge
• Expiration date
• Actions (edit/release)

Automatic Expiration

Reservations can have an optional expiration date. Configure expiration handling:

# config.yaml
reservation:
  default_expiration_days: 30
  cleanup_interval: 1h

Expired reservations:

• Status changes to expired
• IP becomes available for new reservations
• Original reservation record preserved for audit

RBAC Permissions

Default Role Assignments

• admin: All reservation permissions
• operator: All reservation permissions
• viewer: reservation:list, reservation:read

Use Cases

Infrastructure Planning

Reserve IPs during capacity planning:

rackd reservation create \
  --pool production \
  --ip 10.0.1.100 \
  --purpose "Q3 expansion - web tier" \
  --reserved-by "infrastructure-team"

Change Management

Reserve IPs for upcoming changes:

rackd reservation create \
  --pool dmz \
  --ip 192.168.100.50 \
  --purpose "New firewall - CHG-12345" \
  --expires "2024-03-15"

Project Allocation

Reserve IP ranges for projects:

# Reserve multiple IPs for a project
for i in $(seq 50 60); do
  rackd reservation create \
    --pool development \
    --ip "10.10.0.$i" \
    --purpose "Project Phoenix - dev environment"
done

Temporary Assignments

Reserve IPs for temporary workloads:

rackd reservation create \
  --pool testing \
  --purpose "Load testing - week of 3/15" \
  --expires "2024-03-22" \
  --reserved-by "qa-team"

Integration with Other Features

Conflict Detection

Reserved IPs that are assigned to devices trigger reserved_ip_assigned conflicts.

Device Creation

When creating a device:

• If IP is reserved, reservation is automatically claimed
• If IP is already assigned to another device, conflict is created

Webhooks

Subscribe to reservation events:

• reservation.created
• reservation.claimed
• reservation.released
• reservation.expired

Best Practices

1. Always Add Purpose: Document why an IP is reserved
2. Set Expiration: Use expiration dates for temporary reservations
3. Include Ticket Numbers: Reference change tickets in purpose field
4. Regular Cleanup: Review and release unused reservations
5. Naming Convention: Use consistent purpose formatting
6. Owner Tracking: Set reserved_by for accountability