This project is not being maintained, you should use something else.

kubernetesAPI-PHP-client

PHP client library for the Kubernetes API

** Current Version : v0.1.0 **

Contents

• Usage
  • Basic Usage
  • How to use the library
  • Configuration
  • API Endpoints
  • Response
• Installation
  • Requirements
  • Install with composer
• To Do
• About

Usage

Basic Usage

• Install the client and all of its required libraries (instructions)
• Register an PSR-0 compatible autoloader
• Create \DevStub\KubernetesAPIClient\Client() object instance
• Setup all of the configuration options
• Send a request

require '../vendor/autoload.php';
$client = new \DevStub\KubernetesAPIClient\Client();
$client->config()
    ->setAPINodeUrl("https://kubernetesServerAPI.com/api/") //
    ->setAPIVersion('v1beta1')
    ->setAuthType(\DevStub\KubernetesAPIClient\Config::AUTH_TYPE_HTTP_BASIC) // if we are using http authentication
    ->setAuthOptions(['username' => 'username', 'password' => 'password']); // we set the auth credentials

$response = null;

// here we create a new service by passing a json text
// we can also create the request structure with objects and method chaining .. read below for instructions
$client->services()->create(
    '{
  "id": "framework-dev",
  "kind": "Service",
  "apiVersion": "v1beta1",
  "port": 80,
  "containerPort": 80,
  "selector": {
    "name": "app-instance"
  }
}
',$response
);

$statusObj = $response->getContentObject();
// ... process the response here... 

How to use the library

For most of the functionality Client supports 3 ways of setting properties and options. Not all 3 ways are always supported yet so check the each object and it's method for it support

1. Explicitly instantiating objects and passing them as properties

   $pod  = new \DevStub\KubernetesAPIClient\Entity\v1beta1\Pod();
   $pod->setId("app-instance-dev-test".time());
   $pod->setKind("Pod");
   $pod->setApiVersion("v1beta1");
   
   $desiredState = new \DevStub\KubernetesAPIClient\Entity\v1beta1\PodState();
   // we prepare the desired state object
   // ...
   // then we pass it to the pod 
   $pod->setDesiredState($desiredState);
   // ...
   // ... we continue the same process for all other options
   // ...

2. Implicit creation of object by not setting the param

   $client->pods()->create(null,$response)
   	->setId("app-instance-dev-test".time())
   	->setKind("Pod")
   	->setApiVersion("v1beta1")
   	->setDesiredState() // new object is automatically instantiated here
   		->setManifest() //new object is automatically instantiated here
   			->setVolumes() new object is automatically instantiated here
   				->append() // add array item
   					->setName("data") // set property name
   					->setSource() new object is automatically instantiated here
   						->setEmptyDir()->end() new object is automatically instantiated here and closed
   						->end() // we close the setSource
   					->end() //we close the append
   				->end() // we close the setVolumes
   			->setVersion("v1beta1")
   			->setId("app-instance-dev-test".time())
   			->setContainers()
   				->append()
   					->setName("framework")
   					->setImage("registry.domain/user/dev-framework:v0.1.304")
   					->setImagePullPolicy("PullIfNotPresent")
   					->setLifecycle()
   						->setPostStart()
   							->setExec()
   								->setCommand()
   									->append("/opt/conf/poststart.sh")
   									->end()
   								->end()
   							->end()
   						->end()
   					->setVolumeMounts()
   						->append()
   							->setName("data")
   							->setMountPath("/data")
   							->end()
   						->end()
   					->setPorts()
   						->append()
   							->setContainerPort(80)
   							->end()
   						->end()
   					->end()
   				->end()
   			->end()
   		->end()
   	->end();

3. Passing a json string as an argument

   In below example we are just passing the full service request as json

   $response = '';
   
   $client->services()->create(
   	'{
     "id": "framework-dev",
     "kind": "Service",
     "apiVersion": "v1beta1",
     "port": 80,
     "containerPort": 80,
     "selector": {
   	"name": "app-instance"
     }
   }
   ',$response
   );
   var_dump($response);

