Zend Server Web API spotlight: Connecting to a Zend Server cluster

Hey everybody,

Having introduced the basics of Zend Server Web API we can now turn our attention to particular workflows, areas of interest and functionality. In this post, I will show you the basic steps our system goes through to connect to a Zend Server cluster and what happens behind the scenes. We’ll see some (un)popular pitfalls and also get a first glimpse into how our internal Tasks Queue works.

When connecting a Zend Server to a cluster we have two workflows that can be used. Both eventually achieve the same thing but have different requirements. As we’ve come to expect, both are available through the Web API named clusterAddServer and serverAddToCluster. In this post we will take a look at serverAddToCluster and find out the basics of cluster handling.

The Truth About Zend Server Clusters

Happily, I can dispell some of the stranger conspiracy theories about how a Zend Server Cluster works. The Zend Server infrastructure is broken into roughly two main parts: A Database and Everything Else.

Zend Server’s database is actually the beating heart of the Zend Server system. All of Zend Server’s components and daemons depend on the database to store and supply information. This information is anything from a communications medium between some of the components, to very information you can see on the UI.

This is a change from the Zend Server 5.x architecture which did things very differently. The new approach gives Zend Server incredible scalability and elasticity in its operations. Effectively even a single server is actually a cluster – a cluster with a single server, granted, but it is managed as a cluster regardless.

The Direct Approach

Born of this new approach in our architecture, was the idea that each Zend Server will manage itself with collaboration taking place in a central database. This means that when joining a cluster, each Zend Server is expected to run and manage its own connection process. So was born the serverAddToCluster Web API action which allows a client to order Zend Server into a cluster.

At a glance information for serverAddToCluster:

• Added on Web API version 1.3
• It requires FULL permissions to perform
• The request itself is a POST action
• The action is asynchronous, meaning you will get a 202 Accepted response

ServerAddToCluster accepts a number of mandatory parameters to create the connection:

• serverName allows you to enter a unique name to identify the new cluster member
• dbHost, dbName – the location of the database. dbHost can include a port if needed
• nodeId allows you to specify the interface throughwhich the Zend Server WebAPI will be accessible for the cluter to use
• dbUsername and dbPassword are the credentials needed to connect to the cluster database

Joining a cluster, first steps

What the action does changes depending on the current state of the cluster. If the cluster is brand new and this is the first server to become a member, this action will instantiate the database, create a non-root user for database access and add a new administrative Web API key. In some cases it will also create a new configuration snapshot to use for future reseting of your cluster’s configuration.

So, for the first cluster member, dbName is expected to be a root-privileged user. Otherwise, we may not have the permissions required to create the database schema. After the initial creation of the schema, Zend Server creates a ‘zend’ user for its future use and does not save the root user. For the next join operations use the ‘zend’ username and password.

If this is not the first member or the database schema is already in place, only the connection process will take place. Nothing else will change in the cluster. The current configuration blueprint will be imported and used on the newly joined cluster member.

The response body you will get includes three parts, depending on what took place in the connect process:

• serverInfo – the standard element of server information with everything you need to know about the new cluster member
• newCredentials – Informs you if new credentials were created for database access
• clusterAdminKey – Gives you details about the newly created administrative Web API key

Lets round this up with some code

We start the process by calling serverAddToCluster:

$client = new ZendHttpClient();
$client->setUri('http://localhost:10081/ZendServer/Api/
          serverAddToCluster')
 ->setEncType(ZendHttpClient::ENC_FORMDATA)
 ->setMethod('POST')
 ->setHeaders(array(
   ...
 ))
 ->getRequest()->getPost()->fromArray(
     array(
     'serverName' => 'Server unique name',
     'dbHost' => '10.0.0.10', 'dbUsername' => 'root',
     'dbPassword' => 'superSecretPass',
     'nodeIp' => '10.0.0.11','dbName' => 'ZendServer'
 ));
$response = $client->send();
echo $response->getBody();

After some time, this action should respond with:

      25
      Server unique name
      
10.0.0.10
      restarting
      
      false

      Yes

      2
      admin
      
      
      2010-12-15T17:59:12+02:00

What’s next?

If newCredentials is marked as new, you will want to visit the Zend Server logs and check up on the new credentials that were generated for you. You should use these new credentials for connecting other servers into your cluster and not just the all powerful root user.

Also important is to pickup and store the clusterAdminKey that was created for you as part of the database creation process. This key will allow you to continue working through the Web API with the newly joined server, since your old key will no longer be relevant.

The “Timely Manner” problem

In some cases, response to the action may become delayed for some reason, on Zend Server. A “Task did not respond in a timely manner” error will be returned. This indicates that Zend Server could not wait on the action any longer but that does not mean it actually failed – your server may yet join. If the process failed completely, you may want to contact support with your log files within reach. The answer can be a busy database, a heavily loaded computer or some other environment problem.

Next time

In general, after a while the server will join the cluster without requiring further integration. This naturally assumes nothing went wrong. In my next post I’ll take a peek into the next steps in joining clusters and how we can tell if something did actually get a little wonky (a technical term).

See you next time!

Read more : Zend Server Web API spotlight: Connecting to a Zend Server cluster