How to manage relations

Juju facilitates interoperability between applications using an abstraction called Relations. Relations are a communication channel between charms that allow them to notify each other of changes and to reconfigure their workloads to operate together, without manual intervention.

One such relation could be the relation between, say, a CMS and its database.

A certain charmed operator knows that it requires, say, a database and, correspondingly, a database charm knows that is capable of satisfying another charm’s requirements. The act of relating such mutually-dependent charms causes code (hooks) to run in each charm in such a way that both charms can effectively talk to one another. When charms have joined logically in this manner they are said to have formed a relation.

A requirement for a relation is that both applications are currently deployed. See the deploying applications page for guidance.

Relations are not direct connections between charms. They’re implemented on top of the connections that the unit agents establish with the controller at startup. The Juju controller acts as a message broker within a virtual star topology. This allows units to send data via relations that might not have connectivity with each other.

How to manage relations

Common relation management tasks are summarised below. The most important one is creating a relation.

How to create relations

Creating a relation is straightforward enough. The add-relation command is used to set up a relation between two applications:

juju relate mysql wordpress

This will satisfy WordPress’s database requirement where MySQL provides the appropriate schema and access credentials required for WordPress to run properly.

How to create relations explicitly

Creating relations as in the example above will work if there is no ambiguity in what relation the charm requires and what the related charm provides.

If the charms in question are able to establish multiple relation types, Juju may need to be supplied with more information as to how the charms should be joined.

To demonstrate, if we try instead to relate the ‘mysql’ charm to the ‘mediawiki’ charm:

juju relate mysql mediawiki 

This is what will happen:

error: ambiguous relation: "mediawiki mysql" could refer to
  "mediawiki:db mysql:db"; "mediawiki:slave mysql:db"

The solution is to be explicit when referring to an endpoint, where the latter has a format of <application>:<application endpoint>. In this case, it is ‘db’ for both applications. However, it is not necessary to specify the MySQL endpoint because only the MediaWiki endpoint is ambiguous (according to the error message). Therefore, the command becomes:

juju add-relation mysql mediawiki:db

The relation endpoints provided or required by a charm are listed in the result of the juju info command. They are also listed on the page for the charmed operator at CharmHub.

The output of juju status --relations will display the relations:

Relation provider  Requirer       Interface  Type     Message
mysql:cluster      mysql:cluster  mysql-ha   peer     
mysql:db           mediawiki:db   mysql      regular

Cross model relations

Relations can also work across models, even across multiple controllers and clouds.

This functionality can enable your databases to be hosted on bare metal, where I/O performance is paramount, and your applications to live within Kubernetes, where scalability and application density are more important.

See Cross model relations for more information.

Removing relations

See the Removing things page for how to remove established relations.

Last updated a month ago.