### Example Usage of go-ipam for IP Acquisition and Release

Source: https://github.com/metal-stack/go-ipam/blob/master/migrating-to-ipv6.md

Demonstrates a typical workflow using the go-ipam library to manage IP addresses. This example shows how to initialize the ipamer, create a new prefix, acquire an IP from that prefix, print its details, release the IP, and finally delete the prefix. It highlights the simplicity and efficiency of the go-ipam operations.

```go
    ipamer := New()
    prefix, err := ipamer.NewPrefix("192.168.0.0/24")
    if err != nil {
        panic(err)
    }
    ip1, err := ipamer.AcquireIP(prefix.Cidr)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Super Prefix  : %s\n", prefix)
    fmt.Printf("Super Prefix IP1 : %s\n", ip1.IP.String())
    fmt.Printf("Super Prefix IP1 Parent : %s\n", ip1.ParentPrefix)
    // Output:
    // Super Prefix  : 192.168.0.0/24
    // Super Prefix IP1 : 192.168.0.1
    // Super Prefix IP1 Parent : 192.168.0.0/24
    _, err = ipamer.ReleaseIP(ip1)
    if err != nil {
        panic(err)
    }
    _, err = ipamer.DeletePrefix(prefix.Cidr)
    if err != nil {
        panic(err)
    }
```

--------------------------------

### List All Prefix CIDRs in Go

Source: https://context7.com/metal-stack/go-ipam/llms.txt

This Go example shows how to retrieve a list of all prefix CIDRs currently managed by an IPAM instance. It first creates several prefixes (IPv4 and IPv6) and then uses the `ReadAllPrefixCidrs` function to get their CIDRs, printing each one to the console.

```go
package main

import (
    "context"
    "fmt"

    goipam "github.com/metal-stack/go-ipam"
)

func main() {
    ctx := context.Background()
    ipam := goipam.New(ctx)

    // Create multiple prefixes
    _, _ = ipam.NewPrefix(ctx, "10.0.0.0/24")
    _, _ = ipam.NewPrefix(ctx, "192.168.0.0/16")
    _, _ = ipam.NewPrefix(ctx, "2001:db8::/32")

    // List all prefixes
    cidrs, err := ipam.ReadAllPrefixCidrs(ctx)
    if err != nil {
        panic(err)
    }

    fmt.Println("All prefixes:")
    for _, cidr := range cidrs {
        fmt.Printf("  - %s\n", cidr)
    }
    // Output:
    // All prefixes:
    //   - 10.0.0.0/24
    //   - 192.168.0.0/16
    //   - 2001:db8::/32
}

```

--------------------------------

### Start IPAM Server with Docker

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Instructions on how to start the go-ipam server using Docker, with options for PostgreSQL backend. This is a prerequisite for using the CLI commands.

```bash
# Start the IPAM server with PostgreSQL backend
docker run -it --rm ghcr.io/metal-stack/go-ipam postgres

# Or with Docker Compose
docker compose up -d
```

--------------------------------

### Go gRPC Client: Create Prefix

Source: https://github.com/metal-stack/go-ipam/blob/master/README.md

Example of how to use the go-ipam gRPC client to create a new IP prefix. This requires the go-ipam gRPC service to be running and accessible.

```go
package main

import (
    "http"

    "github.com/bufbuild/connect-go"
    v1 "github.com/metal-stack/go-ipam/api/v1"
    "github.com/metal-stack/go-ipam/api/v1/apiv1connect"
)
func main() {

    c := apiv1connect.NewIpamServiceClient(
            http.DefaultClient,
            "http://localhost:9090",
            connect.WithGRPC(),
    )

    bgCtx := context.Background()

    // Optional with Namespace
    ctx := goipam.NewContextWithNamespace(bgCtx, "tenant-a")

    result, err := c.CreatePrefix(ctx, connect.NewRequest(&v1.CreatePrefixRequest{Cidr: "192.168.0.0/16",}))
    if err != nil {
        panic(err)
    }
    fmt.Println("Prefix:%q created", result.Msg.GetPrefix().GetCidr())
}
```

--------------------------------

### Get Prefix Usage Statistics in Go

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Demonstrates how to retrieve usage statistics for a given IPAM prefix, including available and acquired IPs, as well as child prefixes. It initializes the IPAM library, creates a prefix, acquires some IPs, and then fetches and prints the usage details. It also shows how to handle usage for parent prefixes with child allocations.

