Skip to content

Commit ecde7b9

Browse files
slackslack
committed
chore(ssl): expand ssl documentation
1 parent 6cb4b7c commit ecde7b9

1 file changed

Lines changed: 74 additions & 45 deletions

File tree

‎src/managing-workflow/platform-ssl.md‎

Lines changed: 74 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -4,59 +4,88 @@ SSL/TLS is the standard security technology for establishing an encrypted link b
44
and a browser. This link ensures that all data passed between the web server and browsers remain
55
private and integral.
66

7-
To enable SSL for your cluster and all apps running upon it, you can add an SSL key to your load
8-
balancer. You must either provide an SSL certificate that was registered with a CA or provide
9-
[your own self-signed SSL certificate](../reference-guide/creating-a-self-signed-ssl-certificate.md).
7+
To enable SSL for the Workflow API and all managed apps, you can add an SSL certificate to the Deis Workflow router. You
8+
must provide either an SSL certificate that was registered with a CA or [your own self-signed SSL
9+
certificate](../reference-guide/creating-a-self-signed-ssl-certificate.md).
1010

11-
## Installing SSL on a Load Balancer
11+
Note that the platform SSL certificate also functions as a default certificate for your apps that are deployed via
12+
Workflow. If you would like to attach a specific certificate to an application and domain see [Application SSL
13+
Certificates](../.applications/ssl-certificates.md).
1214

13-
On most cloud-based load balancers, you can install a SSL certificate onto the load balancer
14-
itself. Any communication inbound to the load balancer will be encrypted while the internal
15-
components of Deis will still communicate over HTTP.
15+
## Installing SSL on the Deis Router
1616

17-
When you install Deis, Kubernetes will provision a load balancer for the routers. To enable SSL,
18-
you will need to modify the listener settings on the load balancer:
17+
To terminate SSL connections on the Deis Router use `kubectl` to create a new Secret at a known name. The Deis Workflow
18+
router will automatically detect this secret and reconfigure itself appropriately.
1919

20-
- swap the load balancer protocol on port 443 to use HTTPS
21-
- swap the backend protocol to use HTTP
22-
- change the backend port to the same backend port as the listener on port 80
23-
- install the certificate on the listener for port 443
20+
The following criteria must be met:
2421

25-
See your vendor's specific instructions on installing SSL on your load balancer. For AWS, see their
26-
documentation on [installing an SSL cert for load balancing](http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/ssl-server-cert.html).
22+
- The name of the secret must be `deis-router-platform-cert`
23+
- The certificate's public key must be supplied as the value of the `cert` key
24+
- The certificate's private key must be supplied as the value of the `key` key
25+
- Both the certificate and private key must be base64 encoded
2726

28-
## Installing SSL on the Deis Routers
27+
If your certificate has intermediate certs, append the intermediate signing certs to the bottom of the `cert` file
28+
before base64 encoding the combined certificates.
29+
30+
Prepare your certificate and key files by encoding them in bas64:
31+
32+
```
33+
$ cat certificate-file.crt
34+
-----BEGIN CERTIFICATE-----
35+
/ * your SSL certificate here */
36+
-----END CERTIFICATE-----
37+
-----BEGIN CERTIFICATE-----
38+
/* any intermediate certificates */
39+
-----END CERTIFICATE-----
40+
$ cat certificate-file.crt | base64 -e
41+
LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi8gKiB5b3VyIFNTTCBjZXJ0aWZpY2F0ZSBoZXJlICovCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0KLS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi8qIGFueSBpbnRlcm1lZGlhdGUgY2VydGlmaWNhdGVzICovCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
42+
$ cat certificate.key
43+
-----BEGIN RSA PRIVATE KEY-----
44+
/* your unencrypted private key here */
45+
-----END RSA PRIVATE KEY-----
46+
$ cat certificate.key | base64 -e
47+
LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQovKiB5b3VyIHVuZW5jcnlwdGVkIHByaXZhdGUga2V5IGhlcmUgKi8KLS0tLS1FTkQgUlNBIFBSSVZBVEUgS0VZLS0tLS0K
48+
```
49+
50+
Open your favorite text editor and create the Kubernetes manifest:
51+
52+
```
53+
$ $EDITOR deis-router-platform-cert.yaml
54+
```
55+
56+
The format of the Secret manifest should match the below example. Make sure you paste the appropriate values for `cert`
57+
and `key` from the above examples:
58+
59+
```
60+
$ cat deis-router-platform-cert.yaml
61+
apiVersion: v1
62+
kind: Secret
63+
metadata:
64+
name: deis-router-platform-cert
65+
namespace: deis
66+
type: Opaque
67+
data:
68+
cert: LS0...tCg==
69+
key: LS0...LQo=
70+
```
71+
72+
Once you've created the `deis-router-plaform-cert.yaml` file, you can install the manifest with `kubectl create -f
73+
deis-router-platform-cert.yaml`. The Deis Workflow router will automatically notice the new secret and update configuration its
74+
on-the-fly.
2975

30-
You can also use the Deis routers to terminate SSL connections. Use `kubectl` to install the
31-
certificate and private keys. Open your favorite text editor and create the Kubernetes manifest:
76+
## Installing SSL on a Load Balancer
3277

33-
$ $EDITOR deis-router-platform-cert.yaml
78+
Most cloud-based load balancers also support SSL termination in addition to passing traffic through to Deis Router. Any
79+
communication inbound to the load balancer will be encrypted while the internal components of Deis Workflow will still
80+
communicate over HTTP. This offloads SSL processing to the cloud load balancer but also means that any
81+
application-specific SSL certificates must **also** be configured on the cloud load balancer.
3482

35-
At this point, you'll want to create a new Kubernetes secret bearing the wildcard certificate.
36-
The following criteria must be met:
83+
To terminate SSL on the cloud load blanancer you will need to modify the load balancer's listener settings:
3784

38-
- The name must be deis-router-platform-cert
39-
- The certificate's public key must be supplied as the value of the `cert` key
40-
- The certificate's private key must be supplied as the value of the `key` key
41-
- Both the certificate and private key must be base64 encoded
85+
- Swap the load balancer protocol on port 443 to use HTTPS instead of TCP
86+
- Swap the backend protocol to use HTTP instead of TCP
87+
- Change the destination backend port to match the port configured for HTTP, usually port 80
88+
- Install the certificate on the listener associated with port 443
4289

43-
For example:
44-
45-
$ cat deis-router-platform-cert.yaml
46-
apiVersion: v1
47-
kind: Secret
48-
metadata:
49-
name: deis-router-platform-cert
50-
namespace: deis
51-
type: Opaque
52-
data:
53-
cert: LS0...tCg==
54-
key: LS0...LQo=
55-
56-
If your certificate has intermediate certs that need to be presented as part of a certificate
57-
chain, append the intermediate certs to the bottom of the `cert` value before base64 encoding the
58-
cert chain.
59-
60-
Once you've created the certificate manifest, you can then install the certificate with
61-
`kubectl create -f deis-router-platform-cert.yaml`. The router will pick this up and update its
62-
configuration on-the-fly.
90+
See your vendor's specific instructions on installing SSL on your load balancer. For AWS, see their
91+
documentation on [installing an SSL cert for load balancing](http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/ssl-server-cert.html).

0 commit comments

Comments
 (0)