1. technology and computing

EPAM Cloud Orchestrator
Maestro CLI Quick Start
User Guide
November 2014
CIUG-2
Version 2.1
Content
Preface
............................................................................................................... 3
About this Guide ........................................................................................................... 3
Audience
............................................................................................................... 3
The structure of the Guide ............................................................................................ 3
Documentation References .......................................................................................... 4
1.
Prerequisites
............................................................................................................... 5
2.
Procedure
............................................................................................................... 6
2.1.
Setting Access Credentials .................................................................... 6
2.2.
Determining Available Shapes .............................................................. 7
2.3.
Determining Available Machine Images ................................................ 8
2.4.
Running Instances ................................................................................. 9
2.5.
Viewing Instance Properties ................................................................ 10
2.6.
Logging in to Instances ........................................................................ 11
2.7.
Terminating an Instance ...................................................................... 12
Table of Figures .................................................................................................................... 13
Version history ...................................................................................................................... 13
EPAM CONFIDENTIAL
2
Preface
About this Guide
Maestro Command Line Interface (CLI) is a REST client for EPAM Cloud Orchestrator. It
is intended to perform Orchestrator commands via remote command line by sending server
API requests using REST API without the need to install any 3rd party utilities (e.g. cURL,
Poster).
The quick start guide is intended to show you a common use case of cloud environment
setup by means of detailed step-by-step configuration description
Audience
This guide is designed for EPAM Private Cloud users who manage their own infrastructure
via Maestro CLI.
The structure of the Guide
The guide consists of two sections:
1. Prerequisites. This section gives the list of the prerequisites that are to be met for
Maestro CLI to perform successfully.
2. Procedure. This section gives detailed instructions and useful tips on different
stages and actions that can be performed via Maestro CLI. The section covers
basic operations on instances creation and manipulation as well as the ways to log
in to them.
3
EPAM CONFIDENTIAL
EPAM Cloud Orchestrator - Maestro CLI - Quick Start Guide
Documentation References
You might also want to check the following EPAM Cloud Orchestrator documents:
Document Title
Contains Information on
Maestro CLI Developer Guide
Maestro CLI Setup Guide
Maestro CLI client use and customization
Installation of Maestro CLI Client
Maestro CLI Quick Start Guide
Setting up a common cloud environment
Auto Configuration: Box
Solutions
Auto Configuration Service concept and usage
Maestro CLI Reference Guide
EPAM Cloud Orchestrator Command Line Interface and the
list of CLI commands, their parameters and response
examples
Maestro API Reference Guide
EPAM Cloud Orchestrator Application Programming Interface
Project Management Guide
Hints and guidelines on customization of EPAM Orchestrator
for the specific project needs
Resource Utilization Quotas
Guide
Checkpoint Utilization Guide
Email Notification
Subscriptions Guide
EPAM Private Cloud Billing
Guide
Resource Utilization Quotas and respective guidelines
Concepts of checkpoints, including their utilization within
Orchestrator, limitations and best practices
Notifications description, usage and customization guidelines
and default values
Current billing model implemented for EPAM Private Cloud
Graphical User Interface Guide
Setup and utilization of Amazon Web Services-based
infrastructure through EPAM Cloud Orchestrator
EPAM Cloud Orchestration graphical user interface
Maestro Stacks Guide
Maestro Stacks creation and utilization
Maestro CLI Quick Reference
Card
A set of all CLI commands
AWS Utilization Guide
Please email your comments and feedback to EPAM Cloud Consulting at
SpecialEPM-CITConsulting@epam.com to help us provide you with documentation that is
as clear, correct and readable as possible.
4
EPAM SYSTEMS
1. Prerequisites
NB: Meeting the following prerequisites is a must. Otherwise, Maestro CLI will not
function properly.
Before you proceed with this guide, make sure to do the following:

