Merge lp:~bcsaller/pyjuju/subordinate-charms into lp:pyjuju

[Benjamin Saller]

charm metadata support for subordinates

Charm directory, bundle and metadata support for subordinate charms and scoped relations

https://codereview.appspot.com/5532098/

[Gustavo Niemeyer (niemeyer)]

As agreed and discussed in advance, the changes to the APIs and ZooKeeper handling of data
must be debated in advance in the mailing list.

review: Needs Information

[Benjamin Saller (bcsaller)]

Reviewers: mp+84562_code.launchpad.net,

Message:
Please take a look.

Description:
Charm directory, bundle and metadata support for subordinate interfaces

Includes changes related to the first round of feedback

https://code.launchpad.net/~bcsaller/juju/subordinate-charms/+merge/84562

(do not edit description out of merge proposal)

Please review this at https://codereview.appspot.com/5532098/

Affected files:
   M .bzrignore
   M docs/source/charm-upgrades.rst
   A docs/source/drafts/implicit-interfaces.rst
   A docs/source/drafts/subordinate-internals.rst
   A docs/source/drafts/subordinate-services.rst
   M juju/charm/metadata.py
   A juju/charm/tests/repository/series/logging/.ignored
   A juju/charm/tests/repository/series/logging/hooks/install
   A juju/charm/tests/repository/series/logging/metadata.yaml
   A juju/charm/tests/repository/series/logging/revision
   M juju/charm/tests/test_metadata.py

[Benjamin Saller (bcsaller)]

This was pushed in error, still pending the spec review so I can get the naming to what we agree on.

[Gustavo Niemeyer (niemeyer)]

On 2012/01/19 08:59:45, bcsaller wrote:
> Please take a look.

Please hold off on merging this while we talk in the mailing list about
the specification.

https://codereview.appspot.com/5532098/

[Benjamin Saller (bcsaller)]

Please take a look.

https://codereview.appspot.com/5532098/

[lp:~bcsaller/pyjuju/subordinate-charms]

470. By Benjamin Saller on 2012-02-10

Merged subordinate-spec into subordinate-charms.

471. By Benjamin Saller on 2012-02-10

use defines throughout, is_subordinate only checks metadata flag

472. By Benjamin Saller on 2012-02-10

Merged subordinate-spec into subordinate-charms.

[Kapil Thangavelu (hazmat)]

lgtm +1, one minor. woot! first branch of subordinates.

https://codereview.appspot.com/5532098/diff/4001/juju/charm/metadata.py
File juju/charm/metadata.py (right):

https://codereview.appspot.com/5532098/diff/4001/juju/charm/metadata.py#newcode228
juju/charm/metadata.py:228: path)
Feels like this should be an error that's raised.

https://codereview.appspot.com/5532098/

[lp:~bcsaller/pyjuju/subordinate-charms]

473. By Benjamin Saller on 2012-02-16

Merged subordinate-spec into subordinate-charms.

474. By Benjamin Saller on 2012-02-24

Merged subordinate-spec into subordinate-charms.

475. By Benjamin Saller on 2012-02-27

Merged subordinate-spec into subordinate-charms.

476. By Benjamin Saller on 2012-02-28

raise error when subordinate is improperly used

[Benjamin Saller (bcsaller)]

https://codereview.appspot.com/5532098/diff/4001/juju/charm/metadata.py
File juju/charm/metadata.py (right):

https://codereview.appspot.com/5532098/diff/4001/juju/charm/metadata.py#newcode228
juju/charm/metadata.py:228: path)
On 2012/02/27 19:21:20, hazmat wrote:
> Feels like this should be an error that's raised.

It isn't currently because the other checks in the method only log.
However you're correct that this indicates a usage error and should be
corrected so I'm changing it to a MetadataError(...)

https://codereview.appspot.com/5532098/

Unmerged revisions

=== modified file '.bzrignore'
--- .bzrignore	2011-09-05 10:53:18 +0000
+++ .bzrignore	2012-02-09 03:51:19 +0000
@@ -1,6 +1,6 @@
-/debian/files
 /docs/build
 /docs/source/generated
 /_trial_temp
 /tags
-zookeeper.log
+/zookeeper.log
+/TAGS

