XMS Web Console User Guide

Table of Content

What is Xlcloud Management System Web Console?

The XLcloud Management System (XMS) Web Console was designed to provide a web console for XMS services. Its main purpose is to simplify the use of the XMS REST API, and to provide a way to manage the XLcloud platform using a graphical user interface. It is an administration endpoint, and as such supports only management functionalities, not the actual stack utilization by end users and clients.

In the bigger (platform-wide) picture, the XMS Web Console can be treated as the main entry point for administrators and operators of XLcloud. This management console covers all major XMS functional modules, among which the following can be identified:

Identity and Access Management – XLcloud Management System provides a central authorization and authentication module for the entire platform. This includes control of access and privileges at different platform layers: service, SaaS, stack etc.

Cloud Resources Management – cloud resources are the main part of the XLcloud Management System functionalities, allowing users to define new platforms in the PaaS model, and use XMS as a PaaS provider.

Cloud Catalogs Management – contains resources ready to be reused during the configuration of the platform in the PaaS model. This module also contains ready-made platforms which can be reused and launched by the end user.

Additionally, XMS Web Console supports internal Service Provider Interface (SPI) that can be use to enhance its functionalities through custom extensions.

Dashboard

Description of the main page of the application and navigation through the platform.

Log in to the System

To be able to use the XMS Web Console, user needs to authenticate in the XLcloud central Identity and Access Management Service. Web Console will automatically redirect users to the login form if the user is not authenticated, or his session has timed out. After providing correct credentials, user will be redirected back to the page he wanted to access.

xlcloud_login.png

Note that the specified credentials are used to authenticate the user in the Web Console, while authorization of his requests in XMS REST API requires a valid access token (that is being generated through the OAuth 2.0 flow). Since XMS Web Console is configured to be a trusted XLcloud client, access tokens used by this application are generated automatically, without any user prompts.

Main Page

The center part of the main page contains basic information about XLcloud. Below we can find useful links to the main system functionalities. On the left, there is a main menu visible on all pages of the application. In the right corner of the page there is a useful menu (with your user name), allowing you user to manage your profile.

image2014-2-14_13_40_21.png

Main Menu

Main menu visible in the left part of the screen can be used to easily navigate between different sections of the XMS Web Console. Menu items are grouped to simplify the navigation process even more. Depending on the user's role in the system, as well as the entitlements he has, different menu items are available. Table below outlines all possible menu items for standard XMS Web Console installation (keep in mind, though, that due to XMS modularity, this list can be extended by custom plugins).
image2014-2-14_15_5_19.png
image2014-2-14_15_6_48.png
image2014-2-14_15_6_3.png

Description of all menu items depending on the user role:

Platform Administrator Role
AccountsSection of accounts
UsersSection of all users (platform administrators and account users in all accounts)
ProjectsSection of all projects in all accounts
StacksSection of all stacks in all projects
Cloud ImagesSection of public cloud images
Cookbook RepositoriesSection of public repositories
Layer BlueprintsSection of public layer blueprints
Stack BlueprintsSection of public stack blueprints
Account User Role
GroupsSection of account groups
UsersSection of account users
ProjectsSection of projects
StacksSection of all stacks in all projects within the account
Cloud ImagesSection of private cloud images within the account
Cookbook RepositoriesSection of public and private cloud images
Layer BlueprintsSection of public and private layer blueprints
Stack BlueprintsSection of public and private stack blueprints

When the browser window is too small to present the whole page correctly, the main menu is hidden as in the screenshot:

image2014-2-14_15_8_57.png

User is able to open the menu by using the button visible in the screenshot.

User Menu

In the right corner of the page, there is a menu with the user name, expanding when clicked. 

user-menu.png

Using this module, the user is able to view his profile, described more broadly in My Profile. When user switches to the Advanced Mode, advanced functionalities of system are presented to user. It affects mainly the stack page which will be described later in Stack Page

Log out of the System

In the user menu there is a also link to log out of system. The user is informed that he is logged out of system correctly, and using the visible link he is able to log in once again.

image2014-2-17_11_9_41.png

To log out means to destroy the session in XLcloud Management System Web Console, and log out of the XLcloud central Identity and Access Management Service. This operation does not revoke the created access token. When the user logs into system once again, it is highly possible that the same access token will be reused.

My Profile

The profile page contains basic information about the user, and gives him the ability to manage his entitlements and access tokens. Depending on their role in the system, account users can also manage their keypairs and memberships in groups and projects.

image2014-2-17_11_30_34.png

Below the basic user information, there is an information about other entities in system related to user.

Change Password

There is link to change the user password just beside the user name in the details area. When clicked, a new popup dialog appears, and user i prompted to type in a new password and confirm it. The password must contains at least 8 non-whitespace characters, and if validation fails, the user will be informed by an appropriate warning.

User Entitlements

User entitlements are the only part of entitlement management in the platform. They describe which actions users can perform. Atomic actions are grouped by their functionality and entities they operate on. Each group is expandable.

image2014-2-17_11_50_3.png

Edit Entitlements

 

The user can edit his own entitlements, but it is highly discouraged. A basic assumption of access management is that a user cannot assign entitlements higher than the ones he possesses.  In fact, he is able only to assign entitlements from groups he is a member of to his own entitlements.
When the user clicks the button to edit entitlements, he is redirected to a new page with a similar tree structure of entitlements he can assign. The user can then assign new entitlements or remove current one.

image2014-2-17 _2_18_43.png

Note that when you remove some of your own entitlements, it might not be possible to assign them back yourself. 

User Groups

This tab is visible only to account members, and shows the list of all groups the user belongs to.

image2014-2-17_12_37_59.png

Modify Groups

If the user has entitlements to assign himself to groups, the button to modify groups is presented. The user can choose from the list of available groups those he wants to belong to.

image2014-2-17_12_46_19.png

User Projects

User projects tab is also visible only to account members, and shows the list of all projects the user belongs to. Each stack in XLcloud must belong to a project, and only the members of that project can perform operations like starting, stopping, suspending and resuming of that stack.

image2014-2-17_13_18_20.png

Download RC-File

For each project, the user can download the RC-File (runcome file). Such a file contains a Unix script which exports user credentials to shell variables, enabling the user to use OpenStack command line interface tools. After the link is clicked, appropriate file can be downloaded. 

