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 CharmcraftCharmcraft 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
"$"above represents the command line prompt. Sample commands come after this prompt with any relevant output shown below.
Start a new charmYou 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 charmYou 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 charmCharmhub 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
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.
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
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.
Creating a charm
- Charmcraft init
- Lifecycle Events
- Framework Constructs
- Add configuration
- Manage a cluster
- Integrate with other charms
- Unit testing
- WIP Discuss your charm
- Add documentation
- Define an action
- WIP Use resources
- WIP Traditional Infrastructure
- WIP Kubernetes
|Documentation Operator Framework||/docs|
|Set up your Operator Framework development environment||/docs/developer-env|
|Start a new charm with the Operator Framework||/docs/new-charm|
|Operator Framework patterns and constructs||/docs/framework-constructs|
|Manage configration with the Operator Framework||/docs/config|
|Handling charm lifecycle events with the Operator Framework||/docs/lifecycle-events|
|Add documentation to your charm||/docs/charm-docs|
|Operator Framework Release Notes||/docs/framework-releases|