=====================================
YAML File Value Overriding in Hubploy
=====================================

There are several ``.yaml`` files present in the hubploy-template repository. It can be unclear 
which settings go in which files. This topic hopes to clear that up a bit. As a reminder, here is 
the directory structure that Hubploy expects (minimized for focus on the yaml files)::

	hubploy-template/
	├── .github
	│   └── workflows
	│       ├── deploy.yaml
	│       └── image-build.yaml
	├── deployments
	│   └── hub
	│       ├── config
	│       │   ├── common.yaml
	│       │   ├── prod.yaml
	│       │   └── staging.yaml
	│       ├── hubploy.yaml
	│       └── secrets
	│           ├── aws-ecr-config.cfg
	│           ├── aws-eks-config.cfg
	│           ├── prod.yaml
	│           └── staging.yaml
	└── hub
	    ├── Chart.yaml
	    ├── requirements.lock
	    ├── requirements.yaml
	    ├── templates
	    │   ├── jupyter-notebook-config.yaml
	    │   └── nfs-pvc.yaml
	    └── values.yaml


GitHub Action Files
-------------------

The two files under ``.github/workflows/`` manage individual GitHub Actions for Hubploy. They are 
independent of most of the rest of Hubploy.


JupyterHub Deployment Files
---------------------------

The main value files are related to the JupyterHub Helm release. The lowest level of these are 
specified in ``hub/values.yaml`` via::

	jupyterhub: {}

The braces can be removed once there are yaml values in the file, but they are needed if this block
is empty. Appropriate values to put in this file are those that will span both versions of all 
JupyterHubs that you will deploy with Hubploy, as this file will be used for all of them.

The next file in the heirarchy is ``deployments/hub/config/common.yaml``. This file covers 
deployment values that are common to both the staging and production hubs that Hubploy named 
"hub," or what you had changed that folder name to. If there are multiple JupyterHubs being managed
, each one will have a ``common.yaml``. Values in this file will overwrite ``hub/values.yaml``.

The next two files in the heirarchy are also in the config folder: ``staging.yaml`` and 
``prod.yaml``. These contain values for the staging and production hubs, respectively. Values in 
these files will override the previous two. These two files do not override each other ever since they are for two different hubs.

The last files in the heirarchy are under the ``secrets`` directory. These are set in a folder that
we tell git-crypt to encrypt when pushing code to GitHub. In general, there shouldn't be anything 
in these files that overwrites the other ``staging.yaml`` and ``prod.yaml``. It is more expected 
that values in these files will overwrite default credentials or paths present in the first two 
files.

A quick summary of the heirarchy follows in descending priority (lower overwrites higher) 
but ascending generality (higher applies to more hubs)::

	hub/values.yaml
		deployments/hub/config/common.yaml
			deployments/hub/config/staging.yaml
			deployments/hub/config/prod.yaml
			deployments/hub/secrets/staging.yaml
			deployments/hub/secrets/prod.yaml


Local Hub Helm Chart Files
--------------------------

Everything under the hub folder is related to the Helm Chart. In ``Chart.yaml``, the main 
specification is what the Chart is named and what version you are on. In ``requirements.yaml``, 
the JupyterHub Helm chart is listed as the only dependency and you can pick a specific version.
``values.yaml`` is used to provide the lowest level of values for JupyterHub configuration and 
other deployment pieces that are present in the ``templates/`` folder or other dependencies 
you choose to add to the Helm chart.