XMS API Reference

Table of Content

Document Overview

This document describes the REST API provided by the XLcloud Management System in detail. The REST API can be used to integrate applications with the XMS.

General conventions used throughout the API are given in API Conventions. The Identity and Access Management section describes how the security of the API is managed. How private and public resources are managed is described in Resource Catalogs. Finally, a complete documentation of API methods is given in API Resources.

API Conventions

The patterns incorporated in XMS API follow the general rules of designing good RESTful API. All XMS API methods follow these conventions, which simplifies the use of the service.

General URI Format

The general URI format follows the pattern described below:

{uri_base}/{entity_reference}?{query_parameters}

where:

  • uri_base – root context of XMS API implementation system, composed of host and port of application server running XMS, followed by XMS application's context root. Typical example would be https://localhost:8443/xlcloud-xms.
  • entity_reference – the main part of the REST request URI
  • query_parameters – additional, optional query parameters used to filter query results

Entity Reference Notation

Entity reference notation follows the general rules specified for RESTful APIs:

  • entities are always represented as plural nouns in URI (e.g. accounts, users, stacks etc.)
  • entities can be pointed in URIs as:
    • collections: when no identifier is specified after entity noun (i.e. GET accounts returns a list of accounts)
    • item details: when the identifier is explicitly specified (i.e. GET accounts/123 will return details of account with reference id 123)
  • URI simplification approach was used to build resource URIs – each entity or collection is being addressed with the minimal group of nouns necessary to address it. In most cases, only one identifier is necessary and maximum of two entity nouns. For example, if the user wants to list all stacks belonging to the account with an identifier 123, he will call GET accounts/123/stacks. Supposing one of the stacks returned in this list has identifier 124, there is no need to specify the account/{account_id} part in the next call – user can adress the stack directly through GET stacks/124 instead of full GET accounts/123/stacks/124. Some of the methods, however, don't follow this convention, these are:
    • methods that create relationship between two existing entities. Let's take adding a user with an identifier 125 to a project 126 as an example - in this case PUT projects/126/users/125should be called 
    • methods that target entities that don't have global identifiers, like GET users/125/entitlements/1

HTTP Methods

Unless stated differently in specific operation details, XMS API fully supports four standard HTTP methods (GET, PUT, POST, DELETE). The exact list of HTTP methods supported for specific URIs can be found later in the document.

XMS API utilizes HTTP methods according to RFC 2616. The most important rules are:

  • GET method calls never have server-side side effects, hence the results can be cached on the client site (see Headers for more details)
  • GET, PUT and DELETE are idempotent, meaning that multiple identical calls of these method always return the same result

Headers

Headers utilized by the XMS are as follows.

Header

Allowed Values

Required

Description

Content-Type

application/json
application/xml

required if the request contains a bodyDescribes the data format of the request body. XMS API supports JSON and XML data formats. However, JSON is the default data format and should be used whenever possible. Both the XMS-SDK and CLI use JSON for communication.
Accept

application/json
application/xml

optionalDescribes the data format of the response body. If this header is not specified, the response body will be returned as a JSON.
AuthorizationBearer {access_token}requiredDefines the access token to be used for authorization. The {access_token}part is to be replaced by an actual access token. Between the Bearer part and the access token part there is a single space.

HTTP Status Codes

XMS API utilizes HTTP status code to provide response status to end users. When an error occurs, the system will return an HTTP error response code denoting the type of error. The system will also return additional information about the fault in the body of the response. The error code is returned in the body of the response for convenience. The "message" field contains a human-readable message that is appropriate for display to end users. The "type" field contains identifier of the specific exception type. Depending on the exception type there may be additional fields which are described in the table below.

exception type there may be additional fields which are described in the table below.

Response Code

Type ID

Exception Class

Status/Exception Description

Additional fields

200 N/AOK 
204 N/ANo Content 
400validationValidationException

Exception thrown when the request does not meet specified requirements

(for example tries to create an account without specifying its name).

validationFailure – ID of the reason of the exception

invalidField – specific ID of the field/object

401authenticationAuthenticateExceptionException thrown when the authorization header is invalid or is not passed in request header.authenticationFailure – ID of the reason of the exception
403forbiddenForbiddenException

Exception thrown when the request is authenticated in XMS (meaning that authorization token is correct)

but does not have appropriate entitlements necessary to perform specific action.

forbiddenAction – specific reason of the exception

method – HTTP method that user is forbidden from

resource – resource path that user is forbidden from

reason – one of: DENIAL, RESTRICTION, ERROR

403quotaQuotaExceptionException thrown when the request cannot be processed because of reaching the quota limit.resource – the resource that is under quota
404object_not_foundObjectNotFoundExceptionException thrown when the user tries to perform an action on an entity that does not exist.

objectType – type of the object missing

objectId – ID of the missing object

409duplicatedDuplicatedEntityExceptionException thrown when the user tries to create an entity with a name or other unique property that already exists.

entityType – type of the duplicated entity

entityId – name or ID of conflicted entity

500internalInternalErrorExceptionException thrown when the application meets an unexpected condition that prevents it it from fulfilling the request.

stackTrace – stack trace (if configured)

errorType – ID of specific error

The normal response code is 200, except when no content is returned, in which case the response code is 204.

WADL

