Integrations¶

Integrations¶

To add an integration select + ADD and choose your integration. Many HPE Morpheus Software-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 HPE Morpheus Software resources, which can then be uploaded and used in any HPE Morpheus Software appliance they may be needed in. HPE Morpheus Software packages (.morpkg, .mpkg, or .mopkg) are added in the Administration > Integrations > Packages section of the UI. HPE Morpheus Software 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 HPE Morpheus Software resources are immediately available for use in the appliance.

The addition of /administration/packages is primarily targeted for uploading future HPE Morpheus Software-provided packages, however users can create, distribute and/or import custom HPE Morpheus Software packages too. This section goes over the process for writing and preparing packages for upload to a HPE Morpheus Software 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 HPE Morpheus Software 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 HPE Morpheus Software 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 HPE Morpheus Software, 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 HPE Morpheus Software appliance will be overwritten. For example, if a Task has been created by package and changes are made locally to the Task config within HPE Morpheus Software, 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. HPE Morpheus Software 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 HPE Morpheus Software 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 HPE Morpheus Software UI. The example manifest above came from a package that adds resources for an Ubuntu 22.04 library item to HPE Morpheus Software, and is named to indicate that

• CODE: Not visible in UI but exists for referencing the package via HPE Morpheus Software API

• ORGANIZATION: Appears only in the database but can be exposed via HPE Morpheus Software API

• VERSION: Listed in HPE Morpheus Software 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 HPE Morpheus Software 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 HPE Morpheus Software 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¶

HPE Morpheus Software 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.

HPE Morpheus Software maintains a repository of internally-developed and vetted plugins at HPE Morpheus Software Exchange. These plugins can be downloaded and added to HPE Morpheus Software 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 HPE Morpheus Software it’s compatible with.

Marketplace Search¶

The Plugins page includes an integrated search interface for browsing the HPE Morpheus Software Exchange marketplace directly from the UI. Plugins listed in the marketplace are automatically filtered to show only those compatible with the current appliance version, eliminating the risk of installing incompatible plugins.

From the Plugins page, use the marketplace search to:

• Browse available plugins by name or description

• View plugin details including version, compatibility, and description

• Download compatible plugins directly for installation

With at least one plugin integrated, HPE Morpheus Software 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 HPE Morpheus Software Worker is a separately deployed service that can proxy Cloud and Agent traffic, route console and VDI sessions, and act as a quorum witness for supported HVM clusters. A single Worker runtime can provide more than one capability, but each capability uses a specific registration and key in HPE Morpheus Software.

Distributed Workers, including Workers used as HVM quorum witnesses, are available in VM Essentials, Advanced, and Enterprise. The VDI Gateway use case requires an Advanced or Enterprise license.

The gateway API key and Distributed Worker key are independent. Configure only worker['worker_key'] for Distributed Worker and witness use, only worker['apikey'] for console and VDI gateway use, or both keys to enable combined roles on one runtime. A console gateway is not a separate runtime mode; it is a VDI Gateway registration selected for console routing.

Use separate Worker deployments when gateway sessions, Cloud proxy traffic, and quorum witness traffic require different network zones, independent maintenance windows, fault isolation, or capacity scaling. If roles are combined, the Worker URL, certificates, firewall rules, and availability design must satisfy every enabled role.

Supported Cloud Types

The following Cloud/Zone types have established Distributed Worker Cloud API proxy and Agent relay support:

• vmware

• vmwareCloudAws

• nutanix

• openstack

• xenserver

• macstadium

• hvm

• scvmm

• hyperv

HVM, SCVMM, and Hyper-V clouds can be managed remotely through Distributed Workers. When a Worker is assigned to an HVM, SCVMM, or Hyper-V Cloud, Cloud API traffic and Agent relay communication are proxied through the Worker. Note the following:

• An HVM appliance image based on Ubuntu 24.04 is available beginning with HPE Morpheus Software 8.0.6.

• A Distributed Worker can also serve as an HVM quorum witness beginning with HPE Morpheus Software 9.0. Witness traffic is a separate cluster quorum role in addition to Cloud API proxy support.

• For SCVMM and Hyper-V, the Worker proxies WinRM-based API calls and Agent relay traffic to the SCVMM controller host.

Installation¶

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

Requirements

• 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 HPE Morpheus Software appliance over TCP 443 (HTTPS)

• Inbound connectivity from browsers when the Worker is used as a console or VDI gateway

• Inbound connectivity from every participating HVM Host when the Worker is used as a witness

• Superuser privileges via the sudo command for the user installing the HPE Morpheus Software worker package

• Access to base yum or apt repos. Access to Optional RPM repos may be required for RPM distros

Download the appropriate package from HPE Morpheus Software 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 HPE Morpheus Software 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 HPE Morpheus Software

• 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 HPE Morpheus Software 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 HPE Morpheus Software 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

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 HPE Morpheus Software, 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 HPE Morpheus Software UI, head back to the worker box. Configure the gateway by editing /etc/morpheus/morpheus-worker.rb and updating the following:

Distributed Worker or witness only:

worker_url = 'https://worker.example.com'
worker['appliance_url'] = 'https://morpheus.example.com'
worker['worker_key'] = 'DISTRIBUTED WORKER KEY'

Console or VDI gateway only:

worker_url = 'https://worker.example.com'
worker['appliance_url'] = 'https://morpheus.example.com'
worker['apikey'] = 'VDI GATEWAY API KEY'

