Skip to content

Commit 57c7e61

Browse files
jstudlerjstudler
authored
Improve documention (#263)
- Add more verbose CRD documentation - Add Installation methods - Add notes on Mixed usage of Prefixes - Add FAQ Fixes #128
1 parent 7bcbe12 commit 57c7e61

15 files changed

+603
-123
lines changed

‎README.md

+40
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,15 @@ NetBox Operator extends the Kubernetes API by allowing users to manage NetBox re
1717
- kind
1818
- docker cli
1919

20+
## Installation methods
21+
22+
There are several ways to install NetBox Operator on your Cluster:
23+
24+
- NetBox Operator Helm Chart. More information: <https://github.com/netbox-community/netbox-chart/>
25+
- Manifests in <config/default> of this repo. Make sure to first set the correct image using `kustomize edit set image controller=<correctimage>`. Images can be found on the Releases page on GitHub
26+
- The Makefile targets in this repository.
27+
- For debugging and developing, please read further below.
28+
2029
# How to use NetBox Operator
2130

2231
## Running both NetBox Operator and NetBox on a local kind cluster
@@ -46,6 +55,25 @@ Example of assigning a Prefix using PrefixClaim:
4655

4756
Key information can be found in the yaml formatted output of these resources, as well as in the events and Operator logs.
4857

58+
# Mixed usage of Prefixes
59+
60+
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.
61+
62+
Example:
63+
64+
- Assume you use an existing empty NetBox Prefix "192.168.0.0/24" as the `.spec.parentPrefix` for your PrefixClaims, IpAddressClaims and IpRangeClaims.
65+
- You create a PrefixClaim with `.spec.prefixLength` of `/25`, NetBox Operator will assign "192.168.0.0/25"
66+
- You create a IpAddressClaim, NetBox Operator will assign "192.168.0.1/32". Important: NetBox ignores the Prefix in that case and will not return "192.168.0.129" as the first available IP!
67+
- You create a IpAddressClaim with `.spec.size` of `2`, NetBox Operator will assign "192.168.0.2/32" to "192.168.0.3/32". Important: NetBox ignores the Prefix in that case and will not return "192.168.0.129" as the first available IP!
68+
69+
70+
This means that you need to plan your automation carefully. As a rule of thumb:
71+
- If you plan mixed use of the same parentPrefix for both single IPs (/32s) as well as Prefixes (non /32s), use PrefixClaims for everything and avoid using IpRangeClaims and IpAddressClaims.
72+
- If you are in full control of a Prefix and you know it will only be used for assigning IP Addresses and IP Ranges, you can use IpAddressClaims and IpRangeClaims.
73+
- If you don't know what the parentPrefix is used for, avoid using IpAddressClaims and IpRangeClaims.
74+
75+
The same applies if you use parentPrefixSelector with PrefixClaims. The above example is IPv4 based but will be the same with IPv6 equivalents.
76+
4977
# Restoration from NetBox
5078

5179
In the case that the cluster containing the NetBox Custom Resources managed by this NetBox Operator is not backed up (e.g. using Velero), we need to be able to restore some information from NetBox. This includes two mechanisms implemented in this NetBox Operator:
@@ -97,6 +125,18 @@ For the monitoring of the state of the CRs reconciled by the operator [kube stat
97125

98126
[kube state metrics]: https://github.com/kubernetes/kube-state-metrics
99127

128+
# FAQ
129+
130+
## What is the difference between `.spec.customFields` and `.spec.parentPrefixSelector`?
131+
132+
`.spec.customFields` are the NetBox Custom Fields assigned to the resource in NetBox.
133+
`.spec.parentPrefixSelector` is used by a Claim Controller (e.g. the controller of PrefixClaim) to find a suitable Prefix to get e.g. a Prefix from.
134+
135+
## What is the difference between `.spec.tenant` and `.spec.parentPrefixSelector.tenant`?
136+
137+
`.spec.tenant` is the tenant that is assigned to the resource in NetBox.
138+
`.spec.parentPrefixSelector.tenant` is used by a Claim Controller (e.g. the controller of PrefixClaim) to find a suitable Prefix to get e.g. a Prefix from.
139+
100140
# Contributing
101141

102142
We cordially invite collaboration from the community to enhance the quality and functionality of this project. Whether you are addressing bugs, introducing new features, refining documentation, or assisting with items on our to-do list, your contributions are highly valued and greatly appreciated. Please take a look at [Contribution guide] for more details.

‎api/v1/ipaddress_types.go

+33-9
Original file line numberDiff line numberDiff line change
@@ -20,39 +20,63 @@ import (
2020
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
2121
)
2222

23-
// EDIT THIS FILE! THIS IS SCAFFOLDING FOR YOU TO OWN!
24-
// NOTE: json tags are required. Any new fields you add must have json tags for the fields to be serialized.
25-
2623
// IpAddressSpec defines the desired state of IpAddress
2724
type IpAddressSpec struct {
28-
// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
29-
// Important: Run "make" to regenerate code after modifying this file
30-
25+
// The IP Address in CIDR notation that should be reserved in NetBox
26+
// Field is immutable, required
27+
// Example: "192.168.0.1/32"
3128
//+kubebuilder:validation:Format=cidr
3229
//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="Field 'ipAddress' is immutable"
3330
//+kubebuilder:validation:Required
3431
IpAddress string `json:"ipAddress"`
3532

33+
// The NetBox Tenant to be assigned to this resource in NetBox. Use the `name` value instead of the `slug` value
34+
// Field is immutable, not required
35+
// Example: "Initech" or "Cyberdyne Systems"
3636
//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="Field 'tenant' is immutable"
3737
Tenant string `json:"tenant,omitempty"`
3838

39+
// The NetBox Custom Fields that should be added to the resource in NetBox.
40+
// Note that currently only Text Type is supported (GitHub #129)
41+
// More info on NetBox Custom Fields:
42+
// https://github.com/netbox-community/netbox/blob/main/docs/customization/custom-fields.md
43+
// Field is mutable, not required
44+
// Example:
45+
// customfield1: "Production"
46+
// customfield2: "This is a string"
3947
CustomFields map[string]string `json:"customFields,omitempty"`
4048

49+
// Comment that should be added to the resource in NetBox
50+
// Field is mutable, not required
4151
Comments string `json:"comments,omitempty"`
4252

53+
// Description that should be added to the resource in NetBox
54+
// Field is mutable, not required
4355
Description string `json:"description,omitempty"`
4456

57+
// Defines whether the Resource should be preserved in NetBox when the
58+
// Kubernetes Resource is deleted.
59+
// - When set to true, the resource will not be deleted but preserved in
60+
// NetBox upon CR deletion
61+
// - When set to false, the resource will be cleaned up in NetBox
62+
// upon CR deletion
63+
// Setting preserveInNetbox to true is mandatory if the user wants to restore
64+
// resources from NetBox (e.g. Sticky CIDRs even if resources are deleted and
65+
// recreated in Kubernetes)
66+
// Field is mutable, not required
4567
PreserveInNetbox bool `json:"preserveInNetbox,omitempty"`
4668
}
4769

4870
// IpAddressStatus defines the observed state of IpAddress
4971
type IpAddressStatus struct {
50-
// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
51-
// Important: Run "make" to regenerate code after modifying this file
72+
// The ID of the resource in NetBox
5273
IpAddressId int64 `json:"id,omitempty"`
5374

75+
// The URL to the resource in the NetBox UI. Note that the base of this
76+
// URL depends on the runtime config of NetBox Operator
5477
IpAddressUrl string `json:"url,omitempty"`
5578

79+
// Conditions represent the latest available observations of an object's state
5680
Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`
5781
}
5882

@@ -66,7 +90,7 @@ type IpAddressStatus struct {
6690
//+kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
6791
// +kubebuilder:resource:shortName=ip
6892

69-
// IpAddress is the Schema for the ipaddresses API
93+
// IpAddress allows to create a NetBox IP Address. More info about NetBox IP Addresses: https://github.com/netbox-community/netbox/blob/main/docs/models/ipam/ipaddress.md
7094
type IpAddress struct {
7195
metav1.TypeMeta `json:",inline"`
7296
metav1.ObjectMeta `json:"metadata,omitempty"`

‎api/v1/ipaddressclaim_types.go

+37-10
Original file line numberDiff line numberDiff line change
@@ -20,42 +20,65 @@ import (
2020
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
2121
)
2222

23-
// EDIT THIS FILE! THIS IS SCAFFOLDING FOR YOU TO OWN!
24-
// NOTE: json tags are required. Any new fields you add must have json tags for the fields to be serialized.
25-
2623
// IpAddressClaimSpec defines the desired state of IpAddressClaim
2724
type IpAddressClaimSpec struct {
28-
// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
29-
// Important: Run "make" to regenerate code after modifying this file
30-
25+
// The NetBox Prefix from which this IP Address should be claimed from
26+
// Field is immutable, required
27+
// Example: "192.168.0.0/20"
3128
//+kubebuilder:validation:Required
3229
//+kubebuilder:validation:Format=cidr
3330
//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="Field 'parentPrefix' is immutable"
3431
ParentPrefix string `json:"parentPrefix"`
3532

33+
// The NetBox Tenant to be assigned to this resource in NetBox. Use the `name` value instead of the `slug` value
34+
// Field is immutable, not required
35+
// Example: "Initech" or "Cyberdyne Systems"
3636
//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="Field 'tenant' is immutable"
3737
Tenant string `json:"tenant,omitempty"`
3838

39+
// The NetBox Custom Fields that should be added to the resource in NetBox.
40+
// Note that currently only Text Type is supported (GitHub #129)
41+
// More info on NetBox Custom Fields:
42+
// https://github.com/netbox-community/netbox/blob/main/docs/customization/custom-fields.md
43+
// Field is mutable, not required
44+
// Example:
45+
// customfield1: "Production"
46+
// customfield2: "This is a string"
3947
CustomFields map[string]string `json:"customFields,omitempty"`
4048

49+
// Comment that should be added to the resource in NetBox
50+
// Field is mutable, not required
4151
Comments string `json:"comments,omitempty"`
4252

53+
// Description that should be added to the resource in NetBox
54+
// Field is mutable, not required
4355
Description string `json:"description,omitempty"`
4456

57+
// Defines whether the Resource should be preserved in NetBox when the
58+
// Kubernetes Resource is deleted.
59+
// - When set to true, the resource will not be deleted but preserved in
60+
// NetBox upon CR deletion
61+
// - When set to false, the resource will be cleaned up in NetBox
62+
// upon CR deletion
63+
// Setting preserveInNetbox to true is mandatory if the user wants to restore
64+
// resources from NetBox (e.g. Sticky CIDRs even if resources are deleted and
65+
// recreated in Kubernetes)
66+
// Field is mutable, not required
4567
PreserveInNetbox bool `json:"preserveInNetbox,omitempty"`
4668
}
4769

4870
// IpAddressClaimStatus defines the observed state of IpAddressClaim
4971
type IpAddressClaimStatus struct {
50-
// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
51-
// Important: Run "make" to regenerate code after modifying this file
52-
72+
// The assigned IP Address in CIDR notation
5373
IpAddress string `json:"ipAddress,omitempty"`
5474

75+
// The assigned IP Address in Dot Decimal notation
5576
IpAddressDotDecimal string `json:"ipAddressDotDecimal,omitempty"`
5677

78+
// The name of the IpAddress CR created by the IpAddressClaim Controller
5779
IpAddressName string `json:"ipAddressName,omitempty"`
5880

81+
// Conditions represent the latest available observations of an object's state
5982
Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`
6083
}
6184

@@ -68,7 +91,11 @@ type IpAddressClaimStatus struct {
6891
//+kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
6992
// +kubebuilder:resource:shortName=ipc
7093

71-
// IpAddressClaim is the Schema for the ipaddressclaims API
94+
// IpAddressClaim allows to claim a NetBox IP Address from an existing Prefix.
95+
// The IpAddressClaim Controller will try to assign an available IP Address
96+
// from the Prefix that is defined in the spec and if successful it will create
97+
// the IpAddress CR. More info about NetBox IP Addresses:
98+
// https://github.com/netbox-community/netbox/blob/main/docs/models/ipam/ipaddress.md
7299
type IpAddressClaim struct {
73100
metav1.TypeMeta `json:",inline"`
74101
metav1.ObjectMeta `json:"metadata,omitempty"`

‎api/v1/iprange_types.go

+36-6
Original file line numberDiff line numberDiff line change
@@ -20,41 +20,71 @@ import (
2020
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
2121
)
2222

23-
// EDIT THIS FILE! THIS IS SCAFFOLDING FOR YOU TO OWN!
24-
// NOTE: json tags are required. Any new fields you add must have json tags for the fields to be serialized.
25-
2623
// IpRangeSpec defines the desired state of IpRange
2724
type IpRangeSpec struct {
28-
// the startAddress is the first ip address included in the ip range
25+
// The first IP in CIDR notation that should be included in the NetBox IP Range
26+
// Field is immutable, required
27+
// Example: "192.168.0.1/32"
2928
//+kubebuilder:validation:Format=cidr
3029
//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="Field 'startAddress' is immutable"
3130
//+kubebuilder:validation:Required
3231
StartAddress string `json:"startAddress"`
3332

34-
// the endAddress is the last ip address included in the ip range
33+
// The last IP in CIDR notation that should be included in the NetBox IP Range
34+
// Field is immutable, required
35+
// Example: "192.168.0.20/32"
3536
//+kubebuilder:validation:Format=cidr
3637
//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="Field 'endAddress' is immutable"
3738
//+kubebuilder:validation:Required
3839
EndAddress string `json:"endAddress"`
3940

41+
// The NetBox Tenant to be assigned to this resource in NetBox. Use the `name` value instead of the `slug` value
42+
// Field is immutable, not required
43+
// Example: "Initech" or "Cyberdyne Systems"
4044
//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="Field 'tenant' is immutable"
4145
Tenant string `json:"tenant,omitempty"`
4246

47+
// The NetBox Custom Fields that should be added to the resource in NetBox.
48+
// Note that currently only Text Type is supported (GitHub #129)
49+
// More info on NetBox Custom Fields:
50+
// https://github.com/netbox-community/netbox/blob/main/docs/customization/custom-fields.md
51+
// Field is mutable, not required
52+
// Example:
53+
// customfield1: "Production"
54+
// customfield2: "This is a string"
4355
CustomFields map[string]string `json:"customFields,omitempty"`
4456

57+
// Comment that should be added to the resource in NetBox
58+
// Field is mutable, not required
4559
Comments string `json:"comments,omitempty"`
4660

61+
// Description that should be added to the resource in NetBox
62+
// Field is mutable, not required
4763
Description string `json:"description,omitempty"`
4864

65+
// Defines whether the Resource should be preserved in NetBox when the
66+
// Kubernetes Resource is deleted.
67+
// - When set to true, the resource will not be deleted but preserved in
68+
// NetBox upon CR deletion
69+
// - When set to false, the resource will be cleaned up in NetBox
70+
// upon CR deletion
71+
// Setting preserveInNetbox to true is mandatory if the user wants to restore
72+
// resources from NetBox (e.g. Sticky CIDRs even if resources are deleted and
73+
// recreated in Kubernetes)
74+
// Field is mutable, not required
4975
PreserveInNetbox bool `json:"preserveInNetbox,omitempty"`
5076
}
5177

5278
// IpRangeStatus defines the observed state of IpRange
5379
type IpRangeStatus struct {
80+
// The ID of the resource in NetBox
5481
IpRangeId int64 `json:"id,omitempty"`
5582

83+
// The URL to the resource in the NetBox UI. Note that the base of this
84+
// URL depends on the runtime config of NetBox Operator
5685
IpRangeUrl string `json:"url,omitempty"`
5786

87+
// Conditions represent the latest available observations of an object's state
5888
Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`
5989
}
6090

@@ -69,7 +99,7 @@ type IpRangeStatus struct {
6999
//+kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
70100
// +kubebuilder:resource:shortName=ipr
71101

72-
// IpRange is the Schema for the ipranges API
102+
// IpRange allows to create a NetBox IP Range. More info about NetBox IP Ranges: https://github.com/netbox-community/netbox/blob/main/docs/models/ipam/iprange.md
73103
type IpRange struct {
74104
metav1.TypeMeta `json:",inline"`
75105
metav1.ObjectMeta `json:"metadata,omitempty"`

0 commit comments

Comments
 (0)