Skip to content

Commit 534c9bc

Browse files
jstudlerjstudler
committed
Add docs for IpAddress and IpAddressClaim
1 parent 0f238fd commit 534c9bc

File tree

4 files changed

+102
-43
lines changed

4 files changed

+102
-43
lines changed

‎api/v1/ipaddress_types.go

+19-17
Original file line numberDiff line numberDiff line change
@@ -20,25 +20,22 @@ 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
3126
//+kubebuilder:validation:Format=cidr
3227
//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="Field 'ipAddress' is immutable"
3328
//+kubebuilder:validation:Required
34-
// The actual IP Address that should be reserved in NetBox
3529
IpAddress string `json:"ipAddress"`
3630

37-
//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="Field 'tenant' is immutable"
3831
// The NetBox Tenant to be used for creating this resource in Netbox
32+
//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="Field 'tenant' is immutable"
3933
Tenant string `json:"tenant,omitempty"`
4034

41-
// NetBox Custom Fields that should be added to the resource in NetBox. Note that currently only Text Type is supported (GitHub #129)
35+
// The NetBox Custom Fields that should be added to the resource in NetBox.
36+
// Note that currently only Text Type is supported (GitHub #129)
37+
// More info on NetBox Custom Fields:
38+
// https://github.com/netbox-community/netbox/blob/main/docs/customization/custom-fields.md
4239
CustomFields map[string]string `json:"customFields,omitempty"`
4340

4441
// Comment that should be added to the resource in NetBox
@@ -47,23 +44,28 @@ type IpAddressSpec struct {
4744
// Description that should be added to the resource in NetBox
4845
Description string `json:"description,omitempty"`
4946

50-
// preserveInNetbox defines whether or not the Resource should stay in NetBox when the Kubernetes Resource is deleted
51-
// When set to true, the resource will not be deleted in NetBox upon CR deletion
52-
// When set to false, the resource will be cleaned up in NetBox upon CR deletion
53-
// If you want to restore resources from NetBox (e.g. recreation of an entire cluster), preserveInNetbox set to true is a prerequisite.
47+
// Defines whether the Resource should be preserved in NetBox when the
48+
// Kubernetes Resource is deleted.
49+
// - When set to true, the resource will not be deleted but preserved in
50+
// NetBox upon CR deletion
51+
// - When set to false, the resource will be cleaned up in NetBox
52+
// upon CR deletion
53+
// Setting preserveInNetbox to true is mandatory if the user wants to restore
54+
// resources from NetBox (e.g. Sticky CIDRs even if resources are deleted and
55+
// recreated in Kubernetes)
5456
PreserveInNetbox bool `json:"preserveInNetbox,omitempty"`
5557
}
5658

5759
// IpAddressStatus defines the observed state of IpAddress
5860
type IpAddressStatus struct {
59-
// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
60-
// Important: Run "make" to regenerate code after modifying this file
6161
// The ID of the resource in NetBox
6262
IpAddressId int64 `json:"id,omitempty"`
6363

64-
// The URL to the NetBox UI to display this resource. Note that the base depends on the runtime config of NetBox Operator
64+
// The URL to the resource in the NetBox UI. Note that the base of this
65+
// URL depends on the runtime config of NetBox Operator
6566
IpAddressUrl string `json:"url,omitempty"`
6667

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

@@ -77,7 +79,7 @@ type IpAddressStatus struct {
7779
//+kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
7880
// +kubebuilder:resource:shortName=ip
7981

80-
// IpAddress is the Schema for the ipaddresses API
82+
// 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
8183
type IpAddress struct {
8284
metav1.TypeMeta `json:",inline"`
8385
metav1.ObjectMeta `json:"metadata,omitempty"`

‎api/v1/ipaddressclaim_types.go

+26-10
Original file line numberDiff line numberDiff line change
@@ -20,42 +20,54 @@ 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
3126
//+kubebuilder:validation:Required
3227
//+kubebuilder:validation:Format=cidr
3328
//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="Field 'parentPrefix' is immutable"
3429
ParentPrefix string `json:"parentPrefix"`
3530

31+
// The NetBox Tenant to be used for creating this resource in Netbox
3632
//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="Field 'tenant' is immutable"
3733
Tenant string `json:"tenant,omitempty"`
3834

35+
// The NetBox Custom Fields that should be added to the resource in NetBox.
36+
// Note that currently only Text Type is supported (GitHub #129)
37+
// More info on NetBox Custom Fields:
38+
// https://github.com/netbox-community/netbox/blob/main/docs/customization/custom-fields.md
3939
CustomFields map[string]string `json:"customFields,omitempty"`
4040

41+
// Comment that should be added to the resource in NetBox
4142
Comments string `json:"comments,omitempty"`
4243

44+
// Description that should be added to the resource in NetBox
4345
Description string `json:"description,omitempty"`
4446

47+
// Defines whether the Resource should be preserved in NetBox when the
48+
// Kubernetes Resource is deleted.
49+
// - When set to true, the resource will not be deleted but preserved in
50+
// NetBox upon CR deletion
51+
// - When set to false, the resource will be cleaned up in NetBox
52+
// upon CR deletion
53+
// Setting preserveInNetbox to true is mandatory if the user wants to restore
54+
// resources from NetBox (e.g. Sticky CIDRs even if resources are deleted and
55+
// recreated in Kubernetes)
4556
PreserveInNetbox bool `json:"preserveInNetbox,omitempty"`
4657
}
4758

4859
// IpAddressClaimStatus defines the observed state of IpAddressClaim
4960
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-
61+
// The assigned IP Address in CIDR notation
5362
IpAddress string `json:"ipAddress,omitempty"`
5463

64+
// The assigned IP Address in Dot Decimal notation
5565
IpAddressDotDecimal string `json:"ipAddressDotDecimal,omitempty"`
5666

67+
// The name of the IpAddress CR created by the IpAddressClaim Controller
5768
IpAddressName string `json:"ipAddressName,omitempty"`
5869

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

@@ -68,7 +80,11 @@ type IpAddressClaimStatus struct {
6880
//+kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
6981
// +kubebuilder:resource:shortName=ipc
7082

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

‎config/crd/bases/netbox.dev_ipaddressclaims.yaml

+33-1
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,12 @@ spec:
3232
name: v1
3333
schema:
3434
openAPIV3Schema:
35-
description: IpAddressClaim is the Schema for the ipaddressclaims API
35+
description: |-
36+
IpAddressClaim allows to claim a NetBox IP Address from an existing Prefix.
37+
The IpAddressClaim Controller will try to assign an available IP Address
38+
from the Prefix that is defined in the spec and if successful it will create
39+
the IpAddress CR. More info about NetBox IP Addresses:
40+
https://github.com/netbox-community/netbox/blob/main/docs/models/ipam/ipaddress.md
3641
properties:
3742
apiVersion:
3843
description: |-
@@ -55,22 +60,43 @@ spec:
5560
description: IpAddressClaimSpec defines the desired state of IpAddressClaim
5661
properties:
5762
comments:
63+
description: Comment that should be added to the resource in NetBox
5864
type: string
5965
customFields:
6066
additionalProperties:
6167
type: string
68+
description: |-
69+
The NetBox Custom Fields that should be added to the resource in NetBox.
70+
Note that currently only Text Type is supported (GitHub #129)
71+
More info on NetBox Custom Fields:
72+
https://github.com/netbox-community/netbox/blob/main/docs/customization/custom-fields.md
6273
type: object
6374
description:
75+
description: Description that should be added to the resource in NetBox
6476
type: string
6577
parentPrefix:
78+
description: The NetBox Prefix from which this IP Address should be
79+
claimed from
6680
format: cidr
6781
type: string
6882
x-kubernetes-validations:
6983
- message: Field 'parentPrefix' is immutable
7084
rule: self == oldSelf
7185
preserveInNetbox:
86+
description: |-
87+
Defines whether the Resource should be preserved in NetBox when the
88+
Kubernetes Resource is deleted.
89+
- When set to true, the resource will not be deleted but preserved in
90+
NetBox upon CR deletion
91+
- When set to false, the resource will be cleaned up in NetBox
92+
upon CR deletion
93+
Setting preserveInNetbox to true is mandatory if the user wants to restore
94+
resources from NetBox (e.g. Sticky CIDRs even if resources are deleted and
95+
recreated in Kubernetes)
7296
type: boolean
7397
tenant:
98+
description: The NetBox Tenant to be used for creating this resource
99+
in Netbox
74100
type: string
75101
x-kubernetes-validations:
76102
- message: Field 'tenant' is immutable
@@ -82,6 +108,8 @@ spec:
82108
description: IpAddressClaimStatus defines the observed state of IpAddressClaim
83109
properties:
84110
conditions:
111+
description: Conditions represent the latest available observations
112+
of an object's state
85113
items:
86114
description: Condition contains details for one aspect of the current
87115
state of this API Resource.
@@ -138,10 +166,14 @@ spec:
138166
type: object
139167
type: array
140168
ipAddress:
169+
description: The assigned IP Address in CIDR notation
141170
type: string
142171
ipAddressDotDecimal:
172+
description: The assigned IP Address in Dot Decimal notation
143173
type: string
144174
ipAddressName:
175+
description: The name of the IpAddress CR created by the IpAddressClaim
176+
Controller
145177
type: string
146178
type: object
147179
type: object

‎config/crd/bases/netbox.dev_ipaddresses.yaml

+24-15
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,8 @@ spec:
3535
name: v1
3636
schema:
3737
openAPIV3Schema:
38-
description: IpAddress is the Schema for the ipaddresses API
38+
description: 'IpAddress allows to create a NetBox IP Address. More info about
39+
NetBox IP Addresses: https://github.com/netbox-community/netbox/blob/main/docs/models/ipam/ipaddress.md'
3940
properties:
4041
apiVersion:
4142
description: |-
@@ -63,26 +64,34 @@ spec:
6364
customFields:
6465
additionalProperties:
6566
type: string
66-
description: 'NetBox Custom Fields that should be added to the resource
67-
in NetBox. Note that currently only Text Type is supported (GitHub
68-
#129)'
67+
description: |-
68+
The NetBox Custom Fields that should be added to the resource in NetBox.
69+
Note that currently only Text Type is supported (GitHub #129)
70+
More info on NetBox Custom Fields:
71+
https://github.com/netbox-community/netbox/blob/main/docs/customization/custom-fields.md
6972
type: object
7073
description:
7174
description: Description that should be added to the resource in NetBox
7275
type: string
7376
ipAddress:
74-
description: The actual IP Address that should be reserved in NetBox
77+
description: The IP Address in CIDR notation that should be reserved
78+
in NetBox
7579
format: cidr
7680
type: string
7781
x-kubernetes-validations:
7882
- message: Field 'ipAddress' is immutable
7983
rule: self == oldSelf
8084
preserveInNetbox:
8185
description: |-
82-
preserveInNetbox defines whether or not the Resource should stay in NetBox when the Kubernetes Resource is deleted
83-
When set to true, the resource will not be deleted in NetBox upon CR deletion
84-
When set to false, the resource will be cleaned up in NetBox upon CR deletion
85-
If you want to restore resources from NetBox (e.g. recreation of an entire cluster), preserveInNetbox set to true is a prerequisite.
86+
Defines whether the Resource should be preserved in NetBox when the
87+
Kubernetes Resource is deleted.
88+
- When set to true, the resource will not be deleted but preserved in
89+
NetBox upon CR deletion
90+
- When set to false, the resource will be cleaned up in NetBox
91+
upon CR deletion
92+
Setting preserveInNetbox to true is mandatory if the user wants to restore
93+
resources from NetBox (e.g. Sticky CIDRs even if resources are deleted and
94+
recreated in Kubernetes)
8695
type: boolean
8796
tenant:
8897
description: The NetBox Tenant to be used for creating this resource
@@ -98,6 +107,8 @@ spec:
98107
description: IpAddressStatus defines the observed state of IpAddress
99108
properties:
100109
conditions:
110+
description: Conditions represent the latest available observations
111+
of an object's state
101112
items:
102113
description: Condition contains details for one aspect of the current
103114
state of this API Resource.
@@ -154,15 +165,13 @@ spec:
154165
type: object
155166
type: array
156167
id:
157-
description: |-
158-
INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
159-
Important: Run "make" to regenerate code after modifying this file
160-
The ID of the resource in NetBox
168+
description: The ID of the resource in NetBox
161169
format: int64
162170
type: integer
163171
url:
164-
description: The URL to the NetBox UI to display this resource. Note
165-
that the base depends on the runtime config of NetBox Operator
172+
description: |-
173+
The URL to the resource in the NetBox UI. Note that the base of this
174+
URL depends on the runtime config of NetBox Operator
166175
type: string
167176
type: object
168177
type: object

0 commit comments

Comments
 (0)