relation-get.md

relation-get

relation-get reads the settings of the local unit, or of any remote unit, in a given relation (set with -r, defaulting to the current relation identifier, as in relation-set). The first argument specifies the settings key, and the second the remote unit, which may be omitted if a default is available (that is, when running a relation hook other than -broken).

If the first argument is omitted, a dictionary of all current keys and values will be printed; all values are always plain strings without any interpretation. If you need to specify a remote unit but want to see all settings, use - for the first argument.

The environment variable JUJU_REMOTE_UNIT stores the default remote unit:

echo $JUJU_REMOTE_UNIT
 mongodb/2

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 you would instead use:

relation-get username
 jim

To get all settings from a particular remote unit in a particular relation you specify them together with the command:

relation-get -r database:7 - mongodb/5
 username: bob
 password: 2db673e81ffa264c

Note that relation-get produces results that are consistent but not necessarily accurate, in that you will always see settings that:

• were accurate at some point in the reasonably recent past
• are always the same within a single hook run, except when inspecting the unit's own relation settings, in which case local changes from relation-set will be seen correctly.

You should never depend upon the presence of any given key in relation-get output. Processing that depends on specific values (other than private-address) should be restricted to -changed hooks for the relevant unit, and the absence of a remote unit's value should never be treated as an error in the local unit.

In practice, it is common and encouraged for -relation-changed hooks to exit early, without error, after inspecting relation-get output and determining it to be inadequate; and for all other hooks to be resilient in the face of missing keys, such that -relation-changed hooks will be sufficient to complete all configuration that depends on remote unit settings.

Settings for remote units already known to have departed remain accessible for the lifetime of the relation.

!!! Note: relation-get currently has a bug LP #1223339 which allows units of the same service to see each other's settings outside of a peer relation. Depending on this behaviour is inadvisable: if you need to share settings between units of the same service, always use a peer relation to do so, or your charm may fail unexpectedly when the bug is fixed.