From e84a60a1e82d08e9a9978b24ea905b663e7608f0 Mon Sep 17 00:00:00 2001 From: Pablo Garcia Miranda Date: Fri, 11 Apr 2025 10:37:28 +0200 Subject: [PATCH 01/10] Adding claim model and adding a operational-manual.md --- README.md | 12 ++++++++++++ docs/claim-model.svg | 1 + docs/operational-manual.md | 6 ++++++ 3 files changed, 19 insertions(+) create mode 100644 docs/claim-model.svg create mode 100644 docs/operational-manual.md diff --git a/README.md b/README.md index da7136b7..e587a8e3 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,18 @@ for i in {001..100}; do done ``` +# The Claim Model +The NetBox Operator implements a "Claim Model" inspired by Kubernetes PersistentVolumeClaims (PVCs). +In this case, instead of disk storage, NetBox Operator dynamically allocates network resources (Prefixes and IP Addresses) based on claims submitted via custom resources. + +## Purpose +This model ensures a declarative management of IP addressing and subnet allocation, with full NetBox integration. +The network operators will create claims (PrefixClaims & IPAddressClaims), and the NetBox Operator will resolve them into actual Prefixes and IPAddresses within a designated parent block. + +

+ +

+ # Mixed usage of Prefixes Note that NetBox does handle the Address management of Prefixes separately from IP Ranges and IP Addresses. This is important to know when you plan to use the same NetBox Prefix as a parentPrefix for your IpAddressClaims, IpRangeClaims and PrefixClaims. diff --git a/docs/claim-model.svg b/docs/claim-model.svg new file mode 100644 index 00000000..325b3c67 --- /dev/null +++ b/docs/claim-model.svg @@ -0,0 +1 @@ +

NetBox

Claim Allocation Engine

NetBox Operator

Available block

Available IP

PrefixClaim

NetBox

IpAddressClaim

Find parentPrefix

Allocate Prefix

Allocate IP

Prefix

IpAddress

Used by workloads

 \ No newline at end of file diff --git a/docs/operational-manual.md b/docs/operational-manual.md new file mode 100644 index 00000000..8dc6da54 --- /dev/null +++ b/docs/operational-manual.md @@ -0,0 +1,6 @@ +# Operational Manual + +This document describes how to troubleshoot errors in the NetBox Operator. +Known issues are collected on the [GitHub issues](https://github.com/netbox-community/netbox-operator/issues) page. + +## Troubleshooting \ No newline at end of file From ccd3d27b222244556ea3caafb344c6b0a5d3a3a6 Mon Sep 17 00:00:00 2001 From: Pablo Garcia Miranda Date: Wed, 16 Apr 2025 15:15:44 +0200 Subject: [PATCH 02/10] Adding different ways of troubleshooting the operator --- docs/operational-manual.md | 39 +++++++++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/docs/operational-manual.md b/docs/operational-manual.md index 8dc6da54..60ed76a8 100644 --- a/docs/operational-manual.md +++ b/docs/operational-manual.md @@ -3,4 +3,41 @@ This document describes how to troubleshoot errors in the NetBox Operator. Known issues are collected on the [GitHub issues](https://github.com/netbox-community/netbox-operator/issues) page. -## Troubleshooting \ No newline at end of file +## Troubleshooting + +### Check Logs +Use the following command to get logs from the operator: + +```bash +kubectl logs -n deployment/netbox-operator-controller-manager +``` + +### Check CR Status +Inspect the CRs status: + +```bash +kubectl describe -n +``` + +This will show you the status of the operator and any errors it may have encountered. + +### Verify Operator Version + +```bash +kubectl get deployment netbox-operator-controller-manager -n -o=jsonpath="{.spec.template.spec.containers[*].image}" +``` + +### Look at Related Pods +If netbox-oeprator is not running correctly, inspect the related pods: + +```bash +kubectl logs deployment/netbox-operator-controller-manager -n -c manager +kubectl describe pod -n +``` + +### Check Events +Events might give hints about what’s going wrong: + +```bash +kubectl get events -n --sort-by='.lastTimestamp' +``` \ No newline at end of file From f836bd942ceafb9864bf6461326301e5f671d1ae Mon Sep 17 00:00:00 2001 From: Pablo Garcia Miranda Date: Wed, 16 Apr 2025 16:08:03 +0200 Subject: [PATCH 03/10] Change wording --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e587a8e3..ea70006f 100644 --- a/README.md +++ b/README.md @@ -64,12 +64,12 @@ done ``` # The Claim Model -The NetBox Operator implements a "Claim Model" inspired by Kubernetes PersistentVolumeClaims (PVCs). +The NetBox Operator implements a "Claim Model" which is also used in the Kubernetes PersistentVolumeClaims (PVCs). In this case, instead of disk storage, NetBox Operator dynamically allocates network resources (Prefixes and IP Addresses) based on claims submitted via custom resources. ## Purpose This model ensures a declarative management of IP addressing and subnet allocation, with full NetBox integration. -The network operators will create claims (PrefixClaims & IPAddressClaims), and the NetBox Operator will resolve them into actual Prefixes and IPAddresses within a designated parent block. +The users will create claims (PrefixClaims & IPAddressClaims), and the NetBox Operator will resolve them into actual Prefixes and IPAddresses within a designated parent prefix.