```go
package main

import (
    "context"
    "fmt"

    goipam "github.com/metal-stack/go-ipam"
)

func main() {
    ctx := context.Background()
    ipam := goipam.New(ctx)

    prefix, _ := ipam.NewPrefix(ctx, "10.0.0.0/24")

    // Acquire some IPs
    _, _ = ipam.AcquireIP(ctx, prefix.Cidr)
    _, _ = ipam.AcquireIP(ctx, prefix.Cidr)
    _, _ = ipam.AcquireIP(ctx, prefix.Cidr)

    // Get current prefix state
    prefix, _ = ipam.PrefixFrom(ctx, prefix.Cidr)
    usage := prefix.Usage()

    fmt.Printf("Available IPs: %d\n", usage.AvailableIPs)
    fmt.Printf("Acquired IPs: %d\n", usage.AcquiredIPs)
    // Output:
    // Available IPs: 256
    // Acquired IPs: 5 (network + broadcast + 3 acquired)

    // For parent prefixes with child allocations
    parent, _ := ipam.NewPrefix(ctx, "10.1.0.0/16")
    _, _ = ipam.AcquireChildPrefix(ctx, parent.Cidr, 24)
    _, _ = ipam.AcquireChildPrefix(ctx, parent.Cidr, 24)

    parent, _ = ipam.PrefixFrom(ctx, parent.Cidr)
    parentUsage := parent.Usage()

    fmt.Printf("Acquired Prefixes: %d\n", parentUsage.AcquiredPrefixes)
    fmt.Printf("Available Smallest Prefixes: %d\n", parentUsage.AvailableSmallestPrefixes)
    fmt.Printf("Available Prefixes: %v\n", parentUsage.AvailablePrefixes)
    // Output:
    // Acquired Prefixes: 2
    // Available Smallest Prefixes: 16382
    // Available Prefixes: [10.1.2.0/23 10.1.4.0/22 10.1.8.0/21 ...]
}

```

--------------------------------

### Acquire IPv6 Child Prefixes and IPs in Go

Source: https://github.com/metal-stack/go-ipam/blob/master/migrating-to-ipv6.md

Demonstrates how to use go-ipam with the inet.af/netaddr library to acquire IPv6 child prefixes and IP addresses from a given super prefix. This example showcases the library's ability to handle complex IPv6 network manipulations efficiently.

```go
package main

import (
	"fmt"
	"github.com/metal-stack/go-ipam"
)

func main() {
	ipamer := New()
	prefix, err := ipamer.NewPrefix("2001:aabb::/48")
	if err != nil {
		panic(err)
	}
	cp1, err := ipamer.AcquireChildPrefix(prefix.Cidr, 64)
	if err != nil {
		panic(err)
	}
	cp2, err := ipamer.AcquireChildPrefix(prefix.Cidr, 72)
	if err != nil {
		panic(err)
	}
	ip21, err := ipamer.AcquireIP(cp2.Cidr)
	if err != nil {
		panic(err)
	}
	prefix = ipamer.PrefixFrom(prefix.Cidr)
	fmt.Printf("Super Prefix  : %s\n", prefix)
	fmt.Printf("Child Prefix 1: %s\n", cp1)
	fmt.Printf("Child Prefix 2: %s\n", cp2)
	fmt.Printf("Child Prefix 2 IP1: %s\n", ip21.IP)
}

```

--------------------------------

### Get Prefix Usage via gRPC (Go)

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Demonstrates how to retrieve prefix usage statistics using the go-ipam gRPC API. It fetches and prints the count of available IPs, acquired IPs, acquired prefixes, and available smallest prefixes for a given CIDR. Requires the go-ipam API client library.

```go
package main

import (
    "context"
    "fmt"
    "net/http"

    "connectrpc.com/connect"
    v1 "github.com/metal-stack/go-ipam/api/v1"
    "github.com/metal-stack/go-ipam/api/v1/apiv1connect"
)

func main() {
    client := apiv1connect.NewIpamServiceClient(
        http.DefaultClient,
        "http://localhost:9090",
        connect.WithGRPC(),
    )

    ctx := context.Background()

    result, err := client.PrefixUsage(ctx, connect.NewRequest(&v1.PrefixUsageRequest{
        Cidr: "10.0.0.0/24",
    }))
    if err != nil {
        panic(err)
    }

    fmt.Printf("Available IPs: %d\n", result.Msg.GetAvailableIps())
    fmt.Printf("Acquired IPs: %d\n", result.Msg.GetAcquiredIps())
    fmt.Printf("Acquired Prefixes: %d\n", result.Msg.GetAcquiredPrefixes())
    fmt.Printf("Available Smallest Prefixes: %d\n", result.Msg.GetAvailableSmallestPrefixes())
}
```

--------------------------------

### REST API: Get Prefix Usage

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Uses curl to send a POST request to the PrefixUsage endpoint of the go-ipam REST API. This operation retrieves information about the utilization of a specific IP prefix. It requires a JSON payload containing the CIDR of the prefix.

```bash
curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{"cidr": "10.0.0.0/24"}' \
  http://localhost:9090/api.v1.IpamService/PrefixUsage
```

--------------------------------

### List All Namespaces in Go IPAM

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Demonstrates how to list all available namespaces within an IPAM instance using the go-ipam library. It requires the context and the go-ipam package. The function returns a slice of strings representing namespace names.

```go
package main

import (
    "context"
    "fmt"

    goipam "github.com/metal-stack/go-ipam"
)

func main() {
    ctx := context.Background()
    ipam := goipam.New(ctx)

    _ = ipam.CreateNamespace(ctx, "production")
    _ = ipam.CreateNamespace(ctx, "staging")
    _ = ipam.CreateNamespace(ctx, "development")

    namespaces, err := ipam.ListNamespaces(ctx)
    if err != nil {
        panic(err)
    }

    fmt.Println("Namespaces:")
    for _, ns := range namespaces {
        fmt.Printf("  - %s\n", ns)
    }
    // Output:
    // Namespaces:
    //   - root
    //   - production
    //   - staging
    //   - development
}
```

