gomorpheus / morpheus-go-sdk

Morpheus API Client for Go

go-morpheus-sdk

• Website: https://www.morpheusdata.com/
• Docs: Morpheus Documentation
• Support: Morpheus Support

This package provides the official Go library for the Morpheus API.

This is being developed in conjunction with the Morpheus Terraform Provider.

Setup

Install Go, export environment variables, go get the morpheus package and begin executing requests.

Requirements

• Go | 1.17

Environment Variables

Be sure to setup your Go environment variables.

export GOPATH=$HOME/gocode
export PATH=$PATH:$GOPATH/bin

Installation

Use go get to retrieve the SDK to add it to your GOPATH workspace, or project's Go module dependencies.

go get github.com/gomorpheus/morpheus-go-sdk

To update the SDK use go get -u to retrieve the latest version of the SDK.

go get -u github.com/gomorpheus/morpheus-go-sdk

Usage

Here are some examples of how to use morpheus.Client.

New Client

Instantiate a new client and authenticate.

import "github.com/gomorpheus/morpheus-go-sdk"
client := morpheus.NewClient("https://yourmorpheus.com")
client.SetUsernameAndPassword("username", "password")
resp, err := client.Login()
if err != nil {
    fmt.Println("LOGIN ERROR: ", err)
}
fmt.Println("LOGIN RESPONSE:", resp)

You can also create a client with a valid access token, instead of authenticating with a username and password.

import "github.com/gomorpheus/morpheus-go-sdk"
client := morpheus.NewClient("https://yourmorpheus.com")
client.SetAccessToken("a3a4c6ea-fb54-42af-109b-63bdd19e5ae1", "", 0, "write")
resp, err := client.Whoami()
if err != nil {
    fmt.Println("WHOAMI ERROR: ", err)
}
fmt.Println("WHOAMI RESPONSE:", resp)

NOTE It is not necessary to call client.Login() explicitely. The client will attempt to authenticate, if needed, whenever Execute() is called.

Execute Any Request

You can also use the Execute method to execute an arbitrary api request, using any http method, path parameters, and body.

resp, err := client.Execute(&morpheus.Request{
    Method: "GET",
    Path: "/api/instances",
    QueryParams:map[string]string{
        "name": "tftest",
    },
})
if err != nil {
    fmt.Println("API ERROR: ", err)
}
fmt.Println("API RESPONSE:", resp)

List Instances

Fetch a list of instances.

resp, err := client.ListInstances(&morpheus.Request{})
// parse JSON and fetch the first one by ID
listInstancesResult := resp.Result.(*morpheus.ListInstancesResult)
instancesCount := listInstancesResult.Meta.Total
fmt.Sprintf("Found %d Instances.", instancesCount)

NOTE: This may be simplified so that typecasting the result is not always needed.

Testing

You can execute the latest tests using:

go test

The above command will (ideally) print results like this:

Initializing test client for tfplugin @ https://yourmorpheus.com
PASS
ok      github.com/gomorpheus/morpheus-go-sdk   1.098s

Running go test will fail with a panic right away if you have not yet setup your test environment variables.

export MORPHEUS_TEST_URL=https://yourmorpheus.com
export MORPHEUS_TEST_USERNAME=gotest
export MORPHEUS_TEST_PASSWORD=19830B3f489
export MORPHEUS_TEST_TOKEN=8c6380df-4cwf-40qd-9fm6-hj16a0357094

Be Careful running this test suite. It creates and destroys data. Never point at any URL other than a test environment. Although, in reality, tests will not modify or destroy any pre-existing data. It could still orphan some test some data, or cause otherwise undesired effects.

You can run an individual test like this:

go test -run TestGroupsCRUD

go test -v

Contribution

This library is currently under development. Eventually every API endpoint will have a corresponding method defined by Client with the request and response types defined.

Feel free to contribute by implementing the list of missing endpoints. See Coverage.

Code Structure

The main type this package exposes is Client, implemented in client.go.

Each resource is defined in its own file eg. instances.go which extends the Client type by defining a function for each endpoint the resource has, such as GetInstance(), ListInstances(), CreateInstance(), UpdateInstance, DeleteInstance(), etc. The request and response payload types used by those methods are also defined here.

Test Files

Be sure to add a _test.go file with unit tests for each new resource that is implemented.

External Resources

Link	Description
Morpheus API	The Morpheus API documentation.

Coverage

API	Available?
account_groups	n/a
accounts	Accounts
activity	Activity
appliance_settings	Appliance Settings
approvals	Approvals
apps	Apps
archive_buckets	n/a
archive_files	n/a
auth	n/a
blueprints	Blueprints
budgets	Budgets
cloud_datastores	n/a
cloud_folders	n/a
cloud_policies	n/a
cloud_resource_pools	n/a
clouds	Clouds
clusters	Clusters
containers	n/a
custom_instance_types	n/a
cypher	Cypher
dashboard	n/a
deploy	n/a
deployments	Deployments
credentials	Credentials
environments	Environments
execute_schedules	Execute Schedules
execution_request	n/a
file_copy_request	n/a
group_policies	n/a
groups	Groups
guidance_settings	Guidance Settings
image_builder	n/a
instances	Instances
integrations	Integrations
key_pairs	Key Pairs
library_cluster_layouts	Cluster Layouts
library_compute_type_layouts	n/a
library_container_scripts	Script Templates
library_container_templates	File Templates
library_container_types	Node Types
library_container_upgrades	n/a
library_instance_types	Instance Types
library_layouts	n/a
library_spec_templates	Spec Templates
license	License
load_balancer_monitors	Load Balancer Monitors
load_balancer_pools	Load Balancer Pools
load_balancer_monitors	Load Balancer Profiles
load_balancer_types	Load Balancer Types
load_balancer_virtual_servers	Load Balancer Virtual Servers
load_balancers	Load Balancers
logs	n/a
log_settings	Log Settings
monitoring	n/a
monitoring.checks	Checks
monitoring.groups	Check Groups
monitoring.apps	Monitoring Apps
monitoring_settings	Monitoring Settings
monitoring.incidents	Incidents
monitoring.alerts	Alerts
monitoring.contacts	Contacts
network_domain_records	n/a
network_domains	Network Domains
network_groups	Network Groups
network_pool_ips	n/a
network_pool_servers	Network Pool Servers
network_pools	Network Pools
network_proxies	Network Proxies
network_services	n/a
network_subnet_types	n/a
network_subnets	n/a
network_types	n/a
networks	Networks
option_type_lists	Option Type Lists
option_types	Option Types
plans	Plans
plugins	Plugins
policies	Policies
power_schedules	Power Schedules
prices	Prices
price_sets	Price Sets
processes	n/a
provision_types	Provision Types
refresh_token	n/a
reports	n/a
resource_pool_groups	Resource Pool Groups
roles	Roles
scale_thresholds	Scale Thresholds
security_group_rules	n/a
security_groups	n/a
security_packages	Security Packages
security_scans	Security Scans
server_types	n/a
servers	n/a
service_plans	Service Plans
setup	Setup
software_licenses	Software Licenses
storage_buckets	Storage Buckets
storage_providers	n/a
storage_servers	Storage Servers
subnets	n/a
task_sets	Task Sets
tasks	Tasks
user_groups	User Groups
user_settings	n/a
user_sources	Identity Sources
users	Users
vdi_allocations	VDI Allocations
vdi_apps	VDI Apps
vdi_gateways	VDI Gateways
vdi_pools	VDI Pools
virtual_images	Virtual Images
whoami	Whoami
whitelabel_settings	Whitelabel Settings
wikis	Wikis