Servers¶

Listing servers¶

To list a collection of servers, you run:

<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);

$compute = $openstack->computeV2(['region' => '{region}']);

$servers = $compute->listServers(['imageId' => '{imageId}']);

foreach ($servers as $server) {
}

Each iteration will return a :apiref:Server instance <OpenStack/Compute/v2/Models/Server.html>.

By default, PHP generators are used to represent collections of resources in the SDK. The benefit of using generators is that it generally improves performance, since objects are not saved in memory as the iteration cycle goes on; instead, each resource is directly output to the user-defined foreach loop. For all intents and purposes, you interact with generators like any other Traversable object, but to retain collections in memory, you will need to implement your own logic.

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Detailed information¶

By default, only the id, links and name attributes are returned by the server. To return all information for a server, you must enable detailed information, like so:

$servers = $service->listServers(true);

Filtering collections¶

By default, every server will be returned by the remote API. To filter the returned collection, you can provide query parameters which are documented in the reference documentation.

use OpenStack\Common\DateTime;

$servers = $service->listServers(false, [
    'changesSince' => DateTime::factory('yesterday')->toIso8601(),
    'flavorId'     => 'performance1-1',
]);

Create a server¶

The only attributes that are required when creating a server are a name, flavor ID and image ID. The simplest example would therefore be this:

<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);

$compute = $openstack->computeV2(['region' => '{region}']);

$options = [
    // Required
    'name'     => '{serverName}',
    'imageId'  => '{imageId}',
    'flavorId' => '{flavorId}',

    // Required if multiple network is defined
    'networks'  => [
        ['uuid' => '{networkId}']
    ],

    // Optional
    'metadata' => ['foo' => 'bar'],
    'userData' => base64_encode('echo "Hello World. The time is now $(date -R)!" | tee /root/output.txt')
];

// Create the server
/**@var OpenStack\Compute\v2\Models\Server $server */
$server = $compute->createServer($options);

You can further configure your new server, however, by following the below sections, which instruct you how to add specific functionality. They are interoperable and can work together.

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Security groups¶

You can associate your new server with pre-existing security groups by specifying their _name_. One server can be associated with multiple security groups:

$options['securityGroups'] = ['secGroup1', 'default', 'secGroup2'];

Networks¶

By default, the server instance is provisioned with all isolated networks for the tenant. You can, however, configure access by specifying which networks your VM is connected to. To do this, you can either:

specify the UUID of a Neutron network. This is required if you omit the port ID.
specify the UUID of a Neutron port. This is required if you omit the network ID. The port must exist and be in a DOWN state.

// Specifying the network
$options['networks'] = [
    ['uuid' => '{network1Id}'],
    ['uuid' => '{network2Id}'],
];

// Or, specifying the port:
$options['networks'] = [
    ['port' => '{port1Id}'],
    ['port' => '{port2Id}'],
];

External devices and boot from volume¶

This option allows for the booting of the server from a volume. If specified, the volume status must be available, and the volume attach_status in the OpenStack Block Storage DB must be detached.

For example, to boot a server from a Cinder volume:

$options['blockDeviceMapping'] = [
    [
        'deviceName'      => '/dev/sda1',
        'sourceType'      => 'volume',
        'destinationType' => 'volume',
        'uuid'            => '{volumeId}',
        'bootIndex'       => 0,
    ]
];

Personality files¶

Servers, as they’re created, can be injected with arbitrary file data. To do this, you must specify the path and file contents (text only) to inject into the server at launch. The maximum size of the file path data is 255 bytes. The maximum limit refers to the number of bytes in the decoded data and not the number of characters in the encoded data.

The contents must be base-64 encoded.

$options['personality'] = [
    'path'     => '/etc/banner.txt',
    'contents' => base64_encode('echo "Hi!";'),
];

Metadata¶

The API also supports the ability to label servers with arbitrary key/value pairs, known as metadata. To specify this when the server is launched, use this option:

$options['metadata'] = [
    'foo' => 'bar',
    'baz' => 'bar',
];

Retrieve a server¶

When retrieving a server, sometimes you only want to operate on it - say to update or delete it. If this is the case, then there is no need to perform an initial GET request to the server:

<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);

$compute = $openstack->computeV2(['region' => '{region}']);

$server = $compute->getServer(['id' => '{serverId}']);

// By default, this will return an empty Server object and NOT hit the API.
// This is convenient for when you want to use the object for operations
// that do not require an initial GET request. To retrieve the server's details,
// run the following, which *will* call the API with a GET request:

$server->retrieve();

If, however, you do want to retrieve all the details of a remote server from the API, you just call:

$server->retrieve();

which will update the state of the local object. This gives you an element of control over your app’s performance.

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Update a server¶

The first step when updating a server is modifying the attributes you want updated. By default, only a server’s name, IPv4 and IPv6 IPs, and its auto disk config attributes can be edited.

<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);

$compute = $openstack->computeV2(['region' => '{region}']);

$server = $compute->getServer([
    'id' => '{serverId}',
]);

$server->name = '{newName}';
$server->update();

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Delete a server¶

