Merge pull request #297 from appuio/ocp-942/ref-architecture-exoscale

Add Exoscale architecture reference documentation

docs/modules/ROOT/pages/references/exoscale/architecture.adoc

@@ -0,0 +1,96 @@
+:infra-type: Exoscale
+:infra-svg: ocp4-architecture-exoscale.svg
+= APPUiO Managed OpenShift 4 on {infra-type}
+
+== Architecture overview
+
+include::partial$architecture/overview.adoc[]
+
+== {infra-type} requirements
+
+APPUiO Managed OpenShift 4 on {infra-type} needs a https://docs.openshift.com/container-platform/4.14/installing/installing_bare_metal/installing-bare-metal.html#installation-load-balancing-user-infra_installing-bare-metal[Load Balancer setup] that must meet the following requirements:
+
+1. API load balancer: Provides a common endpoint to interact with OpenShift and Kubernetes.
+
+2. Ingress load balancer: Provides an endpoint for application traffic flowing in from outside the cluster.
+
+See the https://docs.openshift.com/container-platform/latest/installing/installing_bare_metal/installing-bare-metal.html#installation-requirements-user-infra_installing-bare-metal[upstream documentation] for details on {infra-type} requirements.
+
+
+== Networking
+
+=== Security Groups
+
+On {infra-type}, APPUiO Managed OpenShift 4 uses public IPs for each node in the cluster.
+See https://kb.vshn.ch/oc4/explanations/exoscale/limitations.html#_private_networks[Limitations] of the {infra-type} environment.
+
+The individual VMs are placed in https://community.exoscale.com/documentation/compute/security-groups[Security Groups] to restrict access and isolate the nodes from the public internet.
+
+NOTE: On the {infra-type} environment there is no single stable egress IP. Every node uses a dynamic public IP for egress traffic, which it's not suited for any forms of whitelisting.
+
+=== Virtual IPs
+
+To expose applications and the Kubernetes API outside the cluster, APPUiO Managed OpenShift 4 manages two floating IPs:
+
+1. The "API VIP" for the Kubernetes and OpenShift API.
+APPUiO Managed OpenShift 4 uses a public floating IP as the API VIP.
+2. The "Ingress VIP" for the OpenShift Ingress Router
+APPUiO Managed OpenShift 4 uses a public floating IP as the Ingress VIP.
+
+APPUiO Managed OpenShift 4 uses two Load Balancer instances to manage the API and ingress VIPs and distributes traffic to the master / infrastructure nodes.
+
+=== Pod and service networks
+
+include::partial$architecture/networking-pods.adoc[]
+
+=== Exposing the cluster
+
+We provide a CNAME target record to point additional DNS records to.
+
+=== External services
+
+include::partial$architecture/networking-external.adoc[]
+
+== Storage
+
+include::partial$architecture/storage.adoc[]
+
+== Glossary
+
+=== Components {infra-type}
+
+[cols="1,3,1"]
+|===
+|Name|Description|provided by
+
+|Security Group
+a|Exoscale Security Groups provide a modular way to define and compose firewall rules.
+
+Security Groups hold two different types of information:
+* A list of rules to apply to traffic
+* A list of member instances in the security group which allows using groups as traffic sources or destinations in rules
+
+See https://community.exoscale.com/documentation/compute/security-groups[Upstream Documentation].
+
+|{infra-type}
+
+|S3 compatible storage
+a|Various OpenShift components require S3 compatible storage.
+This storage is provided by {infra-type}.
+
+The main APPUiO Managed OpenShift 4 components that use object storage are
+
+* OpenShift integrated image registry
+* OpenShift logging stack
+* APPUiO Managed cluster backups
+|{infra-type}
+
+|===
+
+=== Components General
+
+include::partial$architecture/glossary-general.adoc[]
+
+=== Other terms
+
+include::partial$architecture/glossary-others.adoc[]

