ORY Hydra Helm Chart

The ORY Hydra Helm Chart helps you deploy ORY Hydra on Kubernetes using Helm.

Installation

Add the helm repository

$ helm repo add ory https://k8s.ory.sh/helm/charts
$ helm repo update

To install ORY Hydra, the following configuration values must be set:

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: hydra.config.dsn can also be set on runtime.

If you wish to install ORY Hydra with a postgres based database, a cryptographically strong secret, a Login and Consent provider located at https://my-idp/ run:

$ helm install \
    --set 'hydra.config.secrets.system={$(LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 32 | base64)}' \
    --set 'hydra.config.dsn=postgres://foo:bar@baz:1234/db' \
    --set 'hydra.config.urls.self.issuer=https://my-hydra/' \
    --set 'hydra.config.urls.login=https://my-idp/login' \
    --set 'hydra.config.urls.consent=https://my-idp/consent' \
    ory/hydra

You can optionally also set the cookie secrets:

$ helm install \
    ...
    --set 'hydra.config.secrets.cookie=$(LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 32 | base64)' \
    ...
    ory/hydra

Alternatively, you can use an existing Kubernetes Secret instead of letting the Helm Chart create one for you:


$ kubectl create secret generic my-secure-secret --from-literal=dsn=postgres://foo:bar@baz:1234/db \
    --from-literal=secretsCookie=$(LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 32 | base64) \
    --from-literal=secretsSystem=$(LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 32 | base64)

$ helm install \
    ...
    --set 'hydra.existingSecret=my-secure-secret' \
    ...
    ory/hydra

Last but not least, if you’d like to customise the way secrets are updated on your kubernetes cluster, you can do so via the hydra.config.secretAnnotations value as follows:

$ helm install \
    --set hydra.config.secretAnnotations."helm\.sh/hook"="pre-install\,pre-upgrade" \
    --set hydra.config.secretAnnotations."helm\.sh/hook-delete-policy"=before-hook-creation \
    ory/hydra

Local in memory mode

You can also run ORY Hydra with a in memory database. However, this requires changing the image tag to the -sqlite, which supports this mode of operation.

NOTE: This is recommended only for testing, and not intended for production use, as each replica will have its own db, and the data do not persist an application restart

For example:

$ helm install \
    --set 'hydra.config.dsn=memory' \
    --set 'image.tag=latest-sqlite'
    ory/hydra

With SQL Database

To run ORY Hydra against a SQL database, set the connection string. For example:

$ helm install \
    ...
    --set 'hydra.config.dsn=postgres://foo:bar@baz:1234/db' \
    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.

With Google Cloud SQL

To connect to Google Cloud SQL, you could use the gcloud-sqlproxy chart:

$ 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 here:

$ helm install \
    ...
    --set 'hydra.config.dsn=postgres://foo:bar@pg-sqlproxy-gcloud-sqlproxy:5432/db' \
    ory/hydra

Configuration

You can pass your ORY Hydra configuration file by creating a yaml file with key hydra.config

# hydra-config.yaml

hydra:
  config:
    # e.g.:
    ttl:
      access_token: 1h
    log:
      level: trace
    # ...

and passing that as a value override to helm:

$ helm install -f ./path/to/hydra-config.yaml ory/hydra

Additionally, the following extra settings are available:

Examples

This tutorial assumes that you’re running Minikube locally. If you’re not running Kubernetes locally, please adjust the hostnames accordingly.

Let’s install the Login and Consent App first

$ helm install \
    --set 'hydraAdminUrl=http://hydra-example-admin:4445/' \
    --set 'hydraPublicUrl=http://public.hydra.localhost/' \
    --set 'ingress.enabled=true' \
    --name hydra-example-idp \
    ory/example-idp

with hostnames

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

$ helm install \
    --set 'hydra.config.secrets.system={$(LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 32 | base64)}' \
    --set 'hydra.config.dsn=postgres://foo:bar@baz:1234/db' \
    --set 'hydra.config.urls.self.issuer=http://public.hydra.localhost/' \
    --set 'hydra.config.urls.login=http://example-idp.localhost/login' \
    --set 'hydra.config.urls.consent=http://example-idp.localhost/consent' \
    --set 'hydra.config.urls.logout=http://example-idp.localhost/logout' \
    --set 'ingress.public.enabled=true' \
    --set 'ingress.admin.enabled=true' \
    --set 'hydra.dangerousForceHttp=true' \
    --name hydra-example \
    ory/hydra

with hostnames

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)

$ kubectl get ing
NAME                   HOSTS                    ADDRESS        PORTS   AGE
hydra-example-idp      example-idp.localhost    192.168.64.3   80      3m47s
hydra-example-public   public.hydra.localhost   192.168.64.3   80      35s
hydra-example-admin    admin.hydra.localhost    192.168.64.3   80      35s

or alternatively with

$ minikube ip
192.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:

$ cat /etc/hosts
127.0.0.1	    localhost
255.255.255.255	broadcasthost
::1             localhost
# ...
192.168.64.3    example-idp.localhost
192.168.64.3    admin.hydra.localhost
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:

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

Next, you can follow the 5 Minute Tutorial, skipping the git and docker-compose set up sections. Assuming you have ORY Hydra installed locally, you can rewrite commands from, for example,

$ docker-compose -f quickstart.yml exec hydra \
      hydra clients create \
      --endpoint http://127.0.0.1:4445/ \
      --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/ \
      --client-id my-client \
      --client-secret secret

to

$ hydra clients create \
    --endpoint http://admin.hydra.localhost/ \
    --id my-client \
    --secret secret \
    -g client_credentials

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

Set up DSN variable on runtime

If you use need to construct DSN environment variable on the fly, you can leave hydra.config.dsn empty and provide custom DSN variable via extraEnv, e.g.:

Note: extraEnvs are defined separatly for individual objects (deployments, statefulsets, jobs etc), and therefore you need to define the env for all objects using it. Please refer to kratos values as an example

deployment:
  extraEnv:
    - name: DB_USER
      valueFrom:
        secretKeyRef:
          name: hydra.postgres-hydra.credentials.postgresql.acid.zalan.do
          key: username
    - name: DB_PASSWORD
      valueFrom:
        secretKeyRef:
          name: hydra.postgres-hydra.credentials.postgresql.acid.zalan.do
          key: password
    - name: DSN
      value: postgres://$(DB_USER):$(DB_PASSWORD)@postgres-hydra:5432/hydra

In such case you don’t need to take care about hydra.config.dsn value, when database was updated/recreated (in case with dynamic environments, gitops approach etc).

Hydra Maester

This chart includes a helper chart in the form of Hydra Maester, 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:

$ helm install \
    --set 'maester.enabled=false' \
    ory/hydra

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 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.

Upgrade

From 0.18.0

Since this version we support only kubernetes >= v1.18 for the ingress definition.

If you enabled ingresses you need to migrate values from:

ingress:
  public:
    hosts:
      - host: public.hydra.localhost
        paths: ["/"]
  admin:
    hosts:
      - host: admin.hydra.localhost
        paths: ["/"]

to

ingress:
  public:
    className: ""
    hosts:
      - host: public.hydra.localhost
        paths:
          - path: /
            pathType: ImplementationSpecific
  admin:
    className: ""
    hosts:
      - host: admin.hydra.localhost
        paths:
          - path: /
            pathType: ImplementationSpecific

where changes are on: