How to manage units

doc
1

See also: Unit

This document demonstrates various operations that you can perform on a unit.

Units are also relevant when adding storage or scaling an application. See How to manage storage and How to manage applications.

Contents:

Add a unit

To add a unit, use the add-unit command followed by the application name:

This is only true for machine deployments. For Kubernetes, see How to controller the number of units.

juju add-unit mysql

By using various command options, you can also specify the number of units, the model, the kind of storage, the target machine (e.g., if you want to collocate multiple units of the same or of different applications on the same machine – though watch out for potentials configuration clashes!), etc.

See more: juju add-unit

To add a unit in python-libjuju client, you simply call add_unit() on your Application object, as follows:

my_app.add_unit(count=3)

See more: Application (module), Application.add_unit(), Application.scale()

Control the number of units

The procedure depends on whether you are on machines or rather Kubernetes.

Machines. To control the number of an application’s units in a machine deployment, add or remove units in the amount required to obtain the desired number.

See more: How to add a unit, How to remove a unit

Kubernetes. To control the number of an application’s units in a Kubernetes deployment, run the scale-application command followed by the number of desired units (which can be both higher and lower than the current number).

juju scale-application mediawiki 3

See more: juju scale-application

To control the number of units of an application, in its resource definition specify a units attribute. For example, below we set it to 3.

resource "juju_application" "this" {
  model = juju_model.development.name

  charm {
    name = "hello-kubecon"
  }

  units = 3    
}

See more: juju_application (resource)

To control the number of units of an application in python-libjuju client, you can use the Application.add_unit() and Application.destroy_units() methods, or the Application.scale() method, depending on whether you’re working on a CAAS system (e.g. Kubernetes), or an IAAS system (e.g. lxd).

If you’re on an IAAS system (machine applications):

u = my_app.add_unit()
my_app.destroy_units(u.name) # Note that the argument is the name of the unit

# You may give multiple unit names to destroy at once
my_app.destroy_units(u1.name, u2.name)

If you’re on a CAAS sytem (k8s applications):

my_app.scale(4)

See more: Application (module), Application.add_unit(), Application.scale(), Application.destroy_units()

Show details about a unit

To see more details about a unit, use the show-unit command followed by the unit name:

juju show-unit mysql/0

By using various options you can also choose to get just a subset of the output, a different output format, etc.

See more: juju show-unit

Too see details about a unit in python-libjuju client, you can use various fields and methods of a Unit object. For example, to get the public_address of a unit:

my_unit.get_public_address()

Or, to see if the unit is a leader:

my_unit.is_leader_from_status()

See more: Unit (module), Unit (methods), Unit.get_public_address(), Unit.is_leader_from_status()

List a unit’s resources

To see the resources for a unit, use the resources command followed by the unit name. For example:

juju resources mysql/0

See more: juju resources

The python-libjuju client does not support this. Please use the juju client.

Related: Application.get_resources()

Show the status of a unit

To see the status of a unit, use the status command:

juju status

This will show information about the model, along with its machines, applications and units. For example:

Model           Controller           Cloud/Region        Version  SLA          Timestamp
tutorial-model  tutorial-controller  microk8s/localhost  2.9.34   unsupported  12:10:16+02:00

App             Version                         Status  Scale  Charm           Channel  Rev  Address         Exposed  Message
mattermost-k8s  .../mattermost:v6.6.0-20.04...  active      1  mattermost-k8s  stable    21  10.152.183.185  no       
postgresql-k8s  .../postgresql@ed0e37f          active      1  postgresql-k8s  stable     4                  no       Pod configured

Unit               Workload  Agent  Address       Ports     Message
mattermost-k8s/0*  active    idle   10.1.179.151  8065/TCP  
postgresql-k8s/0*  active    idle   10.1.179.149  5432/TCP  Pod configured

See more: juju status, Unit status

To get the status of a unit on pylibjuju-client, you can use various (dynamically updated) status fields defined on a Unit object, such as:

workload_st = my_unit.workload_status
agent_st = my_unit.agent_status

See more: Unit status, Unit (module), Unit (methods), Unit.workload_status (field), Unit.agent_status (field)

Set the meter status on a unit

To set the meter status on a unit, use the set-meter-status command followed by the unit name. For example:

juju set-meter-status myapp/0

See more: juju set-meter-status

The python-libjuju client does not support this. Please use the juju client.

Mark unit errors as resolved

To mark unit errors as resolved, use the resolved command followed by the unit name or a list of space-separated unit names. For example:

juju resolved myapp/0

See more: juju resolved

To mark unit errors as resolved in the python-libjuju client, you can call the resolved() method on a Unit object:

my_unit.resolved()

See more: Unit.resolved()

Remove a unit

To remove individual units instead of the entire application (i.e. all the units), use the remove-unit command followed by the unit name. For example, the code below removes unit 2 of the PostgreSQL charm. For example:

While this can be used for both machine and Kubernetes deployments, unless you care about which unit you’re removing specifically, in Kubernetes you may also just run juju scale-application <n>, where n is less than the current number of units. See How to control the number of units.

juju remove-unit postgresql/2

In the case that the removed unit is the only one running, the corresponding machine will also be removed, unless any of the following is true for that machine:

  • it was created with juju add-machine
  • it is not being used as the only controller
  • it is not hosting Juju-managed containers (KVM guests or LXD containers)

It is also possible to remove multiple units at a time by passing instead a space-separated list of unit names:

juju remove-unit mediawiki/1 mediawiki/3 mediawiki/5 mysql/2

To also destroy the storage attached to the units, add the --destroy-storage option.

As a last resort, use the --force option (in v.2.6.1).

See more: juju remove-unit, Removing things reference

To remove individual units on python-libjuju client, simply use the Application.destroy_units() method:

my_app.destroy_units(u.name) # Note that the argument is the name of the unit

# You may give multiple unit names to destroy at once
my_app.destroy_units(u1.name, u2.name)

See more: Application (module), Application.destroy_units()


Contributors: @hmlanigan, @tmihoc, @cderici

2
3