A service may provide an interface to multiple consuming services
with the same relation name; each of these is a different established
relation. For example, the mysql5 service might provide the
mysql interface to multiple consuming clients using the relation
name db. When interacting with a given consuming client, relation
hooks executing on mysql5 service units in turn would be named
db-relation-joined, db-relation-changed, and
db-relation-departed. In addition, the environment variable
$JUJU_RELATION would be set to db.
This scenario implies that there is potential ambiguity in using the
relation name to refer to the specific relation between a provider and
a consumer. However, this ambiguity is currently rarely seen. This is
because relation hooks are always executed in the context of a
specific relation, as well as any settings on this relation. This
locality avoids most ambiguity in actual usage.
But ambiguity can arise in the following scenarios:
- Relation hooks are used to change local state, so it is currently
possible for the ambiguity in referring to a relation to become
visible over cumulative hook executions. Using appropriate
relation settings can be used to distinguish the consumer, so
there is a workaround.
- To enable the new feature of using relation hook commands to
work with other relations, or for these hook commands to be used
in nonrelation hooks, it is essential to have a nonambiguous
Therefore, to completely specify a relation, it is necessary to use
its relation id, not the relation name. However, the use of relation
ids is restricted: relation ids are only visible inside relation hooks
and/or relation hook commands.
To ensure readibility of the relation id, its format is specified to
<relation name>:<normalized internal relation id>
Normalization removes any padding zeros from the internal id.
Lastly, a new environment variable, $JUJU_RELATION_ID, will always
be set to the relation id in the context of relation hooks.
For example, if the relation is associated with relation name db and
the specific interal relation id is relation-0000000042, then the
relation id is db:42. The relation hooks db-relation-joined,
etc., will have $JUJU_RELATION_ID set to db:42. In addition,
this format further implies that relation id is not globally
unique. If the provider uses the relation name db and a consumer
uses the relation name database, then for interal relation id
relation-0000000042, db:42 and database:42 could both be
in use. However, it is not intended that relation ids be shared, or
even publicly visible to an admin, so this should not pose an issue.
Motivation for relation ids is mentioned in bug #767195:: Hooks must be able to
enumerate and query relations. In addition, possible formats are