MetalLB offers a software network load balancing implementation that allows for LoadBalancing services in Kubernetes. Upstream documentation for MetalLB can be found at https://metallb.universe.tf/
The charm currently supports MetalLB Layer 2 mode.
The official documentation for this charm and how to use it with Kubernetes can be found at MetalLB | Ubuntu.
Thanks @addyess for the review request! @sed-i can you please help with this review? You can go through and tick off the items on the checklist available here and post the result in this thread.
The overall charmhub.io appearance looks good, which means: * The name complies with the naming guidelines. * The publisher is identified. * The links are provided. * The documentation looks reasonable.
Change “Homepage” link to operator website (github, not launchpad); a single tutorial is broken into multiple pages, which is incorrect? On github project page, add a link back to charmhub.io project page.
A reasonable styleguide is enforced in tox.ini/similar and in CI/CD.
In metadata.yaml: (1) “tags” is obsolete and can be removed; (2) “assumes k8s-api” seems wrong, as it is a workloadless & machine charm; (3) this is a k8s charm so it should be named metallb-k8s and the repo metallb-k8s-operator.
tags: okay, it’s a fairly old charm so those have been in there quite a while
assumes k8s-api: this isn’t a machine charm? it’s definitely a k8s charm – correct there’s no workload (sidecar) but it isn’t intended to run in a machine model. It applies workloads to a k8s cluster via a lightkube client
No CI in place
Actually, this charm is built via launchpad (Charm recipes : MetalLB Operator) on request by a jenkins agent and uploaded to Charmhub when changes are detected in the charm.
Perhaps my understanding is outdated, but I learnt about writing tutorials from this page, when juju.is/tutorials was an index of tutorials rendered in a special way. Perhaps @tmihoc could help here: is it ok to split a tutorial into several discourse pages?
In that case, shouldn’t the repo be named metallb-k8s-operator and in metadata.yaml have name: metallb-k8s?
@addyess For the charm naming, you can follow the guidelines set here. If the workload you are covering would only make sense for k8s and nowhere else you can avoid the suffix. If a charm could be created for the workload for any other substrate, adding a “-k8s” suffix is better.
Yes this workload metallb only makes sense for k8s. Metallb isn’t deployable to a machine.
Also, this charm is already deployed in many environments with this name. It’s been named this for 9 months.
is it ok to split a tutorial into several discourse pages?
OK it is. My question is: What do we gain by that?
Some argue that breaking a tutorial down into short sections, each of which achieves something meaningful, is better for engagement. On the other hand, my feeling is that breaking things down too much, or in the wrong way, can make even something simple and straightforward feel big and choppy. So which one is it in this case?
My general thinking on this (disclaimer: it’s always evolving)
I am convinced charm documentation pages should not try to teach people about Juju – rather, they should systematically link up to Juju for all generic content.
On the other hand, they must document all the charm specific content.
This includes Reference material – requirements (e.g., 50 GiB memory), charm-specific actions, configurations, integrations (including what data passes through an endpoint, where meaningful), resources.
It can also include How-to guides – e.g., to guide the user through places where just running a Juju command won’t be sufficient to obtain the right results (e.g., high-availability for charms that require an external load balancer, successful upgrades where you need to configure s3 first, etc.) or to surface particular solutions that become possible by virtue of a charm’s actions, configurations, integrations. (I say “can include How-to guides” because, in my view, if a charm’s documentation needs too many of these, that means we’re doing something wrong, either in the charm or in Juju, either in the products or in the docs.)
Additionally, any product, no matter how small, can benefit from a tutorial, and the tutorial should follow the logic (and, why not, the exact structure) below:
Set things up (I am working on a doc that will cover this generically; charm docs can then simply link to that, and only comment further if necessary)
Watch this charm do wonders for you (think end-to-end story weaving together the actions, configs, integrations, etc., in a meaningful way; keep in mind the person whose life you’re trying to make easier with this charm)
Tear things down (always give the user a way out – how annoying is it when you create an account somewhere and then you find out there is no easy “Delete account” button?; my general setup doc will include a section on this as well)
Thanks Adam, you’ve obviously put a lot of time and effort into the docs for the charm which is great, since so many charms have little or no documentation at all.
Rolling the tutorial steps into a single page won’t be too difficult., I can probably help with that.
