Add examples

.gitignore

@@ -29,5 +29,9 @@ go.work
 *.swp
 *.swo
 *~
-.drawio.dtmp
+*.drawio.dtmp
+*drawio.svg.bkp
 .DS_Store
+
+# Temporary files
+tmp

README.md

@@ -55,6 +55,14 @@ Example of assigning a Prefix using PrefixClaim:
 
 Key information can be found in the yaml formatted output of these resources, as well as in the events and Operator logs.
 
+To test at scale, you can use yq to patch the Kubernetes manifests. The following is an example to create 100 IpAddressClaims based on the sample yaml file:
+
+```bash
+for i in {001..100}; do
+  name="ipc-${i}" yq e '.metadata.name=strenv(name)' config/samples/netbox_v1_ipaddressclaim.yaml | kubectl apply -f -
+done
+```
+
 # 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.

docs/examples/README.md

@@ -0,0 +1,13 @@
+# NetBox Operator Examples
+
+This folder shows some examples how the NetBox Operator can be used.
+
+Each example folder contains a README.md which explains how you can set up your local enviroment to step through the examples.
+
+Prerequisites:
+- go version v1.24.0+
+- docker image netbox-operatore:build-local
+- kustomize version v5.5.0+
+- kubectl version v1.32.2+
+- kind v0.27.0
+- docker cli

docs/examples/example1-getting-started/README.md

@@ -0,0 +1,64 @@
+# Example 1: Getting Started
+
+# 0.1 Create a local cluster with nebox-installed
+
+1. use the 'create-kind' and 'deploy-kind' targets from the Makefile to create a kind cluster and deploy NetBox and NetBox Operator on it
+```bash
+make create-kind
+make deploy-kind
+```
+
+# 0.2 Manually Create a Prefix in NetBox
+
+Before prefixes and ip addresses can be claimed with the NetBox operator, a prefix has to be created in NetBox.
+
+1. Port-forward NetBox:
+```bash
+kubectl port-forward deploy/netbox 8080:8080
+```
+2. Open <http://localhost:8080> in your favorite browser and log in with the username `admin` and password `admin`
+3. Create a new prefix '3.0.0.64/26' with custom field 'environment: prod'
+
+# 0.3 Navigate to the example folder
+
+Navigate to 'docs/examples/example1-getting-started' to run the examples below
+
+# 1.1 Claim a Prefix
+
+In this example, we use a `.spec.parentPrefix` that we know in advance. This is useful if you already know exactly from which prefix you want to claim from.
+
+1. Inspect the spec of the sample prefix claim CR
+```bash
+cat prefixclaim-simple.yaml
+```
+2. Apply  the manifest defining the prefix claim
+```bash
+kubectl apply  -f prefixclaim-simple.yaml
+```
+3. Check that the prefix claim CR got a prefix assigned
+```bash
+kubectl get  pxc,px
+```
+
+![Example 1.1](prefixclaim-simple.drawio.svg)
+
+# 1.2 Dynamically Claim a Prefix with a Parent Prefix Selector
+
+In this example, we use a `.spec.parentPrefixSelector`, which is a list of selectors that tell NetBox Operator from which parent prefixes to claim our Prefix from.
+
+Navigate to 'docs/examples/example1-getting-started' to run the following commands.
+
+1. Inspect the spec of the sample prefix claim CR
+```bash
+cat prefixclaim-dynamic.yaml
+```
+2. Apply  the manifest defining the prefix claim
+```bash
+kubectl apply   -f prefixclaim-dynamic.yaml
+```
+3. Check that the prefix claim CR got a prefix addigned
+```bash
+kubectl get  pxc,px
+```
+
+![Example 1.2](prefixclaim-dynamic.drawio.svg)

docs/examples/example1-getting-started/prefixclaim-dynamic.yaml

@@ -0,0 +1,13 @@
+apiVersion: netbox.dev/v1
+kind: PrefixClaim
+metadata:
+  labels:
+    app.kubernetes.io/name: netbox-operator
+    app.kubernetes.io/managed-by: kustomize
+  name: dynamic-prefix-claim
+spec:
+  tenant: "MY_TENANT"
+  parentPrefixSelector:
+    environment: prod
+    family: IPv4
+  prefixLength: "/30"

docs/examples/example1-getting-started/prefixclaim-simple.yaml

