Document new extra bindings support for charms metadata

[matthewhelmke]

Need to determine where this belongs.

Many charms use a simple model where a relationship with another charm
also indicates there is a network connection between units of those
services. We have utilized this fact to add a network model that allows
system operators to control where those TCP connections are made by
binding the service relation endpoints onto a network space.

However, some charms specifically use relation endpoints only as a way
to pass configuration around, and the relations don't map directly to
services that are running in that charm and/or networking configuration.
These charms want to be able to express that they have more networking
configuration that an operator wants to control without having yet-
another interface that will never be related to another service.

Juju solves the aforementioned issues by introducing an optional new
section in the charm metadata,yaml. The new section is called "extra-
bindings". Similarly to the peers/provides/requires sections, extra-
bindings contains a list of names, which can be used with 'juju deploy
--bind' like relation names. Unlike relations, you don't have to define
hooks or anything more complex to allow the users of the charm to bind
those names to Juju spaces.

Example: ceph charm's metadata.yaml would look like:

name: ceph
summary: Highly scalable distributed storage
maintainer: OpenStack Charmers <openstack-charmers@lists.ubuntu.com>
description: |
 Ceph is a distributed storage and network file system designed to provide
 excellent performance, reliability, and scalability.
tags:
  - openstack
  - storage
  - file-servers
  - misc
peers:
  mon:
    interface: ceph
extra-bindings:
  cluster:
  public:
provides:
  nrpe-external-master:
    interface: nrpe-external-master
    scope: container
…
storage:
  osd-devices:
    type: block
    multiple:
      range: 0-
  osd-journal:
    type: block
    multiple:
      range: 0-1

As a user then you can deploy this charm and tell Juju to provide
distinct addresses for it on one or more spaces:

juju deploy ~/path/to/charm/ceph --bind 'cluster=admin-api public=public-api internal-api'

Units of the ceph service will be deployed on machines which have access
to the "admin-api", "public-api", and "internal-api" spaces in MAAS, a
different network interface and address for each binding.

Then, e.g. in a hook of the same charm, running 'network-get cluster
--primary-address' will only return the correct address - the one coming
from the "admin-api" space.

[chuckbutler]

@dimitern sorry to be a pest here, can you link me to the release notes where this surfaced? We had a user in #juju asking about the extra bindings today, and I had very little information to give them other than this bug as reference to track.

[chuckbutler]

@mbruzek @johnsca - Do we feel this should live in the metadata.yaml overview, or should this live somewhere more specific? such as network-spaces, or xref between the two pages?

Spaces is still a very new feature, and has limited support per cloud. But to date, we have very little representation of this in the docs.

[chuckbutler]

xref with #1200

[mbruzek]

I found information about extra-bindings on the metadata page already.
https://jujucharms.com/docs/2.0/authors-charm-metadata
It is concerning that the navigation does not give the user an idea of "where they are" for this page.

There should be a whole page devoted to network-spaces and how to use that with maas and if possible other providers. A cross reference to the metadata page is appropriate as well. The user may find this "extra-bindings" from metadata page, or the networking page.

The key "extra-bindings" seems pretty generic, and does not appear to be network related at all. This may be on purpose. What other values could be "bound" here?

[mbruzek]

I added "extra-bindings" in the metadata for a charm, the charm still passes proof, so thankfully we do not have to update the charm tools proof method.