Relation references¶

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

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 be:

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