From 544442075ac351e4772050d682823b2e03e7aac5 Mon Sep 17 00:00:00 2001 From: Pablo Garcia Miranda Date: Wed, 16 Apr 2025 16:18:06 +0200 Subject: [PATCH 04/10] Improve wording in claim-model.svg diagram --- docs/claim-model.svg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/claim-model.svg b/docs/claim-model.svg index 325b3c67..17b62619 100644 --- a/docs/claim-model.svg +++ b/docs/claim-model.svg @@ -1 +1 @@ -

NetBox

Claim Allocation Engine

NetBox Operator

Available block

Available IP

PrefixClaim

NetBox

IpAddressClaim

Find parentPrefix

Allocate Prefix

Allocate IP

Prefix

IpAddress

Used by workloads

 \ No newline at end of file +

NetBox Database

Claim model allocation

NetBox Operator

Available prefix

Available IP

NetBox Operator

PrefixClaim

IpAddressClaim

Find parentPrefix

Allocate Prefix

Allocate IP

Prefix

IpAddress

Used by workloads

 \ No newline at end of file From 0a09672309d557b939705ec24735a6566920300b Mon Sep 17 00:00:00 2001 From: Pablo Garcia Miranda Date: Thu, 24 Apr 2025 07:43:27 +0100 Subject: [PATCH 05/10] Adding examples to operational-manual.md --- docs/operational-manual.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/operational-manual.md b/docs/operational-manual.md index 60ed76a8..b9162e5b 100644 --- a/docs/operational-manual.md +++ b/docs/operational-manual.md @@ -19,6 +19,13 @@ Inspect the CRs status: kubectl describe -n ``` +E.g.: +```bash +kubectl describe prefixclaim prefixclaim-sample -n +kubectl describe ipaddressclaim ipaddressclaim-sample -n +kubectl describe prefix prefix-sample -n +kubectl describe ipaddress ipaddress-sample -n +``` This will show you the status of the operator and any errors it may have encountered. ### Verify Operator Version From c711aaac02e5f7e12fa92110931b6e39d0ee07bf Mon Sep 17 00:00:00 2001 From: Pablo Garcia Miranda Date: Thu, 24 Apr 2025 16:04:56 +0200 Subject: [PATCH 06/10] Adding new diagram for representing the claim model --- README.md | 2 +- docs/netbox-operator-claim-model.drawio.svg | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 docs/netbox-operator-claim-model.drawio.svg diff --git a/README.md b/README.md index ea70006f..d4650d1d 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ This model ensures a declarative management of IP addressing and subnet allocati The users will create claims (PrefixClaims & IPAddressClaims), and the NetBox Operator will resolve them into actual Prefixes and IPAddresses within a designated parent prefix.

- +

# Mixed usage of Prefixes diff --git a/docs/netbox-operator-claim-model.drawio.svg b/docs/netbox-operator-claim-model.drawio.svg new file mode 100644 index 00000000..313163c2 --- /dev/null +++ b/docs/netbox-operator-claim-model.drawio.svg @@ -0,0 +1,4 @@ + + + +
k8s cluster
k8s cluster
user namespace
user namespace
NetBox REST API
NetBox REST API
namespace netbox-operator
namespace netbox-operator
reconcile
reconcile
create/update/delete
create/update/delete
create
create
reconcile
reconcile
create/update/delete
create/update/delete
get available prefixes
get available prefixes
netbox-operator
netbox-operator
kind: PrefixClaim
spec:
  parentPrefix: 2.0.0.0/16
  prefixLength: /28
status:
  prefix: 2.0.0.0/28
kind: PrefixClaim...
Prefix 2.0.0.0/16
Prefix 2.0.0.0/16
kind: Prefix
spec:
  prefix: 2.0.0.0/16
kind: Prefix...
reconcile
reconcile
update status
update status
kind: Prefix
spec:
  prefix: 2.0.0.0/28

kind: Prefix...
Prefix 2.0.0.0/28
Prefix 2.0.0.0/28Text is not SVG - cannot display \ No newline at end of file From b464367cbd45699120e09f98a8fc106ab1ee802e Mon Sep 17 00:00:00 2001 From: Pablo Garcia Miranda Date: Thu, 24 Apr 2025 16:05:43 +0200 Subject: [PATCH 07/10] Deleting old diagram --- docs/claim-model.svg | 1 - 1 file changed, 1 deletion(-) delete mode 100644 docs/claim-model.svg diff --git a/docs/claim-model.svg b/docs/claim-model.svg deleted file mode 100644 index 17b62619..00000000 --- a/docs/claim-model.svg +++ /dev/null @@ -1 +0,0 @@ -

NetBox Database

Claim model allocation

NetBox Operator

Available prefix

Available IP

NetBox Operator

PrefixClaim

IpAddressClaim

Find parentPrefix

Allocate Prefix

Allocate IP

Prefix

IpAddress

Used by workloads

 \ No newline at end of file From bb42018a2eab7e85c66b2dbd786504a4738ac4a2 Mon Sep 17 00:00:00 2001 From: Pablo Garcia Miranda Date: Fri, 25 Apr 2025 10:52:54 +0200 Subject: [PATCH 08/10] Updating diagram --- README.md | 2 +- docs/netbox-operator-claim-model.drawio.svg | 4 - ...perator-high-level-architecture.drawio.svg | 461 +----------------- 3 files changed, 5 insertions(+), 462 deletions(-) delete mode 100644 docs/netbox-operator-claim-model.drawio.svg diff --git a/README.md b/README.md index d4650d1d..d4742abb 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ This model ensures a declarative management of IP addressing and subnet allocati The users will create claims (PrefixClaims & IPAddressClaims), and the NetBox Operator will resolve them into actual Prefixes and IPAddresses within a designated parent prefix.

- +

# Mixed usage of Prefixes diff --git a/docs/netbox-operator-claim-model.drawio.svg b/docs/netbox-operator-claim-model.drawio.svg deleted file mode 100644 index 313163c2..00000000 --- a/docs/netbox-operator-claim-model.drawio.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - -
k8s cluster
k8s cluster
user namespace
user namespace
NetBox REST API
NetBox REST API
namespace netbox-operator
namespace netbox-operator
reconcile
reconcile
create/update/delete
create/update/delete
create
create
reconcile
reconcile
create/update/delete
create/update/delete
get available prefixes
get available prefixes
netbox-operator
netbox-operator
kind: PrefixClaim
spec:
  parentPrefix: 2.0.0.0/16
  prefixLength: /28
status:
  prefix: 2.0.0.0/28
kind: PrefixClaim...
Prefix 2.0.0.0/16
Prefix 2.0.0.0/16
kind: Prefix
spec:
  prefix: 2.0.0.0/16
kind: Prefix...
reconcile
reconcile
update status
update status
kind: Prefix
spec:
  prefix: 2.0.0.0/28

kind: Prefix...
Prefix 2.0.0.0/28
Prefix 2.0.0.0/28Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/netbox-operator-high-level-architecture.drawio.svg b/docs/netbox-operator-high-level-architecture.drawio.svg index 55a08d29..62fcb76f 100644 --- a/docs/netbox-operator-high-level-architecture.drawio.svg +++ b/docs/netbox-operator-high-level-architecture.drawio.svg @@ -1,457 +1,4 @@ - - - - - - - - -
-
-
- k8s cluster -
-
-
- - - k8s cluster - - - - - - - - -
-
-
- user namespace -
-
-
- - - user namespace - - - - - - - - - -
-
-
- consumer -
-
-
- - - consumer - - - - - - - -
-
-
- NetBox REST API -
-
-
- - - NetBox REST API - - - - - - - -
-
-
- namespace netbox-operator -
-
-
- - - namespace netbox-operator - - - - - - - - -
-
-
- reconcile -
-
-
- - - reconcile - - - - - - - - -
-
-
- create/update/delete -
-
-
- - - create/update/delete - - - - - - - - -
-
-
- create -
-
-
- - - create - - - - - - - - -
-
-
- reconcile -
-
-
- - - reconcile - - - - - - - - -
-
-
- create/update/delete -
-
-
- - - create/update/delete - - - - - - - - -
-
-
- get available prefixes -
-
-
- - - get available prefixes - - - - - - - -
-
-
- netbox-operator -
-
-
- - - netbox-operator - - - - - - - -
-
-
-
- kind: PrefixClaim -
-
- spec: -
-
- parentPrefix: 2.0.0.0/16 -
-
- prefixLength: /28 -
-
-
-
-
- - - kind: PrefixClaim... - - - - - - - -
-
-
- Prefix 2.0.0.0/16 -
-
-
- - - Prefix 2.0.0.0/16 - - - - - - - - -
-
-
- User -
- w/ kubectl -
-
-
- - - User... - - - - - - - - -
-
-
- GitOps -
- w/ Argo or Flux -
-
-
- - - GitOps... - - - - - - - -
-
-
- and/or -
-
-
- - - and/or - - - - - - - -
-
-
-
- kind: Prefix -
-
- spec: -
-
- prefix: 2.0.0.0/16 -
-
-
-
-
- - - kind: Prefix... - - - - - - - - -
-
-
- reconcile -
-
-
- - - reconcile - - - - - - - - -
-
-
- ownerReference -
-
-
- - - ownerReference - - - - - - - -
-
-
-
- kind: Prefix -
-
- spec: -
-
- prefix: 2.0.0.0/28 -
-
-
-
-
-
-
- - - kind: Prefix... - - - - - - - -
-
-
- Prefix 2.0.0.0/28 -
-
-
- - - Prefix 2.0.0.0/28 - - - - - - - - -
-
-
- create/sync -
-
-
- - - create/sync - - - - - - - - - - - Text is not SVG - cannot display - - - - + + + +
k8s cluster
user namespace
consumer
NetBox REST API
namespace netbox-operator
reconcile
create/update/delete
create
reconcile
create/update/delete
get available prefixes
netbox-operator
kind: PrefixClaim
spec:
  parentPrefix: 2.0.0.0/16
  prefixLength: /28
status:
  prefix: 2.0.0.0/28
Prefix 2.0.0.0/16
User
w/ kubectl
GitOps
w/ Argo or Flux
and/or
kind: Prefix
spec:
  prefix: 2.0.0.0/16
reconcile
update status
(ownerReference)
kind: Prefix
spec:
  prefix: 2.0.0.0/28

Prefix 2.0.0.0/28
create/sync
 image/svg+xml \ No newline at end of file From fb46f293776d5a2b869d4dadf6cb6a0443e26096 Mon Sep 17 00:00:00 2001 From: Pablo Garcia Miranda Date: Mon, 28 Apr 2025 12:55:08 +0200 Subject: [PATCH 09/10] Moving up in the README.md "The Claim Model" --- README.md | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index d4742abb..0b3cf0bf 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,14 @@ NetBox Operator extends the Kubernetes API by allowing users to manage NetBox resources – such as IP addresses and prefixes – directly through Kubernetes. This integration brings Kubernetes-native features like reconciliation, ensuring that network configurations are maintained automatically, thereby improving both efficiency and reliability. +## The Claim Model +The NetBox Operator implements a "Claim Model" which is also used in the Kubernetes PersistentVolumeClaims (PVCs). +In this case, instead of disk storage, NetBox Operator dynamically allocates network resources (Prefixes and IP Addresses) based on claims submitted via custom resources. + +### Purpose +This model ensures a declarative management of IP addressing and subnet allocation, with full NetBox integration. +The users will create claims (PrefixClaims & IPAddressClaims), and the NetBox Operator will resolve them into actual Prefixes and IPAddresses within a designated parent prefix. + ![Figure 1: NetBox Operator High-Level Architecture](docs/netbox-operator-high-level-architecture.drawio.svg) # Getting Started @@ -63,18 +71,6 @@ for i in {001..100}; do done ``` -# The Claim Model -The NetBox Operator implements a "Claim Model" which is also used in the Kubernetes PersistentVolumeClaims (PVCs). -In this case, instead of disk storage, NetBox Operator dynamically allocates network resources (Prefixes and IP Addresses) based on claims submitted via custom resources. - -## Purpose -This model ensures a declarative management of IP addressing and subnet allocation, with full NetBox integration. -The users will create claims (PrefixClaims & IPAddressClaims), and the NetBox Operator will resolve them into actual Prefixes and IPAddresses within a designated parent prefix. - -