The WADL (Web Application Description Language) document is available at application.wadl (e.g. http://localhost:8080/xlcloud-xms/application.wadl). It is a machine-readable XML file containing the description of the XMS API. It can be especially useful if you choose to communicate with XMS using XML content type, as the document defines XSD schemas of all the entities. A human-readable form is also available at application.wadl?type=html.

Identity and Access Management

An important part of the XLcloud platform is the central Identity and Access Management Service which is also responsible for access management of the API. Each API call is secured using the OAuth2 protocol, and requires an access token to be passed in every request to the API. This prevents non-authorized users from interacting with the API. Note that tokens are valid only for a certain configurable period of time, after which they will be automatically revoked. 

Access Token

Each user has to generate his own access tokens to use in the XLcloud platform. Each token has associated with it a list of entitlements allowing the user to perform actions within the platform. There are two types of access tokens:

  • token scoped – when you authenticate with such token, you only have entitlements assigned to the token, newly created token-scoped access tokens have no entitlements
  • user scoped – you have both your entitlements (user entitlements and entitlements from groups you belong to) and that of the access token

It's possible to modify entitlements associated with access tokens (and also users and groups), but note that users cannot assign entitlements higher than the ones they possess. Moreover, when a user loses certain entitlements, which he assigned to the access token, that access token also loses that entitlements. 

Create Access Token

To be able to generate an access token, the application that wants to use the API must be registered inside the XLcloud central Identity and Access Management Service as an OAuth2 client. An example of such an application is the XLcloud Management Service Web Console, which is allowed to generate access tokens. When the client is configured properly it is possible to generate new access token, using the OAuth2 flow.

User has to be redirected to the IAM with the request:

GET /openam/oauth2/authorize?realm=xlc&response_type=code&client_id={client_id}&scope={scope}&redirect_uri={redirect_uri}

Where has to authenticate inside the XLcloud IAM. If user clicks "Allow", he will be redirected to the service defined in the redirect_uri parameter with the authorization code.

It is possible for the client application to retrieve the access token based on the authorization code invoking the IAM API:

POST /openam/oauth2/access_token
realm=xlc&grant_type=authorization_code&code={authorization_code}&client_id={client_id}&client_secret=

IAM response contains the access token which can be used to call XMS API methods:

{
  "expires_in": 5999999,
  "token_type": "Bearer",
  "access_token": "{access_token}"
}

Cloud Catalogs

Some entities are grouped into catalogs. XMS defines the following cloud catalogs:

  • cloud images – disk images used when creating instances
  • cookbook repositories – repositories contain cookbooks that can be used in the stack lifecycle
  • stack blueprints – prepared blueprints, that allow the user to create whole stacks based on them
  • layer blueprints – prepared blueprints, that allow the user to add to a stack new layers based on those blueprints

There are two types of catalogs: public and private. Public catalogs are managed by platform administrators, and the resources contained therein are accessible to all XMS users. Private catalogs are account-scoped, and their resources are visible only to the members of the particular account.

API Resources

Following sections describe possible operations on each individual entity. For every operation any requirements are given (including necessary entitlements), and example request and response in JSON are included.

Accounts

Account represents an institution, team, or any group of people that want share their work with the cloud resources – stacks and projects. Accounts are charged for the billable resource hours of compute, storage, and network allocated to an account in the context of a stack, and also possibly for the added-value services that are consumed by the users of the account. An account provides privacy and isolation from the rest of the world – users, groups, and stacks are managed within the context of an account. Users belonging to a specific account cannot interact with other accounts in any way. Accounts can also have private cloud catalogs (images, stack blueprints, etc.). Accounts can be created by a platform administrator and are managed and supervised by account administrators, who can grant entitlements to the account members.

Accounts have the following fields:

  • id – unique identifier
  • name – name of the account
  • osProjectId – unique identifier of the associated project in Keystone
  • users – list of account members
  • projects – list of the projects in the account

Create Account

Creates a new account.

Resource: POST accounts

Entitlement: POST accounts

Required Fields:

  • name – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter

Error Response Codes:

  • 409 – an account with the same name already exists

Example Request: POST http://localhost:8080/xlcloud-xms/accounts

{
  "name": "my_account"
}
Example Response: 200

{
  "id": 218,
  "href": "accounts/218",
  "name": "my_account",
  "osProjectId": "ad37a228ed754f6891ffb8c17c5616b0"
}

Get Account Details

Gets the details of the account, including its users and project.

Resource: GET accounts/{account_id}

Entitlement: GET accounts/{account_id}

Error Response Codes:

  • 404 – account not found

Example Request: GET http://localhost:8080/xlcloud-xms/accounts/161

Example Response: 200

{
  "projects": {
    "project": [
      {
        "id": 281,
        "href": "projects/281",
        "name": "my_project",
        "accountId": 161,
        "osProjectId": "7b4edd2aa81b4dbd991a333d604fff8f",
        "status": "active"
      }
    ]
  },
  "users": {
    "user": [
      {
        "id": 278,
        "href": "users/278",
        "username": "my_user",
        "accountId": 161,
        "osUserId": "d7f57023ff084daabc64888eb0ddb66e"
      }
    ]
  },
  "id": 161,
  "href": "accounts/161",
  "name": "my_account",
  "osProjectId": "2fd4bd57c5c74a06a7b40bfeb96c9498"
}

List Accounts

Gets the list of accounts.

Resource: GET accounts

Entitlement: GET accounts

Example Request: GET http://localhost:8080/xlcloud-xms/accounts

Example Response: 200

{
  "account": [
    {
      "id": 218,
      "href": "accounts/218",
      "name": "some_account",
      "osProjectId": "ad37a228ed754f6891ffb8c17c5616b0"
    },
    {
      "id": 161,
      "href": "accounts/161",
      "name": "my_account",
      "osProjectId": "2fd4bd57c5c74a06a7b40bfeb96c9498"
    },
    {
      "id": 100,
      "href": "accounts/100",
      "name": "kaef_account",
      "osProjectId": "0759586d9e9e4f0cbffd15812a02b14f"
    }
  ],
  "href": "/accounts"
}

Delete Account

Gets the list of accounts. Account cannot be removed if it has any users or projects.

Resource: DELETE accounts/{account_id}

Entitlement: DELETE accounts/{account_id}

Example Request: DELETE http://localhost:8080/xlcloud-xms/accounts/161

Example Response: 204

(no content)

Users

The user is the digital representation of a person or an application who uses the services of the system. The authentication service will validate that incoming request are being made by the user who claims to be making the call. Users have a login, and may be assigned tokens to access resources. Users may be directly assigned to a particular account (account members), or be platform administrators. Users can be assigned to groups which determine their privileges. Additionally, entitlements can be assigned directly to individual users

Platform administrators do not belong to any account, and they have most of the privileges. In particular, they can manage accounts. However, they are not allowed to manage stack sessions, nor to create or delete projects. Account members, on the other hand, can create projects and start stacks, provided that they have appropriate entitlements.

Newly created account members have default entitlements:

  • GET,POST,PUT,DELETE,HEAD,OPTIONS,PATCH accounts/{account_id}/users/{user_id}/*
  • GET,PUT accounts/{account_id}/users/{user_id}

Users have the following properties:

  • id – unique identifier
  • username – name of the user
  • password – password the user will use to log in into XMS, the password is never returned in any response
  • accountId – identifier of the account the user belongs to, if he is not a platform administrator
  • osUserId – unique identifier of the associated user in Keystone

Create Platform Administrator

Creates a new platform administrator.

Resource: POST users

Entitlement: POST users

Required Fields:

  • username – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter
  • password – must be between 8 and 20 characters long

Error Response Codes:

  • 409 – a user with the same name already exists

Example Request: POST http://localhost:8080/xlcloud-xms/accounts

{
  "username": "my_user",
  "password": "my_password"
}

Example Response: 200

{
  "id": 340,
  "href": "users/340",
  "username": "my_user",
  "osUserId": "7e44b88343494c0db761012394ca0a32"
}

Create Account Member

Creates a new account member.

Resource: POST accounts/{account_id}/users

Entitlement: POST accounts/{account_id}/users

Required Fields:

  • username – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter
  • password – must be between 8 and 20 characters long

Error Response Codes:

  • 404 – account not found
  • 409 – a user with the same name already exists

Example Request: POST http://localhost:8080/xlcloud-xms/accounts/161/users

{
  "username": "my_user",
  "password": "my_password"
}

Example Response: 200

{
  "id": 341,
  "href": "users/341",
  "username": "my_user",
  "accountId": 161,
  "osUserId": "303722b8a7bc449ba8988a11c3e439b7"
}

Create Group Member

Creates a new account member, and automatically assigns them to a group. The account they will be a member of will be the account that group is in.

Resource: POST groups/{group_id}/users

Entitlement: POST accounts/{account_id}/groups/{group_id}/users

Required Fields:

  • username – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter
  • password – must be between 8 and 20 characters long

Error Response Codes:

  • 404 – group not found
  • 409 – a user with the same name already exists

Example Request: POST http://localhost:8080/xlcloud-xms/groups/455/users

{
  "username": "my_user2",
  "password": "my_password"
}

Example Response: 200

{
  "id": 724,
  "href": "users/724",
  "username": "my_user2",
  "accountId": 100,
  "osUserId": "c08b224b9d9f40d29bff0e4a48f8eac0"
}

Create Project Member

Creates a new account member, and automatically assigns them to a project. The account they will be a member of will be the account that project is in.

Resource: POST projects/{project_id}/users

Entitlement: POST accounts/{account_id}/projects/{project_id}/users

Required Fields:

  • username – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter
  • password – must be between 8 and 20 characters long

Error Response Codes:

  • 404 – project not found
  • 409 – a user with the same name already exists

Example Request: POST http://localhost:8080/xlcloud-xms/projects/738/users

{
  "username": "my_user123",
  "password": "my_password"
}

Example Response: 200

{
  "id": 740,
  "href": "users/740",
  "username": "my_user123",
  "accountId": 100,
  "osUserId": "818ae19cc4634a77bd15bd913093704b"
}

Get User Details

Gets the details of a specified user.

Resource: GET users/{user_id}

Entitlement: GET users/{user_id}

Error Response Codes:

  • 404 – user not found

Example Request: GET http://localhost:8080/xlcloud-xms/users/344

Example Response: 200

{
  "id": 344,
  "href": "users/344",
  "username": "my_user3",
  "accountId": 161,
  "osUserId": "2700171abeb548e2b31612de90d12382"
}

List All Users

Lists all platform administrators and members of all accounts.

Resource: GET users

Entitlement: GET users

Example Request: GET http://localhost:8080/xlcloud-xms/users

Example Response: 200

{
  "user": [
    {
      "id": 344,
      "href": "users/344",
      "username": "my_user3",
      "accountId": 161,
      "osUserId": "2700171abeb548e2b31612de90d12382"
    },
    {
      "id": 1,
      "href": "users/1",
      "username": "xlcadmin",
      "osUserId": "8dd91034234644118f05cc987db8ed63"
    },
    {
      "id": 341,
      "href": "users/341",
      "username": "my_user2",
      "accountId": 161,
      "osUserId": "303722b8a7bc449ba8988a11c3e439b7"
    },
    {
      "id": 275,
      "href": "users/275",
      "username": "kaef2",
      "accountId": 100,
      "osUserId": "621081638086445db51a968def24d092"
    }
  ],
  "href": "/users"
}

List Account Members

Lists all members of a specified account.

Resource: GET accounts/{account_id}/users

Entitlement: GET accounts/{account_id}/users

Error Response Codes:

  • 404 – account not found

Example Request: GET http://localhost:8080/xlcloud-xms/accounts/161/users

Example Response: 200

{
  "user": [
    {
      "id": 344,
      "href": "users/344",
      "username": "my_user3",
      "accountId": 161,
      "osUserId": "2700171abeb548e2b31612de90d12382"
    },
    {
      "id": 341,
      "href": "users/341",
      "username": "my_user2",
      "accountId": 161,
      "osUserId": "303722b8a7bc449ba8988a11c3e439b7"
    }
  ],
  "href": "/accounts/161/users"
}

List Group Members

Lists all members of a specified group.

Resource: GET groups/{group_id}/users

Entitlement: GET accounts/{account_id}/groups/{group_id}/users

Error Response Codes:

  • 404 – group not found

Example Request: GET http://localhost:8080/xlcloud-xms/groups/162/users 

Example Response: 200

{
  "user": [
    {
      "id": 341,
      "href": "users/341",
      "username": "my_user2",
      "accountId": 161,
      "osUserId": "303722b8a7bc449ba8988a11c3e439b7"
    }
  ],
  "href": "/groups/162/users"
}

List Project Members

Lists all members of a specified project.

Resource: GET projects/{project_id}/users

Entitlement: GET accounts/{account_id}/projects/{project_id}/users

Error Response Codes:

  • 404 – project not found

Example Request: GET http://localhost:8080/xlcloud-xms/projects/1828/users

Example Response: 200

{
  "user": [
    {
      "id": 1822,
      "href": "users/1822",
      "username": "kaef",
      "accountId": 1765,
      "osUserId": "3af9182ac1014c189d37d88b17eab722"
    },
    {
      "id": 1961,
      "href": "users/1961",
      "username": "my_user",
      "accountId": 1765,
      "osUserId": "8be5657f8f5142f68b84f19101672216"
    }
  ],
  "href": "/projects/1828/users"
}

Change User Password

Changes the password of a specified user.

Resource: PUT users/{user_id}

Entitlement:

  • to change the password of a platform administrator: PUT users/{user_id}
  • to change the password of an account member: PUT accounts/{account_id}/users/{user_id}

Required Fields:

  • password – must be between 8 and 20 characters long

Error Response Codes:

  • 404 – user not found

Example Request: GET http://localhost:8080/xlcloud-xms/users/353

{
  "password": "my_password"
}

Example Response: 200

{
  "id": 353,
  "href": "users/353",
  "username": "my_user",
  "osUserId": "fa4052f84c9d443bae32a203d39eb99e"
}

Delete User

Deletes a user.

Resource: DELETE users/{user_id}

Entitlement:

  • to delete a platform administrator: DELETE users/{user_id}
  • to delete an account member: DELETE accounts/{account_id}/users/{user_id}

Example Request: DELETE http://localhost:8080/xlcloud-xms/users/341

Example Response: 204

(no content)

Groups

Users can be assigned to various account-scoped groups. Groups define entitlements, and users assigned to a certain group gain all those entitlements. This makes groups a convenient way to define roles within the account, or to simply assign the same entitlements to a number of different users. ===

New accounts are created with three default groups:

  • admin – Account administrators group that allows to fully operate on account resources. It grants the following entitlements:
    GET accounts/{account_id}
    • GET,POST,PUT,DELETE,HEAD,OPTIONS,PATCH accounts/{account_id}/*
    • GET stack-blueprints
    • GET stack-blueprints/*
    • GET layer-blueprints
    • GET layer-blueprints/*
    • GET repositories
    • GET repositories/*
    • GET cookbooks
    • GET cookbooks/*
    • GET recipes
    • GET recipes/*
    • GET images
    • GET images/*
  • member – Account members group that allows to view account resources and public catalogs. It grants the following entitlements:GET accounts/{account_id}
    GET accounts/{account_id}/*
    • GET stack-blueprints
    • GET stack-blueprints/*
    • GET layer-blueprints
    • GET layer-blueprints/*
    • GET repositories
    • GET repositories/*
    • GET cookbooks
    • GET cookbooks/*
    • GET recipes
    • GET recipes/*
    • GET images
    • GET images/*
  • power – Account power users group that allows to manage stack lifecycles within the account. It grants the following entitlements:GET accounts/{account_id}
    GET accounts/{account_id}/*
    • POST accounts/{account_id}/stacks
    • POST accounts/{account_id}/stacks/-*-/sessions
    • DELETE accounts/{account_id}/stacks/-*-/sessions/-*-
    • POST accounts/{account_id}/projects/-*-/stacks
    • DELETE accounts/{account_id}/projects/-*-/stacks/-*-
    • PUT accounts/{account_id}/projects/-*-/stacks/-*-/parameters
    • POST accounts/{account_id}/projects/-*-/stacks/-*-/sessions
    • DELETE accounts/{account_id}/projects/-*-/stacks/-*-/sessions/-*-
    • POST accounts/{account_id}/stack-blueprints
    • PUT,DELETE accounts/{account_id}/stack-blueprints/-*-
    • GET stack-blueprints
    • GET stack-blueprints/*
    • GET layer-blueprints
    • GET layer-blueprints/*
    • GET repositories
    • GET repositories/*
    • GET cookbooks
    • GET cookbooks/*
    • GET recipes
    • GET recipes/*
    • GET images
    • GET images/*

Groups have the following fields:

  • id – unique identifier
  • name – name of the group
  • description – arbitrary description of this group
  • accountId – identifier of the account this group belongs to
  • users – list of users assigned to this group

Create Group

Creates a new group. If the list of users is given, they will be automatically assigned to this group.

Resource: POST accounts/{account_id}/groups

Entitlement: POST accounts/{account_id}/groups

Required Fields:

  • name – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter

Error Response Codes:

  • 400 – users in the list belong to a different account
  • 404 – account not found, user in the list not found
  • 409 – a group with the same name already exists in the same account

Example Request: POST http://localhost:8080/xlcloud-xms/accounts/100/groups

{
  "name": "my_group2",
  "description": "The description of this group.",
  "users": {
    "user": [
      {
        "id": 344
      }
    ]
  }
}

Example Response: 200

{
  "users": {
    "user": [
      {
        "id": 344,
        "href": "users/344",
        "username": "my_user3",
        "accountId": 161,
        "osUserId": "2700171abeb548e2b31612de90d12382"
      }
    ]
  },
  "id": 485,
  "href": "groups/485",
  "name": "my_group2",
  "description": "The description of this group.",
  "accountId": 161
}

Get Group Details

Gets the details of a specified group.

Resource: GET groups/{group_id}

Entitlement: GET accounts/{account_id}/groups/{group_id}

Error Response Codes:

  • 404 – group not found

Example Request: GET http://localhost:8080/xlcloud-xms/groups/116

Example Response: 200

{
  "users": {
    "user": [
      {
        "id": 275,
        "href": "users/275",
        "username": "my_user2",
        "accountId": 100,
        "osUserId": "621081638086445db51a968def24d092"
      },
      {
        "id": 157,
        "href": "users/157",
        "username": "my_user",
        "accountId": 100,
        "osUserId": "3f21332a57e34984a59230d4b4692280"
      }
    ]
  },
  "id": 116,
  "href": "groups/116",
  "name": "member",
  "description": "Account members group that allows to view account resources and public catalogs.",
  "accountId": 100
}

List Account Groups

Lists all groups in a specified account.

Resource: GET accounts/{account_id}/groups

Entitlement: GET accounts/{account_id}/groups

Error Response Codes:

  • 404 – account not found

Example Request: GET http://localhost:8080/xlcloud-xms/accounts/100/groups

Example Response: 200

{
  "group": [
    {
      "users": {
        "user": []
      },
      "id": 116,
      "href": "groups/116",
      "name": "member",
      "description": "Account members group that allows to view account resources and public catalogs.",
      "accountId": 100
    },
    {
      "users": {
        "user": []
      },
      "id": 476,
      "href": "groups/476",
      "name": "my_group",
      "description": "The description of this group.",
      "accountId": 100
    },
    {
      "users": {
        "user": []
      },
      "id": 131,
      "href": "groups/131",
      "name": "power",
      "description": "Account power users group that allows to manage stacks lifecycle in context of account.",
      "accountId": 100
    },
    {
      "users": {
        "user": []
      },
      "id": 101,
      "href": "groups/101",
      "name": "admin",
      "description": "Account administrators group that allows to fully operate on account resources.",
      "accountId": 100
    }
  ],
  "href": "/accounts/100/groups"
}

List User Groups

Lists all groups a specified user is assigned to.

Resource: GET users/{user_id}/groups

Entitlement: GET accounts/{account_id}/users/{user_id}/groups

Error Response Codes:

  • 404 – user not found

Example Request: GET http://localhost:8080/xlcloud-xms/users/344/groups

Example Response: 200

{
  "group": [
    {
      "users": {
        "user": []
      },
      "id": 485,
      "href": "groups/485",
      "name": "my_group2",
      "description": "The description of this group.",
      "accountId": 161
    }
  ],
  "href": "/users/344/groups"
}

Assign User to Group

Assigns a user to a group. The user will gain entitlements of the group.

Resource: PUT groups/{group_id}/users/{user_id}

Entitlement: PUT accounts/{account_id}/groups/{group_id}/users/{user_id}

Error Response Codes:

  • 400 – the user is a platform administrator
  • 404 – group not found, user not found

Example Request: PUT http://localhost:8080/xlcloud-xms/groups/485/users/344

Example Response: 204

(no content)

Remove User from Group

Removes a user from a group. The user will lose the entitlements of the group, but will not be deleted.

Resource: DELETE groups/{group_id}/users/{user_id}

Entitlement: DELETE accounts/{account_id}/groups/{group_id}/users/{user_id}

Error Response Codes:

  • 404 – group not found, user not found

Example Request: DELETE http://localhost:8080/xlcloud-xms/groups/485/users/344

Example Response: 204

(no content)

Delete Group

Deletes a group. This causes all users assigned to the group to lose appropriate entitlements, but the users themselves are not deleted.

Resource: DELETE groups/{group_id}

Entitlement: DELETE accounts/{account_id}/groups/{group_id}

Example Request: DELETE http://localhost:8080/xlcloud-xms/groups/116

Example Response: 204

(no content)

Access Tokens

Access tokens are used to authenticate the user in XMS. Access tokens can have entitlements associated with them, and a user authenticating with such token gains those entitlements. There are two types of access tokens: ===

  • token scoped – when you authenticate with such token, you only have entitlements assigned to the token, newly created token-scoped access tokens have no entitlements
  • user scoped – you have both your entitlements (user entitlements and entitlements from groups you belong to) and that of the access token

Access tokens cannot be created using the XMS API.

Access tokens have the following fields:

  • token – actual access token
  • userId – identified of the user this token belongs to
  • scope – type of this token, either "userScoped" or "tokenScoped"
  • expiryTime – date when this token expires, given in milliseconds since January 1, 1970, 00:00:00 GMT

Get Access Token Details

Gets the details of a access token.

Resource: GET access-tokens/{access_token}

Entitlement:

  • to get the details of a platform administrator's access token: GET users/{user_id}/access-tokens/{access_token}
  • to get the details of an account member's access token: GET accounts/{account_id}/users/{user_id}/access-tokens/{access_token}

Error Response Codes:

  • 404 – access token not found

Example Request: GET http://localhost:8080/xlcloud-xms/access-tokens/1b5c445d-4e4a-4d18-a90f-696b72a20765

Example Response: 200

{
  "userId": 1,
  "token": "1b5c445d-4e4a-4d18-a90f-696b72a20765",
  "scope": "userScoped",
  "expiryTime": 1398658431929
}

List User Access Tokens

Lists all access tokens belonging to a specified user.

Resource: GET users/{user_id}/access-tokens

Entitlement:

  • to list access tokens of a platform administrator: GET users/{user_id}/access-tokens
  • to list access tokens of an account member: GET accounts/{account_id}/users/{user_id}/access-tokens

Error Response Codes:

  • 404 – user not found

Example Request: GET http://localhost:8080/xlcloud-xms/users/1/access-tokens

Example Response: 200

{
  "accessToken": [
    {
      "userId": 1,
      "token": "59160b7b-4688-48dd-8a02-91a632d7f8d1",
      "scope": "tokenScoped",
      "expiryTime": 1398658496168
    },
    {
      "userId": 1,
      "token": "af2b79eb-ce23-4643-8281-94fa7df8359b",
      "scope": "userScoped",
      "expiryTime": 1398672581771
    },
    {
      "userId": 1,
      "token": "1b5c445d-4e4a-4d18-a90f-696b72a20765",
      "scope": "userScoped",
      "expiryTime": 1398658431929
    }
  ],
  "href": "/users/1/access-tokens"
}

Revoke Access Token

Revokes an access token. It will no longer be possible to authenticate using that token.

Resource: DELETE access-tokens/{access_token}

Entitlement:

  • to revoke a platform administrator's access token: DELETE users/{user_id}/access-tokens/{access_token}
  • to revoke an account member's access token: DELETE accounts/{account_id}/users/{user_id}/access-tokens/{access_token}

Example Request: DELETE http://localhost:8080/xlcloud-xms/access-tokens/04da48d5-0ee5-4c37-b4f2-d78168fcb70f

Example Response: 204

(no content)

Entitlements

Entitlements define what a user is allowed to do. Whenever the user tries to perform an operation he is not allowed to, a response with status "403 forbidden" is returned. Entitlements can be assigned to users, access tokens, and groups. Entitlements are associated with the HTTP method(s) and a path. For example:

GET,POST accounts/{account_id}/users

It is possible to use wildcards in the path. Two types of wildcards are available:

  • *– represents any text, e.g. the following entitlement grants access to all operations on an account: accounts*
  • -*- – represents any text without the slash symbol. e.g. the following entitlement grants access to the projects of all accounts: accounts/-*-/projects*

It is not allowed to create entitlements that contain two or more subsequent -*- wildcards separated by a slash, like: account/-*-/-*-/123.

Entitlements have the following properties:

  • id – unique identifier
  • action – list of HTTP actions
  • resource – resource this entitlement grants access to

Create User Entitlement

Assigns a new entitlement to a user.

Resource: POST users/{user_id}/entitlements

Entitlement:

  • to create an entitlement for a platform administrator: POST users/{user_id}/entitlements
  • to create an entitlement for an account member: POST accounts/{account_id}/users/{user_id}/entitlements

Required Fields:

  • resource – must be a valid entitlement
  • action – the list cannot be empty

Error Response Codes:

  • 404 – user not found
  • 409 – another rule with same values already exists

Example Request: POST http://localhost:8080/xlcloud-xms/users/344/entitlements

{
  "resource": "accounts/161/*",
  "action": [
    "GET",
    "POST"
  ]
}

Example Response: 200

{
  "resource": "accounts/161/*",
  "action": [
    "POST",
    "GET"
  ],
  "id": 375
}

List User Entitlements

Lists all entitlements assigned to a user.

Resource: GET users/{user_id}/entitlements

Entitlement:

  • to create an entitlement for a platform administrator: GET users/{user_id}/entitlements
  • to create an entitlement for an account member: GET accounts/{account_id}/users/{user_id}/entitlements

Error Response Codes:

  • 404 – user not found

Example Request: GET http://localhost:8080/xlcloud-xms/users/344/entitlements

Example Response: 200

{
  "entitlement": [
    {
      "resource": "accounts/161/users/344/*",
      "action": [
        "POST",
        "GET",
        "PUT",
        "DELETE",
        "HEAD",
        "OPTIONS",
        "PATCH"
      ],
      "id": 345
    },
    {
      "resource": "accounts/161/users/344",
      "action": [
        "GET",
        "PUT"
      ],
      "id": 346
    }
  ],
  "href": "/users/344/entitlements"
}

Edit User Entitlements

Replaces all entitlements assigned to a user.

Resource: PUT users/{user_id}/entitlements

Entitlement:

  • to create an entitlement for a platform administrator: PUT users/{user_id}/entitlements
  • to create an entitlement for an account member: PUT accounts/{account_id}/users/{user_id}/entitlements

Required Fields:

  • entitlement – the list can be empty (all entitlements will be removed)
    • resource – must be a valid entitlement
    • action – the list cannot be empty

Error Response Codes:

  • 404 – user not found

Example Request: PUT http://localhost:8080/xlcloud-xms/users/344/entitlements

{
  "entitlement": [
    {
      "resource": "accounts/161/users/344/*",
      "action": [
        "POST",
        "GET",
        "PUT",
        "DELETE",
        "HEAD",
        "OPTIONS",
        "PATCH"
      ]
    },
    {
      "resource": "accounts/161/users/344",
      "action": [
        "GET",
        "PUT",
        "DELETE"
      ]
    }
  ]
}

Example Response: 200

{
  "entitlement": [
    {
      "resource": "accounts/161/users/344/*",
      "action": [
        "POST",
        "GET",
        "PUT",
        "DELETE",
        "HEAD",
        "OPTIONS",
        "PATCH"
      ],
      "id": 345
    },
    {
      "resource": "accounts/161/users/344",
      "action": [
        "GET",
        "PUT",
        "DELETE"
      ],
      "id": 346
    }
  ],
  "href": "/users/344/entitlements"
}

Delete User Entitlement

Deletes an entitlements assigned to a user.

Resource: DELETE users/{user_id}/entitlements/{entitlement_id}

Entitlement:

  • to delete an entitlement of a platform administrator: DELETE users/{user_id}/entitlements/{entitlement_id}
  • to delete an entitlement of an account member: DELETE accounts/{account_id}/users/{user_id}/entitlements/{entitlement_id}

Example Request: DELETE http://localhost:8080/xlcloud-xms/users/344/entitlements/375

Example Response: 204
(no content)

Create Group Entitlement

Assigns a new entitlement to a group.

Resource: POST groups/{group_id}/entitlements

Entitlement: to POST accounts/{account_id}/groups/{group_id}/entitlements

Required Fields:

  • resource – must be a valid entitlement
  • action – the list cannot be empty

Error Response Codes:

  • 404 – group not found
  • 409 – another rule with same values already exists

Example Request: POST http://localhost:8080/xlcloud-xms/groups/455/entitlements

{
  "resource": "accounts/161/users/344/*",
  "action": [
    "POST",
    "GET",
    "PUT",
    "DELETE",
    "HEAD",
    "OPTIONS",
    "PATCH"
  ]
}

Example Response: 204

{
  "resource": "accounts/161/users/344/*",
  "action": [
    "POST",
    "GET",
    "PUT",
    "DELETE",
    "HEAD",
    "OPTIONS",
    "PATCH"
  ],
  "id": 456
}

List Group Entitlements

Lists all entitlements assigned to a group.

Resource: GET groups/{group_id}/entitlements

Entitlement: GET accounts/{account_id}/groups/{group_id}/entitlements

Error Response Codes:

  • 404 – group not found

Example Request: GET http://localhost:8080/xlcloud-xms/groups/455/entitlements

Example Response: 200

{
  "entitlement": [
    {
      "resource": "accounts/161/users/344/*",
      "action": [
        "POST",
        "GET",
        "PUT",
        "DELETE",
        "HEAD",
        "OPTIONS",
        "PATCH"
      ],
      "id": 456
    }
  ],
  "href": "/groups/455/entitlements"
}

Edit Group Entitlements

replaces all entitlements assigned to a group.

Resource: PUT groups/{group_id}/entitlements

Entitlement: PUT accounts/{account_id}/groups/{group_id}/entitlements

Required Fields:

  • entitlement – the list can be empty (all entitlements will be removed)
    • resource – must be a valid entitlement
    • action – the list cannot be empty

Error Response Codes:

  • 404 – group not found

Example Request: PUT http://localhost:8080/xlcloud-xms/users/344/entitlements

{
  "entitlement": [
    {
      "resource": "accounts/161/users/344/*",
      "action": [
        "POST",
        "GET",
        "PUT",
        "DELETE",
        "HEAD",
        "OPTIONS",
        "PATCH"
      ],
      "id": 345
    },
    {
      "resource": "accounts/161/users/344",
      "action": [
        "GET",
        "PUT",
        "DELETE"
      ],
      "id": 346
    }
  ]
}

Example Response: 200

{
  "entitlement": [
    {
      "resource": "accounts/161/users/344/*",
      "action": [
        "POST",
        "GET",
        "PUT",
        "DELETE",
        "HEAD",
        "OPTIONS",
        "PATCH"
      ],
      "id": 457
    },
    {
      "resource": "accounts/161/users/344",
      "action": [
        "GET",
        "PUT",
        "DELETE"
      ],
      "id": 458
    }
  ],
  "href": "/groups/455/entitlements"
}

Delete Group Entitlement

Deletes an entitlements assigned to a group.

Resource: DELETE groups/{group_id}/entitlements/{entitlement_id}

Entitlement: DELETE accounts/{account_id}/groups/{group_id}/entitlements/{entitlement_id}

Example Request: DELETE http://localhost:8080/xlcloud-xms/groups/455/entitlements/458

Example Response: 204
(no content)

Create Access Token Entitlement

Assigns a new entitlement to an access token.

Resource: POST access-tokens/{access_token}/entitlements

Entitlement:

  • to create an entitlement for a platform administrator's access token: POST users/{user_id}/access-tokens/{access_token}/entitlements
  • to create an entitlement for an account member's access token: POST accounts/{account_id}/users/{user_id}/access-tokens/{access_token}/entitlements

Required Fields:

  • resource – must be a valid entitlement
  • action – the list cannot be empty

Error Response Codes:

  • 404 – access token not found,
  • 409 – another rule with same values already exists

Example Request: POST http://localhost:8080/xlcloud-xms/access-tokens/1b5c445d-4e4a-4d18-a90f-696b72a20765/entitlements

{
  "resource": "users/*",
  "action": [
    "POST",
    "GET",
    "PUT",
    "DELETE",
    "HEAD",
    "OPTIONS",
    "PATCH"
  ]
}

Example Response: 200

{
  "resource": "users/*",
  "action": [
    "POST",
    "GET",
    "PUT",
    "DELETE",
    "HEAD",
    "OPTIONS",
    "PATCH"
  ],
  "id": 460
}

List Access Token Entitlements

Lists all entitlements assigned to an access token.

Resource: GET access-tokens/{access_token}/entitlements

Entitlement:

  • to list entitlements of a platform administrator's access token: GET users/{user_id}/access-tokens/{access_token}/entitlements
  • to list entitlements of an account member's access token: GET accounts/{account_id}/users/{user_id}/access-tokens/{access_token}/entitlements

Error Response Codes:

  • 404 – access token not found

Example Request: GET http://localhost:8080/xlcloud-xms/access-tokens/1b5c445d-4e4a-4d18-a90f-696b72a20765/entitlements

Example Response: 200

{
  "entitlement": [
    {
      "resource": "users",
      "action": [
        "POST",
        "GET"
      ],
      "id": 462
    },
    {
      "resource": "users/*",
      "action": [
        "POST",
        "GET",
        "PUT",
        "DELETE",
        "HEAD",
        "OPTIONS",
        "PATCH"
      ],
      "id": 459
    }
  ],
  "href": "/access-tokens/1b5c445d-4e4a-4d18-a90f-696b72a20765/entitlements"
}

Edit Access Token Entitlements

Replaces all entitlements assigned to an access token.

Resource: PUT access-tokens/{access_token}/entitlements

Entitlement:

  • to edit entitlements of a platform administrator's access token: PUT users/{user_id}/access-tokens/{access_token}/entitlements
  • to edit entitlements of a platform administrator's access token: PUT accounts/{account_id}/users/{user_id}/access-tokens/{access_token}/entitlements

Required Fields:

  • entitlement – the list can be empty (all entitlements will be removed)
    • resource – must be a valid entitlement
    • action – the list cannot be empty

Error Response Codes:

*404 – access token not found

Example Request: PUT http://localhost:8080/xlcloud-xms/access-tokens/1b5c445d-4e4a-4d18-a90f-696b72a20765/entitlements

{
  "entitlement": [
    {
      "resource": "accounts",
      "action": [
        "POST",
        "GET",
        "PUT"
      ]
    }
  ]
}

Example Response: 200

{
  "entitlement": [
    {
      "resource": "accounts",
      "action": [
        "POST",
        "GET",
        "PUT"
      ],
      "id": 465
    }
  ],
  "href": "/access-tokens/1b5c445d-4e4a-4d18-a90f-696b72a20765/entitlements"
}

Delete Access Token Entitlement

Deletes an entitlements assigned to an access token.

Resource: DELETE access-tokens/{access_token}/entitlements/{entitlement_id}

Entitlement:

  • to delete an entitlement from a platform administrator's access token: DELETE users/{user_id}/access-tokens/{access_token}/entitlements/{entitlement_id}
  • to delete an entitlement from an account member's access token: DELETE accounts/{account_id}/users/{user_id}/access-tokens/{access_token}/entitlements/{entitlement_id}

Example Request: DELETE http://localhost:8080/xlcloud-xms/access-tokens/1b5c445d-4e4a-4d18-a90f-696b72a20765/entitlements/465

Example Response: 204
(no content)

Quotas

Quotas can restrict any account-scoped resources, limiting the number of resources of a given type in the account. Quotas can limit the following resource types:

  • users
  • stacks
  • stack blueprints
  • layer blueprints

When a new account is created, default quotas are created:

  • 10 users
  • 5 stacks
  • 5 stack blueprints
  • 5 layer blueprints

Quotas have the following fields:

  • type – type of the resource that is being limited, possible values are: "users", "stacks", "stack-blueprints", and "layer-blueprints"
  • limit – the limit imposed on the resource, maximum number of resources of the given type
  • usage – current number of resources of the given type

List Account Quotas

Lists all quotas in a specified account.

Resource: GET accounts/{account_id}/quotas

Entitlement: GET accounts/{account_id}/quotas

Error Response Codes:

  • 404 – account not found

Example Request: GET http://localhost:8080/xlcloud-xms/accounts/161/quotas

Example Response: 200

{
  "quota": [
    {
      "type": "users",
      "limit": 10,
      "usage": 2
    },
    {
      "type": "stacks",
      "limit": 5,
      "usage": 0
    },
    {
      "type": "stack-blueprints",
      "limit": 5,
      "usage": 0
    },
    {
      "type": "layer-blueprints",
      "limit": 5,
      "usage": 0
    }
  ]
}

Edit Quotas

Edits quotas in a specified account. The quotas specified in the request body get replaced. To remove the quota on a specified resource type, the limit field should be null, blank or omitted. It is possible to update the quota limit to a value below the current usage, and no resources will be deleted.

Resource: PUT accounts/{account_id}/quotas

Entitlement: PUT quotas

Required Fields:

  • type – must be a valid quota type

Error Response Codes:

  • 400 – quota limit is less than 0
  • 404 – account not found

Example Request: PUT http://localhost:8080/xlcloud-xms/accounts/161/quotas

{
  "quota": [
    {
      "type": "users",
      "limit": 20
    },
    {
      "type": "stacks"
    }
  ]
}

Example Response: 200

{
  "quota": [
    {
      "type": "users",
      "limit": 20,
      "usage": 2
    },
    {
      "type": "stacks",
      "usage": 0
    },
    {
      "type": "stack-blueprints",
      "limit": 5,
      "usage": 0
    },
    {
      "type": "layer-blueprints",
      "limit": 5,
      "usage": 0
    }
  ]
}

Restrictions

Restrictions represent complete, concise limitation of XMS functionality. They can limit the access to certain resources of all users in a given account, due to accounting reasons (e.g. exceeding account's funds or lack of payment). Restrictions resemble entitlements, except that they deny the access to certain resources, instead of allowing it.

Restrictions have the following fields:

  • id – unique identifier
  • name – name of this restriction, can have business meaning (e.g. "Creating users")
  • accountId – identifier of the account this restriction is imposed on
  • resources – list of restricted resources

    • resource – restricted resource path

    • action – actions that are restricted on this resource

Create Restriction

Creates a new restriction. It is possible to use predefined restriction types. Two types are available:

  • read-only – POST,DELETE,PUT *
  • full – GET,POST,DELETE,PUT *

If the "type" query param is used, the "resources" list should be empty or omitted.

Resource: POST accounts/{account_id}/restrictions?type={type}

Entitlement: POST restrictions

Required Fields:

  • resources – required if "type" query param is not used – list cannot be empty

    • resource – must be a valid resource path
    • action – list cannot be empty, elements must be valid HTTP actions

Error Response Codes:

  • 400 – if the "resources" list is not empty and the "type" query param is used
  • 404 – account not found

Example Request: POST http://localhost:8080/xlcloud-xms/accounts/100/restrictions

{
  "name": "Stack management restriction",
  "resources": [
    {
      "resource": "accounts/100/stacks/-*-/sessions",
      "action": [
        "DELETE",
        "PUT",
        "POST"
      ]
    },
    {
      "resource": "accounts/100/stacks",
      "action": [
        "POST"
      ]
    },
    {
      "resource": "accounts/100/stacks/-*-",
      "action": [
        "DELETE",
        "PUT"
      ]
    }
  ]
}

Example Response: 200

{
  "resources": [
    {
      "resource": "accounts/100/stacks/-*-",
      "action": [
        "PUT",
        "DELETE"
      ]
    },
    {
      "resource": "accounts/100/stacks",
      "action": [
        "POST"
      ]
    },
    {
      "resource": "accounts/100/stacks/-*-/sessions",
      "action": [
        "POST",
        "PUT",
        "DELETE"
      ]
    }
  ],
  "id": 492,
  "href": "restrictions/492",
  "accountId": 100,
  "name": "Stack management restriction"
}

Get Restriction Details

Gets the details of a specified restriction.

Resource: GET restrictions/{restriction_id}

Entitlement: GET accounts/{account_id}/restrictions/{restriction_id}

Error Response Codes:

  • 404 – restriction not found

Example Request: GET http://localhost:8080/xlcloud-xms/restrictions/721

Example Response: 200

{
  "resources": [
    {
      "resource": "accounts/100/stacks/-*-",
      "action": [
        "PUT",
        "DELETE"
      ]
    },
    {
      "resource": "accounts/100/stacks",
      "action": [
        "POST"
      ]
    },
    {
      "resource": "accounts/100/stacks/-*-/sessions",
      "action": [
        "POST",
        "PUT",
        "DELETE"
      ]
    }
  ],
  "id": 721,
  "href": "restrictions/721",
  "accountId": 100,
  "name": "Stack management restriction"
}

List All Restrictions

Lists all restrictions imposed on all accounts.

Resource: GET restrictions

Entitlement: GET restrictions

Example Request: GET http://localhost:8080/xlcloud-xms/restrictions

Example Response: 200

{
  "restriction": [
    {
      "id": 721,
      "href": "restrictions/721",
      "accountId": 100,
      "name": "Stack management restriction"
    },
    {
      "id": 722,
      "href": "restrictions/722",
      "accountId": 161,
      "name": "My restriction"
    },
    {
      "id": 723,
      "href": "restrictions/723",
      "accountId": 230,
      "name": "Full restriction"
    }
  ],
  "href": "/restrictions"
}

List Account Restrictions

Lists all restrictions imposed on a specified account.

Resource: GET accounts/{account_id}/restrictions

Entitlement: GET accounts/{account_id}/restrictions

Error Response Codes:

  • 404 – account not found

Example Request: GET http://localhost:8080/xlcloud-xms/accounts/100/restrictions

Example Response: 200

{
  "restriction": [
    {
      "resources": [
        {
          "resource": "accounts/100/stacks/-*-",
          "action": [
            "PUT",
            "DELETE"
          ]
        },
        {
          "resource": "accounts/100/stacks",
          "action": [
            "POST"
          ]
        },
        {
          "resource": "accounts/100/stacks/-*-/sessions",
          "action": [
            "POST",
            "PUT",
            "DELETE"
          ]
        }
      ],
      "id": 721,
      "href": "restrictions/721",
      "accountId": 100,
      "name": "Stack management restriction"
    }
  ],
  "href": "/accounts/100/restrictions"
}

Update Restriction

Replaces a restriction with the one specified in the request body.

Resource: PUT restrictions/{restriction_id}

Entitlement: PUT restrictions

Required Fields:

  • resources – list cannot be empty

    • resource – must be a valid resource path

    • action – list cannot be empty, elements must be valid HTTP actions

Error Response Codes:

  • 404 – restriction not found

Example Request: PUT http://localhost:8080/xlcloud-xms/restrictions/721

{
  "name": "New name",
  "resources": [
    {
      "resource": "accounts/100/stacks/-*-/sessions",
      "action": [
        "HEAD"
      ]
    }
  ]
}

Example Response: 200

{
  "resources": [
    {
      "resource": "accounts/100/stacks/-*-/sessions",
      "action": [
        "HEAD"
      ]
    }
  ],
  "id": 721,
  "href": "restrictions/721",
  "accountId": 100,
  "name": "New name"
}

Delete Restriction

Deletes a restriction.

Resource: DELETE restrictions/{restriction_id}

Entitlement: DELETE restrictions/{restriction_id}

Example Request: DELETE http://localhost:8080/xlcloud-xms/restrictions/499

Example Response: 204
(no content)

Projects

Projects provide an organizational structure within an account. Stacks and networks are created and managed within the context of a project. To be able to operate on stacks, you need to be a member of the particular project. Only account members can create and manage projects, provided that they have appropriate entitlements.

Projects are processed asynchronously, and hence can be in different states. Possible project states are:

  • "starting" – network configuration has been created, but the project broker is still starting
  • "active" – the project is active and fully operational
  • "failed" – an error occurred while starting the project, the project is unusable
  • "failed_to_delete" – an error occurred while deleting the project, the project is unusable

Note that it is not possible to delete a project that is starting.

Projects have the following fields:

  • id – unique identifier
  • name – name of the project
  • accountId – identifier of the account this project is in
  • osProjectId – unique identifier of the associated project in Keystone
  • status – current status of the project
  • statusReason – explanation of the current status, if the status is "failed" or "failed_to_delete"

Create Project

Creates a new project. The network configuration is created first, and then the project broker is started. By the time this method returns, the network configuration is guaranteed to be created, but the project broker will be still starting.

To create a project, you need to be a member of the account you are trying to create the project in. This means that platform administrators cannot create projects. The user creating the project will be automatically assigned to that project.

Only the project name is required. If no network configuration is specified, a default one will be created with one (default) subnet:

  • name: {project_name}_first_subnet
  • CIDR: 10.0.0.0/16

If a default subnet name is specified, but no list of subnets, a subnet will be created with that name. If the list of subnets is specified, but the default subnet name isn't, the first subnet on the list will become the default subnet.

Resource: POST accounts/{account_id}/projects

Entitlement: POST accounts/{account_id}/projects

Required Fields:

  • name – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter

Error Response Codes:

  • 400 – default subnet name is not present in the list of subnets, subnet CIDRs overlap, subnet names are not unique
  • 403 – you're not a member of the account
  • 404 – account not found
  • 409 – a project with the same name already exists (event in a different account)

Example Request: POST http://localhost:8080/xlcloud-xms/accounts/100/projects

{
  "name": "my_project",
  "projectEnvironment": {
    "networkConfiguration": {
      "defaultSubnetName": "my_project_first_subnet",
      "subnets": {
        "subnet": [
          {
            "name": "my_project_first_subnet",
            "cidr": "10.0.0.0/16"
          },
          {
            "name": "my_project_second_subnet",
            "cidr": "10.1.0.0/16"
          }
        ]
      }
    }
  }
}

Example Response: 200

{
  "projectEnvironment": {
    "networkConfiguration": {
      "subnets": {
        "subnet": [
          {
            "uuid": "4573e205-7bd7-4c2b-9452-acbe8ddac385",
            "name": "my_project_first_subnet",
            "cidr": "10.0.0.0/16"
          },
          {
            "uuid": "e2801caa-0360-4a58-9d6e-84999f9ab556",
            "name": "my_project_second_subnet",
            "cidr": "10.1.0.0/16"
          }
        ]
      },
      "defaultSubnetName": "my_project_first_subnet"
    }
  },
  "id": 735,
  "href": "projects/735",
  "name": "my_project",
  "accountId": 100,
  "osProjectId": "6b2bad11a2eb4cacb1a193368798257f",
  "status": "starting"
}

Get Project Details

Gets the details of a specified project.

Resource: GET projects/{project_id}

Entitlement: GET accounts/{account_id}/projects/{project_id}

Error Response Codes:

  • 404 – project not found

Example Request: GET http://localhost:8080/xlcloud-xms/projects/735

Example Response: 200

{
  "id": 735,
  "href": "projects/735",
  "name": "my_project",
  "accountId": 100,
  "osProjectId": "6b2bad11a2eb4cacb1a193368798257f",
  "status": "failed",
  "statusReason": "Project broker failed on starting due to unexpected status: failedOnStarting (Resource create failed: ClientException: The server has either erred or is incapable of performing the requested operation. (HTTP 500) (Request-ID: req-5a5c8f60-d1bf-4dd3-a528-4b780c3bb293))"
}

List All Projects

Lists all projects in all accounts.

Resource: GET projects

Entitlement: GET projects

Example Request: GET http://localhost:8080/xlcloud-xms/projects

Example Response: 200

{
  "project": [
    {
      "id": 733,
      "href": "projects/733",
      "name": "my_project125",
      "accountId": 100,
      "osProjectId": "26d26a50c66e49d08abe0e16489adbb0",
      "status": "active"
    },
    {
      "id": 726,
      "href": "projects/726",
      "name": "my_project2",
      "accountId": 100,
      "osProjectId": "090118b5684643d593ea11bc92f71af1",
      "status": "active"
    },
    {
      "id": 735,
      "href": "projects/735",
      "name": "my_project",
      "accountId": 100,
      "osProjectId": "6b2bad11a2eb4cacb1a193368798257f",
      "status": "deleting"
    }
  ],
  "href": "/projects"
}

List Account Projects

Lists all projects in a specified account.

Resource: GET accounts/{account_id}/projects

Entitlement: GET accounts/{account_id}/projects

Error Response Codes:

  • 404 – account not found

Example Request: GET http://localhost:8080/xlcloud-xms/accounts/100/projects

Example Response: 200

{
  "project": [
    {
      "id": 733,
      "href": "projects/733",
      "name": "my_project125",
      "accountId": 100,
      "osProjectId": "26d26a50c66e49d08abe0e16489adbb0",
      "status": "active"
    },
    {
      "id": 726,
      "href": "projects/726",
      "name": "my_project2",
      "accountId": 100,
      "osProjectId": "090118b5684643d593ea11bc92f71af1",
      "status": "active"
    }
  ],
  "href": "/accounts/100/projects"
}

List User Projects

Lists all projects a specified user is assigned to.

Resource: GET users/{user_id}/projects

Entitlement: GET accounts/{account_id}/users/{user_id}/projects

Error Response Codes:

  • 404 – user not found

Example Request: GET http://localhost:8080/xlcloud-xms/users/157/projects

Example Response: 200

{
  "project": [
    {
      "id": 733,
      "href": "projects/733",
      "name": "my_project125",
      "accountId": 100,
      "osProjectId": "26d26a50c66e49d08abe0e16489adbb0",
      "status": "active"
    },
    {
      "id": 726,
      "href": "projects/726",
      "name": "my_project2",
      "accountId": 100,
      "osProjectId": "090118b5684643d593ea11bc92f71af1",
      "status": "active"
    }
  ],
  "href": "/users/157/projects"
}

Assign User to Project

Assigns a user to a project. User must be an account member of the account the project is in.

Resource: PUT projects/{project_id}/users/{user_id}

Entitlement: PUT accounts/{account_id}/projects/{project_id}/users/{user_id}

Error Response Codes:

  • 400 – the user is not a member of the project account
  • 404 – project not found, user not found

Example Request: PUT http://localhost:8080/xlcloud-xms/projects/736/users/724

Example Response: 204

(no content)

Remove User from Project

Removed a user from a project. The user himself will not be deleted.

Resource: DELETE projects/{project_id}/users/{user_id}

Entitlement: DELETE accounts/{account_id}/projects/{project_id}/users/{user_id}

Error Response Codes:

  • 404 – project not found, user not found

Example Request: DELETE http://localhost:8080/xlcloud-xms/projects/736/users/724

Example Response: 204
(no content)

Delete Project

Deletes a project. This operation can only be done by users assigned to the project. In particular, platform administrator cannot delete a project. Note that the project is not deleted immediately. This method puts the project in "deleting" state. After the project broker is stopped, the network configuration is removed, and the project deleted.

Resource: DELETE groups/{group_id}

Entitlement: DELETE accounts/{account_id}/groups/{group_id}

Error Response Codes:

  • 400 – the project has status "starting"
  • 403 – you're not a member of the project

Example Request: DELETE http://localhost:8080/xlcloud-xms/projects/735

Example Response: 200

{
  "id": 735,
  "href": "projects/735",
  "name": "my_project",
  "accountId": 100,
  "osProjectId": "6b2bad11a2eb4cacb1a193368798257f",
  "status": "deleting"
}

{
  "id": 735,
  "href": "projects/735",
  "name": "my_project",
  "accountId": 100,
  "osProjectId": "6b2bad11a2eb4cacb1a193368798257f",
  "status": "deleting"
}

Subnets

Each project has at least one subnet associated with it. Subnets provide isolation and security. The IP range of a subnet is specified as a CIDR, e.g. 10.0.0.0/16. All projects have one subnet designated as default. When a stack is started, its instances are attached to the default subnet, except if this was changed for individual layers. Subnets that have instanced attached to them cannot be deleted. In particular, the project broker is attached to the subnet that was designated as default at the moment of creating the project.

To operate on subnets you need to be a member of the subnet project.

Subnets have the following fields:

  • uuid – unique identifier of the subnet in Neutron
  • name – name of the subnet
  • cidr – IP range of this subnet

Create Subnet

Creates a new subnet in a specified project. In order to perform this operation, the project must be active or starting.

Resource: POST projects/{project_id}/subnets

Entitlement: POST accounts/{account_id}/projects/{project_id}/subnets

Required Fields:

  • name – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter
  • cidr – must be a valid CIDR

Error Response Codes:

  • 400 – project status is "deleting", "failed" or "failed_to_delete"
  • 404 – project not found
  • 409 – subnet name is not unique within the project

Example Request: POST http://localhost:8080/xlcloud-xms/projects/736/subnets

{
  "name": "my_subnet",
  "cidr": "10.1.0.0/16"
}

Example Response: 200

{
  "users": {
    "user": [
      {
        "id": 344,
        "href": "users/344",
        "username": "my_user3",
        "accountId": 161,
        "osUserId": "2700171abeb548e2b31612de90d12382"
      }
    ]
  },
  "id": 485,
  "href": "groups/485",
  "name": "my_group2",
  "description": "The description of this group.",
  "accountId": 161
}

List Project Subnets

Lists all subnets in a specified project. Additionally, the default subnet name is returned.

Resource: GET projects/{project_id}/subnets

Entitlement: GET accounts/{account_id}/projects/{project_id}/subnets

Error Response Codes:

  • 404 – project not found

Example Request: GET http://localhost:8080/xlcloud-xms/projects/736/subnets

Example Response: 200

{
  "subnets": {
    "subnet": [
      {
        "uuid": "e2801caa-0360-4a58-9d6e-84999f9ab556",
        "name": "my_project667_first_subnet",
        "cidr": "10.0.0.0/16"
      }
    ]
  },
  "defaultSubnetName": "my_project667_first_subnet"
}

Choose Default Subnet

Chooses the default subnet.

Resource: PUT projects/{project_id}/subnets/default

Entitlement: PUT accounts/{account_id}/projects/{project_id}/subnets/default

Required Fields:

  • name

Error Response Codes:

  • 404 – project not found, subnet not found

Example Request: PUT http://localhost:8080/xlcloud-xms/projects/736/subnets/default

{
  "name": "my_net"
}

Example Response: 204
(no content)

Delete Subnet

Deletes a subnet. If there are any instances attached to the subnet, it will fail to delete. In particular, the default subnet will generally fail to be deleted, because the project broker is attached to it.

Resource: DELETE projects/{project_id}/subnets/{subnet_uuid}

Entitlement: DELETE accounts/{account_id}/projects/{project_id}/subnets/{subnet_uuid}

Example Request: DELETE http://localhost:8080/xlcloud-xms/projects/736/subnets/593a38bd-dd97-4dd6-afe4-f296db176411 

Example Response: 204

(no content)

Leases

Leases allows to reserve physical host for your own and make sure no other Stacks gonna be run using this host. Reservation is made for specified timeslot and user is allowed to specified how many resources he wants to reserve. Leases are strictly connected with the project and only project members are allowed to create new leases. Platform administrators are only allowed to modify existing entries including removing them.

Leases have the following fields:

  • id – unique identifier
  • name – name
  • startDate - start date of the reservation as Unix timestamp. Note that assigning this date you must concern
    about actual time on the server.
  • endDate - end date of the reservation as Unix timestamp.  Note that assigning this date you must concern
    about actual time on the server.
  • duration - duration in miliseconds of the lease.
  • projectId - project id with which lease is connected
  • status - status of the lease one of:  scheduled, active, finished, broken
  • reservation - list of physical host reservations

    • minSize - minimal size of the reservation

    • maxSize - maximum size of the reservation

    • size - current size of the reservation (not implemented yet)

    • hypervisorProperties - hypervisor properties which host must satisfy to be part of the reservation

    • resourceProperties  - resource properties which host must satisfy to be part of the reservation

Create Lease

Creates new reservation. When user does not specify the startDate lease will start just right now. User has to specify the either endDate of the reservation or duration in milliseconds, so system will count the endDate base on startDate. Leases can be created for project in not failed or deleted state.

Resource: POST projects/{project_id}/leases

Entitlement: POST accounts/{account_id}/projects/projects/{project_id}/leases

Required Fields:

  • name – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a
    letter
  • endDate or duration.
  • reservation – at least one reservation must be specified
    • minSize - greater then 1
    • maxSize greater then minSize

Error Response Codes:

  • 404 – project not found 
  • 403 – lease does not belong to specified project.
  • 400 - project has inappropriate status.

Example Request: POST http://localhost:8080/xlcloud-xms/projects/219/leases

{
    "duration": "600000",
    "startDate": 1396099800000,
    "name": "lease",
    "reservations": [
        {
            "minSize": "1",
            "maxSize": "1",
            "hypervisorProperties": "[\"=\", \"$hypervisor_type\", \"QEMU\"]"
        }
    ]

Example Response: 200

{
    "duration": 600000,
    "endDate": 1396100460000,
    "id": "ef4fbefa-bedb-4fcb-8625-dc2417e35bd5",
    "name": "lease895",
    "projectId": 219,
    "reservations": [
        {
            "maxSize": 1,
            "minSize": 1
        }
    ],
    "startDate": 1396099860000,
    "status": "scheduled"
}

Get Lease Details

Gets the details of a specified lease.

Resource: GET projects/{project_id}/leases/{lease_id}

Entitlement: GET accounts/{account_id}/projects/{project_id}/leases/{lease_id}

Error Response Codes:

  • 404 – lease not found
  • 403 - lease does not belong to project

Example Request: GET http://localhost:8080/xlcloud-xms/projects/219/leases/ef4fbefa-bedb-4fcb-8625-
dc2417e35bd5

Example Response: 200

{
  "duration": 600000,
  "endDate": 1396100460000,
  "id": "ef4fbefa-bedb-4fcb-8625-dc2417e35bd5",
  "name": "lease895",
  "projectId": 219,
  "reservations": [
    {
      "maxSize": 1,
      "minSize": 1
    }
  ],
  "startDate": 1396099860000,
  "status": "scheduled"
}

List All Leases

Lists all leases in all projects in all accounts

Resource: GET leases

Entitlement: GET leases

Example Request: GET http://localhost:8080/xlcloud-xms/leases

Example Response: 200

{
  "lease": [
    {
      "duration": 7200000,
      "endDate": 1396094580000,
      "id": "32c38b3f-1e61-492f-a95d-4e1a473af604",
      "name": "please123_h123",
      "projectId": 330,
      "reservations": [
        {
          "maxSize": 1,
          "minSize": 1
        }
      ],
      "startDate": 1396087380000,
      "status": "scheduled"
    },
    {
      "duration": 600000,
      "endDate": 1396100460000,
      "id": "ef4fbefa-bedb-4fcb-8625-dc2417e35bd5",
      "name": "lease",
      "projectId": 219,
      "reservations": [
        {
          "maxSize": 1,
          "minSize": 1
        }
      ],
      "startDate": 1396099860000,
      "status": "scheduled"
    }
  ]
}

List Project Leases

Lists project leases

Resource: GET projects/{project_id}/leases/

Entitlement: GET accounts/{account_id}/projects/{project_id}/leases/

Example Request: GET http://localhost:8080/xlcloud-xms/projects/219/leases

Example Response: 200

{
  "lease": [
    {
      "duration": 600000,
      "endDate": 1396100460000,
      "id": "ef4fbefa-bedb-4fcb-8625-dc2417e35bd5",
      "name": "lease",
      "projectId": 219,
      "reservations": [
        {
          "maxSize": 1,
          "minSize": 1
        }
      ],
      "startDate": 1396099860000,
      "status": "scheduled"
    }
  ]
}

Update Leases

Update lease. Only name, startDate and endDate of the lease can be updated. When user pass more properties they will be ignored.

Resource: PUT projects/{project_id}/leases/{lease_id}

Entitlement: PUT accounts/{account_id}/projects/{project_id}/leases/{lease_id}

Example Request: PUT http://localhost:8080/xlcloud-xms/leases/ef4fbefa-bedb-4fcb-8625-dc2417e35bd5

{
    "startDate": 1396099860000,
    "duration": "600000",
    "name": "lease123"
}

Example Response: 200

{
  "duration": 600000,
  "endDate": 1396100460000,
  "id": "ef4fbefa-bedb-4fcb-8625-dc2417e35bd5",
  "name": "lease895",
  "projectId": 219,
  "reservations": [
    {
      "maxSize": 1,
      "minSize": 1
    }
  ],
  "startDate": 1396099860000,
  "status": "scheduled"
}

Delete Lease

Removes lease

Resource: DELETE projects/{project_id}/leases/{lease_id}

Entitlement: DELETE accounts/{account_id}/projects/{project_id}/leases/{lease_id}

Error Response Codes:

  • 403 - lease does not belong to project

Example Request: DELETE http://localhost:8080/xlcloud-xms/projects/219/leases/ef4fbefa-bedb-4fcb-8625-dc2417e35bd5

Example Response: 204

 

OS Keypairs

Keypairs are used to allow the users to connect using SSH with stack instances. Keypairs are associated with users, and a single keypair can be used across multiple projects and stacks within the user's account. Note that only account members can create and use keypairs.

Keypairs have the following fields:

  • name – name of the key pair
  • privateKey – private key associated with this keypair, returned only when generating a key pair
  • publicKey – public key associated with this key pair
  • fingerprint – fingerprint of the public key

Import Keypair

Imports an already existing keypair. Keypair name can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter.

Resource: POST users/{user_id}/os-keypairs

Entitlement: POST accounts/{account_id}/users/{user_id}/os-keypairs

Required Fields:

  • name – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter
  • publicKey – must be a valid public key

Error Response Codes:

  • 404 – user not found
  • 409 – user already has a keypair with the same name

Example Request: POST http://localhost:8080/xlcloud-xms/users/157/os-keypairs

{
  "name": "my_keypair3",
  "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCvbRPbqGknlzjn3wuLWklC6AefJJDo7/ueACPuI3VTu0cLiT2J1pVfGfxEwd5QOmRUHodfFIQvpnpn+63OZAVjSzGL53et2mLNlxp4kBtMLZywXgG2nnHBZFHwiUyQ48pzBGAEbIrdd30iPeDwuuJTWv6MjJkD2PU706TTtscEG2plnVc/McFqvwAMpDcS5zsFNAlwHWbCZYUeqcZ3BoiANMz7erd0uQU5ZSG38DukpzwVntw2jpChrfdWLCLLiG9ZU59crNiP97mQ6v5uHIHBlvzwW9QUitSMZE4z5jx9WiZyYjPyDE6kYoAcY0rDkPqdE7/tEUfjShW5pnw7RqmB Generated by Nova
n"
}

Example Response: 200

{
  "name": "my_keypair3",
  "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCvbRPbqGknlzjn3wuLWklC6AefJJDo7/ueACPuI3VTu0cLiT2J1pVfGfxEwd5QOmRUHodfFIQvpnpn+63OZAVjSzGL53et2mLNlxp4kBtMLZywXgG2nnHBZFHwiUyQ48pzBGAEbIrdd30iPeDwuuJTWv6MjJkD2PU706TTtscEG2plnVc/McFqvwAMpDcS5zsFNAlwHWbCZYUeqcZ3BoiANMz7erd0uQU5ZSG38DukpzwVntw2jpChrfdWLCLLiG9ZU59crNiP97mQ6v5uHIHBlvzwW9QUitSMZE4z5jx9WiZyYjPyDE6kYoAcY0rDkPqdE7/tEUfjShW5pnw7RqmB Generated by Nova\n",
  "fingerprint": "5a:c8:85:e9:f8:08:f8:50:9c:4e:6e:02:6a:f0:b7:3f",
  "href": "/users/157/os-keyparis/my_keypair3"
}

Generate Keypair

Generates a new keypair. Keypair name can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter.

Resource: POST users/{user_id}/os-keypairs/{keypair_name}

Entitlement: POST accounts/{account_id}/users/{user_id}/os-keypairs/{keypair_name}

Error Response Codes:

  • 404 – user not found
  • 409 – user already has a keypair with the same name

Example Request: POST http://localhost:8080/xlcloud-xms/users/157/os-keypairs/my_keypair

Example Response: 200

{
  "name": "my_keypair",
  "privateKey": "-BEGIN RSA PRIVATE KEY-\nMIIEpQIBAAKCAQEAr20T26hpJ5c4598Li1pJQugHnySQ6O/7ngAj7iN1U7tHC4k9\nidaVXxn8RMHeUDpkVB6HXxSEL6Z6Z/utzmQFY0sxi+d3rdpizZcaeJAbTC2csF4B\ntp5xwWRR8IlMkOPKcwRgBGyK3Xd9Ij3g8LriU1r+jIyZA9j1O9Ok07bHBBtqZZ1X\nPzHBar8ADKQ3Euc7BTQJcB1mwmWFHqnGdwaIgDTM+3q3dLkFOWUht/A7pKc8FZ7c\nNo6Qoa33Viwiy4hvWVOfXKzYj/e5kOr+bhyBwZb88FvUFIrUjGROM+Y8fVomcmIz\n8gxOpGKAHGNKw5D6nRO/7RFH40oVuaZ8O0apgQIDAQABAoIBAAmypwFiqwWER6IR\n44p9oEUxnJJArD4kXi2a5mGY1jidxsytdphzI2jRf++xJAAdakR4N5WbBb+4nVW4\nRSB+yQl3M7L/Rc93njStYMo/dTLd5qadW8zjr3g4eosom/H6lcuL917nPToHDATj\nlNbaDf77rczJTQA4cz4uchM+LHxejC6vUWKZFpnwGzbItFMtOqf0PtyRbE1vOsue\nGjtdqfiAx2NSomLNd9YvFMiyBCFgwyJwjzEzkdCTzs+/LNWrSmgpfvefUdMcs5nd\n75gYwEiXxFIdQChXIq6U6gSnwwXzti4xCICH59+JM1FSjWfM/C/Q2IjxhcYP7Li1\nIj3TtJ0CgYEA2wiGSZ88u+T/K/B+Q+jGz6Vjc8d+vlJDbHP+nlo/vCj9hOZK8TMc\nkIcVzZKf+W081ACXOaX66suSHTiA3x/bzKBBPqNAqxbbloXaMGCyNP4xNDjZw0Fw\noOLbbntOPr6iZPASsbPgssrguhfXc8qhMH1lPBzSQ/uEgQC1xbsmj68CgYEAzQh5\nnld/W+/4suhcR4pliVIvNf+nAURti23EZJBiFZpcPolZe/ZMWm+K04+Zi4iKYRKU\nD9JOnLX8PVqCB1aXXJi3bf/9xo/lU0N8GrdBtt6rLY58LofUP0U5+a7/4jU7mPUL\n+tGtzlcQYATWi9YS6IVvz4O/fDH4YlbblK9c8CgYEAj1t++QS97YSt9oZLPgtG\nxHVNKGQz8kFJW9x3lBEhkfeKJsfL2R5I3ddsT8Zd6hSzMVbJo7OdDLv8gB+RSXhC\nliV1TpfvJYuqYVRuQCepu8F7VuC2tnNIUiTo1eDij3KaO1JeCezfbmYWu/YK0ACZ\ni3EnJzb97/zY9s4OKsKZNIUCgYEAqaWDi8J1/Mo4C0A7am5WySKZMaLQujm2MhGm\n2Fam8Z0BCjV3Nxx53LJCOf6tW0ikxuEqZVTr+rqRdOp4gD3ji5hI3dlcT3kslJJY\nE3riAr+G/3DPy2hT8+4BpFhqHO9S2qKXQPdRSlO7ltcp9hYxGverCn6hnmzIpELI\noVsZbP0CgYEAnoAibwLmVJzvdNb1fDR6AH/sNOL/kNOV0CilVsb/Em6all/g5TdA\n2ZG5Krt/JePm3EHUvwxQXDjZ8Umv5sbPJi942pfTMNb+H5noSJ2RBXhKYYSjj7e4\nDiHXG1Egjj4FnhHUYIAGgSkt6z6udPeC6TObgH9Ivl4jmbEGAIszV8U=\n-END RSA PRIVATE KEY-\n",
  "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCvbRPbqGknlzjn3wuLWklC6AefJJDo7/ueACPuI3VTu0cLiT2J1pVfGfxEwd5QOmRUHodfFIQvpnpn+63OZAVjSzGL53et2mLNlxp4kBtMLZywXgG2nnHBZFHwiUyQ48pzBGAEbIrdd30iPeDwuuJTWv6MjJkD2PU706TTtscEG2plnVc/McFqvwAMpDcS5zsFNAlwHWbCZYUeqcZ3BoiANMz7erd0uQU5ZSG38DukpzwVntw2jpChrfdWLCLLiG9ZU59crNiP97mQ6v5uHIHBlvzwW9QUitSMZE4z5jx9WiZyYjPyDE6kYoAcY0rDkPqdE7/tEUfjShW5pnw7RqmB Generated by Nova\n",
  "fingerprint": "5a:c8:85:e9:f8:08:f8:50:9c:4e:6e:02:6a:f0:b7:3f",
  "href": "/users/157/os-keyparis/my_keypair"
}

Get Keypair Details

Gets the details of a specified keypair.

Resource: GET users/{user_id}/os-keypairs/{keypair_name}

Entitlement: GET accounts/{account_id}/users/{user_id}/os-keypairs/{keypair_name}

Error Response Codes:

  • 404 – user not found, keypair not found

Example Request: GET http://localhost:8080/xlcloud-xms/users/157/os-keypairs/my_keypair

Example Response: 200

{
  "name": "my_keypair",
  "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCvbRPbqGknlzjn3wuLWklC6AefJJDo7/ueACPuI3VTu0cLiT2J1pVfGfxEwd5QOmRUHodfFIQvpnpn+63OZAVjSzGL53et2mLNlxp4kBtMLZywXgG2nnHBZFHwiUyQ48pzBGAEbIrdd30iPeDwuuJTWv6MjJkD2PU706TTtscEG2plnVc/McFqvwAMpDcS5zsFNAlwHWbCZYUeqcZ3BoiANMz7erd0uQU5ZSG38DukpzwVntw2jpChrfdWLCLLiG9ZU59crNiP97mQ6v5uHIHBlvzwW9QUitSMZE4z5jx9WiZyYjPyDE6kYoAcY0rDkPqdE7/tEUfjShW5pnw7RqmB Generated by Nova ",
  "fingerprint": "5a:c8:85:e9:f8:08:f8:50:9c:4e:6e:02:6a:f0:b7:3f",
  "href": "/users/157/os-keyparis/my_keypair"
}

List User Keypairs

Lists all keypairs of a specified user.

Resource: GET users/{user_id}/os-keypairs

Entitlement: GET accounts/{account_id}/users/{user_id}/os-keypairs

Error Response Codes:

  • 404 – user not found

Example Request: GET http://localhost:8080/xlcloud-xms/users/157/os-keypairs

Example Response: 200

{
  "keypair": [
    {
      "name": "my_keypair",
      "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCvbRPbqGknlzjn3wuLWklC6AefJJDo7/ueACPuI3VTu0cLiT2J1pVfGfxEwd5QOmRUHodfFIQvpnpn+63OZAVjSzGL53et2mLNlxp4kBtMLZywXgG2nnHBZFHwiUyQ48pzBGAEbIrdd30iPeDwuuJTWv6MjJkD2PU706TTtscEG2plnVc/McFqvwAMpDcS5zsFNAlwHWbCZYUeqcZ3BoiANMz7erd0uQU5ZSG38DukpzwVntw2jpChrfdWLCLLiG9ZU59crNiP97mQ6v5uHIHBlvzwW9QUitSMZE4z5jx9WiZyYjPyDE6kYoAcY0rDkPqdE7/tEUfjShW5pnw7RqmB Generated by Nova ",
      "fingerprint": "5a:c8:85:e9:f8:08:f8:50:9c:4e:6e:02:6a:f0:b7:3f",
      "href": "/users/157/os-keyparis/my_keypair"
    },
    {
      "name": "my_keypair2",
      "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCvbRPbqGknlzjn3wuLWklC6AefJJDo7/ueACPuI3VTu0cLiT2J1pVfGfxEwd5QOmRUHodfFIQvpnpn+63OZAVjSzGL53et2mLNlxp4kBtMLZywXgG2nnHBZFHwiUyQ48pzBGAEbIrdd30iPeDwuuJTWv6MjJkD2PU706TTtscEG2plnVc/McFqvwAMpDcS5zsFNAlwHWbCZYUeqcZ3BoiANMz7erd0uQU5ZSG38DukpzwVntw2jpChrfdWLCLLiG9ZU59crNiP97mQ6v5uHIHBlvzwW9QUitSMZE4z5jx9WiZyYjPyDE6kYoAcY0rDkPqdE7/tEUfjShW5pnw7RqmB Generated by Nova\n",
      "fingerprint": "5a:c8:85:e9:f8:08:f8:50:9c:4e:6e:02:6a:f0:b7:3f",
      "href": "/users/157/os-keyparis/my_keypair2"
    },
    {
      "name": "my_keypair3",
      "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCvbRPbqGknlzjn3wuLWklC6AefJJDo7/ueACPuI3VTu0cLiT2J1pVfGfxEwd5QOmRUHodfFIQvpnpn+63OZAVjSzGL53et2mLNlxp4kBtMLZywXgG2nnHBZFHwiUyQ48pzBGAEbIrdd30iPeDwuuJTWv6MjJkD2PU706TTtscEG2plnVc/McFqvwAMpDcS5zsFNAlwHWbCZYUeqcZ3BoiANMz7erd0uQU5ZSG38DukpzwVntw2jpChrfdWLCLLiG9ZU59crNiP97mQ6v5uHIHBlvzwW9QUitSMZE4z5jx9WiZyYjPyDE6kYoAcY0rDkPqdE7/tEUfjShW5pnw7RqmB Generated by Nova\n",
      "fingerprint": "5a:c8:85:e9:f8:08:f8:50:9c:4e:6e:02:6a:f0:b7:3f",
      "href": "/users/157/os-keyparis/my_keypair3"
    }
  ],
  "href": "/users/157/os-keypairs"
}

Delete Keypair

Deletes a keypair.

Resource: DELETE users/{user_id}/os-keypairs/{keypair_name}

Entitlement: DELETE accounts/{account_id}/users/{user_id}/os-keypairs/{keypair_name}

Example Request: DELETE http://localhost:8080/xlcloud-xms/users/157/os-keypairs/my_keypair 

Example Response: 204
(no content)

OS Credentials

OS credentials contain all the information that are necessary to authenticate yourself in OpenStack – Keystone user name, Keystone project name, and the Keystone API URL. You only need to know your password.

OS credentials have the following fields:

  • username – name of the associated user in Keystone
  • osProjectId – identifier of the associated project in Keystone
  • osProjectName – name of the associated project in Keystone
  • authUrl – Keystone URL

Get Credentials

Gets the credentials.

Resource: GET users/{user_id}/os-credentials?projectId={project_id}

Entitlement: (two entitlements are required)

  • GET accounts/{account_id}/users/{user_id}/os-credentials
  • GET accounts/{account_id}/projects/{project_id}

Required Query Parameters:

  • projectId

Error Response Codes:

  • 404 – user not found, project not found

Example Request: GET http://localhost:8080/xlcloud-xms/users/157/os-credentials?projectId=738

Example Response: 200

{
  "username": "kaef",
  "osProjectId": "fcf2b10894fb42638b959e559239d87b",
  "osProjectName": "my_project34",
  "authUrl": "http://10.197.217.60:5000/v2.0"
}

Stacks

A stack is a container and a generic partitioning scheme used to group resources and applications, that has specific computing and data processing capabilities. Users can deploy applications on their stacks. Stacks are created within a context of a project. The concept of a stack is the cornerstone concept of the XLcloud project, as it allows for a PaaS-enabling integration technology in the system. The concept of a stack (and stack instances) brings the operational efficiency of the system, in that all the administrative tasks required to manage the lifecycle and the scalability of a stack instance can be reliably and repetitively automated by the system.

Stacks can be created using stack blueprints from cloud catalogs, or they can be custom (freehand) stacks. It is also possible to modify stacks created from blueprints. How the stack was created is indicated by the stack origin. A freehand stack has origin "custom". Stacks created from blueprints have origin "from blueprint", and after their templates are modified, they origin is changed to "customized from blueprint".

Each stack has an AWS template associated with it. Furthermore, stacks generally consist of layers, and it is layers that define concrete resources (like instances). Layers are in fact nested stacks (they are resources of type AWS::CloudFormation::Stack).

XLcloud stack templates are composed of the following resources:

  • XLcloud-specific parameters – template parameters that utilize specific naming conventions. Each parameter is inherited by all stack layers and resources (within layers as well). Users can always override each parameter directly on a layer level (making a new default value for all resources within this layer) or for separate resources. The following list defines all custom stack parameters used in XLcloud:
    • xlcloud:defaultImageId – defines the default Glance image name for the stack. Images have to be specified in an XLcloud image catalog, either public or private.
    • xlcloud:defaultInstanceType – defines a default instance type for the stack instances. Instance type has to be a valid Nova Flavor defined in Nova.
    • xlcloud:brokerAddress – defines the address (usually IP) of the project broker instance. It has to be an externally-reachable address (hence usually a floating IP) of the project broker stack.
    • xlcloud:brokerPort – defines the port of the project broker. In the current implementation (using RabbitMQ as the project broker) its default value is always the same – 63613.
    • xlcloud:brokerUsername,xlcloud:brokerPassword – they define credentials necessary to use the project broker.
    • xlcloud:stackId – filled for the layers – contain the AWS:StackId of the stack that the layer belong to
    • xlcloud:stackSecret – defines the default OS keypair name for the stack. It will be used for authorization of Ceilometer requests on auto-scaling. Should have the option NoEcho set to True as is stores authorization key.
    • xlcloud:xmsAddress – URL of XMS, it will be used for Ceilometer alarms notifying XMS after automatical rescaling of the stack.xlcloud:defaultKeyName – defines the default OS keypair name for the stack.
  • Layers – each layer represents a set of logically grouped stack resources. Each layer in XLcloud is assigned to a single subnet (configured through dedicated layer parameter) and defines lifecycle configuration (Chef recipes and their attributes assigned to appropriate layer phases). Layers are configured using the following elements:
    • AWS::CloudFormation::Stack resource in the stack template linking the layer to the stack. This resource must have the value of the TemplateURL property set.
    • a separate template that describes the layer structure
  • XLcloud-specific outputs:
    • xlcloud:xsaAddress – the address of the instance serving XSA. The value of the IP address is usually ported from one of the stack layer outputs (since instances hosting XSA usually belong to one of the stack layers). An example value of such an output would be http://10.197.217.161:8080/xsa. When no port is specified, port 80 is assumed.

When Ceilometer alarms are used to request stack configuration after autoscaling, they should call the appropriate XMS endpoint. In Heat template the callback URL can be constructed as follows:

"Fn::Join": [
    "",
    [
        {"Ref":"xlcloud:xmsAddress"},
        "/update?stack=",
        {"Ref":"xlcloud:stackId"},
        "&layer=",
        {"Ref": "AWS::StackId"},
        "&secret=",
        {"Ref": "xlcloud:stackSecret"}
    ]
]

Stacks have the following fields:

  • id – unique identifier
  • name – name of the stack
  • accountId – identifier of the account this stack belongs to
  • projectId – identifier of the project this stack belongs to
  • stackOrigin – origin of this stack, can be one of: "custom" (a freehand stack), "from blueprint" (stack created directly from a blueprint), "customized from blueprint" (stack created from a blueprint, but modifier later)
  • template – AWS template of the stack
  • layers – layers of this stack
  • parametersValues – current values of the stack parameters
    • parametersValues – list of current values
      • name – name of the parameter
      • value – value of the parameter

Create Empty Stack

Creates a new stack without a blueprint. The most basic stack will be created. Such a stack will not have any layers or other resources. It will only be assigned required XLcloud parameters (like "xlcloud:defaultInstanceType"). Values of those parameters can be passed. Those that are not passed will have no value. Unrecognized parameters will be ignored.

A stack created using this method will have origin "custom".

To create a stack, you need to be a member of the project you are trying to create the stack in.

Resource: POST projects/{project_id}/stacks/freehand

Entitlement: POST accounts/{account_id}/projects/{project_id}/stacks/freehand

Required Fields:

  • name – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter

Error Response Codes:

  • 400 – user is not a member of the project, the project is not active
  • 404 – project not found
  • 409 – a stack with the same name already exists in the project

Example Request: POST http://localhost:8080/xlcloud-xms/projects/737/stacks/freehand

{
  "name": "my_stack6",
  "parametersValues": {
    "parametersValues": [
      {
        "value": "my_keypair2",
        "name": "xlcloud:defaultKeyName"
      },
      {
        "value": "m1.xlarge",
        "name": "xlcloud:defaultInstanceType"
      },
      {
        "value": "F19-x86_64-xlcloud",
        "name": "xlcloud:defaultImageId"
      }
    ]
  }
}

Example Response: 200

{
  "layers": {
    "layer": []
  },
  "id": 8,
  "href": "stacks/8",
  "parametersValues": {
    "parametersValues": [
      {
        "value": "my_keypair2",
        "name": "xlcloud:defaultKeyName"
      },
      {
        "value": "m1.xlarge",
        "name": "xlcloud:defaultInstanceType"
      },
      {
        "value": "F19-x86_64-xlcloud",
        "name": "xlcloud:defaultImageId"
      }
    ]
  },
  "name": "my_stack6",
  "accountId": 100,
  "template": {
    "Parameters": {
      "xlcloud:brokerPort": {
        "Description": "RabbitMQ broker port",
        "Type": "String"
      },
      "xlcloud:defaultKeyName": {
        "Description": "Name of an existing EC2 KeyPair to enable SSH access",
        "Type": "String"
      },
      "xlcloud:brokerAddress": {
        "Description": "RabbitMQ broker address",
        "Type": "String"
      },
      "xlcloud:brokerUsername": {
        "Description": "RabbitMQ broker username",
        "Type": "String"
      },
      "xlcloud:defaultInstanceType": {
        "Description": "Default instance type (flavor) for instances in this stack",
        "Type": "String",
        "ConstraintDescription": "must be a valid XLcloud instance type."
      },
      "xlcloud:brokerPassword": {
        "Description": "RabbitMQ broker password",
        "Type": "String"
      },
      "xlcloud:defaultImageId": {
        "Description": "Default image name for instances in this stack",
        "Type": "String",
        "ConstraintDescription": "must be a valid XLcloud image name."
      }
    },
    "Description": "Basic example of XLcloud stack template",
    "AWSTemplateFormatVersion": "2010-09-09"
  },
  "projectId": 737,
  "stackOrigin": "custom"
}

Create Stack from Blueprint

Creates a new stack from a blueprint. Values of the parameters defined in the blueprint can be passed, and will override default values. Those that are not passed will have no value. Unrecognized parameters will be ignored.

A stack created using this method will have origin "from blueprint".

To create a stack, you need to be a member of the project you are trying to create the stack in.

Resource: POST projects/{project_id}/stacks?blueprintId={stack_blueprint_id}

Entitlement: (two entitlements are required)

  • POST accounts/{account_id}/projects/{project_id}/stacks
  • to create a stack from a public blueprint: GET stack-blueprints/{stack_blueprint_id}
  • to create a stack from a private blueprint: GET accounts/{account_id}/stack-blueprints/{stack_blueprint_id}

Required Query Parameters:

  • blueprintId

Required Fields:

  • name – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter

Error Response Codes:

  • 400 – user is not a member of the project, the project is not active
  • 404 – project not found, stack blueprint not found
  • 409 – a stack with the same name already exists in the project

Example Request: POST http://localhost:8080/xlcloud-xms/projects/737/stacks?blueprintId=1

{
  "name": "my_stack8",
  "parametersValues": {
    "parametersValues": [
      {
        "value": "9000",
        "name": "MonitorPort"
      }
    ]
  }
}

Example Response: 200

{
  "layers": {
    "layer": [
      {
        "id": 5,
        "href": "layers/5",
        "parametersValues": {},
        "name": "Slurm",
        "accountId": 100,
        "template": {},
        "stackId": 11
      },
      {
        "id": 6,
        "href": "layers/6",
        "parametersValues": {},
        "name": "Monitor",
        "accountId": 100,
        "template": {},
        "stackId": 11
      }
    ]
  },
  "id": 11,
  "href": "stacks/11",
  "parametersValues": {
    "parametersValues": [
      {
        "value": "63613",
        "name": "xlcloud:brokerPort"
      },
      {
        "value": "9000",
        "name": "MonitorPort"
      },
      {
        "value": "2",
        "name": "xlcloud:Computes:size"
      },
      {
        "value": "m1.small",
        "name": "xlcloud:defaultInstanceType"
      },
      {
        "value": "xlcloud",
        "name": "xlcloud:brokerUsername"
      },
      {
        "value": "SLURM",
        "name": "xlcloud:monitoringCluster"
      },
      {
        "value": "xlcloud",
        "name": "xlcloud:brokerPassword"
      },
      {
        "value": "F19-x86_64-xlcloud",
        "name": "xlcloud:defaultImageId"
      }
    ]
  },
  "name": "my_stack8",
  "accountId": 100,
  "template": {
    "Outputs": {
      "MonitorURL": {
        "Value": {
          "Fn::GetAtt": [
            "Monitor",
            "Outputs.PublicURL"
          ]
        },
        "Description": "Public URL of the monitoring node"
      },
      "LoginIP": {
        "Value": {
          "Fn::GetAtt": [
            "Slurm",
            "Outputs.LoginAddress"
          ]
        },
        "Description": "Public address of the login node"
      },
      "xlcloud:xsaAddress": {
        "Value": {
          "Fn::Join": [
            "",
            [
              "http://",
              {
                "Fn::GetAtt": [
                  "Slurm",
                  "Outputs.xsaIp"
                ]
              },
              ":8080/xsa"
            ]
          ]
        },
        "Description": "XSA URL"
      }
    },
    "Parameters": {
      "xlcloud:brokerPort": {
        "Default": "63613",
        "Description": "RabbitMQ broker port",
        "Type": "String"
      },
      "xlcloud:defaultKeyName": {
        "Description": "Name of an existing EC2 KeyPair to enable SSH access",
        "Type": "String"
      },
      "MonitorPort": {
        "Default": "8649",
        "Description": "TCP port of monitoring traffic data",
        "Type": "String"
      },
      "xlcloud:brokerAddress": {
        "Description": "RabbitMQ broker address",
        "Type": "String"
      },
      "xlcloud:Computes:size": {
        "Default": "2",
        "Description": "Number of compute nodes to launch",
        "Type": "String"
      },
      "xlcloud:brokerUsername": {
        "Default": "xlcloud",
        "Description": "RabbitMQ broker username",
        "Type": "String"
      },
      "xlcloud:defaultInstanceType": {
        "Default": "m1.small",
        "AllowedValues": [
          "m1.tiny",
          "m1.small",
          "m1.medium",
          "m1.large",
          "m1.xlarge"
        ],
        "Description": "Default instance type (flavor) for instances in this stack",
        "Type": "String",
        "ConstraintDescription": "must be a valid XLcloud instance type."
      },
      "xlcloud:monitoringCluster": {
        "Default": "SLURM",
        "Description": "Name of the cluster in the monitoring system",
        "Type": "String",
        "AllowedPattern": "[a-z|A-Z|0-9]*"
      },
      "xlcloud:brokerPassword": {
        "Default": "xlcloud",
        "Description": "RabbitMQ broker password",
        "Type": "String"
      },
      "xlcloud:defaultImageId": {
        "Default": "F19-x86_64-xlcloud",
        "AllowedValues": [
          "F19-x86_64-xlcloud"
        ],
        "Description": "Default image name for instances in this stack",
        "Type": "String",
        "ConstraintDescription": "Must be a valid XLcloud image name."
      }
    },
    "Description": "XLcloud Slurm Stack",
    "AWSTemplateFormatVersion": "",
    "Resources": {
      "Monitor": {
        "Type": "AWS::CloudFormation::Stack",
        "Properties": {
          "Parameters": {
            "xlcloud:brokerPort": {
              "Ref": "xlcloud:brokerPort"
            },
            "xlcloud:defaultKeyName": {
              "Ref": "xlcloud:defaultKeyName"
            },
            "MonitorPort": {
              "Ref": "MonitorPort"
            },
            "xlcloud:brokerAddress": {
              "Ref": "xlcloud:brokerAddress"
            },
            "xlcloud:brokerUsername": {
              "Ref": "xlcloud:brokerUsername"
            },
            "xlcloud:defaultInstanceType": {
              "Ref": "xlcloud:defaultInstanceType"
            },
            "xlcloud:layerSubnetUuid": "50e0c97a-46d8-4c32-87fa-8bf2de9febb4",
            "xlcloud:stackId": {
              "Ref": "AWS::StackId"
            },
            "xlcloud:monitoringCluster": {
              "Ref": "xlcloud:monitoringCluster"
            },
            "xlcloud:brokerPassword": {
              "Ref": "xlcloud:brokerPassword"
            },
            "xlcloud:defaultImageId": {
              "Ref": "xlcloud:defaultImageId"
            }
          },
          "TimeoutInMinutes": "5",
          "TemplateURL": "layers/6"
        }
      },
      "Slurm": {
        "Type": "AWS::CloudFormation::Stack",
        "DependsOn": "Monitor",
        "Properties": {
          "Parameters": {
            "xlcloud:brokerPort": {
              "Ref": "xlcloud:brokerPort"
            },
            "xlcloud:defaultKeyName": {
              "Ref": "xlcloud:defaultKeyName"
            },
            "xlcloud:brokerAddress": {
              "Ref": "xlcloud:brokerAddress"
            },
            "xlcloud:Computes:size": {
              "Ref": "xlcloud:Computes:size"
            },
            "xlcloud:brokerUsername": {
              "Ref": "xlcloud:brokerUsername"
            },
            "xlcloud:defaultInstanceType": {
              "Ref": "xlcloud:defaultInstanceType"
            },
            "xlcloud:layerSubnetUuid": "50e0c97a-46d8-4c32-87fa-8bf2de9febb4",
            "xlcloud:stackId": {
              "Ref": "AWS::StackId"
            },
            "xlcloud:monitoringCluster": {
              "Ref": "xlcloud:monitoringCluster"
            },
            "xlcloud:monitorIP": {
              "Fn::GetAtt": [
                "Monitor",
                "Outputs.MonitorIP"
              ]
            },
            "xlcloud:brokerPassword": {
              "Ref": "xlcloud:brokerPassword"
            },
            "xlcloud:defaultImageId": {
              "Ref": "xlcloud:defaultImageId"
            }
          },
          "TimeoutInMinutes": "40",
          "TemplateURL": "layers/5"
        }
      }
    }
  },
  "projectId": 737,
  "stackOrigin": "from blueprint",
  "blueprintId": 1
}

Create Stack from Stack Template

Creates a new stack using a specified template. The content type used for this request must be template/json. If the template contains layers (resources of type AWS::CloudFormation::Stack), their TemplateURL parameters should be specified as "layer-blueprints/{layer_blueprint_id}". These will be transformed into proper layers based on the specified blueprints. Any other fields of layer resources will be ignored. If not present, the "xlcloud" parameters will be added automatically.

A stack created using this method will have origin "custom".

To create a stack, you need to be a member of the project you are trying to create the stack in.

Resource: POST projects/{project_id}/stacks?stackName={stack_name}

Entitlement: (one or more entitlements are required)

  • POST accounts/{account_id}/projects/{project_id}/stacks
  • for each used public layer blueprint: GET layer-blueprints/{layer_blueprint_id}
  • for each used private layer blueprint: GET accounts/{account_id}/layer-blueprints/{layer_blueprint_id}

Required Headers:

*Content-Type: template/json

Required Query Parameters:

  • stackName – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter

Error Response Codes:

  • 400 – user is not a member of the project, the project is not active, one of the used layer blueprints is not independent (is a part of a stack blueprint), TemplateURL of a layer is not specified or is invalid
  • 404 – project not found
  • 409 – a stack with the same name already exists in the project

Example Request: POST http://localhost:8080/xlcloud-xms/projects/737/stacks?stackName=my_stack16(% class="mybox" %)
{
  "AWSTemplateFormatVersion": "2010-09-09",
  "Description": "Description of my stack",
  "Parameters": {
    "MyParameter": {
      "Description": "This is a description",
      "Type": "String"
    }
  },
  "Resources": {
    "SlurmLayer": {
      "Type": "AWS::CloudFormation::Stack",
      "Properties": {
        "TemplateURL": "layer-blueprints/11"
      }
    }
  }
}

Example Response: 200

{
  "layers": {
    "layer": [
      {
        "id": 35,
        "href": "layers/35",
        "parametersValues": {},
        "name": "SlurmLayer",
        "accountId": 100,
        "template": {},
        "stackId": 35
      }
    ]
  },
  "id": 35,
  "href": "stacks/35",
  "parametersValues": {},
  "name": "my_stack26",
  "accountId": 100,
  "template": {
    "Parameters": {
      "xlcloud:brokerPort": {
        "Description": "RabbitMQ broker port",
        "Type": "String"
      },
      "xlcloud:defaultKeyName": {
        "Description": "Name of an existing EC2 KeyPair to enable SSH access",
        "Type": "String"
      },
      "xlcloud:brokerAddress": {
        "Description": "RabbitMQ broker address",
        "Type": "String"
      },
      "MyParameter": {
        "Description": "This is a description",
        "Type": "String"
      },
      "xlcloud:brokerUsername": {
        "Description": "RabbitMQ broker username",
        "Type": "String"
      },
      "xlcloud:defaultInstanceType": {
        "Description": "Default instance type (flavor) for instances in this stack",
        "Type": "String",
        "ConstraintDescription": "must be a valid XLcloud instance type."
      },
      "xlcloud:brokerPassword": {
        "Description": "RabbitMQ broker password",
        "Type": "String"
      },
      "xlcloud:defaultImageId": {
        "Description": "Default image name for instances in this stack",
        "Type": "String",
        "ConstraintDescription": "must be a valid XLcloud image name."
      }
    },
    "Description": "Description of my stack",
    "AWSTemplateFormatVersion": "2010-09-09",
    "Resources": {
      "SlurmLayer": {
        "Type": "AWS::CloudFormation::Stack",
        "Properties": {
          "Parameters": {
            "xlcloud:brokerPort": {
              "Ref": "xlcloud:brokerPort"
            },
            "xlcloud:defaultKeyName": {
              "Ref": "xlcloud:defaultKeyName"
            },
            "xlcloud:brokerAddress": {
              "Ref": "xlcloud:brokerAddress"
            },
            "xlcloud:brokerUsername": {
              "Ref": "xlcloud:brokerUsername"
            },
            "xlcloud:defaultInstanceType": {
              "Ref": "xlcloud:defaultInstanceType"
            },
            "xlcloud:layerSubnetUuid": "50e0c97a-46d8-4c32-87fa-8bf2de9febb4",
            "xlcloud:stackId": {
              "Ref": "AWS::StackId"
            },
            "xlcloud:brokerPassword": {
              "Ref": "xlcloud:brokerPassword"
            },
            "xlcloud:defaultImageId": {
              "Ref": "xlcloud:defaultImageId"
            }
          },
          "TemplateURL": "layers/35"
        }
      }
    }
  },
  "projectId": 737,
  "stackOrigin": "custom"
}

Create Stack from Layer Template

Creates a new stack containing exactly one layer, and the layer is created using a specified template. The content type used for this request must be template/json. If not present, "xlcloud" parameters will be added automatically.

A stack created using this method will have origin "custom".

To create a stack, you need to be a member of the project you are trying to create the stack in.

Resource: POST projects/{project_id}/layers?stackName={stack_name}

Entitlement: POST accounts/{account_id}/projects/{project_id}/layers

Required Headers:

  • Content-Type: template/json

Required Query Parameters:

  • stackName – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter

Error Response Codes:

  • 400 – user is not a member of the project, the project is not active
  • 404 – project not found
  • 409 – a stack with the same name already exists in the project

Example Request: POST http://localhost:8080/xlcloud-xms/projects/737/layers?stackName=my_stack17

{
  "Parameters": {
    "MonitorPort": {
      "Default": "8649",
      "Type": "String",
      "Description": "TCP port of monitoring traffic data"
    },
    "xlcloud:monitoringCluster": {
      "Type": "String",
      "Description": "Name of the cluster in the monitoring system"
    }
  },
  "Outputs": {
    "MonitorIP": {
      "Description": "Private IP address of the Ganglia server",
      "Value": {
        "Fn::GetAtt": [
          "MonitorNode",
          "PrivateIp"
        ]
      }
    }
  },
  "HeatTemplateFormatVersion": "2012-12-12",
  "Description": "Deploy a monitoring node.",
  "Resources": {
    "MonitorNode": {
      "Type": "AWS::EC2::Instance",
      "Properties": {
        "UserData": {
          "Fn::Base64": {
            "Fn::Join": [
              "",
              [
                "#!/bin/bash -v\nexport MY_PUB_IPV4=$(http_proxy= curl -s http://169.254.169.254/latest/meta-data/public-ipv4)\nexport MY_HOSTNAME=$(http_proxy= curl -s http://169.254.169.254/latest/meta-data/instance-id)\necho $MY_HOSTNAME > /etc/hostname\nhostname $MY_HOSTNAME\nexport HOME=/root\necho $MY_PUB_IPV4 $MY_HOSTNAME >> /etc/hosts\nsource /etc/profile.d/proxy.sh\npip install upgrade heat-cfntools\ncfn-init\ncd /var/chef/chef-repo\n/usr/local/bin/librarian-chef install clean verbose\n/bin/chef-solo -c /etc/chef/solo.rb -j /etc/chef/setup-runlist.json -L /var/log/chef-solo.log"
             ]
           ]
         }
       },
       "KeyName": {
         "Ref": "xlcloud:defaultKeyName"
       },
       "SecurityGroups": [
         {
           "Ref": "MonitorSecurityGroup"
         }
       ],
       "SubnetId": {
         "Ref": "xlcloud:layerSubnetUuid"
       },
       "InstanceType": {
         "Ref": "xlcloud:defaultInstanceType"
       },
       "ImageId": {
         "Ref": "xlcloud:defaultImageId"
       }
     },
     "Metadata": {
       "AWS::CloudFormation::Init": {
         "config": {
           "files": {
             "/etc/chef/resume-runlist.json": {
               "content": {}
             },
             "/var/chef/chef-repo/roles/ganglia-server.json": {
               "content": {
                 "chef_type": "role",
                 "default_attributes": {},
                 "description": "This is a role to install the ganglia service",
                 "run_list": [
                   "recipe[ganglia]",
                   "recipe[ganglia::web]",
                   "recipe[ganglia::python_rr]"
                 ],
                 "override_attributes": {
                   "ganglia": {
                     "cluster": {
                       "collector_host": "127.0.0.1",
                       "name": {
                         "Ref": "xlcloud:monitoringCluster"
                       }
                     },
                     "central_monit": true
                   }
                 },
                 "json_class": "Chef::Role",
                 "name": "ganglia-server"
               },
               "owner": "root",
               "group": "root",
               "mode": "00400"
             },
             "/var/chef/chef-repo/roles/xlc-mco-agent.json": {
               "content": {
                 "chef_type": "role",
                 "default_attributes": {},
                 "description": "This is a role to install ohai + mcollective server + xlcloud agent.",
                 "run_list": [
                   "recipe[ohai]",
                   "recipe[mcollective::server]",
                   "recipe[xlc-mco-agent]"
                 ],
                 "override_attributes": {
                   "mcollective": {
                     "connector": "rabbitmq",
                     "psk": "supersecret",
                     "stomp": {
                       "username": {
                         "Ref": "xlcloud:brokerUsername"
                       },
                       "password": {
                         "Ref": "xlcloud:brokerPassword"
                       },
                       "hostname": {
                         "Ref": "xlcloud:brokerAddress"
                       },
                       "port": {
                         "Ref": "xlcloud:brokerPort"
                       }
                     },
                     "factsource": "ohai",
                     "enable_puppetlabs_repo": false
                   }
                 },
                 "json_class": "Chef::Role",
                 "name": "xlc-mco-agent"
               },
               "owner": "root",
               "group": "root",
               "mode": "00400"
             },
             "/etc/chef/setup-runlist.json": {
               "content": {
                 "run_list": [
                   "role[xlc-mco-agent]",
                   "role[ganglia-server]"
                 ]
               }
             },
             "/etc/chef/suspend-runlist.json": {
               "content": {}
             },
             "/etc/chef/configure-runlist.json": {
               "content": {}
             },
             "/etc/chef/undeploy-runlist.json": {
               "content": {}
             },
             "/etc/xlcloud-facts.json": {
               "content": {
                 "stack_id": {
                   "Ref": "xlcloud:stackId"
                 },
                 "layer_id": {
                   "Ref": "AWS::StackId"
                 },
                 "logical_resource_id": "MonitorNode"
               }
             },
             "/var/chef/chef-repo/Cheffile": {
               "content": {
                 "Fn::Join": [
                   "\n",
                   [
                     "#!/usr/bin/env ruby",
                     "site 'http://community.opscode.com/api/v1'",
                     "cookbook 'ohai'",
                     "cookbook 'mcollective',",
                     "    :git => 'http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git',",
                     "    :path => 'mcollective'",
                     "cookbook 'xlc-mco-agent',",
                     "    :git => 'http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git',",
                     "    :path => 'xlc-mco-agent'",
                     "cookbook 'ganglia',",
                     "    :git => 'http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git',",
                     "    :path => 'ganglia'"
                   ]
                 ]
               },
               "owner": "root",
               "group": "root",
               "mode": "00400"
             },
             "/etc/chef/shutdown-runlist.json": {
               "content": {}
             },
             "/etc/chef/deploy-runlist.json": {
               "content": {}
             }
           }
         }
       }
     }
   },
   "NodeIPAddress": {
     "Type": "AWS::EC2::EIP"
   },
   "MonitorSecurityGroup": {
     "Type": "AWS::EC2::SecurityGroup",
     "Properties": {
       "SecurityGroupIngress": [
         {
           "ToPort": "-1",
           "IpProtocol": "icmp",
           "CidrIp": "0.0.0.0/0",
           "FromPort": "-1"
         }
       ],
       "VpcId": "neutron",
       "GroupDescription": "Firewall rules : SSH, HTTP(s) and Ganglia"
     }
   },
   "NodeIPAssoc": {
     "Type": "AWS::EC2::EIPAssociation",
     "Properties": {
       "InstanceId": {
         "Ref": "MonitorNode"
       },
       "EIP": {
         "Ref": "NodeIPAddress"
       }
     }
   }
 }
}

Example Response: 200

{
  "layers": {
    "layer": [
      {
        "id": 40,
        "href": "layers/40",
        "parametersValues": {},
        "name": "default_layer",
        "accountId": 100,
        "template": {},
        "stackId": 42
      }
    ]
  },
  "id": 42,
  "href": "stacks/42",
  "parametersValues": {},
  "name": "my_stack31",
  "accountId": 100,
  "template": {
    "Parameters": {
      "xlcloud:brokerPort": {
        "Description": "RabbitMQ broker port",
        "Type": "String"
      },
      "xlcloud:defaultKeyName": {
        "Description": "Name of an existing EC2 KeyPair to enable SSH access",
        "Type": "String"
      },
      "xlcloud:brokerAddress": {
        "Description": "RabbitMQ broker address",
        "Type": "String"
      },
      "xlcloud:brokerUsername": {
        "Description": "RabbitMQ broker username",
        "Type": "String"
      },
      "xlcloud:defaultInstanceType": {
        "Description": "Default instance type (flavor) for instances in this stack",
        "Type": "String",
        "ConstraintDescription": "must be a valid XLcloud instance type."
      },
      "xlcloud:brokerPassword": {
        "Description": "RabbitMQ broker password",
        "Type": "String"
      },
      "xlcloud:defaultImageId": {
        "Description": "Default image name for instances in this stack",
        "Type": "String",
        "ConstraintDescription": "must be a valid XLcloud image name."
      }
    },
    "Description": "Basic example of XLcloud stack template",
    "AWSTemplateFormatVersion": "2010-09-09",
    "Resources": {
      "default_layer": {
        "Type": "AWS::CloudFormation::Stack",
        "Properties": {
          "Parameters": {
            "xlcloud:brokerPort": {
              "Ref": "xlcloud:brokerPort"
            },
            "xlcloud:defaultKeyName": {
              "Ref": "xlcloud:defaultKeyName"
            },
            "xlcloud:brokerAddress": {
              "Ref": "xlcloud:brokerAddress"
            },
            "xlcloud:brokerUsername": {
              "Ref": "xlcloud:brokerUsername"
            },
            "xlcloud:defaultInstanceType": {
              "Ref": "xlcloud:defaultInstanceType"
            },
            "xlcloud:layerSubnetUuid": "50e0c97a-46d8-4c32-87fa-8bf2de9febb4",
            "xlcloud:stackId": {
              "Ref": "AWS::StackId"
            },
            "xlcloud:brokerPassword": {
              "Ref": "xlcloud:brokerPassword"
            },
            "xlcloud:defaultImageId": {
              "Ref": "xlcloud:defaultImageId"
            }
          },
          "TemplateURL": "layers/40"
        }
      }
    }
  },
  "projectId": 737,
  "stackOrigin": "custom"
}

Get Stack Details

Gets the details of a specified stack.

Resource: GET stacks/{stack_id}

Entitlement: GET accounts/{account_id}/projects/{project_id}/stacks/{stack_id}

Error Response Codes:

  • 404 – stack not found

Example Request: GET http://localhost:8080/xlcloud-xms/stacks/1

Example Response: 200

{
  "layers": {
    "layer": []
  },
  "id": 1,
  "href": "stacks/1",
  "parametersValues": {
    "parametersValues": [
      {
        "value": "my_keypair2",
        "name": "xlcloud:defaultKeyName"
      },
      {
        "value": "m1.xlarge",
        "name": "xlcloud:defaultInstanceType"
      },
      {
        "value": "F19-x86_64-xlcloud",
        "name": "xlcloud:defaultImageId"
      }
    ]
  },
  "name": "my_stack",
  "accountId": 100,
  "template": {
    "Parameters": {
      "xlcloud:brokerPort": {
        "Description": "RabbitMQ broker port",
        "Type": "String"
      },
      "xlcloud:defaultKeyName": {
        "Description": "Name of an existing EC2 KeyPair to enable SSH access",
        "Type": "String"
      },
      "xlcloud:brokerAddress": {
        "Description": "RabbitMQ broker address",
        "Type": "String"
      },
      "xlcloud:brokerUsername": {
        "Description": "RabbitMQ broker username",
        "Type": "String"
      },
      "xlcloud:defaultInstanceType": {
        "Description": "Default instance type (flavor) for instances in this stack",
        "Type": "String",
        "ConstraintDescription": "must be a valid XLcloud instance type."
      },
      "xlcloud:brokerPassword": {
        "Description": "RabbitMQ broker password",
        "Type": "String"
      },
      "xlcloud:defaultImageId": {
        "Description": "Default image name for instances in this stack",
        "Type": "String",
        "ConstraintDescription": "must be a valid XLcloud image name."
      }
    },
    "Description": "Basic example of XLcloud stack template",
    "AWSTemplateFormatVersion": "2010-09-09"
  },
  "projectId": 737,
  "stackOrigin": "custom"
}

List All Stacks

Lists all stacks in all accounts and projects. Note that "layers", "parametersValues", and "template" fields are not filled in.

Resource: GET stacks

Entitlement: GET stacks

Example Request: GET http://localhost:8080/xlcloud-xms/stacks

Example Response: 200

{
  "stack": [
    {
      "layers": {
        "layer": []
      },
      "id": 1,
      "href": "stacks/1",
      "parametersValues": {},
      "name": "my_stack",
      "accountId": 100,
      "template": {},
      "projectId": 737,
      "stackOrigin": "custom"
    },
    {
      "layers": {
        "layer": []
      },
      "id": 2,
      "href": "stacks/2",
      "parametersValues": {},
      "name": "my_stack2",
      "accountId": 100,
      "template": {},
      "projectId": 737,
      "stackOrigin": "custom"
    },
    {
      "layers": {
        "layer": []
      },
      "id": 8,
      "href": "stacks/8",
      "parametersValues": {},
      "name": "my_stack6",
      "accountId": 100,
      "template": {},
      "projectId": 737,
      "stackOrigin": "custom"
    },
    {
      "layers": {
        "layer": []
      },
      "id": 13,
      "href": "stacks/13",
      "parametersValues": {},
      "name": "my_stack10",
      "accountId": 100,
      "template": {},
      "projectId": 733,
      "stackOrigin": "custom"
    },
    {
      "layers": {
        "layer": []
      },
      "id": 14,
      "href": "stacks/14",
      "parametersValues": {},
      "name": "my_stack99",
      "accountId": 161,
      "template": {},
      "projectId": 744,
      "stackOrigin": "custom"
    }
  ],
  "totalCount": 5,
  "href": "/stacks"
}

List Account Stacks

Lists all stacks in all projects in a specified account. Note that "layers", "parametersValues", and "template" fields are not filled in.

Resource: GET accounts/{account_id}/stacks

Entitlement: GET accounts/{account_id}/stacks

Example Request: GET http://localhost:8080/xlcloud-xms/accounts/100/stacks

Example Response: 200

{
  "stack": [
    {
      "layers": {
        "layer": []
      },
      "id": 1,
      "href": "stacks/1",
      "parametersValues": {},
      "name": "my_stack",
      "accountId": 100,
      "template": {},
      "projectId": 737,
      "stackOrigin": "custom"
    },
    {
      "layers": {
        "layer": []
      },
      "id": 2,
      "href": "stacks/2",
      "parametersValues": {},
      "name": "my_stack2",
      "accountId": 100,
      "template": {},
      "projectId": 737,
      "stackOrigin": "custom"
    },
    {
      "layers": {
        "layer": []
      },
      "id": 8,
      "href": "stacks/8",
      "parametersValues": {},
      "name": "my_stack6",
      "accountId": 100,
      "template": {},
      "projectId": 737,
      "stackOrigin": "custom"
    },
    {
      "layers": {
        "layer": []
      },
      "id": 13,
      "href": "stacks/13",
      "parametersValues": {},
      "name": "my_stack10",
      "accountId": 100,
      "template": {},
      "projectId": 733,
      "stackOrigin": "custom"
    }
  ],
  "href": "/accounts/100/stacks"
}

List Project Stacks

Lists all stacks in a specified project. Note that "layers", "parametersValues", and "template" fields are not filled in.

Resource: GET projects/{project_id}/stacks

Entitlement: GET accounts/{account_id}/projects/{project_id}/stacks

Example Request: GET http://localhost:8080/xlcloud-xms/projects/737/stacks

Example Response: 200

{
  "stack": [
    {
      "layers": {
        "layer": []
      },
      "id": 1,
      "href": "stacks/1",
      "parametersValues": {},
      "name": "my_stack",
      "accountId": 100,
      "template": {},
      "projectId": 737,
      "stackOrigin": "custom"
    },
    {
      "layers": {
        "layer": []
      },
      "id": 2,
      "href": "stacks/2",
      "parametersValues": {},
      "name": "my_stack2",
      "accountId": 100,
      "template": {},
      "projectId": 737,
      "stackOrigin": "custom"
    },
    {
      "layers": {
        "layer": []
      },
      "id": 8,
      "href": "stacks/8",
      "parametersValues": {},
      "name": "my_stack6",
      "accountId": 100,
      "template": {},
      "projectId": 737,
      "stackOrigin": "custom"
    }
  ],
  "href": "/projects/737/stacks"
}

Update Stack Template

Updates the template of a specified stack. The stack must be stopped, and its layers cannot be modified when using this method. If any "xlcloud" parameters or their values are removed, they will be added back automatically. The content type used for this request must be template/json. The response content type is also template/json, which means that the Accept header should have the value template/json, or should not be set at all.

If the updated stack was created from a blueprint, its origin will be changed to "customized from blueprint".

Resource: PUT stacks/{stack_id}

Entitlement: PUT accounts/{account_id}/projects/{project_id}/stacks/{stack_id}

Required Headers:

  • Content-Type: template/json

Error Response Codes:

  • 400 – stack is not stopped, layers were modified
  • 404 – stack not found

Example Request: PUT http://localhost:8080/xlcloud-xms/stacks/9(

{
  "AWSTemplateFormatVersion": "",
  "Description": "XLcloud Slurm Stack",
  "Outputs": {
    "xlcloud:xsaAddress": {
      "Description": "XSA URL",
      "Value": {
        "Fn::Join": [
          "",
          [
            "http://",
            {
              "Fn::GetAtt": [
                "Slurm",
                "Outputs.xsaIp"
              ]
            },
            ":8080/xsa"
          ]
        ]
      }
    }
  },
  "Parameters": {
    "MonitorPort": {
      "Default": "8649",
      "Description": "TCP port of monitoring traffic data",
      "Type": "String"
    },
    "xlcloud:Computes:size": {
      "Default": "2",
      "Description": "Number of compute nodes to launch",
      "Type": "String"
    },
    "xlcloud:brokerAddress": {
      "Description": "RabbitMQ broker address",
      "Type": "String"
    },
    "xlcloud:brokerPassword": {
      "Default": "xlcloud",
      "Description": "RabbitMQ broker password",
      "Type": "String"
    },
    "xlcloud:brokerPort": {
      "Default": "63613",
      "Description": "RabbitMQ broker port",
      "Type": "String"
    },
    "xlcloud:brokerUsername": {
      "Default": "xlcloud",
      "Description": "RabbitMQ broker username",
      "Type": "String"
    },
    "xlcloud:defaultImageId": {
      "AllowedValues": [
        "F19-x86_64-xlcloud"
      ],
      "ConstraintDescription": "Must be a valid XLcloud image name.",
      "Default": "F19-x86_64-xlcloud",
      "Description": "Default image name for instances in this stack",
      "Type": "String"
    },
    "xlcloud:defaultInstanceType": {
      "AllowedValues": [
        "m1.tiny",
        "m1.small",
        "m1.medium",
        "m1.large",
        "m1.xlarge"
      ],
      "ConstraintDescription": "must be a valid XLcloud instance type.",
      "Default": "m1.small",
      "Description": "Default instance type (flavor) for instances in this stack",
      "Type": "String"
    },
    "xlcloud:defaultKeyName": {
      "Description": "Name of an existing EC2 KeyPair to enable SSH access",
      "Type": "String"
    },
    "xlcloud:monitoringCluster": {
      "AllowedPattern": "[a-z|A-Z|0-9]*",
      "Default": "SLURM",
      "Description": "Name of the cluster in the monitoring system",
      "Type": "String"
    }
  },
  "Resources": {
    "Monitor": {
      "Properties": {
        "Parameters": {
          "MonitorPort": {
            "Ref": "MonitorPort"
          }
        },
        "TemplateURL": "/home/kszafran/heat-templates/Monitor1392979184635.template",
        "TimeoutInMinutes": "5"
      },
      "Type": "AWS::CloudFormation::Stack"
    },
    "Slurm": {
      "DependsOn": "Monitor",
      "Properties": {
        "Parameters": {
          "xlcloud:Computes:size": {
            "Ref": "xlcloud:Computes:size"
          },
          "xlcloud:monitorIP": {
            "Fn::GetAtt": [
              "Monitor",
              "Outputs.MonitorIP"
            ]
          },
          "xlcloud:monitoringCluster": {
            "Ref": "xlcloud:monitoringCluster"
          },
          "xlcloud:stackId": {
            "Ref": "AWS::StackId"
          }
        },
        "TemplateURL": "/home/kszafran/heat-templates/Slurm1392979184605.template",
        "TimeoutInMinutes": "40"
      },
      "Type": "AWS::CloudFormation::Stack"
    }
  }
}

Example Response: 200

{
  "Outputs": {
    "xlcloud:xsaAddress": {
      "Value": {
        "Fn::Join": [
          "",
          [
            "http://",
            {
              "Fn::GetAtt": [
                "Slurm",
                "Outputs.xsaIp"
              ]
            },
            ":8080/xsa"
          ]
        ]
      },
      "Description": "XSA URL"
    }
  },
  "Parameters": {
    "xlcloud:brokerPort": {
      "Default": "63613",
      "Description": "RabbitMQ broker port",
      "Type": "String"
    },
    "xlcloud:defaultKeyName": {
      "Description": "Name of an existing EC2 KeyPair to enable SSH access",
      "Type": "String"
    },
    "MonitorPort": {
      "Default": "8649",
      "Description": "TCP port of monitoring traffic data",
      "Type": "String"
    },
    "xlcloud:brokerAddress": {
      "Description": "RabbitMQ broker address",
      "Type": "String"
    },
    "xlcloud:Computes:size": {
      "Default": "2",
      "Description": "Number of compute nodes to launch",
      "Type": "String"
    },
    "xlcloud:brokerUsername": {
      "Default": "xlcloud",
      "Description": "RabbitMQ broker username",
      "Type": "String"
    },
    "xlcloud:defaultInstanceType": {
      "Default": "m1.small",
      "AllowedValues": [
        "m1.tiny",
        "m1.small",
        "m1.medium",
        "m1.large",
        "m1.xlarge"
      ],
      "Description": "Default instance type (flavor) for instances in this stack",
      "Type": "String",
      "ConstraintDescription": "must be a valid XLcloud instance type."
    },
    "xlcloud:monitoringCluster": {
      "Default": "SLURM",
      "Description": "Name of the cluster in the monitoring system",
      "Type": "String",
      "AllowedPattern": "[a-z|A-Z|0-9]*"
    },
    "xlcloud:brokerPassword": {
      "Default": "xlcloud",
      "Description": "RabbitMQ broker password",
      "Type": "String"
    },
    "xlcloud:defaultImageId": {
      "Default": "F19-x86_64-xlcloud",
      "AllowedValues": [
        "F19-x86_64-xlcloud"
      ],
      "Description": "Default image name for instances in this stack",
      "Type": "String",
      "ConstraintDescription": "Must be a valid XLcloud image name."
    }
  },
  "Description": "XLcloud Slurm Stack",
  "AWSTemplateFormatVersion": "",
  "Resources": {
    "Monitor": {
      "Type": "AWS::CloudFormation::Stack",
      "Properties": {
        "Parameters": {
          "xlcloud:brokerPort": {
            "Ref": "xlcloud:brokerPort"
          },
          "xlcloud:defaultKeyName": {
            "Ref": "xlcloud:defaultKeyName"
          },
          "MonitorPort": {
            "Ref": "MonitorPort"
          },
          "xlcloud:brokerAddress": {
            "Ref": "xlcloud:brokerAddress"
          },
          "xlcloud:brokerUsername": {
            "Ref": "xlcloud:brokerUsername"
          },
          "xlcloud:defaultInstanceType": {
            "Ref": "xlcloud:defaultInstanceType"
          },
          "xlcloud:layerSubnetUuid": "50e0c97a-46d8-4c32-87fa-8bf2de9febb4",
          "xlcloud:stackId": {
            "Ref": "AWS::StackId"
          },
          "xlcloud:brokerPassword": {
            "Ref": "xlcloud:brokerPassword"
          },
          "xlcloud:defaultImageId": {
            "Ref": "xlcloud:defaultImageId"
          }
        },
        "TimeoutInMinutes": "5",
        "TemplateURL": "/home/kszafran/heat-templates/Monitor1392979184635.template"
      }
    },
    "Slurm": {
      "Type": "AWS::CloudFormation::Stack",
      "DependsOn": "Monitor",
      "Properties": {
        "Parameters": {
          "xlcloud:brokerPort": {
            "Ref": "xlcloud:brokerPort"
          },
          "xlcloud:defaultKeyName": {
            "Ref": "xlcloud:defaultKeyName"
          },
          "xlcloud:brokerAddress": {
            "Ref": "xlcloud:brokerAddress"
          },
          "xlcloud:Computes:size": {
            "Ref": "xlcloud:Computes:size"
          },
          "xlcloud:brokerUsername": {
            "Ref": "xlcloud:brokerUsername"
          },
          "xlcloud:defaultInstanceType": {
            "Ref": "xlcloud:defaultInstanceType"
          },
          "xlcloud:layerSubnetUuid": "50e0c97a-46d8-4c32-87fa-8bf2de9febb4",
          "xlcloud:stackId": {
            "Ref": "AWS::StackId"
          },
          "xlcloud:monitoringCluster": {
            "Ref": "xlcloud:monitoringCluster"
          },
          "xlcloud:monitorIP": {
            "Fn::GetAtt": [
              "Monitor",
              "Outputs.MonitorIP"
            ]
          },
          "xlcloud:brokerPassword": {
            "Ref": "xlcloud:brokerPassword"
          },
          "xlcloud:defaultImageId": {
            "Ref": "xlcloud:defaultImageId"
          }
        },
        "TimeoutInMinutes": "40",
        "TemplateURL": "/home/kszafran/heat-templates/Slurm1392979184605.template"
      }
    }
  }
}

Get Parameter Values

Gets values of the parameters of a specified stack.

Resource: GET stacks/{stack_id}/parameters-values

Entitlement: GET accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/parameters-values

Error Response Codes:

  • 404 – stack not found

Example Request: GET http://localhost:8080/xlcloud-xms/stacks/1/parameters-values

Example Response: 200

{
  "parametersValues": [
    {
      "value": "m1.xlarge",
      "name": "xlcloud:defaultInstanceType"
    },
    {
      "value": "F19-x86_64-xlcloud",
      "name": "xlcloud:defaultImageId"
    },
    {
      "value": "my_keypair2",
      "name": "xlcloud:defaultKeyName"
    }
  ]
}

Edit Parameter Values

Edits values of stack parameters. The parameters specified in the request body will have their values replaced.

To edit stack parameter values, you need to be a member of the project the stack is in.

Resource: PUT stacks/{stack_id}/parameters-values

Entitlement: PUT accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/parameters-values

Error Response Codes:

  • 400 – one of the parameters is not present in the stack template, stack is paused
  • 403 – you're not a member of the project
  • 404 – stack not found

Example Request: PUT http://localhost:8080/xlcloud-xms/stacks/1/parameters-values

{
  "parametersValues": [
    {
      "name": "xlcloud:defaultInstanceType",
      "value": "m1.tiny"
    }
  ]
}

Example Response: 200

{
  "parametersValues": [
    {
      "value": "m1.tiny",
      "name": "xlcloud:defaultInstanceType"
    },
    {
      "value": "F19-x86_64-xlcloud",
      "name": "xlcloud:defaultImageId"
    },
    {
      "value": "my_keypair2",
      "name": "xlcloud:defaultKeyName"
    }
  ]
}

Delete Stack

Deletes a stack. Only stopped stacks can be deleted.

Resource: DELETE stacks/{stack_id}

Entitlement: DELETE accounts/{account_id}/projects/{project_id}/stacks/{stack_id}

Error Response Codes:

  • 400 – stack is not stopped

Example Request: DELETE http://localhost:8080/xlcloud-xms/stacks/11

Example Response: 204
(no content)

Layers

Layers are fundamental parts of a stack. Technically, layers are nested stacks, and so they also have AWS templates associated with them. Within a layer, all instances belong to the same subnet, and share the same lifecycle configuration. The lifecycle of a stack is divided into several phases. For each phase a list of recipes – called a "runlist" – is defined. When the stack enters a phase, all recipes from the relevant runlist are executed. Available phases are:

  • setup – executed only when the stack first starts, it cannot be triggered by an event
  • configure
  • deploy
  • undeploy
  • suspend
  • resume
  • shutdown

Except for the "setup" phase, all phases are triggered by corresponding stack events.

Each layer also has a security group defined, that prevents traffic to and from outside the layer subnet.

XLcloud layer templates are composed of the following resources:

*XLcloud-specific parameters – a set of parameters similar to that of a stack. These values can be overridden for individual instances. If not, they will be used for all instances within the layer. User can either specify an explicit value for a parameter (through the parameter's current value) or allow the layer to inherit stack defaults. The following list defines all custom layer parameters used in XLcloud:

    • xlcloud:defaultImageId – defines the default Glance image name for the layer. Images have to be specified in an XLcloud image catalog, either public or private.
    • xlcloud:defaultInstanceType – defines the default instance type for the layer. Instance type has to be a valid Nova Flavor defined in Nova.
    • xlcloud:layerSubnetUuid – provides the identifier of a subnet this layer is assigned to. Actual value of this parameter is set when the user assigns the layer to one of the subnets (or when the stack is created, in which case layers are automatically assigned to the default subnet).
    • xlcloud:reservationId – ID of the lease reservation the layer is to be started within. This parameter should not be included in a blueprint, it's added/removed automatically when assigning/removing a layer to/from a lease.
    • xlcloud:stackId – OpenStack/Heat ID of the stack. It's used in instance tags (to pass information about the stack in Ceilometer events).
    • xlcloud:brokerAddress – defines the address (usually IP) of the project broker instance. It has to be an externally-reachable address (hence usually a floating IP) of the project broker stack.
    • xlcloud:brokerPort – defines the port of the project broker. In current implementation (using RabbitMQ as the project broker) its default value is always the same – 63613.
    • xlcloud:brokerUsername, xlcloud:brokerPassword – they define credentials necessary to use the project broker.
      *Heat resources – a set of resources within the layer. A standard layer usually has the following resources defined:
      AWS::AutoScaling::LaunchConfiguration or AWS::EC2::Instance – the resource representing layer instances that can or cannot scale.
    • AWS::AutoScaling::AutoScalingGroup – one or more scaling groups that define how the instance should scale (e.g. load-based scaling with min/max size and appropriate scaling policies)
    • AWS::AutoScaling::ScalingPolicy – defines rules for scaling groups (e.g. scaling based on memory usage defined by one or more AWS::CloudWatch::Alarm resources)
    • AWS::EC2::SecurityGroup – defines a routing table for the instances. Opens ports to appropriate subnets (user defines the subnets in the security group rules, and XMS translates it to subnet CIDR). Additionally, user can manually specify security group rule CIDR (e.g. 0.0.0.0/0 to enable traffic from any IP).xlcloud:defaultKeyName – defines the default OS keypair name for the layer.
  • Lifecycle Management – a set of lifecycle phases (or event types) that this layer should react to and a set of recipes assigned to these phases. When an event is triggered in XSA (e.g. application deployment through XMS), the appropriate runlist will be called on stack instances (through the xlc-mco-agent installed on every instance).
  • Subnet: a Neutron subnet this layer is assigned to. It is always defined as a reference through the xlcloud:layerSubnetUuid parameter. All instances in this layer should be connected to this subnet (through SubnetId parameter). All autoscaling groups within this layer should have this subnet defined as the VPCZoneIdentifier parameter.
  • Outputs – template outputs that can be passed to the users through stack outputs.

Layers have the following fields:

  • id – unique identifier
  • name – name of the layer
  • stackId – identifier of the stack this layer belongs to
  • accountId – identifier of the account this layer's stack belong to
  • template – template of the layer
  • parametersValue – current values of the layer parameters
    • parametersValues – list of current values
      • name – name of the parameter
      • value – value of the parameter
  • setupRunlist – runlist associated with the "setup" phase
    • phase – name of the associated phase
    • recipes – list of recipes to execute
      • name – name of the recipe
    • attributes – list of values of cookbook attributes
      • key – attribute name
      • value – attribute value
  • deployRunlist – runlist associated with the "deploy" phase, see "setupRunlist" for the inner structure of this field
  • undeployRunlist – runlist associated with the "undeploy" phase, see "setupRunlist" for the inner structure of this field
  • suspendRunlist – runlist associated with the "suspend" phase, see "setupRunlist" for the inner structure of this field
  • resumeRunlist – runlist associated with the "resume" phase, see "setupRunlist" for the inner structure of this field
  • shutdownRunlist – runlist associated with the "shutdown" phase, see "setupRunlist" for the inner structure of this field
  • chefFile – defines the Cheffile that will be created on instances
    • cookbooks – list of cookbooks that need to be downloaded by Chef
      • cookbook – name of the cookbook
      • git – address of the cookbook repository

Create Empty Layer

Creates a new layer within a stack without a blueprint. The stack must be stopped. The most basic layer will be created. Such a layer will have an empty lifecycle configuration and no resources, except for a security group with two rules:

  • icmp, from -1 to -1, 0.0.0.0/0
  • tcp, from 22 to 22, 0.0.0.0/0

The layer will be assigned required XLcloud parameters (like "xlcloud:defaultInstanceType") along with their default values (usually references to their counterparts in the stack). Value of the "xlcloud:layerSubnetUuid" parameter will be set to the UUID of the default subnet. Values of layer parameters can be passed using this method. Unrecognized parameters will be ignored.

If the modified stack was created from a blueprint, it's origin will be changed to "customized from blueprint".

Resource: POST stacks/{stack_id}/layers/freehand

Entitlement: POST accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/layers/freehand

Required Fields:

  • name – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter

Error Response Codes:

  • 400 – stack is not stopped, layer blueprint is not independent (belongs to a stack blueprint)
  • 404 – stack not found
  • 409 – a layer with the same name already exists in the stack

Example Request: POST http://localhost:8080/xlcloud-xms/stacks/9/layers/freehand

{
  "name": "my_layer2",
  "parametersValues": {
    "parametersValues": [
      {
        "name": "xlcloud:defaultInstanceType",
        "value": "F20"
      }
    ]
  }
}

Example Response: 200

{
  "parametersValues": {
    "parametersValues": [
      {
        "value": "50e0c97a-46d8-4c32-87fa-8bf2de9febb4",
        "name": "xlcloud:layerSubnetUuid"
      },
      {
        "value": "F20",
        "name": "xlcloud:defaultInstanceType"
      },
      {
        "value": {
          "Ref": "xlcloud:defaultImageId"
        },
        "name": "xlcloud:defaultImageId"
      },
      {
        "value": {
          "Ref": "xlcloud:defaultKeyName"
        },
        "name": "xlcloud:defaultKeyName"
      },
      {
        "value": {
          "Ref": "xlcloud:brokerAddress"
        },
        "name": "xlcloud:brokerAddress"
      },
      {
        "value": {
          "Ref": "xlcloud:brokerPort"
        },
        "name": "xlcloud:brokerPort"
      },
      {
        "value": {
          "Ref": "xlcloud:brokerUsername"
        },
        "name": "xlcloud:brokerUsername"
      },
      {
        "value": {
          "Ref": "xlcloud:brokerPassword"
        },
        "name": "xlcloud:brokerPassword"
      },
      {
        "value": {
          "Ref": "AWS::StackId"
        },
        "name": "xlcloud:stackId"
      }
    ]
  },
  "name": "my_layer5",
  "accountId": 100,
  "template": {
    "Parameters": {
      "xlcloud:defaultKeyName": {
        "Description": "Name of an existing EC2 KeyPair to enable SSH access",
        "Type": "String"
      },
      "xlcloud:brokerPort": {
        "Description": "RabbitMQ broker port",
        "Type": "String"
      },
      "xlcloud:brokerAddress": {
        "Description": "RabbitMQ broker address",
        "Type": "String"
      },
      "xlcloud:defaultInstanceType": {
        "Description": "Default instance type (flavor) for instances in this stack",
        "Type": "String",
        "ConstraintDescription": "must be a valid XLcloud instance type."
      },
      "xlcloud:brokerUsername": {
        "Description": "RabbitMQ broker username",
        "Type": "String"
      },
      "xlcloud:layerSubnetUuid": {
        "Description": "Project's network identifier",
        "Type": "String"
      },
      "xlcloud:stackId": {
        "Description": "The identifier of the parent stack",
        "Type": "String"
      },
      "xlcloud:brokerPassword": {
        "Description": "RabbitMQ broker password",
        "Type": "String"
      },
      "xlcloud:defaultImageId": {
        "Description": "Default image name for instances in this stack",
        "Type": "String",
        "ConstraintDescription": "must be a valid XLcloud image name."
      }
    },
    "Description": "XLcloud layer",
    "AWSTemplateFormatVersion": "2010-09-09",
    "Resources": {
      "DefaultSecurityGroup": {
        "Type": "AWS::EC2::SecurityGroup",
        "Properties": {
          "SecurityGroupIngress": [
            {
              "IpProtocol": "icmp",
              "ToPort": "-1",
              "FromPort": "-1",
              "CidrIp": "0.0.0.0/0"
            },
            {
              "IpProtocol": "tcp",
              "ToPort": "22",
              "FromPort": "22",
              "CidrIp": "0.0.0.0/0"
            }
          ],
          "GroupDescription": "Enable SSH access "
        }
      }
    }
  },
  "setupRunlist": {
    "phase": "setup"
  },
  "configureRunlist": {
    "phase": "configure"
  },
  "deployRunlist": {
    "phase": "deploy"
  },
  "undeployRunlist": {
    "phase": "undeploy"
  },
  "shutdownRunlist": {
    "phase": "shutdown"
  },
  "suspendRunlist": {
    "phase": "suspend"
  },
  "resumeRunlist": {
    "phase": "resume"
  },
  "chefFile": {},
  "stackId": 9
}

Create Layer from Blueprint

Creates a new layer within a stack based on a blueprint. The stack must be stopped. If the name of the layer is not specified, the name of the layer blueprint will be used.

The layer will be assigned required XLcloud parameters (like "xlcloud:defaultInstanceType") along with their default values (usually references to their counterparts in the stack). Value of the "xlcloud:layerSubnetUuid" parameter will be set to the UUID of the default subnet. Values of layer parameters can be passed using this method. Unrecognized parameters will be ignored.

If the modified stack was created from a blueprint, it's origin will be changed to "customized from blueprint".

In the example response, the layer template has been omitted.

Resource: POST stacks/{stack_id}/layers?blueprintId={layer_blueprint_id}

Entitlement: (two entitlements are required)

  • POST accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/layers
  • to create a layer from a public blueprint: GET layer-blueprints/{layer_blueprint_id}
  • to create a layer from a private blueprint: GET accounts/{account_id}/layer-blueprints/{layer_blueprint_id}

Required Query Parameters:

  • blueprintId

Error Response Codes:

  • 400 – stack is not stopped, layer blueprint is not independent (is a part of a stack blueprint), layer name is invalid (name can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter)
  • 404 – stack not found
  • 409 – a layer with the same name already exists in the stack

Example Request: POST http://localhost:8080/xlcloud-xms/stacks/9/layers?blueprintId=2

{
  "name": "my_layer3",
  "parametersValues": {
    "parametersValues": [
      {
        "name": "xlcloud:defaultInstanceType",
        "value": "F20"
      }
    ]
  }
}

Example Response: 200

{
  "parametersValues": {
    "parametersValues": [
      {
        "value": "50e0c97a-46d8-4c32-87fa-8bf2de9febb4",
        "name": "xlcloud:layerSubnetUuid"
      },
      {
        "value": "F20",
        "name": "xlcloud:defaultInstanceType"
      },
      {
        "value": {
          "Ref": "xlcloud:defaultImageId"
        },
        "name": "xlcloud:defaultImageId"
      },
      {
        "value": {
          "Ref": "xlcloud:defaultKeyName"
        },
        "name": "xlcloud:defaultKeyName"
      },
      {
        "value": {
          "Ref": "xlcloud:brokerAddress"
        },
        "name": "xlcloud:brokerAddress"
      },
      {
        "value": {
          "Ref": "xlcloud:brokerPort"
        },
        "name": "xlcloud:brokerPort"
      },
      {
        "value": {
          "Ref": "xlcloud:brokerUsername"
        },
        "name": "xlcloud:brokerUsername"
      },
      {
        "value": {
          "Ref": "xlcloud:brokerPassword"
        },
        "name": "xlcloud:brokerPassword"
      },
      {
        "value": {
          "Ref": "AWS::StackId"
        },
        "name": "xlcloud:stackId"
      }
    ]
  },
  "name": "my_layer3",
  "accountId": 100,
  "template": {
    OMITTED
  },
  "stackId": 14
}

Get Layer Details

Gets the details of a specified layer. In the example response layer template has been omitted for brevity.

Resource: GET layers/{layer_id}

Entitlement: GET accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/layers/{layer_id}

Error Response Codes:

*404 – layer not found

Example Request: GET http://localhost:8080/xlcloud-xms/layers/3

Example Response: 200

{
  "id": 3,
  "href": "layers/3",
  "parametersValues": {
    "parametersValues": [
      {
        "value": {
          "Ref": "xlcloud:defaultKeyName"
        },
        "name": "xlcloud:defaultKeyName"
      },
      {
        "value": {
          "Ref": "xlcloud:brokerPort"
        },
        "name": "xlcloud:brokerPort"
      },
      {
        "value": {
          "Ref": "xlcloud:brokerAddress"
        },
        "name": "xlcloud:brokerAddress"
      },
      {
        "value": "2",
        "name": "xlcloud:Computes:size"
      },
      {
        "value": {
          "Ref": "xlcloud:defaultInstanceType"
        },
        "name": "xlcloud:defaultInstanceType"
      },
      {
        "value": {
          "Ref": "xlcloud:brokerUsername"
        },
        "name": "xlcloud:brokerUsername"
      },
      {
        "value": {
          "Ref": "AWS::StackId"
        },
        "name": "xlcloud:stackId"
      },
      {
        "value": {
          "Ref": "xlcloud:brokerPassword"
        },
        "name": "xlcloud:brokerPassword"
      },
      {
        "value": {
          "Ref": "xlcloud:defaultImageId"
        },
        "name": "xlcloud:defaultImageId"
      }
    ]
  },
  "name": "Slurm_Layer",
  "accountId": 100,
  "template": {
    OMITTED
  },
  "setupRunlist": {
    "phase": "setup"
  },
  "configureRunlist": {
    "recipes": [
      {
        "name": "hpc-vc::configure"
      }
    ],
    "phase": "configure"
  },
  "deployRunlist": {
    "recipes": [
      {
        "name": "hpc-vc::deploy"
      }
    ],
    "phase": "deploy"
  },
  "undeployRunlist": {
    "phase": "undeploy"
  },
  "shutdownRunlist": {
    "phase": "shutdown"
  },
  "suspendRunlist": {
    "phase": "suspend"
  },
  "resumeRunlist": {
    "phase": "resume"
  },
  "chefFile": {
    "cookbooks": [
      {
        "cookbook": "hpc-vc",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      },
      {
        "cookbook": "slurm",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      },
      {
        "cookbook": "hostsfile",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      },
      {
        "cookbook": "nfs",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      },
      {
        "cookbook": "line",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      },
      {
        "cookbook": "nfs_export",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      },
      {
        "cookbook": "xsa",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      },
      {
        "cookbook": "glassfish_ark",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      },
      {
        "cookbook": "ark"
      },
      {
        "cookbook": "jdk_ark",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      }
    ]
  },
  "stackId": 14
}

Update Layer Template

Updates the template of a specified layer. The stack must be stopped, and its layers cannot be modified when using this method. The content type used for this request must be template/json. The response content type is also template/json, which means that the Accept header should have the value template/json, or should not be set at all.

If the updated stack was created from a blueprint, its origin will be changed to "customized from blueprint".

Resource: PUT layers/{layer_id}

Entitlement: PUT accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/layers/{layer_id}

Required Headers:

  • Content-Type: template/json

Error Response Codes:

  • 400 – stack is not stopped
  • 404 – layer not found

Example Request: PUT http://localhost:8080/xlcloud-xms/layers/10

{
  "Outputs": {
    "xsaIp": {
      "Description": "IP address of XSA endpoint",
      "Value": {
        "Ref": "LoginIp"
      }
    }
  },
  "Parameters": {
    "xlcloud:brokerPort": {
      "Description": "RabbitMQ broker port",
      "Type": "String"
    },
    "xlcloud:defaultKeyName": {
      "Description": "Name of an existing EC2 KeyPair to enable SSH access",
      "Type": "String"
    },
    "xlcloud:brokerAddress": {
      "Description": "RabbitMQ broker address",
      "Type": "String"
    },
    "xlcloud:brokerUsername": {
      "Description": "RabbitMQ broker username",
      "Type": "String"
    },
    "xlcloud:defaultInstanceType": {
      "Description": "Default instance type (flavor) for instances in this stack",
      "Type": "String",
      "ConstraintDescription": "must be a valid XLcloud instance type."
    },
    "xlcloud:layerSubnetUuid": {
      "Description": "Project's network identifier",
      "Type": "String"
    },
    "xlcloud:stackId": {
      "Description": "The identifier of the parent stack",
      "Type": "String"
    },
    "xlcloud:brokerPassword": {
      "Description": "RabbitMQ broker password",
      "Type": "String"
    },
    "xlcloud:defaultImageId": {
      "Description": "Default image name for instances in this stack",
      "Type": "String",
      "ConstraintDescription": "must be a valid XLcloud image name."
    }
  },
  "Description": "XLcloud layer",
  "AWSTemplateFormatVersion": "2010-09-09",
  "Resources": {
    "DefaultSecurityGroup": {
      "Type": "AWS::EC2::SecurityGroup",
      "Properties": {
        "SecurityGroupIngress": [
          {
            "IpProtocol": "icmp",
            "ToPort": "-1",
            "FromPort": "-1",
            "CidrIp": "0.0.0.0/0"
          },
          {
            "IpProtocol": "tcp",
            "ToPort": "22",
            "FromPort": "22",
            "CidrIp": "0.0.0.0/0"
          }
        ],
        "GroupDescription": "Enable SSH access "
      }
    }
  }
}

Example Response: 200

{
  "Outputs": {
    "xsaIp": {
      "Value": {
        "Ref": "LoginIp"
      },
      "Description": "IP address of XSA endpoint"
    }
  },
  "Parameters": {
    "xlcloud:brokerPort": {
      "Description": "RabbitMQ broker port",
      "Type": "String"
    },
    "xlcloud:defaultKeyName": {
      "Description": "Name of an existing EC2 KeyPair to enable SSH access",
      "Type": "String"
    },
    "xlcloud:brokerAddress": {
      "Description": "RabbitMQ broker address",
      "Type": "String"
    },
    "xlcloud:brokerUsername": {
      "Description": "RabbitMQ broker username",
      "Type": "String"
    },
    "xlcloud:defaultInstanceType": {
      "Description": "Default instance type (flavor) for instances in this stack",
      "Type": "String",
      "ConstraintDescription": "must be a valid XLcloud instance type."
    },
    "xlcloud:layerSubnetUuid": {
      "Description": "Project's network identifier",
      "Type": "String"
    },
    "xlcloud:stackId": {
      "Description": "The identifier of the parent stack",
      "Type": "String"
    },
    "xlcloud:brokerPassword": {
      "Description": "RabbitMQ broker password",
      "Type": "String"
    },
    "xlcloud:defaultImageId": {
      "Description": "Default image name for instances in this stack",
      "Type": "String",
      "ConstraintDescription": "must be a valid XLcloud image name."
    }
  },
  "Description": "XLcloud layer",
  "AWSTemplateFormatVersion": "2010-09-09",
  "Resources": {
    "DefaultSecurityGroup": {
      "Type": "AWS::EC2::SecurityGroup",
      "Properties": {
        "SecurityGroupIngress": [
          {
            "IpProtocol": "icmp",
            "ToPort": "-1",
            "FromPort": "-1",
            "CidrIp": "0.0.0.0/0"
          },
          {
            "IpProtocol": "tcp",
            "ToPort": "22",
            "FromPort": "22",
            "CidrIp": "0.0.0.0/0"
          }
        ],
        "GroupDescription": "Enable SSH access "
      }
    }
  }
}

Edit Parameter Values

Edits values of layer parameters. The parameters specified in the request body will have their values replaced. Only selected parameters (scalability parameters) can be modified when the stack is not running. No parameters can be modified when the stack is paused or pausing. Scalability parameters have the form xlcloud:{scaling_resource_name}:{parameter_name}, where {scaling_resource_name} is the name of a resource of type AWS::AutoScaling::AutoScalingGroup or OS::Heat::InstanceGroup belonging to one of the layer instances, and parameter_name is an arbitrary name, e.g. xlcloud:Computes:size.

Resource: PUT layers/{layer_id}/parameters-values

Entitlement: PUT accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/layers/{layer_id}/parameters-values

Error Response Codes:

  • 400 – one of the specified parameters does not exist in the template, stack is not stopped and one of the specified parameters cannot be updated when the stack is not stopped, the stack is paused or pausing
  • 404 – layer not found

Example Request: PUT http://localhost:8080/xlcloud-xms/layers/1/parameters-values(% class="mybox" %)

{
  "parametersValues": [
    {
      "name": "xlcloud:defaultInstanceType",
      "value": "m1.tiny"
    }
  ]
}

Example Response: 200

{
  "parametersValues": [
    {
      "value": "m1.tiny",
      "name": "xlcloud:defaultInstanceType"
    }
  ]
}

Add Instance to Layer

Adds a new instance to a layer. The stack must be stopped. The added instance can be either scalable or not – this is specified by the "scalable" query param, default value is "true". Some default resources and an appropriate runlist are created for the added instance. In case of a scalable instance the resources are:

  • AWS::AutoScaling::LaunchConfiguration
  • AWS::AutoScaling::AutoScalingGroup
  • AWS::CloudFormation::WaitCondition
  • AWS::CloudFormation::WaitConditionHandle

And in case of non-scalable instances:

  • AWS::EC2::Instance
  • AWS::CloudFormation::WaitCondition
  • AWS::CloudFormation::WaitConditionHandle

Resource: POST layers/{layer_id}/instances?scalable={boolean}

Entitlement: POST accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/layers/{layer_id}/instances

Error Response Codes:

  • 400 – stack is not stopped
  • 404 – layer not found
  • 409 – an instance with the same name already exists in the layer

Example Request: POST http://localhost:8080/xlcloud-xms/stacks/16/layers/instances?scalable=false(% class="mybox" %)

{
  "name": "my_instance6"
}

Example Response: 200

{
  "resources": {
    "resource": [
      {
        "instance": {
          "metadata": {
            "cfnInit": {
              "configs": [
                {
                  "name": "config",
                  "files": {
                    "files": [
                      {
                        "content": {
                          "run_list": [
                            "role[ganglia-agent]",
                            "role[hpc-vc]",
                            "recipe[hpc-vc::setup]"
                          ]
                        },
                        "name": "/etc/chef/setup-runlist.json"
                      },
                      {
                        "content": {
                          "Fn::Join": [
                            "\n",
                            [
                              "file_cache_path  '/var/chef/cache'",
                              "cookbook_path    [ '/var/chef/chef-repo/cookbooks' ]",
                              "role_path    [ '/var/chef/chef-repo/roles' ]",
                              "log_level :info",
                              "log_location STDOUT",
                              "ssl_verify_mode :verify_none",
                              "http_proxy 'http://10.197.217.62:3128'",
                              "https_proxy 'http://10.197.217.62:3128'",
                              "no_proxy '127.0.0.1,localhost'"
                            ]
                          ]
                        },
                        "name": "/etc/chef/solo.rb"
                      },
                      {
                        "content": {},
                        "name": "/etc/chef/resume-runlist.json"
                      },
                      {
                        "content": {
                          "run_list": [
                            "role[hpc-vc]",
                            "recipe[hpc-vc::deploy]"
                          ]
                        },
                        "name": "/etc/chef/deploy-runlist.json"
                      },
                      {
                        "content": {
                          "Fn::Join": [
                            "\n",
                            [
                              "#!/usr/bin/env ruby",
                              "site 'http://community.opscode.com/api/v1'",
                              "cookbook 'ohai'",
                              "cookbook 'mcollective',",
                              "    :git => 'http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git',",
                              "    :path => 'mcollective'",
                              "cookbook 'xlc-mco-agent',",
                              "    :git => 'http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git',",
                              "    :path => 'xlc-mco-agent'",
                              "cookbook 'hpc-vc',",
                              "    :git => 'http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git',",
                              "    :path => 'hpc-vc'",
                              "cookbook 'slurm',",
                              "    :git => 'http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git',",
                              "    :path => 'slurm'",
                              "cookbook 'hostsfile',",
                              "    :git => 'http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git',",
                              "    :path => 'hostsfile'",
                              "cookbook 'line',",
                              "    :git => 'http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git',",
                              "    :path => 'line'",
                              "cookbook 'nfs',",
                              "    :git => 'http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git',",
                              "    :path => 'nfs'",
                              "cookbook 'nfs_export',",
                              "    :git => 'http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git',",
                              "    :path => 'nfs_export'",
                              "cookbook 'ganglia',",
                              "    :git => 'http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git',",
                              "    :path => 'ganglia'",
                              "cookbook 'jdk_ark',",
                              "    :git => 'http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git',",
                              "    :path => 'jdk_ark'",
                              "cookbook 'glassfish_ark',",
                              "    :git => 'http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git',",
                              "    :path => 'glassfish_ark'",
                              "cookbook 'xsa',",
                              "    :git => 'http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git',",
                              "    :path => 'xsa'"
                            ]
                          ]
                        },
                        "name": "/var/chef/chef-repo/Cheffile",
                        "group": "root",
                        "owner": "root",
                        "mode": "00400"
                      },
                      {
                        "content": {},
                        "name": "/etc/chef/shutdown-runlist.json"
                      },
                      {
                        "content": {},
                        "name": "/etc/chef/suspend-runlist.json"
                      },
                      {
                        "content": {
                          "Fn::Join": [
                            "\n",
                            [
                              "cookbook_path  [ '/var/chef/chef-repo/cookbooks' ]",
                              "role_path    [ '/var/chef/chef-repo/roles' ]",
                              "http_proxy 'http://10.197.217.62:3128'",
                              "https_proxy 'http://10.197.217.62:3128'",
                              "no_proxy '127.0.0.1,localhost'"
                            ]
                          ]
                        },
                        "name": "/root/.chef/knife.rb"
                      },
                      {
                        "content": {},
                        "name": "/etc/chef/undeploy-runlist.json"
                      },
                      {
                        "content": {
                          "run_list": [
                            "role[hpc-vc]",
                            "recipe[hpc-vc::configure]"
                          ]
                        },
                        "name": "/etc/chef/configure-runlist.json"
                      },
                      {
                        "content": {
                          "json_class": "Chef::Role",
                          "run_list": [
                            "recipe[ohai]",
                            "recipe[mcollective::server]",
                            "recipe[xlc-mco-agent]"
                          ],
                          "chef_type": "role",
                          "override_attributes": {
                            "mcollective": {
                              "connector": "rabbitmq",
                              "enable_puppetlabs_repo": false,
                              "psk": "supersecret",
                              "factsource": "ohai",
                              "stomp": {
                                "port": {
                                  "Ref": "xlcloud:brokerPort"
                                },
                                "username": {
                                  "Ref": "xlcloud:brokerUsername"
                                },
                                "hostname": {
                                  "Ref": "xlcloud:brokerAddress"
                                },
                                "password": {
                                  "Ref": "xlcloud:brokerPassword"
                                }
                              }
                            }
                          },
                          "description": "This is a role to install ohai + mcollective server + xlcloud agent.",
                          "name": "xlc-mco-agent",
                          "default_attributes": {}
                        },
                        "name": "/var/chef/chef-repo/roles/xlc-mco-agent.json",
                        "group": "root",
                        "owner": "root",
                        "mode": "00400"
                      }
                    ]
                  }
                }
              ]
            }
          },
          "name": "my_instance6",
          "instanceType": {
            "Ref": "xlcloud:defaultInstanceType"
          },
          "imageId": {
            "Ref": "xlcloud:defaultImageId"
          },
          "userData": {
            "Fn::Base64": {
              "Fn::Join": [
                "",
                [
                  "#!/bin/bash -xe\n",
                  "export HOME=/root\n",
                  "source /etc/profile.d/proxy.sh\n",
                  "pip install upgrade heat-cfntools\n",
                 "/bin/cfn-create-aws-symlinks\n",
                 "/opt/aws/bin/cfn-init\n",
                 "cd /var/chef/chef-repo\n",
                 "/usr/local/bin/librarian-chef install clean verbose\n",
                 "/bin/chef-solo -c /etc/chef/solo.rb -j /etc/chef/setup-runlist.json -L /var/log/chef-solo.log\n",
                 "cfn-signal -e 0 '",
                 {
                   "Ref": "my_instance6_waitConditionHandle"
                 },
                 "'\n"
               ]
             ]
           }
         },
         "keyName": {
           "Ref": "xlcloud:defaultKeyName"
         },
         "securityGroups": [
           "{\"Ref\":\"DefaultSecurityGroup\"}"
         ],
         "tags": [
           {
             "key": "StackId",
            n "value": "{\"Ref\":\"AWS::StackId\"}"
           }
         ]
       }
     }
   ]
 },
 "eips": {
   "eip": []
 },
 "eipAssociations": {
   "eipAssociation": []
 },
 "scalingGroups": {
   "scalingGroup": []
 },
 "waitCondition": {
   "waitCondition": {
     "dependsOn": "my_instance6",
     "name": "my_instance6_waitCondition",
     "count": "1",
     "handle": "my_instance6_waitConditionHandle",
     "timeout": 2400
   }
 },
 "waitConditionHandle": {
   "waitConditionHandle": {
     "name": "my_instance6_waitConditionHandle"
   }
 },
 "name": "my_instance6",
 "instanceType": "non-scalable"
}

Update Runlist

Updates a runlist of a given phase in a specified layer. Contents of the runlist will be replaced. To add or remove recipes, modify the "recipes" list. To set or unset values of recipe attributes, modify the "attributes" list.

As the recipes are added and/or removed, a new Cheffile is generated for the layer.

The "phase" query parameter is used to specify runlist of what phase is to be updated. Possible values are:

  • setup
  • configure
  • deploy
  • undeploy
  • suspend
  • resume
  • shutdown

Resource: PUT layers/{layer_id}/runlists?phase={phase_name}

Entitlement: PUT accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/layers/{layer_id}/runlists

Required Query Parameters:

  • phase

Error Response Codes:

  • 404 – layer not found

Example Request: PUT http://localhost:8080/xlcloud-xms/layers/1/runlists

{
  "recipes": [
    {
      "name": "hpc-vc::setup"
    },
    {
      "name": "rabbitmq"
    }
  ],
  "attributes": [
    {
      "key": "rabbitmq/mnesiadir",
      "value": "the_path2"
    },
    {
      "key": "rabbitmq/disabled_plugins",
      "value": []
    }
  ]
}

Example Response: 200

{
  "recipes": [
    {
      "name": "hpc-vc::setup"
    },
    {
      "name": "rabbitmq"
    }
  ],
  "attributes": [
    {
      "key": "rabbitmq/mnesiadir",
      "value": "the_path2"
    },
    {
      "key": "rabbitmq/disabled_plugins",
      "value": []
    }
  ],
  "phase": "setup"
}

Assign Layer to Lease

Assigns a layer to a lease. The stack must be stopped.

Note that in both the resource and the entitlement path below, it says "lease", not "leases".

Resource: PUT layers/{layer_id}/lease/{lease_id}

Entitlement: PUT accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/layers/{layer_id}/lease/{lease_id}

Error Response Codes:

  • 400 – the stack is not stopped
  • 404 – layer not found, lease not found

Example Request: PUT http://localhost:8080/xlcloud-xms/layers/21/lease/df24f50f-a577-4c0d-bc4a-6337fe81c892

Example Response: 204
(no content)

Remove Layer from Lease

Removes a layer from a lease. The stack must be stopped.

Note that in both the resource and the entitlement path below, it says "lease", not "leases".

Resource: DELETE layers/{layer_id}/lease

Entitlement: DELETE accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/layers/{layer_id}/lease

Error Response Codes:

  • 400 – the stack is not stopped
  • 404 – layer not found

Example Request: DELETE http://localhost:8080/xlcloud-xms/layers/21/lease

Example Response: 204
(no content)

Delete Layer

Deletes a layer. The stack must be stopped.

If the modified stack was created from a blueprint, it's origin will be changed to "customized from blueprint".

Resource: DELETE layers/{layer_id}

Entitlement: DELETE accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/layers/{layer_id}

Error Response Codes:

  • 400 – stack is not stopped

Example Request: DELETE http://localhost:8080/xlcloud-xms/layers/10

Example Response: 204
(no content)

Sessions

A session is related to the stack in Heat. Only stacks that are not stopped have a session associated with them. There are a few terminal states a stack can be in:

  • stack can be stopped – does not exist in Heat, and is not taking any resources
  • stack can be running – the stack is active and fully operational
  • stack can be suspended – is not working nor using any resources, and its physical state is saved to be resumed later
  • stack can be failed – "Configure" event or some operation failed in Heat and the stack is unusable

Current stack status is returned in the session. All possible states are:

  • stopped – the stack is stopped, very unlikely to be returned (only when Heat returns the DELETE_COMPLETE status), usually 404 is returned when the stack is stopped
  • starting – the stack is starting in Heat
  • configuring – the "Configure" or "Resume" event is being processed
  • running – the stack is running
  • updating – the stack is updating in Heat (e.g. is being scaled)
  • suspending – the "Suspend" event is being processed
  • pausing – the stack is suspending in Heat
  • paused – the stack is suspended
  • resuming – the stack is resuming in Heat
  • shuttingDown – the "Shutdown" event is being processed
  • stopping – the stack is stopping in Heat
  • rollingBack – there were some issues in Heat, and the changes are being reverted
  • failedOnStarting – the stack failed to start in Heat
  • failedOnUpdate – the stack failed to update in Heat
  • failedOnPause – the stack failed to suspend in Heat
  • failedOnResume – the stack failed to resume in Heat
  • failedOnStopping – the stack failed to stop in Heat
  • failedOnRollback – the stack failed to rollback in Heat
  • failedOnConfigure – the stack is running in Heat, but the most recent "Configure" event failed

Sessions have the following fields:

  • physicalId – identifier of the stack in Heat
  • status – status of the stack
  • statusReason – explanation of the current status
  • outputs – values of the stack outputs returned by Heat
  • resources – billable resources associated with the running stack

Start Session

Starts a specified stack, creating a new session.

You need to be a member of the stack project in order to perform this operation, and the project must be
active.

Resource: POST stacks/{stack_id}/sessions

Entitlement: POST accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/sessions

Error Response Codes:

  • 400 – project is not active, one of the leases is not active, does not exist or does not belong to the stack project
  • 403 – you're not a member of the stack project
  • 404 – stack not found
  • 409 – the stack is already started

Example Request: POST http://localhost:8080/xlcloud-xms/stacks/1/sessions

Example Response: 200

{
  "outputs": {},
  "status": "configuring",
  "statusReason": "Stack create completed successfully",
  "physicalId": "9e2ba548-e64f-4036-804b-2889b009ccce"
}

Get Session Details

Gets the details of a specified session.

You need to be a member of the stack project in order to perform this operation.

Resource: GET stacks/{stack_id}/sessions/current

Entitlement: GET accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/sessions/current

Error Response Codes:

  • 403 – you're not a member of the stack project
  • 404 – stack not found, stack is stopped

Example Request: GET http://localhost:8080/xlcloud-xms/stacks/1/sessions/current

Example Response: 200

{
  "outputs": {
    "output": [
      {
        "key": "xlcloud:xsaAddress",
        "description": "XSA URL",
        "value": "http://10.197.217.161:8080/xsa"
      },
      {
        "key": "MonitorURL",
        "description": "Public URL of the monitoring node",
        "value": "http://10.197.217.160/ganglia"
      }
    ]
  },
  "resources": [
    {
      "logicalResourceId": "Slurm",
      "resourceStatus": "running",
      "physicalResourceId": "20f8cf1d-5c4c-4d4e-844f-ae3edf520c0c",
      "resourceType": "AWS::CloudFormation::Stack"
    },
    {
      "logicalResourceId": "Monitor",
      "resourceStatus": "running",
      "physicalResourceId": "44202b99-adc6-4203-b9b8-7ec194fdb627",
      "resourceType": "AWS::CloudFormation::Stack"
    },
    {
      "logicalResourceId": "v2dwlyzeg3sx",
      "resourceStatus": "running",
      "physicalResourceId": "1bbbe9e7-fd9c-4fad-bc92-f9d9732fee1c",
      "resourceType": "AWS::EC2::Instance"
    }
  ],
  "status": "shuttingDown",
  "statusReason": "Stack create completed successfully",
  "physicalId": "72c1728f-7c3d-4472-99d6-a36085ddc47a"
}

Update Session

Changes the stack status. Allows to suspend and resume the stack. To do this, the current stack status must be either "running" or "paused".

You need to be a member of the stack project in order to perform this operation, and the project must be active.

Resource: PUT stacks/{stack_id}/sessions/current

Entitlement: PUT accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/sessions/current

Required Fields:

  • status – must be either "paused" (to suspend the stack) or "running" (to resume it)

Error Response Codes:

  • 400 – project is not active, current status is invalid
  • 403 – you're not a member of the stack project
  • 404 – stack not found, stack is stopped

Example Request: PUT http://localhost:8080/xlcloud-xms/stacks/1/sessions/current

{
  "status": "paused"
}

Example Response: 200

{
  "outputs": {},
  "resources": [],
  "status": "running",
  "statusReason": "Stack create completed successfully",
  "physicalId": "aa1d23c2-b895-4c90-9ecc-07efd31653fd"
}

Stop Session

Stops a specified stack, deleting the current session. If the stack status is other than "stopped", "running", "paused", or "failedOn*" (except for "failedOnConfigure"), no "Shutdown" event will be sent, and the stack will be stopped directly in Heat.

You need to be a member of the stack project in order to perform this operation.

Resource: DELETE stacks/{stack_id}/sessions/current

Entitlement: DELETE accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/sessions/current

Error Response Codes:

  • 403 – you're not a member of the stack project
  • 404 – stack not found

Example Request: DELETE http://localhost:8080/xlcloud-xms/stacks/1/sessions/current

Example Response: 204
(no content)

Events

During the stack lifecycle several events take place. They are related to stack status changes, as well as deploying applications. When an event occurs, a message is sent to all instances in the stack (or in one of its layers if it's a "deploy" event), causing them to react according to the runlists defined in their lifecycles. The following events are defined in XMS:

  • CONFIGURE – sent after the stack finishes starting or updating in Heat, and after the RESUME event is processed
  • SUSPEND – sent when the stack is to be suspended, before it is suspended in Heat
  • RESUME – sent after the stack finishes resuming in Heat
  • DEPLOY – sent when an application is deployed on one of the stack layers; it's also sent for each deployed application after the CONFIGURE event is processed
  • UNDEPLOY – sent when an application is underplayed
  • SHUTDOWN – sent when the stack is to be stopped, before it is stopped in Heat

Events have outputs which present results of the event for each instance.

Events have the following fields:

  • id – unique identifier
  • type – type of the event
  • status – event status, either "COMPLETED" or "FAILED"
  • eventDate – time of sending the event
  • exitCode – exit code of the MCollective
  • stack – stack this event was sent to
  • layer – layer this event was sent to, only for deployment and undeployment events
  • runlistAttributes – list of application deployment attributes
    • key – attribute name
    • value – attribute value
  • eventOutput – list of execution outputs of individual instances
    • action – action that was sent in the message, e.g. "configure"
    • sender – name of the instance receiving the message
    • agent – MCollective agent receiving the message
    • statuscode – exit code of the event execution
    • statusmsg – message explaining the status code
  • data – additional information about the execution
    • exitcode – exit code of the event execution
    • stdout – output written to the standard output
    • stderr – output written to the standard error output

List Stack Events

Lists all events of a specified stack.

Resource: GET stacks/{stack_id}/events

Entitlement: GET accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/events

Error Response Codes:

  • 404 – stack not found

Example Request: GET http://localhost:8080/xlcloud-xms/stacks/1/events

Example Response: 200

{
  "event": [
    {
      "runlistAttributes": [],
      "stack": {
        "id": 118,
        "href": "stacks/118",
        "name": "kaef_slurm14"
      },
      "eventOutput": [
        {
          "data": {
            "exitcode": 0
          },
          "action": "configure",
          "sender": "i-00000d33",
          "agent": "xlcloud",
          "statuscode": 0,
          "statusmsg": "OK"
        }
      ],
      "id": 202,
      "href": "stacks/118/events/202",
      "type": "CONFIGURE",
      "eventDate": "2014-01-23T13:50:36",
      "status": "COMPLETED",
      "exitCode": 0
    },
    {
      "runlistAttributes": [
        {
          "key": "xlc-rails/db/name",
          "value": "redmine"
        },
        {
          "key": "xlc-rails/app_name",
          "value": "redmine"
        },
        {
          "key": "xlc-rails/repository",
          "value": "https://github.com/redmine/redmine"
        },
        {
          "key": "xlc-rails/rake_tasks",
          "value": [
            "generate_secret_token"
          ]
        },
        {
          "key": "xlc-rails/bundler/supported",
          "value": "true"
        },
        {
          "key": "xlc-rails/bundler/without_groups",
          "value": [
            "rmagick"
          ]
        },
        {
          "key": "xlc-rails/db/host",
          "value": "10.0.0.15"
        },
        {
          "key": "xlc-rails/db/username",
          "value": "redmine"
        },
        {
          "key": "xlc-rails/db/password",
          "value": "redmine"
        }
      ],
      "stack": {
        "id": 118,
        "href": "stacks/118",
        "name": "kaef_slurm14"
      },
      "layer": {
        "id": 207,
        "href": "layers/207",
        "name": "Slurm"
      },
      "eventOutput": [
        {
          "data": {
            "exitcode": 1,
            "stdout": "\n================================================================================\nError executing action `deploy` on resource 'deploy_revision[redmine]'\n================================================================================\n\nChef::Exceptions::Exec\n\nrake db:migrate returned 1, expected 0\n\nResource Declaration:\n-\n# In /var/chef/chef-repo/cookbooks/application/providers/default.rb\n\n123:   @deploy_resource = send(new_resource.strategy.to_sym, new_resource.name) do\n124:     action force ? :force_deploy : :deploy\n125:     scm_provider new_resource.scm_provider\n126:     revision new_resource.revision\n127:     repository new_resource.repository\n128:     enable_submodules new_resource.enable_submodules\n129:     user new_resource.owner\n130:     group new_resource.group\n131:     deploy_to new_resource.path\n132:     ssh_wrapper \"#{new_resource.path}/deploy-ssh-wrapper\" if new_resource.deploy_key\n133:     shallow_clone new_resource.shallow_clone\n134:     rollback_on_error new_resource.rollback_on_error\n135:     all_environments = ([new_resource.environment]+new_resource.sub_resources.map{|res| res.environment}).inject({}){|acc, val| acc.merge(val)}\n136:     environment all_environments\n137:     migrate new_resource.migrate\n138:     all_migration_commands = ([new_resource.migration_command]+new_resource.sub_resources.map{|res| res.migration_command}).select{|cmd| cmd && !cmd.empty?}\n139:     migration_command all_migration_commands.join(' && ')\n140:     restart_command do\n141:       ([new_resource]+new_resource.sub_resources).each do |res|\n142:         cmd = res.restart_command\n143:         if cmd.is_a? Proc\n144:           app_provider.deploy_provider.instance_eval(&cmd) # @see libraries/default.rb\n145:         elsif cmd && !cmd.empty?\n146:           execute cmd do\n147:             user new_resource.owner\n148:             group new_resource.group\n149:             environment all_environments\n150:           end\n151:         end\n152:       end\n153:     end\n154:     purge_before_symlink (new_resource.purge_before_symlink + new_resource.sub_resources.map(&:purge_before_symlink)).flatten\n\nCompiled Resource:\n\n# Declared in /var/chef/chef-repo/cookbooks/application/providers/default.rb:123:in `run_deploy'\n\ndeploy_revision(\"redmine\") do\n  provider Chef::Provider::Deploy::Revision\n  action [:deploy]\n  updated true\n  updated_by_last_action true\n  retries 0\n  retry_delay 2\n  deploy_to \"/var/www/redmine\"\n  environment {\"RAILS_ENV\"=>\"production\", \"LC_ALL\"=>\"C\"}\n  repository_cache \"cached-copy\"\n  symlink_before_migrate {\"database.yml\"=>\"config/database.yml\"}\n  revision \"HEAD\"\n  migrate true\n  rollback_on_error true\n  remote \"origin\"\n  shallow_clone true\n  scm_provider Chef::Provider::Git\n  keep_releases 5\n  cookbook_name :\"xlc-rails\"\n  repo \"https://github.com/redmine/redmine\"\n  migration_command \"rake db:migrate\"\n  restart_command #<Proc:0x007f13288e8270@/var/chef/chef-repo/cookbooks/application/providers/default.rb:140>\n  before_migrate #<Proc:0x007f13288f0268@/var/chef/chef-repo/cookbooks/application/providers/default.rb:160>\n  before_symlink #<Proc:0x007f13288f7e50@/var/chef/chef-repo/cookbooks/application/providers/default.rb:163>\n  before_restart #<Proc:0x007f13288f7978@/var/chef/chef-repo/cookbooks/application/providers/default.rb:166>\n  after_restart #<Proc:0x007f13288f7798@/var/chef/chef-repo/cookbooks/application/providers/default.rb:169>\n  shared_path \"/var/www/redmine/shared\"\n  destination \"/var/www/redmine/shared/cached-copy\"\n  current_path \"/var/www/redmine/current\"\nend\n\n"
          },
          "action": "deploy",
          "sender": "ruby-ruby-yfiu75sxeoql-server-5v4w5cqkp2bl",
          "agent": "xlcloud",
          "statuscode": 1,
          "statusmsg": "'/bin/chef-solo no-color -c /etc/chef/solo.rb -j /tmp/runlist20140206-1627-1vre9vv -L /var/log/chef-solo.log returned with exit code 1"
       }
     ],
     "id": 206,
     "href": "stacks/118/events/206",
     "type": "DEPLOY",
     "eventDate": "2014-01-23T15:04:54",
     "status": "FAILED",
     "exitCode": 1
   }
 ],
 "href": "/stacks/118/events"
}

Application Deployments

Application Deployment represents the act of deploying application on the layer. Deployment is executed by invoking the runlist of recipes for the "deploy" phase of the layer lifecycle. Depending on the configuration of the lifecycle, an application deployment may need to specify values of runlist cookbook attributes.

Processing of the application deployment is asynchronous. This means that the deploy and undeploy methods only initiate the process, but do not wait for it to be finished.

The application deployment can be in one of three statuses:

  • deploying – the application is currently being deployed
  • active – the deployment was executed successfully
  • undeploying – the application is currently being undeployed
  • undeployed – the application was undeployed sucessfully
  • failed – an error occured when deploying the application
  • failed_to_undeploy – an error occured when undeploying the application

Application deployments have the following fields:

  • name – name set during deploying
  • layerId – identifier of the layer that the deployment has been performed on
  • deployedAt – the date and time at which deployment was created (in the format "yyyy-MM-dd'T'HH:mm:ss")
  • status – status of the deployment processing
  • runlistAttributes – values of cookbook attributes used during the deployment
    • key – name of the attribute
    • value – value of the attribute

Deploy Application

Deploys an application, creating a new application deployment. In order to perform this operation, the project must be active, and the stack running.

Resource: POST layers/{layer_id}/deployments

Entitlement: POST 

accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/layers/{layer_id}/deployments

Error Response Codes:

  • 400 – project is not active, stack is not running
  • 404 – layer not found

Example Request: POST http://localhost:8080/xlcloud-xms/layers/15/deployments

Request body

{
  "runlistAttributes":[
    {
      "key":"xsa/application_war_url",
      "value":"192.168.1.2/something.war"
    }
  ],
  "name":"exampleName"
}

Example Response: 200

{
  "runlistAttributes":[
    {
      "key":"xsa/application_war_url",
      "value":"192.168.1.2/something.war"
    }
  ],
  "id":48,
  "href":"layers/237/deployments/48",
  "name":"exampleName",
  "layerId":15,
  "deployedAt":"2014-02-25T15:31:13",
  "status":"deploying"
}

List Application Deployments

Lists application deployments on a specified layer.

Resource: GET layers/{layer_id}/deployments

Entitlement: GET accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/layers/{layer_id}/deployments

Error Response Codes:

  • 404 – layer not found

Example Request: GET http://localhost:8080/xlcloud-xms/layers/236/deployments

Example Response: 200

{
  "applicationDeployments":[
    {
      "id":46,
      "href":"layers/236/deployments/46",
      "name":"deploy",
      "layerId":236,
      "deployedAt":"2014-02-25T15:01:16",
      "status":"failed"
    }
  ],
  "href":"/layers/236/deployments"
}

Undeploy Application

Undeploys an application. In order to perform this operation, the project must be active, and the stack running. The deployment status must be either "active", "undeployed" or "failed_to_undeploy".

Resource: DELETE layers/{layer_id}/deployments/{deployment_id}

Entitlement: DELETE accounts/{account_id}/projects/{project_id}/stacks/{stack_id}/layers/{layer_id}/deployments/{deployment_id}

Error Response Codes:

  • 400 – project is not active, stack is not running, deployment status is neither "active", "undeployed" nor "failed_to_undeploy"
  • 404 – layer not found

Example Request: DELETE http://localhost:8080/xlcloud-xms/layers/15/deployments/87

Example Response: 204
(no content)

Stack Blueprints

Stack blueprints allows users to create stacks easily. Users can create stacks by specifying a blueprint. Such blueprint defines the stack template, its layers, default values of its parameters, and other elements necessary to get a stack up and running. Stack blueprints are grouped into catalogs.

Stack blueprints have the following fields:

  • id – unique identifier
  • name – name of the stack blueprint
  • type – type of the stack blueprint, it's purely informational, and does not limit how the stack blueprint can be used
  • catalogScope – which catalog the stack blueprint is in, can be either "public" or "private"
  • accountId – identifier of the account this stack blueprint belongs to, only if the blueprint is private
  • author – author of this stack blueprint
  • license – license associated with this stack blueprint
  • copyright – copyright associated with this stack blueprint
  • parametersValues – default values of the stack blueprint template parameters; those values will be used as * current parameter values when a stack is created from the blueprint
  • template – stack template of this blueprint
  • layers – list of layer blueprints of this stack; when a stack is created from the blueprint, it's layers will be created from those layer blueprints

Promote Stack to Public Stack Blueprint

Creates a new public stack blueprint by promoting a stack. Default values of both stack and layer parameters can be specified using the "parametersValues" fields. When a stack is created from the blueprint, it will use those values as current values of its parameters. Default values of the "xlcloud" parameters in layers will be provided automatically if not specified (see how the layers parameters are defined in the stack template in the example response).

In the example response, layer templates have been omitted for brevity.

Resource: POST stack-blueprints?stackId={stack_id}

Entitlement: (two entitlements are required)

  • POST stack-blueprints
  • GET accounts/{account_id}/projects/{project_id}/stacks/{stack_id}

Required Query Parameters:

  • stackId

Required Fields:

  • name – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter
  • type

Error Response Codes:

  • 404 – stack not found, one of the specified layers not found
  • 409 – a public stack blueprint with the same name already exists

Example Request: POST http://localhost:8080/xlcloud-xms/stack-blueprints?stackId=9

{
  "name": "Slurm_Stack22232",
  "type": "slurm",
  "author": "the author",
  "license": "the license",
  "copyright": "the copyright",
  "parametersValues": {
    "parametersValues": [
      {
        "name": "MonitorPort",
        "value": "8649"
      },
      {
        "name": "xlcloud:defaultImageId",
        "value": "F19-x86_64-xlcloud"
      }
    ]
  },
  "layers": {
    "layer": [
      {
        "name": "Slurm",
        "parametersValues": {
          "parametersValues": [
            {
              "name": "xlcloud:defaultInstanceType",
              "value": "m1.large"
            }
          ]
        }
      }
    ]
  }
}

Example Response: 200

{
  "layers": {
    "layer": [
      {
        "id": 5,
        "href": "/layer-blueprints/5",
        "parametersValues": {},
        "name": "Slurm",
        "template": {
          OMITTED
        },
        "setupRunlist": {
          "recipes": [
            {
              "name": "hpc-vc::setup"
            }
          ],
          "phase": "setup"
        },
        "configureRunlist": {
          "recipes": [
            {
              "name": "hpc-vc::configure"
            }
          ],
          "phase": "configure"
        },
        "deployRunlist": {
          "recipes": [
            {
              "name": "hpc-vc::deploy"
            }
          ],
          "phase": "deploy"
        },
        "undeployRunlist": {
          "phase": "undeploy"
        },
        "shutdownRunlist": {
          "phase": "shutdown"
        },
        "suspendRunlist": {
          "phase": "suspend"
        },
        "resumeRunlist": {
          "phase": "resume"
        },
        "chefFile": {
          "cookbooks": [
            {
              "cookbook": "ohai"
            },
            {
              "cookbook": "hpc-vc",
              "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
            },
            {
              "cookbook": "slurm",
              "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
            }
          ]
        },
        "author": "the author",
        "license": "the license",
        "copyright": "the copyright",
        "type": "slurm",
        "catalogScope": "public",
        "stackBlueprintId": 3
      },
      {
        "id": 6,
        "href": "/layer-blueprints/6",
        "parametersValues": {},
        "name": "Monitor",
        "template": {
          OMITTED
        },
        "setupRunlist": {
          "phase": "setup"
        },
        "configureRunlist": {
          "phase": "configure"
        },
        "deployRunlist": {
          "phase": "deploy"
        },
        "undeployRunlist": {
          "phase": "undeploy"
        },
        "shutdownRunlist": {
          "phase": "shutdown"
        },
        "suspendRunlist": {
          "phase": "suspend"
        },
        "resumeRunlist": {
          "phase": "resume"
        },
        "chefFile": {
          "cookbooks": [
            {
              "cookbook": "ohai"
            },
            {
              "cookbook": "mcollective",
              "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
            },
            {
              "cookbook": "xlc-mco-agent",
              "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
            },
            {
              "cookbook": "ganglia",
              "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
            }
          ]
        },
        "author": "the author",
        "license": "the license",
        "copyright": "the copyright",
        "type": "slurm",
        "catalogScope": "public",
        "stackBlueprintId": 3
      }
    ]
  },
  "id": 3,
  "href": "/stack-blueprints/3",
  "parametersValues": {
    "parametersValues": [
      {
        "value": "8649",
        "name": "MonitorPort"
      },
      {
        "value": "F19-x86_64-xlcloud",
        "name": "xlcloud:defaultImageId"
      }
    ]
  },
  "name": "Slurm_Stack",
  "template": {
    "Outputs": {
      "MonitorURL": {
        "Value": {
          "Fn::GetAtt": [
            "Monitor",
            "Outputs.PublicURL"
          ]
        },
        "Description": "Public URL of the monitoring node"
      },
      "LoginIP": {
        "Value": {
          "Fn::GetAtt": [
            "Slurm",
            "Outputs.LoginAddress"
          ]
        },
        "Description": "Public address of the login node"
      },
      "xlcloud:xsaAddress": {
        "Value": {
          "Fn::Join": [
            "",
            [
              "http://",
              {
                "Fn::GetAtt": [
                  "Slurm",
                  "Outputs.xsaIp"
                ]
              },
              ":8080/xsa"
            ]
          ]
        },
        "Description": "XSA URL"
      }
    },
    "Parameters": {
      "xlcloud:brokerPort": {
        "Default": "63613",
        "Description": "RabbitMQ broker port",
        "Type": "String"
      },
      "xlcloud:defaultKeyName": {
        "Description": "Name of an existing EC2 KeyPair to enable SSH access",
        "Type": "String"
      },
      "MonitorPort": {
        "Default": "8649",
        "Description": "TCP port of monitoring traffic data",
        "Type": "String"
      },
      "xlcloud:brokerAddress": {
        "Description": "RabbitMQ broker address",
        "Type": "String"
      },
      "xlcloud:Computes:size": {
        "Default": "2",
        "Description": "Number of compute nodes to launch",
        "Type": "String"
      },
      "xlcloud:brokerUsername": {
        "Default": "xlcloud",
        "Description": "RabbitMQ broker username",
        "Type": "String"
      },
      "xlcloud:defaultInstanceType": {
        "Default": "m1.small",
        "AllowedValues": [
          "m1.tiny",
          "m1.small",
          "m1.medium",
          "m1.large",
          "m1.xlarge"
        ],
        "Description": "Default instance type (flavor) for instances in this stack",
        "Type": "String",
        "ConstraintDescription": "must be a valid XLcloud instance type."
      },
      "xlcloud:monitoringCluster": {
        "Default": "SLURM",
        "Description": "Name of the cluster in the monitoring system",
        "Type": "String",
        "AllowedPattern": "[a-z|A-Z|0-9]*"
      },
      "xlcloud:brokerPassword": {
        "Default": "xlcloud",
        "Description": "RabbitMQ broker password",
        "Type": "String"
      },
      "xlcloud:defaultImageId": {
        "Default": "F19-x86_64-xlcloud",
        "AllowedValues": [
          "F19-x86_64-xlcloud"
        ],
        "Description": "Default image name for instances in this stack",
        "Type": "String",
        "ConstraintDescription": "Must be a valid XLcloud image name."
      }
    },
    "Description": "XLcloud Slurm Stack",
    "AWSTemplateFormatVersion": "",
    "Resources": {
      "Monitor": {
        "Type": "AWS::CloudFormation::Stack",
        "Properties": {
          "Parameters": {
            "xlcloud:brokerPort": {
              "Ref": "xlcloud:brokerPort"
            },
            "xlcloud:defaultKeyName": {
              "Ref": "xlcloud:defaultKeyName"
            },
            "xlcloud:brokerAddress": {
              "Ref": "xlcloud:brokerAddress"
            },
            "xlcloud:brokerUsername": {
              "Ref": "xlcloud:brokerUsername"
            },
            "xlcloud:defaultInstanceType": "m1.large",
            "xlcloud:stackId": {
              "Ref": "AWS::StackId"
            },
            "xlcloud:brokerPassword": {
              "Ref": "xlcloud:brokerPassword"
            },
            "xlcloud:defaultImageId": {
              "Ref": "xlcloud:defaultImageId"
            }
          },
          "TimeoutInMinutes": "5",
          "TemplateURL": "layers/23"
        }
      },
      "Slurm": {
        "Type": "AWS::CloudFormation::Stack",
        "DependsOn": "Monitor",
        "Properties": {
          "Parameters": {
            "xlcloud:brokerPort": {
              "Ref": "xlcloud:brokerPort"
            },
            "xlcloud:defaultKeyName": {
              "Ref": "xlcloud:defaultKeyName"
            },
            "xlcloud:brokerAddress": {
              "Ref": "xlcloud:brokerAddress"
            },
            "xlcloud:brokerUsername": {
              "Ref": "xlcloud:brokerUsername"
            },
            "xlcloud:defaultInstanceType": {
              "Ref": "xlcloud:defaultInstanceType"
            },
            "xlcloud:stackId": {
              "Ref": "AWS::StackId"
            },
            "xlcloud:brokerPassword": {
              "Ref": "xlcloud:brokerPassword"
            },
            "xlcloud:defaultImageId": {
              "Ref": "xlcloud:defaultImageId"
            }
          },
          "TimeoutInMinutes": "40",
          "TemplateURL": "layers/22"
        }
      }
    }
  },
  "author": "the author",
  "license": "the license",
  "copyright": "the copyright",
  "type": "slurm",
  "catalogScope": "public"
}

Promote Stack to Private Stack Blueprint

Creates a new private stack blueprint by promoting a stack. Default values of both stack and layer parameters can be specified using the "parametersValues" fields. When a stack is created from the blueprint, it will use those values as current values of its parameters. It is strongly recommended that you supply values of the "xlcloud" parameters in layers as shown in the example request. Otherwise, those parameters will not be inherited by layers, which can render a stack created from such a blueprint unusable.

In the example response, stack and layer templates have been omitted for brevity.

Resource: POST accounts/{account_id}/stack-blueprints?stackId={stack_id}

Entitlement: (two entitlements are required)

  • POST accounts/{account_id}/stack-blueprints
  • GET accounts/{account_id}/projects/{project_id}/stacks/{stack_id}

Required Query Parameters:

  • stackId

Required Fields:

  • name – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter
  • type

Error Response Codes:

  • 404 – account not found, stack not found, one of the specified layers not found
  • 409 – a private stack blueprint with the same name already exists in the account

Example Request: POST http://localhost:8080/xlcloud-xms/accounts/161/stack-blueprints?stackId=9

{
  "name": "Slurm_Stack",
  "type": "slurm",
  "author": "the author",
  "license": "the license",
  "copyright": "the copyright",
  "parametersValues": {
    "parametersValues": [
      {
        "name": "MonitorPort",
        "value": "8649"
      },
      {
        "name": "xlcloud:defaultImageId",
        "value": "F19-x86_64-xlcloud"
      }
    ]
  },
  "layers": {
    "layer": [
      {
        "name": "Slurm",
        "parametersValues": {
          "parametersValues": [
            {
              "name": "xlcloud:defaultKeyName",
              "value": { "Ref": "xlcloud:defaultKeyName" }
            },
            {
              "name": "xlcloud:brokerPort",
              "value": { "Ref": "xlcloud:brokerPort" }
            },
            {
              "name": "xlcloud:brokerAddress",
              "value": { "Ref": "xlcloud:brokerAddress" }
            },
            {
              "name": "xlcloud:defaultInstanceType",
              "value": { "Ref": "xlcloud:defaultInstanceType" }
            },
            {
              "name": "xlcloud:brokerUsername",
              "value": { "Ref": "xlcloud:brokerUsername" }
            },
            {
              "name": "xlcloud:stackId",
              "value": { "Ref": "AWS::StackId" }
            },
            {
              "name": "xlcloud:brokerPassword",
              "value": { "Ref": "xlcloud:brokerPassword" }
            },
            {
              "name": "xlcloud:defaultImageId",
              "value": { "Ref": "xlcloud:defaultImageId" }
            }
          ]
        }
      },
      {
        "name": "Monitor",
        "parametersValues": {
          "parametersValues": [
            {
              "name": "xlcloud:defaultKeyName",
              "value": { "Ref": "xlcloud:defaultKeyName" }
            },
            {
              "name": "xlcloud:brokerPort",
              "value": { "Ref": "xlcloud:brokerPort" }
            },
            {
              "name": "xlcloud:brokerAddress",
              "value": { "Ref": "xlcloud:brokerAddress" }
            },
            {
              "name": "xlcloud:defaultInstanceType",
              "value": { "Ref": "xlcloud:defaultInstanceType" }
            },
            {
              "name": "xlcloud:brokerUsername",
              "value": { "Ref": "xlcloud:brokerUsername" }
            },
            {
              "name": "xlcloud:stackId",
              "value": { "Ref": "AWS::StackId" }
            },
            {
              "name": "xlcloud:brokerPassword",
              "value": { "Ref": "xlcloud:brokerPassword" }
            },
            {
              "name": "xlcloud:defaultImageId",
              "value": { "Ref": "xlcloud:defaultImageId" }
            }
          ]
        }
      }
    ]
  }
}

Example Response: 200

{
  "layers": {
    "layer": [
      {
        "id": 5,
        "href": "/layer-blueprints/5",
        "parametersValues": {},
        "name": "Slurm",
        "accountId": 161,
        "template": {
          OMITTED
        },
        "setupRunlist": {
          "recipes": [
            {
              "name": "hpc-vc::setup"
            }
          ],
          "phase": "setup"
        },
        "configureRunlist": {
          "recipes": [
            {
              "name": "hpc-vc::configure"
            }
          ],
          "phase": "configure"
        },
        "deployRunlist": {
          "recipes": [
            {
              "name": "hpc-vc::deploy"
            }
          ],
          "phase": "deploy"
        },
        "undeployRunlist": {
          "phase": "undeploy"
        },
        "shutdownRunlist": {
          "phase": "shutdown"
        },
        "suspendRunlist": {
          "phase": "suspend"
        },
        "resumeRunlist": {
          "phase": "resume"
        },
        "chefFile": {
          "cookbooks": [
            {
              "cookbook": "ohai"
            },
            {
              "cookbook": "hpc-vc",
              "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
            },
            {
              "cookbook": "slurm",
              "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
            }
          ]
        },
        "author": "the author",
        "license": "the license",
        "copyright": "the copyright",
        "type": "slurm",
        "catalogScope": "private",
        "stackBlueprintId": 3
      },
      {
        "id": 6,
        "href": "/layer-blueprints/6",
        "parametersValues": {},
        "name": "Monitor",
        "accountId": 161,
        "template": {
          OMITTED
        },
        "setupRunlist": {
          "phase": "setup"
        },
        "configureRunlist": {
          "phase": "configure"
        },
        "deployRunlist": {
          "phase": "deploy"
        },
        "undeployRunlist": {
          "phase": "undeploy"
        },
        "shutdownRunlist": {
          "phase": "shutdown"
        },
        "suspendRunlist": {
          "phase": "suspend"
        },
        "resumeRunlist": {
          "phase": "resume"
        },
        "chefFile": {
          "cookbooks": [
            {
              "cookbook": "ohai"
            },
            {
              "cookbook": "mcollective",
              "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
            },
            {
              "cookbook": "xlc-mco-agent",
              "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
            },
            {
              "cookbook": "ganglia",
              "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
            }
          ]
        },
        "author": "the author",
        "license": "the license",
        "copyright": "the copyright",
        "type": "slurm",
        "catalogScope": "private",
        "stackBlueprintId": 3
      }
    ]
  },
  "id": 3,
  "href": "/stack-blueprints/3",
  "parametersValues": {
    "parametersValues": [
      {
        "value": "8649",
        "name": "MonitorPort"
      },
      {
        "value": "F19-x86_64-xlcloud",
        "name": "xlcloud:defaultImageId"
      }
    ]
  },
  "name": "Slurm_Stack",
  "accountId": 161,
  "template": {
    OMITTED
  },
  "author": "the author",
  "license": "the license",
  "copyright": "the copyright",
  "type": "slurm",
  "catalogScope": "private"
}

Get Stack Blueprint Details

Gets the details of a specified stack blueprint.
In the example response, the stack template has been omitted for brevity. Layer templates are not returned by this method!

Resource: GET stack-blueprints/{stack_blueprint_id}

Entitlement:

  • to get the details of a public stack blueprint: GET stack-blueprints/{stack_blueprint_id}
  • to get the details of a private stack blueprint: GET accounts/{account_id}/stack-blueprints/{stack_blueprint_id}

Error Response Codes:

  • 404 – stack blueprint not found

Example Request: GET http://localhost:8080/xlcloud-xms/stack-blueprints/5

Example Response: 200

{
  "layers": {
    "layer": [
      {
        "id": 9,
        "href": "/layer-blueprints/9",
        "parametersValues": {},
        "name": "Slurm",
        "template": {},
        "author": "the author",
        "license": "the license",
        "copyright": "the copyright",
        "type": "slurm",
        "catalogScope": "public",
        "stackBlueprintId": 5
      },
      {
        "id": 10,
        "href": "/layer-blueprints/10",
        "parametersValues": {},
        "name": "Monitor",
        "template": {},
        "author": "the author",
        "license": "the license",
        "copyright": "the copyright",
        "type": "slurm",
        "catalogScope": "public",
        "stackBlueprintId": 5
      }
    ]
  },
  "id": 5,
  "href": "/stack-blueprints/5",
  "parametersValues": {
    "parametersValues": [
      {
        "value": "8649",
        "name": "MonitorPort"
      },
      {
        "value": "F19-x86_64-xlcloud",
        "name": "xlcloud:defaultImageId"
      }
    ]
  },
  "name": "Slurm_Stack6",
  "template": {
    OMITTED
  },
  "author": "the author",
  "license": "the license",
  "copyright": "the copyright",
  "type": "slurm",
  "catalogScope": "public"
}

List Public Stack Blueprints

Lists all public stack blueprints.

Resource: GET stack-blueprints

Entitlement: GET stack-blueprints

Example Request: GET http://localhost:8080/xlcloud-xms/stack-blueprints

Example Response: 200

{
  "stackBlueprint": [
    {
      "layers": {
        "layer": [
          {
            "id": 1,
            "href": "/layer-blueprints/1",
            "parametersValues": {},
            "name": "Slurm",
            "template": {},
            "author": "AMG.net",
            "license": "freeware",
            "type": "slurm",
            "catalogScope": "public",
            "stackBlueprintId": 1
          },
          {
            "id": 2,
            "href": "/layer-blueprints/2",
            "parametersValues": {},
            "name": "Monitor",
            "template": {},
            "author": "AMG.net",
            "license": "freeware",
            "type": "slurm",
            "catalogScope": "public",
            "stackBlueprintId": 1
          }
        ]
      },
      "id": 1,
      "href": "/stack-blueprints/1",
      "parametersValues": {},
      "name": "Slurm_Stack",
      "template": {},
      "author": "AMG.net",
      "license": "freeware",
      "type": "slurm",
      "catalogScope": "public"
    },
    {
      "layers": {
        "layer": [
          {
            "id": 9,
            "href": "/layer-blueprints/9",
            "parametersValues": {},
            "name": "Slurm",
            "template": {},
            "author": "the author",
            "license": "the license",
            "copyright": "the copyright",
            "type": "slurm",
            "catalogScope": "public",
            "stackBlueprintId": 5
          },
          {
            "id": 10,
            "href": "/layer-blueprints/10",
            "parametersValues": {},
            "name": "Monitor",
            "template": {},
            "author": "the author",
            "license": "the license",
            "copyright": "the copyright",
            "type": "slurm",
            "catalogScope": "public",
            "stackBlueprintId": 5
          }
        ]
      },
      "id": 5,
      "href": "/stack-blueprints/5",
      "parametersValues": {},
      "name": "Slurm_Stack6",
      "template": {},
      "author": "the author",
      "license": "the license",
      "copyright": "the copyright",
      "type": "slurm",
      "catalogScope": "public"
    }
  ],
  "href": "/stack-blueprints"
}

List Private Stack Blueprints

Lists all private stack blueprints in a specified account.

Resource: GET accounts/{account_id}/stack-blueprints

Entitlement: GET accounts/{account_id}/stack-blueprints

Error Response Codes:

  • 404 – account not found

Example Request: GET http://localhost:8080/xlcloud-xms/accounts/100/stack-blueprints

Example Response: 200

{
  "stackBlueprint": [
    {
      "layers": {
        "layer": [
          {
            "id": 3,
            "href": "/layer-blueprints/3",
            "parametersValues": {},
            "name": "Slurm",
            "accountId": 100,
            "template": {},
            "author": "the author",
            "license": "the license",
            "copyright": "the copyright",
            "type": "slurm",
            "catalogScope": "private",
            "stackBlueprintId": 2
          },
          {
            "id": 4,
            "href": "/layer-blueprints/4",
            "parametersValues": {},
            "name": "Monitor",
            "accountId": 100,
            "template": {},
            "author": "the author",
            "license": "the license",
            "copyright": "the copyright",
            "type": "slurm",
            "catalogScope": "private",
            "stackBlueprintId": 2
          }
        ]
      },
      "id": 2,
      "href": "/stack-blueprints/2",
      "parametersValues": {},
      "name": "Slurm_Stack",
      "accountId": 100,
      "template": {},
      "author": "the author",
      "license": "the license",
      "copyright": "the copyright",
      "type": "slurm",
      "catalogScope": "private"
    }
  ],
  "href": "/accounts/100/stack-blueprints"
}

Edit Stack Blueprint

Edits a specified stack blueprint. The only fields that can be edited are: "name", "type", "author", "license", and "copyright".

In the example response, the stack template has been omitted for brevity. Layer templates are not returned by this method!

Resource: PUT stack-blueprints/{stack_blueprint_id}

Entitlement:

  • to edit a public stack blueprint: PUT stack-blueprints/{stack_blueprint_id}
  • to edit a private stack blueprint: PUT accounts/{account_id}/stack-blueprints/{stack_blueprint_id}

Error Response Codes:

  • 404 – stack blueprint not found

Example Request: PUT http://localhost:8080/xlcloud-xms/stack-blueprints/5

{
  "name": "Slurm_Stack67",
  "type": "hpc",
  "author": "my author",
  "license": "my license",
  "copyright": "my copyright"
}

Example Response: 200

{
  "layers": {
    "layer": [
      {
        "id": 9,
        "href": "/layer-blueprints/9",
        "parametersValues": {},
        "name": "Slurm",
        "template": {},
        "author": "the author",
        "license": "the license",
        "copyright": "the copyright",
        "type": "slurm",
        "catalogScope": "public",
        "stackBlueprintId": 5
      },
      {
        "id": 10,
        "href": "/layer-blueprints/10",
        "parametersValues": {},
        "name": "Monitor",
        "template": {},
        "author": "the author",
        "license": "the license",
        "copyright": "the copyright",
        "type": "slurm",
        "catalogScope": "public",
        "stackBlueprintId": 5
      }
    ]
  },
  "id": 5,
  "href": "/stack-blueprints/5",
  "parametersValues": {
    "parametersValues": [
      {
        "value": "8649",
        "name": "MonitorPort"
      },
      {
        "value": "F19-x86_64-xlcloud",
        "name": "xlcloud:defaultImageId"
      }
    ]
  },
  "name": "Slurm_Stack67",
  "template": {
    OMITTED
  },
  "author": "my author",
  "license": "my license",
  "copyright": "my copyright",
  "type": "hpc",
  "catalogScope": "public"
}

Delete Stack Blueprint

Deletes a stack blueprint.

Resource: DELETE stack-blueprints/{stack_blueprint_id}

Entitlement:

  • to delete a public stack blueprint: DELETE stack-blueprints/{stack_blueprint_id}
  • to delete a private stack blueprint: DELETE accounts/{account_id}/stack-blueprints/{stack_blueprint_id}

Example Request: DELETE http://localhost:8080/xlcloud-xms/stack-blueprints/5

Example Response: 204
(no content)

Layer Blueprints

Layer blueprints allows users to create layers easily. Users can add layers to their stacks by specifying a blueprint. Such blueprint defines the layer template and other necessary elements. No default parameter values are defined by layer blueprints. All values need to be specified by the user after creating the layer. Layer blueprints are grouped into catalogs.

Layer blueprints have the following fields:

  • id – unique identifier
  • name – name of the layer blueprint
  • type – type of the layer blueprint, it's purely informational, and does not limit how the layer blueprint can be used
  • catalogScope – which catalog the stack blueprint is in, can be either "public" or "private"
  • accountId – identifier of the account this layer blueprint belongs to, only if the blueprint is private
  • author – author of this layer blueprint
  • license – license associated with this layer blueprint
  • copyright – copyright associated with this layer blueprint
  • template – layer template of this blueprint
  • setupRunlist – runlist used in the "setup" phase
    • recipes – list of recipes in this run list
    • phase – phase this runlist applies to
  • configureRunlist – runlist used in the "configure" phase
    • recipes – list of recipes in this run list
    • phase – phase this runlist applies to
  • suspendRunlist – runlist used in the "suspend" phase
    • recipes – list of recipes in this run list
    • phase – phase this runlist applies to
  • resumeRunlist – runlist used in the "resume" phase
    • recipes – list of recipes in this run list
    • phase – phase this runlist applies to
  • shutdownRunlist – runlist used in the "shutdown" phase
    • recipes – list of recipes in this run list
    • phase – phase this runlist applies to
  • deployRunlist – runlist used in the "deploy" phase
    • recipes – list of recipes in this run list
    • phase – phase this runlist applies to
  • undeployRunlist – runlist used in the "undeploy" phase
    • recipes – list of recipes in this run list
    • phase – phase this runlist applies to
  • chefFile – defines the Chef file
    • cookbooks – list of cookbooks for Chef to download
      • cookbook – name of the cookbook
        *git – address of the repository containing the cookbook

Promote Layer to Public Layer Blueprint

Creates a new public layer blueprint by promoting a layer. Default values of layer parameters cannot be specified.

In the example response, the layer template has been omitted for brevity.

Resource: POST layer-blueprints?layerId={layer_id}

Entitlement: (two entitlements are required)

  • POST layer-blueprints
  • GET accounts/{account_id}/projects/{project_id}/stacks/{stack_id}

Required Query Parameters:

  • layerId

Required Fields:

  • name – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter
  • type

Error Response Codes:

  • 404 – layer not found
  • 409 – a public layer blueprint with the same name already exists

Example Request: POST http://localhost:8080/xlcloud-xms/layer-blueprints?layerId=1

{
  "name": "Slurm_Layer2",
  "type": "slurm",
  "author": "the author",
  "license": "the license",
  "copyright": "the copyright"
}

Example Response: 200

{
  "id": 13,
  "href": "/layer-blueprints/13",
  "parametersValues": {},
  "name": "Slurm_Layer2",
  "template": {
    OMITTED
  },
  "setupRunlist": {
    "recipes": [
      {
        "name": "hpc-vc::setup"
      }
    ],
    "phase": "setup"
  },
  "configureRunlist": {
    "recipes": [
      {
        "name": "hpc-vc::configure"
      }
    ],
    "phase": "configure"
  },
  "deployRunlist": {
    "recipes": [
      {
        "name": "hpc-vc::deploy"
      }
    ],
    "phase": "deploy"
  },
  "undeployRunlist": {
    "phase": "undeploy"
  },
  "shutdownRunlist": {
    "phase": "shutdown"
  },
  "suspendRunlist": {
    "phase": "suspend"
  },
  "resumeRunlist": {
    "phase": "resume"
  },
  "chefFile": {
    "cookbooks": [
      {
        "cookbook": "ohai"
      },
      {
        "cookbook": "mcollective",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      },
      {
        "cookbook": "xlc-mco-agent",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      },
      {
        "cookbook": "hpc-vc",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      }
    ]
  },
  "author": "the author",
  "license": "the license",
  "copyright": "the copyright",
  "type": "slurm",
  "catalogScope": "public"
}

Promote Layer to Private Layer Blueprint

Creates a new private layer blueprint by promoting a layer. Default values of layer parameters cannot be specified.

In the example response, the layer template has been omitted for brevity.

Resource: POST accounts/{account_id}/layer-blueprints?layerId={layer_id}

Entitlement: (two entitlements are required)

  • POST accounts/{account_id}/layer-blueprints
  • GET accounts/{account_id}/projects/{project_id}/stacks/{stack_id}

Required Query Parameters:

  • layerId

Required Fields:

  • name – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter
  • type

Error Response Codes:

  • 404 – account not found, layer not found
  • 409 – a private layer blueprint with the same name already exists in the account

Example Request: POST http://localhost:8080/xlcloud-xms/layer-blueprints?layerId=1

{
  "name": "Slurm_Layer2",
  "type": "slurm",
  "author": "the author",
  "license": "the license",
  "copyright": "the copyright"
}

Example Response: 200

{
  "id": 13,
  "href": "/layer-blueprints/13",
  "parametersValues": {},
  "name": "Slurm_Layer2",
  "accountId": 100,
  "template": {
    OMITTED
  },
  "setupRunlist": {
    "recipes": [
      {
        "name": "hpc-vc::setup"
      }
    ],
    "phase": "setup"
  },
  "configureRunlist": {
    "recipes": [
      {
        "name": "hpc-vc::configure"
      }
    ],
    "phase": "configure"
  },
  "deployRunlist": {
    "recipes": [
      {
        "name": "hpc-vc::deploy"
      }
    ],
    "phase": "deploy"
  },
  "undeployRunlist": {
    "phase": "undeploy"
  },
  "shutdownRunlist": {
    "phase": "shutdown"
  },
  "suspendRunlist": {
    "phase": "suspend"
  },
  "resumeRunlist": {
    "phase": "resume"
  },
  "chefFile": {
    "cookbooks": [
      {
        "cookbook": "ohai"
      },
      {
        "cookbook": "mcollective",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      },
      {
        "cookbook": "xlc-mco-agent",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      },
      {
        "cookbook": "hpc-vc",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      }
    ]
  },
  "author": "the author",
  "license": "the license",
  "copyright": "the copyright",
  "type": "slurm",
  "catalogScope": "private"
}

Get Layer Blueprint Details

Gets the details of a specified layer blueprint.

In the example response, the layer template has been omitted for brevity.

Resource: GET layer-blueprints/{layer_blueprint_id}

Entitlement:

  • to get the details of a public layer blueprint: GET layer-blueprints/{layer_blueprint_id}
  • to get the details of a private layer blueprint: GET accounts/{account_id}/layer-blueprints/{layer_blueprint_id}

Error Response Codes:

  • 404 – layer blueprint not found

Example Request: GET http://localhost:8080/xlcloud-xms/stack-blueprints/5

Example Response: 200

{
  "id": 14,
  "href": "/layer-blueprints/14",
  "parametersValues": {},
  "name": "Slurm_Layer2",
  "accountId": 100,
  "template": {
    OMITTED
  },
  "setupRunlist": {
    "recipes": [
      {
        "name": "hpc-vc::setup"
      }
    ],
    "phase": "setup"
  },
  "configureRunlist": {
    "recipes": [
      {
        "name": "hpc-vc::configure"
      }
    ],
    "phase": "configure"
  },
  "deployRunlist": {
    "recipes": [
      {
        "name": "hpc-vc::deploy"
      }
    ],
    "phase": "deploy"
  },
  "undeployRunlist": {
    "phase": "undeploy"
  },
  "shutdownRunlist": {
    "phase": "shutdown"
  },
  "suspendRunlist": {
    "phase": "suspend"
  },
  "resumeRunlist": {
    "phase": "resume"
  },
  "chefFile": {
    "cookbooks": [
      {
        "cookbook": "ohai"
      },
      {
        "cookbook": "mcollective",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      },
      {
        "cookbook": "xlc-mco-agent",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      },
      {
        "cookbook": "hpc-vc",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      }
    ]
  },
  "author": "the author",
  "license": "the license",
  "copyright": "the copyright",
  "type": "slurm",
  "catalogScope": "private"
}

List Public Layer Blueprints

Lists all public layer blueprints.

Resource: GET layer-blueprints

Entitlement: GET layer-blueprints

Example Request: GET http://localhost:8080/xlcloud-xms/layer-blueprints

Example Response: 200

{
  "layer": [
    {
      "id": 11,
      "href": "/layer-blueprints/11",
      "parametersValues": {},
      "name": "Slurm_Layer",
      "template": {},
      "setupRunlist": {
        "recipes": [
          {
            "name": "hpc-vc::setup"
          }
        ],
        "phase": "setup"
      },
      "configureRunlist": {
        "recipes": [
          {
            "name": "hpc-vc::configure"
          }
        ],
        "phase": "configure"
      },
      "deployRunlist": {
        "recipes": [
          {
            "name": "hpc-vc::deploy"
          }
        ],
        "phase": "deploy"
      },
      "undeployRunlist": {
        "phase": "undeploy"
      },
      "shutdownRunlist": {
        "phase": "shutdown"
      },
      "suspendRunlist": {
        "phase": "suspend"
      },
      "resumeRunlist": {
        "phase": "resume"
      },
      "chefFile": {
        "cookbooks": [
          {
            "cookbook": "ohai"
          },
          {
            "cookbook": "mcollective",
            "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
          },
          {
            "cookbook": "xlc-mco-agent",
            "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
          },
          {
            "cookbook": "hpc-vc",
            "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
          }
        ]
      },
      "author": "the author",
      "license": "the license",
      "copyright": "the copyright",
      "type": "slurm",
      "catalogScope": "public"
    },
    {
      "id": 13,
      "href": "/layer-blueprints/13",
      "parametersValues": {},
      "name": "Slurm_Layer2",
      "template": {},
      "setupRunlist": {
        "recipes": [
          {
            "name": "hpc-vc::setup"
          }
        ],
        "phase": "setup"
      },
      "configureRunlist": {
        "recipes": [
          {
            "name": "hpc-vc::configure"
          }
        ],
        "phase": "configure"
      },
      "deployRunlist": {
        "recipes": [
          {
            "name": "hpc-vc::deploy"
          }
        ],
        "phase": "deploy"
      },
      "undeployRunlist": {
        "phase": "undeploy"
      },
      "shutdownRunlist": {
        "phase": "shutdown"
      },
      "suspendRunlist": {
        "phase": "suspend"
      },
      "resumeRunlist": {
        "phase": "resume"
      },
      "chefFile": {
        "cookbooks": [
          {
            "cookbook": "ohai"
          },
          {
            "cookbook": "mcollective",
            "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
          },
          {
            "cookbook": "xlc-mco-agent",
            "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
          },
          {
            "cookbook": "hpc-vc",
            "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
          }
        ]
      },
      "author": "the author",
      "license": "the license",
      "copyright": "the copyright",
      "type": "slurm",
      "catalogScope": "public"
    }
  ],
  "href": "/layer-blueprints"
}

List Private Layer Blueprints

Lists all private layer blueprints in a specified account.

Resource: GET accounts/{account_id}/layer-blueprints

Entitlement: GET accounts/{account_id}/layer-blueprints

Error Response Codes:

  • 404 – account not found

Example Request: GET http://localhost:8080/xlcloud-xms/accounts/100/layer-blueprints

Example Response: 200

{
  "layer": [
    {
      "id": 12,
      "href": "/layer-blueprints/12",
      "parametersValues": {},
      "name": "Slurm",
      "accountId": 100,
      "template": {},
      "setupRunlist": {
        "recipes": [
          {
            "name": "hpc-vc::setup"
          }
        ],
        "phase": "setup"
      },
      "configureRunlist": {
        "recipes": [
          {
            "name": "hpc-vc::configure"
          }
        ],
        "phase": "configure"
      },
      "deployRunlist": {
        "recipes": [
          {
            "name": "hpc-vc::deploy"
          }
        ],
        "phase": "deploy"
      },
      "undeployRunlist": {
        "phase": "undeploy"
      },
      "shutdownRunlist": {
        "phase": "shutdown"
      },
      "suspendRunlist": {
        "phase": "suspend"
      },
      "resumeRunlist": {
        "phase": "resume"
      },
      "chefFile": {
        "cookbooks": [
          {
            "cookbook": "ohai"
          },
          {
            "cookbook": "mcollective",
            "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
          },
          {
            "cookbook": "xlc-mco-agent",
            "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
          },
          {
            "cookbook": "hpc-vc",
            "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
          }
        ]
      },
      "type": "kaef",
      "catalogScope": "private"
    }
  ],
  "href": "/accounts/100/layer-blueprints"
}

Export Stack Blueprint Layer to Layer Blueprint

Exports a stack blueprint layer to an independent layer blueprint, placing it in an appropriate layer blueprints catalog. If the name is not specified, the name of the original layer blueprint will be used.

In the example response, the layer template has been omitted for brevity.

Resource: POST layer-blueprints/export?blueprintId={layer_blueprint_id}

Entitlement: (two entitlements are required)

  • POST layer-blueprints/export
  • to export a public stack blueprint layer to a layer blueprint: GET layer-blueprints/{layer_blueprint_id}
  • to export a private stack blueprint layer to a layer blueprint: GET accounts/{account_id}/layer-blueprints/{layer_blueprint_id}

Error Response Codes:

  • 400 – layer blueprint is already independent and in a layer blueprints catalog, layer blueprint name is invalid (name can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter)
  • 404 – layer blueprint not found
  • 409 – a private layer blueprint with the same name already exists in the account

Example Request: POST http://localhost:8080/xlcloud-xms/layer-blueprints/export?blueprintId=2

{
  "name": " Monitor_Layer2"
}

Example Response: 200

{
  "id": 16,
  "href": "/layer-blueprints/16",
  "parametersValues": {},
  "name": " Monitor_Layer2",
  "template": {
    OMITTED
  },
  "setupRunlist": {
    "phase": "setup"
  },
  "configureRunlist": {
    "phase": "configure"
  },
  "deployRunlist": {
    "phase": "deploy"
  },
  "undeployRunlist": {
    "phase": "undeploy"
  },
  "shutdownRunlist": {
    "phase": "shutdown"
  },
  "suspendRunlist": {
    "phase": "suspend"
  },
  "resumeRunlist": {
    "phase": "resume"
  },
  "chefFile": {
    "cookbooks": [
      {
        "cookbook": "ohai"
      },
      {
        "cookbook": "mcollective",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      },
      {
        "cookbook": "xlc-mco-agent",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      },
      {
        "cookbook": "ganglia",
        "git": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git"
      }
    ]
  },
  "author": "AMG.net",
  "license": "freeware",
  "type": "slurm",
  "catalogScope": "public"
}

Delete Layer Blueprint

Deletes a layer blueprint.

Resource: DELETE layer-blueprints/{layer_blueprint_id}

Entitlement:

  • to delete a public stack blueprint: DELETE layer-blueprints/{layer_blueprint_id}
  • to delete a private stack blueprint: DELETE accounts/{account_id}/layer-blueprints/{layer_blueprint_id}

Example Request: DELETE http://localhost:8080/xlcloud-xms/layer-blueprints/14

Example Response: 204
(no content)

Images

Cloud images are virtual machine images used to create individual instances of a stack. When creating a stack you specify what image(s) will be used for its instances.

Images have the following fields:

  • id – unique identifier
  • name – name of the image
  • description – informational description about the image
  • catalogScope – which catalog the image is in, can be either "public" or "private"
  • accountId – identifier of the account this image belongs to, only if the image is private
  • author – author of this image
  • license – license associated with this image
  • copyright – copyright associated with this image
  • diskFormat – format of the underlying disk image, can be one of: "raw", "vhd", "vmdk", "vdi", "iso", "qcow2", "aki", "ari", "ami"
    • raw – an unstructured disk image format
    • vhd – the VHD disk format, used by virtual machine monitors from VMWare, Xen, Microsoft, VirtualBox, and others
    • vmdk – a common disk format supported by many common virtual machine monitors
    • vdi – a disk format supported by VirtualBox virtual machine monitor and the QEMU emulator
    • iso – an archive format for the data contents of an optical disc (e.g. CD-ROM)
    • qcow2 – a disk format supported by the QEMU emulator that can expand dynamically and supports Copy on Write
    • aki – the Amazon kernel image
    • ari – the Amazon ramdisk image
    • ami – the Amazon machine image
  • containerFormat – whether the virtual machine image is in a file format that also contains metadata about the actual virtual machine, can be one of:
    • bare – there is no container or metadata envelope for the image
    • ovf – the OVF container format
    • aki – the Amazon kernel image
    • ari – the Amazon ramdisk image
    • ami – the Amazon machine image
  • minDisk – minimum amount of disk space needed to run this image on an instance, in GB
  • minRam – minimum amount of RAM needed to run this image on an instance, in MB
  • size – size of the disk image
  • status – current status of the image, can be one of:
    • queued – the image identifier has been reserved for an image in the Glance registry; no image data has been uploaded
    • saving – image raw data is currently being uploaded to Glance
    • active – an image that is fully available
    • killed – an error occurred during the uploading of the image data, the image is unusable
    • deleted – the image has been deleted, but Glance retained information about it
    • pending_delete – image is about to be deleted from Glance, but it is still recoverable

Register Public Image

Registers a new public cloud image. If disk or container format is one of "aki", "ari", or "ami", the container and disk formats must match.

Resource: POST images

Entitlement: POST images

Required Fields:

  • name – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter

Error Response Codes:

  • 400 – disk or container format is one of "aki", "ari", or "ami", and the container and disk formats do not match
  • 409 – a public image with the same name already exists
    Example Request: POST http://localhost:8080/xlcloud-xms/images

{
  "name": "my_image",
  "description": "the description",
  "author": "the author",
  "license": "the license",
  "copyright": "the copyright",
  "diskFormat": "qcow2",
  "containerFormat": "ovf",
  "minRam": 100,
  "minDisk": 10,
  "properties": {
    "property": [
      {
        "name": "my_property",
        "value": "the value"
      }
    ]
  }
}

Example Response: 200

{
  "id": 4,
  "href": "/images/4",
  "description": "the description",
  "name": "my_image",
  "catalogScope": "public",
  "author": "the author",
  "license": "the license",
  "copyright": "the copyright"
}

Register Private Image

Registers a new private cloud image. If disk or container format is one of "aki", "ari", or "ami", the container and disk formats must match.

Platform administrators cannot create private images.

Resource: POST accounts/{account_id}/images

Entitlement: POST accounts/{account_id}/images

Required Fields:

  • name – can contain only alphanumeric characters, underscores, hyphens, and dots, and has to start with a letter

Error Response Codes:

  • 400 – disk or container format is one of "aki", "ari", or "ami", and the container and disk formats do not match, you are a platform administrator
  • 404 – account not found
  • 409 – a public image with the same name already exists

Example Request: POST http://localhost:8080/xlcloud-xms/accounts/100/images

{
  "name": "my_image",
  "description": "the description",
  "author": "the author",
  "license": "the license",
  "copyright": "the copyright",
  "diskFormat": "qcow2",
  "containerFormat": "ovf",
  "minRam": 100,
  "minDisk": 10,
  "properties": {
    "property": [
      {
        "name": "my_property",
        "value": "the value"
      }
    ]
  }
}

Example Response: 200

{
  "id": 6,
  "href": "/images/6",
  "description": "the description",
  "accountId": 100,
  "name": "my_image",
  "catalogScope": "private",
  "author": "the author",
  "license": "the license",
  "copyright": "the copyright"
}

Get Image Details

Gets the details of a specified image.

Resource: GET images/{image_id}

Entitlement:

  • to get the details of a public image: GET images/{image_id}
  • to get the details of a private image: GET accounts/{account_id}/images/{image_id}

Error Response Codes:

  • 404 – image not found

Example Request: GET http://localhost:8080/xlcloud-xms/images/6

Example Response: 200

{
  "properties": {
    "property": [
      {
        "name": "My_property",
        "value": "the value"
      }
    ]
  },
  "id": 6,
  "href": "/images/6",
  "description": "the description",
  "accountId": 100,
  "name": "my_image",
  "catalogScope": "private",
  "author": "the author",
  "license": "the license",
  "copyright": "the copyright",
  "diskFormat": "qcow2",
  "containerFormat": "ovf",
  "minRam": 100,
  "minDisk": 10,
  "size": 0,
  "status": "queued"
}

List Public Images

Lists all public images.

Resource: GET images

Entitlement: GET images

Example Request: GET http://localhost:8080/xlcloud-xms/images

Example Response: 200

{
  "image": [
    {
      "id": 1,
      "href": "/images/1",
      "description": "Fedora 18 x64",
      "name": "F18-x86_64",
      "catalogScope": "public",
      "author": "AMG.net",
      "license": "freeware"
    },
    {
      "id": 2,
      "href": "/images/2",
      "description": "Fedora 19 x64",
      "name": "F19-x86_64",
      "catalogScope": "public",
      "author": "AMG.net",
      "license": "freeware"
    },
    {
      "id": 3,
      "href": "/images/3",
      "description": "Fedora 19 x64 for XLcloud",
      "name": "F19-x86_64-xlcloud",
      "catalogScope": "public",
      "author": "AMG.net",
      "license": "freeware"
    },
    {
      "id": 4,
      "href": "/images/4",
      "description": "the description",
      "name": "my_image",
      "catalogScope": "public",
      "author": "the author",
      "license": "the license",
      "copyright": "the copyright"
    },
    {
      "id": 5,
      "href": "/images/5",
      "name": "my_image2",
      "catalogScope": "public"
    }
  ],
  "href": "/images"
}

List Private Images

Lists all private images in a specified account.

Resource: GET accounts/{account_id}/images

Entitlement: GET accounts/{account_id}/images

Example Request: GET http://localhost:8080/xlcloud-xms/accounts/100/images

Example Response: 200

{
  "image": [
    {
      "id": 6,
      "href": "/images/6",
      "description": "the description",
      "accountId": 100,
      "name": "my_image",
      "catalogScope": "private",
      "author": "the author",
      "license": "the license",
      "copyright": "the copyright"
    }
  ],
  "href": "/accounts/100/images"
}

Upload Image Data

Uploads the actual data containing the cloud image. The request body contains the data represented as an octet stream. The content type used for this request must be application/octet-stream.

Resource: POST images/{image_id}/data

Entitlement:

  • to upload the data of a public image : POST images/{image_id}/data
  • to upload the data of a private image : POST accounts/{account_id}/images/{image_id}/data

Required Headers:

  • Content-Type: application/octet-stream

Error Response Codes:

  • 404 – image not found

Example Request: POST http://localhost:8080/xlcloud-xms/images/5/data

(image data as an octet-stream)

Example Response: 200

(no content)

Delete Image

Deletes an image.
 
Resource: DELETE images/{image_id}

Entitlement:

  • to delete a public image: DELETE images/{image_id}
  • to delete a private image: DELETE accounts/{account_id}/images/{image_id}

Example Request: DELETE http://localhost:8080/xlcloud-xms/image/6

Example Response: 204
(no content)

Repositories

XLcloud uses Chef as the tool to install software on stacks, and configure them to work. Repositories are containers of Chef cookbooks. By using a repository, all cookbooks needed to configure a stack may be added with by cloning just a single git repository.

Repositories are identified by their URI and, optionally, a reference. This can be anything that git recognizes as a reference (like branch name, tag name, SHA, or SHA unique prefix).

Repository cookbooks must contain the "metadata.json" file. It can be located either in the top-level directory or in its immediate subdirectories.

Repositories are processed asynchronously, and hence can be in one of several states:

  • processing – the repository is being cloned
  • active – the repository has been successfully cloned, and can now be used
  • broken – an error occurred when cloning the repository, and its unusuable

Repositories have the following fields:

  • id – unique identifier
  • name – name of the repository
  • uri – URI of the actual repository containing Chef cookbooks
    ref – repository reference
  • type – type of the repository, only "git" is supported
  • catalogScope – which catalog the image is in, can be either "public" or "private"
  • accountId – identifier of the account this image belongs to, only if the image is private
  • status – current state of the repository
  • statusReason – explanation of the current state

Register Public Repository

Registers a new public repository. The contents of the repository will be processed asynchronously.  Only git repositories are supported.

Resource: POST repositories

Entitlement: POST repositories

Required Fields:

  • name – can contain only alphanumeric characters, spaces, underscores, hyphens, and dots, and has to start with a letter
  • type – must be "git"
  • uri – must be a valid repository URI

Error Response Codes:

  • 409 – a public repository with the same URI already exists

Example Request: POST http://localhost:8080/xlcloud-xms/repositories

{
  "name": "my_repository",
  "type": "git",
  "uri": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git",
  "ref": "566318c6d96768cc34a236eed2a2598d9811c43e"
}

Example Response: 200

{
  "id": 5,
  "href": "repositories/5",
  "name": "my_repository",
  "uri": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git",
  "type": "git",
  "catalogScope": "public",
  "status": "processing",
  "ref": "566318c6d96768cc34a236eed2a2598d9811c43e"
}

Register Private Repository

Registers a new private repository. The contents of the repository will be processed asynchronously.  Only git repositories are supported.

Platform administrators cannot create private images.

Resource: POST accounts/{account_id}/repositories

Entitlement: POST accounts/{account_id}/repositories

Required Fields:

  • name – can contain only alphanumeric characters, spaces, underscores, hyphens, and dots, and has to start with a letter
  • type – must be "git"
  • uri – must be a valid repository URI

Error Response Codes:

  • 400 – you are a platform administrator
  • 409 – a private repository with the same URI already exists in the account

Example Request: POST http://localhost:8080/xlcloud-xms/accounts/100/repositories

{
  "name": "my_repository",
  "type": "git",
  "uri": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git",
  "ref": "566318c6d96768cc34a236eed2a2598d9811c43e"
}

Example Response: 200

{
  "id": 6,
  "href": "repositories/6",
  "name": "my_repository",
  "uri": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git",
  "type": "git",
  "catalogScope": "private",
  "accountId": 100,
  "status": "processing",
  "ref": "566318c6d96768cc34a236eed2a2598d9811c43e"
}

Get Repository Details

Gets the details of a specified repository.

Resource: GET repositories/{repository_id}

Entitlement:

  • to get the details of a public repository: GET repositories/{repository_id}
  • to get the details of a private repository: GET accounts/{account_id}/repositories/{repository_id}

Error Response Codes:

  • 404 – repository not found

Example Request: GET http://localhost:8080/xlcloud-xms/repositories/1

Example Response: 200

{
  "id": 1,
  "href": "repositories/1",
  "name": "XLcloud Cookbooks",
  "uri": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git",
  "type": "git",
  "catalogScope": "public",
  "status": "active",
  "statusReason": "Repository successfully registered",
  "ref": "HEAD"
}

List Public Repositories

Lists all public repositories.

Resource: GET repositories

Entitlement: GET repositories

Example Request: GET http://localhost:8080/xlcloud-xms/repositories

Example Response: 200

{
  "repository": [
    {
      "id": 1,
      "href": "repositories/1",
      "name": "XLcloud Cookbooks",
      "uri": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git",
      "type": "git",
      "catalogScope": "public",
      "status": "active",
      "statusReason": "Repository successfully registered",
      "ref": "HEAD"
    },
    {
      "id": 4,
      "href": "repositories/4",
      "name": "my repo",
      "uri": "http://git.gitorious.ow2.org/xlcloud/some-repo.git",
      "type": "git",
      "catalogScope": "public",
      "status": "active",
      "statusReason": "Repository successfully registered",
      "ref": "HEAD"
    }
  ],
  "href": "/repositories"
}

List Private Repositories

Lists all private repositories in a specified account.

Resource: GET accounts/{account_id}/repositories

Entitlement: GET accounts/{account_id}/repositories

Example Request: GET http://localhost:8080/xlcloud-xms/accounts/100/repositories

Example Response: 200

{
  "repository": [
    {
      "id": 6,
      "href": "repositories/6",
      "name": "my_repository",
      "uri": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git",
      "type": "git",
      "catalogScope": "private",
      "accountId": 100,
      "status": "broken",
      "statusReason": "org.eclipse.jgit.api.errors.TransportException: http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git: cannot open git-upload-pack",
      "ref": "566318c6d96768cc34a236eed2a2598d9811c43e"
    }
  ],
  "href": "/accounts/100/repositories"
}

Update Repository

Updates a specified repostiory. The whole repository is processed again. If the reference is not specified, the current reference is used. Name of the repository cannot be changed using this method.

Resource: PUT repositories/{repository_id}

Entitlement:

  • to update a public repository: GET repositories/{repository_id}
  • to update a private repository: GET accounts/{account_id}/repositories/{repository_id}

Error Response Codes:

  • 404 – repository not found

Example Request: put http://localhost:8080/xlcloud-xms/repositories/1

{
  "ref": "566318c6d96768cc34a236eed2a2598d9811c43e"
}

Example Response: 200

{
  "id": 1,
  "href": "repositories/1",
  "name": "XLcloud Cookbooks",
  "uri": "http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git",
  "type": "git",
  "catalogScope": "public",
  "status": "processing",
  "statusReason": "org.eclipse.jgit.api.errors.TransportException: http://git.gitorious.ow2.org/~xlcloud-continuous-integration/xlcloud/cookbooks-ci.git: cannot open git-upload-pack",
  "ref": "566318c6d96768cc34a236eed2a2598d9811c43e"
}

Delete Repository

Deletes a repository.

Resource: DELETE repositories/{repository_id}

Entitlement:

  • to delete a public repository: DELETE repositories/{repository_id}
  • to delete a private repository: DELETE accounts/{account_id}/repositories/{repository_id}

Example Request: DELETE http://localhost:8080/xlcloud-xms/repositories/3

Example Response: 204
(no content)

Cookbooks

Cookbooks are the fundamental units of configuration. Each cookbook defines a scenario, such as everything needed to install and configure MySQL, and then it contains all of the components that are required to support that scenario.

Cookbooks can define dependencies and attributes using the "metadata.json" file.

Cookbooks have the following fields:

  • id – unique identifier
  • name – name of the cookbook
  • version – version of the cookbook
  • description – information describing what the cookbook does
  • repositoryId – identifier of the repository the cookbooks belongs to
  • dependencies – list of cookbook dependencies
    • dependencyName – name of the cookbook that is depended on
    • satisfied – whether that cookbook is present

Get Cookbook Details

Gets the details of a specified cookbook. An additional query parameter "recursive-dependencies" can be specified to determine whether cookbook dependencies should be retrieved recursively (default is "false").

Resource: GET cookbooks/{cookbook_id}?recursive-dependencies={boolean}

Entitlement:

  • to get the details of a cookbook from a public repository: GET cookbooks/{cookbook_id}
  • to get the details of a cookbook from a private repository: GET accounts/{account_id}/cookbooks/{cookbook_id}

Error Response Codes:

  • 404 – cookbook not found

Example Request: GET http://localhost:8080/xlcloud-xms/cookbooks/665?recursive-dependencies=true

Example Response: 200

{
  "dependencies": [
    {
      "dependencyName": "hostsfile",
      "satisfied": true
    },
    {
      "dependencyName": "nfs",
      "satisfied": true
    },
    {
      "dependencyName": "line",
      "satisfied": true
    },
    {
      "dependencyName": "nfs_export",
      "satisfied": true
    },
    {
      "dependencyName": "nfs",
      "satisfied": true
    },
    {
      "dependencyName": "line",
      "satisfied": true
    }
  ],
  "description": "Installs/Configures a NFS server",
  "href": "cookbooks/665",
  "id": 665,
  "name": "nfs-server",
  "repositoryId": 6,
  "version": "0.1.0"
}

List Public Cookbooks

Lists all cookbooks in all public repositories.

Resource: GET cookbooks

Entitlement: GET cookbooks

Example Request: GET http://localhost:8080/xlcloud-xms/cookbooks

Example Response: 200

{
  "cookbook": [
    {
      "description": "Installs/Configures ark",
      "href": "cookbooks/225",
      "id": 225,
      "name": "ark",
      "repositoryId": 5,
      "version": "0.4.3"
    },
    {
      "description": "Provides the MCollective orchestration framework.",
      "href": "cookbooks/653",
      "id": 653,
      "name": "mcollective",
      "repositoryId": 6,
      "version": "0.11.0"
    }
  ],
  "href": "/cookbooks/"
}

List Account Cookbooks

Lists all cookbooks in all private repositories of a specified account.

Resource: GET accounts/{account_id}/cookbooks

Entitlement: GET accounts/{account_id}/cookbooks

Error Response Codes:

  • 404 – account not found

Example Request: GET http://localhost:8080/xlcloud-xms/accounts/195/cookbooks

Example Response: 200

{
  "cookbook": [
    {
      "accountId": 195,
      "description": "Installs/Configures ark",
      "href": "cookbooks/225",
      "id": 225,
      "name": "ark",
      "repositoryId": 5,
      "version": "0.4.3"
    }
  ],
  "href": "/accounts/195/cookbooks"
}

List Repository Cookbooks

Lists all cookbooks in to a specified repository.

Resource: GET repositories/{repository_id}/cookbooks

Entitlement:

  • to list cookbooks in a public repository: GET repositories/{repository_id}/cookbooks
  • to list cookbooks in a private repository: GET accounts/{account_id}/repositories/{repository_id}/cookbooks

Example Request: GET http://localhost:8080/xlcloud-xms/repositories/5/cookbooks

Example Response: 200

{
  "cookbook": [
    {
      "accountId": 195,
      "description": "Installs/Configures ark",
      "href": "cookbooks/225",
      "id": 225,
      "name": "ark",
      "repositoryId": 5,
      "version": "0.4.3"
    }
  ],
  "href": "/repositories/5/cookbooks"
}

Recipes

Recipes represent Chef recipes. A recipe is a basic element that may be used to configure the lifecycle management of layers in a stack.  It represents a basic step of configuration of the layer environment. It is a Ruby script that may be executed on instances of a layer to configure the environment. Runlists of recipes are executed on lifecycle events. Recipes have to be part of the cookbook and can be create only by registering a repository. Recipes are identified in the platform by their name.

Recipes may be parameterized. Parameters are common to the whole cookbook and their values may be defined during application deployment.

Recipes have the following fields:

  • id – unique identifier
  • name – name
  • description – text describing the recipe function
  • cookbookId – identifier of the cookbook the recipe belongs to
  • attributes – list of the attributes of the recipe
    • name – name of the attribute
    • displayName – more user-friendly name, used for display
    • description – description of the attribute
    • requirement – whether the value of the attribute must be set during deployent, can be one of: "required", "recommended", "optional"
    • type – what kind of value the attribute can take, can be one of: "hash", "array", "string"
    • choice – actual value of the attribute set during the deployment
    • defaultValue – default value of the attribute which will be used if no value is set

Get Recipe Details

Returns the details of a specified recipe.

Resource: GET recipes/{recipe_id}

Entitlement:

  • to get the details of a public recipe: GET recipes/{recipe_id}
  • to get the details of a private recipes: GET accounts/{account_id}/recipes/{recipe_id}

Error Response Codes:

  • 404 – recipe not found

Example Request: GET http://localhost:8080/xlcloud-xms/recipes/1039

Example Response: 200

{
  "attributes": [
      "defaultValues": [],
      "description": "List all plugins that will be deactivated",
      "displayName": "Disabled plugins",
      "name": "rabbitmq/disabled_plugins",
      "type": "array"
    },
    {
      "description": "IP address to bind.",
      "displayName": "RabbitMQ server IP address",
      "name": "rabbitmq/address"
    },
    {
      "defaultValues": [
        "{:name=>\"guest\", :password=>\"guest\", :rights=>[{:vhost=>nil, :conf=>\".*\", :write=>\".*\", :read=>\".*\"}]}"
      ],
      "description": "Users and description of their rights",
      "displayName": "Users and their rights on rabbitmq instance",
      "name": "rabbitmq/enabled_users",
      "type": "array"
    },
  ],
  "cookbookId": 677,
  "description": "Manage users with node attributes",
  "href": "recipe/1039",
  "id": 1039,
  "name": "rabbitmq::user_management"
}

List Cookbook Recipes

Lists all recipes from a specified cookbook. Recipe attributes are not provided by this method.

Resource: GET cookbooks/{cookbook_id}/recipes

Entitlement:

  • to list the recipes in a public cookbook: GET cookbooks/{cookbook_id}/recipes
  • to list the recipes in a private cookbook: GET accounts/{account_id}/cookbooks/{cookbook_id}/recipes

Error Response Codes:

  • 404 – cookbook not found

Example Request: GET http://localhost:8080/xlcloud-xms/cookbooks/677/recipes

Example Response: 200

{
  "href": "/cookbooks/677/recipes",
  "recipe": [
    {
      "cookbookId": 677,
      "description": "Install and configure RabbitMQ",
      "href": "recipe/1035",
      "id": 1035,
      "name": "rabbitmq"
    },
    {
      "cookbookId": 677,
      "description": "Set up RabbitMQ clustering.",
      "href": "recipe/1036",
      "id": 1036,
      "name": "rabbitmq::cluster"
    },
    {
      "cookbookId": 677,
      "description": "Manage plugins with node attributes",
      "href": "recipe/1037",
      "id": 1037,
      "name": "rabbitmq::plugin_management"
    },
    {
      "cookbookId": 677,
      "description": "Manage virtualhost with node attributes",
      "href": "recipe/1038",
      "id": 1038,
      "name": "rabbitmq::virtualhost_management"
    },
    {
      "cookbookId": 677,
      "description": "Manage users with node attributes",
      "href": "recipe/1039",
      "id": 1039,
      "name": "rabbitmq::user_management"
    }
  ]
}

Find Recipes by Names

Lists all public recipes whose name is in a specified list. This list is defined using the "name" attribute which can be specified multiple times.

Resource: GET recipes?name={recipe_name}

Entitlement: GET recipes

Example Request: GET http://localhost:8080/xlcloud-xms/recipes?name=getting-started/setup&name=xia

Example Response: 200

{
  "href": "/recipes?name=getting-started/setup&name=xia",
  "recipe": [
    {
      "cookbookId": 663,
      "description": "runs xia service",
      "href": "recipe/1015",
      "id": 1015,
      "name": "xia"
    },
    {
      "attributes": [
        {
          "defaultValues": "/tmp",
          "description": "Working directory",
          "displayName": "Work directory",
          "name": "getting-started/work_dir",
          "type": "string"
        },
        {
          "defaultValues": "hello_world",
          "description": "Name of the executable",
          "displayName": "Application name",
          "name": "getting-started/deploy/app_name",
          "type": "string"
        },
        {
          "defaultValues": "/usr/local/bin",
          "description": "Directory where to install the application",
          "displayName": "Installation directory",
          "name": "getting-started/install_dir",
          "type": "string"
        }
      ],
      "cookbookId": 668,
      "description": "Setup getting-started",
      "href": "recipe/1023",
      "id": 1023,
      "name": "getting-started/setup"
    }
  ]
}


This wiki is licensed under a Creative Commons 2.0 license
XWiki Enterprise 5.4.6 - Documentation - Legal Notice

Site maintained by