From 0cdeb8738c79339eb47d5d2a9f5d1a48b24edaaa Mon Sep 17 00:00:00 2001
From: "Louise K. Schmidtgen" <louise.schmidtgen@canonical.com>
Date: Mon, 16 Dec 2024 11:09:03 +0200
Subject: [PATCH] How-to Openstack Integration (#855)

---
 docs/src/charm/howto/index.md     |  1 +
 docs/src/charm/howto/openstack.md | 78 +++++++++++++++++++++++++++++++
 2 files changed, 79 insertions(+)
 create mode 100644 docs/src/charm/howto/openstack.md

diff --git a/docs/src/charm/howto/index.md b/docs/src/charm/howto/index.md
index 82438604b..3ce19dc0e 100644
--- a/docs/src/charm/howto/index.md
+++ b/docs/src/charm/howto/index.md
@@ -16,6 +16,7 @@ Overview <self>
 
 charm
 install-lxd
+openstack
 Integrate with etcd <etcd>
 Integrate with ceph-csi <ceph-csi>
 proxy
diff --git a/docs/src/charm/howto/openstack.md b/docs/src/charm/howto/openstack.md
new file mode 100644
index 000000000..98c6479e8
--- /dev/null
+++ b/docs/src/charm/howto/openstack.md
@@ -0,0 +1,78 @@
+# Integrating with OpenStack
+
+This guide explains how to integrate {{product}} with the OpenStack cloud
+platform. The `openstack-integrator` charm simplifies working with {{product}}
+on OpenStack. Using the credentials provided to Juju, it acts as a proxy between
+{{product}} and the underlying cloud, granting permissions to dynamically
+create, for example, Cinder volumes.
+
+## Prerequisites
+
+To follow this guide, you will need:
+
+- An [OpenStack][openstack] cloud environment.
+- Octavia available both to support Kubernetes LoadBalancer services and to
+  support the creation of a load balancer for the Kubernetes API.
+- A valid [proxy configuration][proxy] in constrained environments.
+
+## Installing {{product}} on OpenStack
+
+To deploy the {{product}} [bundle][bundle] on OpenStack you need an overlay
+bundle which serves as an extension of the core bundle. Through the overlay,
+applications are deployed and relations are established between the
+applications. These include the openstack integrator, cloud
+controller, and cinder-csi charm.
+
+### OpenStack Overlay Configurations:
+
+Refer to the base overlay [openstack-overlay.yaml][openstack-overlay] and
+modify it as needed.
+
+```yaml
+applications:
+  openstack-integrator:
+    charm: openstack-integrator
+    num_units: 1
+    trust: true
+    base: ubuntu@22.04
+  openstack-cloud-controller:
+    charm: openstack-cloud-controller
+  cinder-csi:
+    charm: cinder-csi
+relations:
+  - [openstack-cloud-controller:kube-control,            k8s:kube-control]
+  - [cinder-csi:kube-control,                            k8s:kube-control]
+  - [openstack-cloud-controller:external-cloud-provider, k8s:external-cloud-provider]
+  - [openstack-cloud-controller:openstack,               openstack-integrator:clients]
+  - [cinder-csi:openstack,                               openstack-integrator:clients]
+```
+
+### Deploying the Overlay Template
+
+Deploy the {{product}} bundle on OpenStack using the modified overlay:
+
+```
+juju deploy canonical-kubernetes --overlay ~/path/openstack-overlay.yaml --trust
+```
+
+...and remember to fetch the configuration file!
+
+```
+juju run k8s/leader get-kubeconfig | yq eval '.kubeconfig' > kubeconfig
+```
+
+The {{product}} bundle is now deployed and integrated with OpenStack. Run 
+`juju status --watch 1s` to monitor the deployment. It is possible that your
+deployment will take a few minutes until all the components are up and running.
+
+```{note}
+Resources allocated by Kubernetes or the integrator are usually cleaned up automatically when no longer needed. However, it is recommended to periodically, and particularly after tearing down a cluster, use the OpenStack administration tools to make sure all unused resources have been successfully released. 
+```
+
+
+
+<!-- LINKS -->
+[openstack]: https://www.openstack.org/
+[proxy]: https://documentation.ubuntu.com/canonical-kubernetes/main/src/charm/howto/proxy/
+[bundle]: https://github.com/canonical/k8s-bundles/blob/main/main/bundle.yaml
+[openstack-overlay]: https://github.com/canonical/k8s-bundles/blob/main/overlays/openstack.yaml