.. _manage-charms: Manage charms ============= See first: `Juju | Charm `_, `Juju | Manage charms `_ Initialise a charm ------------------ To initialise a charm project, create a directory for your charm, enter it, then run ``charmcraft init`` with the ``--profile`` flag followed by a suitable profile name (for machine charms: ``machine``; for Kubernetes charms: ``kubernetes``, ``simple``, or ``flask-framework``); that will create all the necessary files and even prepopulate them with useful content. .. code-block:: bash charmcraft init --profile .. collapse:: Example session .. code-block:: bash mkdir my-flask-app-k8s cd my-flask-app-k8s/ charmcraft init --profile flask-framework .. terminal:: Charmed operator package file and directory tree initialised Now edit the following package files to provide fundamental charm metadata and other information: charmcraft.yaml src/charm.py README.md .. code-block:: bash ls -R .. terminal:: .: charmcraft.yaml requirements.txt src ./src: charm.py The command also allows you to not specify any profile (in that case you get the ``simple`` profile -- a Kubernetes profile with lots of scaffolding, suitable for beginners) and has flags that you can use to specify a different directory to operate in, a charm name different from the name of the root directory, etc. See more: :ref:`ref_commands_revisions`, :ref:`profile`, :ref:`files` See more: :ref:`manage-extensions` Add charm project metadata, an icon, docs ----------------------------------------- Specify that the project is a charm ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To specify that the project is a charm (as supposed to a bundle), in your ``charmcraft.yaml`` file set the ``type`` key to ``charm``: .. code-block:: yaml type: charm Specify a name ~~~~~~~~~~~~~~ To specify a pack-and-deploy name for your charm, in your charm's ``charmcraft.yaml`` file specify the ``name`` key. E.g., .. code-block:: yaml name: traefik-k8s .. See more: :ref:`recipe-key-name` Specify a title ~~~~~~~~~~~~~~~ To specify a title for your charm's page on Charmhub, in your charm's ``charmcraft.yaml`` file specify a value for the ``title`` key. E.g., .. code-block:: yaml title: | Traefik Ingress Operator for Kubernetes .. See more: :ref:`recipe-key-title` Add a summary ~~~~~~~~~~~~~ To add a summary line for your charm, in your charm's ``charmcraft.yaml`` file specify a value for the ``summary`` key. E.g., .. code-block:: yaml summary: | A Juju charm to run a Traefik-powered ingress controller on Kubernetes. .. See more: :ref:`recipe-key-summary` Add a description ~~~~~~~~~~~~~~~~~ To add a longer description for your charm, in your charm's ``charmcraft.yaml`` file specify a value for the ``description`` key. E.g., .. code-block:: yaml description: | A Juju-operated Traefik operator that routes requests from the outside of a Kubernetes cluster to Juju units and applications. .. See more: :ref:`recipe-key-description` Add contact information ~~~~~~~~~~~~~~~~~~~~~~~ To add maintainer contact information for a charm, in your charm's ``charmcraft.yaml`` file specify a value for the :ref:`links.contact ` key. E.g., .. code-block:: yaml links: contact: Please send your answer to Old Pink, care of the Funny Farm, Chalfont .. See more: :ref:`recipe-key-contact` Add a link to source code ~~~~~~~~~~~~~~~~~~~~~~~~~ To add a link to the source code for a charm, in your charm's ``charmcraft.yaml`` file specify an item under the :ref:`links.source ` key. E.g., .. code-block:: yaml links: source: - https://github.com/canonical/traefik-k8s-operator .. See more: :ref:`recipe-key-links` Add a link to the bug tracker ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To add a link to the bug tracker for a charm, in your charm's ``charmcraft.yaml`` file specify an item under the :ref:`links.issues ` key. E.g., .. code-block:: yaml links: issues: - https://github.com/canonical/traefik-k8s-operator/issues .. See more: :ref:`recipe-key-links` Add a link to the website ~~~~~~~~~~~~~~~~~~~~~~~~~ If your charm has a website outside of Charmhub, to add a link to this website, in your charm's ``charmcraft.yaml`` file specify an item under the :ref:`links.website ` key. E.g., .. code-block:: yaml links: website: - https://charmed-kubeflow.io/ .. See more: :ref:`recipe-key-links` Add docs and a link to the docs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you publish your charm on Charmhub, reference documentation about the charm's resources, actions, configurations, relations, and libraries is extracted automatically. However, you should also aim to add further docs, e.g., a tutorial, how-to guides, etc. To provide a link to these docs, in your charm's ``charmcraft.yaml`` file specify a value for the :ref:`links.documentation ` key. Note that at present this must be a Discourse page. E.g., .. code-block:: yaml links: documentation: https://discourse.charmhub.io/t/traefik-k8s-docs-index/10778 .. See more: :ref:`recipe-key-links` Add terms of use ~~~~~~~~~~~~~~~~ To add terms of use for your charm, in your charm's ``charmcraft.yaml`` file specify a value for the ``terms`` key. E.g., .. code-block:: yaml terms: - Butterscotch is regal - Cara is adorable .. See more: :ref:`recipe-key-terms` Add an icon ~~~~~~~~~~~ See :ref:`manage-icons`. Add runtime details to a charm ------------------------------ Require a specific Juju version ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To require a specific Juju version for your charm, in your charm's ``charmcraft.yaml`` specify the ``assumes`` key. E.g., .. code-block:: yaml assumes: - juju >= 3.5 .. See more: :ref:`recipe-key-assumes` Require a Kubernetes cloud ~~~~~~~~~~~~~~~~~~~~~~~~~~ To require a Kubernetes cloud for your charm, in your charm's ``charmcraft.yaml`` file specify the ``assumes`` key. E.g., .. code-block:: yaml assumes: - k8s-api .. See more: :ref:`recipe-key-assumes` Require a specific base and platforms ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To require a specific base and platforms for your charm, in your charm's ``charmcraft.yaml`` file specify the ``base``, and ``platforms`` keys. E.g., .. note:: In Charmcraft < 3.0 this was done via a single key: ``bases``. .. code-block:: yaml # The run time base, the base format is @, # accepted bases are: # - ubuntu@24.04 base: # The build time base, if not defined the base is also the build time # base, in addition to valid bases, the build-base can be "devel" # which would use the latest in development Ubuntu Series. build-base: platforms: # The supported platforms, may omit build-for if platform-name # is a valid arch, valid architectures follow the Debian architecture names, # accepted architectures are: # - amd64 # - arm64 # - armhf # - ppc64el # - riscv64 # - s390x : # The build time architecture build-on: | # The run time architecture build-for: | .. See more: :ref:`recipe-key-base`, :ref:`recipe-key-build-base` Specify container requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To specify container requirements, in your charm's ``charmcraft.yaml`` file specify the ``containers`` key. See more: :ref:`recipe-key-containers` Specify associated resources ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To specify the resources associated with the charm, in your charm's ``charmcraft.yaml`` file specify the ``resources`` key. See :ref:`manage-resources`. Specify device requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~ To specify device requirements, in your charm's ``charmcraft.yaml`` file specify the ``devices`` key. See more: :ref:`recipe-key-devices` Specify storage requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To specify storage requirements, in your charm's ``charmcraft.yaml`` file specify the ``storage`` key. See more: :ref:`recipe-key-storage` Specify extra binding requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To specify extra binding requirements, in your charm's ``charmcraft.yaml`` file specify the ``extra-bindings`` key. See more: :ref:`recipe-key-extra-bindings` Require subordinate deployment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To require subordinate deployment for your charm (i.e., for it to be deployed to the same machine as another charm, called its *principal*), in your charm's ``charmcraft.yaml`` file specify the ``subordinate`` key. See more: :ref:`recipe-key-subordinate` Manage actions ~~~~~~~~~~~~~~ See first: `Juju | Action `_, `Juju | Manage actions `_ To declare an action in your charm, in your charm's ``charmcraft.yaml`` file specify the ``actions`` key. See more: :ref:`recipe-key-actions` See next: :external+ops:ref:`manage-actions` Manage configurations ~~~~~~~~~~~~~~~~~~~~~ See first: `Juju | Application configuration `_, `Juju | Manage applications > Configure `_ To declare a configuration option for your charm, in your charm's ``charmcraft.yaml`` specify the ``config`` key. See more: :ref:`recipe-key-config` See next: :external+ops:ref:`manage-configurations` Manage relations (integrations) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See first: `Juju | Relation `_, `Juju | Manage relations `_ To declare a relation endpoint in your charm, in your charm's ``charmcraft.yaml`` specify the ``peers``, ``provides``, or ``requires`` key. See more: :ref:`recipe-key-peers` See more: :external+ops:ref:`manage-relations` Specify necessary libs ~~~~~~~~~~~~~~~~~~~~~~ .. See first: `Juju | Library <>`_ See more: :ref:`manage-libraries` Manage secrets ~~~~~~~~~~~~~~ See first: `Juju | User secret `_ To make your charm capable of accepting a user secret, in your charm's ``charmcraft.yaml`` specify the ``config`` key with the ``type`` subkey set to ``secret``. See more: :ref:`recipe-key-config` See next: :external+ops:ref:`manage-secrets` Specify necessary parts ~~~~~~~~~~~~~~~~~~~~~~~ See more: :ref:`manage-parts` Pack a charm ------------ To pack a charm directory, in the charm's root directory, run the command below: .. code-block:: bash charmcraft pack This will fetch any dependencies (from PyPI, based on ``requirements.txt``), compile any modules, check that all the key files are in place, and produce a compressed archive with the extension ``.charm``. As you can verify, this archive is just a zip file with metadata and the operator code itself. .. collapse:: Example session for a charm called microsample-vm Pack the charm: .. code-block:: bash charmcraft pack .. terminal:: Created 'microsample-vm_ubuntu-22.04-amd64.charm'. Charms packed: microsample-vm_ubuntu-22.04-amd64.charm Optionally, verify that this has created a .charm file in your charm's root directory: .. code-block:: bash ls .. terminal:: CONTRIBUTING.md charmcraft.yaml requirements.txt tox.ini LICENSE microsample-vm_ubuntu-22.04-amd64.charm src README.md pyproject.toml tests Optionally, verify that the .charm file is simply a zip file that contains everything you've packed plus any dependencies: .. code-block:: bash unzip -l microsample-vm_ubuntu-22.04-amd64.charm | { head; tail;} .. terminal:: Archive: microsample-vm_ubuntu-22.04-amd64.charm Length Date Time Name --------- ---------- ----- ---- 815 2023-12-05 12:12 README.md 11337 2023-12-05 12:12 LICENSE 250 2023-12-05 12:31 manifest.yaml 102 2023-12-05 12:31 dispatch 106 2023-12-01 14:59 config.yaml 717 2023-12-05 12:31 metadata.yaml 921 2023-12-05 12:26 src/charm.py 817 2023-12-01 14:44 venv/setuptools/command/__pycache__/upload.cpython-310.pyc 65175 2023-12-01 14:44 venv/setuptools/command/__pycache__/easy_install.cpython-310.pyc 4540 2023-12-01 14:44 venv/setuptools/command/__pycache__/py36compat.cpython-310.pyc 1593 2023-12-01 14:44 venv/setuptools/command/__pycache__/bdist_rpm.cpython-310.pyc 6959 2023-12-01 14:44 venv/setuptools/command/__pycache__/sdist.cpython-310.pyc 2511 2023-12-01 14:44 venv/setuptools/command/__pycache__/rotate.cpython-310.pyc 2407 2023-12-01 14:44 venv/setuptools/extern/__init__.py 2939 2023-12-01 14:44 venv/setuptools/extern/__pycache__/__init__.cpython-310.pyc --------- ------- 20274163 1538 files The command has a number of flags that allow you to specify a different charm directory to pack, whether to force pack if there are linting errors, etc. See more: :ref:`ref_commands_pack` .. caution:: **If you've declared any resources :** This will *not* pack the resources. This means that, when you upload your charm to Charmhub (if you do), you will have to upload the resources separately. See more: :ref:`manage-resources`. .. important:: When the charm is packed, a series of analyses and lintings will happen, you may receive warnings and even errors to help improve the quality of the charm. See more: :ref:`Charmcraft analyzers and linters ` .. See next: `Juju | Manage charms `_ .. _publish-a-charm: Publish a charm on Charmhub --------------------------- 1. Log in to Charmhub: .. code-block:: bash charmcraft login .. See more: :ref:`manage-the-current-charmhub-user` 2. Register your charm's name (the one you specified in ``charmcraft.yaml`` > ``name``): .. code-block:: bash charmcraft register my-awesome-charm .. See more: :ref:`manage-names` .. note:: This automatically creates 4 channels, all with track ``latest`` but with different risk levels, namely, edge, beta, candidate, stable, respectively. See more: :ref:`manage-channels`. 3. Upload the charm to Charmhub: Use the ``charmcraft upload`` command followed by the your charm's filepath. E.g., if you are in the charm's root directory, .. code-block:: bash charmcraft upload my-awesome-charm.charm .. terminal:: Revision 1 of my-awesome-charm created .. See more: :ref:`ref_commands_upload` .. note:: Each time you upload a charm to Charmhub, that creates a revision (unless you upload the exact same file again). See more: :ref:`manage-charm-revisions`. 4. If your charm has associated resources: These are not packed with the rest of the charm project, so you must upload them explicitly to Charmhub as well. For example: .. code-block:: bash charmcraft upload-resource my-super-charm someresource --filepath=/tmp/superdb.bin .. terminal:: Revision 1 created of resource 'someresource' for charm 'my-super-charm' .. See more: :ref:`manage-resources` .. note:: Each time you upload a resource to Charmhub, that creates a revision (unless you upload the exact same file again). See more: :ref:`manage-resource-revisions`. 5. Release the charm: To release a charm, release your revision of choice to the target release channel. E.g., .. code-block:: bash charmcraft release my-awesome-charm --revision=1 --channel=beta .. terminal:: Revision 1 of charm 'my-awesome-charm' released to beta .. See more: :ref:`manage-charm-revisions` .. note:: This automatically opens the channel. See more: :ref:`manage-channels`. .. See next: `Juju | Deploy a Charmub charm `_, `Juju | Update a Charmhub charm `_ .. tip:: To update the charm on Charmhub, repeat the upload and release steps. .. important:: Releasing a charm on Charmhub gives it a public URL. However, the charm will not appear in the Charmhub search results until it has passed formal review. To request formal review, reach out to the community to announce your charm and ask for a review by an experienced community member. See more: `Discourse | review requests `_. Also, the point of publishing and having a charm publicly listed on Charmhub is so others can reuse it and potentially contribute to it as well. To publicise your charm: - `Write a Discourse post to announce your release. `_ - `Schedule a community workshop to demo your charm's capabilities. `_ - `Chat about it with your charmer friends. `_