Cross model relations

Cross-model Relations (CMR) allow applications in different models to be related. Models may be hosted on the same controller, different controllers, and different clouds.

What is a relation?: If you are unsure what the terms model and relation mean in the context of Juju, then you should read the Models and Managing relations pages for introductions.


In this section command syntax may be simplified to keep complexity to a minimum. See the above CLI help text for full syntax and more examples.

Intended use cases

CMR addresses the case where one may wish to centralise a service. This can allows your models to become more targeted and can reduce their needs.

Some services that can benefit from central administration:

  • Certificate Authorities, such as the easyrsa charm
  • secret management, such as Vault
  • logging and monitoring
  • block storage management
  • databases

Another use case would be when you are simply using different cloud types.


An offer is an application that an administrator makes available to applications residing in remote models. The model in which the offer resides is known as the offering model.

The application (and model) that utilizes the offer is called the consuming application (and consuming model).

Like traditional Juju applications,

  • an offer has one or more endpoints that denote the features available for that offer.

  • a fully-qualified offer endpoint includes the associated offer name:

    <offer name>:<offer endpoint>

  • a reference to an offer endpoint will often omit the ‘offer name’ if the context presupposes it.

  • an endpoint has an interface that satisfies a particular protocol.

Illustrative Examples

Shared storage

Assume that operational requirements dictate that management for full text search is managed by central team. Cross-model relations enable multiple web applications to make use of this service.

At a high level, we can model full text search and each web application as independent entities:

juju add-model search
juju add-model webapp-1
juju add-model webapp-2
juju switch search
juju deploy -n 3 elasticsearch
juju offer elasticsearch:client



How to create an offer

An offer stems from an application endpoint. This is how an offer is created:

juju offer <application>:<application endpoint>

Although an offer may have multiple (offer) endpoints it is always expressed as a single URL:


If the ‘controller’ portion is omitted the current controller is assumed.

How to remove an offer

An offer can be removed providing a relation has not been made to it. To override this behaviour the --force option is required, in which case the relation is also removed. This is how an offer is removed:

juju remove-offer [--force] <offer-url>

Note that if the offer resides in the current model then the shorter offer name can be used instead of the longer URL.

Similarly, if an application is being offered it cannot be deleted until all its offers are removed.

How do I control access to an offer?

Offers can have one of three access levels:

  • read (a user can see the offer when searching)
  • consume (a user can relate an application to the offer)
  • admin (a user can manage the offer)

These are applied similarly to how standard model access is applied, via the juju grant and juju revoke commands:

juju grant <user> <access-level> <offer-url>
juju revoke <user> <access level> <offer-url>

Revoking a user’s consume access will result in all relations for that user to that offer to be suspended. If the consume access is granted anew, each relation will need to be individually resumed. Suspending and resuming relations are explained in more detail later.

Relating to offers

If a user has consume access to an offer, they can deploy an application in their model and establish a relation to the offer by way of its URL. The controller part of the URL is optional if the other model resides in the same controller.

juju add-relation <application>[:<application endpoint>] <offer-url>[:<offer endpoint>]

Specifying the endpoint for the application and the offer is analogous to normal relations. They can be added but are often unnecessary:

juju add-relation <application> <offer-url>

When an offer is related to, a proxy application is made in the consuming model, named after the offer.

Note that the relations block in status shows any relevant status information about the relation to the offer in the Message field. This includes any error information due to rejected ingress, or if the relation is suspended etc.

An offer can be consumed without relating to it. This workflow sets up the proxy application in the consuming model and creates a user-defined alias for the offer. This latter is what’s used to subsequently relate to. Having an offer alias can avoid a namespace conflict with a pre-existing application.

juju consume <offer-url> <offer-alias>
juju add-relation <application> <offer alias>

Offers which have been consumed show up in juju status in the SAAS section. Such an object can be removed in the consuming model with:

juju remove-saas <offer alias>

Relations and firewalls

When the consuming model is behind a NAT firewall its traffic will typically exit (egress) that firewall with a modified address/network. In this case, the --via option can be used with the juju relate command to request the firewall on the offering side to allow this traffic. This option specifies the NATed address (or network) in CIDR notation:

juju add-relation <application> <offer url> --via <cidr subnet>

It’s possible to set this up in advance at the model level in this way:

juju model-config egress-subnets=<cidr subnet>

To be clear, the above command is applied to the consuming model.

However, an administrator can control what incoming traffic is allowed to contact the offering model by whitelisting subnets:

juju set-firewall-rule juju-application-offer --whitelist <cidr subnet>

Where ‘juju-application-offer’ is a well-known string that denotes the firewall rule to apply to any offer in the current model.

The above command is applied to the offering model.

The juju set-firewall-rule command only affects subsequently created relations, not existing ones.

Suspending and resuming relations

A relation to an offer may be temporarily suspended, causing the consuming application to no longer have access to the offer:

juju suspend-relation <id1>

A suspended relation is resumed by an admin on the offering side:

juju resume-relation <id1>

Command juju offers provides the relation ids.

Removing relations

To remove a relation entirely:

juju remove-relation <id1>

Removing a relation on the offering side will trigger a removal on the consuming side. A relation can also be removed from the consuming side, as well as the application proxy, resulting in all relations being removed.

Example scenarios

The following CMR scenarios will be examined:

  • Scenario #1
    A MediaWiki deployment, based within the same controller, used by the admin user, but consumed by multiple models.
  • Scenario #2
    A MediaWiki deployment, based within multiple controllers, used by a non-admin user, and consumed by a single model.

Commands used with Cross-model Relations

The commands related specifically to this subject are:

: Accepts an offer to a model but does not relate to it.

: Finds URLs and endpoints of available offers.

: Lists the firewall rules.

: Creates an offer.

: Lists connected (related to) offers.

: Removes an offer.

: Removes a SAAS object created with the juju consume command.

: Resumes a suspended relation to an offer.

: Sets a firewall rule.

: Shows details for a connected (related to) offer.

: Suspends a relation to an offer.

Why is this documentation page not listed on the left column on ? @timClicks

Good question, but I don’t have a good answer. I’ve added it now in the Deployment section.

seems the content of the page refers to Advanced application deployment and no longer contains documentation about cross model relations.

1 Like

Fixed now. Thanks for flagging this.