docs/modules/ROOT/partials/architecture/glossary-general.adoc

@@ -32,9 +32,21 @@ If the service network IP range conflicts with existing subnets, the service net
 | VSHN / Cilium
 
 |DNS
-|The APPUiO Managed OpenShift 4 cluster's base DNS records are defined and managed by VSHN.
+a|The APPUiO Managed OpenShift 4 cluster's base DNS records are defined and managed by VSHN.
 All records must be publicly resolvable.
 To expose applications under a customer domain, a CNAME target is provided.
 | VSHN
 
+
+ifeval::["{infra-type}" == "Exoscale"]
+|Storage Cluster
+a|The APPUiO Managed Storage Cluster offers advanced cloud-native storage capabilities for APPUiO Managed OpenShift 4.
+
+This product is based on https://rook.io/[Rook] and uses https://ceph.io/en/[Ceph] as it’s underlying storage technology.
+
+See https://products.vshn.ch/appuio/managed/storage_cluster.html[APPUiO Managed Storage Cluster] product page for more details.
+
+| VSHN / Rook
+endif::[]
+
 |===

docs/modules/ROOT/partials/architecture/storage.adoc

@@ -19,16 +19,27 @@ They're allocated dynamically based on requests from workloads (applications or
 These block devices are automatically attached to the VM hosting the application container.
 They're deleted when the corresponding Kubernetes `PersistentVolume` resource is deleted.
 
+ifeval::["{infra-type}" != "Exoscale"]
 The {infra-type} CSI driver is the in-cluster component which is responsible for allocating, attaching and deleting the persistent volume block devices.
+endif::[]
+
+ifeval::["{infra-type}" == "Exoscale"]
+IMPORTANT: {infra-type} does not provide storage usable by Kubernetes as persistent volumes.
+To fill this gap, {product} in {intra-type} uses https://products.vshn.ch/appuio/managed/storage_cluster.html[APPUiO Managed Storage Cluster] to provide storage to be used as read write once and read write many persistent volumes.
+endif::[]
 
 These devices hold application data, but backups are usually done from within the cluster.
 
 === S3 compatible object storage
 
 Various OpenShift components, such as the integrated image registry, the logging stack and backups, require S3 compatible object storage.
-The customer or vSphere infrastructure operator must provide S3 compatible object storage.
+ifeval::["{infra-type}" != "Exoscale"]
+ifeval::["{infra-type}" != "cloudscale.ch"]
+The customer or {infra-type} infrastructure operator must provide S3 compatible object storage.
 Most modern storage solutions offer some object storage functionality.
 
 If https://products.vshn.ch/appcat/index.html[VSHN's Application Catalog (AppCat)] offering is required on the cluster, the object storage must support automatic bucket creation via an AppCat-supported provisioner.
 
 NOTE: If no object storage is available, we can use external object storage as a fallback.
+endif::[]
+endif::[]

docs/modules/ROOT/partials/nav.adoc

@@ -14,7 +14,7 @@
 ** xref:oc4:ROOT:references/architecture/metering-data-flow-appuio-managed.adoc[Resource Usage Reporting]
 ** xref:oc4:ROOT:references/architecture/single_sign_on.adoc[]
 
-** Exoscale
+** xref:oc4:ROOT:references/exoscale/architecture.adoc[Exoscale]
 *** xref:oc4:ROOT:explanations/exoscale/limitations.adoc[Limitations]
 
 ** Google Cloud Platform
@@ -40,6 +40,7 @@
 *** xref:oc4:ROOT:how-tos/cloudscale/decommission.adoc[Decommissioning]
 
 ** Exoscale
+*** xref:oc4:ROOT:references/exoscale/architecture.adoc[Architecture]
 *** xref:oc4:ROOT:references/exoscale/config.adoc[Configuration]
 *** xref:oc4:ROOT:how-tos/exoscale/install.adoc[Install]
 // Node management