Commit ffcd501f authored by Adam Lewenberg's avatar Adam Lewenberg
Browse files

more work on README

parent 8e16ab50
......@@ -5,11 +5,10 @@
## Introduction
This is an _example_ Helm project that creates a Deployment of the
[Apache+Shibboleth Docker
container](https://code.stanford.edu/orange/docker-apache-shib) optimized
for GCP (Google Cloud Platform). This project is intended as a template
for creating other Helm projects that use Docker containers based on the
Apache+Shibboleth Docker container.
[Apache+Shibboleth Docker container][2] optimized for GCP (Google Cloud
Platform). This project is intended as a template for creating other Helm
projects that use Docker containers based on the Apache+Shibboleth Docker
container.
The architecture follows the standard GCP Ingress model:
```
......@@ -27,10 +26,10 @@ The architecture follows the standard GCP Ingress model:
+---------------------------------------------------------------------+
```
THe client connects via HTTPS to the External HTTPS Load Balancer
The client connects via HTTPS to the External HTTPS Load Balancer
provisioned by the Ingress. The Ingress sends requests to the Service over
port 80. Apache runs in the Pod and services the requests via HTTP. Note
that wven though the traffic from the Ingress to the Service and fro the
that even though the traffic from the Ingress to the Service and from the
Service to the Pod is over HTTP, the traffic is encrypted; see ["Encryption
from the load balancer to the
backends"](https://cloud.google.com/load-balancing/docs/ssl-certificates#backend-encryption)
......@@ -65,30 +64,29 @@ Default: `apache-shib-demo-dev.example.com`.
### Deployment
[`templates/deployment.yaml`](templates/deployment.yaml) The Deployment
creates a replica set using the [apache-shib
Docker](https://code.stanford.edu/et-iedo/docker/docker-apache-shib)
container. The container runs Apache and Shibboleth and listens on port 80
to HTTP traffic.
creates a replica set using the [apache-shib Docker][2] container. The
container runs Apache and Shibboleth and listens on port 80 to HTTP
traffic.
### Service
[`templates/service.yaml`](templates/service.yaml)
A NodePort Service is created that listens on port 80. This service is
intended to sit behind an Ingress.
[`templates/service.yaml`](templates/service.yaml) A NodePort Service is
created that listens on port 80. This service sites between the Ingress
and the Pod.
### Ingress
[`templates/ingress.yaml`](templates/ingress.yaml) The Ingress serves as
the TLS endpoint for the service using the registered name
`SERVER_NAME`. The DNS entry imapping the IP address to `SERVER_NAME` is
created in Google DNS using [externalDNS][1].
the TLS endpoint using the DNS-registered name `SERVER_NAME`. The DNS entry
imapping the IP address to `SERVER_NAME` is created in Google DNS using
[externalDNS][1].
This chart creates a ManagedCertificate object so that GCP will
automatically provision and update the TLS certificate that the HTTP Load
Balancer uses as the termination point.
The Ingress uses a FrontendConfig to enforce the use of TLS 1.2 or later;
see the section ["FrontendConfig"](#FrontendConfig) below for more
see the section ["FrontendConfig"](#frontendconfig) below for more
information.
We configure the Ingress to accept only connections via HTTPS. Connections
......@@ -96,14 +94,14 @@ using HTTP will come back with a 404 error. (GKE supports automatic
HTTP-to-HTTPS redirects in version 1.18.10-gke.600; see [Configuring
Ingress
features](https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-features)
for more information.
for more information.)
#### Ingress Health Check
The Ingress uses a health-check to the backend Service to determine if the
service is running properly. We cannot use the default health-check so we
create a custom health-check using a BackendConfig. See the
["BackendConfig"](#BackendConfig) section below for more details.
["BackendConfig"](#backendconfig) section below for more details.
### FrontendConfig
......@@ -112,7 +110,16 @@ This configuration points to the Google SSL policy that enforces the
minimum version of TLS as well as allowed cipher suites. The name of this
policy is set in the `values.yaml` setting `sslpolicy`. This Google SSL
Policy is _not_ managed by this Helm chart, rather, it must be managed
externally. Default value: `minimum-tls-12`. This
externally. Default value: `minimum-tls-12`.
Here is an example of you might create this policy using terraform:
```
resource "google_compute_ssl_policy" "ssl_policy_minimum_tls_12" {
name = "minimum-tls-12"
profile = "MODERN"
min_tls_version = "TLS_1_2"
}
```
### BackendConfig
......@@ -131,9 +138,12 @@ the path `/Shibboleth.sso/Metadata` which is _not_ SAML-protected.
This Helm chart does *not* setup or provision any Kubernetes secrets: you
must create them independently. The secrets needed are:
* `apache-shib-demo-<APP_ENV>-saml-key`
* `apache-shib-demo-<APP_ENV>-saml-key`: the private key portion of the SAML
Service provider public/private key pair.
* `apache-shib-demo-<APP_ENV>-saml-crt`: the public key portion of the SAML
Service provider public/private key pair.
* `apache-shib-demo-<APP_ENV>-saml-crt`
## SAML
......@@ -142,3 +152,5 @@ The SAML entity ID for this Service Provider will be the URL
[1]: https://github.com/kubernetes-sigs/external-dns
[2]: https://code.stanford.edu/orange/docker-apache-shib
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment