Removing things

doc
1

This document clarifies the various Juju commands that can be used to remove things, as well as a couple of options that can be used to force a removal.

Contents:

Removal terms

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

  • Unregister means to decouple a resource from a logical entity for the client. The effect 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.

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 an intentionally conservative approach to the deletion of things.

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.

Furthermore, 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.

2

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?

3

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

1 Like
4

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.)

5

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?

6

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
7

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).

8

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.

9

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

10
11