-
Install Java 1.6 or Java 1.7
Perform Express installation of the CLI client.
See ‘EPAM Cloud Orchestrator - Maestro CLI - Setup’ guide for detailed guidelines.
-
Make sure you have valid PMC credentials (user ID, password).
-
Check whether your PMC project is activated in EPAM Cloud and which
virtualization regions are available for it. You can do it in one step by invoking the
or2-describe-regions(or2dreg) command.
If your project is active, you will get a list of available regions. An example output is
given in the screenshot below:
Figure 1 – or2-describe-regions response for an active project
The list of the regions may depend on your current project role.
If the specified project is not activated, you will get the following CLI output:
Figure 2 – or2-describe-regions response for an inactive project
-
5
If the project is not activated, please contact the Help Desk to activate it. The project
activation should be approved by the project manager or coordinator.
Obtain an SSH client application (PuTTY or similar).
EPAM CONFIDENTIAL
EPAM Cloud Orchestrator - Maestro CLI - Quick Start Guide
2. Procedure
By following the steps from this section, you will be able to quickly launch, configure and
then terminate a virtual Machine (Instance) in EPAM Private Cloud by means of Maestro
CLI commands.
NB: Each Maestro CLI command has two invoke options: its default name and
shortened one. Choosing an option to use is up to you. Shortened names are hereinafter
provided in brackets after each full command name.
2.1.
Setting Access Credentials
NB: This document contains command examples using Windows 7 syntax. In case you
use a *nix OS, make sure to either add the ‘./’ prefix to each command or configure an
environment variable pointing at Maestro-CLI directory.
In case you did not do it earlier, run the or2-get-access (or2access) command and
enter your credentials when prompted. You can choose, whether to use your EPAM PMC
(without ‘@epam.com’) or Domain (with ‘@epam.com’) credentials.
If successful, the ‘default.cr’ file will be created, and you will no longer need to provide your
user credentials.
You can run this command and provide the ‘-s’ parameter to use your system credentials. If
this parameter is skipped, the command requests PMC or EPAM domain credentials.
Command example:
or2-get-access
Response example:
The command returns user name and encoded password.
Figure 3 - or2-get-access Response Example
EPAM CONFIDENTIAL
6
2.2.
Determining Available Shapes
Run or2-describe-shapes (or2dshape) command to find out available instance
shapes for your PMC project. Provide your PMC project ID (-p) and service region (-r) as
its parameters.
Command example:
or2-describe-shapes -p epm-cit -r EPAM-MSQ
Response example:
The command returns a list of available shapes with their names (left column), number of
CPU’s (middle column) and available RAM (right column) per shape.
Figure 4 - or2dshape Response Example
See ‘EPAM Cloud Orchestrator - Maestro CLI - User/Reference Guide’ for detailed Maestro
CLI command reference.
7
EPAM CONFIDENTIAL
EPAM Cloud Orchestrator - Maestro CLI - Quick Start Guide
2.3.
Determining Available Machine Images
Run or2-describe-images (or2dim) command to find out available machine images
for your project and virtualization region. Provide your PMC project ID (-p) and virtualization
region (-r) as its parameters.
Command example:
or2-describe-images -p epm-pmc -r epam-msq
Response example:
The command returns a list of available machine images IDs with their description and
additional info (group and state)
Figure 5 - or2dshape Response Example
8
EPAM SYSTEMS
2.4.
Running Instances
Choose a shape and a machine image among the available ones (See steps 2.2 Determining Available Shapes and 2.3 - Determining Available Machine Images.)
Run or2-run-instances (or2run) command to launch your instance. Provide your
PMC project ID (-p), virtualization region (-r), required shape (-s), required machine
image (-i), and required number of instances (-c) (optional) as its parameters.
You can also provide the expiration date parameter (-e) as ‘yyyy-MM-ddTHH:mm’ (ISO
8601) EPAM Cloud Orchestrator will stop the instance at the specified time.
If you use keypairs, submit the name of existing keypair to associate with this instance via
the (-k) parameter
NB: The ‘--count’ parameter must be an integer value greater than 0. If the ‘-c’
parameter is omitted, the application regards this as ‘count=1’ and launches a single
instance.
Command example:
or2-run-instances -p epm-cit -r epam-msq -s small -i CentOS6template -c 1
Response example:
The command returns an ID assigned to your instance and its current state.
Figure 6 - or2run Response Example
NB: Having executed the or2-run-instances command, wait for email confirmation that
your instance has launched (or failed to do so) , before running the next command.
Please keep in mind that:
a)
b)
It takes at least 25 minutes to launch a Windows VM
If you send a request to create multiple instances, they will be
processed one-by-one.
9
EPAM CONFIDENTIAL
EPAM Cloud Orchestrator - Maestro CLI - Quick Start Guide
2.5.
Viewing Instance Properties
Run or2-describe-instances (or2din) command to confirm your instance has
been successfully launched and find out its IP address. Provide your PMC project ID (-p),
virtualization region (-r), and instance id (-i) as its parameters.
NB: To see a list of all instances running in your virtualization region for your project, do
not include the ‘-i’ parameter.
Command example:
or2-describe-instances -p epm-cit -r epam-msq -i %INSTANCE_ID%
Response example:
The command returns the following information concerning your instance (left to right): ID,
DNS name, private IP, current state, number of CPUs, amount of RAM, operating system.
Figure 7 - or2din Response Example
10
EPAM SYSTEMS
2.6.
Logging in to Instances
Run your SSH client and connect to your instance, specifying its private IP (See step 2.5 Viewing Instance Properties.)
NB: In order to access Windows instances via SSH you first have to access them via
RDP and configure SSH connection.
Figure 8 - Connecting to an Instance via SSH
Once you login to your instance login using your EPAM domain credentials (for Windowsbased instances) or default credentials: login:user/password:user (for *nix-based instances).
In the latter case you will have to change the default credentials before you continue
working with your instance.
11
EPAM CONFIDENTIAL
EPAM Cloud Orchestrator - Maestro CLI - Quick Start Guide
2.7.
Terminating an Instance
Once you no longer need your instance, run or2-terminate-instances (or2kill)
command to terminate it. Provide your PMC project ID (-p), virtualization region (-r), and
instance id (-i) as its parameters.
Having executed this command you should type ‘yes’ as confirmation, when prompted. You
can skip this step and proceed with termination by providing the (-y) parameter initially.
Please, exercise caution when using it to avoid unintentional instance termination.
NB: If you would like to save attached storages, make sure you also include the ‘-l’
parameter (without quotes). The default command behavior is deleting attached storage
volumes as well.
Command example:
or2-terminate-instances -p epm-cit -r epam-msq -i %INSTANCE_ID%
Response example:
The command returns your instance ID (left column) and its current state (right column)
Figure 9 - or2kill Response Example
12
EPAM SYSTEMS
Table of Figures
Figure 1 - or2-get-access Response Example ....................................................................... 6
Figure 2 - or2dshape Response Example .............................................................................. 7
Figure 3 - or2dshape Response Example .............................................................................. 8
Figure 4 - or2run Response Example ..................................................................................... 9
Figure 5 - or2din Response Example ................................................................................... 10
Figure 6 - Connecting to an Instance via SSH ...................................................................... 11
Figure 7 - or2kill Response Example ................................................................................... 12
Version history
Version
Summary
1.0
October 29, 2012
Initial version is published
1.1
November 15, 2012
Command syntax is brought up to date
1.2
December 21, 2012
Screenshots are updated
1.3
January 8, 2013
2.0
13
Date
-
Warnings and screenshots are updated
Typos are fixed
-
or2access, or2dshape, or2dim, and or2kill
commands description is updated
-
Minor omissions are fixed
April 11, 2013
2.01
August 16, 2013
-
Related documents are added
2.02
August 30, 2013
-
Links throughout the document are updated
2.03
November 28, 2013
-
Preface is added
-
Documentation links updated
2.04
September 20, 2014
-
Java versions added
2.1
November 1, 2014
-
Documentation references updated
EPAM CONFIDENTIAL
Global
41
University
Drive
Suite
202, Newtown (PA), 18940,
USA
Phone:
+1-267-759-9000
Fax:
+1-267-759-8989
EU
Corvin Offices I. Futó st 4753
Budapest, H-1082, Hungary
Phone:
Fax:
+36-1-327-7400
+36-1-577-2384
CIS
9th
Radialnaya
Building 2
Street,
Moscow, 115404, Russia
Phone:
+7-495-730-6360
Fax:
+7-495-730-6361
© 1993-2012 EPAM Systems. All Rights Reserved.