Blueprints¶

Overview¶

App Blueprints support a vast array of providers and configurations with programmatic markup or Infrastructure as Code capabilities. Blueprints configs can be manually added or scoped to a git repo. Morpheus blueprints allows for full automation configuration, locked fields, tiered boots, and linked tiers with exported evars. All blueprints have permission settings for controlling group and tenant access.

Blueprint Types¶

Morpheus
Terraform
ARM (Azure)
CloudFormation (AWS)
Kubernetes
Helm

Morpheus Blueprints¶

Morpheus App Blueprints allow pre-configured full multi-tier application deployments for multiple environments. Blueprints can be provisioned from the Provisioning -> Apps section and can be fully configured for one click provisioning. Blueprints can be built within the Builder section or by code in the Raw section. Blueprints can also be exported as YAML or JSON and created with the Morpheus API and CLI.

A unique capability of the YAML/JSON based Morpheus blueprint structure is the ability to have multiple configurations per instance being provisioned within the app blueprint. This can be a scoped configuration that acts as overrides based on selected cloud, group, and/or environment the app is being provisioned in as a target. For example. maybe the “development” environment doesn’t need as many horizontally scaled nodes as the “production” environment. Another great aspect of this configuration markup is a blueprint can be defined as a hybrid cloud blueprint. This makes the app blueprint structure very powerful and in some ways better than alternative infrastructure as code orchestrators. For Example, ARM is locked into Azure, while CloudFormation is locked into AWS. Even Terraform does not allow a tf file to expand its bounds beyond a specific provider type.

Basic Blueprint Structure¶

In a Morpheus App Blueprint there are a few structural concepts to be aware of. Firstly there is a concept of a Tier. A Tier is a grouping of instances within an app blueprint. Tiers can be used for a variety of things including sequenced booting of instances or even properly creating endpoint groups and security group contexts in network security tools like Cisco ACI. An example of a Tier structure might be a Web tier and a Database tier. These tiers can also be marked as connected such that network communication rules can appropriately be defined. A basic 2 Tier blueprint skeleton might look something like this:

name: Tier Example
type: morpheus
tiers:
  Web:
    linkedTiers:
      - Database
    tier:
      bootOrder: 1
    instances:
  Database:
    tier:
      bootOrder: 0
    instances:

This example has defined 2 tiers as yaml properties under the tiers object. They are called Web and Database. A Tier can optionally define its connected tiers which are bi-directional even though only one tier has to define them. This is the linkedTiers array and simply lists the connected tiers by tier name. A Boot Order can also optionally be defined under a nested {"tier": {"bootOrder": 1}} object structure.

Configuration Scopes¶

Another capability of Morpheus App Blueprint structure is its configuration scoping. This allows properties to be overridden based on the apps target environment or even target group and cloud. For example. Maybe we want to use a larger plan size in production vs. development

An example of that can be done using “environments” overrides.

name: Simple Nginx
type: morpheus
tiers:
  Web:
    instances:
      - instance:
          type: docker
          name: Sample Nginx
        clouds:
          AWS Cali:
            instance:
              layout:
                code: docker-1.7-single
            config:
              dockerImageVersion: latest
              dockerRegistryId: ''
              dockerImage: nginx
            plan:
              code: container-128
         environments:
           Production:
             groups:
               All Clouds Demo:
                 clouds:
                   AWS Cali:
                     plan:
                       code: container-256

Note the new environments object. The object graph of the morpheus blueprint structure gets merged and flattened at provision time based on the scope of the configurations provided as well as the users target cloud, group, and environment selection. In the Above example, a selective override was done for the AWS Cali cloud when using a Production Environment and deploying to the group All Clouds Demo. This specific example changes the plan to a larger size. Scoped configurations have various levels of precedence. Cloud is the lowest level of precedence. a cloud configuration in a group is the next level higher and finally an environment configuration in a group in a cloud is the highest level of scoped precedence.