To permanently delete a server:

<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);

$compute = $openstack->computeV2(['region' => '{region}']);

/**@var OpenStack\Compute\v2\Models\Server $server */
$server = $compute->getServer(['id' => '{serverId}']);

$server->delete();

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Retrieve metadata¶

This operation will retrieve the existing metadata for a server:

<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);

$compute = $openstack->computeV2(['region' => '{region}']);

$server = $compute->getServer(['id' => '{serverId}']);

$metadata = $server->getMetadata();

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Reset metadata¶

This operation will _replace_ all existing metadata with whatever is provided in the request. Any existing metadata not specified in the request will be deleted.

<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);

$compute = $openstack->computeV2(['region' => '{region}']);

$server = $compute->getServer([
    'id' => '{serverId}',
]);

$server->resetMetadata([
    'key' => 'value',
]);

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Merge metadata¶

This operation will _merge_ specified metadata with what already exists. Existing values will be overriden, new values will be added. Any existing keys that are not specified in the request will remain unaffected.

<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);

$compute = $openstack->computeV2(['region' => '{region}']);

$server = $compute->getServer(['id' => '{serverId}']);

$server->mergeMetadata([
    'key' => 'value'
]);

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Retrieve metadata item¶

This operation allows you to retrieve the value for a specific metadata item:

<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);

$compute = $openstack->computeV2(['region' => '{region}']);

$server = $compute->getServer(['id' => '{serverId}']);

$metadataItem = $server->getMetadataItem('{metadataItem}');

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Delete metadata item¶

This operation allows you to remove a specific metadata item:

<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);

$compute = $openstack->computeV2(['region' => '{region}']);

$server = $compute->getServer(['id' => '{serverId}']);

$server->deleteMetadataItem('key');

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Change root password¶

This operation will replace the root password for a server.

<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);

$compute = $openstack->computeV2(['region' => '{region}']);

$server = $compute->getServer([
    'id' => '{serverId}',
]);

$server->changePassword('{newPassword}');

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Reset server state¶

This operation will reset the state of the server.

<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);

$compute = $openstack->computeV2(['region' => '{region}']);

$server = $compute->getServer([
    'id' => '{serverId}',
]);

$server->resetState();

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Reboot server¶

This operation will reboot a server. Please be aware that you must specify whether you want to initiate a HARD or SOFT reboot (you specify this as a string argument).

<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);

$compute = $openstack->computeV2(['region' => '{region}']);

$server = $compute->getServer([
    'id' => '{serverId}',
]);

$server->reboot();

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Rebuild server¶

Rebuilding a server will re-initialize the booting procedure for the server and effectively reinstall the operating system. It will shutdown, re-image and then reboot your instance. Any data saved on your instance will be lost when the rebuild is performed.

<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);

$compute = $openstack->computeV2(['region' => '{region}']);

$server = $compute->getServer([
    'id' => '{serverId}',
]);

$server->rebuild([
    'imageId'   => '{imageId}',
    'name'      => '{newName}',
    'adminPass' => '{adminPass}',
]);

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Resize server¶

You can resize the flavor of a server by performing this operation. As soon the operation completes, the server will transition to a VERIFY_RESIZE state and a VM status of RESIZED. You will either need to confirm or revert the resize in order to continue.

<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);

$compute = $openstack->computeV2(['region' => '{region}']);

$server = $compute->getServer([
    'id' => '{serverId}',
]);

$server->resize('{flavorId}');

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Confirm server resize¶

Once a server has been resized, you can confirm the operation by calling this. The server must have the status of VERIFY_RESIZE and a VM status of RESIZED. Once this operation completes, the server should transition to an ACTIVE state and a migration status of confirmed.

<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);

$compute = $openstack->computeV2(['region' => '{region}']);

$server = $compute->getServer([
    'id' => '{serverId}',
]);

$server->confirmResize();

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Revert server resize¶

Once a server has been resized, you can revert the operation by calling this. The server must have the status of VERIFY_RESIZE and a VM status of RESIZED. Once this operation completes, the server should transition to an ACTIVE state and a migration status of reverted.

<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);

$compute = $openstack->computeV2(['region' => '{region}']);

$server = $compute->getServer([
    'id' => '{serverId}',
]);

$server->revertResize();

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Create server image¶

This operation will create a new server image. The only required option is the new image’s name. You may also specify additional metadata:

<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);

$compute = $openstack->computeV2(['region' => '{region}']);

$server = $compute->getServer(['id' => '{serverId}']);

$server->createImage([
    'name' => '{imageName}',
]);

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

List server IP addresses¶

To list all the addresses for a specified server or a specified server and network:

$ipAddresses = $server->listAddresses();

$public  = $ipAddresses['public'];
$private = $ipAddresses['private'];

You can also refine by network label:

$ipAddresses = $server->listAddresses([
    'networkLabel' => '{networkLabel}',
]);

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Further links¶

Reference docs for Server class
API docs

Read the Docs v: latest

Versions: latest; stable

Downloads: pdf; htmlzip; epub

On Read the Docs: Project Home; Builds

Free document hosting provided by Read the Docs.