add VPC documentation

docs/src/SUMMARY.md

@@ -22,6 +22,7 @@
       - [Data Disks](./topics/disks/data-disks.md)
     - [Machine Health Checks](./topics/health-checking.md)
     - [Autoscaling](./topics/autoscaling.md)
+    - [VPC](./topics/vpc.md)
 - [Development](./developers/development.md)
     - [Releasing](./developers/releasing.md)
 - [Reference](./reference/reference.md)

docs/src/developers/development.md

@@ -170,7 +170,7 @@ This can then be used with `clusterctl` by adding the following to `~/.clusterct
 ```
 providers:
   - name: local-linode
-    url: ${HOME}/cluster-api-provider-linode/infrastructure-linode/v0.0.0/infrastructure-components.yaml
+    url: ${HOME}/cluster-api-provider-linode/infrastructure-local-linode/v0.0.0/infrastructure-components.yaml
     type: InfrastructureProvider
 ```
 

docs/src/topics/flavors/vpcless.md

@@ -19,7 +19,7 @@ supported in this flavor and it uses VXLAN for pod to pod communication.
 1. Generate cluster yaml
     ```bash
     clusterctl generate cluster test-cluster \
-        --infrastructure linode:0.0.0 \
+        --infrastructure linode-linode \
         --flavor vpcless > test-cluster.yaml
     ```
 2. Apply cluster yaml

docs/src/topics/getting-started.md

@@ -33,7 +33,7 @@ For Regions and Images that do not yet support Akamai's cloud-init datasource CA
 to provision the node. If you are using a custom image ensure the [cloud_init](https://www.linode.com/docs/api/images/#image-create) flag is set correctly on it
 ```
 ```admonish warning
-By default, clusters are provisioned within VPC. For Regions which do not have [VPC support](https://www.linode.com/docs/products/networking/vpc/#availability) yet, use the VPCLess[TODO] flavor to have clusters provisioned.
+By default, clusters are provisioned within VPC. For Regions which do not have [VPC support](https://www.linode.com/docs/products/networking/vpc/#availability) yet, use the [VPCLess](./flavors/vpcless.md) flavor to have clusters provisioned.
 ```
 
 ## Register linode as an infrastructure provider

docs/src/topics/vpc.md

@@ -0,0 +1,51 @@
+# VPC
+
+This guide covers how [VPC](https://www.linode.com/docs/products/networking/vpc/) is used with CAPL clusters. By default, CAPL clusters are provisioned within VPC.
+
+## Default configuration
+Each linode within a cluster gets provisioned with two interfaces:
+1. eth0 (for public and nodebalancer traffic)
+2. eth1 (connected to VPC, for pod-to-pod traffic)
+
+Key facts about VPC network configuration:
+1. VPCs are provisioned with a private subnet 10.0.0.0/8.
+2. All pod-to-pod communication happens over the VPC interface (eth1).
+3. We assign a pod CIDR of range 10.192.0.0/10 for pod-to-pod communication.
+3. By default, cilium is configured with [native routing](https://docs.cilium.io/en/stable/network/concepts/routing/#native-routing)
+4. [Kubernetes host-scope IPAM mode](https://docs.cilium.io/en/stable/network/concepts/ipam/kubernetes/) is used to assign pod CIDRs to nodes. We run [linode CCM](https://github.com/linode/linode-cloud-controller-manager) with [route-controller enabled](https://github.com/linode/linode-cloud-controller-manager?tab=readme-ov-file#routes) which automatically adds/updates routes within VPC when pod cidrs are added/updated by k8s. This enables pod-to-pod traffic to be routable within the VPC.
+5. kube-proxy is disabled by default.
+
+## How VPC is provisioned
+A VPC is tied to a region. CAPL generates LinodeVPC manifest which contains the VPC name, region and subnet information. By defult, VPC name is set to cluster name but can be overwritten by specifying relevant environment variable.
+
+```yaml
+---
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
+kind: LinodeVPC
+metadata:
+  name: ${VPC_NAME:=${CLUSTER_NAME}}
+  labels:
+    cluster.x-k8s.io/cluster-name: ${CLUSTER_NAME}
+spec:
+  region: ${LINODE_REGION}
+  subnets:
+    - ipv4: 10.0.0.0/8
+      label: default
+```
+
+Reference to LinodeVPC object is added to LinodeCluster object which then uses the specified VPC to provision resources.
+
+## Troubleshooting
+### If pod-to-pod connectivity is failing
+If a pod can't ping pod ips on different node, check and make sure pod CIDRs are added to ip_ranges of VPC interface.
+
+```sh
+curl --header 'Authorization: Bearer $LINODE_API_TOKEN' -X GET https://api.linode.com/v4/linode/instances/${LINODEID}/configs | jq .data[0].interfaces[].ip_ranges
+```
+
+```admonish note
+CIDR returned in the output of above command should match with the pod CIDR present in node's spec `k get node <nodename> -o yaml | yq .spec.podCIDRs`
+```
+
+### Running cilium connectivity tests
+One can also run cilium connectivity tests to make sure networking works fine within VPC. Follow the steps defined in [cilium e2e tests](https://docs.cilium.io/en/stable/contributing/testing/e2e/) guide to install cilium binary, set the KUBECONFIG variable and then run `cilium connectivity tests`.

templates/addons/cilium/cilium-vxlan.yaml

@@ -16,6 +16,8 @@ spec:
     wait: true
     timeout: 5m
   valuesTemplate: |
+    bgpControlPlane:
+      enabled: true
     ipam:
       mode: kubernetes
     k8s:

templates/addons/provider-linode/linode-ccm-vpcless.yaml

@@ -10,7 +10,7 @@ spec:
   repoURL: https://linode.github.io/linode-cloud-controller-manager/
   chartName: ccm-linode
   namespace: kube-system
-  version: ${LINODE_CCM_VERSION:=v0.4.3}
+  version: ${LINODE_CCM_VERSION:=v0.4.4}
   options:
     waitForJobs: true
     wait: true

templates/addons/provider-linode/linode-ccm.yaml

@@ -17,7 +17,7 @@ spec:
     timeout: 5m
   valuesTemplate: |
     routeController:
-      vpcName: ${VPC_NAME:=${CLUSTER_NAME}}
+      vpcName: {{ .InfraCluster.spec.vpcRef.name }}
       clusterCIDR: 10.0.0.0/8
       configureCloudRoutes: true
     secretRef: