Relation (integration)

See also: How to manage relations

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) that allows them to notify each other of changes and to reconfigure their workloads to operate together, without manual intervention.

relations
Example: The WordPress application with actual relations to MySQL and Apache and a potential relation to HAProxy, by virtue of the wordpress charm having a requires endpoint that supports the mysql interface, compatible with mysqls provides endpoint supporting the same interface, and a provides endpoint that supports the http interface, compatible with apache2’s or haproxy’s requires endpoint supporting the same interface, among others.

The connection happens through the Juju controller (which acts as a message broker between the unit agents of the units of the integrated applications, within a virtual star topology.

Contents:

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 relation scenarios, depending on whether the models are on the same controller or different controllers, and in the latter case whether the controllers are on the same cloud or on different clouds. Note: As all communication between integrated applications happens through the Juju controller, the red relation lines above merely represent the fact that, post integration, the applications work together.

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

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

  • each unit gets a unit databag
  • leaders unit also get an application databag

While the relation is maintained,

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

Relation lifecycle

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.


Contributors: @ppasotti, @serdarvural80, @tmihoc

Last updated a month ago. Help improve this document in the forum.