Example of an RC-File:

#!/bin/bash
export OS_AUTH_URL="http://keystone.url:5000/v2.0"
export OS_TENANT_ID="6f39b07b59b84c26a452ae90755bdccc"
export OS_TENANT_NAME="demo_project"
export OS_USERNAME="demo"
echo "Please enter your openstack password: "
read -s OS_PASSWORD_INPUT
export OS_PASSWORD=$OS_PASSWORD_INPUT

Modify Projects

Just like in the case of groups, the user can modify his project memberships, and choose projects he want to belong to from the list of available projects.

User Access Tokens

This tab is visible to all users, regardless of their role in the system. The presented list contains all access tokens generated for and by the user, both user-scoped and token-scoped. 

image2014-2-17_13_43_47.png

Access Token Details

After clicking an access token, the user is redirected to the page with detailed information about that access token.

image2014-2-17_13_48_18.png

Basic information includes token expiry time, its scope, and the user that generated that access token. Moreover, every access token can have separate entitlements. By default, user-scoped access tokens have the same entitlements as the user. Newly generated token-scoped access tokens have no entitlements, and to make them usable, the user has to assign to them chosen entitlements.

Create Access Token

The user can generate a new token-scoped access token using the application. When he does so, he is redirected to the Xlcloud Identity and Access Management Service, and is prompted to allow for a new access token to be generated. 

image2014-2-17_14_3_58.png

After the user generates a new access token, he is redirect back to list of access tokens, and the newly-created one can be seen there.

If the user denies the application to create a new access token, he can log out of system, or go back to page he was visiting most recently.

image2014-2-17_14_23_30.png

Revoke Access Token

The user can revoke an access token using the "Actions" menu on the list of access tokens. After a token is removed, subsequent use of this token to authorize in the API will return a forbidden exception. The user is not able to revoke an access token he currently using in the Xlcloud Web Console session, and this is the only restriction.

Edit Entitlements

Editing entitlements is identical to editing user entitlements. Users cannot assign entitlements higher then the ones they possess.

User Keypairs

This tab is visible only to account members. Every keypair is generated by the user, and can be reused in every project he belongs to. The list contains all keypairs registered in the platform that can be used when configuring stacks.

image2014-2-17_14_45_25.png

Generate Keypair

To generate a keypair means to create a new private key and store it on the user's local machine. There is no other possibility to retrieve the generated private key later. To generate a keypair, use the link above the list of keypairs, and a new popoup will be shown. The user has to type the name of the keypair (name can contain only letters, digits, underscores and hyphens) and an appropriate file is downloaded by the web browser. Afterwards the keypair appears on the list. 

Import Keypair

The user can also import his own keypair into the platform. In this case, besides typing the name, the user has to provide the public key of the keypair.

image2014-2-17_14_53_19.png

Show Details

By clicking on the keypair name, we can view its details, including the name, public key, and the fingerprint. 

image2014-2-17_14_56_19.png

Delete Keypair

Deleting a keypair is possible from the "Actions" menu on the keypair list. Note that after a keypair is removed, the user has to reconfigure all stopped stacks where he used that keypair.

Accounts

This section is visible only to platform administrators, and allows to operate on accounts. This includes creating an account, and operating on entities related to accounts.

List Accounts

The main page of this section contains the list of all accounts registered in the platform. 

image2014-2-17_15_9_0.png

Create Account

To create a new account, the user has to click on the link above the account list. He is redirected to a new page where he is prompted to type in the account name, which can contain only alphanumeric characters or ".-_" and has to start with a letter. Leading and trailing spaces will be omitted

image2014-3-7_14_50_42.png

Account Details

Basic account details contain only the name of the account. 

image2014-2-17_23_34_47.png

Below this details, there are multiple tabs with entities related to the account. This view enables platform administrators to perform actions on those entities. For example to modify private cloud resources or private cloud catalogs. Every action on those entities will be described in detail in appropriate sections.

Users

The "Users" tab contains the list of account members. Moreover, in this view, the platform administrator is able to create a new user in the account. Other actions are described in details in Users Section.

image2014-2-17_23_41_38.png

Groups

The "Groups" section contains the list of account groups. Additionally, this is the only view which enables platform administrators to perform actions on account groups, described in detail in Groups Section.

image2014-2-18_7_54_4.png

Whenever a new account is created, those 3 groups are also generated by default. They are created in order to facilitate entitlement management, and it is highly recommended to assign users to those groups, when managing their entitlements.

Projects

The "Projects" tab lists all projects in an account, regardless of the project status. Platform administrators are limited to just modifying project members. Only account members are allowed to create or remove projects. More information about projects can be found in the Projects Section.

image2014-2-18_7_59_4.png

Stacks

The "Stacks" tab contains all stacks from all projects within the account. Platform administrators are limited to only listing the stacks, and so cannot perform actions like starting, stopping, suspending, resuming, or deleting. The only possible action is to promote a stack to a stack blueprint. More about stacks can be found in the Stacks Section.

image2014-2-18_8_5_10.png

Cloud Images

The "Cloud Images" tab contains the list of private images of the account. In this view, platform administrators are able to view account images. More about cloud images can be found in the Cloud Images Section

image2014-2-18_8_10_45.png

Repositories

The "Repositories" tab contains the list of registered repositories in the account. Only in this view, platform administrators are able to view repositories registered in an account and perform actions on them. Statuses of repositories are loaded after the list is displayed, and if any repository is in the "Processing" status, its status will be polled until the processing finished. More about repositories can be found in the Repositories Section.

image2014-2-18_8_20_29.png

Layer Blueprints

The "Layer Blueprints" tab contains the list of private layer blueprints registered in the account. The only possible action is to delete one of the blueprints. More about layer blueprints can be found in the Blueprints Section.

image2014-2-18_8_55_14.png

Stack Blueprints

The "Stack Blueprints" tab contains the list of private stack blueprints registered in the account. Platform administrators cannot create stacks, so the only possible action is to delete one of the blueprints. More about stack blueprints can be found also in the Blueprints Section.

image2014-2-18_8_57_34.png

Quotas

Quotas limit the number of account entities. In the XLcloud Management System, the following entities can be limited:

Quota

