Added markdown docs

docsmd/clowder-design.md

@@ -0,0 +1,97 @@
+# Clowder Design
+
+## Problem Statement
+
+Engineers have a steep learning curve when they start writing their first
+application for cloud.redhat.com, particularly if they're unfamiliar working in
+a cloud-native environment before.
+
+Additionally, enforcing standards and consistency across cloud.redhat.com
+applications is difficult because of the number of disparate teams across the
+enterprise that contribute to the ecosystem.
+
+Similar to application consistency, it is difficult for engineers to be able to
+handle the inconsistencies between environments, e.g local development versus
+production. While these differences can never be fully eliminated, ideally
+developers would not have to devise their own solutions to handle these
+differences.
+
+## Mission
+
+Clowder aims to abstract the underlying Kubernetes environment and configuration
+to simplify the creation and maintenance of applications on cloud.redhat.com.
+
+## Goals
+
+* Abstract Kubernetes environment and configuration details from applications
+* Enable engineers to deploy their application in every Kubernetes environment
+ (i.e. dev, stage, prod) with minimal changes to their custom resources.
+* Increase operational consistency between cloud.redhat.com applications,
+ including rollout parameters and pod affinity.
+* Handle metrics configuration and standard SLI/SLO metrics and alerts
+* Some form of progressive deployment
+
+## Non-goals
+
+* Support applications outside cloud.redhat.com
+
+## Proposal
+
+Build a single operator that handles the common use cases that cloud.redhat.com
+applications have. These use cases will be encoded into the API of the
+operator, which is of course CRDs. There will be two CRDs:
+
+* ``ClowdEnvironment``
+This CR represents an instance of the entire cloud.redhat.com environment,
+e.g. stage or prod. It contains configuration for various aspects of the
+environment, implemented by *providers*.
+
+* ``ClowdApp`` This CR represents a all the configuration an app needs to be deployed into
+the cloud.redhat.com environment, including:
+
+ * One or more deployment specs
+ * Kafka topics
+ * Databases
+ * Object store buckets (e.g. S3)
+ * In-memory DBs (e.g. Redis)
+ * Public API endpoint name(s)
+ * SLO/SLI thresholds
+
+
+How these CRs will be translated into lower level resource types:
+
+![Clowder Flow](img/clowder-flow.svg)
+
+Apps will consume their environmental configuration from a JSON document mounted
+in their app container. This JSON document contains the various configuration
+that could be considered common across the platform or common kinds of resources
+that would be requested by an app on the platform, including:
+
+* Kafka topics
+* Connection information for Kafka, object storage, databases, and in-memory DBs
+* Port numbers for metrics and webservices
+* Public API endpoint prefix
+
+Common configuration interface:
+
+![Clowder Common Interface](img/clowder-new.svg)
+
+## Alternatives
+
+* One operator per app, perhaps with a shared library between them
+ * While this proposal falls neatly in the "app teams are responsible for the
+ operation of their app" mantra, the overhead of having each team build and
+ maintain their own operator is considered too high. The design proposed in
+ this document helps draw the boundary between the responsibilities of the
+ Cloud Dot platform team and the teams that build apps on that platform.
+
+* One operator with a CRD for each app
+ * While this would provide significantly more flexibility for teams to
+ configure their apps, many app teams would not add any custom attributes,
+ thus essentially making their custom CRDs boilerplate code. In addition,
+ teams that did in fact add custom fields would then have to maintain the
+ code required to reconcile them.
+
+The design proposed in this document is intentionally opinionated and makes
+choices on behalf of apps because more often than not dev teams do not have
+strong preferences on many operational aspects of their application.