Merge pull request #178 from robszumski/long-term

Add long term goals to design docs

Author: robszumski

doc/design/long-term/norms-to-follow.md

@@ -0,0 +1,17 @@
+## SDK examples/docs show API norms authors should follow
+
+**Goal:** Help Operator authors avoid common mistakes and usability issues that the community has learned through the various operators in use today.
+
+**Problem:** There are three classes of mistakes that we have seen folks make:
+1. Methods for connecting Kubernetes objects through labels, OwnerRefs, status etc that may be incompatible with future updates or too restrictive in the long term.
+2. Attempting to add in remote connectivity directly into the Operator via an HTTP API. The Kubernetes API should be the source of desired state.
+3. Requiring state that is not stored within the cluster to operate safely.
+
+**Why is this important:** The SDK will be successful if it solves problems for developers out of the box. Shipping updates and new features safely via an Operator is only possible when they are deployed and used correctly.
+
+**Proposed work streams to accomplish this:**
+ - Documentation for dos and don’ts for an Operator
+ - Canonical sample operator that shows a complex use-case done correctly
+
+**Open questions:**
+1. How much of the object organization is done via helper code in the SDK vs well-planned label queries and OwnerRefs by the developer?

doc/design/long-term/simple-extensions.md

@@ -0,0 +1,20 @@
+## Simple Operator Extensions
+
+**Goal:** ISVs choose the Operator SDK to ship their apps because it provides OOTB extensions for common enterprise asks, like audit logging, handling TLS, monitoring, etc. The SDK provides these capabilities as libraries that can be easily inserted into your business logic where it makes sense.
+
+**Problem:** Kubernetes provides the unified stack that software vendors strive for. However, each vendor is left to writing code to utilize platform features. This leads to custom solutions, incorrect usage and security flaws. It’s impossible for one engineering team to be an expert in logging, monitoring, security, etc in addition to software they are providing.
+
+**Why is this important:** The SDK should be solving hard problems and saving folks time. Vendors have different needs, and should be able to plug and play different features as they require them.
+
+**Proposed work streams to accomplish this:**
+1. Provide methods for generating and storing TLS assets as secrets
+2. Operator emits Prometheus metrics by default and optional other ones can be created
+3. Ship default logging for generated code and methods for adding more
+4. Authentication/Authorization
+	- example: deploy a database and provide access to a specific set of Kubernetes users with the same credentials
+5. Backup/Restore hooks
+	- example: before/after upgrade
+6. Provide hooks into the Kubernetes audit log and event stream
+
+**Open questions:**
+  - none so far

doc/design/long-term/testing-operators.md

@@ -0,0 +1,19 @@
+## Make testing an Operator simple and easy
+
+**Goal:** Make local development of Operators easy, so software vendors can produce high quality software. 
+Make functional tests easy to integrate into a big matrix (upstream, OpenShift, GKE, etc) since we want the SDK to work equally well on all platforms.
+
+**Problem:** Operators are inherently tied to a clustered environment, which complicates testing. Running a full cluster locally can be hard, and requiring a remote cluster is clunky. Aside from a single test cluster, running your Operator against the range of Kubernetes offering requires a ton of industry knowledge and expertise.
+ 
+**Why is this important:** We think Operators are the best way to ship software on Kubernetes. This will naturally happen if we provide methods to build high quality software, of which testing is a huge part.
+
+**Proposed work streams to accomplish this:**
+ - Mock clients to enable unit testing without Kubernetes in under a second
+ - Functional testing is run against X last releases via platform scripts in codebase
+ - SDK provides a method to generate a functional testing container
+ - Docs for using a test container and setting it up against a number of providers for use in a partners CI environment
+ - Provide a way to run the Operator binary locally outside of a container
+    - Eg. https://github.com/coreos/operator-sdk/issues/142
+
+**Open questions:**
+  - none so far