Getting Started¶

To get started, it may be best to look at a simple App Blueprint configuration. Docker templates are less complex than virtual machine based templates so lets look at a Blueprint that deploys a single Nginx container to a target cloud:

name: Simple Nginx
type: morpheus
tiers:
  Web:
    linkedTiers: []
    instances:
      - instance:
          type: docker
          name: Sample Nginx
        clouds:
          AWS Cali:
            instance:
              layout:
                code: docker-1.7-single
                id: 206
            volumes:
              - rootVolume: true
                name: root
                size: 1
            backup:
              createBackup: false
            config:
              dockerImageVersion: latest
              dockerRegistryId: ''
              dockerImage: nginx
            plan:
              id: 68
              code: container-128
            ports:
              - name: HTTP
                port: 80
                lb: HTTP

Theres some useful things to look at in the above docker example. One is there are different objects based on the different available configuration options for the target provision type. These options are actually data driven and can be extracted from the option types api in the morpheus api doc. That is a useful resource to look at while building morpheus blueprints or by using the morpheus-cli which provides prompts for helping build custom morpheus app blueprints.

Creating App Blueprints¶

Navigate to Provisioning -> Blueprints
Select + ADD
Enter a NAME for the Blueprint and select NEXT
Optionally add a Description, Category, and Image for the Blueprint.

Add Tiers¶

In the STRUCTURE section, select + to add a Tier
Select or enter a Tier Name.
Select the Tier to set Boot Order, rename, or once multiple Tiers are added, connect the Tier to other Tiers.

Add Instances to Tiers¶

In the STRUCTURE section, select + in a Tier to add an Instance
Select an Instance Type
Optionally add a name for the Instance. Instances with blank names will automatically be named based off the App name.

Tip

You can use the variable ${app.name} in your instance naming convention to reference the name of the application you’re deploying.

Add Configurations to Instances¶

In the STRUCTURE section, select + in an Instance to add a Configuration
Select at least one option from Group, Cloud or Environment.
Select ADD CONFIG to create the configuration
Populate the Configuration
- Configurations can be fully partially or populated
- Fields can be locked or hidden by selecting the Lock icon next to the Field. Locking prevents the field from being editable when provisioning an App using the Blueprint while hidden fields are not revealed to the user at all
- ALLOW EXISTING INSTANCE will allow users to add existing Instances to the App when using the blueprint

Save¶

Once all desired Tiers, Instances and Configurations are added, select Save. The Blueprint will be created, can be edited after saving, and will available in the Apps section for provisioning.

Note

Blueprints are not provisioned when created. To provision a Blueprint, use Provisioning -> Apps.

RAW¶

Blueprints can be create, edited or Exported in the RAW section when creating or editing a blueprint.

To Export a Blueprint as JSON or YAML:

Navigate to Provisioning > Blueprints
Edit an existing App by clicking on the pencil icon
On the Edit Blueprint modal, select the Raw tab
Select YAML or JSON from the dropdown in the top right
Click the Export button
Select the configurations to include in the export by selecting or deselecting configurations as needed. Selected configurations will be highlighted
Click the DOWNLOAD CONFIGURATION button
The Blueprint export file will be downloaded to your computer as {app_name}-config.json or {app_name}-config.yaml

Preview¶

In the APP BLUEPRINT modal, select the Preview section to display a graphical representation of your Blueprint Tiers, Instances and Tier Connections.

Important

When Tiers are connected, the Instances in a Tier will import the evars from Instances in connected Tiers, and if |morpheus] is managing the Instance Firewalls, communication between the Instances will be facilitated based on the Instances port configurations.

Provisioning¶

To provision a Blueprint, navigate to Provisioning -> Apps and select the Blueprint when creating an App. See the App section of Morpheus docs for more on provisioning Apps.

Terraform Blueprints¶

