Hook tool

Without arguments, it just prints the status code e.g. ‘maintenance’. With --include-data specified, it prints YAML which contains the status value plus any data associated with the status.

Include the --application option to get the overall status for the application, rather than an individual unit.

status-get

status-get --include-data

status-get --application

status-set allows charms to describe their current status. This places the responsibility on the charm to know its status, and set it accordingly using the status-set hook tool. Changes made via status-set are applied without waiting for a hook execution to end and are not rolled back if a hook execution fails.

The leader unit is responsible for setting the overall status of the application by using the --application option.

This hook tool takes 2 arguments. The first is the status code and the second is a message to report to the user.

Valid status codes are:

• maintenance (the unit is not currently providing a service, but expects to be soon, e.g. when first installing)
• blocked (the unit cannot continue without user input)
• waiting (the unit itself is not in error and requires no intervention, but it is not currently in service as it depends on some external factor, e.g. an application to which it is related is not running)
• active (This unit believes it is correctly offering all the services it is primarily installed to provide)

For more extensive explanations of these status codes, please see the status reference page.

The second argument is a user-facing message, which will be displayed to any users viewing the status, and will also be visible in the status history. This can contain any useful information.

In the case of a blocked status though the status message should tell the user explicitly how to unblock the unit insofar as possible, as this is primary way of indicating any action to be taken (and may be surfaced by other tools using Juju, e.g. the Juju GUI).

A unit in the active state with should not generally expect anyone to look at its status message, and often it is better not to set one at all. In the event of a degradation of service, this is a good place to surface an explanation for the degradation (load, hardware failure or other issue).

A unit in error state will have a message that is set by Juju and not the charm because the error state represents a crash in a charm hook - an unmanaged and uninterpretable situation. Juju will set the message to be a reflection of the hook which crashed. For example “Crashed installing the software” for an install hook crash, or “Crash establishing database link” for a crash in a relationship hook.

# Set the unit's workload status to "maintenance".
# This implies a short downtime that should self-resolve.
status-set maintenance "installing software"
status-set maintenance "formatting storage space, time left: 120s"

# Set the unit's workload status to "waiting"
# The workload is awaiting something else in the model to become active 
status-set waiting "waiting for database"

# Set the unit workload's status to "active"
# The workload is installed and running. Any messages should be informational. 
status-set active
status-set active "Storage 95% full"

# Set the unit's workload status to "blocked"
# This implies human intervention is required to unblock the unit.
# Messages should describe what is needed to resolve the problem.
status-set blocked "Add a database relation"
status-set blocked "Storage full"

# From a unit, update its status
status-set maintenance "Upgrading to 4.1.1"

# From the leader, update the application's status line 
status-set --application maintenance "Application upgrade underway"

Non-leader units which attempt to use --application will receive an error

status-set --application maintenance "I'm not the leader."
error: this unit is not the leader

application-version-set 1.1.10

juju-log -l 'WARN' Something has transpired

Import-Module CharmHelpers

# Basic logging
Write-JujuLog "Something has transpired"

# Logs the message and throws an error, stopping the script
Write-JujuError "Something has transpired. Throwing an error..."

action-fail 'unable to contact remote service'

TIMEOUT=$(action-get timeout)

action-set answer 42

add-metric metric1=value1 [metric2=value2 …]

By default it lists three pieces of address information:

• binding address(es)
• ingress address(es)
• egress subnets

See Network primitives for in-depth coverage.

The behavior differs a little bit between machine charms and Kubernetes charms.

Machine charms. On public clouds the port will only be open while the application is exposed. It accepts a single port or range of ports with an optional protocol, which may be icmp, udp, or tcp. tcp is the default.

open-port will not have any effect if the application is not exposed, and may have a somewhat delayed effect even if it is. This operation is transactional, so changes will not be made unless the hook exits successfully.

Prior to Juju 2.9, when charms requested a particular port range to be opened, Juju would automatically mark that port range as opened for all defined application endpoints. As of Juju 2.9, charms can constrain opened port ranges to a set of application endpoints by providing the --endpoints flag followed by a comma-delimited list of application endpoints.

Kubernetes charms. The port will open directly regardless of whether the application is exposed or not. This connects to the fact that juju expose currently has no effect on sidecar charms. Additionally, it is currently not possible to designate a range of ports to open for Kubernetes charms; to open a range, you will have to run open-port multiple times.

Open port 80 to TCP traffic:

open-port 80/tcp

Open port 1234 to UDP traffic:

open-port 1234/udp

