juju add-relation

Usage: juju add-relation [options] <application>[:<relation>] <application>[:<relation>]

Summary:
Relate two applications.

Global Options:
--debug  (= false)
    equivalent to --show-log --logging-config=<root>=DEBUG
-h, --help  (= false)
    Show help on a command or other topic.
--logging-config (= "")
    specify log levels for modules
--quiet  (= false)
    show no informational output
--show-log  (= false)
    if set, write the log file to stderr
--verbose  (= false)
    show more verbose output

Command Options:
-m, --model (= "")
    Model to operate in. Accepts [<controller name>:]<model name>|<model UUID>
--via (= "")
    for cross model relations, specify the egress subnets for outbound traffic

Details:
Relate two applications. Relations are a communication interface provided by
the Juju controller that enable units to transfer data. This star messaging
topology allows units to send and receive data, even if direct connectivity
between units is restricted by firewall rules. Charms define the logic for
transferring and interpreting relation data.

The most common use of 'juju relate' specifies two applications that co-exist
within the same model:

    juju relate <application> <application>

Occasionally, more explicit syntax is required. Juju is able to relate
units that span models, controllers and clouds, as described below.


Relating applications in the same model

The most common case specifying two applications, and adding the specific
relation name when required.

    juju relate <application>[:<relation>] <application>[:<relation>]

Juju uses these arguments to create an "application endpoint". An application
endpoint is the combination of an "application name", a "relation name" and a
"role". The role and relation name are described by charms' metadata.yaml file.

The order does not matter, however each side must perform complementary roles.
One side performs the "provides" role and the other side performs the "requires"
role. Juju can always infer the role that each side is performing, so specifying
them is not necessary as command-line arguments.

<app-name> is the name of an application that has already been added to the
model. The Applications section of 'juju status' provides a list of current
applications.

<relation-name> is the name of a relation defined within the metadata.yaml
of the charm for <app-name>. Valid relation names are defined within the
"provides:" and "requires:" section of that file. Juju will request that you
specify the <relation-name> when it is unable to resolve the name itself.


Subordinate applications

Relating a principal application to a subordinate application has the effect of
deploying the subordinate alongside its principal. This functionality use the
same syntax as relating applications within the same model.


Peer relations

Relations within an application between units (known as "peer relations") do
not need to be added manually. They are created when the 'juju add-unit' and
'juju scale-application' commands are executed.


Cross-model relations

Applications can be related, even when they are deployed to different models.
Those models may be managed by different controllers and/or be hosted on
different clouds. This functionality is known as "cross-model relations" or CMR.


Cross-model relations: different model on the same controller

Adding a relation between applications in models managed by the same controller
is very similar to adding a relation between applications in the same model:

    juju relate <application>[:<relation>] <model>.<application>[:<relation>]

<model> is the name of the model outside of the current context. enables the
Juju controller to bridge two models. List the model currently available with
the 'juju models' command.

To relate models outside of the current context, add the '-m <model>' option:

    juju relate -m <model> <application>[:<relation>] \
                   <model>.<application>[:<relation>]


Cross-model relations: different controllers

Applications can relate to a remove application via an "offer URL" that has
been generated by the 'juju offer' command. The syntax for adding a cross-model
relation is similar to adding a local relation:

    juju relate <application>[:<relation>] <offer-endpoint>

<offer-endpoint> describes the remote application, from the point of view of the
local one. An <offer-endpoint> takes one of two forms:

    <offer-alias>
    <offer-url>[:<relation-name>]

<offer-alias> is an alias that has been defined by the 'juju consume' command.
Use the 'juju find-offers' command to list aliases.

<offer-url> is a path to enable Juju to resolve communication between
controllers and the models they control.

    [[<controller>:]<user>/]<model-name>.<application-name>

<controller> is the name of a controller. The 'juju controllers' command
provides a list of controllers.

<user> is the user account of the model's owner.


Cross-model relations: network management

When the consuming side (the local application) is behind a firewall and/or
NAT is used for outbound traffic, it is possible to use the '--via' option to
inform the offering side (the remote application) the source of traffic to
enable network ports to be opened.

    ... --via <cidr-subnet>[,<cidr-subnet>[, ...]]


Further reading:

    https://juju.is/docs/relations
    https://juju.is/docs/cross-model-relations


Examples:

    # Relate the wordpress and percona-cluster applications, asking Juju to resolve
    # the relation names. Expands to "wordpress:db" (with the requires role) and
    # "percona-cluster:server" (with the provides role).
    juju relate wordpress percona-cluster

    # Relate the wordpress and postgresql applications, using an explicit
    # relation name.
    juju relate wordpress postgresql:db

    # Relate an etcd instance within the current model to centrally managed
    # EasyRSA Certificate Authority hosted in the "secrets" model
    juju relate etcd secrets.easyrsa

    # Relate a wordpress application with a mysql application hosted within the
    # "prod" model, using the "automation" user. Facilitate firewall management
    # by specifying the routes used for relation data.
    juju add-relation wordpress automation/prod.mysql --via 192.168.0.0/16,10.0.0.0/8


See also:

    consume
    find-offers
    set-firewall-rule
    suspend-relation

Aliases: relate