Terraform Blueprints are one way that Terraform can be integrated and leveraged with Morpheus, with the other being the Morpheus Terraform provider which is not discussed in this section. Morpheus and Terraform are complimentary technologies which together can increase efficiency and simplify automation across cloud environments. For more on this relationship, see our whitepaper on how Morpheus and Terraform are better together.

Currently, Morpheus supports provisioning Apps based on Terraform Blueprints to VMware, Amazon, Azure, and Oracle Clouds with additional Cloud support coming in future releases. On first attempt to provision a Terraform App, Morpheus will automatically install Terraform. It is possible in some operating system configurations for this automated installation process to fail, requiring you to install Terraform manually. If needed, manual installation instructions and guidance are provided here.

To create a new Terraform Blueprint, navigate to Provisioning > Blueprints. Click + ADD.

On the Name tab of the New Blueprint modal, enter a name for your new Blueprint. In the Type dropdown menu, select Terraform. NEXT

In the Blueprint Summary section, complete the following fields as needed:

NAME: Enter a name for this Blueprint as it will appear in the Morpheus Blueprints list
DESCRIPTION: An optional description field for your Blueprint
CATEGORY: An optional category tag for your Blueprint, such as web, utility, or app
IMAGE: An optional image icon to more easily identify your Blueprint from a list. If no image is uploaded, a default image will be used

The Terraform Configuration section is where the Terraform template file (.tf) is added or linked to the Blueprint. Using a Config Type of “Terraform (.tf)” or “Terraform JSON (.tf.json)”, you can write or paste your configuration directly into the new Blueprint. Alternatively, you can pull in config files from an integrated Git repository using the “Git Repository” Config type.

In the Terraform Configuration section, complete the following fields as needed when entering your configuration directly into the new Blueprint:

CONFIG TYPE: “Terraform (.tf)” or “Terraform JSON (.tf.json)” to create or paste configuration directly into the new Blueprint
CONFIG: Enter your configuration here
TFVAR SECRET: Select an existing TFVar-formatted Cypher. See the Cyphers section or Morpheus docs for more information on Cyphers
OPTIONS: Enter any additional options, such as a variable definition

In the Terraform Configuration section, complete the following fields as needed when syncing in configuration from a Git repository:

CONFIG TYPE: “Git Repository”
SCM INTEGRATION: If a pre-existing SCM integration is selected here, the available selections in the “Repository” dropdown menu will be filtered to show only those associated with the chosen SCM integration
REPOSITORY: Select the repository in which your configuration resides
BRANCH OR TAG: The branch in which your configuration resides
WORKING PATH: The path to your configuration files
CONFIG: Your selected config file
TFVAR SECRET: Select an existing TFVar-formatted Cypher. See the Cyphers section of Morpheus docs for more information on Cyphers
OPTIONS: Enter any additional options, such as a variable definition

Once finished, click COMPLETE.

Your new Terraform Blueprint is now saved and should be visible in the list of Blueprints. Blueprints are deployed in the Provisioning > Apps section of Morpheus. See the Apps section of Morpheus docs for more information on that process.

ARM Blueprints¶

ARM Blueprints provide a simple and repeatable way of deploying infrastructure-as-code to Azure Clouds. Objects and properties are defined in a JSON file and are provisionable on-demand in Provisioning > Apps

To create a new ARM Blueprint, navigate to Provisioning > Blueprints. Click + ADD.

On the Name tab of the New Blueprint modal, enter a name for your new Blueprint. In the Type dropdown menu, select ARM. NEXT

In the Blueprint Summary section, complete the following fields as needed:

NAME: Enter a name for this Blueprint as it will appear in the Morpheus Blueprints list
DESCRIPTION: An optional description field for your Blueprint
CATEGORY: An optional category tag for your Blueprint, such as web, utility, or app
IMAGE: An optional image icon to more easily identify your Blueprint from a list. If no image is uploaded, a default image will be used

