TLS info

ee/ucp/interlock/usage/tls.md

@@ -1,14 +1,12 @@
 ---
-title: Applications with SSL
+title: Securing services with TLS
 description: Learn how to configure your swarm services with TLS using the layer
   7 routing solution for UCP.
 keywords: routing, proxy, tls
-redirect_from:
-  - /ee/ucp/interlock/usage/ssl/
 ---
 
-Once the [layer 7 routing solution is enabled](../deploy/index.md), you can
+# Securing services with TLS
-start using it in your swarm services. You have two options for securing your
+After [deploying a layer 7 routing solution](../deploy/index.md), you have two options for securing your
 services with TLS:
 
 * Let the proxy terminate the TLS connection. All traffic between end-users and
@@ -17,10 +15,7 @@ service is not secured.
 * Let your swarm service terminate the TLS connection. The end-to-end traffic
 is encrypted and the proxy service allows TLS traffic to passthrough unchanged.
 
-In this example we'll deploy a service that can be reached at `app.example.org`
+Regardless of the option selected to secure swarm services, there are two steps required to
-using these two options.
-
-No matter how you choose to secure your swarm services, there are two steps to
 route traffic with TLS:
 
 1. Create [Docker secrets](/engine/swarm/secrets.md) to manage from a central
@@ -29,11 +24,10 @@ place the private key and certificate used for TLS.
 
 
 ## Let the proxy handle TLS
-
+The following example deploys a swarm service and lets the proxy service handle
-In this example we'll deploy a swarm service and let the proxy service handle
 the TLS connection. All traffic between the proxy and the swarm service is
-not secured, so you should only use this option if you trust that no one can
+not secured, so use this option only if you trust that no one can
-monitor traffic inside services running on your datacenter.
+monitor traffic inside services running in your datacenter.
 
 ![TLS Termination](../../images/interlock-tls-1.png)
 
@@ -86,15 +80,15 @@ secrets:
     file: ./app.example.org.key
 ```
 
-Notice that the demo service has labels describing that the proxy service should
+Notice that the demo service has labels specifying that the proxy service should
-route traffic to `app.example.org` to this service. All traffic between the
+route `app.example.org` traffic to this service. All traffic between the
 service and proxy takes place using the `demo-network` network. The service also
-has labels describing the Docker secrets to use on the proxy service to terminate
+has labels specifying the Docker secrets to use on the proxy service for terminating
 the TLS connection.
 
-Since the private key and certificate are stored as Docker secrets, you can
+Because the private key and certificate are stored as Docker secrets, you can
 easily scale the number of replicas used for running the proxy service. Docker
-takes care of distributing the secrets to the replicas.
+distributes the secrets to the replicas.
 
 Set up your CLI client with a [UCP client bundle](../../user-access/cli.md),
 and deploy the service:
@@ -103,25 +97,24 @@ and deploy the service:
 docker stack deploy --compose-file docker-compose.yml demo
 ```
 
-The service is now running. To test that everything is working correctly you
+The service is now running. To test that everything is working correctly, update your `/etc/hosts` file to map `app.example.org` to the
-first need to update your `/etc/hosts` file to map `app.example.org` to the
 IP address of a UCP node.
 
-In a production deployment, you'll have to create a DNS entry so that your
+In a production deployment, you must create a DNS entry so that 
 users can access the service using the domain name of your choice.
-After doing that, you'll be able to access your service at:
+After creating the DNS entry, you can access your service:
 
 ```bash
 https://<hostname>:<https-port>
 ```
 
-Where:
+FOr this example:
-* `hostname` is the name you used with the `com.docker.lb.hosts` label.
+* `hostname` is the name you specified with the `com.docker.lb.hosts` label.
-* `https-port` is the port you've configured in the [UCP settings](../deploy/index.md).
+* `https-port` is the port you configured in the [UCP settings](../deploy/index.md).
 
 ![Browser screenshot](../../images/interlock-tls-2.png){: .with-border}
 
-Since we're using self-sign certificates in this example, client tools like
+Because this example uses self-sign certificates, client tools like
 browsers display a warning that the connection is insecure.
 
 You can also test from the CLI:
@@ -132,23 +125,22 @@ curl --insecure \
   https://<hostname>:<https-port>/ping
 ```
 
-If everything is properly configured you should get a JSON payload:
+If everything is properly configured, you should get a JSON payload:
 
 ```json
 {"instance":"f537436efb04","version":"0.1","request_id":"5a6a0488b20a73801aa89940b6f8c5d2"}
 ```
 
-Since the proxy uses SNI to decide where to route traffic, make sure you're
+Because the proxy uses SNI to decide where to route traffic, make sure you are
 using a version of `curl` that includes the SNI header with insecure requests.
-If this doesn't happen, `curl` displays an error saying that the SSL handshake
+Otherwise, `curl` displays an error saying that the SSL handshake
-was aborterd.
+was aborted.
 
 > **Note**: Currently there is no way to update expired certificates using this method.
 > The proper way is to create a new secret then update the corresponding service. 
 
 ## Let your service handle TLS
-
+The second option for securing with TLS involves encrypting traffic from end users to your swarm service.
-You can also  encrypt the traffic from end-users to your swarm service.
 
 ![End-to-end encryption](../../images/interlock-tls-3.png)
 
@@ -189,11 +181,11 @@ secrets:
     file: ./app.example.org.key
 ```
 
-Notice that we've update the service to start using the secrets with the
+The service is updated to start using the secrets with the
 private key and certificate. The service is also labeled with
 `com.docker.lb.ssl_passthrough: true`, signaling UCP to configure the proxy
 service such that TLS traffic for `app.example.org` is passed to the service.
 
-Since the connection is fully encrypt from end-to-end, the proxy service
+Since the connection is fully encrypted from end-to-end, the proxy service
-won't be able to add metadata such as version info or request ID to the
+cannot add metadata such as version information or request ID to the
 response headers.