Combined Distributed Worker and gateway roles:

worker_url = 'https://worker.example.com' # URL used to reach this Worker
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'] = 'VDI GATEWAY API KEY'
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

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.

Once the installation is complete the morpheus worker service will automatically start and open a web socket with the specified HPE Morpheus Software 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

Verify package service health before assigning traffic:

sudo morpheus-worker-ctl status
sudo morpheus-worker-ctl tail worker

Container Installation¶

The Worker is also published as the morpheusdata/morpheus-worker container image. Use a version tag approved for the HPE Morpheus Software Manager release. Do not use latest for production because it can point to a different product version. The examples below use the confirmed 9.0.2 tag; replace it when deploying with another supported Manager release. During Docker Hub maintenance, a valid tag may temporarily be absent from the web or API tag listing.

The image exposes HTTP on port 8080 and HTTPS on port 8443. The following variables configure its roles:

Set WORKER_IMAGE_TAG to the approved tag before running these examples:

export WORKER_IMAGE_TAG=9.0.2

Distributed Worker only:

docker run -d --name morpheus-worker \
  -p 8080:8080 \
  -e MORPHEUS_URL=https://morpheus.example.com \
  -e MORPHEUS_WORKER_KEY=<distributed-worker-key> \
  morpheusdata/morpheus-worker:${WORKER_IMAGE_TAG}

A witness also uses MORPHEUS_WORKER_KEY, but it must publish a trusted endpoint reachable from every participating Host. Use the production HTTPS example below for a witness container.

Console or VDI gateway only with a test self-signed listener:

docker run -d --name morpheus-worker \
  -p 8443:8443 \
  -e MORPHEUS_URL=https://morpheus.example.com \
  -e MORPHEUS_KEY=<vdi-gateway-key> \
  -e MORPHEUS_SELF_SIGNED=true \
  morpheusdata/morpheus-worker:${WORKER_IMAGE_TAG}

Combined Distributed Worker and gateway roles:

docker run -d --name morpheus-worker \
  -p 8443:8443 \
  -e MORPHEUS_URL=https://morpheus.example.com \
  -e MORPHEUS_WORKER_KEY=<distributed-worker-key> \
  -e MORPHEUS_KEY=<vdi-gateway-key> \
  -e MORPHEUS_SELF_SIGNED=true \
  morpheusdata/morpheus-worker:${WORKER_IMAGE_TAG}

For production HTTPS or witness use, mount a PKCS#12 certificate and omit MORPHEUS_SELF_SIGNED:

docker run -d --name morpheus-worker \
  -p 8443:8443 \
  -v /secure/path/cert.p12:/etc/certs/cert.p12:ro \
  -e MORPHEUS_URL=https://morpheus.example.com \
  -e MORPHEUS_WORKER_KEY=<distributed-worker-key> \
  -e MORPHEUS_SSL_ALIAS=<certificate-alias> \
  -e MORPHEUS_SSL_PASSWORD=<certificate-password> \
  morpheusdata/morpheus-worker:${WORKER_IMAGE_TAG}

After startup, verify that the container is running and healthy, that the configured Worker or gateway appears active in HPE Morpheus Software, and that clients for each enabled role can reach the published URL:

docker ps --filter name=morpheus-worker
docker inspect --format '{{.State.Health.Status}}' morpheus-worker
docker logs morpheus-worker

The image health check verifies the bundled Guacamole service. Also validate the HPE Morpheus Software registration and the end-to-end traffic path for each enabled role. Upgrade by validating a new release-compatible tag, recreating the container with the same registration keys and certificate configuration, and repeating the role-specific checks.

Witness Configuration¶

A Distributed Worker can provide quorum witness services for HVM 1.3 or later clusters using an HPE Shared File System (GFS2) datastore. This includes two-node GFS2 clusters and stretch clusters with site groups. For the complete two-node topology, deployment order, validation, failure behavior, and limitations, see Two-Node Clusters with a Witness.

The Worker URL on the Distributed Worker record is mandatory for witness use. HPE Morpheus Software uses this value to construct the witnessUrl sent to each cluster Host. Every participating Host must be able to resolve the URL, route to the Worker listener, and trust its TLS certificate. The Worker’s outbound connection to the HPE Morpheus Software appliance does not prove that Hosts can reach the witness.

Before assigning a witness:

1. Create the Distributed Worker record in Administration > Integrations > Distributed Workers and set Worker URL to the stable client-facing URL for the Worker.

2. Configure the runtime with the record’s worker_key or MORPHEUS_WORKER_KEY.

3. Verify that the Worker shows as active in HPE Morpheus Software.

4. From every cluster Host, resolve the Worker URL and make an HTTPS connection to it. A successful TLS connection or HTTP response confirms the path; do not disable certificate validation in production.

5. Ensure firewalls and load balancers preserve the witness path and do not require interactive authentication.

For cluster assignment and quorum validation:

• Two-Host GFS2 with no Site Groups: Two-Node Clusters with a Witness

• Site Groups / multi-site stretch: Stretch Clusters & Witness Nodes

Highly-Available (HA) Deployment¶

If desired, multiple distributed worker nodes may be associated to the same HPE Morpheus Software 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, HPE Morpheus Software Agent communications can be balanced equally across worker nodes by placing a VIP in front of your distributed workers.