The ARM template itself is defined in the ARM Configuration section. Using the Config Type dropdown menu, we can opt to write or paste JSON configuration directly into this modal, or we can choose to bring in a JSON which we’re keeping under version control in a Git repository.

Depending on whether we need the Morpheus Agent installed and/or cloud-init enabled, mark the following boxes in the next section:

INSTALL AGENT
CLOUD INIT ENABLED

If writing or pasting your configuration JSON directly into the modal, fill out the following fields:

OS TYPE: Identify the resources to be created as Linux or Windows
CONFIG TYPE: ARM Template JSON (.json)
CONFIG: Your JSON configuration template

If bringing in a template from a Git repository, fill out the following fields:

OS TYPE: Identify the resources to be created as Linux or Windows
CONFIG TYPE: “Git Repository”
SCM INTEGRATION: If a pre-existing SCM integration is selected here, the available selections in the “Repository” dropdown menu will be filtered to show only those associated with the chosen SCM integration
REPOSITORY: Select the repository in which your configuration resides
BRANCH OR TAG: The branch in which your configuration resides
WORKING PATH: The path to your configuration files
CONFIG: Your selected config file

Once finished, click COMPLETE.

Your new ARM Blueprint is now saved and should be visible in the list of Blueprints. Blueprints are deployed in the Provisioning > Apps section of Morpheus. See the Apps section of Morpheus docs for more information on that process.

CloudFormation Blueprints¶

CloudFormation Blueprints consume new or existing CloudFormation templates to create easily-deployable application stacks. CloudFormation templates in Morpheus are JSON or YAML-formatted text documents that declare all relevant AWS resources needed for the provisioned application. They can be created directly in the New Blueprint modal or pulled in from existing Git repositories.

If needed, Amazon has educational resources available for getting started with CloudFormation. They can be found in the AWS CloudFormation documentation.

To create a new CloudFormation Blueprint, navigate to Provisioning > Blueprints. Click + ADD.

On the Name tab of the New Blueprint modal, enter a name for your new Blueprint. In the Type dropdown menu, select CloudFormation. Click NEXT

In the Blueprint Summary section, complete the following fields as needed:

NAME: Enter a name for this Blueprint as it will appear in the Morpheus Blueprints list
DESCRIPTION: An optional description field for your Blueprint
CATEGORY: An optional category tag for your Blueprint, such as web, utility, or app
IMAGE: An optional image icon to more easily identify your Blueprint from a list. If no image is uploaded, a default image will be used

Depending on whether we need the Morpheus Agent installed and/or cloud-init enabled, mark the following boxes in the next section:

INSTALL AGENT
CLOUD INIT ENABLED

In some cases, you must explicitly acknowledge that your template contains certain capabilities in order for the application to successfully be deployed. There is more information on this in Amazon’s documentation here. If any of the following capabilities are contained in your application, acknowledge them by marking any of the following boxes that apply:

CAPABILITY_IAM
CAPABILITY_NAMED_IAM
CAPABILITY_AUTO_EXPAND

Continuing on with the CloudFormation Configuration section, complete the following fields as needed when entering your configuration directly into the new Blueprint:

CONFIG TYPE: “CloudFormation Template JSON (.json)”
CONFIG TYPE: “CloudFormation Template YAML (.yaml)”
CONFIG: Enter your configuration here

In the CloudFormation Configuration section, complete the following fields as needed when syncing in configuration from a Git repository:

CONFIG TYPE: “Git Repository”
SCM INTEGRATION: If a pre-existing SCM integration is selected here, the available selections in the “Repository” dropdown menu will be filtered to show only those associated with the chosen SCM integration
REPOSITORY: Select the repository in which your configuration resides
BRANCH OR TAG: The branch in which your configuration resides
WORKING PATH: The path to your configuration files
CONFIG: Your selected config file

Once finished, click COMPLETE.