--------------------------------

### Create IPAM Instance with Custom Storage (Go)

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Initializes a new go-ipam Ipamer instance with a custom storage backend. It supports various backends like PostgreSQL and Redis by implementing the Storage interface. The function takes the storage implementation as an argument.

```Go
package main

import (
    "context"
    "fmt"

    goipam "github.com/metal-stack/go-ipam"
)

func main() {
    ctx := context.Background()

    // Create with PostgreSQL storage
    storage, err := goipam.NewPostgresStorage(
        "localhost",      // host
        "5432",           // port
        "ipam_user",      // user
        "secret",         // password
        "ipam_db",        // database name
        goipam.SSLModeDisable,
    )
    if err != nil {
        panic(err)
    }

    ipam := goipam.NewWithStorage(storage)

    // Create with Redis storage
    redisStorage, err := goipam.NewRedis(ctx, "localhost", "6379")
    if err != nil {
        panic(err)
    }
    ipamRedis := goipam.NewWithStorage(redisStorage)

    fmt.Printf("PostgreSQL IPAM ready\n")
    fmt.Printf("Redis IPAM ready\n")
    _ = ipam
    _ = ipamRedis
}
```

--------------------------------

### List Prefixes via gRPC (Go)

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Demonstrates how to list all available prefixes using the go-ipam gRPC API. It iterates through the returned prefixes and prints their CIDR notation, indicating the parent CIDR if it's a child prefix. Requires the go-ipam API client library.

```go
package main

import (
    "context"
    "fmt"
    "net/http"

    "connectrpc.com/connect"
    v1 "github.com/metal-stack/go-ipam/api/v1"
    "github.com/metal-stack/go-ipam/api/v1/apiv1connect"
)

func main() {
    client := apiv1connect.NewIpamServiceClient(
        http.DefaultClient,
        "http://localhost:9090",
        connect.WithGRPC(),
    )

    ctx := context.Background()

    result, err := client.ListPrefixes(ctx, connect.NewRequest(&v1.ListPrefixesRequest{}))
    if err != nil {
        panic(err)
    }

    fmt.Println("Prefixes:")
    for _, prefix := range result.Msg.GetPrefixes() {
        if prefix.GetParentCidr() != "" {
            fmt.Printf("  - %s (child of %s)\n", prefix.GetCidr(), prefix.GetParentCidr())
        } else {
            fmt.Printf("  - %s\n", prefix.GetCidr())
        }
    }
}
```

--------------------------------

### Create IPAM Instance with In-Memory Storage (Go)

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Initializes a new go-ipam Ipamer instance using in-memory storage. This is suitable for development and testing. It requires the context and returns an Ipamer instance or an error.

```Go
package main

import (
    "context"
    "fmt"

    goipam "github.com/metal-stack/go-ipam"
)

func main() {
    ctx := context.Background()

    // Create IPAM instance with in-memory storage
    ipam := goipam.New(ctx)

    // Create a prefix
    prefix, err := ipam.NewPrefix(ctx, "10.0.0.0/24")
    if err != nil {
        panic(err)
    }
    fmt.Printf("Created prefix: %s\n", prefix.Cidr)
    // Output: Created prefix: 10.0.0.0/24
}
```

--------------------------------

### Dump and Load IPAM State in Go

Source: https://context7.com/metal-stack/go-ipam/llms.txt

This Go code snippet demonstrates how to back up the entire IPAM state to a JSON string using the `Dump` function and restore it into a new IPAM instance using the `Load` function. It includes creating prefixes and acquiring IPs before dumping, and then verifies the restoration by retrieving a prefix from the new instance.

```go
package main

import (
    "context"
    "fmt"

    goipam "github.com/metal-stack/go-ipam"
)

func main() {
    ctx := context.Background()
    ipam := goipam.New(ctx)

    // Create prefixes and allocate IPs
    prefix, _ := ipam.NewPrefix(ctx, "10.0.0.0/24")
    _, _ = ipam.AcquireIP(ctx, prefix.Cidr)
    _, _ = ipam.AcquireIP(ctx, prefix.Cidr)

    // Dump to JSON
    dump, err := ipam.Dump(ctx)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Backup JSON length: %d bytes\n", len(dump))
    // Output: Backup JSON length: XXX bytes

    // Create new IPAM instance and restore
    newIpam := goipam.New(ctx)
    err = newIpam.Load(ctx, dump)
    if err != nil {
        panic(err)
    }

    // Verify restoration
    restoredPrefix, _ := newIpam.PrefixFrom(ctx, "10.0.0.0/24")
    fmt.Printf("Restored prefix: %s\n", restoredPrefix.Cidr)
    // Output: Restored prefix: 10.0.0.0/24
}

```

--------------------------------

### Create Isolated Namespaces in Go IPAM

