Openstack Region Provider Documentation

Get some thoughts and processes down on paper.

README.md

@@ -9,16 +9,14 @@
 
 Unikorn abstracts away installation of Cluster API.
 
-There are three resource types:
+There are four resource types:
 
+* Organizations, that are analogous to organizations defined for [Unikorn Identity](https://github.com/unikorn-cloud/identity), but in this component merely provide a namespace for projects.
 * Projects, that are a container for higher level abstractions.
 * ControlPlanes, that basically are instances of Cluster API that live in Projects.
-* Clusters, Kubernetes clusters.
+* Clusters, are Kubernetes clusters, and managed by control planes.
 
-Control planes are actually contained themselves in virtual clusters, as CAPI is pretty terrible at cleaning things up on OpenStack errors, so we make these cattle.
-One Kubernetes cluster to one instance of Cluster API.
-If something goes wrong, just delete the virtual cluster and restart.
-In future, when things get more stable, we can support many-to-one to save on resource costs, and even do away with virtual clusters entirely.
+Control planes are actually contained themselves in virtual clusters, this allows horizontal scaling and multi-tenant separation.
 
 Projects allow multiple control planes to be contained within them.
 These are useful for providing a boundary for billing etc.
@@ -209,7 +207,7 @@ YOu must deploy [Unikorn Identity](https://github.com/unikorn-cloud/identity) fi
 
 To enable Unikorn UI `--set ui.enabled=true`.
 This only enables the ingress route for now.
-You will also need to install the UI using Helm as described in the [unikorn-ui repository](https://github.com/unikorn-cloud/unikorn-ui).
+You will also need to install the UI using Helm as described in the [unikorn-ui repository](https://github.com/unikorn-cloud/ui).
 It **must** be installed in the same namespace as Unikorn server in order for the service to be seen by the Ingress.
 
 ## Monitoring & Logging
@@ -221,6 +219,12 @@ See the [monitoring & logging](docs/monitoring.md) documentation from more infor
 
 ## Documentation
 
+### Region Providers
+
+These actually provide access to cloud resources and abstract away vendor specifics:
+
+* [OpenStack](pkg/providers/openstack/README.md)
+
 ### API (Unikorn Server)
 
 Consult the [server readme](pkg/server/README.md) to get started.

pkg/providers/openstack/README.md

@@ -0,0 +1,83 @@
+# Unikorn OpenStack Provider
+
+Provides a driver for OpenStack based regions.
+
+## Initial Setup
+
+It is envisoned that an OpenStack cluster may be used for things other than the exclusive use of Unikorn, and as such it tries to respect this as much as possible.
+In particular we want to allow different instances of Unikorn to cohabit to support, for example, staging environments.
+
+### OpenStack Platform Configuration
+
+Start by selecting a unique name that will be used for the deployment's name, project, and domain:
+
+```bash
+PROJECT=unikorn-staging
+PASSWORD=$(apg -m 24)
+```
+
+Create the project.
+While Unikorn, by necessity, runs as an `admin` account, we use the project to limit scope.
+For example while we can see all images and flavors on the system, we can filter out those not shared explicitly with the project.
+Likewise, we can have project specific images that aren't shared with other users on the system, this allows then to be discovered by the provider.
+By marking the images as `community` we can then use the images for deployment in other per-Kubernetes cluster projects.
+
+```bash
+PROJECT_ID=$(openstack create project ${PROJECT} -f json | jq .id}
+```
+
+Crete the user.
+
+```bash
+USER_ID=$(openstack user create --project ${PROJECT} --password=${PASSWORD} ${PROJECT} -f json | jq .id)
+```
+
+Grant any roles to the user.
+When a Kubernetes cluster is provisioned, it will be done using application credentials, so ensure any required application credentials as configured for the region are explicitly associated with the user here.
+
+```bash
+openstack role add --user ${USER_ID} --project ${PROJECT_ID} admin
+openstack role add --user ${USER_ID} --project ${PROJECT_ID} member
+openstack role add --user ${USER_ID} --project ${PROJECT_ID} load-balancer_member
+```
+
+Create the domain.
+The use of project domains for projects deployed to provision Kubernetes cluster acheives a few aims.
+First namespace isolation.
+Second is a security consideration.
+It is dangerous, anecdotally, to have a privileged process that has the power of deletion.
+By limiting the scope of list operations to that of the project domain we limit our impact on other tenants on the system.
+A domain may also aid in simplifying operations like auditing and capacity planning.
+
+```bash
+DOMAIN_ID=$(openstack domain create ${PROJECT} -f json | jq .id}
+```
+
+### Unikorn Configuration
+
+When we create a `Region` of type `openstack`, it will require a secret that contains credentials.
+This can be configured as follows.
+
+```bash
+kubectl create secret -n unikorn uk-north-1-credentials \
+	--from-literal=domain-id=${DOMAIN_ID} \
+	--from-literal=user-id=${USER_ID} \
+	--from-literal=password=${PASSWORD}
+```
+
+Finally we can create the region itself.
+For additional configuration options for individual OpenStack services, consult `kubectl explain regions.unikorn-cloud.org` for documentation.
+
+```yaml
+apiVersion: unikorn-cloud.org/v1alpha1
+kind: Region
+metadata:
+  name: uk-north-1
+spec:
+  provider: openstack
+  openstack:
+    endpoint: https://openstack.uk-north-1.unikorn-cloud.org:5000
+    serviceAccountSecret:
+      namespace: unikorn
+      name: uk-north-1-credentials
+```