Usage

Command line tools

Occopus can be used via CLI commands to build, maintain, scale and destroy infrastructures. The commands and their usages are described below.

occopus-build

This command deploys an infrastructure based on an infrastructure description.

On error during creating the infrastructure it rolls back everything to the initial state. The user can also stop the process manually by executing a SIGINT (Ctrl + C). Allocation of resources will be rolled back in this case as well.

Once the infrastructure is successfully built, Occopus exits. This command provides no lifecycle-management.

Usage:

occopus-build [-h]
              [--cfg CFG_PATH]
              [--auth_data_path AUTH_DATA_PASS]
              [--parallelize]
              [-i INFRA_ID]
              infra_def
Parameters:
  • -h, --help: (optional) shows help message
  • --cfg CFG_PATH: (optional) path to Occopus config file (default: None) if undefined, file named occopus_config.yaml is searched at predefined locations, e.g. $HOME/.occopus
  • --auth_data_path AUTH_DATA_PATH: (optional) path to Occopus authentication file (default: None) if undefined, file named auth_data.yaml is searched at predefined locations, e.g. $HOME/.occopus
  • --parallelize: (optional) parallelize processing instructions e.g. independent nodes are created parallel (default: sequential)
  • -i INFRA_ID: (optional) identifier of a previously built, existing infrastructure - if provided, occopus will reconfigure the existing infrastructure instead of building a new one. Use with caution! Occopus may build/destroy nodes based on the difference between the existing and the new infrastructure defined by infra_def!
  • infra_def: file containing an infrastructure definition to be built
Return type:
On successful finish it returns the identifier of the infrastructure. The identifier can be stored or listed by the occopus-maintain command.

occopus-destroy

This command destroys an infrastructure including all of its nodes built previously by Occopus. No recover is possible.

Usage:

occopus-destroy [-h]
                [--cfg CFG_PATH]
                [--auth_data_path AUTH_DATA_PATH]
                -i INFRA_ID
Parameters:
  • -h, --help: (optional) shows help message
  • --cfg CFG_PATH: (optional) path to Occopus config file (default: None) if undefined, file named occopus_config.yaml is searched at predefined locations, e.g. $HOME/.occopus
  • --auth_data_path AUTH_DATA_PATH: (optional) path to Occopus authentication file (default: None) if undefined, file named auth_data.yaml is searched at predefined locations, e.g. $HOME/.occopus
  • -i INFRA_ID: identifier of the infrastructure to destroy

occopus-maintain

This command is capable of maintaining an infrastructure built by Occopus. Maintenance includes health checking, recovery and scaling. It can also list available infrastructure or can provide details on an infrastructure.

Usage:

occopus-maintain [-h]
                 [--cfg CFG_PATH]
                 [--auth_data_path AUTH_DATA_PATH]
                 [-l|--list]
                 [-r|--report]
                 [-i INFRA_ID]
                 [-c|--cyclic]
                 [-t INTERVAL]
Parameters:
  • -h, --help: (optional) shows help message
  • --cfg CFG_PATH: (optional) path to Occopus config file (default: None) if undefined, file named occopus_config.yaml is searched at predefined locations, e.g. $HOME/.occopus
  • --auth_data_path AUTH_DATA_PATH: (optional) path to Occopus authentication file (default: None) if undefined, file named auth_data.yaml is searched at predefined locations, e.g. $HOME/.occopus
  • -l, --list: (optional) list the built pieces of infrastructure
  • -r, --report: (optional) reports about an infrastructure
  • -i INFRA_ID: (optional) identifier of the infrastructure to maintain
  • -c, --cyclic: (optional) performs continuous maintenance
  • -t INTERVAL: (optional) specifies the time in seconds between maintenance sessions (default: 10)

occopus-scale

This command registers scaling requests for a given node in an infrastructure. With scaling the instance count of a node can be increased or decreased by a given number. Scaling requests are handled and realized by the occopus-maintain command.

Usage:

occopus-scale [-h]
              [--cfg CFG_PATH]
              [--auth_data_path AUTH_DATA_PATH]
              -i INFRA_ID
              -n|--node NODE
              -c|--count COUNT
Parameters:
  • -h, --help: (optional) shows help message
  • --cfg CFG_PATH: (optional) path to Occopus config file (default: None) if undefined, file named occopus_config.yaml is searched at predefined locations, e.g. $HOME/.occopus
  • --auth_data_path AUTH_DATA_PATH: (optional) path to Occopus authentication file (default: None) if undefined, file named auth_data.yaml is searched at predefined locations, e.g. $HOME/.occopus
  • -i INFRA_ID: identifier of the infrastructure which contains the node to scale
  • -n NODE, --node NODE: name of the node to scale
  • -c COUNT, --count COUNT: positive/negative number expressing the direction and magnitude of scaling (positive: scale up; negative: scale down)

occopus-import

This command imports i.e. loads the node definitions from file to the database behind Occopus.

Important

Each time a node definition file changes, this command must be executed since Occopus takes node definitions from its database!

Usage:

occopus-import [-h]
               [--cfg CFG_PATH]
               datafile
Parameters:
  • -h, --help: (optional) shows help message
  • --cfg CFG_PATH: (optional) path to Occopus config file (default: None) if undefined, file named occopus_config.yaml is searched at predefined locations, e.g. $HOME/.occopus
  • datafile: file containing node definition(s)

occopus-rest-service