Source: https://context7.com/metal-stack/go-ipam/llms.txt

This Go code demonstrates how to create and use isolated namespaces within the IPAM library for multi-tenant environments. It shows creating two namespaces ('tenant-a', 'tenant-b'), then creating prefixes and acquiring IPs within each namespace, proving that the same CIDR and IP addresses can coexist independently across different namespaces.

```go
package main

import (
    "context"
    "fmt"

    goipam "github.com/metal-stack/go-ipam"
)

func main() {
    ctx := context.Background()
    ipam := goipam.New(ctx)

    // Create namespaces for different tenants
    err := ipam.CreateNamespace(ctx, "tenant-a")
    if err != nil {
        panic(err)
    }
    err = ipam.CreateNamespace(ctx, "tenant-b")
    if err != nil {
        panic(err)
    }
    fmt.Println("Namespaces created")

    // Create context with namespace
    tenantACtx := goipam.NewContextWithNamespace(ctx, "tenant-a")
    tenantBCtx := goipam.NewContextWithNamespace(ctx, "tenant-b")

    // Same CIDR can exist in different namespaces
    prefixA, _ := ipam.NewPrefix(tenantACtx, "10.0.0.0/24")
    prefixB, _ := ipam.NewPrefix(tenantBCtx, "10.0.0.0/24")

    fmt.Printf("Tenant A prefix: %s\n", prefixA.Cidr)
    fmt.Printf("Tenant B prefix: %s\n", prefixB.Cidr)
    // Both output: 10.0.0.0/24 (isolated from each other)

    // IPs are independent per namespace
    ipA, _ := ipam.AcquireIP(tenantACtx, prefixA.Cidr)
    ipB, _ := ipam.AcquireIP(tenantBCtx, prefixB.Cidr)

    fmt.Printf("Tenant A IP: %s\n", ipA.IP)
    fmt.Printf("Tenant B IP: %s\n", ipB.IP)
    // Both output: 10.0.0.1 (same IP, different namespaces)
}

```

--------------------------------

### IP Management CLI Commands

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Details command-line interface commands for acquiring and releasing individual IP addresses within a specified prefix. Shows how to acquire single or multiple IPs and how to release a specific IP.

```bash
# Acquire an IP from a prefix
docker compose exec ipam /cli ip acquire --prefix 192.168.0.0/16
# Output: ip:"192.168.0.1" acquired

# Acquire multiple IPs
docker compose exec ipam /cli ip acquire --prefix 192.168.0.0/16
# Output: ip:"192.168.0.2" acquired

# Release an IP
docker compose exec ipam /cli ip release --prefix 192.168.0.0/16 --ip 192.168.0.1
# Output: ip:"192.168.0.1" released
```

--------------------------------

### Go Library: Acquire and Release IPs and Prefixes

Source: https://github.com/metal-stack/go-ipam/blob/master/README.md

Demonstrates the core functionality of the go-ipam library for managing IP addresses and prefixes within a namespace. It shows how to create a new prefix, acquire and release individual IPs, and acquire child prefixes.

```go
package main

import (
    "context"
    "fmt"
    "time"

    goipam "github.com/metal-stack/go-ipam"
)

func main() {
    // The background context
    bgCtx := context.Background()

    // Create a ipamer with in memory storage
    ipam := goipam.New(bgCtx)

    // Optionally, we can pass around a context for a given namespace
    namespace := "tenant-a"
    err := ipam.CreateNamespace(bgCtx, namespace)
    if err != nil {
        panic(err)
    }
    ctx := goipam.NewContextWithNamespace(bgCtx, namespace)
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()

    // Create a prefix to manage some IPs
    prefix, err := ipam.NewPrefix(ctx, "192.168.0.0/24")
    if err != nil {
        panic(err)
    }

    // Acquire and release an IP with this prefix
    ip, err := ipam.AcquireIP(ctx, prefix.Cidr)
    if err != nil {
        panic(err)
    }
    fmt.Printf("got IP: %s\n", ip.IP)

    prefix, err = ipam.ReleaseIP(ctx, ip)
    if err != nil {
        panic(err)
    }
    fmt.Printf("IP: %s released.\n", ip.IP)

    // Now a IPv6 Super Prefix with Child Prefixes
    prefix, err = ipam.NewPrefix(ctx, "2001:aabb::/48")
    if err != nil {
        panic(err)
    }

    cp1, err := ipam.AcquireChildPrefix(ctx, prefix.Cidr, 64)
    if err != nil {
        panic(err)
    }
    fmt.Printf("got Prefix: %s\n", cp1)

    cp2, err := ipam.AcquireChildPrefix(ctx, prefix.Cidr, 72)
    if err != nil {
        panic(err)
    }
    fmt.Printf("got Prefix: %s\n", cp2)
    ip21, err := ipam.AcquireIP(ctx, cp2.Cidr)
    if err != nil {
        panic(err)
    }
    fmt.Printf("got IP: %s\n", ip21.IP)
}
```

--------------------------------

