docs: add multi-tenant clusters

docs/src/SUMMARY.md

@@ -11,6 +11,7 @@
       - [k3s](./topics/flavors/k3s.md)
       - [rke2](./topics/flavors/rke2.md)
     - [Etcd](./topics/etcd.md)
+    - [Multi-Tenancy](./topics/multi-tenancy.md)
 - [Development](./developers/development.md)
     - [Releasing](./developers/releasing.md)
 - [Reference](./reference/reference.md)

docs/src/developers/development.md

@@ -147,12 +147,13 @@ providers:
 Here is a list of required configuration parameters:
 
 ```sh
-# Cluster settings
+## Cluster settings
 export CLUSTER_NAME=capl-cluster
 export KUBERNETES_VERSION=v1.29.1
 
-# Linode settings
+## Linode settings
 export LINODE_REGION=us-ord
+# Multi-tenancy: This may be changed for each cluster to deploy to different Linode accounts.
 export LINODE_TOKEN=<your linode PAT>
 export LINODE_CONTROL_PLANE_MACHINE_TYPE=g6-standard-2
 export LINODE_MACHINE_TYPE=g6-standard-2

docs/src/topics/multi-tenancy.md

@@ -0,0 +1,51 @@
+# Multi-Tenancy
+
+CAPL can manage multi-tenant workload clusters across Linode accounts. Custom resources may reference an optional Secret
+containing their Linode credentials (i.e. API token) to be used for the deployment of Linode resources (e.g. Linodes,
+VPCs, NodeBalancers, etc.) associated with the cluster.
+
+The following example shows a basic credentials Secret:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: linode-credentials
+stringData:
+  apiToken: <LINODE_TOKEN>
+```
+
+```admonish warning
+The Linode API token data must be put in a key named `apiToken`!
+```
+
+Which may be optionally consumed by one or more custom resource objects:
+
+```yaml
+# Example: LinodeCluster
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
+kind: LinodeCluster
+metadata:
+  name: test-cluster
+spec:
+  credentialsRef:
+    name: linode-credentials
+  ...
+---
+# Example: LinodeVPC
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
+kind: LinodeVPC
+metadata:
+  name: test-vpc
+spec:
+  credentialsRef:
+    name: linode-credentials
+  ...
+```
+
+Secrets from other namespaces by additionally specifying an optional
+`.spec.credentialsRef.namespace` value.
+
+```admonish warning
+If `.spec.credentialsRef` is set for a LinodeCluster, it should also be set for adjacent resources (e.g. LinodeVPC).
+```