From be1bf95900d71b0220306e9a6f860bc39b6431b5 Mon Sep 17 00:00:00 2001
From: Cindy Bang <cbang@akamai.com>
Date: Mon, 4 Mar 2024 09:00:00 -0500
Subject: [PATCH] docs: add multi-tenant clusters

---
 docs/src/SUMMARY.md                |  1 +
 docs/src/developers/development.md |  5 +--
 docs/src/topics/multi-tenancy.md   | 51 ++++++++++++++++++++++++++++++
 3 files changed, 55 insertions(+), 2 deletions(-)
 create mode 100644 docs/src/topics/multi-tenancy.md

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index a1cb0d91c..fbf5abe64 100644
--- a/docs/src/SUMMARY.md
+++ b/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)
diff --git a/docs/src/developers/development.md b/docs/src/developers/development.md
index 7cbea2614..b6b29487b 100644
--- a/docs/src/developers/development.md
+++ b/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
diff --git a/docs/src/topics/multi-tenancy.md b/docs/src/topics/multi-tenancy.md
new file mode 100644
index 000000000..290dcec96
--- /dev/null
+++ b/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).
+```