doc: Update philosophy document (#3333)

This commit updates the Contour philosophy document, as our position
on how we make settings configurable hss evolved since it was first
written.

Also, gets rid of those stupid smart quotes.

Signed-off-by: Nick Young <[email protected]>

site/_resources/philosophy.md

@@ -12,6 +12,7 @@ Contour is not a service mesh, nor is it the intention for Contour to expose all
 
 Contour is not intended for proxying layer 4 protocols such as TCP or UDP except insofar as they are needed to deliver HTTP.
 So, TCP proxying is available, but expects the proxying to be used for passing through HTTPS.
+We made a mistake when naming this, it should be called "TLS Proxying".
 In the future, some UDP support may be added so that we can support QUIC, which uses UDP as a transport.
 Using Contour to proxy raw TCP or UDP traffic may work, but is not the intended usage.
 
@@ -51,17 +52,21 @@ For example, many projects allow network buffer sizes to be configured arbitrari
 In providing the tools, but little or no guidance on how they should be used, infinitely tweakable knobs forces the burden of mastering the high dimensional configuration space onto the end users of the product.
 The secondary impact on support teams and the upstream development team should not be discounted, both in terms of difficulty in diagnosing problems, and the possibility of configuration drift between environments.
 
-Contour takes the position that when there is a sensible default value for an Envoy configuration parameters, Contour will apply it unconditionally.
-We’ve used this position in the past by compressing HTTP response bodies unconditionally, disallowing TLS/1.0, choosing an aggressive cipher suite, and so on.
+Contour takes the position that when there is a sensible default value for an Envoy configuration parameters, Contour will apply it.
+We've used this position in the past by compressing HTTP response bodies unconditionally, disallowing TLS/1.0 and 1.1, choosing as secure as possible a default cipher suite, and so on.
 
-Contour will provide a method for the administrator or developer to supply their chosen value as a last resort, in the event that we cannot discover a universally acceptable value.
-In the history of the project this second scenario has rarely occurred.
-More often than not, the discussion sparked by the desire to change a particular parameter has led to a deeper understanding of the ways in which Contour is being used which would not have otherwise occurred.
+When Contour was first developed, generally we stopped there.
+However, users of Contour found that this approach, while excellent for the combined cluster operator/application developer users, was not ideal when the cluster operator had to keep a large production deployment up and running.
+
+Contour still and always will attempt to choose the best default for the largest set of users, but we will allow tweaking of those defaults when requested.
+
+In addition, sometimes it's useful for application developers to be able to override some global defaults.
+When we do allow overriding of defaults, we will do our best to also supply [Gatekeeper](https://github.com/open-policy-agent/gatekeeper) policies and validations to allow cluster operators to limit the *range* of values that app devs may configure.
 
 ### Limited feature scope
 
 The Contour project has a well defined scope: a reverse proxy implementation for HTTP workloads on Kubernetes clusters.
-Contour’s limited support for TCP proxying is intended solely for Contour to to support web applications which desire to handle TLS directly.
+Contour's limited support for TCP proxying is intended solely for Contour to support web applications which desire to handle TLS directly.
 
 ### Every feature is supportable by the application developer or cluster administrator
 
@@ -77,9 +82,9 @@ When designing Kubernetes objects, we try to expose information as close as poss
 For example, we will ensure that HTTPProxy objects have status conditions that tell the user that created them if there is a problem, rather than just logging that information from Contour itself.
 
 ### We meet users where they are
-Contour currently supports Ingress v1beta1, HTTPProxy and IngressRoute.
-In the near future, we’ll add support for Ingress v1 and after that Ingress v2.
-We don’t ask users to choose which ingress API they want to use, instead we will consider providing support for any requested types to meet users wherever they are.
+Contour currently supports Ingress v1beta1, and HTTPProxy.
+In the near future, we'll add support for Ingress v1 and after that the Service-APIs.
+We don't ask users to choose which ingress API they want to use, instead we will consider providing support for any requested types to meet users wherever they are.
 
 This goal is in conflict with the goal of a minimum surface area, but we realize that channeling all our users to an API which is only implemented in Contour is bad for their interoperability and limits our total addressable market.
 The idea for this goal is that we will thoughtfully consider new ingress types as they become available, and add them in if we believe it is a good idea.