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.
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 mysql
s 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
- Regular vs. subordinate vs. peer relations
- Relation data
- Relation lifecycle
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