docs: add section on using jupyterhub as a subchart

[consideRatio]

It would be nice to have a section in the docs on using jupyterhub as a subchart.

Related

• @manics suggesting value of documenting .fullname helpers: https://github.com/jupyterhub/zero-to-jupyterhub-k8s/pull/2042#issuecomment-782717957
• Description of jupyterhub.<something>.fullname helpers: https://github.com/jupyterhub/zero-to-jupyterhub-k8s/pull/2042#discussion_r579641446
• PR adding fullnameOverride / nameOverride which increased the need to have a way to not hardcode references: https://github.com/jupyterhub/zero-to-jupyterhub-k8s/pull/1923

[consideRatio]

From https://github.com/jupyterhub/zero-to-jupyterhub-k8s/pull/2042#discussion_r579853992

But, named templates defined in _helpers.tpl are globally scoped and can be used from a parent chart with the parent chart's scope.

Ah! This is the part I misunderstood, thank you! It's a specific issue to exporting helpers to be used by downstream charts. I never realized helpers were available to other charts. Do we need to think about what our public helper API is and how it's documented? I always assumed these were purely private. What would happen in a case like mybinder.org, where jupyterhub is a dependency two hops away, i.e. binderhub.jupyterhub.hub...? Is that sustainable?

Me responding in this issue

Do we need to think about what our public helper API is and how it's documented?

I have done my absolute best to consider this, and I find that this is about as good as it get at the moment. With that said, I don't find it great.

I've opened this issue to represent this such effort going onwards.

What would happen in a case like mybinder.org, where jupyterhub is a dependency two hops away, i.e. binderhub.jupyterhub.hub...? Is that sustainable?

At this point, mybinder.org templates would need to use hardcoded names or modify the scope passed to a named template such as "jupyterhub.hub.fullname".

I don't think that is a good solution, but my attempts to come up with improvements have failed - I find that the complexity added / maintenance sustainability of my ideas are not worth locking into.

[minrk]

Great idea! I have some questions that might help with what might go in these docs.

At this point, which ones do we have and what helpers are considered a 'public' API (i.e. one we should try not to break)? I see some issues around what the chart name that means some will work if it's a sub-chart, but others will not. Which ones are in which state? How do we communicate with both chart contributors and dependent-chart authors what's public and what's not?

As I see it right now, with no documentation yet, these helpers may as well not exist yet from the perspective of downstream charts. So we can be free to pick from scratch what should be considered for stable, documented exports.

How much is exporting and documenting helpers an existing practice in other charts? And how often do mainstream charts export helpers that work regardless of the chart's name or depth in dependencies? Here, I'm trying to get at are we trying to keep up with existing best practices, or are we going above and beyond what anybody else does?

While I appreciate the effort to make it work as much as possible, complicated helpers seem to be among the least maintainable things in helm, so I think we should aim to keep helpers as simple and as few as possible.

[consideRatio]

At this point, which ones do we have and what helpers are considered a 'public' API (i.e. one we should try not to break)?

At this point, I consider all helpers private, but in the future I'd like to through documentation promote a few of the jupyterhub.<something>.fullname helpers to be considered public, but not all.

How much is exporting and documenting helpers an existing practice in other charts? And how often do mainstream charts export helpers that work regardless of the chart's name or depth in dependencies? Here, I'm trying to get at are we trying to keep up with existing best practices, or are we going above and beyond what anybody else does?

I've not yet seen anyone document their helpers for parent chart consumption. There is the concept of library charts where you only install helpers, but I've also never seen a library chart. Doing some research of library charts may be relevant.

While I appreciate the effort to make it work as much as possible, complicated helpers seem to be among the least maintainable things in helm, so I think we should aim to keep helpers as simple and as few as possible.

I agree especially on exposing them for consumption to other charts, but also in general. It is a balancing act that I think contain a lot of grey zones though, especially for a chart as big as ours.

[manics]

Is it possible to use a naming convention such as a _ prefix to indicate _private in addition to the docs? It'd mean renaming all the existing helpers, but would make reviewing future changes a lot easier since there's no need to cross-reference a change with the docs.