- -

- # Mixed usage of Prefixes Note that NetBox does handle the Address management of Prefixes separately from IP Ranges and IP Addresses. This is important to know when you plan to use the same NetBox Prefix as a parentPrefix for your IpAddressClaims, IpRangeClaims and PrefixClaims. From abd9170cf8b4d0e3d466f415db898588004f8994 Mon Sep 17 00:00:00 2001 From: Pablo Garcia Miranda Date: Mon, 28 Apr 2025 12:58:31 +0200 Subject: [PATCH 10/10] Updating SVG to match light backgrounds --- ...prefixclaim-sample-with-netbox-running-in-cluster.drawio.svg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/prefixclaim-sample-with-netbox-running-in-cluster.drawio.svg b/docs/prefixclaim-sample-with-netbox-running-in-cluster.drawio.svg index 99cd828a..5118715c 100644 --- a/docs/prefixclaim-sample-with-netbox-running-in-cluster.drawio.svg +++ b/docs/prefixclaim-sample-with-netbox-running-in-cluster.drawio.svg @@ -1,4 +1,4 @@ -
k8s cluster
k8s cluster
namespace default
namespace default
user namespace
user namespace
namespace netbox-operator
namespace netbox-operator
create
create
reconcile
reconcile
netbox-operator
netbox-operator
reconcile
reconcile
ownerReference
ownerReference
kind: Prefix
spec:
  prefix: 2.0.0.0/28
