How to manage charms

This document shows various ways in which you may interact with a charm.

In Juju, a deployed charm is an application. As such, some of these types of interaction can happen at both levels, in different ways / in the same way. Below we indicate this with links to How to manage applications.

Contents:

Query Charmhub for available charms or bundles

To query Charmhub for available charms or bundles, run the find command followed by your keyword of interest. For example:

juju find wordpress

See more: juju find

View details about a Charmhub charm

To view details about a Charmhub charm, run the info command followed by the name of the charm. For example:

juju info postgresql

See more: juju info

For comprehensive information about the charm, including charm documentation, it is always best to see the charm’s page on Charmhub.

Find out the resources available for a charm

See: How to manage charm resources > Find out the resources available for a charm

Download a Charmhub charm

This is relevant for air-gapped deployments.

To download a Charmhub charm, run the download command followed by the name of the charm. For example:

juju download postgresql

See more: juju download

Deploy a charm

See: How to manage applications > Deploy an application

Update a charm

Updating a charm to the latest revision always involves the refresh command, but the exact way to use it differs a little bit depending on whether you are dealing with a Charmhub charm or rather a local charm.

Update a Charmhub charm

Because of the way charm channels work, ‘updating’ doesn’t have to mean ‘upgrading’ – you can switch to any charm revision, no matter if it’s newer or older. The instructions below reflect this.

However, as newer versions typically contain improvements, Juju will notify you if a new version exists: Juju polls Charmhub once a day to check for updates and, if an update is found, the poll will cause juju status to indicate that a newer charm version is available.

  1. If you don’t know your current channel: Run status and check the App > Channel column.

  2. If you don’t know which channel you want to update to / would like to find out all the available channels: Run info followed by the charm name.

  3. Run refresh followed by the charm name and the desired new channel.


Expand to view an example featuring the machine charm for PostgreSQL
# Find out the current channel (see App > Channel):
$  juju status
Model        Controller  Cloud/Region         Version  SLA          Timestamp
welcome-lxd  lxd         localhost/localhost  3.1.6    unsupported  14:58:37+01:00

App          Version        Status   Scale  Charm           Channel    Rev  Exposed  Message
postgresql                  waiting    0/1  postgresql      14/stable  351  no       agent initialising

Unit            Workload  Agent       Machine  Public address  Ports  Message
postgresql/0*   waiting   allocating  2        10.122.219.3           agent initialising

Machine  State    Address         Inst id        Base          AZ  Message
2        started  10.122.219.3    juju-f25b73-2  ubuntu@22.04      Running

# Find out all the available channels:
$ juju info postgresql
name: postgresql
publisher: Canonical Data Platform
summary: Charmed PostgreSQL VM operator
description: |
  Charm to operate the PostgreSQL database on machines.
store-url: https://charmhub.io/postgresql
charm-id: ChgcZB3RhaDOnhkAv9cgRg52LhjBbDt8
supports: ubuntu@22.04
tags: databases
subordinate: false
relations:
  provides:
    cos-agent: cos_agent
    database: postgresql_client
    db: pgsql
    db-admin: pgsql
  requires:
    certificates: tls-certificates
    s3-parameters: s3
channels: |
  14/stable:         351                            2024-01-03  (351)  29MB  amd64  ubuntu@22.04
  14/candidate:      363                            2024-01-31  (363)  33MB  amd64  ubuntu@22.04
  14/beta:           363                            2024-01-31  (363)  33MB  amd64  ubuntu@22.04
  14/edge:           365                            2024-02-02  (365)  33MB  amd64  ubuntu@22.04
  latest/stable:     initial-reactive-278-ge3f064a  2023-11-09  (345)  7MB   amd64  ubuntu@16.04, ubuntu@18.04, ubuntu@20.04, ubuntu@22.04
  latest/candidate:  ↑
  latest/beta:       ↑
  latest/edge:       ↑

# Update the charm to revision `365` by switching to the `14/edge` channel:
$ juju refresh postgresql --channel 14/edge
Added charm-hub charm "postgresql", revision 365 in channel 14/edge, to the model
no change to endpoints in space "alpha": certificates, cos-agent, database, database-peers, db, db-admin, restart, s3-parameters, upgrade

# Verify that the charm has been updated (see App > Channel):

$ juju status
Model        Controller  Cloud/Region         Version  SLA          Timestamp
welcome-lxd  lxd         localhost/localhost  3.1.6    unsupported  15:05:16+01:00

App          Version        Status  Scale  Charm           Channel  Rev  Exposed  Message
postgresql   14.9           active      1  postgresql      14/edge  365  no       

Unit            Workload  Agent      Machine  Public address  Ports     Message
postgresql/0*   active    executing  2        10.122.219.3    5432/tcp  (config-changed) 

Machine  State    Address         Inst id        Base          AZ  Message
2        started  10.122.219.3    juju-f25b73-2  ubuntu@22.04      Running


See more: juju status](/t/10173), [juju info, juju refresh

Update a local charm

To upgrade a local charm, run the refresh command followed by the name of the charm and the local path to the charm:

juju refresh juju-test --path ./path/to/juju-test

The command offers many other options, for example, the possibility to replace a charm completely with another charm by using the --switch option followed by a different path (a process known as ‘crossgrading’). (Note: --path and --switch are mutually exclusive. Use --switch if you want to replace your existing charm with a completely new charm.)

See more: juju refresh

Remove a charm

As a charm is just the means by which an application is deployed, there is no method to remove a charm. What you can do, however, is remove the application.

See more: How to remove an application


Contributors: @hmlanigan, @tmihoc

Last updated 10 days ago. Help improve this document in the forum.