Managing machines

Like all our APIs the compute service uses resource names, these resource names are based on a resource path like a URL. Machines for example have a resource name like projects/your-project-name/machines/some-machine-identifier. Where projects/your-project-name is the parent and machines/some-machine-identifier the relative name. The machine id is some-machine-identifier.

Our SDKs help with this by instantiating a new client library with the project name as first argument to the client. And most machine action methods will have the machine id as first argument. For example stopMachine('some-machine-identifier').

All of our APIs and SDKs are designed around idempotency. This means that it should always be possible to do a call again with the same idempotency key, if the call has already been executed the previous response will be returned. This makes retries during for example network errors possible. There will be no side-effects and the action won't be repeated.

For long running operations like creating a machine our API will return an operation. As the operation progresses the metadata of the operation will update with a progress report. You can poll this operation until the Done property will be true. At that point there will be a response or error available in the operation.

Listing machines

CLIPHP

cbws compute machine list

<?php

use Cbws\Sdk\Compute\V1alpha1\ListMachinesRequest;

require_once 'vendor/autoload.php';

// Instantiate new Compute service client
$compute = new \Cbws\Sdk\Compute\V1alpha1\Client('your-project-name');

// Paginate through machines, can also use listMachines
foreach ($compute->paginateMachines(ListMachinesRequest::create()->withoutState()) as $machine) {
    echo $machine->getName() . PHP_EOL;
}

Creating a machine

CLIPHP

cbws compute machine create some-machine

<?php
require_once 'vendor/autoload.php';

// Instantiate new Compute service client
$compute = new \Cbws\Sdk\Compute\V1alpha1\Client('your-project-name');

// Start the machine creation operation in the background
$operation = $compute->createMachine(
    'some-machine-identifier',

    Machine::create()
        ->withHostname('some-machine.example.com') // this is optional, will default to the machine name
        ->withType('zones/nl-ein-1/types/g2.1') // Start with G2.1 (1 core, 2 GB of RAM and 20 GB SSD) machine type in the NL-EIN-1 availability zone,

    // Ensure we can recover after an error during the request, re-calling the createMachine call with the same
    // idempotency key will return the result of the initial call. This is recommended but optional.
    CreateMachineRequest::create()->withIdempotencyKey(Uuid::fromString('e62e7adf-9763-41aa-b2c8-2291cd035739'))
);

// Poll the operation has finished, you could also call $compute->getOperation() which does not block.
foreach ($compute->pollOperation($operation->getName()) as $operation) {
    print_r($operation);
}

Stopping a machine

CLIPHP

cbws compute machine stop machine-name

<?php
// Start the machine stop operation in the background
$operation = $compute->stopMachine(
    'some-machine-identifier',
    // Ensure we can recover after an error during the request, re-calling the stopMachine call with the same
    // idempotency key will return the result of the initial call. This is recommended but optional.
    StopMachineRequest::create()->withIdempotencyKey(Uuid::fromString('e62e7adf-9763-41aa-b2c8-2291cd035739'))
);

// Poll the operation has finished, you could also call $compute->getOperation() which does not block.
foreach ($compute->pollOperation($operation->getName()) as $operation) {
    print_r($operation);
}