### gRPC Create Prefix with Go IPAM API

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Demonstrates creating a new IP prefix using the gRPC/Connect API provided by go-ipam. It requires the context, HTTP client, and Connect RPC libraries. The request specifies the CIDR and optionally a namespace, returning the created prefix details.

```go
package main

import (
    "context"
    "fmt"
    "net/http"

    "connectrpc.com/connect"
    v1 "github.com/metal-stack/go-ipam/api/v1"
    "github.com/metal-stack/go-ipam/api/v1/apiv1connect"
)

func main() {
    client := apiv1connect.NewIpamServiceClient(
        http.DefaultClient,
        "http://localhost:9090",
        connect.WithGRPC(),
    )

    ctx := context.Background()

    // Create prefix
    result, err := client.CreatePrefix(ctx, connect.NewRequest(&v1.CreatePrefixRequest{
        Cidr: "10.0.0.0/16",
    }))
    if err != nil {
        panic(err)
    }

    fmt.Printf("Created prefix: %s\n", result.Msg.GetPrefix().GetCidr())
    // Output: Created prefix: 10.0.0.0/16

    // Create prefix in specific namespace
    result, err = client.CreatePrefix(ctx, connect.NewRequest(&v1.CreatePrefixRequest{
        Cidr:      "192.168.0.0/24",
        Namespace: strPtr("tenant-a"),
    }))
    if err != nil {
        panic(err)
    }
    fmt.Printf("Created prefix in namespace: %s\n", result.Msg.GetPrefix().GetCidr())
}

func strPtr(s string) *string { return &s }
```

--------------------------------

### Prefix Management CLI Commands

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Provides essential command-line interface commands for managing IPAM prefixes. Includes creating, listing, acquiring child prefixes, releasing child prefixes, and deleting prefixes.

```bash
# Create a prefix
docker compose exec ipam /cli prefix create --cidr 192.168.0.0/16
# Output: prefix:"192.168.0.0/16" created

# List all prefixes
docker compose exec ipam /cli prefix list
# Output: Prefix:"192.168.0.0/16" parent:"

# Acquire a child prefix
docker compose exec ipam /cli prefix acquire --parent 192.168.0.0/16 --length 24
# Output: child prefix:"192.168.0.0/24" from "192.168.0.0/16" created

# Release a child prefix
docker compose exec ipam /cli prefix release --cidr 192.168.0.0/24
# Output: child prefix:"192.168.0.0/24" from "192.168.0.0/16" released

# Delete a prefix
docker compose exec ipam /cli prefix delete --cidr 192.168.0.0/16
# Output: prefix:"192.168.0.0/16" deleted
```

--------------------------------

### Acquire Child Prefix via gRPC (Go)

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Demonstrates how to acquire a child prefix using the go-ipam gRPC API. It shows acquiring a prefix of a specific length and acquiring a specific child prefix. Requires the go-ipam API client library.

```go
package main

import (
    "context"
    "fmt"
    "net/http"

    "connectrpc.com/connect"
    v1 "github.com/metal-stack/go-ipam/api/v1"
    "github.com/metal-stack/go-ipam/api/v1/apiv1connect"
)

func main() {
    client := apiv1connect.NewIpamServiceClient(
        http.DefaultClient,
        "http://localhost:9090",
        connect.WithGRPC(),
    )

    ctx := context.Background()

    // Acquire child prefix with specific length
    result, err := client.AcquireChildPrefix(ctx, connect.NewRequest(&v1.AcquireChildPrefixRequest{
        Cidr:   "10.0.0.0/16",
        Length: 24,
    }))
    if err != nil {
        panic(err)
    }
    fmt.Printf("Acquired child prefix: %s (parent: %s)\n",
        result.Msg.GetPrefix().GetCidr(),
        result.Msg.GetPrefix().GetParentCidr())
    // Output: Acquired child prefix: 10.0.0.0/24 (parent: 10.0.0.0/16)

    // Acquire specific child prefix
    result, err = client.AcquireChildPrefix(ctx, connect.NewRequest(&v1.AcquireChildPrefixRequest{
        Cidr:      "10.0.0.0/16",
        ChildCidr: strPtr("10.0.100.0/24"),
    }))
    if err != nil {
        panic(err)
    }
    fmt.Printf("Acquired specific child: %s\n", result.Msg.GetPrefix().GetCidr())
    // Output: Acquired specific child: 10.0.100.0/24
}

func strPtr(s string) *string { return &s }
```

--------------------------------

### PrefixFrom

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Retrieves an existing prefix by its CIDR notation. Returns the prefix with its current state, including allocated IPs and child prefixes.

```APIDOC
## PrefixFrom

### Description
Retrieves a prefix by its CIDR notation. Returns the prefix with its current state including allocated IPs and child prefixes.

### Method
GET (implied by the go function signature, no explicit HTTP endpoint provided)

### Endpoint
N/A (This is a library function, not a REST API endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
This function does not directly map to a request body in a typical REST API sense. The parameters are passed directly to the function.
- **cidr** (string) - Required - The CIDR notation of the prefix to retrieve.

### Request Example
```go
// Example usage within the go-ipam library:
// prefix, err := ipam.PrefixFrom(ctx, "10.0.0.0/24")
```

### Response
#### Success Response (200)
- **Prefix** (*goipam.Prefix) - The retrieved prefix object.

#### Response Example
```json
{
  "Cidr": "10.0.0.0/24",
  "Parent": null,
  "Version": 4,
  "AvailableBits": 24,
  "TotalBits": 24
}
```

#### Error Handling
- Returns `goipam.ErrNotFound` if the prefix does not exist.
```

