Add initial blazar documentation (azimuth-cloud#190)

* Add initial Blazar documentation

* Add initial notes about coral credits

* Move blazar docs into a separate file

* Fix typo

* Add note about storage network

* Rework new docs

* Fix menu item

* Small tidy of unclear language

---------

Co-authored-by: Matt Pryor <[email protected]>

Author: 2 people

docs/configuration/04-target-cloud/01-openstack-blazar.md

@@ -0,0 +1,104 @@
+# OpenStack Blazar
+
+!!! warning  "Technology preview"
+
+    Blazar support is currently in technology preview and under active development.
+
+    Its possible how this feature works may radically change in a future release.
+
+When available on the target cloud, Azimuth is able to make use of
+[Blazar](https://docs.openstack.org/blazar/latest/), an OpenStack service for reserving
+cloud resources. When Blazar support is enabled, Azimuth is able to create reservations
+for platforms and deploy platforms into those reservations.
+
+Currently, Azimuth is using Blazar to give users better feedback about when the cloud is full,
+meaning that their platform cannot be created right now. This is a common issue with
+"fixed capacity" clouds, where there is more demand for resources than available capacity.
+
+When creating a platform, users must specify how long they need that platform for. Azimuth
+translates this information, along with the parameters for the platform, into a request for
+a Blazar reservation (starting now) that can accomodate the requested platform. If this is
+successful then Azimuth creates the platform using the reserved resources. If it is not
+successful, Azimuth reports that the cloud is not able to accomodate the platform as currently
+configured and the user may try again with different parameters.
+
+!!! info  "Future work"
+
+    Blazar also supports creating reservations that start in the future, e.g. "can I have three
+    machines of flavor X and two of flavor Y for two weeks starting tomorrow". This is useful for
+    cases where it is known advance when resources will be required, and they can be reserved for
+    that time. In the future, Azimuth will support creating platforms that start in the future
+    using this mechanism.
+
+## Blazar flavor plugin
+
+Azimuth relies on the new
+[Blazar flavor plugin](https://opendev.org/openstack/blazar/src/branch/master/blazar/plugins/flavor/flavor_plugin.py)
+that allows resources to be reserved in Blazar using existing Nova flavors. When creating a
+reservation, the required number of servers of each flavor is specified and Blazar reserves
+the corresponding resources from its pool of hosts.
+
+Azimuth does not currently support the host reservation or instance reservation plugins.
+
+There is active work on the Blazar flavor plugin to improve the support for VMs with GPUs
+attached, and to allow [Ironic](https://docs.openstack.org/ironic/latest/) bare-metal nodes
+to be added as possible flavor reservation targets.
+
+Currently, Azimuth only supports the case where all projects are able to access all configured
+Nova flavors via Blazar.
+
+For more information on Blazar, and how to add hosts into Blazar's control, please see the
+[Blazar documentation](https://docs.openstack.org/blazar/latest/cli/flavor-based-instance-reservation.html).
+
+## Coral Credits
+
+Blazar has support for
+[delegating to an external service](https://docs.openstack.org/blazar/latest/admin/usage-enforcement.html#externalservicefilter)
+to determine whether a reservation is permitted.
+
+[Coral Credits](https://github.com/stackhpc/coral-credits) is a new open-source service for
+facilitating sharing of resources using credit allocations. It implements the API required
+for Blazar to call out to it, allowing the creation of Blazar reservations to be constrained
+by the available credits for a project.
+
+Coral Credits can be deployed as part of an Azimuth installation using the following:
+
+```yaml  title="environments/my-site/inventory/group_vars/all/variables.yml"
+coral_credits_enabled: yes
+```
+
+For Details on how to configure Blazar to use Coral Credits as an enforcement plugin, and how
+to configure the credit allocations for each OpenStack project, see the
+[Coral Credits documentation](https://github.com/stackhpc/coral-credits/blob/main/README.md#blazar-configuration).
+
+## Azimuth configuration
+
+To enable "time-limited" platforms in Azimuth, i.e. platforms that are automatically deleted
+at a specified time in the future, set the following variable:
+
+```yaml  title="environments/my-site/inventory/group_vars/all/variables.yml"
+azimuth_scheduling_enabled: true
+```
+
+When this variable is set, Azimuth users will be required to specify an end time for any
+platforms that they create.
+
+!!! warning  "Platforms cannot be extended"
+
+    Currently, Azimuth does **not** support extending the end time for a platform.
+
+By default, this **does not** use Blazar reservations - Azimuth just ensures that the platform is
+deleted at the requested time. This is still useful to help to prevent resource squatting on clouds
+where Blazar is not available. However platforms can still encounter issues when the cloud is full
+because the resources are not reserved for the platform as they are in Blazar.
+
+To tell Azimuth to create Blazar reservations for platforms, set the following variable:
+
+```yaml  title="environments/my-site/inventory/group_vars/all/variables.yml"
+azimuth_schedule_operator_blazar_enabled: true
+```
+
+When this variable is set, Azimuth will attempt to create a Blazar lease for each platform. If
+the creation of the Blazar lease fails, Azimuth will report whether the problem was due to cloud
+capacity or being limited by credits. If the Blazar lease is created successfully, Azimuth will
+create the platform using the reserved resources.

docs/configuration/04-target-cloud/02-openstack-manila.md

@@ -0,0 +1,92 @@
+# OpenStack Manila
+
+!!! warning  "Technology preview"
+
+    Manila support is currently in technology preview and under active development.
+
+    Its possible how this feature works may radically change in a future release.
+
+[Manila](https://docs.openstack.org/manila/latest/) is the OpenStack service for providing shared
+read-write-many filesystems for OpenStack workloads.
+
+## Project share
+
+!!! warning  "Limited platform support"
+
+    Currently, only the `Slurm` and `Linux Workstation` platforms support the project share.
+
+    Support for the other reference platforms is planned for the future.
+
+!!! warning  "Limited share type and protocol support"
+
+    Azimuth will use the default share type for the project, unless there is only one share type
+    available. Azimuth also assumes that this share type supports the CephFS share protocol.
+
+When Manila is available, Azimuth is able to provide a filesystem to platforms that is shared
+across all the platforms in a project, and persists beyond the lifetime of any single platform.
+The shared filesystem is mounted at `/project` within each platform, and data written to `/project`
+by one platform will be available to all the other platforms.
+
+To enable project shares in Azimuth, set the following variable to the size (in GB) that you want
+to use for the project shares:
+
+```yaml  title="environments/my-site/inventory/group_vars/all/variables.yml"
+azimuth_openstack_manila_project_share_gb: 100
+```
+
+For example, with this configuration Azimuth will ensure that a 100GB Manila share exists for each
+tenancy and make that available to platforms.
+
+!!! warning  "Resizing of shares is not supported"
+
+    If you increase the share size in your Azimuth configuration, new shares will be created at
+    the new size but existing shares **will not** be resized.
+
+    Existing shares can be resized manually using the OpenStack CLI or Horizon dashboard.
+
+Ansible-based platforms will receive the following variables that can be use to configure the share:
+
+```yaml
+cluster_project_manila_share: true
+cluster_project_manila_share_name: "azimuth-project-share"
+cluster_project_manila_share_user: "proj-<project_id>"
+```
+
+!!! warning  "Project shares are not backed up"
+
+    There is no automated backup or snapshotting of project shares.
+
+## Storage network automation
+
+In order to access a Manila share, platforms need to be able to route to the storage service that
+is providing the share. This often requires an additional network to be attached to the machines
+that make up a platform.
+
+Azimuth has the ability to detect and attach an additional network that is used for connecting
+to storage. Similar to the
+[internal and external network detection](./index.md#networking-configuration), Azimuth uses the
+[Neutron resource tag](https://docs.openstack.org/neutron/latest/contributor/internals/tag.html)
+`portal-storage` to identify the storage network.
+
+If the storage network supports
+[SR-IOV](https://en.wikipedia.org/wiki/Single-root_input/output_virtualization), Azimuth is also
+able to utilise this which can improve performance when talking to the storage.
+
+When Azimuth finds a network with the `portal-storage` tag, Ansible-based platforms will receive
+the following Ansible variable containing the name of the network, allowing them to connect a
+second NIC to it:
+
+```yaml
+cluster_storage_network: "name-of-portal-storage-network"
+```
+
+To specify that SR-IOV should be used on this network, set the following in your Azimuth
+configuration:
+
+```yaml  title="environments/my-site/inventory/group_vars/all/variables.yml"
+azimuth_caas_operator_global_extravars_overrides:
+  cluster_storage_vnic_type: direct
+```
+
+Additional Kubernetes templates can also be defined that are aware of the storage network - see
+[Custom cluster templates](../10-kubernetes-clusters.md#custom-cluster-templates) for an example.

docs/configuration/04-target-cloud.md renamed to docs/configuration/04-target-cloud/index.md

@@ -75,45 +75,46 @@ azimuth_capi_operator_cluster_templates_default: {}
 ### Custom cluster templates
 
 If you want to include custom cluster templates in addition to the default templates,
-e.g. for advanced networking configurations, you can specify them using the variable
-`azimuth_capi_operator_cluster_templates_extra`.
+e.g. for
+[accessing Manila shares](./04-target-cloud/02-openstack-manila.md#storage-network-automation),
+you can specify them using the variable `azimuth_capi_operator_cluster_templates_extra`.
 
 For example, the following demonstrates how to configure a template where the cluster
 worker nodes have two networks attached - the control plane nodes and workers are all
 attached to the Azimuth internal network but the workers are attached to an additional
-SR-IOV capable network:
+SR-IOV capable storage network:
 
 ```yaml  title="environments/my-site/inventory/group_vars/all/variables.yml"
 azimuth_capi_operator_cluster_templates_extra:
   # The index in the dict is the template name
-  kube-1-24-2-multinet:
+  kube-1-31-2-multinet:
     # Access control annotations
     annotations: {}
     # The cluster template specification
     spec:
       # A human-readable label for the template
-      label: v1.24.2 / multinet
+      label: v1.31.2 / multinet
       # A brief description of the template
       description: >-
-        Kubernetes 1.24.2 with HA control plane and high-performance networking.
+        Kubernetes 1.31.2 with HA control plane and high-performance networking.
       # Values for the openstack-cluster Helm chart
       values:
         # Specify the image and version for the cluster
         # These are the only required values
-        kubernetesVersion: 1.24.2
-        machineImageId: "{{ community_images_image_ids.kube_1_24 }}"
+        kubernetesVersion: 1.31.2
+        machineImageId: "{{ community_images_image_ids.kube_1_31 }}"
         # Use the portal-internal network as the main cluster network
         clusterNetworking:
           internalNetwork:
             networkFilter:
               tags: portal-internal
-        # Configure an extra SR-IOV port on worker nodes using an SR-IOV capable network
+        # Configure an extra SR-IOV port on worker nodes on the storage network
         nodeGroupDefaults:
           machineNetworking:
             ports:
               - {}
               - network:
-                  tags: sriov-vlan
+                  tags: portal-storage
                 securityGroups: []
                 vnicType: direct
 ```

docs/configuration/10-kubernetes-clusters.md

@@ -17,7 +17,10 @@ nav:
       - configuration/01-prerequisites.md
       - configuration/02-deployment-method.md
       - configuration/03-kubernetes-config.md
-      - configuration/04-target-cloud.md
+      - 'Target OpenStack cloud':
+          - configuration/04-target-cloud/index.md
+          - configuration/04-target-cloud/01-openstack-blazar.md
+          - configuration/04-target-cloud/02-openstack-manila.md
       - configuration/05-secret-key.md
       - configuration/06-ingress.md
       - configuration/07-platform-identity.md