Open a range of ports to UDP traffic:
```bash
open-port 1000-2000/udp

Open a range of ports to TCP traffic for specific application endpoints (since Juju 2.9):

open-port 1000-2000/tcp --endpoints dmz,monitoring

# Close single port
close-port 80

# Close a range of ports
close-port 9000-9999/udp

# Disable ICMP
close-port icmp

# Close a range of ports for a set of endpoints (since Juju 2.9)
close-port 80-90 --endpoints dmz,public

It accepts a single argument, which must be private-address or public-address. It is not affected by context.

Note that if a unit has been deployed with --bind space then the address returned from unit-get private-address will get the address from this space, not the ‘default’ space.

unit-get public-address

opened-ports

INTERVAL=$(config-get interval)

config-get --all

goal-state provides:

• the details of other peer units have been deployed and their status
• the details of remote units on the other end of each endpoint and their status

The output will be a subset of that produced by the juju status. There will be output for sibling (peer) units and relation state per unit.

The unit status values are the workload status of the (sibling) peer units. We also use a unit status value of dying when the unit’s life becomes dying. Thus unit status is one of:

allocating active waiting blocked error dying

The relation status values are determined per unit and depend on whether the unit has entered or left scope. The possible values are:

• joining : a relation has been created, but no units are available. This occurs when the application on the other side of the relation is added to a model, but the machine hosting the first unit has not yet been provisioned. Calling relation-set will work correctly as that data will be passed through to the unit when it comes online, but relation-get will not provide any data.
• joined : the relation is active. A unit has entered scope and is accessible to this one.
• broken : unit has left, or is preparing to leave scope. Calling relation-get is not advised as the data will quickly out of date when the unit leaves.
• suspended : parent cross model relation is suspended
• error: an external error has been detected

By reporting error state, the charm has a chance to determine that goal state may not be reached due to some external cause. As with status, we will report the time since the status changed to allow the charm to empirically guess that a peer may have become stuck if it has not yet reached active state.

goal-state

An invocation without arguments will allow the current hook to complete, and will only cause a reboot if the hook completes successfully.

If the --now flag is passed, the current hook will terminate immediately, and be restarted from scratch after reboot. This allows charm authors to write hooks that need to reboot more than once in the course of installing software.

The --now flag cannot terminate a debug-hooks session; hooks using --now should be sure to terminate on unexpected errors, so as to guarantee expected behavior in all situations.

# immediately reboot
juju-reboot --now

# Reboot after current hook exits
juju-reboot

is-leaderwill write "True" to STDOUT and return 0 if the unit is currently leader and can be guaranteed to remain so for 30 seconds.

Output can be expressed as --format json or --format yaml if desired.

LEADER=$(is-leader)
if [ "${LEADER}" == "True" ]; then
  # Do something a leader would do
fi

leader-get acts much like relation-get) but only reads from the leader settings. If no key is given, or if the key is “-”, all keys and values will be printed.

ADDRESSS=$(leader-get cluster-leader-address)

The hook tool will fail if called without arguments, or if called by a unit that is not currently application leader.

leader-set lets you distribute string key=value pairs to other units, but with the following differences:

• there’s only one leader-settings bucket per application (not one per unit)
• only the leader can write to the bucket
• only minions are informed of changes to the bucket
• changes are propagated instantly

The instant propagation may be surprising, but it exists to satisfy the use case where shared data can be chosen by the leader at the very beginning of the install hook.

It is strongly recommended that leader settings are always written as a self-consistent group leader-set one=one two=two three=three.

leader-set cluster-leader-address=10.0.0.123

# Getting the settings of the default unit in the default relation is done with:
 relation-get
  username: jim
  password: "12345"

# To get a specific setting from the default remote unit in the default relation
  relation-get username
   jim

# To get all settings from a particular remote unit in a particular relation you
   relation-get -r database:7 - mongodb/5
    username: bob
    password: 2db673e81ffa264c

relation-ids database

relation-list 9

relation-set port=80 tuning=default

relation-set -r server:3 username=jim password=12345

storage-add takes the name of the storage volume (as defined in the charm metadata), and optionally the number of storage instances to add. By default, it will add a single storage instance of the name.

storage-add database-storage=1

If the executing hook is a storage hook, information about the storage related to the hook will be reported; this may be overridden by specifying the name of the storage as reported by storage-list, and must be specified for non-storage hooks.

storage-get can be used to identify the storage location during storage-attached and storage-detaching hooks. The exception to this is when the charm specifies a static location for singleton stores.

# retrieve information by UUID
storage-get 21127934-8986-11e5-af63-feff819cdc9f

# retrieve information by name
storage-get -s data/0

The storage instance identifiers returned from storage-list may be passed through to the storage-get command using the -s option.

payload-status-set monitor abcd13asa32c starting

Used while a hook is running to let Juju know that a payload has been started. The information used to start the payload must be provided when “register” is run.

The payload class must correspond to one of the payloads defined in the charm’s metadata.yaml.

An example fragment from metadata.yaml:

payloads:
    monitoring:
        type: docker
    kvm-guest:
        type: kvm

payload-register monitoring docker 0fcgaba

It used while a hook is running to let Juju know that a payload has been manually stopped. The class and id provided must match a payload that has been previously registered with Juju using payload-register.

payload-unregister monitoring 0fcgaba