How to remove things

This page is dedicated to the topic of removing objects in Juju. We first cover the meanings of certain removal terms and then provide information and steps for how different kinds of objects are removed.

For guidance on what to do when a removal does not apply cleanly consult the Troubleshooting removals page.


Removal terms

There is a distinction between the similar sounding terms “unregister”, “detach”, “remove”, “destroy”, and “kill”. These terms are ordered such that their effect increases in severity:

  • Unregister means to decouple a resource from a logical entity for the client. The affect is local to the client only and does not affect the logical entity in any way.

  • Detach means to decouple a resource from a logical entity (such as an application). The resource will remain available and the underlying cloud resources used by it also remain in place.

  • Remove means to cleanly remove a single logical entity. This is a destructive process, meaning the entity will no longer be available via Juju, and any underlying cloud resources used by it will be freed (however, this can often be overridden on a case-by-case basis to leave the underlying cloud resources in place).

  • Destroy means to cleanly tear down a logical entity, along with everything within these entities. This is a very destructive process.

  • Kill means to forcibly tear down an unresponsive logical entity, along with everything within it. This is a very destructive process that does not guarantee associated resources are cleaned up.

These command terms/prefixes do not apply to all commands in a generic way. The explanations above are merely intended to convey how a command generally operates and what its severity level is.

Command kill-controller

The kill-controller command deserves some attention as it is very destructive and also has exceptional behaviour modes. This command will first attempt to remove a controller and its models in an orderly fashion. That is, it will behave like destroy-controller. If this fails, usually due the controller itself being unreachable, then the controller machine and the workload machines will be destroyed by having the client contact the backing cloud’s API directly.

Forcing removals

Juju object removal commands do not succeed when there are errors in the multiple steps that are required to remove the underlying object. For instance, a unit will not remove properly if it has a hook error, or a model cannot be removed if application units are in an error state. This is a conservative approach to the deletion of things, which is good.

However, this policy can also be a source of frustration for users in certain situations (i.e. “I don’t care, I just want my model gone!”). Because of this, several commands have a --force option.

Secondly, even when utilising the --force option, the process may take more time than an administrator is willing to accept (i.e. “Just go away as quickly as possible!”). Because of this, several commands that support the --force option have, in addition, support for a --no-wait option.

Caution: The --force and --no-wait options should be regarded as tools to wield as a last resort. Using them introduces a chance of associated parts (e.g. relations) not being cleaned up, which can lead to future problems.

As of v.2.6.1, this is the state of affairs for those commands that support at least the --force option:

command --force --no-wait
destroy-model yes yes
detach-storage yes no
remove-application yes yes
remove-machine yes yes
remove-offer yes no
remove-relation yes no
remove-storage yes no
remove-unit yes yes

When a command has --force but not --no-wait, this means that the combination of those options simply does not apply.

Object removal list

Destroying controllers

A controller is removed with:

juju destroy-controller <controller-name>

You will always be prompted to confirm this action. Use the -y option to override this.

As a safety measure, if there are any models (besides the ‘controller’ model) associated with the controller you will need to pass the --destroy-all-models option.

Additionally, if there is persistent storage in any of the controller’s models you will be prompted to either destroy or release the storage, using the --destroy-storage or --release-storage options respectively.

For example:

juju destroy-controller -y --destroy-all-models --destroy-storage aws

Use the kill-controller command as a last resort if the controller is not accessible for some reason.

Destroying models

To destroy a model, along with any associated machines and applications:

juju destroy-model <model-name>

You will always be prompted to confirm this action. Use the -y option to override this.

Additionally, if there is persistent storage in the model you will be prompted to either destroy or release the storage, using the --destroy-storage or --release-storage options respectively.

For example:

juju destroy-model -y --destroy-storage beta

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

Detaching storage

To detach a storage instance:

juju detach-storage <storage-instance>

For example:

juju detach-storage osd-devices/2

Detaching storage does not destroy the storage.

Removing applications

An application can be removed with:

juju remove-application <application-name>

For example:

juju remove-application apache2

This will remove all of the application’s units. All associated machines will also be removed providing they are not hosting containers or another application’s units.

If persistent storage is in use by the application it will be detached and left in the model. However, the --destroy-storage option can be used to instruct Juju to destroy the storage once detached.

Removing an application which has relations with another application will terminate that relation. This may adversely affect the other application. See section Removing relations below for how to selectively remove relations.

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

Removing charmed operators or bundles

A charmed operator is the means by which an application is installed. There is therefore no method to remove a charm. Removal should be done at either the unit or application level.

A bundle is not a logical entity that can be removed. Once a bundle is deployed, applications can evolve in numerous ways that are not tracked and associated with the original bundle. For complex deployments, the recommendation is to deploy on a per-model basis so the removal of a complex deployment becomes equivalent to the removal of a model.