--------------------------------

### CLI Prefix Management

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Provides command-line interface (CLI) commands for managing prefixes, including creation, listing, acquiring child prefixes, releasing child prefixes, and deletion.

```APIDOC
## CLI Prefix Management Commands

### Description
Command-line interface for managing prefixes using the bundled CLI tool. This allows for CRUD operations on prefixes and management of their relationships.

### Usage
Ensure the go-ipam server is running (e.g., via Docker or Docker Compose).

### Commands

#### Create Prefix
```bash
docker compose exec ipam /cli prefix create --cidr 192.168.0.0/16
```
*Output:* `prefix:"192.168.0.0/16" created`

#### List Prefixes
```bash
docker compose exec ipam /cli prefix list
```
*Output:* `Prefix:"192.168.0.0/16" parent:""`

#### Acquire Child Prefix
```bash
docker compose exec ipam /cli prefix acquire --parent 192.168.0.0/16 --length 24
```
*Output:* `child prefix:"192.168.0.0/24" from "192.168.0.0/16" created`

#### Release Child Prefix
```bash
docker compose exec ipam /cli prefix release --cidr 192.168.0.0/24
```
*Output:* `child prefix:"192.168.0.0/24" from "192.168.0.0/16" released`

#### Delete Prefix
```bash
docker compose exec ipam /cli prefix delete --cidr 192.168.0.0/16
```
*Output:* `prefix:"192.168.0.0/16" deleted`
```

--------------------------------

### List All Namespaces

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Retrieves a list of all namespaces within the IPAM instance. This function is useful for understanding the current organizational structure of IP address management.

```APIDOC
## ListNamespaces

### Description
Returns a list of all namespaces in the IPAM instance.

### Method
GET

### Endpoint
/namespaces

### Parameters
#### Query Parameters
- **ctx** (context.Context) - Required - The context for the request.

### Response
#### Success Response (200)
- **[]string** - A slice of strings, where each string is a namespace name.

#### Response Example
```json
["root", "production", "staging", "development"]
```
```

--------------------------------

### CLI Backup and Restore

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Provides command-line interface (CLI) commands for backing up and restoring the IPAM data.

```APIDOC
## CLI Backup and Restore Commands

### Description
Command-line interface for backing up and restoring IPAM data using the bundled CLI tool. This is crucial for data persistence and disaster recovery.

### Usage
Ensure the go-ipam server is running.

### Commands

#### Backup Data
```bash
docker compose exec ipam /cli backup --file /data/backup.json
```
*Note:* This command will create a backup file at the specified path within the container. You may need to mount a volume to persist this data outside the container.

#### Restore Data
```bash
docker compose exec ipam /cli restore --file /data/backup.json
```
*Note:* Ensure the backup file exists at the specified path within the container. This operation will overwrite existing data.
```

--------------------------------

### gRPC List Prefixes

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Lists all available prefixes managed by the IPAM service via the gRPC API.

```APIDOC
## ListPrefixes - gRPC List All Prefixes

### Description
Lists all prefixes currently managed by the IPAM service through the gRPC API. This includes both parent and child prefixes.

### Method
GRPC

### Endpoint
`/v1.IpamService/ListPrefixes`

### Parameters
No specific parameters are required for this request.

### Request Example
```json
{
  "": ""
}
```

### Response
#### Success Response (200)
- **prefixes** (array) - A list of prefix objects.
  - **cidr** (string) - The CIDR of the prefix.
  - **parentCidr** (string) - The CIDR of the parent prefix, if it's a child prefix.

#### Response Example
```json
{
  "prefixes": [
    {
      "cidr": "10.0.0.0/16",
      "parentCidr": ""
    },
    {
      "cidr": "10.0.0.0/24",
      "parentCidr": "10.0.0.0/16"
    }
  ]
}
```
```

--------------------------------

### CreatePrefix - gRPC Create Prefix

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Creates a new IP prefix within the IPAM system using the gRPC API. You can specify a CIDR block and optionally assign it to a specific namespace.

```APIDOC
## POST /v1/CreatePrefix

### Description
Creates a new prefix via the gRPC API.

### Method
POST

### Endpoint
/v1/CreatePrefix

### Parameters
#### Request Body
- **Cidr** (string) - Required - The CIDR notation of the prefix to create (e.g., "10.0.0.0/16").
- **Namespace** (string) - Optional - The name of the namespace to which the prefix should be assigned.

### Request Example
```json
{
  "Cidr": "10.0.0.0/16"
}
```
```json
{
  "Cidr": "192.168.0.0/24",
  "Namespace": "tenant-a"
}
```

### Response
#### Success Response (200)
- **Prefix** (object) - Contains details of the created prefix.
  - **Cidr** (string) - The CIDR notation of the created prefix.

#### Response Example
```json
{
  "Prefix": {
    "Cidr": "10.0.0.0/16"
  }
}
```
```