Description

usersquota for users registered within the account
stacksquota for stacks created in all projects within the account
stack-blueprintsquota for promoted stack blueprints
layer-blueprintsquota for promoted layer blueprints

Platform administrators are able to view the quota limits and current usage information for the account.

image2014-2-18_8_59_12.png

Edit Quota

It is possible to edit quotas. When the user click on the quota name, a new popup will be displayed. 

image2014-2-18_9_15_54.png

The user can type the limit value. Leaving the value empty will result in no quota limitation for that entity.

Users

There are different views of the users section for different roles.
Platform administrators can list all users created in platform. If there is no account name next to the name, it means that the user is a platform administrator.

image2014-2-18_9_21_5.png

For account members the view is simplified, and the list contains only users created within the account. 

image2014-2-18_9_23_0.png

Create User

For both roles, the button to create a user moves to the same page. Platform administrators will be able to create an another platform administrator in this view. To create an account user, a platform administrator must perform this action in the account view.

Account members will be able to create a user within the same account, and assign him to selected groups at the same time.

image2014-2-18_9_28_57.png

The user has to type a new username, password, and confirm that password for security reasons. The password must contains at least 8 non-white space characters. When creating a new user, it is possible to assign him to some of the available groups, but only if the created user is an account member.

User Details

User details page is the same page as My Profile, but with some limitations. Users cannot view others keypairs, so there is no such tab in the user view.

Groups

The "Groups" section is only available to account members. This section allow one to modify groups and assign account members to them. Groups supports entitlement management, so each group member is granted the group entitlements. The main page of this section contains the list of all the groups registered in the account. 

image2014-2-18_13_52_10.png

By default, those 3 groups are created for each new account. They contain sets of entitlements which allow users to use the XLcloud Management System Web Console.

Show Details

To view the details of a group, the user has to click on the group name, and will be navigated to new page.

image2014-2-18_17_31_54.png

Below the basic information about the group there are two tabs allowing the user to edit group memberships and entitlements.

Users

The "Users" tab contains the list of members of a the group.

image2014-2-18_17_32_55.png

It is possible to modify the users by clicking on the "Modify users" button. The user is then navigated to new page.

image2014-2-18_17_35_23.png

On this page, the user can choose all members of the group. Users currently assigned to group are checked by default.

Entitlements

The "Entitlements" tab includes a list all the entitlements assigned to group.

image2014-2-18_17_38_36.png

As in the case of user entitlements, the user can modify entitlements, but note that it is impossible for a user to assign entitlements higher than the ones he possesses.

Delete Group

When on the list of groups, it is possible to delete a group. This does not cause the members of that groups to be deleted. Deleting a group has effect on the entitlements of the members of that group. It revokes any entitlements they might have been granted as its members.

Create Group

To create a new group, the user has to type its name and description. It is recommend to configure the entitlements of the group, as the main purpose of groups is to manage user entitlements. Group name has to be unique within the account.

image2014-2-18_17_44_59.png

Projects

The "Projects" section is available not only to account members, but also for platform administrations. The difference is that only account members can create or delete projects, and so platform administrators are not allowed to perform those operations. However, they can still assign users to projects. There's also a difference in visibility of the projects. Platform administrators can control all projects in all accounts, but account members can only manage projects created within their account. To facilitate management, the list of projects seen by platform administrators is supplemented with the account column indicating which account a project belong to.

image2014-2-18_19_8_33.png

The status of the project is loaded after the project is displayed on the list. When the current status is "Starting" or "Deleting", the status will be updated periodically, until a the project enters a terminal state (e.g. "Active").

Create Project

Only account members are able to create projects. By default, the user creating a project is automatically assigned to that project. When the user clicks on the button to create a project, he is be redirected to a new page. 

image2014-2-18_19_13_31.png

The project name has to be unique within the account, and if it's not, the user will be informed by an appropriate warning. During the creation of the project a new network configuration with the first (default) subnet is created. When the user types the name of the project, the name of the first subnet is suggested automatically, but the can change that name. The user has to set up the CIDR of this subnet, but in this case the application also assists the user and suggests "10.0.0.0/16" by default. Every project has to have at least one subnet in its network configuration and CIDRs cannot overlap. After the project is created, it's status is "Starting". In this state, the user cannot start any stacks in the project. Only projects with status "Active" allow such an operation. There are two statuses for when something goes wrong – "Failed" and "Failed to Delete". The first one means that the project could not be created, and it's only possible to delete it. The second one means that an error occurred while deleting a project, and the user can try to delete it once again. The status "Deleting" means that the project resources are currently being released, and it should disappear from the project list, provided that no error occurs. 

Show Details

By clicking on the project name, the user navigates to new page with detailed information about the project. Basic information contains its name and status.

image2014-2-18_19_29_19.png

Below the basic information there are 3 tabs – "Users", "Stacks" and "Network".

Users

The "Users" tab contains the list all members of the project. As it was mentioned earlier, a user that created a project is by default assigned to that project. Platform administrators and account members are allowed to modify the users in the project, as it was the case for groups. Users can select from the list of all users within the project account.

image2014-3-25_15_52_47.png

Stacks