Removing clouds

Removing a cloud definition can be done locally or, since v.2.6.1, remotely (on a controller). Here, we’ll show how to do it locally (client cache).

A cloud definition can be removed with:

juju remove-cloud [options] <cloud-name>

For example:

juju remove-cloud --local lxd-remote

The following attempted removals will cause the command to error out, accompanied by appropriate messaging:

  1. a remote private cloud currently in use
  2. a local or remote built-in cloud

In versions prior to v.2.6.1 the remove-cloud command only operates locally (there is no --local option).

Removing machines

A machine can be removed with:

juju remove-machine <machine ID>

For example:

juju remove-machine 3

However, it is not possible to remove a machine that is currently hosting either a unit or a container. Either remove all of its units (or containers) first or, as a last resort, use the --force option.

In some situations, even with the --force option, the machine on the backing cloud may be left alive. Examples of this include the Manual cloud or if harvest provisioning mode is not set. In addition to those situations, if the client has lost connectivity with the backing cloud, any backing cloud, then the machine may not be destroyed, even if the machine’s record has been removed from the Juju database and the client is no longer aware of it.

By default, when a machine is removed, the backing system, typically a cloud instance, is also destroyed. The --keep-instance option overrides this; it allows the instance to be left running.

Removing offers

An application offer (for a cross model relation) is removed with:

juju remove-offer <offer url>

For example:

juju remove-offer hosted-mysql

The attempt will fail if a relation has already been made to the offer. To override this behaviour the --force option is required, in which case the relation is also removed.

Note that if the offer does not reside in the current model then the full URL must be used:

juju remove-offer prod.model/hosted-mysql

Removing relations

A relation is removed by calling out both (application) sides of the relation:

juju remove-relation <application-name> <application-name>

For example:

juju remove-relation mediawiki mysql

In cases where there is more than one relation between the two applications, it is necessary to specify the interface at least once:

juju remove-relation mediawiki mysql:db

Removing storage

To remove a storage instance from a model first detach it and then:

juju remove-storage <storage-instance>

For example:

juju detach-storage osd-devices/3
juju remove-storage osd-devices/3

The --force option can be used to avoid having to first detach the storage.

The removal of storage is, by default, a destructive process (destroyed on the cloud provider). To prevent this, the --no-destroy option is available. Note that, by using this option, the storage will no longer be visible to Juju.

Removing units

To remove individual units instead of the entire application (i.e. all the units):

juju remove-unit <unit>

For example:

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)

To remove multiple units:

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

The --destroy-storage option is available for this command as it is for the remove-application command above.

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

Removing users

A user can be removed from a controller with:

juju remove-user <user-name>

For example:

juju remove-user teo

Unregistering controllers

A controller can be removed from a client with:

juju unregister <controller-name>

For example:

juju unregister aws-controller

This removes local connection information from the local client. This command does not affect the controller itself in any way.

Are all these commands non-blocking? How do I find out whether the removal has finished?

I want to destroy a charm. Charms are not in the list of objects which can be removed.
I am assuming that removing the application will suffice.

I ran juju remove-application haproxy then waited a few minutes. I still see haproxy in the GUI and with juju status.

When I run juju remove-application haproxy --debug I see some colorful output finishing with “command finished”.

What am I doing wrong? How do I view the status of a removal to ensure that it actually finished successfully?

I’ve edited this doc page to make things clearer. Thanks for that feedback.

1 Like

When i try that, it says:

$ juju remove-unit ntp/3
removing unit ntp/3 failed: unit "ntp/3" is a subordinate

How do I remove a subordinate? (I have already removed the relationship.)

The commands on this page do not work if the unit or application is in an error state.

When a unit has state error: hook failed: "install", the juju remove-unit command does not work. (It doesn’t print an error message or return an error code, but it doesn’t remove the unit either.)

So how can I remove a unit which is in an error state?

The list up the top mentioned “remove”, “destroy” and “kill”, yet juju destroy-unit and juju kill-unit are not valid commands. How do I remove or kill a unit?

The commands are indeed non-blocking, and are asynchronous. Generally speaking, confirmation of actions taken are confirmed by the output to juju status. There could be an issue with the backing cloud. It’s hard to say at this point. If the application does not get removed you may look into the logs and Troubleshooting removals. You can file a software issue here if you feel the need to.

1 Like

You would remove its application:

juju remove-application ntp

Subordinate applications don’t operate like regular applications in the sense that their units are not independent. They depend on the charm they’re associated with (the principal charm).

You can use the Troubleshooting removals page I linked to previously.

Re the removal prefixes, correct they do not apply to all commands. I will update the doc page to clarify.

The first condition is not true. We should remove that from the doc.