Skip to content

Commit

Permalink
docs: update hydra helm docs (ory#188)
Browse files Browse the repository at this point in the history
  • Loading branch information
@DKImprowised
DKImprowised authored Nov 9, 2020
1 parent 5a37cc5 commit d314653
Showing 1 changed file with 72 additions and 47 deletions.
119 changes: 72 additions & 47 deletions docs/helm/hydra.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,22 @@ The ORY Hydra Helm Chart helps you deploy ORY Hydra on Kubernetes using Helm.

## Installation

To install ORY Hydra, the following values must be set
([documentation](https://github.com/ory/hydra/blob/master/docs/config.yaml)):
To install ORY Hydra, the following
[configuration values](https://www.ory.sh/hydra/docs/reference/configuration)
must be set:

* `hydra.config.dsn`
* `hydra.config.urls.self.issuer`
* `hydra.config.urls.login`
* `hydra.config.urls.consent`
* `hydra.config.secrets.system`
- `hydra.config.dsn`
- `hydra.config.urls.self.issuer`
- `hydra.config.urls.login`
- `hydra.config.urls.consent`
- `hydra.config.secrets.system`

> **NOTE:** If no `hydra.config.secrets.system` secrets is supplied and `hydra.existingSecret` is empty, a secret is generated automatically. The generated secret is cryptographically secure, and 32 signs long.
> **NOTE:** If no `hydra.config.secrets.system` secrets is supplied and
> `hydra.existingSecret` is empty, a secret is generated automatically. The
> generated secret is cryptographically secure, and 32 signs long.
If you wish to install ORY Hydra with an in-memory database, a cryptographically strong secret, a Login and Consent
provider located at `https://my-idp/` run:
If you wish to install ORY Hydra with an in-memory database, a cryptographically
strong secret, a Login and Consent provider located at `https://my-idp/` run:

```bash
$ helm install \
Expand All @@ -38,7 +41,9 @@ $ helm install \
ory/hydra
```

Alternatively, you can use an existing [Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/) instead of letting the Helm Chart create one for you:
Alternatively, you can use an existing
[Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/)
instead of letting the Helm Chart create one for you:

```bash

Expand All @@ -64,22 +69,25 @@ $ helm install \
ory/hydra
```

This chart does not require MySQL, PostgreSQL, or CockroachDB as dependencies because we strongly encourage
you not to run a database in Kubernetes but instead recommend to rely on a managed SQL database such as Google
Cloud SQL or AWS Aurora.
This chart does not require MySQL, PostgreSQL, or CockroachDB as dependencies
because we strongly encourage you not to run a database in Kubernetes but
instead recommend to rely on a managed SQL database such as Google Cloud SQL or
AWS Aurora.

### With Google Cloud SQL

To connect to Google Cloud SQL, you could use
the [`gcloud-sqlproxy`](https://github.com/rimusz/charts/tree/master/stable/gcloud-sqlproxy) chart:
To connect to Google Cloud SQL, you could use the
[`gcloud-sqlproxy`](https://github.com/rimusz/charts/tree/master/stable/gcloud-sqlproxy)
chart:

```bash
$ helm upgrade pg-sqlproxy rimusz/gcloud-sqlproxy --namespace sqlproxy \
--set 'serviceAccountKey="$(cat service-account.json | base64 | tr -d '\n')"' \
...
```

When bringing up ORY Hydra, set the host to `pg-sqlproxy-gcloud-sqlproxy` as documented
When bringing up ORY Hydra, set the host to `pg-sqlproxy-gcloud-sqlproxy` as
documented
[here](https://github.com/rimusz/charts/tree/master/stable/gcloud-sqlproxy#installing-the-chart):

```bash
Expand All @@ -91,7 +99,8 @@ $ helm install \

## Configuration

You can pass your [ORY Hydra configuration file](https://github.com/ory/hydra/blob/master/docs/config.yaml)
You can pass your
[ORY Hydra configuration file](https://www.ory.sh/hydra/docs/reference/configuration)
by creating a yaml file with key `hydra.config`

```yaml
Expand All @@ -102,7 +111,7 @@ hydra:
# e.g.:
ttl:
access_token: 1h
# ...
# ...
```

and passing that as a value override to helm:
Expand All @@ -113,12 +122,15 @@ $ helm install -f ./path/to/hydra-config.yaml ory/hydra

Additionally, the following extra settings are available:

- `autoMigrate` (bool): If enabled, an `initContainer` running `hydra migrate sql` will be created.
- `dangerousForceHttp` (bool): If enabled, sets the `--dangerous-force-http` flag on `hydra serve all`.
- `dangerousAllowInsecureRedirectUrls` (string[]): Sets the `--dangerous-allow-insecure-redirect-urls` flag on `hydra serve all`.
- `autoMigrate` (bool): If enabled, an `initContainer` running
`hydra migrate sql` will be created.
- `dangerousForceHttp` (bool): If enabled, sets the `--dangerous-force-http`
flag on `hydra serve all`.
- `dangerousAllowInsecureRedirectUrls` (string[]): Sets the
`--dangerous-allow-insecure-redirect-urls` flag on `hydra serve all`.

## Examples

### Exemplary Login and Consent App

This tutorial assumes that you're running Minikube locally. If you're not
Expand All @@ -137,14 +149,16 @@ $ helm install \

with hostnames

- `http://hydra-example-admin:4445/` corresponding to deployment name `--name hydra-example` (see next code sample)
with suffix `-admin` which is the hostname of the ORY Hydra Admin API Service.
- `https://public.hydra.localhost/` which is the default value for `ingress.public.hosts[0].host` from `ory/hydra` (
see next code sample).
- `http://hydra-example-admin:4445/` corresponding to deployment name
`--name hydra-example` (see next code sample) with suffix `-admin` which is
the hostname of the ORY Hydra Admin API Service.
- `https://public.hydra.localhost/` which is the default value for
`ingress.public.hosts[0].host` from `ory/hydra` ( see next code sample).

Next install ORY Hydra. Please note that SSL is disabled using `--set hydra.dangerousForceHttp=true`
which should never be done when working outside of `localhost` and only
for testing and demonstration purposes. Install the ORY Hydra Helm Chart
Next install ORY Hydra. Please note that SSL is disabled using
`--set hydra.dangerousForceHttp=true` which should never be done when working
outside of `localhost` and only for testing and demonstration purposes. Install
the ORY Hydra Helm Chart

```bash
$ helm install \
Expand All @@ -163,15 +177,17 @@ $ helm install \

with hostnames

- `example-idp.localhost` which is the default for `ingress.hosts[0].host` from `ory/example-idp`.
- `example-idp.localhost` which is the default for `ingress.hosts[0].host` from
`ory/example-idp`.

If running Minikube, enable the Ingress addon

```bash
$ minikube addons enable ingress
```

and get the IP addresses for the Ingress controllers with (you may need to wait a bit)
and get the IP addresses for the Ingress controllers with (you may need to wait
a bit)

```bash
$ kubectl get ing
Expand All @@ -184,12 +200,12 @@ hydra-example-admin admin.hydra.localhost 192.168.64.3 80 35s
or alternatively with

```bash
$ minikube ip192.168.64.3
$ minikube ip192.168.64.3

```

next route the hostnames to the IP Address from above by editing, for example `/etc/hosts`. The result should look something
like:
next route the hostnames to the IP Address from above by editing, for example
`/etc/hosts`. The result should look something like:

```bash
$ cat /etc/hosts
Expand All @@ -202,18 +218,18 @@ $ cat /etc/hosts
192.168.64.3 public.hydra.localhost
```

Please note that file contents will be different on every operating system and network. Now, confirm that everything
is working:
Please note that file contents will be different on every operating system and
network. Now, confirm that everything is working:

```bash
$ curl http://example-idp.localhost/
http://public.hydra.localhost/.well-known/openid-configuration
```
```

Next, you can follow the [5 Minute Tutorial](https://www.ory.sh/docs/hydra/5min-tutorial),
skipping the `git` and `docker-compose` set up sections. Assuming
you have ORY Hydra installed locally, you can rewrite commands
from, for example,
Next, you can follow the
[5 Minute Tutorial](https://www.ory.sh/docs/hydra/5min-tutorial), skipping the
`git` and `docker-compose` set up sections. Assuming you have ORY Hydra
installed locally, you can rewrite commands from, for example,

```bash
$ docker-compose -f quickstart.yml exec hydra \
Expand All @@ -222,7 +238,7 @@ $ docker-compose -f quickstart.yml exec hydra \
--id my-client \
--secret secret \
-g client_credentials

$ docker-compose -f quickstart.yml exec hydra \
hydra token client \
--endpoint http://127.0.0.1:4444/ \
Expand All @@ -238,15 +254,21 @@ $ hydra clients create \
--id my-client \
--secret secret \
-g client_credentials

$ hydra token client \
--endpoint http://public.hydra.localhost/ \
--client-id my-client \
--client-secret secret
```

### Hydra Maester
This chart includes a helper chart in the form of [Hydra Maester](https://github.com/ory/k8s/blob/master/docs/helm/hydra-maester.md), a Kubernetes controller, which manages OAuth2 clients using the `oauth2clients.hydra.ory.sh` custom resource. By default, this component is enabled and installed together with Hydra. However, it can be disabled by setting the proper flag:

This chart includes a helper chart in the form of
[Hydra Maester](https://github.com/ory/k8s/blob/master/docs/helm/hydra-maester.md),
a Kubernetes controller, which manages OAuth2 clients using the
`oauth2clients.hydra.ory.sh` custom resource. By default, this component is
enabled and installed together with Hydra. However, it can be disabled by
setting the proper flag:

```bash
$ helm install \
Expand All @@ -256,8 +278,11 @@ $ helm install \

#### Using fullnameOverride

If you use need to override the name of the hydra resources such as the deployment or services, the traditional `fullnameOverride` value is available.
If you use need to override the name of the hydra resources such as the
deployment or services, the traditional `fullnameOverride` value is available.

If you use it and deploy maester as part of hydra, make sure you also set `maester.hydraFullnameOverride` with the same value, so that the admin service name used by maester is properly computed with the new value.
If you use it and deploy maester as part of hydra, make sure you also set
`maester.hydraFullnameOverride` with the same value, so that the admin service
name used by maester is properly computed with the new value.

Should you forget, helm will fail and remind you to.

0 comments on commit d314653

Please sign in to comment.