README

👁 Build Status
👁 Total Downloads
👁 Discord

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.

Getting Started

Install using composer:

composer require utopia-php/orchestration

Example

<?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);

Usage

Initialisation

There are currently two orchestrator adapters available and each of them has slightly different parameters:

• DockerAPI

  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.

• DockerCLI

  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:

• Pulling an image

  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');

  
  

• Running a container

  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,
  );

• Executing a command in a running container

  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,
  )

• Removing a container

  This method removes a container and returns a boolean value indicating if the container was removed successfully.

  $orchestration->remove('container_id', true);

• List containers

  This method returns an array of containers.

  $orchestration->list(['label' => 'value']);

• List Networks

  This method returns an array of networks.

  $orchestration->listNetworks();

• Create a Network

  This method creates a new network and returns a boolean value indicating if the network was created successfully.

  $orchestration->createNetwork('name', false);

• Remove a Network

  This method removes a network and returns a boolean value indicating if the network was removed successfully.

  $orchestration->removeNetwork('network_id');

• Connect a container to a network

  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');

• Disconnect a container from a network

  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);

System Requirements

Utopia Framework requires PHP 7.3 or later. We recommend using the latest PHP version whenever possible.

Copyright and license

The MIT License (MIT) http://www.opensource.org/licenses/mit-license.php