Your new CloudFormation Blueprint is now saved and should be visible in the list of Blueprints. Blueprints are deployed in the Provisioning > Apps section of Morpheus. See the Apps section of Morpheus docs for more information on that process.

Kubernetes Blueprints¶

Morpheus allows you to store Kubernetes configuration YAML files for easy deployment on-demand. Kubernetes Blueprints can be built by pulling in Kubernetes spec stored as a Morpheus Spec Template object, those tracked under version control in a Git repository, or you can write them directly in the New Blueprint modal.

To create a new Kubernetes Blueprint, navigate to Provisioning > Blueprints. Click + ADD.

On the Name tab of the New Blueprint modal, enter a name for your new Blueprint. In the Type dropdown menu, select Kubernetes. NEXT

In the Cluster Summary section, complete the following fields as needed:

NAME: Enter a name for this Blueprint as it will appear in the Morpheus Blueprints list
DESCRIPTION: An optional description field for your Blueprint
CATEGORY: An optional category tag for your Blueprint, such as web, utility, or app
IMAGE: An optional image icon to more easily identify your Blueprint from a list. If no image is uploaded, a default image will be used

Complete the Kubernetes Configuration section as follows depending on your Config Type selection.

To consume a Morpheus Spec Template containing Kubernetes spec:

CONFIG TYPE: “Kubernetes Spec”
SPEC TEMPLATE: Use the typeahead field to locate the desired Spec Template

To draft or paste configuration directly in the New Blueprint modal:

CONFIG TYPE: “Kubernetes Yaml Spec”
CONFIG: Enter your YAML configuration template here

To consume YAML configuration files tracked in a Git repository:

CONFIG TYPE: “Git Repository”
SCM INTEGRATION: If a pre-existing SCM integration is selected here, the available selections in the “Repository” dropdown menu will be filtered to show only those associated with the chosen SCM integration
REPOSITORY: Select the repository in which your configuration resides
BRANCH OR TAG: The branch in which your configuration resides
WORKING PATH: The path to your configuration files
CONFIG: Your selected config file

Once finished, click COMPLETE.

Your new Kubernetes Blueprint is now saved and should be visible in the list of Blueprints. Blueprints are deployed in the Provisioning > Apps section of Morpheus. See the Apps section of Morpheus docs for more information on that process.

Helm Blueprints¶

If you’re using Helm Charts to manage Kubernetes applications, Morpheus allows you to bring them in from a Git repository as a Blueprint. The selected repository must be integrated with Morpheus before creating the Blueprint.

To create a new Helm Blueprint, navigate to Provisioning > Blueprints. Click + ADD.

On the Name tab of the New Blueprint modal, enter a name for your new Blueprint. In the Type dropdown menu, select Helm. Click guilabel:NEXT.

In the Blueprint Summary section, complete the following fields as needed:

NAME: Enter a name for this Blueprint as it will appear in the Morpheus Blueprints list
DESCRIPTION: An optional description field for your Blueprint
CATEGORY: An optional category tag for your Blueprint, such as web, utility, or app
IMAGE: An optional image icon to more easily identify your Blueprint from a list. If no image is uploaded, a default image will be used

In the Helm Configuration section, complete the following fields as needed to sync in configuration from a Git repository:

CONFIG TYPE: “Git Repository”
SCM INTEGRATION: If a pre-existing SCM integration is selected here, the available selections in the “Repository” dropdown menu will be filtered to show only those associated with the chosen SCM integration
REPOSITORY: Select the repository in which your configuration resides
BRANCH OR TAG: The branch in which your configuration resides
CHART PATH: The path to the folder within the repository containing your configuration files, enter “./” if this is the top level folder within the repository
CONFIG: Config files within your selected folder are displayed here for confirmation

Once finished, click COMPLETE.

Your new Helm Blueprint is now saved and should be visible in the list of Blueprints. Blueprints are deployed in the Provisioning > Apps section of Morpheus. See the Apps section of Morpheus docs for more information on that process.