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 |
| Start a new charm |
| Build a charm |
| Deploy a local charm |
| Publish a charm |
| Add documentation |
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.10.0 from Canonical 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.
Deploy a local charm
You will want to test your built charm, before you publish it for others to consume. To do so, you will need a Kubernetes cluster. Follow the quickstart guide Once Juju is bootstrapped on that cluster, it is easy 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
Mapping table
| Level | Path | Navlink |
|---|---|---|
| 0 | Introduction | |
| 1 | Quickstart guide | |
| 1 | developer-env | Setup a development environment |
| 0 | Creating a charm | |
| 1 | new-charm | Charmcraft init |
| 1 | lifecycle-events | Lifecycle Events |
| 1 | framework-constructs | Framework Constructs |
| 1 | config | Add configuration |
| 1 | Manage a cluster | |
| 1 | Integrate with other charms | |
| 1 | Unit testing | |
| 1 | Debugging | |
| 0 | Advanced Topics | |
| 1 | WIP Discuss your charm | |
| 1 | charm-docs | Add documentation |
| 1 | Define an action | |
| 1 | WIP Use resources | |
| 1 | WIP Traditional Infrastructure | |
| 1 | WIP Discuss your charm | |
| 1 | WIP Kubernetes | |
| 0 | Quick Reference | |
| 1 | API Reference | |
| 1 | Juju Glossary | |
| 1 | framework-releases | Release Notes |
Redirects
Mapping table
| Path | Location |
|---|