=== modified file 'docs/source/charm-upgrades.rst'
--- docs/source/charm-upgrades.rst	2011-09-15 17:56:23 +0000
+++ docs/source/charm-upgrades.rst	2012-02-09 03:51:19 +0000
@@ -5,7 +5,7 @@
 Upgrading a charm
 -------------------
 
-A charm_ can be upgraded via the command line using the following
+:doc:`charm` can be upgraded via the command line using the following
 syntax::
 
   $ juju upgrade-charm <service-name>
@@ -21,7 +21,6 @@
 The unit agent will switch over to executing hooks from the new charm,
 after executing the `upgrade-charm` hook.
 
-.. _charm: ../charm.html
 
 
 Charm upgrade support

=== modified file 'docs/source/charm.rst'
--- docs/source/charm.rst	2011-10-06 21:04:13 +0000
+++ docs/source/charm.rst	2012-02-09 03:51:19 +0000
@@ -74,6 +74,20 @@
         means the relation is required. While you may define it, this
         field is not yet enforced by juju.
 
+      * **scope:** - Controls which units of related-to services can
+        be communicated with through this relationship. Juju supports
+        the following scopes:
+
+        * **global:** `default` When a traditional relation is added
+          between two services, all the service units for the first service will
+          receive relation events about all service units for the second
+          service.
+
+        * **container**: Communication is restricted to units deployed
+          in the same container. It is not possible to establish a
+          container scoped relation between principal services. See
+          :doc:`subordinate-services`.
+
       As a shortcut, if these properties are not defined, and instead
       a single string value is provided next to the relation name, the
       string is taken as the interface value, as seen in this

=== added file 'docs/source/drafts/implicit-relations.rst'
--- docs/source/drafts/implicit-relations.rst	1970-01-01 00:00:00 +0000
+++ docs/source/drafts/implicit-relations.rst	2012-02-09 03:51:19 +0000
@@ -0,0 +1,62 @@
+ Implicit relations
+===================
+
+Implicit relations allow for interested services to gather
+lifecycle-oriented events and data about other services without
+expecting or requiring any modifications on the part of the author of
+the other service's charm.
+
+Implicit relationships are named in the reserved the juju-*
+namespace. Both the relation name and interface names provided by juju
+are prefixed with `juju-`. Charms attempting to provide new
+relationships in this namespace will trigger an error.
+
+Juju currently provides one implicit relationship to all deployed
+services.
+
+`juju-info`, if specified would look like::
+
+   provides:
+       juju-info:
+           interface: juju-info
+
+The charm author should not declare the `juju-info` relation and is
+provided here only as an example. The `juju-info` relation is
+implicitly provided by all charms, and enables the requiring unit to
+obtain basic details about the related-to unit. The following settings
+will be implicitly provided by the remote unit in a relation through its
+`juju-info` relation ::
+
+     private-address
+     public-address
+
+
+Relationship resolution
+-----------------------
+
+If **rsyslog** is a :doc:`subordinate charm<subordinate-services>` and
+requires a valid `scope: container` relationship in order to
+deploy. It can take advantage of optional support from the principal
+charm but in the event that the principal charm doesn't provide this
+support it will still require a `scope: container` relationship. In
+this event the logging charm author can take advantage of the implicit
+relationship offered by all charms, `juju-info`. ::
+
+   requires:
+     logging:
+         interface: logging-directory
+         scope: container
+     juju-info:
+         interface: juju-info
+         scope: container
+
+The admin then issues the following  ::
+
+    juju add-relation wordpress rsyslog
+
+If the wordpress author doesn't provide the `logging-directory`
+interface juju will use the less-specific (in the sense that it likely
+provides less information) `juju-info` interface.
+
+juju always attempts to match user provided interfaces before looking
+for possible relationship matches in the `juju-*` namespace.

