Relation (integration)

In Juju, a relation (integration) is a connection between two applications with compatible endpoints (i.e., the same endpoint interface and compatible endpoint roles –requires to provides, provides to requires, or peers to peers).

Same-model vs. cross-model relations

Same-model relation

A same-model relation is a relation between applications on the same model.

Cross-model relation

A cross-model relation (CMR) is a relation between applications on different models (possibly also different controllers and different clouds).

Cross-model relations enable, for example, scenarios where your databases are hosted on bare metal, to take advantage of I/O performance, and your applications live within Kubernetes, to take advantage of scalability and application density.

Regular vs. subordinate vs. peer relations

Depending on your deployment, you should be able to see one or more of these relation types in your juju status --relations.

Regular relation

A regular relation is a relation between two applications having the same endpoint interface and opposite provides and requires endpoints, where both applications are principal.

This relation is formed through juju integrate and can be same-model or cross-model.

Subordinate relation

A subordinate relation is a relation between two applications having the same endpoint interface and opposite provides and requires endpoints, where one application is principal and the other is subordinate.

This relation is formed through juju integrate and can be same-model but not cross-model, because a subordinate application is by definition an application deployed on the same machine as its principal application.

The subordinate relation helps the subordinate application acquire a unit (when you deploy a subordinate charm, it appears in your Juju model with no unit). The subordinate application then scales automatically when the principal application does, by virtue of this relation.

Peer relation

A peer relation is a relation of an application to itself.

This relation is created automatically every time an application has a peers endpoint. It can only be same-model.

Because every relation results in the creation of unit and application databags in Juju’s database, peer relations are sometimes used by charm authors as a way to persist charm data. When the application has multiple units, peer relations are also the mechanism behind coordinated horizontal scaling.

Relation data and relation data bags

When an application becomes involved in a relation, each one of its units gets a data bag in the Juju database, as follows:

  • each unit gets a unit data bag
  • leaders unit also get an application data bag

While the relation is maintained,

  • in a regular or subordinate relation:
    • each unit can read and write to its own data bag(s)
    • leader units can also read all of their peers data bags
    • all units of an application can read all of data bags of the other application
  • in a peer relation:
    • each unit can read all of its peers’ data bags

Relations lifecycle and usage

When a relation is first created, the Juju unit agent executes the charm on the <endpoint name>-relation-created hook.

Each unit involved in the relation (from either application) then receives a <endpoint name>-relation-joined hook.

From the moment the relation is created, any unit involved in it can interact with it. In practice, that means using one of the following hook tools that the Juju unit agent exposes to the charm:

  • relation-ids
  • relation-list
  • relation-get
  • relation-set

When the charm uses relation-set to write something to a databag, all of the units that have read access to that same databag will be notified by means of a <endpoint name>-relation-changed hook.

For example, if the wordpress/0* leader uses relation-set to write to its local unit databag, its peers and the mysql/0* leader will receive http-relation-changed, because they can access that data (by calling relation-get), but the other mysql units will not be notified.

Any time one of the involved applications is scaled up, the existing units will receive <endpoint>-relation-joined, once for each unit being added. Any time one of the involved applications is scaled down, the existing units will receive <endpoint>-relation-departed, once for each unit being removed.

When the user destroys the relation by using juju remove-relation, all involved units will be notified with <endpoint>-relation-broken.

Last updated 20 seconds ago. Help improve this document in the forum.