{"id":28471313,"url":"https://github.com/appthrust/plexaubnet","last_synced_at":"2025-10-23T02:33:39.168Z","repository":{"id":292795909,"uuid":"981953990","full_name":"appthrust/plexaubnet","owner":"appthrust","description":"Manage IPv4 CIDR pools at scale via CRDs \u0026 high-performance controllers—built for multi-cluster production.","archived":false,"fork":false,"pushed_at":"2025-05-14T01:35:10.000Z","size":298,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-26T10:56:42.049Z","etag":null,"topics":["cidr","cloudnative","kubernetes"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/appthrust.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-12T06:47:55.000Z","updated_at":"2025-05-14T09:03:04.000Z","dependencies_parsed_at":"2025-05-12T07:42:24.404Z","dependency_job_id":"d07de7f0-e1a8-4eea-ae06-73b18b64e66a","html_url":"https://github.com/appthrust/plexaubnet","commit_stats":null,"previous_names":["appthrust/plexaubnet"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/appthrust/plexaubnet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Fplexaubnet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Fplexaubnet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Fplexaubnet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Fplexaubnet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/appthrust","download_url":"https://codeload.github.com/appthrust/plexaubnet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Fplexaubnet/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263039381,"owners_count":23404168,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cidr","cloudnative","kubernetes"],"created_at":"2025-06-07T10:40:11.135Z","updated_at":"2025-10-23T02:33:34.137Z","avatar_url":"https://github.com/appthrust.png","language":"Go","readme":"# Plexaubnet (CIDR Operator)\n\nDeclarative CIDR Management Operator for Multi-Cluster Kubernetes v1.28+\n\n\u003c!-- Badges --\u003e\n[![CI](https://github.com/appthrust/plexaubnet/actions/workflows/test.yml/badge.svg)](https://github.com/appthrust/plexaubnet/actions/workflows/test.yml) ![Go Report Card](https://goreportcard.com/badge/github.com/appthrust/plexaubnet) ![License](https://img.shields.io/github/license/appthrust/plexaubnet)\n\n---\n\n## 1. Introduction\n\n**Plexaubnet** is a lightweight Kubernetes operator that automates CIDR assignment across clusters, tenants, or applications with simple declarative YAML—no spreadsheets, no custom scripts.  \nIt delivers declarative, idempotent CIDR assignment for clusters, tenants, or applications across multi-cluster environments.  \nWhile designed to integrate seamlessly with Submariner, Calico and other CNI plug-ins, Plexaubnet works perfectly as a standalone operator.\n\n**Key benefits**\n- Self-service CIDR allocation via CRDs – forget spreadsheets and ticket queues\n- Instant visibility into free \u0026 used ranges with millisecond-fast look-ups\n- Request exactly the subnet size you need (/16 – /28) while Plexaubnet handles the math with Linear or Buddy strategies\n- Built-in Prometheus metrics and rich CRD status for effortless monitoring and troubleshooting\n\n---\n\n## 2. Feature Overview\n\n| Resource | Description |\n| -------- | ----------- |\n| **SubnetPool** | Defines CIDR range, block-size constraints and allocation strategy (*Linear* / *Buddy*) |\n| **SubnetClaim** | Request a block (by block size or fixed CIDR) for a cluster / tenant |\n| **Subnet** | Controller-generated allocation object |\n| **SubnetPoolClaim** | Dynamically split an existing pool to create child SubnetPools |\n| **Idempotent** | `spec.clusterID` prevents duplicate allocations |\n| **Status \u0026 Metrics** | `allocatedCount`, `freeCountBySize` etc. exposed via CR status and Prometheus |\n\n**Latest additions**\n- **Centralized Field Indexer** – consistent naming \u0026 O(1) look-ups\n- **Parent Pool Requeue Strategy** – unified management in *PoolStatusReconciler*\n- **Extended Subnet Status** – `phase`, `allocatedAt`, `releasedAt` fields\n\n---\n\n## 3. Architecture\n\n### Controller Set\n1. **SubnetClaim Reconciler** – validates requests \u0026 drives phase transitions (`Pending → Bound / Error`)\n2. **PoolStatusReconciler** – centralizes pool statistics based on current Subnets\n3. **SubnetReconciler** – manages Subnet lifecycle and re-queues parent pools\n4. **SubnetPoolClaim Reconciler** – splits parent pools and creates child pools\n\n### Flow\n\n```mermaid\nflowchart TD\n  subgraph User\n    A[SubnetPool] --\u003e|ref| B[SubnetClaim]\n    A2[Parent SubnetPool] --\u003e|ref| F[SubnetPoolClaim]\n  end\n  B --enqueue--\u003e C[Claim Reconciler]\n  C --\u003e|allocate| D[Subnet]\n  D --\u003e|trigger| E[PoolStatusReconciler]\n  E --\u003e|update| A[SubnetPool Status]\n  C --\u003e|set Bound| B\n  F --enqueue--\u003e G[PoolClaim Reconciler]\n  G --\u003e|create child| H[SubnetPool]\n  H --\u003e|exists in same namespace| A2\n```\n\n### Prerequisites\n- Kubernetes **v1.30 or later**\n- `kubectl` access with cluster-admin privileges\n- Optional: Go **1.22+** when building from source\n\n### Compatibility Matrix\n\n| Kubernetes | CRD Version | Operator Image |\n| ---------- | ----------- | -------------- |\n| v1.30+     | `v1alpha1`  | `ghcr.io/appthrust/plexaubnet:v0.5.x` |\n\nFor detailed design docs see:\n- [Architecture Overview](docs/design/architecture-overview.md)\n- [Parent Pool Requeue Strategy](docs/design/pool-status/parent-pool-requeue-strategy.md)\n- [Centralized Field Indexer Design](docs/design/indexer-centralization/centralize-indexes-design.md)\n\n---\n\n## 4. API Specification (Excerpt)\n\n**Group / Version**: `plexaubnet.io/v1alpha1`\n\n### SubnetPool\n| Field | Type | Required | Description |\n| ----- | ---- | -------- | ----------- |\n| `spec.cidr` | string (cidr) | ✅ | Pool range, e.g. `10.0.0.0/16` |\n| `spec.defaultBlockSize` | int (16-28) |  | Default when claim omits block size (default **24**) |\n| `spec.minBlockSize` / `spec.maxBlockSize` | int |  | Allocation size constraints |\n| `spec.strategy` | enum |  | `Linear` / `Buddy` (default **Linear**) |\n\n### SubnetClaim\n| Field | Type | Required | Description |\n| ----- | ---- | -------- | ----------- |\n| `spec.poolRef` | string | ✅ | Source SubnetPool |\n| `spec.clusterID` | string | ✅ | DNS-1123 idempotency key |\n| `spec.blockSize` | int | Cond. | Prefix length |\n| `spec.requestedCIDR` | string (cidr) | Cond. | Fixed CIDR (mutually exclusive with `blockSize`) |\n\n### Subnet\n| Field | Type | Required | Description |\n| ----- | ---- | -------- | ----------- |\n| `spec.poolRef` | string | ✅ | Parent SubnetPool |\n| `spec.cidr` | string (cidr) | ✅ | Allocated CIDR |\n| `spec.clusterID` | string | ✅ | |\n| `spec.claimRef.name` / `uid` | string |  | Back-link to claim |\n| `status.phase` | string |  | Allocated / Released / Failed |\n| `status.allocatedAt` | datetime |  | Allocation timestamp |\n| `status.releasedAt` | datetime |  | Release timestamp |\n\n### SubnetPoolClaim\n| Field | Type | Required | Description |\n| ----- | ---- | -------- | ----------- |\n| `spec.parentPoolRef` | string | ✅ | Parent pool to split |\n| `spec.desiredBlockSize` | int (16-28) | ✅ | CIDR prefix length for child pool |\n\n➡️ **Full CRDs** are located under [`./config/crd/bases`](config/crd/bases).\n\n---\n\n## 5. Installation\n\n### Helm (official chart)\n\n```bash\n# ▶︎ From the published Helm repo\nhelm repo add plexaubnet https://appthrust.github.io/plexaubnet\nhelm install plexaubnet plexaubnet/plexaubnet \\\n  --namespace plexaubnet \\\n  --create-namespace\n\n# ▶︎ From the source tree (development / local testing)\nhelm install plexaubnet charts/plexaubnet \\\n  --namespace plexaubnet \\\n  --create-namespace\n\n# Example: load a locally-built image into kind and deploy\nkind create cluster --name plexaubnet-test\n\ndocker build -t ghcr.io/appthrust/plexaubnet:dev .\nkind load docker-image ghcr.io/appthrust/plexaubnet:dev --name plexaubnet-test\n\nhelm install plexaubnet charts/plexaubnet \\\n  --namespace plexaubnet \\\n  --create-namespace \\\n  --set image.tag=dev\n```\n\nCommon values:\n| Key | Default | Description |\n|-----|---------|-------------|\n| `metrics.enabled` | `true` | Expose `/metrics` endpoint \u0026 create Service |\n| `metrics.serviceMonitor.enabled` | `false` | Create ServiceMonitor for Prometheus Operator |\n| `podSecurityContext.runAsUser` | `65532` | Non-root UID (non-root distroless) |\n\n\u003e **Tip**: run `helm show values charts/plexaubnet` for the full list.\n\n### Kustomize (recommended)\n\n```bash\nkubectl apply -k github.com/appthrust/plexaubnet/config/default\n```\n\n### Raw Manifests\n\n```bash\nkubectl apply -f https://raw.githubusercontent.com/appthrust/plexaubnet/main/release/plexaubnet.yaml\n```\n\nAfter installation verify CRDs:\n\n```bash\nkubectl get crds | grep plexaubnet\n```\n\nHelm chart support is now available via the published repo above.\n\n---\n\n## 6. Quick Start\n\n1. **Create a SubnetPool**  \n   `pool.yaml`\n   ```yaml\n   apiVersion: plexaubnet.io/v1alpha1\n   kind: SubnetPool\n   metadata:\n     name: example-pool\n   spec:\n     cidr: 10.10.0.0/16\n     defaultBlockSize: 24\n     strategy: Linear\n   ```\n\n   ```bash\n   kubectl apply -f pool.yaml\n   ```\n\n2. **Request a SubnetClaim**\n\n   ```yaml\n   apiVersion: plexaubnet.io/v1alpha1\n   kind: SubnetClaim\n   metadata:\n     name: cluster-a\n   spec:\n     poolRef: example-pool\n     clusterID: cluster-a\n     blockSize: 24\n   ```\n\n   ```bash\n   kubectl apply -f claim.yaml\n   ```\n\n3. **Inspect the result**\n\n   ```bash\n   kubectl get subnetclaims\n   kubectl get subnetpools example-pool -o yaml\n   kubectl get subnets -l plexaubnet.io/cluster-id=cluster-a\n   ```\n\n   The claim status `allocatedCIDR` should show **10.10.0.0/24** and `allocatedCount` in the pool will increment.\n\n---\n\n## 7. Status \u0026 Metrics\n\n### SubnetPool Status\n\n| Field | Description |\n| ----- | ----------- |\n| `allocatedCount` | Number of allocated blocks |\n| `freeCountBySize` | Free blocks per size |\n| `allocatedCIDRs` | CIDR → clusterID mapping |\n| `conditions` | Ready / Exhausted / etc. |\n\n### Prometheus Metrics\n\n- `plexaubnet_pool_allocated_total{pool=\"example-pool\"}`\n- `plexaubnet_claim_phase{phase=\"Bound\"}`\n- `subnet_status_update_total{result=\"success\"}`\n- `subnetpool_parent_requeue_total{event_type=\"delete\"}`\n- `subnetpool_parent_reconcile_duration_seconds`\n\nMetrics are exposed at the `/metrics` endpoint and can be scraped via the standard Prometheus Operator.\n\n---\n\n## 8. FAQ\n\n**Q. Do you support IPv6?**  \n**A.** IPv4 only for now. IPv6 support is planned for v0.7.\n\n**Q. Will it conflict with my existing IPAM?**  \n**A.** Configure non-overlapping pools and Plexaubnet can coexist with external IPAM (e.g., Calico).\n\n**Q. Does it scale to large environments?**  \n**A.** Yes. Centralized indexers, optimized patch operations and a custom rate limiter allow handling thousands of Subnets and Pools.\n\n---\n\n## 9. Roadmap \u0026 Contributing\n\n| Version | Planned Items |\n| ------- | ------------- |\n| v0.5 ✅ | Centralized Field Indexer, Parent Pool Requeue Strategy |\n| v0.6 | Helm Chart, extended CI/CD pipeline |\n| v0.7 | IPv6 support, Buddy allocation optimizations |\n| v1.0 | GA, multi-namespace support |\n\nContributions are welcome! Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) and sign the CLA before opening a PR.\n\n---\n\n© 2025 Aquanaut Project / Plexaubnet Authors – Licensed under Apache-2.0","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappthrust%2Fplexaubnet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fappthrust%2Fplexaubnet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappthrust%2Fplexaubnet/lists"}