Utopia framework orchestration library is simple and lite library for abstracting the interaction with multiple container orchestrators. This library is aiming to be as simple and easy to learn and use. This library is maintained by the Appwrite team.
Although this library is part of the Utopia Framework project it is dependency free and can be used as standalone with any other PHP project or framework.
Install using composer:
composer require utopia-php/orchestration
<?php
require_once 'vendor/autoload.php';
use Utopia\Orchestration\Orchestration;
use Utopia\Orchestration\Adapter\DockerCLI;
// Initialise Orchestration with Docker CLI adapter.
$orchestration = new Orchestration(new DockerCLI());
// Pull the image.
$orchestration->pull('ubuntu:latest');
// Launch a ubuntu container that doesn't end using the tail command.
$containerID = $orchestration->run('ubuntu:latest', 'testContainer', ['tail', '-f', '/dev/null']);
$stderr = '';
$stdout = '';
// Execute a hello world command in the container
$orchestration->execute($containerID, ['echo', 'Hello World!'], $stdout, $stderr);
// Remove the container forcefully since it's still running.
$orchestration->remove($containerID, true);
There are currently two orchestrator adapters available and each of them has slightly different parameters:
-
Directly communicates to the Docker Daemon using the Docker UNIX socket.
use Utopia\Orchestration\Orchestration; use Utopia\Orchestration\Adapter\DockerAPI; $orchestration = new Orchestration(new DockerAPI($username, $password, $email));
$username, $password and $email are optional and are only used to pull private images from Docker Hub.
-
Uses the Docker CLI to communicate to the Docker Daemon.
use Utopia\Orchestration\Orchestration; use Utopia\Orchestration\Adapter\DockerCLI; $orchestration = new Orchestration(new DockerCLI($username, $password));
$username and $password are optional and are only used to pull private images from Docker Hub.
Once you have initialised your Orchestration object the following methods can be used:
-
This method pulls the image requested from the orchestrators registry. It will return a boolean value indicating if the image was pulled successfully.
$orchestration->pull('image:tag');
Parameters
-
image
[String] [Required]The image to pull from the registry.
-
-
This method creates and runs a new container. On success, it will return a string containing the container ID. On failure, it will throw an exception.
$orchestration->run( 'image:tag', 'name', ['echo', 'hello world!'], 'entrypoint', 'workdir', ['tmp:/tmp:rw', 'cooldirectory:/home/folder:rw'], ['ENV_VAR' => 'value'], '/tmp', ['label' => 'value'], 'hostname', true, );
Parameters
-
image
[String] [Required]The image to base the container off.
-
name
[String] [Required]The name given to the container.
-
command
[Array]The command to run in the container seperated into a array.
-
entrypoint
[String]The executable to run in the container.
-
workdir
[String]The default directory in which the container commands will run.
-
volumes
[Array]The volumes to attach to the container.
-
env
[Array]The environment variables to set in the container.
-
mountFolder
[String]A folder that will be automatically mounted to /tmp in the container
-
labels
[Array]The labels to set on the container.
-
hostname
[String]The hostname to set on the container.
-
remove
[Boolean]Whether to remove the container once it exits.
-
-
This method executes a command in an already running container and returns a boolean value indicating if the command was executed successfully.
$stdout = ''; $stderr = ''; $orchestraton->execute( 'container_id', ['echo', 'Hello World!'], $stdout, $stderr, ['VAR' => 'VALUE'], 10, )
Parameters
-
container_id
[String] [Required]The ID of the container to execute the command in.
-
command
[Array] [Required]The command to execute in the container.
-
stdout
[String] [Reference]The variable to store the stdout of the command in.
-
stderr
[String] [Reference]The variable to store the stderr of the command in.
-
env
[Array]The environment variables to set while executing the command.
-
timeout
[Integer]The timeout in seconds to wait for the command to finish.
-
-
This method removes a container and returns a boolean value indicating if the container was removed successfully.
$orchestration->remove('container_id', true);
Parameters
-
container_id
[String] [Required]The ID of the container to remove.
-
force
[Boolean]Whether to remove the container forcefully.
-
-
This method returns an array of containers.
$orchestration->list(['label' => 'value']);
Parameters
-
filters
[Array]Filters to apply to the list of containers.
-
-
This method returns an array of networks.
$orchestration->listNetworks();
Parameters
This method has no parameters
-
This method creates a new network and returns a boolean value indicating if the network was created successfully.
$orchestration->createNetwork('name', false);
Parameters
-
name
[String] [Required]The name of the network.
-
internal
[Boolean]Whether to set the network to be an internal network.
-
-
This method removes a network and returns a boolean value indicating if the network was removed successfully.
$orchestration->removeNetwork('network_id');
Parameters
-
network_id
[String] [Required]The ID of the network to remove.
-
-
This method connects a container to a network and returns a boolean value indicating if the connection was successful.
$orchestration->connect('container_id', 'network_id');
Parameters
-
container_id
[String] [Required]The ID of the container to connect to the network.
-
network_id
[String] [Required]The ID of the network to connect to.
-
-
This method disconnects a container from a network and returns a boolean value indicating if the removal was successful.
$orchestration->disconnect('container_id', 'network_id', false);
Parameters
-
container_id
[String] [Required]The ID of the container to disconnect from the network.
-
network_id
[String] [Required]The ID of the network to disconnect from.
-
force
[Boolean]Whether to disconnect the container forcefully.
-
Utopia Framework requires PHP 7.3 or later. We recommend using the latest PHP version whenever possible.
The MIT License (MIT) https://www.opensource.org/licenses/mit-license.php