-
Notifications
You must be signed in to change notification settings - Fork 7
Getting Started
The Morpheus CLI is a command line interface for the Morpheus appliance. It is a powerful tool for automating the management of your Morpheus appliance, and it also provides a way to explore the data model and available operations of the Morpheus API.
A Prerequisite to running the Morpheus CLI is to have ruby 2.5 or newer installed. Use rubygems to install the cli.
gem install morpheus-cli
Once the gem is installed, all the cli commands can be run on the shell via the morpheus executable.
The first thing that needs to be done after installation is to point the cli to the appliance. To point to a new appliance, run morpheus remote add [name] [url].
morpheus remote add demo https://mymorpheus
This creates the new remote configuration and will prompt you to login. Prompting can be skipped by using -N or --quiet.
By default, the cli will error if the appliance is using an untrusted SSL certificate. If you need to have the client Ignore SSL Errors, use remote add --insecure or update the existing remote with morpheus remote update demo --insecure.
You can add multiple remote appliances to your cli configuration, for instance you might have one for each morpheus appliance in your organization eg. test, staging and production. Each remote name must be unique, but you can have several remotes that all point to the same appliance. Each remote has its own separate saved credentials, so you can login and logout of sessions for each remote independently.
To switch between remotes, run morpheus remote use [name]. The very first remote added to the config will be used and made active automatically by default.
To switch to having no active remote, run morpheus remote unuse.
To see your configured remotes, run morpheus remote list.
When morpheus executes a command that requires establishing a connection to the appliance (most commands), the current active remote will be used by default. Alternatively, you may specify which remote to use for each command by including the -r [remote] option, for example morpheus whoami -r staging.
It is also possible to run commands without adding a remote by using the --remote-url option, for example morpheus ping --remote-url https://staging.mymorpheus --insecure.
Also, for commands that require authentication, morpheus will used the saved access token that is stored when you run morpheus login. An alternative to morpheus login is to use --username and --password OR --token to authorize for each command you run, for example morpheus instances list --remote-url https://sandbox.morpheusdata.com --username jdoe --password 'Hell0Morpheus!'
The shell command is a great place to start when using the Morpheus CLI. It provides a way to view and search your command history as well as TAB to autocomplete command names which is useful for learning the CLI. Most importantly, it saves you time because you do not need to prefix every command with morpheus and the ruby runtime does not need to be reloaded for each command you run.
To start a new morpheus shell, run
morpheus shell
Now, let's confirm that we are hooked into the appliance properly, run remote current
morpheus> remote current
Morpheus Appliance
==================
Name: sandbox
URL: https://sandbox.morpheusdata.com
Version: 5.0.0.beta
Appliance URL: https://sandbox.morpheusdata.com
Secure: No
Active: Yes (current)
Username: david
Last Login: 14 days ago
Last Check: just now
Response Time: 29ms
Status: READY
We can also inspect our user current information using whoami:
morpheus> whoami
Current User
==================
ID: 1
Tenant: Morpheus Data (Master Tenant)
First Name: David
Last Name: E
Username: david
Email: david@morpheusdata.com
Role: System Admin
Fantastic! We are now ready to start our adventure in the Morpheus CLI. If this command fails please be sure to verify the appliance url entered previously is correct, and also verify the provided credentials are correctly entered.
The CLI is under active development and new features are added as the Morpheus appliance expands its capabilities. You can see which commands are available by invoking the cli without any arguments:
morpheusThis returns an error about the missing [command] argument and prints the available commands and options.
morpheus: [command] argument is required.
Usage: morpheus [command] [options]
Commands:
access-token
activity
alias
appliance-settings
approvals
apps
archives
backup-settings
benchmark
blueprints
budgets
clouds
clusters
containers
cypher
datastores
deploy
deployments
edit-profile
edit-rc
environments
execute-schedules
execution-request
file-copy-request
groups
guidance
health
hosts
image-builder
instance-types
instances
integrations
invoices
jobs
key-pairs
library-cluster-layouts
library-file-templates
library-instance-types
library-layouts
library-node-types
library-option-lists
library-option-types
library-scripts
library-spec-templates
library-upgrades
license
load-balancers
log-settings
login
logout
logs
monitor-alerts
monitor-apps
monitor-checks
monitor-contacts
monitor-groups
monitor-incidents
network-domains
network-groups
network-pool-servers
network-pools
network-proxies
network-routers
network-services
networks
passwd
ping
policies
power-schedules
price-sets
prices
process
provisioning-licenses
provisioning-settings
recent-activity
remote
reports
resource-folders
resource-pools
roles
security-groups
service-plans
setup
shell
storage-buckets
subnets
tasks
tenants
user-groups
user-settings
user-sources
users
version
virtual-images
whitelabel-settings
whoami
wiki
workflows
Options:
-e, --exec EXPRESSION Execute the command(s) expression. This is an alternative to passing [command] [options]
--noprofile Do not read and execute the personal initialization script .morpheus_profile
-C, --nocolor Disable ANSI coloring
-B, --benchmark Print benchmark time after the command is finished.
-V, --debug Print extra output for debugging.
-v, --version Print the version.
-h, --help Print this help
For more information, see https://github.com/gomorpheus/morpheus-cli/wiki
The cli is organized as commands and many of the commands are further split into subcommands. For example lets look at morpheus users
morpheus: [command] argument is required
Usage: morpheus users [command] [options]
Commands:
add
count
get
list
passwd
permissions
remove
update
OK, now let's see how to provision a server. First we'll look at the groups we have available.
morpheus> groups list
Morpheus Groups
==================
ID | NAME | LOCATION | CLOUDS | HOSTS
-------|------------|----------------------------------|--------|------
23 | Ansible | Defaults to Ansible Dev | 4 | 37
19 | Chef | Defaults to Chef Demo bootstrap | 2 | 25
=> 2 | Demo | 24 hour expiration policy | 23 | 60
548 | Developer | | 1 | 0
371 | DevTest | 2 day Shutdown, 7 day expiration | 12 | 42
50 | Production | Approval Required | 7 | 46
366 | Puppet | Demo Puppet Master | 0 | 0
424 | SaltStack | Defaults to Salt Master prod | 1 | 12
443 | ServiceNow | ServiceNow Approval, CMDB | 3 | 34
447 | Tower | | 1 | 12
Viewing 1-10 of 10
In the above example the currently active group is Demo as can be seen by the => symbol to the left of the group name. To switch groups run:
morpheus groups use "Developer"
This now becomes the active group we would like to provision into. Another thing to know before provisioning is we do have to also specify the cloud we want to provision into . This does require the cloud be in the group that is currently active. To see a list of clouds in the group run:
morpheus clouds list -g "Developer"
Morpheus Clouds | phrase: Developer
==================
ID | NAME | TYPE | LOCATION | GROUPS | SERVERS | STATUS
---|----------------------------------|---------------------|---------------------|-----------------------------|---------|---------
1 | Dev Vmware | VMware vCenter | my place | Developer | 2 | OK
Viewing 1-1 of 1
This will scope the clouds command to list only those clouds that in the specified group.
Morpheus makes it very easy to get started provisioning via the CLI. It provides a list of instance-types that can be provisioned via the instance-types list command. Lets get started by provisioning an ubuntu virtual machine.
morpheus> instances add
Usage: morpheus instances add TYPE NAME
-g, --group GROUP Group
-c, --cloud CLOUD Cloud
-O, --option OPTION Option
-N, --no-prompt Skip prompts. Use default values for all optional fields.
-j, --json JSON Output
-d, --dry-run Dry Run, print json without making the actual request.
-r, --remote REMOTE Remote Appliance
-U, --url REMOTE API Url
-u, --username USERNAME Username
-p, --password PASSWORD Password
-T, --token ACCESS_TOKEN Access Token
-C, --nocolor ANSI
-V, --debug Print extra output for debugging.
-h, --help Prints this help
morpheus> instances add MyInstanceName -c "Dev Vmware" -t ubuntu
Layout ['?' for options]: ?
* Layout [-O layout=] - Select which configuration of the instance type to be provisioned.
Options
===============
* Docker Ubuntu Container [104]
* VMware VM [105]
* Existing Ubuntu [497]
Layout ['?' for options]: VMware VM
Plan ['?' for options]: ?
* Plan [-O servicePlan=] - Choose the appropriately sized plan for this instance
Options
===============
* Memory: 512MB Storage: 10GB [10]
* Memory: 1GB Storage: 10GB [11]
* Memory: 2GB Storage: 20GB [12]
* Memory: 4GB Storage: 40GB [13]
* Memory: 8GB Storage: 80GB [14]
* Memory: 16GB Storage: 160GB [15]
* Memory: 24GB Storage: 240GB [16]
* Memory: 32GB Storage: 320GB [17]
Plan ['?' for options]: 10
Root Volume Label [root]:
Root Volume Size (GB) [10]:
Root Datastore ['?' for options]: ?
* Root Datastore [-O rootVolume.datastoreId=] - Choose a datastore.
Options
===============
* Auto - Cluster [autoCluster]
* Auto - Datastore [auto]
* cluster: labs-ds-cluster - 2.9TB Free [19]
Root Datastore ['?' for options]: Auto - Cluster
Add data volume? (yes/no): no
Network ['?' for options]: VM Network
Network Interface Type ['?' for options]: E1000
IP Address: Using DHCP
Add another network interface? (yes/no): no
Public Key (optional) ['?' for options]:
Resource Pool ['?' for options]: ?
* Resource Pool [-O config.vmwareResourcePoolId=] -
Options
===============
* Resources [resgroup-56]
* Resources / Brian [resgroup-2301]
* Resources / Brian / Macbook [resgroup-2302]
* Resources / David [resgroup-2158]
* Resources / David / Macbook [resgroup-2160]
Resource Pool ['?' for options]: resgroup-2160
As can be seen in the example above, the CLI can prompt the user for input on required options for provisioning this particular instance type within this particular cloud. There may be many configuration options in this scenario, such as adding multiple disks and multiple networks. It is also posslbe to skip these prompts and provision everything via one command line syntax by using the -O optionName=value syntax:
morpheus> instances add ubuntu MyInstanceName -c "Dev Vmware" -O layout=105 -O servicePlan=10 -O rootVolume.datastoreId=autoCluster
This will cause morpheus cli to skip prompting for input on these prompts. All inputs have an equivalent -O option that can be passed. To see what that option argument is enter ? on the input prompt to get specifics.
Now your VM should be provisioning and status can be checked by typing instances list.
Most of the list commands return paginated results with a default max of 25 results. There are options available for filtering and paginating the results .
Use the -s or --search option can be used to filter results by matching a phrase, for example morpheus instances list -s davey
Use the --sort ORDER and --desc options control the order of the results, for example morpheus users list --sort username and to reverse the order use morpheus users list --sort username --desc. Alternatively, the order can be specified as part of the sort option in the format --sort '[property' [asc|desc]', for example morpheus instances list --sort 'lastUpdated desc'
The -m or --max and --offset options are available for paginating the results, for example morpheus users list -m 100 will return the first 100 results instead of the default of 25, and morpheus users list -m 100 --offset 100 will load the next page of results.
To get all records, use a sufficiently large max such as -m 1000000
To see the usage and available options for any command, use -h or --help
morpheus> instances list -h
Usage: morpheus [options]
-g, --group GROUP Group Name
-m, --max MAX Max Results
-o, --offset OFFSET Offset Results
-s, --search PHRASE Search Phrase
-S, --sort ORDER Sort Order
-D, --desc Reverse Sort Order
-j, --json JSON Output
-r, --remote REMOTE Remote Appliance
-U, --url REMOTE API Url
-u, --username USERNAME Username
-p, --password PASSWORD Password
-T, --token ACCESS_TOKEN Access Token
-C, --nocolor ANSI
-V, --debug Print extra output for debugging.
-h, --help Prints this help