Zonecloud Controller Handbook

Table of contents

• Creating a cluster
• Creating an agent
• Creating a node
• Easy ZoneCloud configuration for agents/nodes
• Creating a user
• Excluding a zone
• Removing a zone exclusion
• Changing timezone
• External API Access
  • Token authorization
  • Endpoints
    • POST /api/check_zone_active
    • POST /api/exclude-zone
    • POST /api/remove-exclude-zone
    • GET /api/get-duplicate-zones

Creating a cluster #

Navigate to Clusters and press the “Create cluster” button.

Give your new cluster a name press the “Create” button.

Creating an agent #

Navigate to “Servers” and press the “Create Server” button.

Fill in the required fields and press “Save”.

Server name: could be the hostname of the server, unique for each agent
Server token: will be used in the agent’s configuration file, press the “GENERATE” button to create a random one
IP: The server’s IP
Agent selection active
Cluster: Select the appropriate cluster from the list

Navigating back to the Servers page, you should see the newly created server/agent.

Creating a node #

Navigate to “Servers” and press the “Create Server” button.

Fill in the required fields and press “Save”.

Server name: could be the hostname of the server, unique for each agent
Server token: will be used in the nodes’s configuration file, press the “GENERATE” button to create a random one
IP: The server’s IP
Node selection active
Cluster: Select the appropriate cluster from the list

Navigating back to the Servers page, you should see the newly created server/node.

Easy ZoneCloud configuration for agents/nodes #

Navigate to “Servers” and press the “Configuration” button for the agent/node you want to setup.
You can copy-paste the configurations on your agent/node.

e.g.:

Creating a user #

Navigate to Users and press the “CREATE USER” button.
Fill in the appropriate fields and press “Create”.

Excluding a zone #

If for some reason you want a zone to not be served by an agent, all you have to do is navigate to Zones page and press the “Exclude” button.

Removing a zone exclusion #

Navigate to Zones page and locate the zone on the “Excluded zones” table.
Press the “Remove exclusion” button.

Changing timezone #

The time zone can be set on the .env file:

APP_TIMEZONE='Europe/Athens'

External API Access #

Token authorization #

To allow an external application to interact with ZoneCloud Controller’s API, you need to create an access token.

You can do this from the App API Access page.
From this page you can create new tokens or revoke existing ones.

Endpoints #

POST /api/check_zone_active #

{"active":true}

{"active":true,"active_in":["server1"]}

{"active":false}

{"message":"Authorization token missing\/invalid."}

{"active":false,"message":"No such cluster"}

{"message":"No zone given as parameter."}

curl examples:

curl https://<controller_hostname>/api/check_zone_active -H "Authorization: dEYmHvuoSiwQJATTF2y8fiAfZ9N887b" -X POST --data "zone=test1.com" {"active":true} 
curl https://<controller_hostname>/api/check_zone_active -H "Authorization: dEYmHvuoSiwQJATTF2y8fiAfZ9N887b" -X POST --data "zone=test-inactive1.com" {"active":false} 
curl https://<controller_hostname>/api/check_zone_active -H "Authorization: dEYmHvuoSiwQJATTF2y8fiAfZ9N887b" -X POST --data "zone=test1.com&extra_info=1" {"active":true,"active_in":["server1"]}

POST /api/exclude-zone #

Exclude a zone from an agent.

{"result":true,"message":"Zone excluded from server."}

{"result":false,"message":"Can't find an agent with such name."}

{"result":false,"message":"Can't find a zone with such name\/agent name."}

{"message":"Authorization token missing\/invalid."}

{"result":false,"message":"Missing \"zone\" and\/or \"server_name\" parameter."}

curl examples:

curl https://<controller_hostname>/api/exclude-zone -H "Authorization: dEYmHvuoSiwQJATTF2y8fiAfZ9N887b" -X POST --data "zone=test1.com&server_name=demo1"
{"result":true,"message":"Zone excluded from server."}

curl https://<controller_hostname>/api/exclude-zone -H "Authorization: dEYmHvuoSiwQJATTF2y8fiAfZ9N887b" -X POST --data "zone=test1.com&server_name=non_existing"
{"result":false,"message":"Can't find an agent with such name."}

curl https://<controller_hostname>/api/exclude-zone -H "Authorization: dEYmHvuoSiwQJATTF2y8fiAfZ9N887b" -X POST --data "zone=not-existing-zone.com&server_name=demo1"
{"result":false,"message":"Can't find a zone with such name\/agent name."}

POST /api/remove-exclude-zone #

Remove a zone exclusion from an agent.

{"result":true,"message":"Zone exclusion removed from server."}

{"result":false,"message":"Can't find an agent with such name."}

{"result":false,"message":"Can't find a zone with such name\/agent name."}

{"message":"Authorization token missing\/invalid."}

{"result":false,"message":"Missing \"zone\" and\/or \"server_name\" parameter."}

curl examples:

curl https://<controller_hostname>/api/remove-exclude-zone -H "Authorization: dEYmHvuoSiwQJATTF2y8fiAfZ9N887b" -X POST --data "zone=test1.com&server_name=demo1"
{"result":true,"message":"Zone exclusion removed from server."}

curl https://<controller_hostname>/api/remove-exclude-zone -H "Authorization: dEYmHvuoSiwQJATTF2y8fiAfZ9N887b" -X POST --data "zone=test1.com&server_name=non_existing"
{"result":false,"message":"Can't find an agent with such name."}

curl https://<controller_hostname>/api/remove-exclude-zone -H "Authorization: dEYmHvuoSiwQJATTF2y8fiAfZ9N887b" -X POST --data "zone=not-existing-zone.com&server_name=demo1"
{"result":false,"message":"Can't find a zone with such name\/agent name."}

GET /api/get-duplicate-zones #

Responds with duplicate zones along with a list of the servers that the zone is active in.

Takes no parameters.

curl exapmles:

curl -s https://<controller_hostname>/api/get-duplicate-zones -H "Authorization: dEYmHvuoSiwQJATTF2y8fiAfZ9N887b" | jq
[
{
"zone": "test0.com",
"server_id": 30,
"cluster_id": 6,
"count": 2,
"server_name": "demo1",
"duplicate_servers": [
{
"name": "demo1",
"id": 30
},
{
"name": "demo3",
"id": 32
}
],
"excluded_in": 0,
"excluded_server_count": 0,
"not_excluded_server_count": 2
}
]