Getting started with Morpheus and Azure¶
This guide is designed to help you get started and quickly get the most out of Morpheus with Microsoft Azure public cloud. By the end, you will integrate your first cloud with Morpheus, configure networking, prepare and consume images, provision instances, and get started with automation. We will briefly discuss installation and account setup but will provide links to additional resources for those very first steps. For the most part, this guide assumes you are able to get Morpheus installed and are ready to move forward from that point. There is a lot more to see and do in Morpheus that is beyond the scope of this guide. For more, consult the complete Morpheus documentation or take part in our Reddit user community forum.
Installation & Setup¶
In the simplest configuration, Morpheus needs one appliance server which will contain all the components necessary to orchestrate virtual machines and containers. Full requirements, including storage and networking considerations, can be found in Morpheus documentation here. In order to provision any new Instances, hosts, or applications (or convert any discovered resources to managed resources) you will need a valid license. If you don’t have one, you can request a community edition license for free at Morpheus Hub. Once obtained, the license can be applied in Administration > Settings > LICENSE. For more, take a look at our community edition welcome package.
Groups in Morpheus define which resources a user has access to. Clouds are added to Groups and a user can only access Clouds that are in the Groups to which their roles give them access. More information on Morpheus Groups is here. A deep dive into Groups goes beyond the scope of this guide but it’s often useful to create a Group that contains all Clouds for testing purposes. We will create that group now so that we can add our first Cloud into this Group in the next section.
Navigate to Infrastructure > Groups. Here we will see a list of all configured groups but, of course, this will be empty immediately after installation. Click “+CREATE”. Give your group a name, such as “All Clouds”. The “CODE” field is used when calling Morpheus through Morpheus API or Morpheus CLI. It’s useful in most cases to have an “All Clouds” group for testing purposes so this will likely help you down the road.
Click SAVE CHANGES. Your Group is now ready to accept Clouds.
Integrating Your First Cloud¶
Clouds in Morpheus consist of any consumable endpoint whether that be on-prem, public clouds, or even bare metal. In this guide, we will focus on integrating and working with Microsoft Azure public cloud.
To get started, we will navigate to Infrastructure > Clouds. This is the Cloud list page which lists all configured Clouds. It will be empty if you’ve just completed installation and setup of Morpheus but soon we will see our integrated Azure cloud here.
Click the “+ADD” button to pop the “CREATE CLOUD” wizard. Select “AZURE (PUBLIC)” and click the “NEXT” button.
On the “CONFIGURE” tab, we’re asked to provide Azure-specific details to connect to the cloud. Morpheus Azure integration requires Owner or Contributor access to subscription via App Registration. Adding an Azure Cloud or Clouds to Morpheus will require the following:
Azure Subscription ID
Directory (tenant) ID
Application (client) ID
Application (client) Secret
Application (client) must be Owner or Contributor of Subscription
CSP Accounts require the additional following input:
CSP Directory (tenant) ID
CSP Application (client) ID
CSP Application (client) SECRET
Create App Registration¶
Morpheus authenticates with Azure via an App Registration with an Owner or Contributor Role on a Subscription. Use the steps below to create and collect the required credentials and assign the required permissions to integrate Azure with Morpheus.
Using an App Registration (service principal) that has selective resource permissions and is not an Owner or Contributor of the Subscription is not supported and will cause failures/issues. Please confirm the App Registration you use to integrate Azure with Morpheus has Owner or Contributor permissions on the specified Subscription.
If you do not have an existing Azure Active Directory App Registration, or you wish to use an new one for Morpheus, you will need to create one using the steps below. If you already have one you wish to use, continue to the next section.
Log into the Azure portal
Select “Azure Active Directory”
Select “App Registrations”
Select “New Registration”
Next, give the app a name, specify Web app / API for the type (default) and enter any URL for the Sign-on URL:
Click Create and your new App Registration will be created.
Now that we have our App Registration, we will gather the credentials required for the Morpheus Azure integration in the next section.
Copy Directory (tenant) and Application (client) IDs¶
The App Registration Directory (tenant) and Application (client) ID are required for the Morpheus Azure integration. Both can be found in the overview section of the App Registration.
Go to the Overview section of your App Registration
Copy the Directory (tenant) ID
Store/Paste for use as the Tenant ID when adding your Azure cloud in Morpheus
Copy the Application (client) ID
Store/Paste for use as the Client ID when adding your Azure cloud in Morpheus
Generate a Client Secret¶
While still in your App Registration:
Select “Certificates & secrets” in the Manage section
+ New client secret
The “Add a client secret” modal will come up
Add a description to help identify the secret in the future
Select an expiration duration
Copy the newly-generated client secret value.
Copy the client secret value before continuing as it will not be viewable again later.
Store/Paste client secret for use later when adding your Azure cloud in Morpheus
You now have three of the four credentials required for Morpheus Azure cloud integration. The last credential required is the Azure Subscription ID which we will gather in the next section.
To get the Azure Subscription ID:
Navigate to the Subscriptions section. The search function can help to locate these sections if they aren’t immediately apparent in the UI menu
In the Subscriptions section, copy the Subscription ID
Store/Paste for use as the Subscription ID when adding your Azure cloud in Morpheus
Make App Registration owner or contributor of Subscription¶
The App Registration used needs to be an owner of the Azure Subscription used for the Morpheus cloud integration. If lesser permissions are given or permissions are assigned at individual resource levels, Morpheus will not be able to properly inventory existing cloud resources, create resources or remove them.
In the Subscriptions section in Azure, select the Subscription
In the Subscription pane, select “Access Control (IAM)”
Either Click :guilabel`+ Add`, and then “Add Role Assignment” OR simply select “Add a role assignment”
In the right pane, select “Owner” or “Contributor” Role type
Search for the name of the App Registration used for the Morpheus integration
Select the App Registration in the search results
You now have the required credentials and permissions to add an Azure Cloud integration into Morpheus. Continue on with the next sections of this guide to complete the integration from the Morpheus side.
Complete the Add Cloud Process in Morpheus¶
If you’ve followed this guide from the start, you will already have a Cloud integration modal open in Morpheus UI. If you still need to open that wizard, navigate to Infrastructure > Clouds > + ADD > Azure (Public) and click NEXT. Fill in the following fields with the information gathered in the steps above:
Inventory Existing Instances
Once valid credentials are populated in the appropriate fields, the LOCATION dropdown menu will be populated. Select an available region, this is also a helpful check to ensure you’ve correctly provided working credentials. In addition, we can scope the cloud integration to all resource groups in the region (All) or can select a specific resource group to limit Morpheus resource inventorying and creation to just that resource group.
By checking INVENTORY EXISTING INSTANCES, Morpheus will automatically onboard existing cloud resources which are scoped to the region and resource group indicated. If this box is checked, we will also need to select either basic inventorying, which syncs name, IP addresses, platform types, power status, and sizing data (storage, CPU, and RAM) OR full (API heavy) inventorying which syncs resource utilization metrics (storage, CPU, and RAM) when available in addition to what we get with basic inventorying.
To move on, expand the “Advanced Options” section.
CSP accounts will also need to enter CSP TENANT ID, CSP CLIENT ID, and CSP CLIENT SECRET in the Advanced Options section.
Within the “Advanced Options” drawer are additional configurations to consider for your first Cloud. Some of these won’t usable until they reference additional configured integrations. Common settings to consider are DOMAIN, STORAGE TYPE, APPLIANCE URL (overrides the Morpheus URL for external systems), GUIDANCE (setting “Manual” will make recommendations for rightsizing), COSTING, DNS INTEGRATION, CMDB, and AGENT INSTALL MODE.
Once you’re satisfied with your selections, click “NEXT”
We have now arrived at the “GROUP” tab. In this case, we will mark the radio button to “USE EXISTING” Groups if you wish to use the Group we configured earlier. Alternatively, you can create a new one here.
Once you’ve selected or created the Group, click “NEXT”
On the final tab of the “CREATE CLOUD” wizard, you’ll confirm your selections and click “COMPLETE”. The new Cloud is now listed on the Cloud list page. After a short time, Morpheus will provide summary information and statistics on existing virtual machines, networks, and other resources available in the Cloud.
Viewing Cloud Inventory¶
Now that we’ve integrated our first Azure cloud, we can stop for a moment to review what Morpheus gives us from the Cloud detail page. We can see that Morpheus gives us estimated costs and cost histories, metrics on used resources, and also lists out resource counts in various categories including container hosts, hypervisors, and virtual machines. We can drill into these categories to see lists of resources in the various categories by clicking on the category tabs. We can link to the detail page for any specific resource by clicking on it from its resource category list.
Configuring Resource Pools¶
With our Azure Cloud configured, Morpheus will automatically sync in available resource pools and data stores.
For resource pools, once Morpheus has had time to ingest them, then will be visible from the cloud detail page. Navigate to Infrastructure > Clouds > (your Azure cloud) > Resources tab. In here, we are able to see and control access to the various resource pools that have been configured in Azure. For example, we can restrict access to a specific resource pool within Morpheus completely by clicking on the “ACTIONS” button, then clicking “Edit”. If we unmark the “ACTIVE” button and then click “SAVE CHANGES” we will see that the resource pool is now grayed out in the list. The resources contained in that pool will not be accessible for provisioning within Morpheus if it is not configured as active.
Often our clients will want to make specific blocks of resources available to their own customers. This can be easily and conveniently controlled through the same “EDIT RESOURCE POOL” dialog box we were just working in. If we expand the “Group Access” drawer, we are able to give or remove access to each pool to any Group we’d like. We can also choose to make some or all of our resource pools available to every Group. Specific resource pools can also be defined as the default for each Group when needed.
Additionally, we may choose to allow only certain service plans to be provisioned into a specific pool of resources. For example, perhaps a specific cluster is my SQL cluster and only specific services plans should be consumable within it. We can control that through this same dialog box.
Configuring Data Stores¶
To take a look at data stores, we’ll move from the “Resources” tab to the “Data Stores” tab on our Cloud detail page.
Morpheus gives the user similar control with data stores to what we saw with our resources pools earlier. Just like with resource pools, we can disable access within Morpheus completely by clicking on “ACTIONS” and then “Edit”. If we unmark the “ACTIVE” checkbox and click “SAVE CHANGES”, you will see that specific data store has been grayed out.
Just like with resource pools, we are also able to scope data stores to specific Groups. This ensures that the members of each Group are only able to consume the data stores they should have access to.
Configuring Network for Provisioning¶
When configuring networking, we can set global defaults by going to Infrastructure > Network > NETWORKS tab. Here we can add or configure networks from all Clouds integrated into Morpheus. Depending on the number of clouds Morpheus has ingested, this list may be quite large and may also be paginated across a large number of pages. In such a case, it may be easier to view or configure networks from the specific Cloud detail page so that networks from other Clouds are not shown.
Still in Infrastructure > Network, make note of the “INTEGRATIONS” tab. It’s here that we can set up any integrations that may be relevant, such as IPAM integrations. Generally speaking, when adding IPAM integrations, we simply need to name our new integration, give the API URL, and provide credentials. There’s more information in the IPAM integration section of Morpheus Docs.
In Infrastructure > Networking we can also set up IP address pools from the IP Pools tab. These pools can be manually defined, known as a Morpheus-type IP pool, or they can come from any IPAM integrations you’ve configured. As Instances are provisioned, Morpheus will assign IP addresses from the pool chosen during provisioning. When the Instance is later dissolved, Morpheus will automatically release the IP address to be used by another Instance when needed. When adding or editing a network, we can opt to scope the network to one of these configured IP address pools.
Since this guide is focused on working within an Azure cloud that we integrated at the start, we will take a look at our network configurations on the cloud detail page as well. Navigate to Infrastructure > Clouds > (your Azure cloud) > NETWORKS tab. Just as with resource pools and data stores, we have the ability to make certain networks inactive in Morpheus, or scope them to be usable only for certain Groups or Tenants.
Provisioning Your First Instance¶
At this point, the groundwork is laid and we are ready to attempt our first new provisioning. As a first Instance, we’ll provision an Apache web server to our Azure cloud. Morpheus includes a very robust catalog of pre-configured Instance types. We’ll use one of these included catalog items for this guide but you’ll likely also need to prep your own custom images and Instance types to make available to your users. Much more on this can be found elsewhere in Morpheus documentation.
Navigate to Provisioning > Instances. If any Instances are currently provisioned, we will see them listed here. To start a new Instance we click + ADD to open the “CREATE INSTANCE” wizard. We’ll scroll down to and select the Apache instance type and click “NEXT”.
First, we’ll specify the Group to provision into which determines the Clouds available. If you’ve followed this guide to this point, you should at least have a Group that houses all of your Clouds which you can select here. This will allow us to select the Azure cloud from the “CLOUD” dropdown menu. Provide a unique name to this instance and then click “NEXT”
From the “CONFIGURE” tab, we’re presented with a number of options. The options are cloud and layout-specific, more generalized information on creating Instances and available options is here. For our purposes, we’ll select the following options:
LAYOUT: Includes options such as the base OS, custom layouts will also be here when available
PLAN: Select the resource plan for your instance. Some plans have minimum resource limits, Morpheus will only show plans at or above these limits. User-defined plans can also be created in Administration > Plans & Pricing.
VOLUMES: The minimum disk space is set by the plan, this value may be locked if you’ve selected a custom plan that defines the volume size
NETWORKS: Select a network
Under the “User Config” drawer, mark the box to “CREATE YOUR USER”. Click NEXT.
“CREATE YOUR USER” will seed a user account into the VM with credentials set in your Morpheus user account settings. If you’ve not yet defined these credentials, you can do so by clicking on your username in the upper-right corner of the application window and selecting “USER SETTINGS”.
For now, we’ll simply click NEXT to move through the “AUTOMATION” tab but feel free to stop and take a look at the available selections here. There is more information later in this guide on automation and even more beyond that in the rest of Morpheus docs.
Review the settings for your first instance and click COMPLETE.
We are now dropped back onto the Instances list page. We can see a new entry in the list at this point with a status indicator that the new machine is being launched (rocket icon in the status field). We can double click on the Instance in the list to move to the Instance detail page. For now we will see a progress bar indicating that the Instance is being created and is starting up. The exact amount of time this process will take depends on selections made when provisioning the Instance. Initially, Morpheus will guess as to how long this will take and the progress bar may not be accurate. Over time, Morpheus will learn how long these processes take and progress bar accuracy will improve. For more detailed information on the status of various provisioning processes, we can scroll down and select the “HISTORY” tab. The “STATUS” icon will change from the blue rocket to a green play button when the Instance is fully ready. Furthermore, we can click on the hyperlinked IP address in the “VMS” section of this page to view a default page in a web browser to confirm success.
Creating Your First Library Item¶
In the prior section, we manually provisioned our first Instance. However, Morpheus allows you to build a catalog of custom provisionable items to simplify and speed provisioning in the future. In this section, we’ll build a catalog item and show how that can translate into quick Instance provisioning after configuration.
Before starting this process, it’s important to decide which virtual image you plan to use. If you’re not using a Morpheus-provided image, you’ll want to ensure it’s configured. You will not be able to complete this section without selecting an available image. In this example we will use a CentOS image that was previously configured in the Morpheus library. If you need to configure your own images prior to starting this section, navigate to Provisioning > Virtual Images and click + ADD. A deeper dive into image prep and virtual image configuration goes beyond the scope of this guide.
When searching for Azure Marketplace offers, please be aware as of 2.04/focal, Canonical now has separate offers for each major version sku, vs listing all version skus under the
UbuntuServer offer. Searching for the ubuntu version name, such as
focal in the IMAGE field will list that versions offers, as 20.x+ sku will not be found under the traditional
Provisionable elements in Morpheus combine a Node Type(s), Layout(s), and an Instance Type. The Overview section of Morpheus docs discusses these objects and how they work together in greater detail. Our first step here will be to create a Node Type which wrap the image itself with additional configuration, templates, and scripts. While not strictly required, creating the Node Type, Instance Type, and then the Layout is often a good workflow for creating Library items. That is the order we will follow in this guide.
Navigate to Provisioning > Library > NODE TYPES and click + ADD
In this example, I am going to set the following options in the “NEW NODE TYPE” wizard:
NAME: Example Azure CentOS 7
SHORT NAME: eac7 (Identifies the Node Type in Morpheus API/CLI)
VERSION: 7 (Ensures the correct Node Types are used when tying Layouts with multiple images to the same Instance Type)
VM IMAGE: Azure-Centos-7
Click SAVE CHANGES
With the new Node Type created, we’ll now add a new Instance type which will be accessible from the provisioning wizard once created. Move from the “NODE TYPES” tab to the “INSTANCE TYPES” tab and click + ADD.
In the “NEW INSTANCE TYPE” wizard, I’ll simply enter a NAME and CODE value. Click SAVE CHANGES. You could also provide a description, icon, and category for easier identification from the provisioning wizard later.
Now that we’ve created a new Instance type, access it by clicking on the name in the list of custom Instances you’ve created. In my case, I’ve given the name “Example Azure CentOS 7”.
Once we’ve opened the new Instance type, by default, we should be on the “LAYOUTS” tab. Click + ADD LAYOUT. I’ve set the following fields on my example layout:
NAME: Example Azure CentOS 7
VERSION: 7 (This is the version number of the layout itself, which is labeled 7 in the example)
Nodes: Select the Node Type we created earlier, if desired you can specify multiple nodes
Click SAVE CHANGES.
At this point we’ve completed the setup work and can now provision the Instance we’ve created to our specifications. Navigate to Provisioning > Instances and click + ADD. From the search bar we can search for the new Instance type we’ve created.
As before, we can select a Group and Cloud to provision this new Instance. Click NEXT. On the “CONFIGURE” tab, make note that the layout and plan are already selected because they were configured as part of creating the new Instance type. Select a network and click NEXT. Once again we will also click NEXT through the “AUTOMATION” tab. Finally, click COMPLETE.
As before when we provisioned a pre-existing Instance from the default catalog, Morpheus will now begin to spin up the new VM. How long this will take depends on the configuration and environmental factors but Morpheus will predict how long this process will take and represent that on a progress bar. Over time, Morpheus begins to learn how long these processes take and becomes more accurate in predicting spin-up time.
Once the provisioning process has completed, open the Instance detail page in Morpheus and click on the “CONSOLE” tab. You’ll be logged in with your user account and are then able to confirm the machine is ready and available, assuming the image and your custom catalog item were configured to seed user accounts and connect back to the Morpheus appliance.
Automation and Configuration Management¶
Morpheus automation is composed of Tasks and Workflows. A Task could be a script added directly, scripts or Blueprints pulled from the Morpheus Library, playbooks, recipes, or a number of other things. The complete list of Task types can be found in the Automation section of Morpheus docs. Tasks can be executed individually but they are often combined into workflows. We can opt to run a workflow at provision time or they can be executed on existing instances through the Actions menu.
In this guide we will set up an Ansible integration, create a Task, add the Task to a Workflow, and run the Workflow against a new and existing Instance. If you’ve worked through this guide to this point, you should already have an Apache instance running. If you don’t yet have that, provision one before continuing with this guide and ensure it’s reachable on port 80.
We’ll first set up the Ansible integration, you can integrate with the sample repository referenced here or integrate with your own. Go to ‘Administration > Integrations’. Click +NEW INTEGRATION and select Ansible from the dropdown menu. Fill in the following details:
ANSIBLE GIT URL: https://github.com/ncelebic/morpheus/-ansible-example, or enter the URL for your own Ansible git repository
Mark the box to “USE Morpheus AGENT COMMAND BUS”
If your git repository requires authentication, you should create a keypair and use the following URL format: firstname.lastname@example.org:ncelebic/morpheus/-ansible-example.git.
Click SAVE CHANGES. You’ll now see our new Ansible integration listed among any other configured integrations. If we click on this new integration to view detail, a green checkmark icon indicates the git repository has been fully synced.
With the Ansible integration set up, we can now create a task that includes our playbook. Go to Provisioning > Automation, click + ADD. We’ll first set our “TYPE” value to Ansible Playbook so that the correct set of fields appear in the “NEW TASK” wizard. Set the following options:
ANSIBLE REPO: Here we will choose the Ansible integration that we just created
PLAYBOOK: In our example case, enter ‘playbook.yml’
Click “SAVE CHANGES” to save our new task. We can test the new task on our Apache VM now by going to Provisioning > Instances and clicking into our VM. From the “ACTIONS” menu select “Run Task”. From the “TASK” dropdown menu, select the task we just added and click “EXECUTE”.
To see the progress of the task, click on the “HISTORY” tab and click on the (i) button to the right of each entry in the list. In this case, we can also see the results of the task by clicking on the link in the “LOCATION” column of the “VMS” section.
Now that our task is created, we can put it into a workflow. Back in Provisioning > Automation we will click on the “WORKFLOWS” tab. Click “+ADD” and select Provisioning Workflow. We’ll give the new workflow a name and expand the Post Provision section. As we begin to type in the name of the task we’ve created, it should appear as a selection. Click “SAVE CHANGES”.
Now that we have a Workflow, return to Provisioning > Instances and begin to provision another Apache instance. More detailed instructions on provisioning a new Apache instance are included earlier in this guide if needed. Now, when you reach the “AUTOMATION” section of the “CREATE INSTANCE” wizard, we have a workflow to select. From the “WORKFLOW” dropdown menu, select the workflow we just created and complete provisioning of the new instance.
As the instance is provisioning, we can go to the “HISTORY” tab and see Morpheus executing the tasks that were contained in our workflow.
This is just one example of using Morpheus to automate the process of configuring an instance to your needs. There are a number of other automation types that can be built into your Workflows as well. For further information, take a look at the automation integrations guide in Morpheus docs.
At this point you should be up and running in Morpheus, ready to consume Azure public cloud. This guide only scratches the surface, there is a lot more to see and do in Morpheus. Take a look at the rest of Morpheus Docs for more information on supported integrations and other things possible.