Managing relations

Juju is an Open Source Charmed Operator Framework. It helps you move from configuration management to application management and has two main components:

  • Charmed Operator Lifecycle Manager (OLM) - a hybrid-cloud application management and orchestration system that helps you from Day 0 to Day 2. Deploy, configure, scale, integrate, maintain and manage Kubernetes native, container-native and VM-native applications – and the relations between them.

    • Charmed Operators, packaged as “Charms”, are software that encapsulate a single application and all the code and know-how it takes to operate it on Kubernetes or machines.
  • Charmed Operator SDK - a guide to help you build Charmed Operators for use with the Charmed OLM.

Applications often rely on other applications to deliver meaningful value. For example, a typical web application requires a database.

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.

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

Relations management tasks

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

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 schema and access credentials required for WordPress to run properly.

Creating 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.

Is there another page with more information about relations? specifically, around gathering relation data from the cli (relation-get, relation-list, relation-ids)?