See also: Charm publication checklist
When you create your charm, an important decision is how to name it. Below are some recommendations.
Naming charms
Of course, there is a large number of existing charms already with all their variants on naming. Please check, if naming of existing Charms can be improved, it will help others to find your Charms. But more importantly, consider the following points for new charming efforts:
Required / Recommended | Background | Examples |
---|---|---|
Slug-oriented naming required: ASCII lowercase letters, numbers, and hyphens. | Ensure URL-safeness, finding charms easier. |
node_red node-red |
Do not abbreviate application names. | Finding charms easier. | matterm mattermost |
Do not consider camelcase naming. | Think of slugs, also not supported. | NodeRed node-red |
No charm or operator suffix | It is about Charms Exception: Bundles need to be distinguished from the Charm. |
ghost-operator ghost grafana-charm grafana However: discourse discourse-bundle |
No organisation as prefix | Hard to have it consistently across all charms, Belongs to charmcraft.yaml |
kafka oracle-mysql mysql |
No publisher name as prefix to the charm name. | Hard to have it consistently across all charms, Belongs to charmcraft.yaml |
mysql-charmers-mysql-server mysql charmteam-kafka kafka |
Avoid the purpose, use the name of the application instead. | Multiple charms for same purpose exist or will come. | general-cache varnish (if the varnish OSS project represents the application) |
Do not use non-production identifiers, for public. | Not useful for the community of Charmhub users. | jenkins-test mysql-draft hadoop-internal kafka-demo |
Single charms: Avoid mix of app name and purpose. | Suffixes or prefixes shall be omitted and can be part of summary. | drupal-server drupal However: kubeflow-dashboard kubeflow-pipeline kubeflow-volumes |
Multiple charms: Put the name before the function. | Sorting. | pipeline-kubeflow kubeflow-pipeline |
Explain short names if used. | Three letter acronyms: prone to be confused. | |
Exception: Use “-k8s” for kubernetes only charms | In general, do not use a suffix for platforms. Only a) for “kubernetes only” charms and b) another non-k8s-charm is around, use the suffix "-k8s” to distinguish the k8s-charm from the other. For a charm covering a workload that makes only sense for k8s and nowhere else, avoid the suffix. | graylog-k8s |
Maintainer contact
Currently, the charmcraft.yaml
supports the maintainer of the charm being listed :
A list of maintainers in the format "First Last <email>
The naming of the maintainer has three main goals:
- Identify the right person to contact
- Visibility (for merits) of the publisher(s) or author(s) of the Charm
- Transparent responsibility for the published software. However, please note that the maintainer list does not necessarily denote the responsible party (copyright holder) of the published Charm implementation.
The maintainer field in charmcraft.yaml
must be filled out, either with
-
A maintaining individual contact
-
Multiple maintaining individual contacts if that applies (preferred),
-
The maintaining organisation if that applies.
-
Do not use fantasy / virtual team names as feedback has shown it causes confusion.
Naming repositories
Charms shall have a publicly accessible (git) repository. Opposed to the charm listing on Charmhub.io, a distinguishing element in the name of a repository helps to identify the right repository with the Charm implementation.
The distinguishing element is the suffix “-operator”, because that aligns also with the names of the other parts in the Juju world, such as the Charmed Operator Framework or the Charmed Operator SDK. So, in summary, we have the following steps:
-
Name the repository like your charm (see naming rules above)
-
Add a suffix to it: -operator (because: Charmed Operator SDK)
-
Prefer suffix over prefix (
operator-mydatabaseserver
) -
Plural form only if there are in fact multiple charm implementations in the repository, do not mimic an (adverbial) genitive.
It is understood that many repositories already exist with the suffix -charm
along to the repositories with -operator
. Repository renaming can be hard in some cases. The naming guide defines the preferred naming.
Of course, some organisations have their own naming conventions for their repositories which cannot be easily overruled.