schema.yaml

title: Config
type: object
properties:
  hub:
    type: object
    properties:
      cookieSecret:
        type:
          - string
          - "null"
        description: |
          A 32-byte cryptographically secure randomly generated string used to sign values of
          secure cookies set by the hub. If unset, jupyterhub will generate one on startup and
          save it in the file `jupyterhub_cookie_secret` in the `/srv/jupyterhub` directory of
          the hub container. A value set here will make JupyterHub overwrite any previous file.

          You do not need to set this at all if you are using the default configuration for
          storing databases - sqlite on a persistent volume (with `hub.db.type` set to the
          default `sqlite-pvc`). If you are using an external database, then you must set this
          value explicitly - or your users will keep getting logged out each time the hub pod
          restarts.

          Changing this value will all user logins to be invalidated. If this secret leaks,
          *immediately* change it to something else, or user data can be compromised
          
          ```sh
          # to generate a value, run
          openssl rand -hex 32
          ```
      imagePullPolicy:
        type: string
        enum:
          - IfNotPresent
          - Always
          - Never
        description: |
          Set the imagePullPolicy on the hub pod.

          See the [Kubernetes docs](https://kubernetes.io/docs/concepts/containers/images/#updating-images)
          for more info on what the values mean.
      image:
        type: object
        description: |
          Set custom image name / tag for the hub pod.

          Use this to customize which hub image is used. Note that you must use a version of
          the hub image that was bundled with this particular version of the helm-chart - using
          other images might not work.
        properties:
          name:
            type: string
            description: |
              Name of the image, without the tag.

              ```
              # example names
              yuvipanda/wikimedia-hub
              gcr.io/my-project/my-hub
              ```
          tag:
            type: string
            description: |
              The tag of the image to pull.
              
              This is the value after the `:` in your full image name.

              ```
              # example tags
              v1.11.1
              zhy270a
              ```
      db:
        type: object
        properties:
          type:
            type: string
            enum:
              - sqlite-pvc
              - sqlite-memory
              - mysql
              - postgres
            description: |
              Type of database backend to use for the hub database.

              The Hub requires a persistent database to function, and this lets you specify
              where it should be stored.

              The various options are:

              1. **sqlite-pvc**

                 Use an `sqlite` database kept on a persistent volume attached to the hub.

                 By default, this disk is created by the cloud provider using
                 *dynamic provisioning* configured by a [storage
                 class](https://kubernetes.io/docs/concepts/storage/storage-classes/).
                 You can customize how this disk is created / attached by
                 setting various properties under `hub.db.pvc`.

                 This is the default setting, and should work well for most cloud provider
                 deployments.

              2. **sqlite-memory**

                 Use an in-memory `sqlite` database. This should only be used for testing,
                 since the database is erased whenever the hub pod restarts - causing the hub
                 to lose all memory of users who had logged in before.

                 When using this for testing, make sure you delete all other objects that the
                 hub has created (such as user pods, user PVCs, etc) every time the hub restarts.
                 Otherwise you might run into errors about duplicate resources.

              3. **mysql**

                 Use an externally hosted mysql database.

                 You have to specify an sqlalchemy connection string for the mysql database you
                 want to connect to in `hub.db.url` if using this option.

                 The general format of the connection string is:
                 ```
                 mysql+pymysql://<db-username>:<db-password>@<db-hostname>:<db-port>/<db-name>
                 ```

                 The user specified in the connection string must have the rights to create
                 tables in the database specified.

                 Note that if you use this, you *must* also set `hub.cookieSecret`.

              4. **postgres**

                 Use an externally hosted postgres database.

                 You have to specify an sqlalchemy connection string for the postgres database you
                 want to connect to in `hub.db.url` if using this option.

                 The general format of the connection string is:
                 ```
                 postgres+psycopg2://<db-username>:<db-password>@<db-hostname>:<db-port>/<db-name>
                 ```

                 The user specified in the connection string must have the rights to create
                 tables in the database specified.

                 Note that if you use this, you *must* also set `hub.cookieSecret`.
          pvc:
            type: object
            description: |
              Customize the Persistent Volume Claim used when `hub.db.type` is `sqlite-pvc`.
            properties:
              annotations:
                type: object
                description: |
                  Annotations to apply to the PVC containing the sqlite database.

                  See [the Kubernetes
                  documentation](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/)
                  for more details about annotations.
              selector:
                type: object
                description: |
                  Label selectors to set for the PVC containing the sqlite database.

                  Useful when you are using a specific PV, and want to bind to
                  that and only that.

                  See [the Kubernetes
                  documentation](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims)
                  for more details about using a label selector for what PV to
                  bind to.
              storage:
                type: string
                description: |
                  Size of disk to request for the database disk.
          url:
            type:
              - string
              - "null"
            description: |
              Connection string when `hub.db.type` is mysql or postgres.

              See documentation for `hub.db.type` for more details on the format of this property.
      labels:
        type: object
        description: |
          Extra labels to add to the hub pod.

          See the [Kubernetes docs](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
          to learn more about labels.
      extraEnv:
        type: list
        description: |
          Extra environment variables that should be set for the hub pod.

          A list of [EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.9/#envvar-v1-core)
          objects.

          These are usually used in two circumstances:
            - Passing parameters to some custom code specified with `extraConfig`
            - Passing parameters to an authenticator or spawner that can be directly customized
              by environment variables (rarer)
      extraConfig:
        type: string
        description: |
          Arbitrary extra python based configuration that should be in `jupyterhub_config.py`.

          This is the *escape hatch* - if you want to configure JupyterHub to do something specific
          that is not present here as an option, you can just write the raw Python to do it here.

          Non-exhaustive examples of things you can do here:
            - Subclass authenticator / spawner to do a custom thing
            - Dynamically launch different images for different sets of images
            - Inject an auth token from GitHub authenticator into user pod
            - Anything else you can think of!

          Since this is usually a multi-line string, you want to format it using YAML's
          [| operator](http://www.yaml.org/spec/1.2/spec.html#id2795688).

          For example:
            ```yaml
            hub:
              extraConfig: |
                c.JupyterHub.something = 'something'
                c.Spawner.somethingelse = 'something else'
            ```

          No validation of this python is performed! If you make a mistake here, it will probably
          manifest as either the hub pod going into `Error` or `CrashLoopBackoff` states, or in
          some special cases, the hub running but... just doing very random things. Be careful!
      uid:
        type: integer
        minimum: 0
        description:
          The UID the hub process should be running as.

          Use this only if you are building your own image & know that a user with this uid
          exists inside the hub container! Advanced feature, handle with care!

          Defaults to 1000, which is the uid of the `jovyan` user that is present in the
          default hub image.
      fsGid:
        type: integer
        minimum: 0
        description:
          The gid the hub process should be using when touching any volumes mounted.

          Use this only if you are building your own image & know that a group with this gid
          exists inside the hub container! Advanced feature, handle with care!

          Defaults to 1000, which is the gid of the `jovyan` user that is present in the
          default hub image.
  proxy:
    type: object
    properties:
      secretToken:
        type: string
        description: |
          A 32-byte cryptographically secure randomly generated string used to secure communications
          between the hub and the configurable-http-proxy.

          ```sh
          # to generate a value, run
          openssl rand -hex 32
          ```

          Changing this value will cause the proxy and hub pods to restart. It is good security
          practice to rotate these values over time. If this secret leaks, *immediately* change
          it to something else, or user data can be compromised
    required:
      - secretToken


  auth:
    type: object
    properties:
      state:
        type: object
        properties:
          enabled:
            type: boolean
            description: |
              Enable persisting auth_state (if available).
              See: http://jupyterhub.readthedocs.io/en/latest/api/auth.html
          cryptoKey:
            type:
              - string
              - "null"
            description: |
              auth_state will be encrypted and stored in the Hub’s database. This can include things like authentication tokens, etc. to be passed to Spawners as environment variables.
              Encrypting auth_state requires the cryptography package.
              It must contain one (or more, separated by ;) 32-byte encryption keys. These can be either base64 or hex-encoded.
              The JUPYTERHUB_CRYPT_KEY environment variable for the hub pod is set using this entry.

              ```sh
              # to generate a value, run
              openssl rand -hex 32
              ```

              If encryption is unavailable, auth_state cannot be persisted.


  singleuser:
    type: object
    description: |
      Options for customizing the environment that is provided to the users after they log in.
    properties:
      cpu:
        type: object
        description: |
          Set CPU limits & guarantees that are enforced for each user.
          See: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/
        properties:
          limit:
            type:
              - string
              - "null"
          guarantee:
            type:
              - string
              - "null"
      memory:
        type: object
        description: |
          Set Memory limits & guarantees that are enforced for each user.
          
          See the [Kubernetes docs](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container)
          for more info.
        properties:
          limit:
            type:
              - string
              - "null"
          guarantee:
            type:
              - string
              - "null"
            description: |
              Note that this field is referred to as *requests* by the Kubernetes API.
      imagePullSecret:
        type: object
        description: |
          Creates an image pull secret for you and makes the user pods utilize
          it, allowing them to pull images from private image registries.
          
          Using this configuration option automates the following steps that
          normally is required to pull from private image registries.
          
          ```sh
          # you won't need to run this manually...
          kubectl create secret docker-registry singleuser-image-credentials \
            --docker-server=<REGISTRY> \
            --docker-username=<USERNAME> \
            --docker-email=<EMAIL> \
            --docker-password=<PASSWORD>
          ```

          ```yaml
          # you won't need to specify this manually...
          spec:
            imagePullSecrets:
              - name: singleuser-image-credentials
          ```

          To learn the username and password fields to access a gcr.io registry
          from a Kubernetes cluster not associated with the same google cloud
          credentials, look into [this
          guide](http://docs.heptio.com/content/private-registries/pr-gcr.html)
          and read the notes about the password.
        properties:
          registry:
            type: string
            description: |
              Name of the private registry you want to create a credential set
              for. It will default to Docker Hub's image registry.

              Examples:
                - https://index.docker.io/v1/
                - quay.io
                - eu.gcr.io
                - alexmorreale.privatereg.net
          username:
            type: string
            description: |
              Name of the user you want to use to connect to your private
              registry. For external gcr.io, you will use the `_json_key`.

              Examples:
                - alexmorreale
                - alex@pfc.com
                - _json_key
          password:
            type: string
            description: |
              Password of the user you want to use to connect to your private
              registry.

              Examples:
                - plaintextpassword
                - abc123SECRETzyx098

              For gcr.io registries the password will be a big JSON blob for a
              Google cloud service account, it should look something like below.
                            
              ```yaml
              password: |-
                {
                  "type": "service_account",
                  "project_id": "jupyter-se",
                  "private_key_id": "f2ba09118a8d3123b3321bd9a7d6d0d9dc6fdb85",
                  ...
                }
              ```

              Learn more in [this
              guide](http://docs.heptio.com/content/private-registries/pr-gcr.html).
      image:
        type: object
        description: |
          Set custom image name / tag used for spawned users.

          This image is used to launch the pod for each user.
        properties:
          name:
            type: string
            description: |
              Name of the image, without the tag.

              Examples:
                - yuvipanda/wikimedia-hub-user
                - gcr.io/my-project/my-user-image
          tag:
            type: string
            description: |
              The tag of the image to use.

              This is the value after the `:` in your full image name.
          pullPolicy:
            type: string
            enum:
              - IfNotPresent
              - Always
              - Never
            description: |
              Set the imagePullPolicy on the singleuser pods that are spun up by the hub.

              See the [Kubernetes docs](https://kubernetes.io/docs/concepts/containers/images/#updating-images)
              for more info.
      schedulerStrategy:
        type:
          - string
          - "null"
        description: |
          Deprecated and no longer does anything. Use the user-scheduler instead
          in order to accomplish a good packing of the user pods.


  scheduling:
    type: object
    description: |
      Objects for customizing the scheduling of various pods on the nodes and
      related labels.
    properties:
      userScheduler:
        type: object
        description: |
          The user scheduler is making sure that user pods are scheduled
          tight on nodes, this is useful for autoscaling of user node pools.
        properties:
          enabled:
            type: boolean
            description: |
              Enables the user scheduler.
          replicas:
            type: integer
            description: |
              You can have multiple schedulers to share the workload or improve
              availability on node failure.
          image:
            type: object
            description: |
              The image containing the [kube-scheduler
              binary](https://console.cloud.google.com/gcr/images/google-containers/GLOBAL/kube-scheduler-amd64).
            properties:
              name:
                type: string
              tag:
                type:
                  - string
                  - "null"