Integrations¶

Note

To add and edit certain integrations such as Ansible Tower, vRO, Chef and Puppet, the user must have FULL permission for “Library: Integrations” in addition to “Admin: Integrations”.

To add an integration select + ADD and choose your integration. Many Morpheus-supported integrations can be configured in this section, though not all. Some integrations, such as networking integrations, must be configured within their own areas of the application. The following integrations can be configured in this section:

Chef
Puppet
Ansible
Ansible Tower
vRealize Orchestrator
Microsoft DNS
PowerDNS
Route 53
Bind DNS
Git
Github
Docker Repositories
Jenkins
ServiceNow
Cherwell
Remedy

Please see the Guides for each specific integration type for more detailed information on setup steps and features supported by the integration.

Packages¶

Overview¶

Packages are code files used to define Morpheus resources, which can then be uploaded and used in any Morpheus appliance they may be needed in. Morpheus packages (.morpkg, .mpkg, or .mopkg) are added in the Administration > Integrations > Packages section of the UI. Morpheus packages contain Library and automation objects, such as Instance Types, Layouts, Node Types, Tasks, Spec Temples and Cluster Layouts. Following upload of a valid package, the defined Morpheus resources are immediately available for use in the appliance.

The addition of /administration/packages is primarily targeted for uploading future Morpheus-provided packages, however users can create, distribute and/or import custom Morpheus packages too. This section goes over the process for writing and preparing packages for upload to a Morpheus appliance.

Role Permissions¶

Access and capabilities for the Packages section is determined by the following role permissions:

Role: Feature Access: Admin: Plugins

None: Cannot access Admin: Plugins section
Full: Access to Admin: Plugins and ability to upload Morpheus packages (.morpkg, .mpkg, or .mopkg)

Getting Started¶

Packages consist of two primary parts, a .json manifest file (which sets some metadata about the package) and one or more .scribe files which define the resources to be added. These files are zipped and imported into Morpheus as one file (.morpkg, .mpkg, or .mopkg). Scribe files are written in HCL (Hashicorp Configuration Language) and follow referenced resource naming. In the next section, we will define the required attributes for both the .json manifest and the scribe files with examples.

When uploading packages to Morpheus, keep in mind that the same packages can be reinstalled as many times as desired. When the same package is reinstalled, any local changes to those resources made in the Morpheus appliance will be overwritten. For example, if a Task has been created by package and changes are made locally to the Task config within Morpheus, subsequent uploads of the packages would overwrite those changes. A better method for making changes to package-sourced resources would be to update the package code, increase the version number, and upload the package once again. This ensures important local changes would not be overwritten by subsequent uploads. There is no warning given in the UI, changes are simply overwritten without notice.

Additionally, it’s worth noting that while packages can be deleted (🗑 icon on the packages detail page), you will simply delete the package from the list. Morpheus will show a helpful list of resources added with the package if cleanup is desired but will not delete them.

Creating Packages¶

As noted in the last section, a package consists of a .json manifest file and any number of .scribe files. We’ll first look at the manifest file, its purpose, and attributes that must be included in the JSON map.

A typical package manifest looks like this:

{
    "type": "scribe",
    "name": "morpheus-ubuntu-22.04-vmware",
    "code": "morpheus-ubuntu-22.04-vmware",
    "organization": "morpheus",
    "version": "20240415"
}

The manifest includes each of the following attributes:

TYPE: Tells Morpheus to process all included files with the package as scribe files. Currently, this is the only supported type
NAME: This is the name for the package that will appear in Morpheus UI. The example manifest above came from a package that adds resources for an Ubuntu 22.04 library item to Morpheus, and is named to indicate that
CODE: Not visible in UI but exists for referencing the package via Morpheus API
ORGANIZATION: Appears only in the database but can be exposed via Morpheus API
VERSION: Listed in Morpheus UI and is useful for tracking changes over time to package-sourced resources

Scribe files are quite a bit more complicated and have not yet been fully documented publicly. Nevertheless, we can show a couple examples here and give strategies for extracting additional examples from your own environment. Certain resources will require reference to other resources included with the scribe file. Here’s a simple scribe file creating a shell script-type “Hello World” Task:

