Merge pull request #57 from stakater/service-definition

Service definition and Tiltfile

README.md

@@ -6,44 +6,74 @@ SAAP docs are built using [MkDocs](https://github.com/mkdocs/mkdocs) which is ba
 
 This repository has Github action workflow which checks the quality of the documentation and builds the Dockerfile image on Pull Requests. On a push to the main branch, it will create a GitHub release and push the built Dockerfile image to an image repository.
 
-## Build Dockerfile image and run container
+## Build locally
+
+There are at least three options to get fast continuous feedback during local development:
+
+1. Build and run the docs using the Dockerfile image
+1. Run the commands locally
+1. Use Tilt
 
-Build Dockerfile image:
+### Build Dockerfile image and run container
 
-```shell
+Build Dockerfile test image:
+
+```bash
 $ docker build . -t test
 ```
 
-Run container:
+Run test container:
 
-```shell
+```bash
 $ docker run -p 8080:8080 test
 ```
 
 Then access the docs on [`localhost:8080`](localhost:8080).
 
-## Build locally
-
-It is preferred to build and run the docs using the Dockerfile image, however an alternative is to run the commands locally.
+### Run commands locally
 
 Use [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/install.html) to set up Python virtual environments.
 
 Install [Python 3](https://www.python.org/downloads/).
 
 Install mkdocs-material and mermaid plugin:
 
-```sh
+```bash
 $ pip3 install mkdocs-material mkdocs-mermaid2-plugin
 ```
 
 Finally serve the docs using the built-in web server which is based on Python http server - note that the production build will use Nginx instead:
 
-```
+```bash
 $ mkdocs serve
 ```
 
 or 
 
-```
+```bash
 $ python3 -m mkdocs serve 
-```
+```
+
+### QA Checks
+
+Markdown linting:
+
+```bash
+$ brew install markdownlint-cli
+$ markdownlint -c .markdownlint.yaml content
+```
+
+Spell checking:
+
+```bash
+$ brew install vale
+$ vale content
+```
+
+## Use Tilt
+
+Install [Tilt](https://docs.tilt.dev/index.html), then run:
+
+```bash
+$ tilt up
+```

Tiltfile

@@ -0,0 +1,22 @@
+local_resource('install vale',
+                cmd='which vale > /dev/null || brew install vale')
+local_resource('spell check with vale',
+                cmd='vale content',
+                deps='./content/',
+                resource_deps=['install vale'])
+
+local_resource('install markdownlint',
+                cmd='which markdownlint > /dev/null || brew install markdownlint-cli')
+local_resource('markdownlint',
+                cmd='markdownlint -c .markdownlint.yaml content',
+                deps='./content/',
+                resource_deps=['install markdownlint'])
+
+local_resource('build test image',
+               cmd='docker build -t test .',
+               deps='./content/',
+               resource_deps=['spell check with vale', 'markdownlint'])
+
+local_resource('run test container',
+               cmd='docker run -d -p 8080:8080 test',
+               resource_deps=['build test image'])

content/about/cloud-providers/overview.md

@@ -1,14 +1,15 @@
 # Overview
 
-Stakater App Agility Platform (SAAP) is currently supported on following cloud providers:
+Stakater App Agility Platform (SAAP) supports all clouds which are based on OpenStack, VMWare or BareMetals:
 
-* [Azure](./azure.md)
 * [AWS](./aws.md)
-* [Google](./gcp.md)
+* [Azure](./azure.md)
 * [Binero](./binero.md)
-* [UpCloud](./upcloud.md)
-* [Exoscale](./exoscale.md)
 * [Complior](./complior.md)
 * [Elastx](./elastx.md)
+* [Exoscale](./exoscale.md)
+* [GCP](./gcp.md)
+* [SafeSpring](./safespring.md)
+* [UpCloud](./upcloud.md)
 
-We support all sorts of clouds which are based on OpenStack, VMWare or BareMetals; just drop us an email at [`[email protected]`](mailto:[email protected]) if you would like to include your cloud!
+Just drop us an email at [`[email protected]`](mailto:[email protected]) if you would like to partner up with another cloud!

content/about/saap-key-differentiators.md

@@ -1,6 +1,6 @@
 # Key Differentiators
 
-Stakater App Agility Platform is a true hybrid-cloud enabler. All components of Stakater App Agility Platform use common standards which can run on any cloud service, so it is easy for you to run in a hybrid environment, as well as migrate from one cloud to another. We don’t just run the platform, we enable it for you, giving you substantial Return on your Investment
+Stakater App Agility Platform is a true hybrid-cloud enabler. All components of Stakater App Agility Platform use common standards which can run on any cloud service, so it is easy for you to run in a hybrid environment, as well as migrate from one cloud to another. We don't just run the platform, we enable it for you, giving you substantial Return on your Investment
 
 - We support infra nodes, i.e. we fully manage nodes that run all managed addons of your choice.
 - We manage the addons as well; and provide SLA on them.

content/about/service-definition/account-management.md

@@ -2,14 +2,16 @@
 
 ## Billing
 
+SAAP requires a minimum base cluster purchase with minimum technical requirements specified in [Sizing](../../for-administrators/plan-your-environment/sizing.md).
+
+Customers can either use their existing cloud infrastructure account to deploy SAAP, or use one of Stakater's partners to create infrastructure. The customer always pays Stakater for the SAAP subscription and pays the cloud provider for the cloud costs. It is the customer's responsibility to pre-purchase or provide compute instances to ensure lower cloud infrastructure costs.
+
+Billing for SAAP is on a monthly basis, or yearly basis with discounts.
+
 ## Cloud Providers
 
-SAAP is available as a managed service on the following cloud providers:
+SAAP is available as a managed platform on the cloud providers listed on the [cloud providers overview](../cloud-providers/overview.md).
 
-- Amazon Web Services (AWS)
-- Google Cloud Platform (GCP)
-- Azure
-- Binero
-- UpCloud
+## Cluster Creation
 
-## Cluster Provisioning
+The administrative section contains information about [cluster creation](../../for-administrators/create-your-cluster.md).

content/about/service-definition/logging.md

@@ -2,14 +2,14 @@
 
 SAAP provides an optional integrated log forwarding to log store.
 
-## Cluster audit logging
+## Cluster Audit Logging
 
-Cluster audit logs are available through log store, if the integration is enabled. If the integration is not enabled, you can request the audit logs by opening a support case.
+Cluster audit logs are available through log store, if the integration is enabled. If the integration is not enabled, you can request the audit logs by opening a [support ticket](https://support.stakater.com/index.html).
 
-## Application logging
+## Application Logging
 
 Application logs sent to `STDOUT` are collected by log collector and forwarded to log store through the cluster logging stack, if it is installed.
 
-## Data retention
+## Data Retention
 
-By default only 7 days data is kept; and if you want to store for long term then open a support case.
+By default only 7 days data is kept; if you want to store data for longer then open a [support ticket](https://support.stakater.com/index.html).

content/about/service-definition/monitoring.md

@@ -2,14 +2,14 @@
 
 This section provides information about the service definition for SAAP monitoring.
 
-## Cluster metrics
+## Cluster Metrics
 
-SAAP instances come with an integrated Prometheus stack for cluster monitoring including CPU, memory, and network-based metrics. This is accessible through the web console. These metrics also allow for horizontal pod autoscaling based on CPU or memory metrics.
+SAAP come with an integrated Prometheus stack for cluster monitoring including CPU, memory, and network-based metrics. This is accessible through the SAAP web console. These metrics also allow for horizontal pod autoscaling based on CPU or memory metrics.
 
-## Application monitoring
+## Application Monitoring
 
 SAAP provides an optional application monitoring stack based on Prometheus to monitor business critical applications. This allows for adding scrape targets in user namespaces.
 
-## Data retention
+## Data Retention
 
-By default only 7 days data is kept; and if you want to store for long term then open a support case.
+By default only seven (7) days data is kept; if you want to store data for longer then open a [support ticket](https://support.stakater.com/index.html).

content/about/service-definition/networking.md

@@ -1,21 +1,43 @@
 # Networking
 
-## Custom domains for applications
+## Custom Domains for applications
 
-To use a custom hostname for a route, you must update your DNS provider by creating a canonical name (CNAME) record. Your CNAME record should map the OpenShift canonical router hostname to your custom domain. The OpenShift canonical router hostname is shown on the Route Details page after a Route is created. Alternatively, a wildcard CNAME record can be created once to route all subdomains for a given hostname to the cluster’s router.
+To use a custom hostname for a route, you must update your DNS provider by creating a canonical name (CNAME) record. Your CNAME record should map the SAAP canonical router hostname to your custom domain. The SAAP canonical router hostname is shown on the Route Details page after a Route is created. Alternatively, a wildcard CNAME record can be created once to route all subdomains for a given hostname to the cluster's router.
 
 ## Custom domains for cluster services
 
-Custom domains and subdomains are not available for the platform service routes, for example, the API or web console routes, or for the default application routes.
+Custom domains and subdomains for cluster services are available except for the SAAP service routes, for example, the API or web console routes, or for the default application routes.
 
 ## Domain validated certificates
 
-SAAP includes TLS security certificates needed for both internal and external services on the cluster. For external routes, there are two, separate TLS wildcard certificates that are provided and installed on each cluster, one for the web console and route default hostnames and the second for the API endpoint. Let’s Encrypt is the certificate authority used for certificates. Routes within the cluster, for example, the internal API endpoint, use TLS certificates signed by the cluster’s built-in certificate authority and require the CA bundle available in every pod for trusting the TLS certificate.
+SAAP includes TLS security certificates needed for both internal and external services on the cluster. For external routes, there are two, separate TLS wildcard certificates that are provided and installed on each cluster, one for the web console and route default hostnames and the second for the API endpoint. Let's Encrypt is the certificate authority used for certificates. Routes within the cluster, for example, the internal API endpoint, use TLS certificates signed by the cluster's built-in certificate authority and require the CA bundle available in every pod for trusting the TLS certificate.
 
 ## Load-balancers
 
-## Network usage
+SAAP is normally created via the installer provisioned infrastructure (IPI) installation method which installs operators that manage load-balancers in the customer cloud, and API load-balancers to the master nodes. Application load-balancers are created as part of creating routers and ingresses. The operators use cloud identities to interact with the cloud providers API to create the load-balancers.
+
+User-provisioned installation (UPI) method is also possible if extra security is needed and then you must create the API and application ingress load balancing infrastructure separately and before SAAP is installed.
+
+SAAP has a default router/ingress load-balancer that is the default application load-balancer, denoted by `apps` in the URL. The default load-balancer can be configured in SAAP to be either publicly accessible over the internet, or only privately accessible over a pre-existing private connection. All application routes on the cluster are exposed on this default router load-balancer, including cluster services such as the logging UI, metrics API, and registry.
+
+SAAP has an optional router/ingress load-balancer that is a secondary application load-balancer, denoted by `apps2` in the URL. The secondary load-balancer can be configured in SAAP to be either publicly accessible over the internet, or only privately accessible over a pre-existing private connection. If a 'Label match' is configured for this router load-balancer, then only application routes matching this label will be exposed on this router load-balancer, otherwise all application routes are also exposed on this router load-balancer.
+
+SAAP has optional load-balancers for services that can be mapped to a service running on SAAP to enable advanced ingress features, such as non-HTTP/SNI traffic or the use of non-standard ports. Cloud providers may have a quota that limits the number of load-balancers that can be used within each cluster.
+
+## Network use
+
+Network use is not monitored, and is billed directly by the cloud provider.
 
 ## Cluster ingress
 
+Project administrators can add route annotations for ingress control through IP allow-listing.
+
+Ingress policies can also be changed by using `NetworkPolicy` objects.
+
+All cluster ingress traffic goes through the defined load-balancers. Direct access to all nodes is blocked by cloud configuration.
+
 ## Cluster egress
+
+`EgressNetworkPolicy` objects can control pod egress traffic to prevent or limit outbound traffic in SAAP.
+
+Public outbound traffic from the control plane and infrastructure nodes is required and necessary to maintain cluster image security and cluster monitoring. This requires the `0.0.0.0/0` route to belong only to the internet gateway.

content/about/service-definition/overview.md

@@ -1,20 +1,23 @@
 # Overview
 
-This section outlines the service definition for the SAAP:
+This section outlines the service definition for Stakater App Agility Platform (SAAP):
 
-1. [Managed Kubernetes (Red Hat OpenShift)](platform.md)
-2. [Managed Monitoring Stack (Prometheus, Grafana, Alert Manager)](monitoring.md)
-3. [Managed Logging Stack (Fluentd, Vector, ElasticSearch, Kibana)](logging.md)
-4. Managed Container Registry (Nexus)
-5. Managed Artifacts Store (Nexus)
-6. Managed Backup Restore (Velero)
-7. [Managed Secrets Management (Vault)](secrets-management.md)
-8. Managed Multi-tenancy (MTO)
-9. Managed Service Mesh (`Istio`, `Kiali`, `Jagaer`, `Prometheus`)
-10. Managed Certs
-11. Managed CD (ArgoCD)
-12. Managed CI (Tekton)
-13. Managed Policy Enforcement (Gatekeeper, OPA)
-14. Managed Downtime Alerting (IMC, UptimeRobot)
-15. Managed Dynamic Environments (Tronador)
-16. Managed Dynamic Application Reload (Reloader)
+1. [Managed Kubernetes (Red Hat OpenShift)](./platform.md)
+1. [Account Management](./account-management.md)
+1. [Storage](./storage.md)
+1. [Security](./security.md)
+1. [Networking](./networking.md)
+1. [Managed Monitoring Stack (Prometheus, Grafana, Alert Manager, UptimeRobot)](./monitoring.md)
+1. [Managed Logging Stack (Fluentd, Vector, ElasticSearch, Kibana)](./logging.md)
+1. [Managed Container Registry and Artifact Store (Nexus)](../../managed-addons/nexus/overview.md)
+1. [Managed Backup Restore (Velero)](../../managed-addons/velero/overview.md)
+1. [Managed Secrets Management (Vault)](./secrets-management.md)
+1. [Managed Multi-tenancy (MTO)](../../managed-addons/mto/overview.md)
+1. [Managed Service Mesh (`Istio`, `Kiali`, `Jagaer`, `Prometheus`)](./service-mesh.md)
+1. [Managed Certificates](../../managed-addons/cert-manager/overview.md)
+1. [Managed Continuous Delivery (ArgoCD)](../../managed-addons/argocd/overview.md)
+1. [Managed Continuous Integration (Tekton)](../../managed-addons/tekton/introduction.md)
+1. [Managed Policy Enforcement (Kyverno, OPA)](../../for-cisos/policies/policies.md)
+1. [Managed Downtime Alerting (IMC)](../../managed-addons/imc/overview.md)
+1. [Managed Dynamic Environments (Tronador)](../../managed-addons/tronador/overview.md)
+1. [Managed Dynamic Application Reload (Reloader)](../../managed-addons/reloader/overview.md)

content/about/service-definition/platform.md

@@ -2,11 +2,11 @@
 
 ## Autoscaling
 
-Node autoscaling is available on few clouds; you can find details in the relevant cloud section. You can configure the autoscaler option to automatically scale the number of machines in a cluster.
+Node autoscaling is available on few clouds; you can find details in the relevant [cloud section](../cloud-providers/overview.md). You can configure the autoscaler option to automatically scale the number of machines in a cluster.
 
 ## Daemonsets
 
-Customers can create and run daemonsets on SAAP. To restrict daemonsets to only running on worker nodes, use the following `nodeSelector`:
+Customers can create and run daemonsets on SAAP. To restrict daemonsets to only run on worker nodes, use the following `nodeSelector`:
 
 ```yaml
 ...
@@ -16,40 +16,36 @@ spec:
 ...
 ```
 
-## Multiple availability zone
+## Multiple Availability Zone
 
 In a multiple availability zone cluster, control plane nodes are distributed across availability zones and at least one worker node is required in each availability zone.
 
-## Node labels
+## Node Labels
 
 Custom node labels are created by Stakater during node creation and cannot be changed on SAAP at this time. However, custom labels are supported when creating new machine pools.
 
-## OpenShift version
+## OpenShift Version
 
-SAAP is run as a managed service and is kept up to date with the latest OpenShift Container Platform version. Upgrade scheduling to the latest version is available.
+SAAP is run as a managed service and is kept up to date with the latest OpenShift Container Platform version, see [change management in responsibilities](../responsibilities.md#change-management). Upgrade scheduling to the latest version is available.
 
-## Container engine
+## Container Engine
 
 SAAP runs on OpenShift 4 and uses [CRI-O](https://www.redhat.com/en/blog/red-hat-openshift-container-platform-4-now-defaults-cri-o-underlying-container-engine) as the only available container engine.
 
-## Operating system
+## Operating System
 
 SAAP runs on OpenShift 4 and uses Red Hat CoreOS as the operating system for all control plane and worker nodes.
 
-## Windows Containers
-
-Red Hat OpenShift support for Windows Containers is not available on SAAP at this time.
-
 ## Upgrades
 
-Upgrades can be scheduled by opening a [support case](https://support.stakater.com/index.html).
+Upgrades can be done either immediately or be scheduled at a specific date by opening a [support ticket](https://support.stakater.com/index.html).
 
-See the [SAAP Life Cycle](../update-lifecycle.md) for more information on the upgrade policy and procedures.
+See the [SAAP Update Life Cycle](../update-lifecycle.md) for more information on the upgrade policy and procedures.
 
-## Kubernetes Operator support
+## Kubernetes Operator Support
 
-All Operators listed in the Operator Hub marketplace should be available for installation. These operators are considered customer workloads, and are not monitored by Stakater SRE.
+All operators listed in the [Operator Hub marketplace](https://operatorhub.io/) should be available for installation. These operators are considered customer workloads, and are not monitored by Stakater SRE, see [customer applications responsibilities](../responsibilities.md#data-and-applications).
 
-## Red Hat Operator support
+## Red Hat Operator Support
 
-Red Hat workloads typically refer to Red Hat-provided Operators made available through Operator Hub. Red Hat workloads are not managed by the Stakater SRE team, and must be deployed on worker nodes and must be managed by the customer.
+Red Hat workloads typically refer to Red Hat-provided operators made available through [Operator Hub](https://operatorhub.io/). Red Hat workloads are not managed by the Stakater SRE team, and must be deployed on worker nodes and must be managed by the customer, see [customer applications responsibilities](../responsibilities.md#data-and-applications).