docs: add doc about subordinate charms#2455
Conversation
Co-authored-by: Copilot <copilot@github.com>
|
Draft doc updated per our discussion at daily. Ready for review - thanks |
|
|
||
| ## Runtime constraints | ||
|
|
||
| A subordinate charm can't control the Ubuntu base that its units run on. If the principal charm supports multiple bases, consider publishing a separate revision of the subordinate charm for each base. |
There was a problem hiding this comment.
Talking about "the" principal charm like this seems wrong, since the subordinate doesn't know what principal it is deployed with.
I'm still not clear why a subordinate charm can't control the base that it runs on. I assume it still has to declare its bases in charmcraft.yaml. Does Juju just ignore it?
There was a problem hiding this comment.
I believe it will error if the charm isn't available for the base the principal is delayed on.
Maybe this would be better as encouragement to support as many bases as possible? Something about the base having to match the principal, so it's good to handle as many LTS bases as feasible.
There was a problem hiding this comment.
I believe it will error if the charm isn't available for the base the principal is delayed on.
Like if you try to deploy a regular charm on a machine with the wrong base?
I think what we're getting at here is that with a principal charm, you can pretty easily say you run on only one specific base, and only your direct users care. Whereas a subordinate charm may have interest from users of different principal charms across different bases.
But TBH I don't think this difference is all that substantial -- in either case you have to find out what your users need and what you can afford to support.
Maybe this would be better as encouragement to support as many bases as possible? Something about the base having to match the principal, so it's good to handle as many LTS bases as feasible.
What I want to push back against (until I understand it further, at least) is the idea that subordinate charms need to support arbitrary bases.
Sure, someone might want to deploy you on Ubuntu 20.04 with their principal charm that runs there, and it would be a shame if they couldn't, but the same is true of principal charms. I just don't see the difference between "there's a user who wants to deploy our charm on an old base", and "there's a user who wants to deploy our charm on an old base alongside another charm".
It seems like developers of subordinate charms should be able to be just as clear about their supported bases and support periods as any other charm. But maybe there's something I'm missing here.
There was a problem hiding this comment.
James and I discussed this today. Our thinking is that for now it's best to focus on the importance of documenting the subordinate charm's support for bases - at least until we work on #2460.
Updated wording:
A subordinate charm can’t control the Ubuntu base that its units run on. When you document which charms your subordinate charm is intended to be used with, mention any differences in supported bases.
tonyandrewmeyer
left a comment
tonyandrewmeyer
left a comment
There was a problem hiding this comment.
I think we should link to the Juju docs, at least https://documentation.ubuntu.com/juju/latest/reference/charm/#subordinate-charm and maybe https://documentation.ubuntu.com/juju/latest/reference/relation/#subordinate-relation.
I think what we really need is a how-to for writing a subordinate that goes alongside this explanation. But happy to leave that for another cycle.
A few general comments noted as well. I'm approving now so I don't block things while travelling. I assume you and James can narrow down the bits left, including the comments I've left and whether they should be addressed or not.
|
|
||
| ## Runtime constraints | ||
|
|
||
| A subordinate charm can't control the Ubuntu base that its units run on. If the principal charm supports multiple bases, consider publishing a separate revision of the subordinate charm for each base. |
There was a problem hiding this comment.
I believe it will error if the charm isn't available for the base the principal is delayed on.
Maybe this would be better as encouragement to support as many bases as possible? Something about the base having to match the principal, so it's good to handle as many LTS bases as feasible.
| <!-- TODO when ref target is available (from https://github.com/juju/juju/pull/22373) --> | ||
| <!-- See {external+juju:ref}`Juju | The implicit juju-info relation <the-implicit-juju-info-relation-endpoint>`. --> |
There was a problem hiding this comment.
Uncomment this before merging
james-garner-canonical
left a comment
james-garner-canonical
left a comment
There was a problem hiding this comment.
Looks great, thanks @dwilding.
3 participants
This PR adds an explanation doc about subordinate charms. My intention is to give a summary of what a subordinate charm is, when it's appropriate to write a subordinate charm, and some of the considerations. This isn't meant to be a detailed guide on how to write a subordinate charm.
Preview doc