Quickstart

This page takes you from the first helm install to the first hibernation. Hibernator starts in dry run: it writes to its log what it would scale, and terminates nothing.

Before you start

You need these:

• Credentials for the registry that holds the chart and the images.
• Your license file. Without a license, Hibernator scales nothing. On AWS, the controller also needs an AWS role and access to AWS STS: see License.
• A mail server. Users sign in with a one-time code that Hibernator sends by email, so without a mail server nobody can sign in. Authentication has the values.
• A cluster with Kubernetes 1.21 or later and RBAC, Helm 3.8 or later, and kubectl.
• An HTTPS address for the UI.

Install

1. Log in to the registry

helm registry login registry.gitlab.com

If you copy the chart and the images into your own registry, Install tells you which values to change.

2. Generate the two secrets

openssl rand -base64 32   # secrets.jwtSecret
openssl rand -base64 32   # secrets.internalApiSecret

Keep both values. If jwtSecret changes on a later upgrade, every user must sign in again.

If your own pipeline supplies the secrets, the chart can read them from your own Secret: see Install.

3. Write a values file

Copy this file to my-values.yaml. Replace each value in angle brackets and each example.com address.

imagePullSecrets:
  create: true
  username: "<registry-username>"
  password: "<registry-password-or-token>"
  # Or use a pull secret that you manage. Then remove the three lines above.
  # existingSecret: "<your-pull-secret>"

# Or put the secrets in a Secret that you manage, and name it in existingSecret.
secrets:
  jwtSecret: "<first openssl output>"
  internalApiSecret: "<second openssl output>"
  smtp:
    user: "hibernator@example.com"
    password: "<smtp-password>"

# The license file you received, whole and unchanged. Or leave this out and add
# --set-file license=HL-XXXXXXXX.license to the install command. license.md has
# the other ways to install a license.
license: |
  -----BEGIN HIBERNATOR LICENSE-----
  <the lines of your license file>
  -----END HIBERNATOR LICENSE-----

config:
  # A name for this cluster. Required. The UI and the notifications show it.
  clusterName: "my-cluster"

  # The address where users open Hibernator. Required. It starts with https://
  # and ends with /. Sign-in emails and satellite redirects use it.
  externalUrl: "https://hibernator.example.com/"

  auth:
    adminUsers:
      - "you@example.com"
    # The domains whose addresses can sign in.
    allowedEmailDomains:
      - "example.com"

  smtp:
    enabled: true
    host: "smtp.example.com"
    port: 587
    from: "hibernator@example.com"

  workingHours:
    timezone: "Europe/Berlin"
    schedule:
      monday:    "08:00-20:00"
      tuesday:   "08:00-20:00"
      wednesday: "08:00-20:00"
      thursday:  "08:00-20:00"
      friday:    "08:00-20:00"
      saturday:  "off"
      sunday:    "off"

  targeting:
    namespaces:
      exclude:
        - pattern: "kube-*"
        - exact: "hibernator"

  operations:
    # Hibernator writes to its log what it would do, and changes nothing.
    # Set this to false when the exclude list above is correct.
    dryRun: true

Warning

If you do not exclude a namespace, Hibernator scales it. With the list above, the first hibernation scales down all namespaces except the kube-* namespaces and the hibernator namespace. Add each namespace that must stay up to config.targeting.namespaces.exclude. Keep config.operations.dryRun: true until the controller log shows only the workloads that you expect.

4. Install the chart

License in my-values.yaml

helm install hibernator oci://registry.gitlab.com/cirriton/hibernator/charts/hibernator \
  -n hibernator --create-namespace \
  -f my-values.yaml

License with --set-file

Remove the license block from my-values.yaml. Then give the license file with --set-file:

helm install hibernator oci://registry.gitlab.com/cirriton/hibernator/charts/hibernator \
  -n hibernator --create-namespace \
  -f my-values.yaml \
  --set-file license=HL-XXXXXXXX.license

When a required value is missing, the install fails, and the message names the value.

Check the install

1. Check the pods

kubectl get pods -n hibernator

The controller pod and the app pod must both be Running.

2. Expose the UI

Set service.type to LoadBalancer, or put your own Ingress or Gateway in front of the service hibernator-app. Make sure that config.externalUrl is the address that results. If it is not, change the value and upgrade the release.

3. Sign in

1. Open config.externalUrl.
2. Enter an address from config.auth.adminUsers.
3. Enter the one-time code from the email.

The first hibernation

1. Test a hibernation in dry run

1. In Manual Control, click Trigger Manual Hibernation.
2. Enter a reason of 10 to 50 characters.
3. Click Hibernate Resources.

While config.operations.dryRun is true, Hibernator changes nothing. It writes each change that it would make to the controller log:

kubectl logs -n hibernator deployment/hibernator-controller | grep "(dry-run)"

The manual hibernation continues until the working hours start. To stop it before then, click Resume Schedule in Manual Control.

2. Turn off dry run

When the log shows only the workloads that you expect, set config.operations.dryRun: false in my-values.yaml. Then upgrade the release:

License in my-values.yaml

helm upgrade hibernator oci://registry.gitlab.com/cirriton/hibernator/charts/hibernator \
  -n hibernator -f my-values.yaml --version X.Y.Z

License with --set-file

helm upgrade hibernator oci://registry.gitlab.com/cirriton/hibernator/charts/hibernator \
  -n hibernator -f my-values.yaml --version X.Y.Z \
  --set-file license=HL-XXXXXXXX.license

Replace X.Y.Z with the chart version that you want. Without --version, Helm installs the newest version.

When dry run ends, Hibernator acts at once. Outside the working hours, or while the manual hibernation from the test continues, it scales the workloads to zero. This is the first hibernation.

3. Wake the workloads

To bring the workloads back before the working hours start:

1. In Manual Control, click Wake Up Resources.
2. Select how long the workloads stay awake.
3. Click Wake Up Resources in the dialog.

When the wake expires, the schedule decides again.

Next steps

• Schedule: set your own working hours.
• Authentication: the mail server, who can sign in, the admins and the sessions.
• Annotations: keep one workload running at all times.
• Stop Hibernator in an emergency: make Hibernator hand back everything it scaled down.
• Install: the other checks, and what the chart creates.
• Troubleshooting: what to check when something does not work.