Skip to content

Commit 21457df

Browse files
cjschaefcjschaef
committed
VPC: Add infrastructure creation proposal
Add a new proposal with details and images for creating and deleting VPC resources for the IBMVPCCluster definition.
1 parent 1cc2bc3 commit 21457df

4 files changed

+393
-0
lines changed

‎docs/images/vpc-cluster-components.png

79 KB
Loading

‎docs/images/vpc-cluster-create-workflow.png

58.2 KB
Loading

‎docs/images/vpc-cluster-delete-workflow.png

48.7 KB
Loading

‎docs/proposal/20240308-vpc-infra-creation.md

+393
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,393 @@
1+
# Dynamically create infrastructure required for VPC cluster
2+
3+
## Motivation
4+
Currently, inorder to create a VPC cluster using cluster api we need to create
5+
resources as prerequisites. This involves work which is limiting the true
6+
capabilities of cluster api.
7+
8+
9+
## Goal
10+
1. Dynamically create the required cloud resources as a part of cluster
11+
creation.
12+
13+
14+
## Proposal
15+
16+
17+
### Cluster API VPC cluster components
18+
19+
![vpc-cluster-components.png](../images/vpc-cluster-components.png)
20+
21+
22+
### Proposed API changes
23+
24+
25+
#### VPCCluster improvements
26+
```go
27+
// IBMVPCClusterSpec defines the desired state of IBMVPCCluster.
28+
type IBMVPCClusterSpec struct {
29+
// Important: Run "make" to regenerate code after modifying this file
30+
31+
// controlPlaneEndpoint represents the endpoint used to communicate with the control plane.
32+
// +optional
33+
ControlPlaneEndpoint capiv1beta1.APIEndpoint `json:"controlPlaneEndpoint"`
34+
35+
// controlPlaneLoadBalancer is optional configuration for customizing control plane behavior.
36+
// +optional
37+
ControlPlaneLoadBalancer []*VPCLoadBalancerSpec `json:"controlPlaneLoadBalancer,omitempty"`
38+
39+
// cosInstance is the IBM COS instance to use for cluster resources.
40+
COSInstance *CosInstance `json:"cosInstance,omitempty"`
41+
42+
// networkSpec represents the VPC network to use for the cluster.
43+
NetworkSpec *VPCNetworkSpec `json:"networkSpec,omitempty"`
44+
45+
// region defines the IBM Cloud Region the cluster resources will be deployed in.
46+
Region string `json:"region"`
47+
48+
// resourceGroup defines the IBM Cloud resource group where the cluster resources should be created.
49+
ResourceGroup string `json:"resourceGroup"`
50+
51+
// The Name of VPC.
52+
// Deprecated: use NetworkSpec instead.
53+
VPC string `json:"vpc,omitempty"`
54+
55+
// The Name of availability zone.
56+
// Deprecated: use NetworkSpec instead.
57+
Zone string `json:"zone,omitempty"`
58+
}
59+
60+
// VPCNetworkSpec defines the desired state of the network resources for the cluster.
61+
type VPCNetworkSpec struct {
62+
// computeSubnetsSpec is a set of Subnet's which define the Compute subnets.
63+
ComputeSubnetsSpec []Subnet `json:"computeSubnetsSpec,omitempty"`
64+
65+
// controlPlaneSubnetsSpec is a set of Subnet's which define the Control Plane subnets.
66+
ControlPlaneSubnetsSpec []Subnet `json:"controlPlaneSubentsSpec,omitempty"`
67+
68+
// resourceGroup is the name of the Resource Group containing all of the newtork resources.
69+
// This can be different than the Resource Group containing the remaining cluster resources.
70+
ResourceGroup *string `json:"resourceGroup,omitempty"`
71+
72+
// securityGroups is a set of SecurityGroup's which define the VPC Security Groups that manage traffic within and out of the VPC.
73+
SecurityGroups []SecurityGroup `json:"securityGroups,omitempty"`
74+
75+
// vpc defines the IBM Cloud VPC.
76+
VPC *VPCResourceReference `json:"vpc,omitempty"`
77+
}
78+
79+
// IBMVPCClusterStatus defines the observed state of IBMVPCCluster.
80+
type IBMVPCClusterStatus struct {
81+
// Important: Run "make" to regenerate code after modifying this file
82+
83+
// Conditions defines current service state of the load balancer.
84+
// +optional
85+
Conditions capiv1beta1.Conditions `json:"conditions,omitempty"`
86+
87+
// ControlPlaneLoadBalancerState is the status of the load balancer.
88+
// Deprecated: rely on NetworkStatus instead.
89+
// +optional
90+
ControlPlaneLoadBalancerState *VPCLoadBalancerState `json:"controlPlaneLoadBalancerState,omitempty"`
91+
92+
// COSInstance is the reference to the IBM Cloud COS Instance used for the cluster.
93+
COSInstance *VPCResourceReference
94+
95+
// networkStatus is the status of the VPC network in its entirety resources.
96+
NetworkStatus *VPCNetworkStatus `json:"networkStatus,omitempty"`
97+
98+
// ready is true when the provider resource is ready.
99+
// +kubebuilder:default=false
100+
Ready bool `json:"ready"`
101+
102+
// resourceGroup is the reference to the IBM Cloud VPC resource group under which the resources will be created.
103+
ResourceGroup *ResourceReference `json:"resourceGroupID,omitempty"`
104+
105+
// Deprecated: rely on NetworkStatus instead.
106+
Subnet Subnet `json:"subnet,omitempty"`
107+
108+
// Deprecated: rely on NetworkStatus instead.
109+
VPC VPC `json:"vpc,omitempty"`
110+
111+
// Deprecated: rely on ControlPlaneEndpoint
112+
VPCEndpoint VPCEndpoint `json:"vpcEndpoint,omitempty"`
113+
}
114+
115+
// VPCNetworkStatus provides details on the status of VPC network resources.
116+
type VPCNetworkStatus struct {
117+
// computeSubnets references the VPC Subnets for the cluster's Data Plane.
118+
// +optional
119+
ComputeSubnets []*VPCResourceReference `json:"computeSubnets,omitempty"`
120+
121+
// controlPlaneSubnets references the VPC Subnets for the cluster's Control Plane.
122+
// +optional
123+
ControlPlaneSubnets []*VPCResourceReference `json:"controlPlaneSubnets,omitempty"`
124+
125+
// loadBalancers references the VPC Load Balancer's for the cluster.
126+
// +optional
127+
LoadBalancers []VPCLoadBalancerStatus `json:"loadBalancers,omitempty"`
128+
129+
// publicGateways references the VPC Public Gateways for the cluster.
130+
// +optional
131+
PublicGateways []*VPCResourceReference `json:"publicGateways,omitempty"`
132+
133+
// securityGroups references the VPC Security Groups for the cluster.
134+
// +optional
135+
SecurityGroups []*VPCResourceReference `json:"securityGroups,omitempty"`
136+
137+
// vpc references the IBM Cloud VPC.
138+
// +optional
139+
VPC *VPCResourceReference `json:"vpc,omitempty"`
140+
}
141+
142+
// VPCResourceReference identifies a resource by id and type.
143+
type VPCResourceReference struct {
144+
// controllerCreated indicates whether the resource is created by the CAPI controller.
145+
ControllerCreated bool `json:"controllerCreated,omitempty"`
146+
147+
// crn defines the IBM Cloud CRN of the resource.
148+
// +optional
149+
CRN *string `json"crn,omitempty"`
150+
151+
// id defines the ID of the IBM Cloud resource.
152+
ID string `json:id"`
153+
154+
// type defines the type of IBM Cloud resource.
155+
Type VPCResourceType `json:type"`
156+
}
157+
158+
type VPCResourceType string
159+
160+
const (
161+
VPCResourceTypeCOS VPCResourceType = VPCResourceType("cos")
162+
VPCResourceTypePublicGateway VPCResourceType = VPCResourceType("publicgateway")
163+
VPCResourceTypeSecurityGroup VPCResourceType = VPCResourceType("securitygroup")
164+
VPCResourceTypeSecurityGroupRule VPCResourceType = VPCResourceType("securitygrouprule")
165+
VPCResourceTypeSubnet VPCResourceType = VPCResourceType("subnet")
166+
VPCResourceTypeVPC VPCResourceType = VPCResourceType("vpc")
167+
)
168+
```
169+
170+
171+
#### Share existing common resource definitions
172+
Rather than duplicate code and also make references to existing resources
173+
complex, we also propose relocating existing resource references into a
174+
common file. This prevents the duplication of code in PowerVS and VPC
175+
definitions, but also removes the direct dependence on PowerVS definitions,
176+
placing them into a common location (preventing unexpected dependencies).
177+
178+
Relocate the following resource definitions in IBMPowerVSCluster
179+
```go
180+
// VPCResourceReference is a reference to a specific VPC resource by ID or Name
181+
// Only one of ID or Name may be specified. Specifying more than one will result in
182+
// a validation error.
183+
type VPCResourceReference struct {
184+
// ID of resource
185+
// +kubebuilder:validation:MinLength=1
186+
// +optional
187+
ID *string `json:"id,omitempty"`
188+
189+
// Name of resource
190+
// +kubebuilder:validation:MinLength=1
191+
// +optional
192+
Name *string `json:"name,omitempty"`
193+
194+
// IBM Cloud VPC region
195+
Region *string `json:"region,omitempty"`
196+
}
197+
198+
// CosInstance represents IBM Cloud COS instance.
199+
type CosInstance struct {
200+
// PresignedURLDuration defines the duration for which presigned URLs are valid.
201+
//
202+
// This is used to generate presigned URLs for S3 Bucket objects, which are used by
203+
// control-plane and worker nodes to fetch bootstrap data.
204+
//
205+
// When enabled, the IAM instance profiles specified are not used.
206+
// +optional
207+
PresignedURLDuration *metav1.Duration `json:"presignedURLDuration,omitempty"`
208+
209+
// Name defines name of IBM cloud COS instance to be created.
210+
// +kubebuilder:validation:MinLength:=3
211+
// +kubebuilder:validation:MaxLength:=63
212+
// +kubebuilder:validation:Pattern=`^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$`
213+
Name string `json:"name,omitempty"`
214+
215+
// bucketName is IBM cloud COS bucket name
216+
BucketName string `json:"bucketName,omitempty"`
217+
218+
// bucketRegion is IBM cloud COS bucket region
219+
BucketRegion string `json:"bucketRegion,omitempty"`
220+
}
221+
```
222+
223+
To a shared location, such as [types.go](https://github.com/kubernetes-sigs/cluster-api-provider-ibmcloud/blob/main/api/v1beta2/types.go).
224+
225+
We also are adding additional resources and definitions that could be shared,
226+
such as the following:
227+
```go
228+
// PortRange represents a range of ports, minimum to maximum.
229+
type PortRange struct {
230+
// maximumPort is the inclusive upper range of ports.
231+
MaximumPort int `json:"maximumPort,omitempty"`
232+
233+
// minimumPort is the inclusive lower range of ports.
234+
MinimumPort int `json:"minimumPort,omitempty"`
235+
}
236+
237+
// SecurityGroup defines a VPC Security Group that should exist or be created within the specified VPC, with the specified Security Group Rules.
238+
type SecurityGroup struct {
239+
// id of the Security Group.
240+
ID string
241+
242+
// name of the Security Group.
243+
Name string
244+
245+
// resourceGroup of the Security Group.
246+
ResourceGroup string
247+
248+
// rules are the Security Group Rules for the Security Group.
249+
Rules []*SecurityGroupRule
250+
251+
// tags are tags to add to the Security Group.
252+
Tags []string
253+
254+
// vpc is the IBM Cloud VPC for the Security Group.
255+
VPC *VPCResourceReference
256+
}
257+
258+
// SecurityGroupRule defines a VPC Security Group Rule for a specified Security Group.
259+
type SecurityGroupRule struct {
260+
// action defines whether to allow or deny traffic defined by the Security Group Rule.
261+
Action SecurityGroupRuleAction
262+
263+
// destination is a SecurityGroupRulePrototype which defines the destination of outbound traffic for the Security Group Rule.
264+
// Only used when Direction is SecurityGroupRuleDirectionOutbound.
265+
// +optional
266+
Destination *SecurityGroupRulePrototype
267+
268+
// direction defines whether the traffic is inbound or outbound for the Security Group Rule.
269+
Direction SecurityGroupRuleDirection
270+
271+
// securityGroupID is the ID of the Security Group for the Security Group Rule.
272+
SecurityGroupID *string
273+
274+
// source is a SecurityGroupRulePrototype which defines the source of inbound traffic for the Security Group Rule.
275+
// Only used when Direction is SecurityGroupRuleDirectionInbound.
276+
Source *SecurityGroupRulePrototype
277+
}
278+
279+
// SecurityGroupRuleRemote defines a VPC Security Group Rule's remote details.
280+
// The type of remote defines the additional remote details where are used for defining the remote.
281+
type SecurityGroupRuleRemote struct {
282+
// cidrSubnetName is the name of the VPC Subnet to retrieve the CIDR from, to use for the remote's destination/source.
283+
// Only used when RemoteType is SecurityGroupRuleRemoteTypeCIDR.
284+
// +optional
285+
CIDRSubnetName *string `json:"cidrSubnetName,omitempty"`
286+
287+
// ip is the IP to use for the remote's destination/source.
288+
// Only used when RemoteType is SecurityGroupRuleRemoteTypeIP.
289+
// +optional
290+
IP *string `json:ip,omitempty"`
291+
292+
// remoteType defines the type of filter to define for the remote's destination/source.
293+
// +required
294+
RemoteType SecurityGroupRuleRemoteType `json:"remoteType"`
295+
296+
// securityGroupName is the name of the VPC Security Group to use for the remote's destination/source.
297+
// Only used when RemoteType is SecurityGroupRuleRemoteTypeSG
298+
// +optional
299+
SecurityGroupName *string `json:"securityGroupName,omitempty"`
300+
}
301+
302+
// SecurityGroupRulePrototype defines a VPC Security Group Rule's traffic specifics for a series of remotes (destinations or sources).
303+
type SecurityGroupRulePrototype struct {
304+
// icmpCode is the ICMP code for the Rule.
305+
// Only used when Protocol is SecurityGroupProtocolICMP.
306+
// +optional
307+
ICMPCode *string `json:"icmpCode,omitempty"`
308+
309+
// icmpType is the ICMP type for the Rule.
310+
// Only used when Protocol is SecurityGroupProtocolICMP.
311+
// +optional
312+
ICMPType *string `json:"icmpType,omitempty"`
313+
314+
// portRange is a PortRange allowed for the Rule's remote.
315+
// +optional
316+
PortRange *PortRange `json:"portRange,omitempty"`
317+
318+
// protocol defines the traffic protocol used for the Security Group Rule.
319+
// +required
320+
Protocol SecurityGroupRuleProtocol `json:"protocol"`
321+
322+
// remotes is a set of SecurityGroupRuleRemote's that define the traffic allowed by the Rule's remote.
323+
// Specifying multiple SecurityGroupRuleRemote's creates a unique Security Group Rule with the shared Protocol, PortRange, etc.
324+
// This allows for easier management of Security Group Rule's for sets of CIDR's, IP's, etc.
325+
Remotes []SecurityGroupRuleRemote `json:"remotes"`
326+
}
327+
```
328+
329+
#### Shared enumerations
330+
Since IBM Cloud API's do not define enumerations for resource options, we have
331+
added some enumerations to enforce values and for validation.
332+
```go
333+
type SecurityGroupRuleAction string
334+
335+
const (
336+
SecurityGroupRuleActionAllow SecurityGroupRuleAction = vpcv1.NetworkACLRuleActionAllowConst
337+
SecurityGroupRuleActionDeny SecurityGroupRuleAction = vpcv1.NetworkACLRuleActionDenyConst
338+
)
339+
340+
type SecurityGroupRuleDirection string
341+
342+
const (
343+
SecurityGroupRuleDirectionInbound SecurityGroupRuleDirection = vpcv1.NetworkACLRuleDirectionInboundConst
344+
SecurityGroupRuleDirectionOutbound SecurityGroupRuleDirection = vpcv1.NetworkACLRuleDirectionOutboundConst
345+
)
346+
347+
type SecurityGroupRuleProtocol string
348+
349+
const (
350+
SecurityGroupRuleProtocolAll SecurityGroupRuleProtocal = vpcv1.NetworkACLRuleProtocolAllConst
351+
SecurityGroupRuleProtocolICMP SecurityGroupRuleProtocal = vpcv1.NetworkACLRuleProtocolIcmpConst
352+
SecurityGroupRuleProtocolTCP SecurityGroupRuleProtocal = vpcv1.NetworkACLRuleProtocolTCPConst
353+
SecurityGroupRuleProtocolUDP SecurityGroupRuleProtocal = vpcv1.NetworkACLRuleProtocolUDPConst
354+
)
355+
356+
type SecurityGroupRuleRemoteType string
357+
358+
const (
359+
SecurityGroupRuleRemoteTypeAny SecurityGroupRuleRemoteType = SecurityGroupRuleRemoteType("any")
360+
SecurityGroupRuleRemoteTypeCIDR SecurityGroupRuleRemoteType = SecurityGroupRuleRemoteType("cidr")
361+
SecurityGroupRuleRemoteTypeIP SecurityGroupRuleRemoteType = SecurityGroupRuleRemoteType("ip")
362+
SecurityGroupRuleRemoteTypeSG SecurityGroupRuleRemoteType = SecurityGroupRuleRemoteType("sg")
363+
)
364+
```
365+
366+
367+
### Following resources can be created
368+
1. [VPC](https://cloud.ibm.com/docs/vpc?topic=vpc-about-vpc)
369+
2. [VPC Subnets](https://cloud.ibm.com/docs/vpc?topic=vpc-about-networking-for-vpc)
370+
3. [VPC Public Gatways](https://cloud.ibm.com/docs/vpc?topic=vpc-about-networking-for-vpc#external-connectivity)
371+
4. [VPC Security Groups](https://cloud.ibm.com/docs/vpc?topic=vpc-using-security-groups) & [VPC Security Group Rules](https://cloud.ibm.com/docs/vpc?topic=vpc-using-security-groups#defining-security-group-rules)
372+
5. [VPC Load Balancers](https://cloud.ibm.com/docs/vpc?topic=vpc-nlb-vs-elb)
373+
374+
375+
### Cluster creation workflow
376+
The user is expected to set the annotation
377+
`vpc.cluster.x-k8s.io/create-infra:true` on the IBMVPCCluster object to
378+
make use of this feature. If not set, the cluster creation will proceed using
379+
the existing process.
380+
381+
THe user can specify existing resources in Spec, and the specified controller
382+
will attempt to reuse those resources instead of creating new ones.
383+
384+
When the resource is not set in the Spec or the provided resource name does
385+
not exist in cloud, the controller will create a new resource.
386+
387+
![vpc-cluster-create-workflow.png](../images/vpc-cluster-create-workflow.png)
388+
389+
390+
### Cluster Deletion workflow
391+
The controller will only delete the resources which are created by it.
392+
393+
![vpc-cluster-delete-workflow.png](../images/vpc-cluster-delete-workflow.png)

0 commit comments

Comments
 (0)