github.com/wallyworld/juju@v0.0.0-20161013125918-6cf1bc9d917a/doc/entity-creation.txt (about)

     1  Entity Creation
     2  ===============
     3  
     4  This document describes the circumstances in which fundamental state entities
     5  are created, from the perspective of the CLI.
     6  
     7  juju deploy
     8  -----------
     9  
    10  The `juju deploy` command always creates services, may create relations, and
    11  may also create units and machines.
    12  
    13    * New services can always be added.
    14    * If the created service's charm defines any peer relations, a (runtime) peer
    15      relation will be created for each. BUG: this is not done in the same
    16      transaction as service creation; a connection failure at the wrong time
    17      will create a broken and unfixable service (because peer relations cannot
    18      be manipulated via the CLI).
    19    * If the created service's charm is not subordinate, some number of units will
    20      be created; this number is controlled via the "--num-units" parameter which
    21      defaults to 1.
    22    * If units were created, machines may also be created, as below.
    23  
    24  
    25  juju add-unit
    26  -------------
    27  
    28  The `juju add-unit` command applies only to principal services. It always
    29  creates units, and may create machines. Different providers assign units to
    30  machines in different ways, and so machine creation can vary: for example, the
    31  ec2 provider creates a new machine for each unit that cannot be placed on an
    32  existing machine without assigned units.
    33  
    34    * New units can only be added to Alive services.
    35  
    36  
    37  juju add-relation
    38  -----------------
    39  
    40  The `juju add-relation` command creates relations, and may -- if the relation
    41  has container scope, by virtue of one or more endpoints having container scope
    42  -- indirectly cause the creation of subordinate units. Subordinate units are in
    43  fact created by principal unit agents, at the point when they enter scope of a
    44  container-scoped relation and find that no suitable subordinate already exists.
    45  
    46    * New relations can only be added between Alive services.
    47    * New subordinate units will only be added as a consequence of an Alive
    48      principal unit's participation in an Alive relation (implying an Alive
    49      subordinate service).