resource "task" "HelloWorld" {
  name = "HelloWorld"
  uuid = "2c2306e0-3b30-4886-b8a3-d1362c9b9490"
  dateCreated = "2024-04-19T19:15:47.000Z"
  executeTarget = "resource"
  labels = [ "export" ]
  lastUpdated = "2024-04-19T19:18:40.000Z"
  options = [
    { optionType = { code = "shell.sudo" }, value = "on" },
    {
      content = { uuid = "ff5de589-75da-48ec-ba66-5fe5905397b0" }
      optionType = { code = "script" }
    }
  ]
  taskType = { code = "script" }
}

resource "file-content" "ff5de589-75da-48ec-ba66-5fe5905397b0" {
  uuid = "ff5de589-75da-48ec-ba66-5fe5905397b0"
  content = "echo \"Hello World\""
  dateCreated = "2024-04-19T19:15:47.000Z"
  lastUpdated = "2024-04-19T19:15:47.000Z"
}

In this case, the Task config was written locally in the Add/Edit Task modal within Morpheus rather than sourced from elsewhere (such as a Github repository). The Task content itself is a distinct resource and is referenced in the Task resource by UUID. Outside resources can also be referenced by HCL referenced resource naming such as in the following example where a workload-type resource references a virtual-image resource:

resource "virtual-image" "vmware_vsphere_image_morpheus_almalinux_9_20240324" {
  code = "vmware_vsphere_image_morpheus_almalinux_9_20240324"
  category = "vmware.vsphere.image.morpheus.almalinux"
  name = "Morpheus AlmaLinux 9 XX-DATE-XX"
  imageType = "vmdk"
  remotePath = "https://s3-us-west-1.amazonaws.com/morpheus-images/vmware/20240324/almalinux-9/morpheus-almalinux-9-x86_64-20240324.ovf"
  imagePath = "vmware/20240324/almalinux-9"
  isCloudInit = true
  systemImage = true
  installAgent = true
  osType {
    code = "almalinux.9.64"
  }
  zoneType = "vmware"
}

