Update documentation

pgagnon · Aug 8, 2018 · b533926 · b533926
1 parent 12c54fd
commit b533926
Show file tree

Hide file tree

Showing 5 changed files with 167 additions and 77 deletions.
diff --git a/README.md b/README.md
@@ -3,94 +3,38 @@
 A helper web-app which talks to one or more [Dex Identity services](https://github.com/coreos/dex) to generate
 `kubectl` commands for creating and modifying a `kubeconfig`.
 
-* The Web UI supports generating tokens against multiple clusters
-    * Dev / Staging / Production etc
-* Generates appropriate `kubectl config` commands (user/cluster/context)
-* SSL Support
-
-## Screen shots
-
-![Index Page](examples/index-page.png)
-
-![Kubeconfig Page](examples/kubeconfig-page.png)
-
-## Building a binary
-
-    make 
-
-Creates ./bin/dex-k8s-authenticator
-
-## Building a container
-
-    make container
-
-## Configuraton
-
-An example configuration is available [here](examples/config.yaml)
-
-Configuration also supports environment variables to be used for cluster configuration.
-
-```
-clusters:
-  - name: example-cluster
-    short_description: "Example Cluster"
-    description: "Example Cluster Long Description..."
-    client_secret: ${CLIENT_SECRET_EXAMPLE_CLUSTER}
-```
+The Web UI supports generating tokens against multiple cluster such as Dev / Staging / Production. 
 
-## Running 
 
-### Start Dex Server instance
-
-Follow the example here:
-https://github.com/coreos/dex/blob/master/Documentation/getting-started.md
-
-Start it with using the provided `./examples/dex-server-config-dev.yaml`
-
-### Start Dex K8s Authenticator
-
-    ./bin/dex-k8s-authenticator --config ./examples/config.yaml
-
-* Browse to http://localhost:5555
-* Click 'Example Cluster'
-* Click 'Log in with Email'
-* Login with `[email protected]` followed by the password `password`
-* You should be redirected back to the dex-k8s-authenticator
-
-## Deploying using Helm
-
-This project provides [`helm` charts](charts) for deploying both `dex` and
-`dex-k8s-authenticator` to your Kubernetes cluster. Instructions are provided
-for each chart.
-
-## Multiple Clusters
-
-You can run multiple Dex Server instances with different backends if required.
+## Also provides
+* Helm Charts
+* SSL Support
+* Linux/Mac/Windows instructions
 
-Just update the `examples/config.yaml` to add an extra cluster to the list with the 
-required settings.
+## Documentation
 
-## SSL
+- [Developing and Running](docs/develop.md)
+- [Configuration Options](docs/config.md)
+- [Using the Helm Charts](docs/helm.md)
+- [SSL Support](docs/ssl.md)
 
-### Docker
+## Screen shots
 
-Mount a directory containing your self signed certificates to */certs* and the entrypoint will update the local trust store before starting dex-k8s-authenticator. Certificates must have a .crt extension in order to be included by update-ca-certificates.
+![Index Page](examples/index-page.png)
 
-    docker run --rm -t -i -v /tmp/certs:/certs:ro -v /tmp/config.yml:/tmp/config.yml:ro mintel/dex-k8s-authenticator:latest --config /tmp/config.yml
+![Kubeconfig Page](examples/kubeconfig-page.png)
 
-### HELM
 
-Add list of Certificates to your values.yaml file, certificates need to be base64 encoded. 
+## Contributing
 
+Feel free to raise feature-requests and bugs. PR's are also very welcome.
 
 ## Alternatives
 
-A similar web UI that generates `kubectl` configurations without using `dex` to authenticate first
-* https://github.com/negz/kuberos
-
-OIDC helpers that run locally to setup `kubectl`:
-* https://github.com/micahhausler/k8s-oidc-helper
-* https://github.com/coreos/dex/tree/master/cmd/example-app
+- https://github.com/heptiolabs/gangway
+- https://github.com/micahhausler/k8s-oidc-helper
+- https://github.com/negz/kuberos
+- https://github.com/negz/kubehook
 
-A Kubernetes JWT webhook helper with a similar UX to Kuberos
-* https://github.com/negz/kubehook
+This application is based on the original [example-app](https://github.com/coreos/dex/tree/master/cmd/example-app
+) available in the CoreOS Dex repo.
diff --git a/docs/config.md b/docs/config.md
@@ -0,0 +1,41 @@
+# Configuration 
+
+An example configuration is available [here](../examples/config.yaml)
+
+## Configuration options
+
+
+| Name              | Required | Context | Description                                                                           |
+|-------------------|----------|---------|---------------------------------------------------------------------------------------|
+| name              | yes      | cluster | Internal id of cluster                                                                |
+| short_description | yes      | cluster | Short description of cluster                                                |
+| description       | yes      | cluster | Extended description of cluster                                             |
+| client_secret     | yes      | cluster | OAuth2 client-secret (shared between dex-k8s-auth and dex)                            |
+| client_id         | yes      | cluster | OAuth2 client-id public identifier (shared between dex-k8s-auth and dex)              |
+| issuer            | yes      | cluster | Dex issuer url                                                                        |
+| redirect_uri      | yes      | cluster | Redirect uri called by dex (defines a callback on dex-k8s-auth)                       |
+| k8s_master_uri    | no       | cluster | Kubernetes api-server endpoint (used in kubeconfig)                                   |
+| k8s_ca_uri        | no       | cluster | A url pointing to the CA for generating 'certificate-authority' option in kubeconfig  |
+| k8s_ca_pem        | no       | cluster | The CA for your k8s server (used in generating instructions)                          |
+| tls_cert          | no       | root    | Path to TLS cert if SSL enabled                                                       |
+| tls_key           | no       | root    | Path to TLS key if SSL enabled                                                        |
+| idp_ca_uri        | no       | root    | A url pointing to the CA for generating 'idp-certificate-authority' in the kubeconfig |
+| trusted_root_ca   | no       | root    | A list of trusted-root CA's to be loaded by dex-k8s-auth at runtime                   |
+| listen            | yes      | root    | The listen address/port                                                                    |
+| web_path_prefix   | no       | root    | A path-prefix to serve dex-k8s-auth at (defaults to '/')                              |
+| kubectl_version   | no       | root    | A kubectl-version string that is used to provided a download path                     |
+| logo_uri          | no       | root    | A url pointing to a logo image that is displayed in the header                        |
+| debug             | no       | root    | Enable more debug by setting to true                                                  |
+
+## Environment Variable Support
+
+Environment variables can be included in the configuration. This enables you to pass in dynamic variables or secrets without having to hardcode them.
+```
+clusters:
+  - name: example-cluster
+    short_description: "Example Cluster"
+    description: "Example Cluster Long Description..."
+    client_secret: ${CLIENT_SECRET_EXAMPLE_CLUSTER}
+```
+
+In this example, `${CLIENT_SECRET_EXAMPLE_CLUSTER}` is substituted at runtime. Must be enclosed by `${...}`
diff --git a/docs/develop.md b/docs/develop.md
@@ -0,0 +1,36 @@
+# Developing and Running
+
+## Building a binary
+
+    make 
+
+Creates ./bin/dex-k8s-authenticator
+
+## Building a container
+
+    make container
+
+## Running it
+
+### Start a Dex Server instance
+
+You must have a `dex` instance running before starting `dex-k8s-authenticator`.
+
+Follow the example here:
+https://github.com/coreos/dex/blob/master/Documentation/getting-started.md
+
+Start it with using the provided `./examples/dex-server-config-dev.yaml`
+
+### Start Dex K8s Authenticator
+
+    ./bin/dex-k8s-authenticator --config ./examples/config.yaml
+
+* Browse to http://localhost:5555
+* Click 'Example Cluster'
+* Click 'Log in with Email'
+* Login with `[email protected]` followed by the password `password`
+* You should be redirected back to the dex-k8s-authenticator
+
+### Configuration Options
+
+Additional configuration options are explained [here](config.md)
diff --git a/docs/helm.md b/docs/helm.md
@@ -0,0 +1,13 @@
+# Helm Charts
+
+This project provides Helm Charts to install `dex` and `dex-k8s-authenticator` into a Kubernetes cluster.
+
+Follow the links for specific documentation on each chart:
+- [dex-k8s-authenticator](../charts/dex-k8s-authenticator)
+- [dex](../charts/dex)
+
+
+Please note, that whilst we maintain our own `dex` chart, there is now an official version available in the main helm charts repo:
+
+- https://github.com/helm/charts/tree/master/stable/dex
+
diff --git a/docs/ssl.md b/docs/ssl.md
@@ -0,0 +1,56 @@
+# SSL
+
+## Adding Trusted Certificates
+
+There are a couple of ways to have `dex-k8s-authenticator` use trusted certificates.
+
+### 1. Mounting `/certs/` volume
+
+`entrypoint.sh` runs `update-ca-certificates` against certificates found in `/certs/`
+
+They must end in the extension `.crt`
+
+If using docker, you can mount a volume like so:
+
+```
+docker run --rm -t -i \
+    -v /tmp/certs:/certs:ro \
+    -v /tmp/config.yml:/tmp/config.yml:ro \ 
+    mintel/dex-k8s-authenticator:latest --config /tmp/config.yml
+```
+
+### 2. `trusted_root_ca` config option
+
+You can define multiple certificates via the configuration file:
+
+```yaml
+trusted_root_ca:
+  - |
+    -----BEGIN CERTIFICATE-----
+    MIIGJDCCBAygAwI...
+    -----END CERTIFICATE-----
+```
+
+## Serving requests on SSL
+
+The configuration file requires the following:
+
+
+```yaml
+listen: https://127.0.0.1:5555
+tls_cert: /path/to/dex-client.crt
+tls_key: /path/to/dex-client.key
+```
+
+- Note, the `listen` option is using `https` not `http`
+- You need to supply both `.crt` and the `.key` files
+
+The `.crt` and `.key` file can be mounted as a volume.
+
+## Helm Charts
+
+### dex-k8a-authenticator
+
+Our Helm chart providers options for both using trusted root certs, and serving requests on SSL.
+
+For more information on SSL support in our Helm chart, please read [here](../charts/dex-k8s-authenticator)