Additional doc updates regarding protocol support (#1279)

* Additional doc updates regarding protocol support
* Re-add information about server-speaks-first protocols

Signed-off-by: Kevin Lingerfelt <kl@buoyant.io>

README.md

@@ -11,7 +11,7 @@ control plane written in Go, and a native proxy data plane written in
 [Rust][rust] that boasts the performance of C without the heartbleed.
 
 Conduit is **alpha**. It is capable of proxying all TCP traffic, including
-websockets and HTTP tunneling, and reporting top-line metrics (success rates,
+WebSockets and HTTP tunneling, and reporting top-line metrics (success rates,
 latencies, etc) for all HTTP, HTTP/2, and gRPC traffic.
 
 ## Get involved

doc/adding-your-service.md

@@ -12,10 +12,9 @@ of your application will not be affected.
 
 ## Prerequisites
 
-* Applications that use WebSockets or HTTP tunneling/proxying (use of the HTTP
-  `CONNECT` method), or plaintext MySQL, SMTP, or other protocols where the server
-  sends data before the client sends data, may require additional configuration.
-  See the [Protocol Support](#protocol-support) section below.
+* Applications that use protocols where the server sends data before the client
+  sends data may require additional configuration. See the
+  [Protocol support](#protocol-support) section below.
 * gRPC applications that use grpc-go must use grpc-go version 1.3 or later due
   to a [bug](https://github.com/grpc/grpc-go/issues/1120) in earlier versions.
 
@@ -36,24 +35,30 @@ if its proxy status is green in the Conduit dashboard.
 ### You can always get to the Conduit dashboard by running
 #### `conduit dashboard`
 
-## Protocol Support
+## Protocol support
 
-Conduit supports most applications without requiring any configuration on your
-part. To accomplish this, Conduit automatically detects the protocol used on
-each connection. In some cases, however, Conduit's protocol detection can't be
-fully automated and requires some configuration from you.
+Conduit is capable of proxying all TCP traffic, including WebSockets and HTTP
+tunneling, and reporting top-line metrics (success rates, latencies, etc) for
+all HTTP, HTTP/2, and gRPC traffic.
 
-### MySQL and SMTP
+### Server-speaks-first protocols
 
-Most non-HTTP traffic will also be handled automatically and transparently by
-Conduit without any configuration on your part. However, for protocols where the
-server sends data before the client sends, e.g. MySQL and SMTP connections that
-aren't protected by TLS, Conduit currently requires some manual configuration.
-In such cases, use the `--skip-inbound-ports` flag when running `conduit
-inject`. For pods that make outgoing connections using such protocols, use the
-`--skip-outbound-ports` flag when running `conduit inject`. (Note that this
-applies only to non-TLS'd connections; connections with TLS enabled do not
-require any additional configuration irrespective of protocol.)
+For protocols where the server sends data before the client sends data over
+connections that aren't protected by TLS, Conduit cannot automatically recognize
+the protocol used on the connection. Two common examples of this type of
+protocol are MySQL and SMTP. If you are using Conduit to proxy plaintext MySQL
+or SMTP requests on their default ports (3306 and 22, respectively), then Conduit
+is able to successfully identify these protocols based on the port. If you're
+using non-default ports, or if you're using a different server-speaks-first
+protocol, then you'll need to manually configure Conduit to recognize these
+protocols.
 
-### For example, to allow outbound traffic to port 3306 (MySQL) to bypass the proxy, use the command:
-#### `conduit inject deployment.yml --skip-outbound-ports=3306 | kubectl apply -f -`
+If you're working with a protocol that can't be automatically recognized by
+Conduit, use the `--skip-inbound-ports` and `--skip-outbound-ports` flags when
+running `conduit inject`.
+
+### For example, if your application makes requests to a MySQL database running on port 4406, use the command:
+#### `conduit inject deployment.yml --skip-outbound-ports=4406 | kubectl apply -f -`
+
+### Likewise if your application runs an SMTP server that accepts incoming requests on port 33, use the command:
+#### `conduit inject deployment.yml --skip-inbound-ports=33 | kubectl apply -f -`

doc/getting-started.md

@@ -17,11 +17,10 @@ cluster, and how to set up a sample gRPC application.
 Afterwards, check out the [Using Conduit to debug a service](/debugging-an-app) page,
 where  we'll walk you through how to use Conduit to investigate poorly performing services.
 
-> Note that Conduit v{{% latestversion %}} is an alpha release. Conduit will
-automatically work for most protocols. However, applications that use
-WebSockets, HTTP tunneling/proxying, or protocols such as MySQL and SMTP, will
-require some additional configuration. See [Adding your service to the
-mesh](/adding-your-service) for details.
+> Note that Conduit v{{% latestversion %}} is an alpha release. It is capable of
+proxying all TCP traffic, including WebSockets and HTTP tunneling, and reporting
+top-line metrics (success rates, latencies, etc) for all HTTP, HTTP/2, and gRPC
+traffic.
 
 ____
 

doc/proxy-metrics.md

@@ -1,5 +1,5 @@
 +++
-title = "Proxy Metrics"
+title = "Metrics exported by the proxy"
 docpage = true
 [menu.docs]
   parent = "proxy-metrics"
@@ -9,7 +9,7 @@ The Conduit proxy exposes metrics that describe the traffic flowing through the
 proxy.  The following metrics are available at `/metrics` on the proxy's metrics
 port (default: `:4191`) in the [Prometheus format][prom-format]:
 
-# Protocol-Level Metrics
+## Protocol-Level Metrics
 
 ### `request_total`
 
@@ -141,7 +141,7 @@ request_total{
 }
 ```
 
-# Transport-Level Metrics
+## Transport-Level Metrics
 
 The following metrics are collected at the level of the underlying transport
 layer.