bwsw / cs-entities

Simple CloudStack Entities Framework

GitHub

cs-entities

Simple CloudStack Entities Framework

The library provides the convenient way of working with Apache CloudStack entities through the following mechanisms:

  1. Creating and retrieving the declared entities on/from Apache CloudStack server, such as users, accounts, virtual machines, tags. It based on the extensible request builders which simplify creating CloudStack requests.
  2. Base set of Apache CloudStack events to work with CloudStack Event Log (see official documentation).

Install with SBT

Add the following to your build.sbt

libraryDependencies += "com.bwsw" %% "cs-entities" % "1.410np.0"

Getting Started

  1. Create Executor instance with specified parameters to interact with Apache CloudStack server. \
  2. Create JsonSerializer instance for parsing json responses from the server. \
  3. Use Executor and JsonSerializer to create a GenericDao instance, it may be an existing GenericDao or a custom implementation
    (if you implement GenericDao, first of all you have to implement one Request for each DAO method).
  4. Use existing Entity response hierarchy to work with users, accounts, vms or tags
    (if you create a new GenericDao implementation for another Apache CloudStack entity then you have to implement a new Entity response hierarchy).

The diagrams are provided for you to understand the process of library classes relationships.

Example Usage

The example below shows how to create new user entity in CloudStack server and then retrieve it:

val creatorSettings = PasswordAuthenticationClientCreator.Settings("admin","password","/")
val executorSettings = Executor.Settings(Array(s"http://localhost:8888/client/api"), retryDelay = 1000)

val creator = new PasswordAuthenticationClientCreator(creatorSettings)
val executor = new Executor(executorSettings, creator, true)
val mapper = new JsonMapper(true)

val userId = UUID.randomUUID()
val userCreationSettings = UserCreateRequest.Settings(
      accountName="admin",
      email = "e@example.com",
      firstName = "first",
      lastName = "last",
      password = "passwd",
      username = "username"
    )

val userCreateRequest = new UserCreateRequest(userCreationSettings).withId(userId)
userDao.create(userCreateRequest)

val findRequest = new UserFindRequest().withId(userId)
val users = userDao.find(findRequest)

Testing

Unit tests

Run tests: sbt test

Integration tests

  1. Add local environment variables:

    • CS_PORT - port of Apache CloudStack simulator server, for example - "8888"
    • CS_HOST - host of Apache CloudStack simulator server, by default - "localhost"
    • KAFKA_HOST - host of Kafka, for example - "localhost"
    • KAFKA_PORT - port of Kafka, for example - "9092"
    • KAFKA_TOPIC - kafka topic containing cloudstack events
  2. Run Apache CloudStack simulator in docker container:

    docker run -d --rm --name spotify-kafka --tty=true -p 2181:2181 -p $KAFKA_PORT:$KAFKA_PORT --env ADVERTISED_HOST=$KAFKA_HOST --env ADVERTISED_PORT=$KAFKA_PORT spotify/kafka
    
    docker run --rm -e KAFKA_HOST="${KAFKA_HOST}" \
                    -e KAFKA_PORT="${KAFKA_PORT}" \
                    -e KAFKA_TOPIC="${KAFKA_TOPIC}" \
                    --name cloudstack-kafka-sim -d -p $CS_PORT:$CS_PORT bwsw/cs-simulator-kafka:4.10.3-NP
  1. After the end of the cloudstack simulator deploying (you can check it like this) execute: sbt it:test

Versioning

Library includes the minor version which depends on CloudStack version.
For example 1.410.0 version depends on CloudStack 4.10

License

This project is licensed under the Apache License - see the LICENSE file for details