Managing relations

Most applications rely on other applications to function correctly. For example, typically web apps require a database to connect to. Relations avoid the need for manual intervention when the charm’s environment changes. The charm will be notified of new changes, re-configure and restart the application automatically.

Relations are a Juju abstraction that enables applications to inter-operate. They are a communication channel between charms.

A certain charm 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 joining 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.

Creating 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 structures (e.g. tables) needed for WordPress to run properly.

Ambiguous relations

If the charms in question are versatile enough, 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

An application endpoint can be discovered by looking at the metadata of the corresponding charm. This can be done by examining the charm on the Charm Store or by querying the Store with the Charm Tools (using a command like charm show <application> charm-metadata).

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

Model    Controller  Cloud/Region         Version    SLA          Timestamp
default  lxd         localhost/localhost  2.4-beta4  unsupported  20:22:45Z

App        Version  Status  Scale  Charm      Store       Rev  OS      Notes
mediawiki  1.19.14  active      1  mediawiki  jujucharms   19  ubuntu  
mysql      5.7.22   active      1  mysql      jujucharms   58  ubuntu  

Unit          Workload  Agent  Machine  Public address  Ports     Message
mediawiki/0*  active    idle   2        10.115.37.227   80/tcp    Ready
mysql/0*      active    idle   1        10.115.37.45    3306/tcp  Ready

Machine  State    DNS            Inst id        Series  AZ  Message
1        started  10.115.37.45   juju-db874f-1  xenial      Running
2        started  10.115.37.227  juju-db874f-2  trusty      Running

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

The final section of the status output shows all current established relations.

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 apps to live within Kubernetes, where scalability and application density are more important.

See Cross model relations for more information.

Removing relations

There are times when a relation just isn’t working and it is time to move on. See the Removing things page for how to do this.

Implementation details

Relations are not network connections. 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 typology. This allows units to send data via relations that might not have connectivity with each other.

Last updated 2 months ago. Help improve this document in the forum.