kind: Prefix...
NetBox REST API
NetBox REST API
create/update/delete
create/update/delete
get available prefixes
get available prefixes
Prefix 2.0.0.0/16
Prefix 2.0.0.0/16
Prefix 2.0.0.0/28
Prefix 2.0.0.0/28
kind: MetalLBIPPoolNetBox (kro )
spec:
  parentPrefix: 2.0.0.0/16
  prefixLength: /28
kind: MetalLBIPPoolNetBox (kro )...
kind: PrefixClaim
spec:
  parentPrefix: 2.0.0.0/16
  prefixLength: /28
status:
  ipAddress:
kind: PrefixClaim...
kind: IPAddressPool
spec:
  parentPrefix: 2.0.0.0/16
  prefixLength: /28
kind: IPAddressPool...Text is not SVG - cannot display \ No newline at end of file +
k8s cluster
namespace default
user namespace
namespace netbox-operator
create
reconcile
netbox-operator
reconcile
ownerReference
kind: Prefix
spec:
  prefix: 2.0.0.0/28
 image/svg+xml
NetBox REST API
create/update/delete
get available prefixes
Prefix 2.0.0.0/16
Prefix 2.0.0.0/28
kind: MetalLBIPPoolNetBox (kro )
spec:
  parentPrefix: 2.0.0.0/16
  prefixLength: /28
kind: PrefixClaim
spec:
  parentPrefix: 2.0.0.0/16
  prefixLength: /28
status:
  ipAddress:
kind: IPAddressPool
spec:
  parentPrefix: 2.0.0.0/16
  prefixLength: /28
 \ No newline at end of file