--------------------------------

### Create Network Prefix (Go)

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Creates a new network prefix (subnet) from CIDR notation. This prefix can then be used for IP address allocation or creating child prefixes. The function accepts a context and the CIDR string, returning a Prefix object or an error if the prefix is invalid or overlaps.

```Go
package main

import (
    "context"
    "fmt"

    goipam "github.com/metal-stack/go-ipam"
)

func main() {
    ctx := context.Background()
    ipam := goipam.New(ctx)

    // Create an IPv4 prefix
    ipv4Prefix, err := ipam.NewPrefix(ctx, "192.168.1.0/24")
    if err != nil {
        panic(err)
    }
    fmt.Printf("IPv4 Prefix: %s\n", ipv4Prefix.Cidr)
    // Output: IPv4 Prefix: 192.168.1.0/24

    // Create an IPv6 prefix
    ipv6Prefix, err := ipam.NewPrefix(ctx, "2001:db8::/48")
    if err != nil {
        panic(err)
    }
    fmt.Printf("IPv6 Prefix: %s\n", ipv6Prefix.Cidr)
    // Output: IPv6 Prefix: 2001:db8::/48

    // Attempting to create overlapping prefix returns error
    _, err = ipam.NewPrefix(ctx, "192.168.1.128/25")
    if err != nil {
        fmt.Printf("Error (expected): %v\n", err)
        // Output: Error (expected): 192.168.1.128/25 overlaps 192.168.1.0/24
    }
}
```

--------------------------------

### Acquire Specific IP Address - Go

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Acquires a specific IP address from a given prefix. Returns an error if the IP is already allocated or outside the prefix. Requires the context and the prefix CIDR string.

```go
package main

import (
    "context"
    "errors"
    "fmt"

    goipam "github.com/metal-stack/go-ipam"
)

func main() {
    ctx := context.Background()
    ipam := goipam.New(ctx)

    prefix, _ := ipam.NewPrefix(ctx, "10.0.0.0/24")

    // Acquire a specific IP
    ip, err := ipam.AcquireSpecificIP(ctx, prefix.Cidr, "10.0.0.100")
    if err != nil {
        panic(err)
    }
    fmt.Printf("Acquired specific IP: %s\n", ip.IP)
    // Output: Acquired specific IP: 10.0.0.100

    // Attempting to acquire the same IP again returns error
    _, err = ipam.AcquireSpecificIP(ctx, prefix.Cidr, "10.0.0.100")
    if errors.Is(err, goipam.ErrAlreadyAllocated) {
        fmt.Println("IP already allocated")
        // Output: IP already allocated
    }

    // Attempting to acquire IP outside prefix returns error
    _, err = ipam.AcquireSpecificIP(ctx, prefix.Cidr, "10.0.1.1")
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        // Output: Error: given ip:10.0.1.1 is not in 10.0.0.0/24
    }
}
```

--------------------------------

### CLI IP Management

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Provides command-line interface (CLI) commands for acquiring and releasing individual IP addresses from specified prefixes.

```APIDOC
## CLI IP Management Commands

### Description
Command-line interface for acquiring and releasing individual IP addresses using the bundled CLI tool. This operates on top of the existing prefix structure.

### Usage
Ensure the go-ipam server is running and prefixes are created.

### Commands

#### Acquire IP
```bash
docker compose exec ipam /cli ip acquire --prefix 192.168.0.0/16
```
*Output:* `ip:"192.168.0.1" acquired`

#### Acquire Multiple IPs (example shows acquiring the next available IP)
```bash
docker compose exec ipam /cli ip acquire --prefix 192.168.0.0/16
```
*Output:* `ip:"192.168.0.2" acquired`

#### Release IP
```bash
docker compose exec ipam /cli ip release --prefix 192.168.0.0/16 --ip 192.168.0.1
```
*Output:* `ip:"192.168.0.1" released`
```

--------------------------------

### Docker Compose: Backup and Restore IPAM Data

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Commands to create a backup of the IPAM data to a JSON file and restore the IPAM database from a backup file. The backup command outputs JSON to stdout, and the restore command requires the database to be empty.

```bash
docker compose exec ipam /cli backup create > ipam-backup.json
docker compose exec ipam /cli backup restore --file /path/to/ipam-backup.json
# Output: database restored
```

--------------------------------

### gRPC Acquire IP with Go IPAM API

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Illustrates acquiring an IP address using the gRPC/Connect API of go-ipam. This function requires the context, HTTP client, and Connect RPC libraries. It allows acquiring the next available IP within a prefix or a specific IP address.

