Provisioning

From DreamFactory
Jump to: navigation, search
m
m
 
(23 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
== Provisioners ==
 
== Provisioners ==
In the DFE world, a *provisioner* represents a contract to: manage instances, in a virtual environment, in a specific manner. This is physically represented in code by classes that adhere to one or more pre-defined interfaces. The diagram below shows the **DreamFactory** instance provisioner in code form.
+
In DFE, a '''provisioner''' represents a contract to manage virtual instances in a specific manner. This is physically represented in code by classes that adhere to one or more pre-defined '''interfaces'''. Below is the class/UML diagram of the ''DreamFactory'' provisioner.
  
 
[[file:Dfe-software-provisioning.png]]
 
[[file:Dfe-software-provisioning.png]]
  
Each provisioner is comprised of one or more *services* which provide portions of the provisioning process. This is not necessary. Provisioning may be completed by a single service. However, for flexibility and future expansion, the provisioning system is driven completely by configuration and discovery.
+
Each provisioner is comprised of one or more '''sub-provisioners''' which each provide a slice of the provisioning process. This is my no means necessary, and provisioning may be completed by a single service. For flexibility and future expansion, the provisioning system is driven completely by configuration and discovery.
  
The default **DreamFactory** provisioner is installed via composer using the `dreamfactory/dfe-dreamfactory-provisioner` package. This package consists of a service which adheres to the provisioning contracts stated above, and can be used to create and manage instances. It consists of three sub-provisioners. These are the *instance*, *storage*, and *database*.  
+
The default ''DreamFactory'' provisioner is installed via composer using the <code>dreamfactory/dfe-dreamfactory-provisioner</code> package. This package consists of a service which adheres to the provisioning contracts stated above, and can be used to create and manage instances. It consists of three sub-provisioners. These are the '''instance''', '''storage''', and '''database'''.  
  
In the DFE world, each **DreamFactory** instance requires provisioning management, storage facilities, and database access. These individual parts are managed by the three separate sub-provisioners defined in the library, and sub-sequential configuration. The default/shipping configuration is shown below.
+
To enable this provisioner, a section is added to the <code>config/provisioners.php</code> configuration file as shown below. This example stanza lives within the <code>provisioners.hosts</code> config array.
+
<pre>
+
<?php
+
//******************************************************************************
+
//* The instance provisioners available from this console
+
//******************************************************************************
+
use DreamFactory\Enterprise\Common\Enums\PortableTypes;
+
  
return [
+
<pre lang="php">
    //  The default provisioner
+
     'dreamfactory' => [
    'default' => 'dreamfactory',
+
         'provides'    => [
    //  The provisioners, or "hosts" of our instances, or "guests".
+
            PortableTypes::INSTANCE => DreamFactory\Enterprise\Provisioners\DreamFactory\InstanceProvisioner::class,
     'hosts'   => [
+
            PortableTypes::STORAGE  => DreamFactory\Enterprise\Provisioners\DreamFactory\StorageProvisioner::class,
         /** DreamFactory v2.x */
+
            PortableTypes::DATABASE => DreamFactory\Enterprise\Provisioners\DreamFactory\DatabaseProvisioner::class,
        'dreamfactory' => [
+
            /********************************************************************************
+
            * The namespace for our provisioning classes. This is optional and you may specify
+
            * fully qualified class names in the "provides" section. You cannot mix and match
+
            * however. If an "namespace" key exists, it will be pre-pended to all provisioner
+
            * classes.
+
            ********************************************************************************/
+
            /** 'namespace'    => 'App\Provisioners\Acme, */
+
            /********************************************************************************
+
            * Each provisioner has a set of "sub-provisioners". The important one is the
+
            * "instance" provisioner. Also required are two standard sub-provisioners.
+
            *
+
            * The first is "storage" which is the class responsible for instance storage
+
            * provisioning. The second is "db", or the class/service responsible for instance
+
            * database provisioning. Currently, all three (instance,db,storage) are required.
+
            * However, even though the methods are required to exist by the contract, they
+
            * may have empty method bodies and do nothing.
+
            *
+
            * Any of these "resource" sub-provisioners may implement the "PortableData"
+
            * interface, making them available for import/export services from the console and
+
            * dashboard. The "dreamfactory" provisioner does this and offers import/export services
+
            * through the provisioning sub-system.
+
            *
+
            * Developers may add additional sub-provisioners to the list in their own
+
            * provisioner host class.
+
            ********************************************************************************/
+
            'provides'    => [
+
                PortableTypes::INSTANCE => DreamFactory\Enterprise\Provisioners\DreamFactory\InstanceProvisioner::class,
+
                PortableTypes::STORAGE  => DreamFactory\Enterprise\Provisioners\DreamFactory\StorageProvisioner::class,
+
                PortableTypes::DATABASE => DreamFactory\Enterprise\Provisioners\DreamFactory\DatabaseProvisioner::class,
+
            ],
+
            /********************************************************************************
+
            * Provisioners may provide "offerings" or options that dictate certain features of
+
            * the available guest(s). Selecting a version for instance (as below). It can be
+
            * used for anything and provides an automatic UI in the Dashboard for user selection.
+
            ********************************************************************************/
+
            'offerings'    => [],
+
            /** The instance-provided resource discovery uri */
+
            'resource-uri' => '/api/v2/system/',
+
 
         ],
 
         ],
 +
        'offerings'    => [],
 +
        'resource-uri' => DreamFactory\Enterprise\Provisioners\DreamFactory\InstanceProvisioner::RESOURCE_URI,
 
     ],
 
     ],
];
 
 
</pre>
 
</pre>
  
The `provides` section details the sub-provisioners available with this provisioner configuration. As you see, there are the three discussed: instance, storage, and database. The order is not important because, in this case, the InstanceProvisioner class makes the sub-provisioning requests.  
+
The top level is the mnemonic name of the provisioner, ''dreamfactory'' in this case. This may contain the following elements:
 +
 
 +
* <code>provides</code>: an array of sub-provisioners that make up the entire provisioner. The ''dreamfactory'' provisioner consists of three sub-provisioners: instance, storage, and database.  
 +
* <code>offerings</code>: an array of options that are provided to the end-user during provisioning. These can be versions or other feature selections offered by the guest location and/or instance.
 +
* <code>resource-uri</code>: an endpoint at the provisioned instance where the console can communicate with it.
 +
 
 +
== Provisioning Management System ==
 +
The provisioning management system, or '''PMS''', consists of the ''ProvisionManager'' class and its ''Provision'' '''facade'''. It resolves and oversees all provisioning requests.
 +
 
 +
[[file:provisioning-manager.png]]
 +
 
 +
=== Available Services ===
 +
The PMS provides the following services:
 +
 
 +
* <code>provision</code>
 +
* <code>deprovision</code>
 +
* <code>import</code>
 +
* <code>export</code>
 +
 +
<br/>Each service is passed a request, or '''job''', as the first argument. These jobs are <code>ProvisionJob</code>, <code>DeprovisionJob</code>, <code>ImportJob</code>, and <code>ExportJob</code> respectively. Below is the class diagram for the four main job types. All services are eligible to be queued.
 +
 
 +
[[file:pms-job-types.png]]
 +
 
 +
==== REST Access ====
 +
All PMS services are available via the Console's [https://en.wikipedia.org/wiki/Representational_state_transfer RESTful] API. Please see the [[DFE/Console/REST|REST API]] section for further details. The endpoints are as follows:
 +
 
 +
* <code>/api/v1/ops/provision</code>
 +
* <code>/api/v1/ops/deprovision</code>
 +
* <code>/api/v1/ops/import</code>
 +
* <code>/api/v1/ops/export</code>
 +
 +
<br/>An eligible client is required to make these requests. The <code>dreamfactory/dfe-ops-client</code> package provides this service to any client.
 +
 +
==== Command Line Access ====
 +
All PMS services are available via command line as well. The following ''artisan'' commands are provided for this purpose:
 +
 
 +
* <code>dfe:provision [-c,--cluster-id=CLUSTER_ID] [-p,--packages=PACKAGES] [-t,--owner-type=OWNER_TYPE_] [--] <owner-id> <instance-id> [<guest-location>]</code>
 +
* <code>dfe:deprovision [--cluster-id=CLUSTER_ID] [--] <instance-id></code>
 +
* <code>dfe:import [--cluster-id=CLUSTER_ID] [--snapshot-id] [--owner-type=OWNER_TYPE] [--] <owner-id> <instance-id> <snapshot> [<guest-location>]</code>
 +
* <code>dfe:export [--destination=DESTINATION] [--] <instance-id></code>
 +
 +
<br/>All commands must be run from the [[DFE/Console|DFE Console]] installation directory.
 +
 
 +
=== Events ===
 +
Each of the four services, and their associated sub-services, will throw an event upon completion of the current task. One may create handlers to listen, and/or respond, to fired events. All events will receive a reference to the requesting service and the original request. The available events are:
  
The `offerings` section allows a provisioner to provide options, or *offerings*, to the requestor regarding the provisioning of instances. A different version number perhaps, or data "tags" and/or text.
+
* dfe.provisioned
 +
** dfe.storage.provisioned
 +
** dfe.database.provisioned
 +
* dfe.deprovisioned
 +
** dfe.storage.deprovisioned
 +
** dfe.database.deprovisioned
 +
* dfe.imported
 +
** dfe.storage.imported
 +
** dfe.database.imported
 +
* dfe.exported
 +
** dfe.storage.exported
 +
** dfe.database.exported

Latest revision as of 16:29, 4 April 2016

Provisioners

In DFE, a provisioner represents a contract to manage virtual instances in a specific manner. This is physically represented in code by classes that adhere to one or more pre-defined interfaces. Below is the class/UML diagram of the DreamFactory provisioner.

Dfe-software-provisioning.png

Each provisioner is comprised of one or more sub-provisioners which each provide a slice of the provisioning process. This is my no means necessary, and provisioning may be completed by a single service. For flexibility and future expansion, the provisioning system is driven completely by configuration and discovery.

The default DreamFactory provisioner is installed via composer using the dreamfactory/dfe-dreamfactory-provisioner package. This package consists of a service which adheres to the provisioning contracts stated above, and can be used to create and manage instances. It consists of three sub-provisioners. These are the instance, storage, and database.

To enable this provisioner, a section is added to the config/provisioners.php configuration file as shown below. This example stanza lives within the provisioners.hosts config array.

    'dreamfactory' => [
        'provides'     => [
            PortableTypes::INSTANCE => DreamFactory\Enterprise\Provisioners\DreamFactory\InstanceProvisioner::class,
            PortableTypes::STORAGE  => DreamFactory\Enterprise\Provisioners\DreamFactory\StorageProvisioner::class,
            PortableTypes::DATABASE => DreamFactory\Enterprise\Provisioners\DreamFactory\DatabaseProvisioner::class,
        ],
        'offerings'    => [],
        'resource-uri' => DreamFactory\Enterprise\Provisioners\DreamFactory\InstanceProvisioner::RESOURCE_URI,
    ],

The top level is the mnemonic name of the provisioner, dreamfactory in this case. This may contain the following elements:

  • provides: an array of sub-provisioners that make up the entire provisioner. The dreamfactory provisioner consists of three sub-provisioners: instance, storage, and database.
  • offerings: an array of options that are provided to the end-user during provisioning. These can be versions or other feature selections offered by the guest location and/or instance.
  • resource-uri: an endpoint at the provisioned instance where the console can communicate with it.

Provisioning Management System

The provisioning management system, or PMS, consists of the ProvisionManager class and its Provision facade. It resolves and oversees all provisioning requests.

Provisioning-manager.png

Available Services

The PMS provides the following services:

  • provision
  • deprovision
  • import
  • export


Each service is passed a request, or job, as the first argument. These jobs are ProvisionJob, DeprovisionJob, ImportJob, and ExportJob respectively. Below is the class diagram for the four main job types. All services are eligible to be queued.

Pms-job-types.png

REST Access

All PMS services are available via the Console's RESTful API. Please see the REST API section for further details. The endpoints are as follows:

  • /api/v1/ops/provision
  • /api/v1/ops/deprovision
  • /api/v1/ops/import
  • /api/v1/ops/export


An eligible client is required to make these requests. The dreamfactory/dfe-ops-client package provides this service to any client.

Command Line Access

All PMS services are available via command line as well. The following artisan commands are provided for this purpose:

  • dfe:provision [-c,--cluster-id=CLUSTER_ID] [-p,--packages=PACKAGES] [-t,--owner-type=OWNER_TYPE_] [--] <owner-id> <instance-id> [<guest-location>]
  • dfe:deprovision [--cluster-id=CLUSTER_ID] [--] <instance-id>
  • dfe:import [--cluster-id=CLUSTER_ID] [--snapshot-id] [--owner-type=OWNER_TYPE] [--] <owner-id> <instance-id> <snapshot> [<guest-location>]
  • dfe:export [--destination=DESTINATION] [--] <instance-id>


All commands must be run from the DFE Console installation directory.

Events

Each of the four services, and their associated sub-services, will throw an event upon completion of the current task. One may create handlers to listen, and/or respond, to fired events. All events will receive a reference to the requesting service and the original request. The available events are:

  • dfe.provisioned
    • dfe.storage.provisioned
    • dfe.database.provisioned
  • dfe.deprovisioned
    • dfe.storage.deprovisioned
    • dfe.database.deprovisioned
  • dfe.imported
    • dfe.storage.imported
    • dfe.database.imported
  • dfe.exported
    • dfe.storage.exported
    • dfe.database.exported