github.com/mhilton/juju-juju@v0.0.0-20150901100907-a94dd2c73455/doc/bootstrapping.txt (about)

     1  Boostrapping an environment
     2  
     3  When you first start looking at the bootstrap process it all seems to be a convoluted mess. However there is method to our madness.
     4  
     5  Bootstrapping starts with the CLI command `bootstrap`.  That is found in
     6     cmd/juju/bootstrap.go
     7  
     8  The first step of bootstrap is to create an Environ instance which is named.
     9  This Environ instance has the environment configuration (the *config.Config instance).
    10  Initially this will check in the default config store, which is $JUJU_HOME/environments.
    11  This calls through to environs.PrepareForName in environs/open.go.  This makes sure the the
    12  environment configuration contains an admin secret, a CA cert, and a UUID.
    13  
    14  It is at this time that the initial .jenv file is written out to $JUJU_HOME/environments.
    15  
    16  Further checks are then done as part of the bootstrap command:
    17   * validating the constaints
    18   * checking to make sure the environment is already bootstrapped
    19  
    20  The code then moves on to the Bootstrap function defined in environs/bootstrap/bootstrap.go.
    21  
    22  bootstrap.Bootstrap starts with sanity checks:
    23   * setting a package global in the network package for prefer IPv6 (not sanity)
    24   * there is an admin-secret
    25   * that there is at least one authorised SSH key
    26   * that there is a CA Cert and CA Key
    27   * that the environment storage is writable (by writing the bootstrap-init file)
    28   * finds available tools
    29     - locate tools available externally (matching constraints)
    30     - determine which tools can be built and uploaded to make up shortfall in above
    31     - if the best tools are made locally, and we can upload tools, they get uploaded
    32  
    33  This code then calls into the Bootstrap function on the environ instance (backed by a provider), which returns arch, series, and a finalizer function.
    34  
    35  Now things diverge here a little:
    36   * azure does some initial config around affinity groups and networks, then calls common.Bootstrap.
    37   * ec2, joyent, maas, and openstack all fall through to common.Bootstrap
    38   * dummy, local and manual all do their own thing
    39  
    40  Firstly, common.Bootstrap:
    41   * creates machine config for the bootstrap machine
    42   * starts an instance for the bootstrap machine
    43   * writes the instance id (as yaml) into the the "provider-state" file in environ storage
    44     - this step will go away soon, or at least become provider specific
    45  
    46  The finalizer function, is run after the following checks from bootstrap.Bootstrap:
    47   * selects tools from the previously calculated set based on the architecture and series
    48     of the instance that the provider started
    49   * makes sure that the tools are available
    50   * creates the machine config struct for the bootstrap machine
    51   * sets the tools in that structure to the tools bootstap knows about
    52   * then it calls the finalizer function.
    53  
    54  The common finalizer function does the following: 
    55   * updates the machine config with the instance id of the new machine
    56   * calls environs.FinishMachineConfig
    57     * populates the machine config with information from the config object
    58     * checks for CA Cert
    59     * checks for admin-secret
    60     * creates a password hash using the utils.CompatSalt
    61     * uses this password hash for both the APIInfo and MongoInfo passwords.
    62     * creates the state server cert and key
    63     * strips the admin-secret and server ca-private-key from the config
    64       * this step is probably not needed any more
    65   * calls common.FinishBootstrap
    66     * calls ssh with a custom script that first checks the nonce on the cloud instance
    67     * calls ConfigureMachine
    68       * creates cloud init script from the machine config, this includes the call
    69         to jujud bootstrap-state.
    70       * the bootstrap config is passed to jujud as base64 encoded yaml
    71       * runs said script over ssh
    72  
    73  jujud bootstrap-state
    74  
    75   * creates a *config.Config object from the base64 encoded yaml from the command line
    76   * sets the package global in the network package for prefer IPv6
    77   * generates and writes out the system SSH identity file
    78   * generates a (long) shared secret for mongo
    79   * mongo is then started
    80   * the database is then initialized (state.Initialize)
    81   * copies the tools into environment storage
    82     - also clones the tools for each series of the same OS
    83       (for the time being at least, while each series' tools are equivalent)