Installing and Working Offline with Cloudify 3.4

This guide has recently been updated. To find the latest version, in PDF format, click this link to download.

The expression “working offline”, when it comes to Cloudify, refers to the practice of installing and configuring Cloudify Manager in a self-contained manner; that is, all resources required by Cloudify Manager — ranging from the bootstrap process to workflow execution — are contained within the Cloudify Manager, rather than being retrieved from any other source, be it an internal network or (more commonly) the public network.

Why Work Offline?

Having a Cloudify topology work offline bears with it, first and foremost, the benefits of stability and security. Consider that access to any network — especially the public network — embodies a certain level of risk. For example, if Cloudify Manager requires access to the public network for the purpose of downloading YAML files (or plugin packages), then outbound access to the public network needs to be allowed. For certain organizations, such access is strictly prohibited, be it at the corporate level or, at times, even legally; for other organizations, providing access to the public network raises audit compliance issues (which may or may not be eventually accepted). Regardless, though, providing outbound access to the public network can always be perceived as an added security concern, which should (or must, depending on the circumstances) be avoided.

Register today for our live Open vCPE Webinar on Feb 16!  Go

The Bootstrap Process

The bootstrap process involves using the Cloudify CLI to install a manager blueprint. Behind the scenes, the CLI runs in what’s called “local mode” (AKA “cfy local“), installing a manager blueprint in much the same way that a Cloudify Manager runs the install workflow on any application blueprint. There is nothing special about a manager blueprint from that perspective.
The bootstrap process in Cloudify 3.4 has a few online prerequisites:

Let’s look at how to prepare the bootstrap client machine (that is, the machine where the bootstrap process is executing from; for brevity, we will refer to it as the CLI machine), and the target Cloudify Manager VM, so the bootstrap process can be be performed completely offline.

Setting Up the Bootstrap Client Machine (the CLI Machine)

YAML Files Imported by Manager Blueprint

1. Take note of all externally-available YAML files’ URLs imported by the manager blueprint, transitively (that is: YAML files which are imported directly or indirectly by the manager blueprint).

2. Look at the YAML files’ URL’s and aggregate them based on common URL prefixes, trying to minimize the number of groups. For example, consider the following list of URLs:

You can easily notice that the most economical way of aggregating them would be as follows:

(Usually, grouping per domain name would be the best way to go)

3. Download all YAML files into the CLI machine. The files need to be laid out in a directory hierarchy, which will make it feasible to later write Import Resolver rules for them. This can be done in the following manner:
   1. For each group concluded in the previous step, create a separate directory on the CLI machine. Continuing the aforementioned example, you could create the following directories:
      1. /tmp/yaml/cloudify
      2. /tmp/yaml/some-site
   2. Place YAML files into these directories, each file located relatively to the root with accordance to the original YAML URL. Example:
   3. 1. /tmp/yaml/cloudify/spec/cloudify/3.4.1/types.yaml
      2. /tmp/yaml/cloudify/spec/fabric-plugin/1.4.1/plugin.yaml
      3. /tmp/yaml/some-site/some-path/plugin.yaml
      4. /tmp/yaml/some-site/some-other-path/plugin.yaml

4. Follow the documentation for writing Import Resolver rules, in the directory from which you are going to invoke the bootstrap process. For example, if — on the CLI machine — you are going to run the bootstrap process from /home/isaac/cfy/boot:

— and then add the Import Resolver rules as necessary. For the example above:

By following the steps above, you make sure that the Cloudify DSL parser is able to read all imported YAML files by using its Import Resolver, without accessing the external network.

DSL Resources

The dsl_resources manager blueprint input is a useful mechanism for uploading arbitrary files to the Cloudify Manager machine. Most typically, it is used to upload YAML files, so they become available for serving by the Cloudify Manager itself, through Import Resolver rules.

DSL resources, uploaded to the Cloudify Manager machine during the bootstrap process, are always — without exception — uploaded to a path which is relative to /opt/manager/resources.
The default value of the dsl_resources input handles the following YAML files:

• The Cloudify global types file (

types.yaml

• )

• The plugin.yaml file of the following plugins:
  • Fabric
  • Diamond
• For a manager blueprint that is IaaS-specific (note: these will be removed in Cloudify 4.0): the plugin.yaml file of the Cloudify plugin that corresponds to the IaaS being used (the simple manager blueprint uploads the plugin.yaml files of all IaaS plugins)

