Nutanix.dev

Nutanix Calm DSL – Brownfield Apps the Easy Way

Nutanix.dev-NutanixCalmDSLnBrownfieldAppstheEasyWa

Table of Contents

With Nutanix Cloud Manager (NCM) Self-Service you can create an app using either one or several running VMs and an existing blueprint. Formerly known as Calm, NCM Self-Service also offers a simple, API-driven method for creating apps using the Nutanix Calm Domain Specific Language (DSL). In this article, we walk through creating brownfield apps manually using the NCM Self-Service UI and how to automate this process with the Nutanix Calm DSL.

Brownfield Apps with NCM Self-Service

With NCM Self-Service, you can create a new application without deploying it by itself, which is useful  in a few scenarios:

  • You have an existing app outside of NCM Self-Service, and you want to manage it through the Self-Service dashboard in the same way as your other apps.
  • You already have an automation chain to create apps, but you cannot migrate it to NCM Self-Service, and you want to use Self-Service as both an app dashboard and a day-2 operations entry point.

Instructions

To create a brownfield app with the NCM Self-Service UI, navigate to the Brownfield Application tab on the Applications page.

Brownfield Applications Tab

Click Create Brownfield Application to launch a multi-VM blueprint editor.

Multi-VM Blueprint Editor

You can edit your blueprint just like a “classic” Self-Service blueprint by adding services, day-2 operations, credentials, variables, and so on. The only difference is that, when you add a service, the VM properties section shows slightly different options:

  • By selecting Greenfield, you can request a fresh VM the same way as a classic Self-Service blueprint.
  • By selecting Brownfield, you can select which existing, unmanaged VMs you want to include in the blueprint.
VM Properties: Greenfield or Brownfield Option
Brownfield VM Properties

It’s best to use the Brownfield feature  for a small number of apps. Because manual blueprint creation can become a time-consuming task, it’s not intended for use at large scale..

Brownfield Apps with the Nutanix Calm DSL

In this section, we complete the same process described in the previous section but with the help of the Nutanix Calm DSL instead of the NCM Self-Service UI.

About the Nutanix Calm DSL

The Nutanix Calm DSL provides simple NCM Self-Service asset manipulation from the command line. See the Nutanix Calm DSL homepage for an introduction, including technical articles and labs.

Important things to know about the Nutanix Calm DSL:

  • You can install the Calm DSL on Linux, Windows, or as a container.
  • We based the Calm DSL’s specs on Python 3.
  • The Calm DSL is the best way to do CI/CD with NCM Self-Service.

Prerequisites

Before continuing, you must have:

  • A blueprint corresponding to the app you want to create
    • You can use the blueprint used to create a greenfield application. In this case, be aware that the blueprint’s “Package install” action and “Create” tasks are applied on your imported VM.
  • A VM or container with the Nutanix Calm DSL installed and fully functional
  • One or multiple unmanaged VMs and their IP addresses (or FQDNs) to be used for the brownfield app

Instructions

Completing the following steps associates a blueprint with an existing, unmanaged VM. This high-level process includes creating a Python script to define how to associate the VM to an app’s services and then launching the app.

Get Blueprint Details

On the machine or within the container running the Nutanix Calm DSL, run the following command to get the existing greenfield blueprint’s details:

calm describe bp <name of your BP>

The following screenshot shows an example of this command’s output.

Get Blueprint Details Command Output

You can find each deployment’s name and details in the “Deployments” section of the output. These names are required in the next section, so take note of them now.

Create the Brownfield App Python File

This part of the procedure creates the Python file that associates the VM to the blueprint’s services. The following script sample demonstrates the Nutanix Calm DSL importing a unique VM under a brownfield application:

Import a unique VM under a brownfield application

Here is how the script works:

  • Lines 1 and 2 import the required Python modules.
  • Line 4 defines a string variable containing the instance’s IP address.
    • This variable could be read from an external file, which is considered best practice for automating brownfield app creation.
  • Line 7 creates the class that defines how to replace your service in the blueprint.
    • You can give this class any name. In our example, we used the deployment name prefixed with an underscore to keep our code standards compliant with Python best practices.
  • Line 9 uses the deployment name noted in the previous section and defines which service attaches to the imported VM.
  • Lines 10–12 define the VM to host this service.
    • Note that line 11 uses the IP address string variable created earlier.

If you have a blueprint with several services, you need to repeat lines 7–12  as many times as the number of services. Make sure to update the class name (shown on line 7) and the deployment name (shown on line 9) for each service you plan to import.

Launch Brownfield Application

When you’re ready to launch the brownfield app creation, run the following command:

calm launch bp -a <APPNAME> -b <brownfield python script> <BPNAME> -i

This command creates the app with the name <APPNAME>, using the blueprint <BPNAME> and the existing VM targeted in the brownfield Python script. The -i parameter forces predefined variable values, leaving the credentials and other variables defined in the blueprint unchanged.

Notes and Limitations

Services with VM Replicas

The Nutanix Calm DSL does not currently support blueprint import of multiple VM replicas in the same service.

Package Install

During brownfield app creation with the Calm DSL, package install tasks owned by the blueprint are applied. Use caution to ensure unintended actions are only applied to VMs that require them. We recommend choosing one of the courses of action:

  1. Use dedicated blueprints without package install tasks.
  2. Add tests at the beginning of the “Package Install” tasks to check if the VM is new  or if it is an imported brownfield VM.

Conclusion

Possible use cases for updating an app using this process include:

  • Update your blueprint to add new or day-2 operations.
  • Soft-delete your existing app created with a previous version of the blueprint, resulting in a VM no longer being managed by NCM Self-Service.
  • Create a brownfield app with the Nutanix Calm DSL, allowing a previously unmanaged VM to use the newly created day-2 operations.

We hope this article provides useful information for both new and existing users of NCM Self-Service and the Calm DSL.

© 2024 Nutanix, Inc. All rights reserved. Nutanix, the Nutanix logo and all Nutanix product, feature and service names mentioned herein are registered trademarks or trademarks of Nutanix, Inc. in the United States and other countries. Other brand names mentioned herein are for identification purposes only and may be the trademarks of their respective holder(s). This post may contain links to external websites that are not part of Nutanix.com. Nutanix does not control these sites and disclaims all responsibility for the content or accuracy of any external site. Our decision to link to an external site should not be considered an endorsement of any content on such a site. Certain information contained in this post may relate to or be based on studies, publications, surveys and other data obtained from third-party sources and our own internal estimates and research. While we believe these third-party studies, publications, surveys and other data are reliable as of the date of this post, they have not independently verified, and we make no representation as to the adequacy, fairness, accuracy, or completeness of any information obtained from third-party sources.