Configuration

Before any requests can be made with the client you will need to setup some configuration options.

Following options are available

setSslVerify($value) $value = TRUE | FALSE - defaults: [TRUE] Set it to false when you don't want to verify the SSL cert. (Useful for development)

setAPINodeUrl($value) *$value = String * Set it to the full url of the Kubernetes API server. Note: don't include the version path portion. It is added by the client.

->setAPINodeUrl("https://kubernetesServerAPI.com/api/") //

setAPIVersion($value) $value = String - defaults: [v1beta1] Set the version of the API Schema

->setApiVersion("v1beta1");

setAuthType($value) $value = String - defaults: [Config::AUTH_TYPE_HTTP_BASIC] Options: Config::AUTH_TYPE_HTTP_BASIC, Config::AUTH_TYPE_NONE At this time only one type of auth type is supported

->setAuthType(\DevStub\KubernetesAPIClient\Config::AUTH_TYPE_HTTP_BASIC)

setAuthOptions($value) *$value = Array * *Options: username, password Set the array which provides auth data based on the authType Selected

->setAuthOptions(['username' => 'username', 'password' => 'password']); // we set the auth credentials

setConnectionAdapter($value) $value = String - defaults: [Config::CONNECTION_ADAPTER_GUZZLE] *Options: CONNECTION_ADAPTER_GUZZLE Sets the type of rest http adapter to use, currently only guzzle is supported.

->setConnectionAdapter(\DevStub\KubernetesAPIClient\Config::CONNECTION_ADAPTER_GUZZLE)

Configuration setting Example:

$clientConfig = new \DevStub\KubernetesAPIClient\Config();

$clientConfig->setAPINodeUrl("https://162.242.254.164/api/");
$clientConfig->setAPIVersion('v1beta1');
$client->config($clientConfig)

// or you can use method chaining on config

$clientConfig->setAPINodeUrl("https://162.242.254.164/api/")
			 ->setAPIVersion('v1beta1');
$client->config($clientConfig)

API Endpoints

To make requests to the API endpoints you call endpoint methods on the client object, which returns an endpoint object on which you can call: create, update, delete and get methods.

$client->services()->create($serviceObject);

Available endpoint methods on the client object:

• pods()
• replicationControllers()
• endpoints()
• services()
• minions()
• events()
• bindings()

Response

All of the requests will return an instance AdapterResponse class. With it you can check the status of the response:

$response = $client->pods()->get();
if ($response->getStatusCode() == 500) { // we check against http status code 500
    throw \Exception("error retrieving the response");
}

or retrieve the response content as JSON :

$response = $client->pods()->get();
$responseContent = $response->getContentRaw(); // this returns a json string
var_dump($responseContent);

or as nested objects :

$response = $client->pods()->get();
/* @var \DevStub\KubernetesAPIClient\Entity\v1beta1\PodList $podList */
$podList = $response->getContentObject();
/* @var \DevStub\KubernetesAPIClient\Entity\v1beta1\Pod $pod */
foreach ($podList->getItems() as $pod) {
	print "\n".$pod->getId();
}

For a full list of available kubernetes entities check the \DevStub\KubernetesAPIClient\Entity namespace

Installation

Requirements

• Guzzle Http client
• JsonMapper

Easies way to retrieve all of the dependencies is by using composer

Install with composer

The recommended way is to use Composer to install the kubernetes PHP API Client

# Install Composer
curl -sS https://getcomposer.org/installer | php

Next run composer to install the latest version of the kubernetes PHP API Client:

composer require devstub/kubernetes-api-php-client

And don't forget to require the autoloader in your project:

require 'vendor/autoload.php';

Alternatively you can also specify the dependency in your exisitng composer.json

 {
   "require": {
      "devstub/kubernetes-api-php-client": "*"
   }
}

To do

• Add unit tests
• Support other API Versions
• Support additional REST adapters
• Add way to poll/watch the endpoints for changes

About

License

Kubernetes PHP API Client is licensed under Apache 2.0

Author

Faruk Brbovic, DevStub.com