The "Stacks" tab contains all stacks created within the project. All users can view this page. However, if a user is not a project member (in particular if he's a platform administrator), he is not able to view the status of the stack. Such users are also forbidden to start, stop, pause or resume the stacks. The only action they can take is to promote a stack.

image2014-3-25_15_54_23.png

Network

The "Network" tab contains information about the network configuration of the project. More precisely, it presents a list of available subnets in the network. The network configuration can be modified when the project is active or starting.

image2014-3-25_15_58_19.png

Create a Subnet

Only project members are allowed to create a subnet, so the button is visible only to those users. After it's clicked, a new popup appears, and the user can type in the subnet name and the CIDR. The name of the subnet must be unique within the project, and can contain only alphanumeric characters or ".-_" and has to start with a letter. In this case, the user has to provide the subnet CIDR himself without any hints, but the CIDR is still validated not to overlap any other subnet in the project.


Set a Subnet as the Default

One of the subnets is always marked as default. The user is not able to delete such a subnet. When creating a stack from a blueprint, all layers are attached to the default subnet. The user can change the default subnet by clicking on a radio button.

Delete Subnet

Only non-default subnets can be deleted, and this operation is only allowed to project members. It is not possible to delete the first subnet (created together with the project), because the project broker is attached to that subnet. Similarly, the user will be informed by appropriate message if he tries to delete a subnet with any stack instances attached to it. When the user deletes a subnet, he has to reconfigure all stack layers which were using that subnet, or else he won't be able to start those stacks.
 

Leases

The leases tab contains list of reservations of physical hosts made for the project. Project details contains calendar with specified project leases. Red color means that lease is broken, green means that lease is currently active, and grey one is for scheduled lease status. 

image2014-3-25_16_43_28.png

Create lease

To create lease click on the button. Note that only project members are allowed to create new leases. 

image2014-3-25_16_47_2.png

Lease name must be unique within project and can contain only alphanumeric characters and ".-_" and has to start with a letter. User has to specified start date or can choose that lease has to start now. Moreover during date specification, above the input there is displayed a timezone, in which user has to type a datetime. By default the option start now is enabled. User can specify the duration of the lease, and by default it is set to one day or choose the end date. User has to specify the rane of the hosts that he wants to reserve. Moreover he can add more properties to the reservation as hypervisor properties and resource properties. That are additional requirements that host must satisfy to be part of the reservation.

Lease Details

By clicking on the lease additional menue is displayed. User can show details of the lease, can edit lease or delete it. To achive one of those action user does not have to be a member of the project.

image2014-3-25_16_54_0.png

By clicking on the show details, new popup appears with additional information of the lease.

image2014-3-25_17_31_28.png

Edit Lease

User can edit lease names and start date and end date of the lease.

image2014-3-25_17_32_51.png

Remove lease

User using menu of the lase are allowed to remove lease.

Cloud Images

The "Cloud Images" section is available for both account memebers and platform administrators. The difference is that platform administrators can operate on public images, but do not see the tab with private images. To perform actions on private cloud images, a platform administrator can navigate to the account details screen. The "Public" tab contains all public images available in the platform which can be used to create stacks.

image2014-2-19_9_18_27.png

Create Cloud Image

Te register a new cloud image, the user has to upload a file containing that image. This can be done in the top part of the page, and when the user uploads the file, the image name will be automatically filled in according to name of file. The user can provide a short description of the image, its license, and copyright, but is is not mandatory. 

The disk format of the virtual machine image is the format of the underlying disk image. Virtual appliance vendors have different formats for laying out the information contained in a virtual machine disk image. You can set your image disk format to one of the ollowing:

Format

Descripion

rawThis is an unstructured disk image format
vhdThis is the VHD disk format, a common disk format used by virtual machine monitors from VMWare, Xen, Microsoft, VirtualBox, and others
vmdkAnother common disk format supported by many common virtual machine monitor
vdiA disk format supported by VirtualBox virtual machine monitor and the QEMU emulator
isoAn archive format for the data contents of an optical disc (e.g. CDROM)
qcow2A disk format supported by the QEMU emulator that can expand dynamically and supports Copy on Write
akiThis indicates what is stored in Glance is an Amazon kernel image
ariThis indicates what is stored in Glance is an Amazon ramdisk image
amiThis indicates what is stored in Glance is an Amazon machine image

The container format refers to whether the virtual machine image is in a file format that also contains metadata about the actual virtual machine. Note that the container format string is not currently used by Glance or other OpenStack components, so it is safe to simply specify bare as the container format if you are unsure. You can set the container format of your image to one of the following:

Format

Description

bareThis indicates there is no container or metadata envelope for the image
ovfThis is the OVF container format
akiThis indicates what is stored in Glance is an Amazon kernel image
ariThis indicates what is stored in Glance is an Amazon ramdisk image
amiThis indicates what is stored in Glance is an Amazon machine image

Also, optional parameters can be specified, like the minimal disk in GB and minimal RAM in MB.

When adding an image to Glance, you may specify some common image properties that may prove useful to the consumers of your image. The list of the names of these properties and the expected values is as follows:

Property

Expected Value

architecture

Operating system architecture

instance_uuid

The ID of the instance used to create this image.

kernel_id

The ID of image stored in Glance that should be used as the kernel when booting an AMI-style image.

ramdisk_id

The ID of image stored in Glance that should be used as the ramdisk when booting an AMI-style image.

os_distro

The common name of the operating system distribution

os_version

The operating system version as specified by the distributor.

But user can specify his own properties. There is no validation for this section.

image2014-2-19_9_24_51.png

Show Details

To view the details of a cloud image, the user has to click on the image name on the image list. The details of the image contain the same information as was specified when creating the image, but without the possibility to edit any of those values.

Delete Image

The user can delete an image when on the image list or the image page, but needs to remember that he will have to reconfigure all stopped stacks that use that image. Otherwise, he won't be able to start those stacks.

Cookbook Repositories

The "Cookbook Repositories" section is available to all users – platform administrators and account members. 

image2014-2-19_11_0_0.png

The tab with private repositories is displayed only to account members, and contains the list of all registered repositories within the account. Platform administrators can list account repositories in the account details view. 

Repository status is loaded after the repository is displayed on the list. "Active" status means that the repository has been successfully registered in platform, "Broken" means that something went wrong while processing the repository, and "Processing" means that the XLcloud Management System is currently processing the repository – registering or updating it.

Show Details

To view the details of a repository, the user can click its name on the list. He is navigated to new page, with basic information including the repository name, its type (currently, only git repositories is supported), catalog scope, status, and the reference to the git repository.

image2014-2-19_11_55_11.png

Cookbooks

The list of cookbooks is available only when repository has been successfully registered in the XLcloud Management System (it's active or currently updating). The list contains all cookbooks found in the repository during its registration.

image2014-2-19_12_6_3.png

When user the clicks on the name of one of the cookbooks, he is navigated to a new page with more information about that cookbook, including its name, version, description and dependencies. This information is stored in the "metadata.json" file which has to be placed inside the cookbook directory.

image2014-2-19_12_11_36.png

Recipes

On the cookbook page, under the basic information, there is the list of recipes in the cookbook.

image2014-2-19_12_16_10.png

When the user clicks the name of a recipe, he is navigated to a new page with more information about the recipe – its description, cookbook it belong to, and the list of attributes.

Attributes

The "Attributes" section is located below the basic recipe information on the recipe page. It contains all attributes defined in the cookbook, which could be setup during layer lifecycle configuration. 

image2014-2-19_12_18_11.png

When the user clicks on name of the attribute, a new popup will appear with more information about the attribute:

image2014-2-19_12_21_4.png

The name of the attribute is the name as it will be typed in the lifecycle configuration file. The display name is the name that appears in the user interface. The description is a short explanation of the attribute, also displayed in the user interface. "Choice" is an array of available values of the attribute. "Type" is the value type, either string (regular text), array (an array of values), or hash (a value saved as JSON).

Register Repository

To register a repository, the user has to click on the "Register repository" button. A new popup will appear and the user has to fill the form in. 

image2014-2-19_12_35_43.png

The name of the repository is the name that the repository will be displayed under. The "Type" is the type of the repository, and currently the XLcloud Management System supports only git repositories. URI is the address to the git repository, where the system will be able to clone it from. The reference is anything that git will recognize as a "reference" – branch name, tag name, SHA, or SHA unique prefix. This parameter is optional and by default the master branch is used.

The XLcloud Management System supports only repositories, where the cookbooks are located in the main directory or in it's subdirectories. Each cookbook must contain the "metadata.json" file with information about the cookbook. Every "metadata.rb" file can be convert to the "metadata.json" file using the knife tool (see Knife Documentation).

Registration of a repository is an asynchronous process. When the user registers a repository, it's status is "Processing" at first, until the system finished the processing. Afterwards, the repository status changes to either "Active" or "Broken".

Update Repository

Only "Active" repositories can be updated. Updating a repository means that the XLcloud Management System will download the repository once again and reprocess it. Users can specify a new reference or use the previous one.

Delete Repository

If repository is in a terminal state ("Active" or "Broken") it can be deleted by the user. If the repository is currently being processed, it will be deleted just after processing is finished. This operation does not affect current lifecycle configurations of existing layers. However, when the user tries to update lifecycle configurations that utilized the deleted repository, attribute values will not be removed from the configuration. Note that the Cheffile will be generated again, without this repository.

Leases

Leases section contains list of reservations of physical hosts made for all the projects within all accounts. Section contains calendar with specified project leases. Red color means that lease is broken, green means that lease is currently active, and grey one is for scheduled lease status.
image2014-3-25_17_13_40.png

When user click on the lease, additional menu of the lease appears and user is allowed to perform actions on the lease.

Moreover user can change view and the list of the leases is shown:

image2014-3-25_17_35_32.png

Lease Details

By clicking on the lease additional menu is displayed. User can show details of the lease, can edit lease or delete it. To achive one of those action user does not have to be a member of the project.

image2014-3-25_16_54_0.png

By clicking on the show details, new popup appears with additional information of the lease.

image2014-3-25_17_31_28_1.png

Edit Lease

User can edit lease names and start date and end date of the lease.

image2014-3-25_17_32_511.png

Remove lease

User using menu of the lase are allowed to remove lease.

Stacks

The "Stacks" section is accessible to account members and platform administrators. Account users can list all stacks created in all projects within their account. Platform administrators are able to list all stacks created in all accounts.  

image2014-2-19_14_25_35.png

The view for account members is similar, but without the "Account" column. Status of the stack is loaded after the stack is displayed on the list. To be able to view the stack status, the user has to be a member of the project the stack belongs to. Because of this limit, platform administrators in particular are not able to see any stack statuses. Operations on the stack, like starting, stopping, suspending, resuming, or deleting it, are available only after the status has been successfully loaded. All users can promote a stack, to a public or private catalog (depending on their role and entitlements).

Create Stack

To create a stack, the user can click on the "Create stack" button, and a new popup will appear. Only users which are members of at least one project can create a stack.

image2014-2-19_14_44_12.png

The user has to specify the stack name, and the stack will be available in the application under this name. It should be unique within the project it's going to be created, and can contain only alphanumeric characters or ".-_" and has to start with letter.
The user can create an empty stack without a blueprint, or choose an existing blueprint from the list. Empty stack contain only default parameters and have no layers. A stack created from a blueprint is a basically a copy of that blueprint. The the user is able to configure and modify such a stack later to suit his needs.

Delete Stack

Stacks can be deleted only if their status is "Stopped". The user must be able to retrieve the status of the stack to be allowed to perform this action. 

Stack

The stack page is available to all users – both platform administrators and account members. 

Stack Details

In the top part of the page there is basic information about the stack.

image2014-2-19_15_7_11.png

Platform administrators can also see the link to the account the stack belongs to. The "Project" field is a link to the project which the stack was created in. 

The origin of the stack can be one of:
"This is a custom stack created in XMS." – in case of a freehand stack created in the XLcloud Management System
"This stack was created from the blueprint" – for a stack created from a blueprint and not modified
"This stack was created from the blueprint, but has been changed afterwards." – if the was stack created from a blueprint, but customized later by user

The "Description" is simply a description of the stack, and can be edited when clicked.

"Instance Type" is the default flavor of the instances in the stack. All instances in the stack will inherit this value if unless configured otherwise by the user.  Possible instance types are:

Flavor

Memory (MB)

Disk (GB)

Ephemeral Disk (GB)

VCPUs

m1.tiny512001
m1.small204810201
m1.medium409610402
m1.large819210804
m1.xlarge16384101608

Note that some blueprints can limit the choice of the instance types to only a subset of the above.

The user can select the cloud image from all the images registered in public and private catalogs. It will be used as the default image for all instances in the stack, unless configured otherwise on a per-layer and per-instance basis.

The "Key Name" is the name of the default keypair which will be used on all instances, unless configured otherwise manually. Note that keypairs are generated per user, so if you want to start a stack created and configured by someone else, you will need set up your own keypair in order to do this. It is impossible to create a stack session using someone else's keypair. 

On this page, the user is also able to generate or import a keypair, and it will be automatically set as the one to be used.

Current value of the instance type, cloud image, and key name are highlighted in green, and the gray ones are other possible values that can be chosen. You can change the value simply by clicking on the gray tile, but note that a stack can be updated only if it is stopped.

Stack Lifecycle

There are several possible stack statuses, and different actions can be performed in each of those states.

Status

Description

Possible Actions

Stack Update

StoppedStack is stopped and we can modify the stack and its layersStartallowed
StartingStack is currently starting and resources are being created – we cannot configure the stackdisabled
ConfiguringStack is being processed by XMS and the "Configure" event takes place – we cannot configure the stackdisabled
RunningStack is currently running and the "Configure" event has been processed – only scalability parameters can be modifiedSuspend, Stopdisabled (except for scalability parameters)
SuspendingThe "Suspend" event is being processed by XMS, and after that the stack will be suspendeddisabled
PausingThe "Suspend" event has been processed, and stack resources are currently being suspendeddisabled
PausedStack resources have been paused successfullyResumedisabled
ResumingStack resources are currently being resumed, and afterwards the "Resume" event will be sentdisabled
UpdatingStack scallability parameters have been updated and the stack is currently updatingdisabled
Shutting downThe "Shutdown" event is currently being processed by XMSdisabled
StoppingStack resources are currently being stoppeddisabled
Failed to startCould not start stack resourcesTerminatedisabled
Failed to stopCould not stop stack resourcesTerminatedisabled
Failed to resumeCould not resume stack resourcesTerminatedisabled
Failed to pauseCould not pause stack resourcesTerminatedisabled
Failed to updateCould not update stack resourcesTerminatedisabled

The diagram below illustrates possible status transitions due to user actions and success or failure of individual operations.

Stack_Lifecycle.png

Events

An event is a message triggered by the XLcloud Management System. Those messages are sent to instances, that in turn execute the chef solo with an appropriate runlist. Event is considered successful only when all the instances respond successfully. 

image2014-2-25_12_44_47.png

Clicking on an event opens up a new popup with more information about the event.

image2014-2-25_12_49_23.png

Those details contain the name of the event, its status, and the date when event was triggered. If there were any additional parameters sent in the event to the instances, they are displayed below the basic description. In the bottom part, there is a detailed description of the instance outputs.

Stack Layers

The stack layers section contains the list of layers within the stack. 

image2014-2-20_13_19_46.png

The user can promote a layer, or delete it if the stack is stopped.

Add New Layer

To add a new layer, the stack must be stopped. The user can click on the "New Layer" button and a new popup will appear.  

image2014-2-20_13_18_29.png

The user is prompted to type in the name (the name is required). The layer name should be unique within the stack, and can contain only alphanumeric characters or ".-_" and has to start with letter. 

The user is able to choose whether he wants to create an empty stack without a blueprint, or use an existing layer blueprint to base the layer on. An empty layer contains no resources except for several default parameters and a default security group that allows to SSH to instances. 

The user adding a new layer has to specify the subnet which the layer instances will be attached to. Initially, the default subnet is selected.

Delete Layer

The user can delete a layer only when the stack is stopped. Note that this operation cannot be undone.

Parameters

Stack parameter list contains all parameters, except some reserved XLcloud parameters. Note that all stack parameter must have their values set before the stack is started, if no default value is available. Those values are marked in red, and can be updated when clicked.

image2014-2-20_14_1_31.png

Parameters with the "No Echo" option set to true, are masked with 5 asterisks star. Note that the length of the mask is fixed and does not depend on the actual length of the value.

The user is allowed to delete a parameter, but note that some parameters are used to pass values further down to layers. Deleting them may require a reconfiguration of stack resources and layers.

Set Parameter Value

 

To set parameter value click on the value or the parameter name. A new popup will appear, and you will be able to edit the value of the parameter. Users are not able to see the value of "No Echo" parameters. 

Add New Parameter

Adding a new parameter is only possible when the user switches to the Advanced Mode (one of the option in user menu). The "New Parameter" button is then visible. When the user clicks the button, a new popup will appear.

image2014-2-20_14_51_15.png

The name of the parameter is the display name, and parameter values will be passed to XLcloud Management System using this name.  

The "Description" is a description of the parameter, visible in parameter details.

The "Type" is the parameter type. A parameter of type "String" is simply some text. A parameter of type
"Number" is an integer.

"NoEcho" indicates if the value of the parameter should be masked with asterisks star.

"Default Value" is a value that will be used for this parameter, if no other value is specified. If the parameter has any constraints defined, this value must satisfy those constraints. Note that the use of this field is discouraged. In general, it is present for legacy reasons, and to enhance the support of freehand stacks.

The constraint description is a text explaining the constraint requirements, and it's displayed when the constraints are violated.

Text constraints are visible only when the user chooses the "String" parameter type.

"Max Length" is an integer value that determines the largest number of characters in the parameter value.

"Min Length" is an integer value that determines the smallest number of characters in the parameter value.

"Allowed Pattern" is a regular expression that must be matched by the parameter value.

"Allowed Values" is an array containing the list of values allowed for the parameter.

Numeric constraints are visible only when the user chooses the "Number" parameter type.

"Max Value" is an integer value that determines the largest value allowed for the parameter.

"Min Value" is an integer value that determines the smallest value allowed for the parameter.

Parameter Details

To view parameter details click on the parameter name, and a popup will appear. It contains the same information that is supplied when a new parameter is created, but without the possibility to edit it.

Edit Parameters

It is also possible to edit parameter definitions using the "Edit" button from the "Actions" menu. When that button is clicked, the same popup as when creating a new parameter will appear, but already filled in according to the definition of the parameter.

Outputs

Output section is only visible in the Advanced Mode or when the stack is running, and contains the list of stack outputs. What is displayed in the "Value" column, depends on the status of the stack. If the stack is running, the actual value is resolved and displayed (e.g. in case of the output shown in the picture below, the physical ID of the layer "first_layer" would be shown). In any other state, the definition of the output will be presented, additionally formatted to make it more readable.

image2014-2-20_15_46_25.png

Add New Output

To add a new output click on the "New Output" button and a popup will appear:

image2014-2-20_15_55_34.png

AWS intrinsic functions can be used in the value of the output.

Editing the Template

It is possible to view or edit the source of the stack template, presented as a JSON. Editing of the template is only possible when stack is not started. To enter the source view use the "Stack" menu, located just below the user menu, and click to expand it.

image2014-2-20_16_2_46.png

A new popup with the template source will appear:

image2014-2-20_16_3_45.png

Layer

The layer page is available for both platform administrators and account members. Updating a layer is possible only when the stack is stopped, and the user must be allowed to retrieve the status of the layer stack. Otherwise, a read-only view of this page is shown.

Layer Description

Basic information about the layer is placed in the top part of the page. The "Description" is a short description of the layer. The default instance type, cloud image and key name are displayed just like on the stack page. However, there is an additional option available for each of them –  to inherit the value from the stack. User also is obliged to select the subnet that all instances in the layer will be attached to. Out of the box, the default subnet of the project is chosen as the layer subnet.

image2014-2-20_17_24_34.png

Parameters

The "Parameters" section is hidden in the Basic Mode and users wanting to create freehand layers should remember about this. Editing parameters is done identically as in the case of Stack Parameters. It is possible for a parameter to inherit its value from another parameter, including stack parameters. To achieve this, set the value of the parameter to a reference. For example:

{"Ref": "param"}

will inherit the value of the parameter with name "param". 

Instances

Each resource of type AWS::EC2::Instance and AWS::AutoScaling::LaunchConfiguration is visible in this view as an instance of the layer.

image2014-2-21_11_57_50.png

Add New Instance

The user can add a new instance to instance list if stack is stopped. Adding new instance means creating an appropriate resource, depending on the type of the instance – either scalable or non-scalable. Every instance should have its own AWS::CloudFormation::WaitCondition and AWS::CloudFormation::WaitConditionHandle so those resources are added by default when a new instance is created. Newly-created instances use the default parameter values for key name, cloud image and instance type, but the user can customize those attributes afterwards. Moreover, created instances inherit the lifecycle configuration of the layer, and appropriate files are created. Those operations are hidden from the user, and the only thing he has to do it to choose a name for the instance, and decide whether it should be scalable or not.

Instance Details

To view the instance details, the user has to click the name of the instance.

image2014-2-21_13_38_47.png

As in the case of editing stack and layer parameters, the user can specify the instance type, image and key name. By default, those attributes are inherited from the layer.

Elastic IP

Elastic IP is a resource which allows the users to connect to his instance from any place in the world, provided that the security group permits that. 

image2014-2-21_13_41_58.png

Only one elastic IP can be created for an instance, so if there are no elastic IPs, the button to add one is visible.

User Data

The "User Data" is a script which will be run after an instance is started in the cloud.

image2014-2-21_13_44_25.png

Intrinsic functions are formatted as blocks to improve readability.

The user can modify the script, but it's not recommended to do so. If you are sure editing the user data cannot be avoided, please only extend the existing script, and do not remove any of the commands. 

Initialization

To customize your instance please use the initialization section which allows to create files, install packages, define services, and run commands.

Files

The "Files" section allows to automatically create new files after the instance is up.

image2014-2-21_14_2_27.png

This set of files should not be modified, because it is a part of the XLcloud platform, and enables the lifecycle configuration management. 

To create a new file, click on the "Create file configuration" button, and a new popup will appear.

image2014-2-21_14_14_20.png

The "File Path" indicates the full path where the file will be placed. All paths should starts with a slash "/". Note that the path must be unique within all files in the instance configuration. 

The user can specify the content of the file in one of the two ways. The first one is to choose "Provided content", and type in the content of the file inside the "File Content" text area. The second one is to choose the "Remote content" option, and provide the source of the file.

Properties of the file include the owner, owner group, and the file mode with file permissions in Linux number notation.

The user can also modify an existing file configuration, clicking one the name of the file configuration to be updated. The same popup will appear, and the user can change the file properties.

Packages

A package is an application installed by one of the package managers: rpm, yum, apt, rubygems, or python. 

image2014-2-21_15_11_21.png

The user can update an existing package or create a new one. To create a new package, the user has to click on the "Create package configuration" button, and a new popup will appear:

image2014-2-21_15_13_46.png

The user has to specify the package name, and the package manager which should be used to install this package. The user can type which versions of the package should be installed.

Services

Using the "Services" section, you can define what services should be enabled or disabled when the instance is launched.

image2014-2-23_23_20_29.png

Adding a new service requires the user to type in the service name, and to choose to ensure whether the service will be started automatically or not upon booting. If not, the service will be started after cfn-init finishes.

Commands

The "Commands" section ensures that the execution of the specified commands will take place on the instance. The commands are processed in alphabetical order.

image2014-2-23_23_44_13.png

To add a new command, the user has to click on the "Create command configuration" button, and a new popup will appear.

image2014-2-23_23_27_17.png

The user needs to specify the command name. Note that commands will be run on the instance in the alphabetical order. The executable command should also be specified. User can also add environment variables for the command. Clicking on the "Add" button makes a new input show up, where the user can type in the environment variable. The current working directory is an optional parameter, and sets the directory where the command will be run. The "Test Command" is a command that must return "true" in order for cfn-init to process the command in the command key. If the "Skip Errors" option is checked, executing the commands along with the initialization will be continued even if errors occur. The "Waits After Command" field specifies how long to wait (in seconds) after a command has finished, in case the command causes a reboot. 

Scalability Parameters

To support scaling a scalable instance in the stack lifecycle, the template author has to configure scaling policy using parameters with the name convention of xlcloud:{scaling_resource_name}:{parameter_name}. Those parameters are not shown in the "Scalability Parameters" section, and not in the parameter list.

image2014-2-24_0_16_27.png

Scale Stack

Value of the scalability parameters can be changed even when the stack is running. Updating the value of such a parameter means updating the stack and scaling the instance manually.

Application Deployments

The "Application Deployments" section shows all application deployed on the layer. Per-deployment information contains the date of the deployment and its status.

image2014-2-25_13_5_11.png

Deploy Application

Its possible to deploy an application only when the stack is running. To deploy an application, click on the "New Application Deployment" button, and a new popup will appear. Then, type in the name of the application, and provide deployment attributes in case they should overwrite currently configured values. Note that those parameters are based on the lifecycle configuration and differ between layers.

image2014-2-25_13_9_51.png

This screenshot shows the hpc-vc::deploy attributes.

Undeploy Application

Only successfully deployed applications can be undeployed, provided that the stack is running.

Lifecycle Management

"Lifecycle Management" is a section available only in the Advanced Mode, and enables the user to modify runlists of all lifecycle phases. 

image2014-2-24_9_41_58.png

This section is divided into seven lifecycle phases:

Phase

Description

SetupRun only once, when the instance starts up
ConfigureRun always when configuration of the stack is changed (after start-up, update, scale, or resume)
DeployRun on user demand when an application is deployed and also when new instances are added to the stack
UndeployRun on user demand after the undeploy action is invoked
SuspendRun before the stack is suspended
ResumeRun after the stack is resumed, but before it's configured
ShutdownRun just before the stack is shut down

Add Recipe

To add a recipe to a phase, click the "Add recipe" button, and a new popup will appear.

image2014-2-24_9_51_57.png

Firstly, the user should choose one of the existing cookbooks, and when it's done the list of available recipes and parameters are loaded. The user needs to choose a recipe that he wants to be added to the runlist. Note that it is impossible to add a new recipe to the same phase from the same cookbook, but with different parameters. Attributes from the same cookbook share values within a phase. Attributes from the "deploy" phase can be configured in the lifecycle, but can also be modified and overwritten later when an application is deployed by the user.

Configure Recipe Attributes

Clicking on the recipe tile, makes the same popup appear. The user can then configure the recipe attributes for the phase.

Remove Recipe

Removing a recipe is done by clicking the "X" button. However, the recipe attributes will not be removed.

Security Groups

A security group acts like a firewall that controls the traffic of one or more instances. When you launch an instance, you associate one or more security groups with the instance. You can add rules to each security group that allow traffic to or from its associated instances. This section is available only in the Advanced View. 

image2014-2-24_10_26_15.png

A layer created in XLcloud contains a default security group that allows to SSH to the instances, opening the port 22 to the whole world. All instances added to the layer share the same set of security groups, all defined in the list.

Show Details

The details of a security group can be viewed after the user clicks the name of the security group. Basic information contains the name and the description, but also the physical ID of the VPC, if configured.

image2014-2-24_10_38_53.png

Below the basic information there are sets of security group egress rules which configure the egress from the instances. If there are no rules, the firewall enables access to all the internet.

Security group ingress configures the firewall and opens selected ports of the defined addresses for the specified IP protocol. If there are no rules, no ingress will be allowed to the instance.

Configure Rules

Adding a new rule is can be done by clicking the "Add rule" button, and a new popup appears:

image2014-2-24_10_50_0.png

The user can type in an arbitrary CIDR or choose one of the configured subnets. The user needs to define one of the existing IP protocols, e.g. TCP, UDP, ICMP. "From Port" is the first port in the port range, and "To Port" is the last one.

Add Security Group

To add a security group, please click the "New Security Group" button, and type in its name and description. The ID of the VPC can be set as well.

Outputs

Outputs of a layer are similar to the Stack ouptuts, but those values are not resolved even when the stack is running, and only the definition of the output is presented. However, it is possible to use the value of the output in other resources using the intrinsic functions. To see the value of a layer output, create a stack output that show the values of that outputs.

Resources

The list of layer resources contains all the remaining resources that are not presented elsewhere.

image2014-2-24_11_29_22.png

There is no graphical user interface allowing to configure such resources (they can only be deleted). One possibility to do this is by editing the template directly in the source view.

Editing the Template

Just like in the case of the Stack Template, the user is allowed to view and edit the source of the layer template. This feature can be accessed from the "Layer" menu located in the same place as on the stack page.

Stack Blueprints

The "Stack Blueprints" section, like other cloud catalog sections, are available for both platform administrators and account members. Also in this case, the catalog is divided into the private catalog of the account (where account members can promote their stacks to) and the public catalog (where platform administrators can promote stacks to). 

image2014-2-24_12_4_35.png

Platform administrators can view the private catalog of an account on the details page of that account. 

Show Details

To view the details of a blueprint simply click its name. 

image2014-2-24_12_10_22.png

This view resembles the stack details section, but is extended by the blueprint type, author, license, and the catalog. The default key name cannot be included in a blueprint, and so it must be specified in the stack, after it's created from the blueprint.

The rest of the blueprint view is analogous to the stack page, except that there it's not possible to edit the stack blueprint configuration.

Promote Stack to a Blueprint

Any stack can be promoted to a blueprint. This action can be performed on the stack list and on the stack page (using the "Stack" menu). When the user clicks "Promote", a new popup appears. The user can then specify the details of the stack blueprints, and save the configuration of the stack parameters.

image2014-2-24_12_33_52.png

The user needs to type in the name of the stack blueprint, which can contain only alphanumeric characters and ".-_" and has to start with a letter. The "Type" is like a category of the stack blueprint, and simplifies browsing the stack blueprints catalog. The fields "Author", "License" and "Copyright" define the legal aspects of the stack blueprint usage.

The user can choose which parameter values should be saved in the blueprint, so that they do not have to be configured manually when a stack is created from the blueprint.

Create Stack from a Blueprint

To create a stack from a blueprint, the user can use the blueprint menu, and a new popup will appear. The user can then type in the name of the stack (a name is suggested automatically based on the blueprint name), and choose one of the projects which he is a member of.

Layer Blueprints

Layer blueprints are sets of layer configurations that can be used in any stack. "Layer Blueprints" is a section available for platform administrators and account members, just like "Stack Blueprints".

image2014-2-24_13_0_51.png

Show Details

To show the details of a layer blueprint click on the name of the blueprint. Details of a layer blueprint are similar to the details of a layer, but present additional fields – "License", "Author", "Copyright" and "Type", analogous to the stack blueprint details. The Basic View contains only the essential information about the blueprint. To view all the details switch to the Advanced Mode.

Promote Layer to a Blueprint

Promoting a layer to a blueprint is possible on the layer list on the stack page and from the "Layer" menu on the layer page. To promote a layer please fill in the form similarly to as described in Promote a stack to a blueprint.

Another possibility to create a layer blueprint is to export a layer of a stack blueprint. The user only needs to type in the name of the layer blueprint, and the whole configuration of the layer will be exported.

Add Layer form a Blueprint

When adding a new layer to a stack, the user can create an empty layer (to be customized later), or choose one of the blueprints. If the user creates a layer form a blueprint, the whole configuration is copied from that blueprint to the created layer.


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

Site maintained by