This command launches occopus as a web service. The occopus rest service can create, maintain, scale and destroy any infrastructure built by the service. This service provides a restful interface described by REST API.

Usage:

occopus-rest-service [-h]
                     [--cfg CFG_PATH]
                     [--auth_data_path AUTH_DATA_PATH]
                     [--host HOST]
                     [--port PORT]
                     [--parallelize]
Parameters:
  • -h, --help: (optional) shows help message
  • --cfg CFG_PATH: (optional) path to Occopus config file (default: None) if undefined, file named occopus_config.yaml is searched at predefined locations, e.g. $HOME/.occopus
  • --auth_data_path AUTH_DATA_PATH: (optional) path to Occopus authentication file (default: None) if undefined, file named auth_data.yaml is searched at predefined locations, e.g. $HOME/.occopus
  • --host HOST: (optional) sets the host for the service to be assigned to (default: 127.0.0.1)
  • --port PORT: (optional) sets the port for the service to be assigned to (default: 5000)
  • --parallelize: (optional) parallelize processing instructions (default: sequential)

REST API

POST /infrastructures/

Create a new infrastructure and returns the identifier of the infrastructure. The returned identifier can be used as infraid parameter in the infrastructure-related commands.

Requires an infrastructure description as POST data.

Return type:
{
    "infraid": "<infraid_in_uuid_format>"
}

Example:

curl -X POST http://127.0.0.1:5000/infrastructures/ --data-binary @my_infrastructure_description.yaml
GET /infrastructures/

List the identifier of infrastructures currently maintained by the service.

Return type:
{
    "infrastructures": [
        "<infraid_in_uuid_format_for_an_infrastructure>",
        "<infraid_in_uuid_format_for_another_infrastructure>"
    ]
}
POST /infrastructures/(infraid)/scaledown/(nodename)/(nodeid)

Scales down a node in an infrastructure by destroying one of its instances specified.

Parameters:
  • infraid – The identifier of the infrastructure.
  • nodename – The name of the node which is to be scaled down.
  • nodeid – The identifier of the selected instance.
Return type:
{
    "infraid": "<infraid>",
    "method": "scaledown",
    "nodeid": "<nodeid>"
    "nodename": "<nodename>"
}
POST /infrastructures/(infraid)/scaleup/(nodename)/(int: count)

Scales up a node in an infrastructure by creating the specified number of instances of the node.

Parameters:
  • infraid – The identifier of the infrastructure.
  • nodename – The name of the node to be scaled up.
  • count – The number of instances to be created.
Return type:
{
    "count": <count>,
    "infraid": "<infraid>",
    "method": "scaleup",
    "nodename": "<nodename>"
}
POST /infrastructures/(infraid)/scaledown/(nodename)

Scales down a node by destroying one of its instances in the infrastructure. The instance to be destroyed is automatically selected by OCCO based on its configured DownScale strategy.

Parameters:
  • infraid – The identifier of the infrastructure.
  • nodename – The name of the node to be scaled down.
Return type:
{
    "infraid": "<infraid>",
    "method": "scaledown",
    "nodeid": null,
    "nodename": "<nodename>"
}
POST /infrastructures/(infraid)/scaleup/(nodename)

Scales up a node in an infrastructure by creating a new instance of the node.

Parameters:
  • infraid – The identifier of the infrastructure.
  • nodename – The name of the node to be scaled up.
Return type:
{
    "count": 1,
    "infraid": "<infraid>",
    "method": "scaleup",
    "nodename": "<nodename>"
}
POST /infrastructures/(infraid)/attach

Starts maintaining an existing infrastructure.

Parameters:
  • infraid – The identifier of the infrastructure.
Return type:
{
    "infraid": "<infraid>"
}
POST /infrastructures/(infraid)/detach

Stops maintaining an infrastructure.

Parameters:
  • infraid – The identifier of the infrastructure.
Return type:
{
    "infraid": "<infraid>"
}
POST /infrastructures/(infraid)/notify

Sets notification properties for an infrastructure.

Parameters:
  • infraid – The identifier of the infrastructure.

Requires a notification description in JSON format as the POST data.

Return type:
{
    "infraid": "<infraid>",
}
GET /infrastructures/(infraid)

Report the details of an infrastructure.

Parameters:
  • infraid – The identifier of the infrastructure.
Return type:
{
    "<nodename>": {
        "instances": {
            "<nodeid>": {
                "resource_address": "<ipaddress>",
                "state": "<state>"
            }
        },
        "scaling": {
            "actual": <current_number_of_instances>,
            "max": <maximum_number_of_instances>,
            "min": <minimum_number_of_instances>,
            "target": <target_number_of_instances>
        }
    },
    ...
}
DELETE /infrastructures/(infraid)

Shuts down an infrastructure.

Parameters:
  • infraid – The identifier of the infrastructure.
Return type:
{
    "infraid": "<infraid>"
}
GET /static/(path: filename)

Function used internally to send static files from the static folder to the browser.

New in version 0.5.

GET /info/(key)

Evaluates a key by the info broker and returns the value

Parameters:
  • key – The name of the key to be evaluated.

Python API

Occopus provides a Python API which can be used to implement Occopus-based applications in a unified way. The API gives the possibility to utilise Occopus functionalities inside an application. To read about this possibility, please go to the API section of the Developers’ guide.

Previous page

← Cloudbroker

Next page

→ Tutorial

This Page