resource "workload-type" "vmware_almalinux_9" {
  code = "vmware-almalinux-9"
  shortName = "almalinux"
  name = "AlmaLinux 9"
  ports = [22]
  containerVersion = "9"
  entryPoint = ""
  mountLogs = "/var/log"
  statTypeCode = "vm"
  logTypeCode = "vm"
  showServerLogs = true
  category = "almalinux"
  cloneType = "almalinux"
  priorityOrder = 0
  serverType = "vm"
  providerType = "vmware"
  containerPorts = [{code = "almalinux.22"}]
  actions = [{code = "generic-remove-node"}]
  checkTypeCode = "containerCheck"
  virtualImage = virtual-image.vmware_vsphere_image_morpheus_almalinux_9_20240324
  provisionType = "vmware"
  backupType = "vmwareSnapshot"

The specific virtual image is referenced as virtual-image.vmware_vsphere_image_morpheus_almalinux_9_20240324.

To go further, you can generate additional examples from your own environments. Use the Import/Export feature built into Morpheus and export your created resources into integrated Git repositories. When viewing the results in your repositories, you’ll see the resources are exported as scribe files.

Preparing and Uploading Packages¶

To prepare the package, ensure the manifest and scribe files are gathered into one directory. You’ll then need to zip the contents of that directory with a valid extension (.morpkg, .mpkg, or .mopkg). In Linux, from outside the directory, you can use: zip -j <package-name>.mpkg <directory-name>/*. The package is now ready to be uploaded. Navigate to Administration > Integrations > Packages on any appliance and use the file picker tool to upload your new package file.

Plugins¶

Overview¶

Morpheus is extendable with custom plugins for Task types, UI tabs, reports, approvals, cypher, and more. Plugins are added from the Plugins tab of the Integration page under Administration (Administration > Integrations > Plugins). Simply browse for a local plugin file (.jar) to add it to the UI. Custom plugins can also be edited or deleted by clicking on the pencil or trash can icons in the corresponding row.

Morpheus maintains a repository of internally-developed and vetted plugins at Morpheus Exchange. These plugins can be downloaded and added to Morpheus using the instructions in the prior paragraph. Alongside the download link, you can also find helpful readme information that discusses how the plugin can be used and which versions of Morpheus it’s compatible with.

With at least one plugin integrated, Morpheus will show details on each plugin from the Plugins List View. The following information is displayed:

NAME: The name given to the plugin
DESCRIPTION: A description value (if any) coded into the plugin
FILE NAME: The .jar filename
VERSION: The plugin version number
STATUS: The status of the plugin, such as “loaded” when the plugin is ready for use
STATUS MESSAGE: A status message (if any) for the plugin
ENABLED: If the plugin is enabled, a check mark appears here. Disabled plugins are also grayed out

Additional information about each plugin can be viewed by clicking on the pencil (edit) icon. Most of the information in this modal is read-only but you can enable or disable plugins from this pane.

Please visit the Morpheus Developer Portal for Plugin Architecture SDK documentation and help getting started with custom Plugin development.

Distributed Workers¶

Overview¶

The Morpheus distributed worker is installed using the same package as the VDI Gateway worker. Organizations which have already deployed VDI Gateway(s) can use the same worker for both purposes if desired, you’d simply need to update configuration in /etc/morpheus/morpheus-worker.rb and run a reconfigure. When creating a distributed worker or VDI Gateway object in Morpheus UI, an API key is generated. Adding one or both types of API keys to the worker configuration file determines if the worker is running in VDI gateway and/or distributed worker mode.

Supported Cloud Types

The following Cloud/Zone types support Distributed Workers

vmware
vmwareCloudAws
nutanix
openstack
xenserver
macstadium

Installation¶

A distributed worker VM is installed and configured similarly to a Morpheus appliance via rpm or deb package.

Note

Package URLs for the distributed worker are available at https://app.morpheushub.com in the downloads section.

Note

The distributed worker requires that the Morpheus appliance has a trusted SSL certificate. This can be accomplished by configuring a public trusted SSL certificate on the Morpheus appliance (or load balancer) or ensure the certificate and chain are added to the Java Keystore of the Distributed Worker to trust the certificate.

Requirements

**Supported Operating Systems**¶
OS	Version(s)
Amazon Linux	2
CentOS	7.x, 8.x
Debian	10, 11
RHEL	7.x, 8.x
SUSE SLES	12
Ubuntu	18.04, 20.04, 22.04

Memory: 4 GB RAM minimum recommended
Storage: 10 GB storage minimum recommended. Storage is required for installation packages and log files
CPU: 4-core minimum recommended
Network connectivity to the Morpheus appliance over TCP 443 (HTTPS)
Superuser privileges via the sudo command for the user installing the Morpheus worker package
Access to base yum or apt repos. Access to Optional RPM repos may be required for RPM distros

Important

In order to proxy VMware vCenter Cloud traffic through a Distributed Worker, you must have a static public DNS entry for the internal IP address of the vCenter appliance. If this is not done, everything may appear to be working properly when configuring the Cloud but problems will arise at provision time. This is not a Morpheus limitation but is a limitation of the VMware SDK client which does not natively support proxies.

Download the appropriate package from Morpheus Hub based on your target Linux distribution and version for installation in a directory of your choosing. The package can be removed after successful installation.

wget https://downloads.morpheusdata.com/path/to/morpheus-worker-$version.distro

Validate the package checksum as compared with the values indicated on Hub. For example:

sha256sum morpheus-worker-$version.distro

Next, install the package using your selected distribution’s package installation command and your preferred options. Example, for RPM:

rpm:

$ sudo rpm -ihv morpheus-worker-$version.$distro

Preparing...                          ################################# [100%]
Updating / installing...
   1:morpheus-worker-x.x.x-1.$distro    ################################# [100%]
Thank you for installing Morpheus Worker!
Configure and start the Worker by running the following command:

sudo morpheus-worker-ctl reconfigure

Configuration¶

With the package installed, we need to add a new distributed worker in Morpheus UI. Distributed workers are added in Administration > Integrations > Distributed Workers. To create one, populate the following fields:

NAME: A name for the distributed worker in Morpheus
DESCRIPTION: An optional description for the distributed worker
PROXY HOSTS: A comma-delimited list of global proxy hosts, any endpoint listed here will be proxied through the Morpheus worker. For VMware, you must list the host addresses for any vCenter you wish to proxy through the worker. Xen hosts and PowerVC hosts must be listed here as well. Other Cloud types which are supported by the Morpheus worker need only have the worker configured on the Edit Cloud modal (Infrastructure > Clouds > Selected Cloud > Edit button)
ENABLED: When marked, the selected worker is available for use

Important

The proxy host URL entered in the Worker configuration must match the URL set in the Cloud configuration. That is, if you use the URL in the Cloud configuration you must also use it in the Worker configuration. The reverse is also true, if an IP address is used in the Cloud configuration, that should be used in the Worker configuration as well. There are also configuration considerations that must be made for proxying vCenter Cloud traffic through a Distributed Worker. See the “IMPORTANT” box in the “Requirements” section for additional details.

After clicking SAVE CHANGES, an API key is generated and displayed. Make note of this as it will be needed in a later configuration step.

With the worker configured in Morpheus, the next step is to update supported Cloud integrations which should be proxied through the worker. Select the desired Cloud from the Clouds List Page (Infrastructure > Clouds) and click EDIT from the chosen Cloud’s Detail Page. Within the Connection Options section, choose a configured worker from the WORKER dropdown menu. Click SAVE CHANGES.

With the API key in hand and configuration complete in Morpheus UI, head back to the worker box. Configure the gateway by editing /etc/morpheus/morpheus-worker.rb and updating the following:

worker['worker_url'] = 'https://gateway_worker_url' # This is the worker URL the Morpheus appliance can resolve and reach on 443
worker['appliance_url'] = 'https://morpheus_appliance_url' # The resolvable URL or IP address of Morpheus appliance which the worker can reach on port 443
worker['apikey'] = 'API KEY FOR THIS GATEWAY' # VDI Gateway API Key generated from Morpheus Appliance VDI Pools > VDI Gateways configuration. For worker only mode, a value is still required but can be any value, including the 'API KEY FOR THIS GATEWAY' default template value
worker['worker_key'] = 'DISTRIBUTED WORKER KEY' # Distributed Worker API Key from Administration > Integrations > Distributed Workers configuration
worker['proxy_address'] = 'http://proxy.address:1234' # For environments in which the worker must go through a proxy to communicate with the Morpheus appliance or other resources, configure the address
worker['no_proxy'] = 'vcenter.example.com,192.168.xx.xx' # A comma-separated list of resources that should be accessed directly and not through the proxy

Note

By default the worker_url uses the machine’s hostname, ie https://your_machine_name. The default worker_url value can be changed by editing /etc/morpheus/morpheus-worker.rb and changing the value of worker_url. Additional appliance configuration options are available below.

After all configuration options have been set, run sudo morpheus-worker-ctl reconfigure to install and configure the worker, nginx and guacd services:

sudo morpheus-worker-ctl reconfigure

The worker reconfigure process will install and configure the worker, nginx and guacd services and dependencies.

Tip

If the reconfigure process fails due to a missing dependency, add the repo that the missing dependency can be found in and run

Note

Configuration options can be updated after the initial reconfigure by editing /etc/morpheus/morpheus-worker.rb and running sudo morpheus-worker-ctl reconfigure again.

Once the installation is complete the morpheus worker service will automatically start and open a web socket with the specified Morpheus appliance. To monitor the startup process, run morpheus-worker-ctl tail to tail the logs of the worker, nginx and guacd services. Individual services can be tailed by specifying the service, for example morpheus-worker-ctl tail worker

Highly-Available (HA) Deployment¶

If desired, multiple distributed worker nodes may be associated to the same Morpheus appliance to eliminate a single point of failure should a distributed worker node go down. Configure each distributed worker node using the same worker key (process described in the prior section) and add redundancy using as many additional workers nodes as needed. When multiple worker nodes are using the same worker key, proxy calls will always go through the primary worker node when possible. The primary node is the first worker node configured using a specific worker key. When necessary, automatic failover will take place and another active worker node will be used. While proxy calls will always try to use the primary node when available, Morpheus Agent communications can be balanced equally across worker nodes by placing a VIP in front of your distributed workers.