Provisioning

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.

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.

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.

REST Access

All PMS services are available via the Console's [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) 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 [--cluster-id=CLUSTER_ID] [--] <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 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