@@ -0,0 +1,11 @@
+apiVersion: netbox.dev/v1
+kind: PrefixClaim
+metadata:
+  labels:
+    app.kubernetes.io/name: netbox-operator
+    app.kubernetes.io/managed-by: kustomize
+  name: simple-prefixclaim
+spec:
+  tenant: "MY_TENANT"
+  parentPrefix: 3.0.0.64/26
+  prefixLength: "/30"

docs/examples/example2-load-balancer-ip/README.md

@@ -0,0 +1,68 @@
+# Example 2: Glue NetBox CRs to MetalLB CRs
+
+## Introduction
+
+So we have Prefixes represented as Kubernetes Resources. Now what can we do with this?
+
+We use kro.run to glue this to MetalLB IPAddressPools
+
+### 0.1 Create a local cluster with nebox-installed
+
+1. use the 'create-kind' and 'deploy-kind' targets from the Makefile to create a kind cluster and deploy NetBox and NetBox Operator on it
+```bash
+make create-kind
+make deploy-kind
+```
+
+### 0.2 Manually Create a Prefix in NetBox
+
+Before prefixes and ip addresses can be claimed with the NetBox operator, a prefix has to be created in NetBox.
+
+1. Port-forward NetBox:
+```bash
+kubectl port-forward deploy/netbox 8080:8080
+```
+2. Open <http://localhost:8080> in your favorite browser and log in with the username `admin` and password `admin`
+3. Create a new prefix '3.0.0.64/26' with custom field 'environment: prod'
+
+### 0.3 Navigate to the example folder
+
+Navigate to 'docs/examples/example2-load-balancer-ip/' to run the examples below
+
+## Example Steps
+
+0. Install kro and metallb with the installation script `docs/examples/example2-load-balancer-ip/prepare-demo-env.sh`
+Then navigate to 'docs/examples/example2-load-balancer-ip' to follow the steps below.
+
+1. Inspect the spec of the sample prefix claim CR
+```bash
+cat zurich-pool.yaml
+```
+2. Apply the manifests to create a deployment with a service and a metallb-ip-address-pool-netbox to create a metalLB IPAddressPool from the prefix claimed from NetBox
+```bash
+kubectl apply -f zurich-pool.yaml
+```
+3. Check if the prefixclaim CR and the metalLB ipaddresspool CR got created
+```bash
+kubectl get pxc,ipaddresspool -A
+```
+4. Inspect the spec of the sample prefix claim CR
+```bash
+cat sample-deployment.yaml
+```
+5. Apply the manifests to createa deployment with a service that gets a ip assigned from the metalLB pool created in the prevoius step
+```bash
+kubectl apply -f sample-deployment.yaml
+```
+6. check if the service got an external ip address assigned and that the nginx deployment is ready
+```bash
+kubectl get deploy,svc -n nginx
+```
+7. try to connect to your service with the external ip
+```bash
+k exec curl -it -- sh
+curl <external-ip>
+```
+
+
+![Example 2](metallb-ipaddresspool-netbox.drawio.svg)

docs/examples/example2-load-balancer-ip/load-balancer-ip-pool-netbox.yaml

@@ -0,0 +1,39 @@
+apiVersion: kro.run/v1alpha1
+kind: ResourceGraphDefinition
+metadata:
+  name: load-balancer-ip-pool-netbox
+spec:
+  schema:
+    apiVersion: v1alpha1
+    kind: LoadBalancerIPPoolNetBox
+    spec:
+      name: string
+      tenant: string
+      prefixLength: string
+      parentPrefixSelector:
+        environment: string
+        family: string
+    status:
+
+  # Define the resources this API will manage.
+  resources:
+    - id: prefixclaim
+      template:
+        apiVersion: netbox.dev/v1
+        kind: PrefixClaim
+        metadata:
+          name: ${schema.spec.name}
+        spec:
+          prefixLength: ${schema.spec.prefixLength}
+          parentPrefixSelector: ${schema.spec.parentPrefixSelector}
+
+    - id: ipaddresspool
+      template:
+        apiVersion: metallb.io/v1beta1
+        kind: IPAddressPool
+        metadata:
+          name: ${schema.spec.name}
+          namespace: metallb-system
+        spec:
+          addresses:
+            - ${prefixclaim.status.prefix}