diff --git a/docs/helm/hydra.md b/docs/helm/hydra.md index 0b18334549..6f7f693946 100644 --- a/docs/helm/hydra.md +++ b/docs/helm/hydra.md @@ -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 \ @@ -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 @@ -64,14 +69,16 @@ $ 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 \ @@ -79,7 +86,8 @@ $ helm upgrade pg-sqlproxy rimusz/gcloud-sqlproxy --namespace sqlproxy \ ... ``` -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 @@ -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 @@ -102,7 +111,7 @@ hydra: # e.g.: ttl: access_token: 1h - # ... + # ... ``` and passing that as a value override to helm: @@ -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 @@ -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 \ @@ -163,7 +177,8 @@ $ 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 @@ -171,7 +186,8 @@ If running Minikube, enable the Ingress addon $ 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 @@ -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 @@ -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 \ @@ -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/ \ @@ -238,7 +254,7 @@ $ hydra clients create \ --id my-client \ --secret secret \ -g client_credentials - + $ hydra token client \ --endpoint http://public.hydra.localhost/ \ --client-id my-client \ @@ -246,7 +262,13 @@ $ hydra token client \ ``` ### 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 \ @@ -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.