{"id":22220856,"url":"https://github.com/nokia/k8s-ipam","last_synced_at":"2025-04-09T20:15:36.518Z","repository":{"id":62637866,"uuid":"560880071","full_name":"nokia/k8s-ipam","owner":"nokia","description":null,"archived":false,"fork":false,"pushed_at":"2024-10-09T04:56:47.000Z","size":1420,"stargazers_count":19,"open_issues_count":3,"forks_count":9,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-09T20:15:30.330Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/nokia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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}},"created_at":"2022-11-02T13:26:17.000Z","updated_at":"2024-12-14T05:44:52.000Z","dependencies_parsed_at":"2023-02-17T06:00:27.758Z","dependency_job_id":"93ec3716-fae2-45b8-898c-5dce85ff0148","html_url":"https://github.com/nokia/k8s-ipam","commit_stats":{"total_commits":251,"total_committers":4,"mean_commits":62.75,"dds":0.01195219123505975,"last_synced_commit":"de66a47ea16c73346e56570e77ff8c61caa3a005"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Fk8s-ipam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Fk8s-ipam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Fk8s-ipam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Fk8s-ipam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nokia","download_url":"https://codeload.github.com/nokia/k8s-ipam/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248103872,"owners_count":21048245,"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":[],"created_at":"2024-12-02T23:10:38.973Z","updated_at":"2025-04-09T20:15:36.489Z","avatar_url":"https://github.com/nokia.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n[![Go Report](https://img.shields.io/badge/go%20report-A%2B-blue?style=flat-square\u0026color=00c9ff\u0026labelColor=bec8d2)](https://goreportcard.com/report/github.com/henderiw-nephio/ipam)\n\n\n---\n# A Native Kubernetes IPAM\n\nThe IPAM is a kubernetes native IP address management, which supports:\n- virtual networks to allow for overlapping IP(s)\n- IP addresses, IP prefixes, IP pools and IP ranges within a virtual network\n- A k8s api using CRD(s) for configuring and allocating IP addresses within a virtual network\n- A GRPC API for allocating and deallocating IP addresses/prefixes/pools\n- labels as selectors for IP address allocation or to provide metadata to the ipam resource\n- IPv6 and IPv4 in single stack or dual stack mode\n\n![ipam architecture](ipam-architecture.jpg)\n\n## ipam logic and terminology\n◊\nThe IPAM has multiple network contexts (implemented as network-instances) that can have multiple prefixes that can be nested. The top prefix of a nested hierarchy is called an aggregated prefix. At the bottom layer we can have IP ranges or IP addresses that are allocated from within a prefix.\n\n![ipam hierarchy](ipam-hierarchy.jpg)\n\nPrefix - A subnet defined within an aggregate prefix. Prefixes extend the hierarchy by nesting within one another. (For example, 2000:1:1::/64 will appear within 2000:1::/48.)\n\nIP Range - An arbitrary range of individual IP addresses within a prefix, all sharing the same mask. (out of scope for now)\n\nIP Address - An individual IP address along with its subnet mask, automatically arranged beneath its parent prefix.\n\nThe actual IPPrefix CRD does not distinguish between an address or a prefix, since an address is a special case of a prefix. An address has a /128 or /32 for ipv6, ipv4 resp.\n\n### ipam use cases\n\nEverything in the IPAM is modelled as an IP Prefix. An IP address is a specific implementation of an IP prefix, meaning is is resp /32 or /128 for ipv4 and ipv6. Besides the IP address There are various use cases for an IP Prefix, like interface based IP(s), loopback based IPs and IP pools/ranges. In order to allow for flexibility a prefix kind is introduced and hence an ip prefix can have various kinds:\n\n- Aggregate: \n  - IP Prefixes are naturally hierarchical and are typically drawn from a specific space that someone operates with. An aggregate prefix-kind can be seen as the top level when nesting IP prefixes. E.g. if an operator got a IP prefix assigned from the RIR it would be implemented as an aggergate. \n  - An aggregate can be nested. E.g. if someone wants to subdivide an address space they can define multiple aggregates where multiple teams operate with.\n  - Children of an aggregate IP prefix can be of kind: network, pool and loopback\n  - Parents of an aggregate IP prefix can be of kind: aggregate\n- network: \n  - IP prefixes that are assigned on (virtual/physical) interfaces of a application would be modelled as a prefix kind network. IP prefixes of this kind can have a mesh relationship between them. E.g. a LAN environment can have multiple routers and hosts that all are in the same subnet.\n  - Children of a network IP prefix can be of kind: network\n  - Parents of a network IP prefix can be of kind: aggregate\n- pool:\n  - IP prefixes can also be assigned to pools. E.g. a pool for a DHCP server, a pool for NAT, a pool for allocating IP adddresses to users. The IP prefix of kind pool allows for this use case\n  - Children of a pool IP prefix can be of kind: pool\n  - Parents of a pool IP prefix can be of kind: aggregate or pool\n- loopback\n  - IP prefixes can also be assigned to a loopback interface in the application. E.g. a socket for a RADIUS server, Diameter, HTTP srever. The IP prefix of kind loopback allows for this use case\n  - Children of a loopback IP prefix can be of kind: loopback\n  - Parents of a loopback IP prefix can be of kind: aggregate \n\n## Injector\n\nBesides the base IPAM block there is also a injector functions which looks at IP Allocations within a GitRepo/package revision and allocates/deallocates IP(s) using a GRPC interface. This is a pluggable system which allows to interact with 3rd party IPAM systems.\n\n## use cases\n\n### run IPAM\n\n```\nmake run\n```\n\n### run IPAM using kpt\n\n```\nkpt live init blueprint/ipam\nkpt live apply blueprint/ipam\n```\n\n### Setup IPAM\n\nTo steup the IPAM, one needs to configure a virtual network, implemented through a network-instance\n\n```\ncat \u003c\u003cEOF | kubectl apply -f -\napiVersion: ipam.nephio.org/v1alpha1\nkind: NetworkInstance\nmetadata:\n  name: vpc-1\nspec:\nEOF\n```\n\nThe next step is to create a prefix from which ip addresses can be allocated.\n\nA network prefix example with a gateway.\n\n```\ncat \u003c\u003cEOF | kubectl apply -f -\napiVersion: ipam.nephio.org/v1alpha1\nkind: IPPrefix\nmetadata:\n  name: net1-prefix1\n  labels:\n    nephio.org/gateway: \"true\"\nspec:\n  prefix: 10.0.1.1/24\n  network: net1\n  networkInstance: vpc-1\nEOF\n```\n\nAn aggregated prefix example\n\n```\ncat \u003c\u003cEOF | kubectl apply -f -\napiVersion: ipam.nephio.org/v1alpha1\nkind: IPPrefix\nmetadata:\n  name: aggregate0\nspec:\n  kind: aggregate\n  prefix: 10.0.0.0/8\n  networkInstance: vpc-1\nEOF\n```\n\nTo verify the status in the system we can use the following command\n\n```\nkubectl get ipam\n```\n\nThe output will look like this\n\n```\nNAME                                    SYNC   STATUS   NETWORK   KIND        NETWORK   PREFIX-REQ    PREFIX-ALLOC   AGE\nipprefix.ipam.nephio.org/aggregate0     True   True     vpc-1     aggregate             10.0.0.0/8    10.0.0.0/8     5s\nipprefix.ipam.nephio.org/net1-prefix1   True   True     vpc-1     network     net1      10.0.1.1/24   10.0.1.1/24    75s\n\nNAME                                    SYNC   STATUS   AGE\nnetworkinstance.ipam.nephio.org/vpc-1   True   True     2m44s\n```\n\nTo view the IPAM IP allocation we can look at the allocations under the network-instance\n\n```\nkubectl describe  networkinstances.ipam.nephio.org network-1\n```\n\nThe output will look like this\n\n```\nk describe networkinstances.ipam.nephio.org network-1\nName:         vpc-1\nNamespace:    default\nAPI Version:  ipam.nephio.org/v1alpha1\nKind:         NetworkInstance\n\n....\n\nStatus:\n  Allocations:\n    10.0.0.0/8:\n      nephio.org/address-family:    ipv4\n      nephio.org/allocation-name:   aggregate0\n      nephio.org/network-instance:  vpc-1\n      nephio.org/origin:            prefix\n      nephio.org/prefix-kind:       aggregate\n      nephio.org/prefix-length:     8\n      nephio.org/prefix-name:       aggregate0\n    10.0.1.0/24:\n      nephio.org/address-family:    ipv4\n      nephio.org/allocation-name:   10.0.1.0-24\n      nephio.org/network:           10.0.1.0\n      nephio.org/network-instance:  vpc-1\n      nephio.org/network-name:      net1\n      nephio.org/origin:            system\n      nephio.org/prefix-kind:       network\n      nephio.org/prefix-length:     24\n      nephio.org/prefix-name:       net\n    10.0.1.0/32:\n      nephio.org/address-family:        ipv4\n      nephio.org/allocation-name:       10.0.1.0\n      nephio.org/network:               10.0.1.0\n      nephio.org/network-instance:      vpc-1\n      nephio.org/network-name:          net1\n      nephio.org/origin:                system\n      nephio.org/parent-prefix-length:  24\n      nephio.org/prefix-kind:           network\n      nephio.org/prefix-length:         32\n      nephio.org/prefix-name:           net\n    10.0.1.1/32:\n      nephio.org/address-family:        ipv4\n      nephio.org/allocation-name:       net1-prefix1\n      nephio.org/gateway:               true\n      nephio.org/network:               10.0.1.0\n      nephio.org/network-instance:      vpc-1\n      nephio.org/network-name:          net1\n      nephio.org/origin:                prefix\n      nephio.org/parent-prefix-length:  24\n      nephio.org/prefix-kind:           network\n      nephio.org/prefix-length:         32\n      nephio.org/prefix-name:           net1-prefix1\n  Conditions:\n    Kind:                  Synced\n    Last Transition Time:  2022-11-07T11:01:28Z\n    Reason:                ReconcileSuccess\n    Status:                True\n    Kind:                  Ready\n    Last Transition Time:  2022-11-07T11:01:28Z\n    Reason:                Ready\n    Status:                True\nEvents:                    \u003cnone\u003e\n```\n\n### IP address allocation \n\nTo request an IP address from the IPAM system we either use the K8s or the GRPC API.\nBy providing a network-instance and network-name label-selector an IP address will be allocated\nfrom an IPAM prefix that matches these labels.\n\n```\ncat \u003c\u003cEOF | kubectl apply -f -\napiVersion: ipam.nephio.org/v1alpha1\nkind: IPAllocation\nmetadata:\n  name: alloc1\nspec:\n  kind: network\n  selector:\n    matchLabels:\n      nephio.org/network-instance:  vpc-1\n      nephio.org/network-name: net1\nEOF\n```\n\nA prefix and parent prefix is allocated\n\n```\nNAME                                  SYNC   STATUS   KIND      AF    PREFIXLENGTH   PREFIX-REQ   PREFIX-ALLOC   GATEWAY    AGE\nipallocation.ipam.nephio.org/alloc1   True   True     network                                     10.0.1.2/32    10.0.1.1   4s\n```\n\n### static IP address allocation \n\nTo support static or determinsitic IP allocation a predetermined IP is allocated using the IP Prefix API, that sets a specific label e.g. key: nephio.org/interface value: n3. Any key and value can be used other thna the system defined once\n\n```\ncat \u003c\u003cEOF | kubectl apply -f -\napiVersion: ipam.nephio.org/v1alpha1\nkind: IPPrefix\nmetadata:\n  name: net1-prefix10\n  labels:\n    nephio.org/interface: n3\nspec:\n  prefix: 10.0.1.10/24\n  network: net1\n  networkInstance: vpc-1\nEOF\n```\n\nBy referencing this label in the label selector we can allocate the IP that was statically allocated\n\n```\ncat \u003c\u003cEOF | kubectl apply -f -\napiVersion: ipam.nephio.org/v1alpha1\nkind: IPAllocation\nmetadata:\n  name: alloc2-n3\nspec:\n  kind: network\n  selector:\n    matchLabels:\n      nephio.org/network-instance:  vpc-1\n      nephio.org/network-name: net1\n      nephio.org/interface: n3\nEOF\n```\n\n```\nNAME                                     SYNC   STATUS   NETWORK   KIND        NETWORK   PREFIX-REQ     PREFIX-ALLOC   AGE\nipprefix.ipam.nephio.org/aggregate0      True   True     vpc-1     aggregate             10.0.0.0/8     10.0.0.0/8     19m\nipprefix.ipam.nephio.org/net1-prefix1    True   True     vpc-1     network     net1      10.0.1.1/24    10.0.1.1/24    21m\nipprefix.ipam.nephio.org/net1-prefix10   True   True     vpc-1     network     net1      10.0.1.10/24   10.0.1.10/24   14m\n\nNAME                                     SYNC   STATUS   KIND      AF    PREFIXLENGTH   PREFIX-REQ   PREFIX-ALLOC   GATEWAY     AGE\nipallocation.ipam.nephio.org/alloc1      True   True     network                                     10.0.1.11/32   10.0.1.0    17m\nipallocation.ipam.nephio.org/alloc2-n3   True   True     network                                     10.0.1.10/32   10.0.1.10   11m\n```\n\n### GW IP address allocation\n\nTo request the GW IP of the prefix, we use the following mechanism:\n\n- First when creating the IP prefix we create it using the following notation 10.0.0.1/24. As such the .1 is allocated by the IPAM as a gateway IP automatically.\n\nAllocate an IP with the ephio.org/gateway: \"true\" label in the label selector\n\n```\ncat \u003c\u003cEOF | kubectl apply -f -\napiVersion: ipam.nephio.org/v1alpha1\nkind: IPPrefix\nmetadata:\n  name: net1-prefix1\n  labels:\n    nephio.org/gateway: \"true\"\nspec:\n  prefix: 10.0.1.1/24\n  network: net1\n  networkInstance: vpc-1\nEOF\n```\n\nNow also the GW IP will be referenced\n\n```\nkubectl get ipam\n```\n\n```\nNAME                                     SYNC   STATUS   NETWORK   KIND        NETWORK   PREFIX-REQ     PREFIX-ALLOC   AGE\nipprefix.ipam.nephio.org/aggregate0      True   True     vpc-1     aggregate             10.0.0.0/8     10.0.0.0/8     19m\nipprefix.ipam.nephio.org/net1-prefix1    True   True     vpc-1     network     net1      10.0.1.1/24    10.0.1.1/24    21m\nipprefix.ipam.nephio.org/net1-prefix10   True   True     vpc-1     network     net1      10.0.1.10/24   10.0.1.10/24   14m\n\nNAME                                     SYNC   STATUS   KIND      AF    PREFIXLENGTH   PREFIX-REQ   PREFIX-ALLOC   GATEWAY     AGE\nipallocation.ipam.nephio.org/alloc1      True   True     network                                     10.0.1.11/32   10.0.1.0    17m\nipallocation.ipam.nephio.org/alloc2-n3   True   True     network                                     10.0.1.10/32   10.0.1.10   11m\n```\n\n### pool allocation\n\nTo allocate a pool we speific the prefix length and the network-instance that should match\n\n```\ncat \u003c\u003cEOF | kubectl apply -f -\napiVersion: ipam.nephio.org/v1alpha1\nkind: IPAllocation\nmetadata:\n  name: alloc-pool1\nspec:\n  kind: pool\n  prefixLength: 16\n  selector:\n    matchLabels:\n      nephio.org/network-instance:  vpc-1\nEOF\n```\n\n```\nkubectl get get ipallocations.ipam.nephio.org\n```\n\n```\nNAME                                       SYNC   STATUS   KIND      AF    PREFIXLENGTH   PREFIX-REQ   PREFIX-ALLOC   GATEWAY     AGE\nipallocation.ipam.nephio.org/alloc-pool1   True   True     pool            16                          10.1.0.0/16                4s\n```\n## License\n\nCopyright 2022 nokia.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnokia%2Fk8s-ipam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnokia%2Fk8s-ipam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnokia%2Fk8s-ipam/lists"}