Documentation Operator Framework

Overview

The Operator Framework allows the development of operators in a simple and straightforward way, using standard Python structures to allow for clean, maintainable, and reusable code. Charmcraft is a command line tool used alongside the Operator Framework to create, build, and publish operators (aka charms).

The following sections provide a basic overview of the process of developing a new charm, from installation through publication:

Install Charmcraft

Charmcraft is available as a snap, and can be installed on any Linux distribution [with snap support](https://snapcraft.io/docs/installing-snapd):
$ sudo snap install charmcraft --beta
charmcraft (beta) 0.6.0 from John Lenton (chipaca) installed

The "$" above represents the command line prompt. Sample commands come after this prompt with any relevant output shown below.

Start a new charm

You can create a new charm now, but in order to test your charm you will need a working . To create a skeleton charm:
$ mkdir hello-operator
$ cd hello-operator
hello-operator$ charmcraft init --name=helloworld
All done.
There are some notes about things we think you should do.
These are marked with ‘TODO:’, as is customary. Namely:
      README.md: fill out the description
      README.md: explain how to use the charm
  metadata.yaml: fill out the charm's description
  metadata.yaml: fill out the charm's summary

To better understand the files generated by charmcraft init take a look at our detailed breakdown of a new charm.

The following is a list of topics you may wish to review for developing a new charm:

Build a charm

You now have a functioning charm codebase. It is time to build and test your charm.
$ charmcraft build
Done, charm left in 'helloworld.charm'

This will create two artifacts in your charm directory: a new directory named build which contains the built charm for review; and, a binary file named helloworld.charm which is used when deploying or publishing your charm.

You will want to test your built charm, before you publish it for others to consume. To do so, you will need a working development environment. Once Juju is configured with a working provide, it is time to deploy your built charm:

$ juju deploy ./helloworld-charm
Deploying charm "local:kubernetes/helloworld-0".

While Juju is provisioning the units for your charm, you can check on its status. Once the process is complete, the status should look like:

$ juju status
Model        Controller  Cloud/Region        Version  SLA          Timestamp
development  micro       microk8s/localhost  2.8.6    unsupported  07:04:33-07:00

App         Version  Status   Scale  Charm       Store  Rev  OS          Address  Notes
helloworld           unknown      1  helloworld  local    0  kubernetes

Unit           Workload  Agent  Address  Ports  Message
helloworld/0*  waiting   idle                   waiting for container

Publish a charm

Charmhub uses Ubuntu One for developer accounts. If you already have an Ubuntu One account, you are ready to publish your first charm. If you need to create an account you can visit [Ubuntu One Log in](https://login.ubuntu.com/+login) now, and select "I don't have an Ubuntu One account".

The first step to publishing your charm is to reserve a name for the charm:

$ charmcraft register helloworld
Congrats! You are now the publisher of 'helloworld'

All commands to Charmhub need to be authenticated. Charmcraft handles authentication automatically when required. If credentials are expired or not found, a browser page will open asking you to sign into Charmhub. You can always check your active credentials with charmcraft whoami.

You can also view your list of reserved names:

$ charmcraft names
Name            Visibility    Status
helloworld      private       registered

You are now ready to release a revision of your built charm:

$ charmcraft upload
Revision 1 of 'helloworld' created

To verify the new revision uploaded successfully, you can see all active revisions of your charm:

$ charmcraft revisions
Revision    Version    Created at    Status
1           0.1        2020-11-11    approved

These commands did not require you to specify the charm’s name. This is because we’re in the charm’s project directory, so the name is retrieved automatically. If you want to ask for any other charm you can use the --name option.

Now it’s time to release!

$ charmcraft release 1 stable
Revision 1 of charm 'helloworld' released to stable

For more information about channels, private/public charms, and more, please visit our article on Publishing.

Add documentation

Your charm is now available on Charmhub. You should be able to access it with the following URL: https://charmhub.io/<charm>/. Following the previous sections, <charm> would be replaced with helloworld. For an example, you can review the Mattermost Operator. Each charm page has a “Docs” tab on Charmhub, and you may wish to add additional information to this section.

Create a cover page

To get started, you will need to create visit the Charmhub Discourse and login. You will be able to use the same Ubuntu One login you used for publishing your charm. Once logged in, follow these steps:

  • Browse to the Charm Category on Discourse
  • Click on the +New Topic botton near the top of the page
  • Name your topic <charm> docs - index - replacing <charm> with your reserved charm name
  • The body of this topic will be used as the cover page for the Docs section of your charm page on Charmhub

Link your cover page to your charm

The final step is to link your new topic to your publish charmed. Browse to your new topic and discouse and copy the URL from your browser. Add the URL to metadata.yaml with the name docs:

docs: https//discourse.charmhub.io/t/charm-docs-index/9999

You will need to build and publish your charm again to get Charmhub to pick up the docs link. Charmhub will only pull the link from the stable channel.

For advanced topics, like populating the navigation panel and creating additional pages, please visit our Add documentation tutorial.

Navigation

Introduction

Creating a charm

Advanced Topics

Quick Reference

URLs

Mapping table

Redirects

Mapping table
Path Location