Provisioning

Provisioners

In the DFE world, 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' => '/api/v2/system/',
    ],

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 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.