=== added file 'docs/source/drafts/subordinate-internals.rst'
--- docs/source/drafts/subordinate-internals.rst	1970-01-01 00:00:00 +0000
+++ docs/source/drafts/subordinate-internals.rst	2012-02-09 03:51:19 +0000
@@ -0,0 +1,168 @@
+ Subordinate service implementation details
+===========================================
+
+
+This document explains the implementation of subordinate services. For
+a higher level understanding please refer to the primary :doc:`subordinates
+document <subordinate-services>`.
+
+
+Overview
+-------
+
+Principal services can have relationships with subordinates. This is
+modeled using extensions to the `client-server` relationship
+type. This new relation type is used exclusively between subordinates
+and principals and is used to limit communication to only service
+units in the same container.
+
+
+ZooKeeper state
+---------------
+
+Subordinate relations use the normal `client-server` relationship type
+but store additional information in the relation nodes to maintain a
+1-1 mapping from the unit-id of the principal to the unit id of the
+subordinate. ::
+
+    relations/
+      relation-000000001/
+        container_relations/
+        |    subordinate_id-00000002: principal_id-00000001
+        |    subordinate_id-00000004: principal_id-00000003
+        ---------------------------------------------------
+        settings/
+          principal_id-00000001/
+          |    private-address: 10.2.2.2
+          -------------------------------
+          principal_id-00000003/
+          |    private-address: 10.2.2.3
+          ---------------------------------------------------
+
+Elements ending with **/** refer to ZK nodes with its children
+indented under it.. Elements preceded by **|** represent a YAML
+encoded structure under the preceding ZK node. `container_relations`
+is a new structure under the each relations ZK node. This contains a
+mapping from the subordinate unit's id to the id of its principal
+services' unit agent. This representation takes advantage of the fact
+that while a principal can have many subordinates a subordinate can
+only have one principal. In the context of a given relationship this
+mapping is unique.
+
+Additionally there are changes related to the storage of the relation
+in the topology. A `relation_scope` is added to the ordered list of
+properties such that ::
+
+    relations
+        relation-00000001:
+          - relation_type
+          - relation_scope
+          - service-00000001: {name: name, role: role}
+            service-00000002: {name: name, role: role}
+
+
+Watch related changes
+---------------------
+
+The unit agent will use watch_relation_states to see when new
+relations are added. When a subordinate relation is present deployment
+actions will be taken in the unit agents lifecycle.
+
+UnitRelationStates.watch_related_units will dispatch on the relation
+and only establish watches between the principal and subordinate units
+in the same container.
+
+Deployment
+----------
+
+`juju deploy` needs to enforce that services which require `scope:
+container` relations are not deployed until one of those relationships
+have been satisfied.
+
+The UnitMachineDeployment/UnitContainerDeployment in machine/unit will
+undergo minor refactoring to make it more easily useable by the
+UnitAgent to do its deployment of subordinate services. The Unit Agent
+is the only entity with direct a relationship to its subordinate unit
+and so the UnitAgent does the deployment of its subordinate units
+rather than the MachineAgent. This model will continue to work in
+the expected LXCEverywhere future.
+
+When a subordinate unit is deployed it is assigned the public and private
+addresses of its principal service (even though it may expose its own
+ports). This is because networking is dependent on the container its
+running it, i.e, that of the principal's service unit.
+
+One interesting caveat is that we don't assign the subordinate unit a
+machine id. `juju-status` exposes this information in a way that is
+clear and is outlined below. Machine assignment is currently used to
+trigger a class of deployment activities which subordinate services do
+not take advantage of. It is an error to assign a machine directly to
+a subordinate unit (as this indicates a usage error).
+
+`juju.unit.lifecycle._process_service_changes` is currently
+responsible for adding unit state to relations. This code will change
+so that when relationships are added or removed we have access to the
+unit_name of the subordinate. This information is used to annotate the
+UnitRelationState with the mapping from principal unit_name to
+subordinate unit name and is stored in ZooKeeper as outlined
+above. When a relationship is removed we detect this here as well and
+update the mapping using the unit_name of the principal.
+
+`juju.state.relation.ServiceRelationState.add_unit_state` will be
+augmented to support tracking of the 1-1 mapping between principal and
+subordinate unit names. It will take an optional `principal_unit`
+argument. This will take the `unit_name` the of principal unit the
+service is contained with. Error checking will validate that the
+service unit should be subordinate to the principal service in
+question.
+
+
+Unit management
+---------------
+
+`juju add-unit` must raise an error informing the admin they can not
+add units of a subordinate service. These scale automatically with the
+principal service.
+
+`juju remove-unit` produces an error on subordinate services for the
+same reason.
+
+
+Relation management
+-------------------
+
+`juju add-relation` and `juju remove-relation` must trigger the
+deployment and removal of subordinate units. This is done using the
+watch machinery outlined above. Each principal service unit will
+deploy a new unit agent for its subordinate when the appropriate new
+relationship is added and remove it when the relationship is departed.
+
+The subordinate service will maintain a watch of its relationship to
+the principal and should this relationship be removed the subordinate
+will transition its state to stopped and then remove its own state
+from the container and terminate. This will require follow up work to
+handle the proper triggering of stop hooks on the subordinate units
+which isn't handled
+
+Status
+------
+
+The changes to status are outlined in the user oriented documentation.
+
+
+Roadmap
+-------
+
+This serves as a guide to the planned merge tree. ::
+
+    subordinate-spec
+    subordinate-charms  # (charm metadata support)
+    subordinate-implicit-interfaces # (juju-info)
+    subordinate-relation-type
+
+    subordinate-control-deploy
+    subordinate-control-units # (add/remove)
+    subordinate-control-status
+
+    subordinate-control-relations # (add/remove)
+    subordinate-unit-agent-deploy

=== added file 'docs/source/drafts/subordinate-services.rst'
--- docs/source/drafts/subordinate-services.rst	1970-01-01 00:00:00 +0000
+++ docs/source/drafts/subordinate-services.rst	2012-02-09 03:51:19 +0000
@@ -0,0 +1,170 @@
+ Subordinate services
+=====================
+
+Services are composed of one or more service units. A service unit
+runs the service's software and is the smallest entity managed by
+juju. Service units are typically run in an isolated container on a
+machine with no knowledge or access to other services deployed onto
+the same machine. Subordinate services allows for units of different
+services to be deployed into the same container and to have knowledge
+of each other.
+
+
+Motivations
+-----------
+
+Services such as logging, monitoring, backups and some types of
+storage often require some access to the runtime of the service they
+wish to operate on. Under the current modeling of services it is only
+possible to relate services to other services with an explicit
+interface pairing.  Requiring a specified relation implies that every
+charm author need be aware of any and all services a deployment might
+wish to depend on, even if the other service can operate without any
+explicit cooperation.  For example a logging service may only require
+access to the container level logging directory to function.
+
+The following changes are designed to address these issues and allow a
+class of charm that can execute in the context of an existing
+container while still taking advantage of the existing relationship
+machinery.
+
+
+Terms
+-----
+
+Principal service
+    A traditional service or charm  in whose container subordinate
+    services will execute.
+
+Subordinate service/charm
+    A service designed for and deployed to the running container of
+    another service unit.
+
+Subordinate relation
+    A qualified relation type between principal services and their
+    subordinate service units. While modeled identically to
+    traditional relationships, juju only implements the relationship
+    between the unit of the principal and the subordinate service or
+    charm in the same container.
+
+
+Relations
+---------
+
+When a traditional relation is added between two services, all the
+service units for the first service will receive relation events about
+all service units for the second service. Subordinate services have a
+very tight relationship with their principal service, so it makes
+sense to be able to restrict that communication in some cases so that
+they only receive events about each other. That's precisely what
+happens when a relation is tagged as being a scoped to the
+container. See :doc:`scoped relations<charm>`.
+
+Container relations exist because they simplify responsibilities for
+the subordinate service charm author who would otherwise always have
+to filter units of their relation before finding the unit they can
+operate on.
+
+If a subordinate service needs to communicate with all units of the
+principal service, it can still establish a traditional
+(non-container) relationship to it.
+
+In order to deploy a subordinate service a `scope: container`
+relationship is required. Even when the principal services' charm
+author doesn't provide an explicit relationship for the subordinate to
+join, using an :doc:`implicit relation<implicit-relations>` with
+`scope: container` will satisfy this constraint.
+
+
+Addressability
+--------------
+
+No special changes are made for the purpose of naming or addressing
+subordinate units. If a subordinate logging service is deployed with a
+single unit of wordpress we would expect the logging unit to be
+addressable as logging/0, if this service were then related to a mysql
+service with a single unit we'd expect logging/1 to be deployed in its
+container. Subordinate units inherit the public/private address of the
+principal service. The container of the principal defines the network
+setup.
+
+
+Declaring subordinate charms
+----------------------------
+
+When a charm author wishes to indicate their charm should operate as a
+subordinate service only a small changes to the subordinate charms
+metadata is required. Declaring a required interface with `scope:
+container` in the interface definition of the charms metadata will
+result in a subordinate deployment. Subordinate services may still
+declare traditional relations to any service. The deployment is
+delayed until a container relation is added.
+
+The example below shows adding a container relation to a charm. ::
+
+    requires:
+        logging-directory:
+           interface: logging
+           scope: container
+
+
+
+Status of subordinates
+----------------------
+
+The status output contains details about subordinate units under the
+status of the principal service unit that it is sharing the container
+with. The subordinate unit's output matches the formatting of existing
+unit entries but omits `machine`, `public-address` and `subordinates`
+(which are all the same as the principal unit).
+
+The subordinate service is listed in the top level `services`
+dictionary in an abbreviated form. The `subordinate-to: []` list is
+added to the service which contains the names of all services this
+service is subordinate to. `units` is displayed as a list of principal
+unit names under which instances of this service are found. ::
+
+     services:
+       logging:
+         charm: local:series/logging-1
+         subordinate-to: [wordpress]
+         relations:
+          logging-directory: wordpress
+       wordpress:
+          machine: 0
+          public-address: wordpress-0.example.com
+          charm: local:series/wordpress-3
+          relations: {loggin: logging}
+          units:
+            wordpress/0:
+              relations:
+                logging: {state: up}
+              state: started
+              subordinates:
+                  logging/0:
+                    relations:
+                      logging: {state: up}
+
+
+
+Usage
+-----
+
+Assume the following deployment::
+
+  juju deploy mysql
+  juju deploy wordpress
+  juju add-relation mysql wordpress
+
+Now we'll create a subordinate logging service::
+
+  juju deploy logging
+  juju add-relation logging mysql
+  juju add-relation logging wordpress
+
+This will create a logging service unit inside each of the containers
+holding the mysql and wordpress units.  The logging service has a
+standard client-server relation to both wordpress and mysql but these
+new relationships are implemented only between the principal unit and
+the subordinate unit . A subordinate unit may still have standard
+relations established with any unit in its environment as usual.

=== modified file 'juju/charm/metadata.py'
--- juju/charm/metadata.py	2011-11-14 15:58:01 +0000
+++ juju/charm/metadata.py	2012-02-09 03:51:19 +0000
@@ -15,10 +15,16 @@
 
 UTF8_SCHEMA = UnicodeOrString("utf-8")
 
+SCOPE_GLOBAL = "global"
+SCOPE_CONTAINER = "container"
+
+
 INTERFACE_SCHEMA = KeyDict({
-        "interface": UTF8_SCHEMA,
-        "limit": OneOf(Constant(None), Int()),
-        "optional": Bool()})
+    "interface": UTF8_SCHEMA,
+    "limit": OneOf(Constant(None), Int()),
+    "scope": OneOf(Constant(SCOPE_GLOBAL), Constant(SCOPE_CONTAINER)),
+    "optional": Bool()},
+    optional=["scope"])
 
 
 class InterfaceExpander(object):
@@ -66,6 +72,7 @@
             return {
                 "interface": UTF8_SCHEMA.coerce(value, path),
                 "limit": self.limit,
+                "scope": "global",
                 "optional": False}
         else:
             # Optional values are context-sensitive and/or have
@@ -76,6 +83,7 @@
                 value["limit"] = self.limit
             if "optional" not in value:
                 value["optional"] = False
+            value["scope"] = value.get("scope", "global")
             return INTERFACE_SCHEMA.coerce(value, path)
 
 
@@ -87,7 +95,8 @@
     "peers": Dict(UTF8_SCHEMA, InterfaceExpander(limit=1)),
     "provides": Dict(UTF8_SCHEMA, InterfaceExpander(limit=None)),
     "requires": Dict(UTF8_SCHEMA, InterfaceExpander(limit=1)),
-    }, optional=set(["provides", "requires", "peers", "revision"]))
+    "subordinate": Bool(),
+    }, optional=set(["provides", "requires", "peers", "revision", "subordinate"]))
 
 
 class MetaData(object):
@@ -144,6 +153,26 @@
         """The charm peers relations."""
         return self._data.get("peers")
 
+    @property
+    def is_subordinate(self):
+        """Indicates the charm requires a contained relationship.
+
+        This property will effect the deployment options of its
+        charm. When a charm is_subordinate it can only be deployed
+        when its contained relationship is satisfied. See the
+        subordinates specification.
+        """
+        if self._data.get("subordinate", False) is False:
+            return False
+
+        if not self.requires:
+            return False
+
+        for relation_data in self.requires.values():
+            if relation_data.get("scope") == "container":
+                return True
+        return False
+
     def get_serialization_data(self):
         """Get internal dictionary representing the state of this instance.
 
@@ -187,6 +216,17 @@
                 "%s: revision field is obsolete. Move it to the 'revision' "
                 "file." % path)
 
+        if self._data.get("subordinate", False) is True:
+            proper_subordinate = False
+            if self.requires:
+                for relation_data in self.requires.values():
+                    if relation_data.get("scope") == "container":
+                        proper_subordinate = True
+            if not proper_subordinate:
+                log.warning(
+                    "%s labeled subordinate but lacking scope:container `requires` relation",
+                    path)
+
     def parse_serialization_data(self, serialization_data, path=None):
         """Parse the unprocessed serialization data and load in this instance.
 

=== added directory 'juju/charm/tests/repository/series/logging'
=== added file 'juju/charm/tests/repository/series/logging/.ignored'
--- juju/charm/tests/repository/series/logging/.ignored	1970-01-01 00:00:00 +0000
+++ juju/charm/tests/repository/series/logging/.ignored	2012-02-09 03:51:19 +0000
@@ -0,0 +1,1 @@
+#
\ No newline at end of file

=== added directory 'juju/charm/tests/repository/series/logging/hooks'
=== added file 'juju/charm/tests/repository/series/logging/hooks/install'
--- juju/charm/tests/repository/series/logging/hooks/install	1970-01-01 00:00:00 +0000
+++ juju/charm/tests/repository/series/logging/hooks/install	2012-02-09 03:51:19 +0000
@@ -0,0 +1,2 @@
+#!/bin/bash
+echo "Done!"

=== added file 'juju/charm/tests/repository/series/logging/metadata.yaml'
--- juju/charm/tests/repository/series/logging/metadata.yaml	1970-01-01 00:00:00 +0000
+++ juju/charm/tests/repository/series/logging/metadata.yaml	2012-02-09 03:51:19 +0000
@@ -0,0 +1,13 @@
+name: logging
+summary: "Subordinate logging test charm"
+description: |
+    This is a longer description which
+    potentially contains multiple lines.
+subordinate: true
+provides:
+    logging-client:
+       interface: logging
+requires:
+    logging-directory:
+       interface: logging
+       scope: container

=== added file 'juju/charm/tests/repository/series/logging/revision'
--- juju/charm/tests/repository/series/logging/revision	1970-01-01 00:00:00 +0000
+++ juju/charm/tests/repository/series/logging/revision	2012-02-09 03:51:19 +0000
@@ -0,0 +1,1 @@
+1
\ No newline at end of file

=== modified file 'juju/charm/tests/test_metadata.py'
--- juju/charm/tests/test_metadata.py	2011-11-08 14:30:44 +0000
+++ juju/charm/tests/test_metadata.py	2012-02-09 03:51:19 +0000
@@ -59,6 +59,7 @@
         self.assertEquals(self.metadata.obsolete_revision, None)
         self.assertEquals(self.metadata.summary, None)
         self.assertEquals(self.metadata.description, None)
+        self.assertEquals(self.metadata.is_subordinate, False)
 
     def test_parse_and_check_basic_info(self):
         """
@@ -72,6 +73,41 @@
         self.assertEquals(self.metadata.description,
                           u"This is a longer description which\n"
                           u"potentially contains multiple lines.\n")
+        self.assertEquals(self.metadata.is_subordinate, False)
+
+    def test_is_subordinate(self):
+        """Validate rules for detecting proper subordinate charms are working"""
+        logging_path = os.path.join(
+            test_repository_path, "series", "logging", "metadata.yaml")
+        logging_configuration = open(logging_path).read()
+        self.metadata.parse(logging_configuration)
+        self.assertTrue(self.metadata.is_subordinate)
+
+    def test_subordinate_without_container_relation(self):
+        """Validate rules for detecting proper subordinate charms are working
+
+        Case where no container relation is specified.
+        """
+        with self.change_sample() as data:
+            data["subordinate"] = True
+        log = self.capture_logging("juju.charm")
+
+        self.metadata.parse(self.sample, "some/path")
+        self.assertIn("some/path labeled subordinate but lacking scope:container `requires` relation",
+        log.getvalue())
+
+    def test_scope_constraint(self):
+        """Verify the scope constrain is parsed properly."""
+        logging_path = os.path.join(
+            test_repository_path, "series", "logging", "metadata.yaml")
+        logging_configuration = open(logging_path).read()
+        self.metadata.parse(logging_configuration)
+        # Verify the scope settings
+        self.assertEqual(self.metadata.provides[u"logging-client"]["scope"],
+                         "global")
+        self.assertEqual(self.metadata.requires[u"logging-directory"]["scope"],
+                         "container")
+        self.assertTrue(self.metadata.is_subordinate)
 
     def assert_parse_with_revision(self, with_path):
         """
@@ -204,7 +240,7 @@
         self.assertEqual(metadata.peers, None)
         self.assertEqual(
             metadata.provides["server"],
-            {"interface": "mysql", "limit": None, "optional": False})
+            {"interface": "mysql", "limit": None, "optional": False, "scope": "global"})
         self.assertEqual(metadata.requires, None)
 
     def test_riak_sample(self):
@@ -212,13 +248,13 @@
         metadata = self.get_metadata("riak")
         self.assertEqual(
             metadata.peers["ring"],
-            {"interface": "riak", "limit": 1, "optional": False})
+            {"interface": "riak", "limit": 1, "optional": False, "scope": "global"})
         self.assertEqual(
             metadata.provides["endpoint"],
-            {"interface": "http", "limit": None, "optional": False})
+            {"interface": "http", "limit": None, "optional": False, "scope": "global"})
         self.assertEqual(
             metadata.provides["admin"],
-            {"interface": "http", "limit": None, "optional": False})
+            {"interface": "http", "limit": None, "optional": False, "scope": "global"})
         self.assertEqual(metadata.requires, None)
 
     def test_wordpress_sample(self):
@@ -227,13 +263,13 @@
         self.assertEqual(metadata.peers, None)
         self.assertEqual(
             metadata.provides["url"],
-            {"interface": "http", "limit": None, "optional": False})
+            {"interface": "http", "limit": None, "optional": False, "scope": "global"})
         self.assertEqual(
             metadata.requires["db"],
-            {"interface": "mysql", "limit": 1, "optional": False})
+            {"interface": "mysql", "limit": 1, "optional": False, "scope": "global"})
         self.assertEqual(
             metadata.requires["cache"],
-            {"interface": "varnish", "limit": 2, "optional": True})
+            {"interface": "varnish", "limit": 2, "optional": True, "scope": "global"})
 
     def test_interface_expander(self):
         """Test rewriting of a given interface specification into long form.
@@ -252,22 +288,22 @@
         # shorthand is properly rewritten
         self.assertEqual(
             expander.coerce("http", ["provides"]),
-            {"interface": "http", "limit": None, "optional": False})
+            {"interface": "http", "limit": None, "optional": False, "scope": "global"})
 
         # defaults are properly applied
         self.assertEqual(
             expander.coerce(
                 {"interface": "http"}, ["provides"]),
-            {"interface": "http", "limit": None, "optional": False})
+            {"interface": "http", "limit": None, "optional": False, "scope": "global"})
         self.assertEqual(
             expander.coerce(
                 {"interface": "http", "limit": 2}, ["provides"]),
-            {"interface": "http", "limit": 2, "optional": False})
+            {"interface": "http", "limit": 2, "optional": False, "scope": "global"})
         self.assertEqual(
             expander.coerce(
-                {"interface": "http", "optional": True},
+                {"interface": "http", "optional": True, "scope": "global"},
                 ["provides"]),
-            {"interface": "http", "limit": None, "optional": True})
+            {"interface": "http", "limit": None, "optional": True, "scope": "global"})
 
         # invalid data raises SchemaError
         self.assertRaises(
@@ -276,7 +312,7 @@
         self.assertRaises(
             SchemaError,
             expander.coerce,
-            {"interface": "http", "optional": None}, ["provides"])
+            {"interface": "http", "optional": None, "scope": "global"}, ["provides"])
         self.assertRaises(
             SchemaError,
             expander.coerce,
@@ -286,4 +322,4 @@
         expander = InterfaceExpander(limit=1)
         self.assertEqual(
             expander.coerce("http", ["consumes"]),
-            {"interface": "http", "limit": 1, "optional": False})
+            {"interface": "http", "limit": 1, "optional": False, "scope": "global"})