You may, of course, add entries to the dsl_resources input. However, you must make sure that all resources denoted by source_path are available to the CLI machine at the time of bootstrap.

Manager-Side Import Resolver Rules

By default, the Cloudify DSL parser at the Cloudify Manager side is configured with a single Import Resolver rule:
http://www.getcloudify.org/spec file:///opt/manager/resources/spec
This single rule, combined with the value of the dsl_resources input, is sufficient to serve all out-of-the-box Cloudify YAML files offline. If you have your own YAML files which are uploaded to the manager (either via the dsl_resources input, or manually after bootstrap), you will need to update the Import Resolver rules accordingly.

Plugin Packages

The bootstrap process itself, orchestrated by the CLI, requires access to the code of each and every plugin referred-to by the manager blueprint.
Typically, the –install-plugins switch takes care of that. When specified, the “source” value of each “plugin” declaration included in the manager blueprint, is retrieved and then installed (using “pip install” semantics) on the active Python virtual environment (virtualenv). If the plugin’s source has dependencies, these dependencies are downloaded and installed as well (again, through pip‘s own dependency resolution mechanism).
However, in an offline environment, or an environment where access to the public network is limited, –install-plugins may not be applicable. To make it applicable:

• Out-of-the-box YAML files (such as plugin.yaml files for Cloudify’s official plugins) would need to be edited so the source field points to an accessible location.
• If the plugin package has dependencies, those dependencies would have to exist in a pip mirror which is accessible to the CLI machine (and, of course, the local pip configuration would have to be modified to search the mirror instead of the official pip site).

While possible, this approach is not recommended. Doing so requires system administrators to modify out-of-the-box YAML files, as well as set up a local pip mirror — both pose an administration overhead.
Instead, if –install-plugins is not applicable, the recommended approach is to pre-install plugin packages on the CLI’s virtualenv, and avoid specifying that switch in the command-line:

• Download each plugin package to the CLI machine (follow the source field)
• Download all dependencies for all plugin packages
• Install all dependencies and plugin packages on the CLI’s virtualenv

Cloudify Manager Resources Package

During the bootstrap process, the Cloudify Manager Resources Package (located where the manager_resources_package input points to) is downloaded into the manager’s machine. The download is initiated from within the manager’s machine; therefore, the URL specified by manager_resources_package must be accessible from there.
By default, manager_resources_package points to Cloudify’s S3 bucket, which exists on the public network. If the manager’s machine has n access to the public network, you’ll need to download the manager resources package and host it in an accessible location.

Post-Bootstrap Adjustments

Offline Plugins

During deployment creation, Cloudify retrieves the code for each plugin used by the deployment. The retrieval algorithm works as follows:

• If the plugin definition contains package_name and package_version:
  • Conclude the operating system distribution and version, for the machine on which the operation is currently being run (the manager’s machine if the operation’s executor is central_deployment_agent, or the agent machine if the executor is host_agent).
  • Look up an offline plugin package (also called “Wagon”) that satisfies the package_name, package_version and the OS distribution/version in question.
  • If a match is found, obtain the plugin’s source from the Wagon and exit.
• Obtain the plugin’s code from the URL denoted by the source key.
• Install the plugin’s code using pip.

Therefore, in order to make the Cloudify installation self-contained, it is required to upload Wagons to the Cloudify Manager.

Cloudify’s official plugins are provided as Wagons for various distributions and versions (except for plugins that typically run on the Cloudify Manager machine, in which case, only RHEL 7.x / CentOS 7.x Wagons are provided). For custom plugins, you can use the Wagon tool to create a Wagon files. Wagon files can then be uploaded to the Cloudify Manager instance using the command-line interface or the REST API.

Summary

As demonstrated, “working offline” with Cloudify requires certain additional effort to the Cloudify Manager setup process depending on the level of separation required from the public networks (or any network, including internal ones). However, when weighed against the benefits involved in running with a self-contained Cloudify Manager, the scale clearly tips towards working offline, especially in mission-critical Cloudify Manager installations. The feedback we receive from our customers is pretty much unanimous: working offline helped reduce outages borne out of network instabilities impacting access to online resources, which is why we recommend this approach to our customers.