From 92017d66dc99c00394cb32119b6f3541bb8288ff Mon Sep 17 00:00:00 2001
From: Stephen Cahill <stephen.cahill@datadoghq.com>
Date: Sat, 2 Dec 2023 22:19:02 -0500
Subject: [PATCH] add docs/examples for pre-release and nightly img deployments
 with clusterctl

---
 docs/book/src/clusterctl/commands/upgrade.md | 37 ++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/docs/book/src/clusterctl/commands/upgrade.md b/docs/book/src/clusterctl/commands/upgrade.md
index 88c8bb92c7ee..236249f3252e 100644
--- a/docs/book/src/clusterctl/commands/upgrade.md
+++ b/docs/book/src/clusterctl/commands/upgrade.md
@@ -123,3 +123,40 @@ clusterctl upgrade apply \
 In this case, all the provider's versions must be explicitly stated.
 
 </aside>
+
+<aside class="note warning">
+
+<h1> Upgrading to Cluster API core components pre-release versions </h1>
+
+Use `clusterctl` CLI options to target the [desired version](https://github.com/kubernetes-sigs/cluster-api/releases).  
+
+The following shows an example of upgrading `bootrap`, `kubeadm` and `core` components to version `v1.6.0-rc.1`:
+
+```bash
+TARGET_VERSION=v1.6.0-rc.1
+
+clusterctl upgrade apply \
+    --bootstrap=kubeadm:${TARGET_VERSION} \
+    --control-plane=kubeadm:${TARGET_VERSION} \
+    --core=cluster-api:${TARGET_VERSION}
+```
+
+</aside>
+
+<aside class="note warning">
+
+<h1> Deploying nightly release images </h1>
+
+Cluster API publishes nightly versions of the project's images from the `main` branch to a `staging` registry that can be deployed in a management cluster using [clusterctl image overrides](../configuration.md#image-overrides).
+
+The tagging convention for the nightly images is `nightly_main_$(shell date +'%Y%m%d')`.  
+
+For example, to deploy the image versions `nightly_main_20231201` from the Cluster API staging repository, add the following `images` override entry to your [clusterctl config file](../configuration.md#clusterctl-configuration-file):
+
+```yaml
+images:
+  all:
+    tag: nightly_main_20231201
+    repository: gcr.io/k8s-staging-cluster-api
+```
+</aside>