```go
package main

import (
    "context"
    "fmt"
    "net/http"

    "connectrpc.com/connect"
    v1 "github.com/metal-stack/go-ipam/api/v1"
    "github.com/metal-stack/go-ipam/api/v1/apiv1connect"
)

func main() {
    client := apiv1connect.NewIpamServiceClient(
        http.DefaultClient,
        "http://localhost:9090",
        connect.WithGRPC(),
    )

    ctx := context.Background()

    // Acquire next available IP
    result, err := client.AcquireIP(ctx, connect.NewRequest(&v1.AcquireIPRequest{
        PrefixCidr: "10.0.0.0/24",
    }))
    if err != nil {
        panic(err)
    }
    fmt.Printf("Acquired IP: %s\n", result.Msg.GetIp().GetIp())
    // Output: Acquired IP: 10.0.0.1

    // Acquire specific IP
    result, err = client.AcquireIP(ctx, connect.NewRequest(&v1.AcquireIPRequest{
        PrefixCidr: "10.0.0.0/24",
        Ip:         strPtr("10.0.0.100"),
    }))
    if err != nil {
        panic(err)
    }
    fmt.Printf("Acquired specific IP: %s\n", result.Msg.GetIp().GetIp())
    // Output: Acquired specific IP: 10.0.0.100
}

func strPtr(s string) *string { return &s }
```

--------------------------------

### Release IP by Prefix and IP String - Go

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Releases an IP address using its prefix CIDR and IP address string, without requiring the IP struct. This is useful when only the string representations are available. Requires context, prefix CIDR, and IP string.

```go
package main

import (
    "context"
    "fmt"

    goipam "github.com/metal-stack/go-ipam"
)

func main() {
    ctx := context.Background()
    ipam := goipam.New(ctx)

    prefix, _ := ipam.NewPrefix(ctx, "10.0.0.0/24")

    // Acquire specific IP
    _, _ = ipam.AcquireSpecificIP(ctx, prefix.Cidr, "10.0.0.50")

    // Release using prefix CIDR and IP string
    err := ipam.ReleaseIPFromPrefix(ctx, "10.0.0.0/24", "10.0.0.50")
    if err != nil {
        panic(err)
    }
    fmt.Println("IP 10.0.0.50 released successfully")
    // Output: IP 10.0.0.50 released successfully
}
```

--------------------------------

### ReleaseChildPrefix

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Releases a previously acquired child prefix back to the parent prefix, making it available for reallocation.

```APIDOC
## ReleaseChildPrefix

### Description
Releases a previously acquired child prefix back to the parent prefix. This makes the prefix available for reallocation.

### Method
POST (implied by the go function signature, no explicit HTTP endpoint provided)

### Endpoint
N/A (This is a library function, not a REST API endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
This function does not directly map to a request body in a typical REST API sense. The parameters are passed directly to the function.
- **childPrefix** (*goipam.Prefix) - Required - The child prefix object to release.

### Request Example
```go
// Example usage within the go-ipam library:
// err := ipam.ReleaseChildPrefix(ctx, child)
```

### Response
#### Success Response
- **Success** (bool) - Indicates if the release operation was successful.

#### Response Example
```json
{
  "Success": true
}
```

#### Error Handling
- Returns an error if the child prefix is invalid or cannot be released.
```

--------------------------------

### AcquireIP - gRPC Acquire IP

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Acquires the next available IP address from a specified prefix using the gRPC API. You can also request a specific IP address within the prefix.

```APIDOC
## POST /v1/AcquireIP

### Description
Acquires an IP address via the gRPC API.

### Method
POST

### Endpoint
/v1/AcquireIP

### Parameters
#### Request Body
- **PrefixCidr** (string) - Required - The CIDR notation of the prefix from which to acquire an IP (e.g., "10.0.0.0/24").
- **Ip** (string) - Optional - The specific IP address to acquire within the prefix. If not provided, the next available IP will be assigned.

### Request Example
```json
{
  "PrefixCidr": "10.0.0.0/24"
}
```
```json
{
  "PrefixCidr": "10.0.0.0/24",
  "Ip": "10.0.0.100"
}
```

### Response
#### Success Response (200)
- **Ip** (object) - Contains details of the acquired IP address.
  - **Ip** (string) - The acquired IP address.

#### Response Example
```json
{
  "Ip": {
    "Ip": "10.0.0.1"
  }
}
```
```

--------------------------------

### ReleaseIPFromPrefix

Source: https://context7.com/metal-stack/go-ipam/llms.txt

Releases an IP address using only the prefix CIDR and the IP address string, without needing the IP struct. This is a convenient alternative to ReleaseIP.

```APIDOC
## ReleaseIPFromPrefix

### Description
Releases an IP address using the prefix CIDR and IP string, without needing the IP struct. Useful when the IP object is not readily available.

### Method
POST (or equivalent internal operation)

### Endpoint
`/ipam/release/from-prefix` (conceptual endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
- **prefixCidr** (string) - Required - The CIDR notation of the prefix.
- **ipAddress** (string) - Required - The IP address string to release.

#### Request Body
None

### Request Example
(Conceptual - Go function call shown in example)
```go
// Example Go function call:
ipam.ReleaseIPFromPrefix(ctx, "10.0.0.0/24", "10.0.0.50")
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating successful release.

#### Response Example
```json
{
  "message": "IP 10.0.0.50 released successfully"
}
```
```