Operator Publication

Registration and visibility

Operator names

Register a name for an operator with the charmcraft register command. Some names may be reserved or registered already, just ask on the community forum if you think a reserved name should be used for your operator.

When you register a name, bear in mind the ‘principle of least surprise’ which is that you may not use a well‐known name unless you intend to publish your operator for anybody to use to drive that well‐known workload. A common convention if you are not sure is to prefix your own name to the application name, for example ‘frblix‐wmdmon’; we can rename your operator to drop the suffix once there is consensus it should be the main operator for that well‐known name.

Private operators

Anybody may use this site to host their own private operators. There are no special requirements or restrictions for private operators, other than the expectation that usage of the site is in line with the goals of the community.

Private operators live in the same namespace as public operators and their names may not conflict. To store a private operator here, just register the name.

A private operator will not show up in listings or on web pages, and can only be retrieved by its publisher and contributors. So a single developer, or a group of developers, can push/release/deploy/update that charm for their own purposes, but it is private to them.

Public operators

Public operators can be retrieved by anybody. Their list of channels and released revisions is visible to everybody. The designated maintainer’s name and contact information are visible and they should be accountable for the operator and responsive to bug reports and pull requests.

We encourage public operator maintainers to release beta and release candidate revisions into the appropriate channels, and to maintain separate tracks for major and minor releases, but not point releases, following semantic versioning where possible.

Channels

Operators are published in channels with a fixed naming convention: track, stability, and branch. Examples might include:

  • 1.2/stable/hotfix-342443
  • 2.9/beta
  • 3.0/rc
  • latest/stable
  • lates

In general channel looks like this:

  • track/stability/branch

A given deployment remembers the channel name, and updates will come from the same channel. So if you deploy from the release candidate channel, and then do an update, you can expect to get the latest release candidate if one is available.

Tracks

The track represents the version of the operator. In general, track names tend to follow the upstream application version name, or be related to it in an obvious way. We recommend that tracks use major.minor semantic versioning. There is always a ‘latest’ track, which doesn’t have a particular version associated with it. The version you get from the latest track will change based on the preferences of the publisher. Use the latest track to keep up with the flow in cases where you don’t necessarily care to hard lock a major version.

One track can be designated the default track for that operator, which means that deploying the operator without specifying a track will result in that track being selected (and remembered as if it had been deployed explicitly). The latest track is the default if no default has been specified.

Stability

The four stability options in channel names are stable, rc, beta and edge. It is good practice for the publisher to keep these populated whenever they have code that reasonably conforms to expectations of those levels of stability. The edge stability should be auto‐updated with daily builds after CI tests have passed, so that it reflects current development whenever tests are passing. Beta and RC channels are a way for users to test pre‐release versions of operators; these channels should be populated when such versions exist, and closed otherwise.

When an edge, beta or RC channel is closed, the operator will be drawn from the next‐more‐stable channel. If you have deployed a beta version, and there is currently no beta but there is an RC, then you will get the RC. If there is currently no RC, you will get the stable channel. You will never get a less-stable channel, only a more‐stable channel.

If no stability is specified then the stable channel is assumed. So deploying ‘1.2’ will in effect deploy ‘1.2/stable’.

Branches

Most deployments will not use a branch name; branches are optional and are typically only used during development to enable feature branch testing, and in production for the distribution of very specific hotfixes that are not yet ready to be rolled out universally.

Revisions

When the publisher pushes a new version of an operator, a Docker image to be used with the operator, or another resource (such as a data set or trained machine learning model), a revision is assigned for that asset. The publisher can push new assets at any time and get new revisions, but those revisions are not considered released until the publisher makes an explicit decision to release them into a particular channel with the charmcraft release command. Publishers can test revisions before they decide to release them for wider consumption in a stable, rc, beta or edge channel.