TripleO/TuskarJunoPlanning/TemplateBackend

= Overview =

The purpose of this page is to describe a change in architecture to use Heat templates and environments as the data store for Tuskar.

This design assumes the following:


 * completion of the Juno changes to the TripleO Heat templates to use provider resources.
 * images are created outside of Tuskar

= Format =

There are two main types of information that are needed when configuring an overcloud:
 * The selection and count of what services will be run in the cloud.
 * The configuration for those services.

The Icehouse release for Tuskar uses a database to store both pieces of information. For Juno, the goal is to move that information directly into the Heat templates themselves. This will be accomplished using two recently added features of Heat: provider resources and environments. Provider resources allow for fine-grained stacks to be defined and built up into a larger Heat stack. Environments are a way to capture the selection of which provider resources to use and their configuration values.

Using these features, Tuskar will be able to choose a subset of the TripleO Heat templates to include in the overcloud. Those templates remain static and unedited by Tuskar. Tuskar is then responsible for generating the overall cloud template that includes each of the provider resources and the environment file for saving the configuration.

The following series of diagrams shows the relationships between the provider resource templates and the Tuskar-generated files that will use them for configuring a cloud. Note: Discussion on where these files are stored is elsewhere on this page; what follows is a description of the interplay between the TripleO templates and the Tuskar-generated files.

Step 1: Create a Cloud


When a cloud is initially created in Tuskar, it is comprised of two files: the deployment plan which is the overarching Heat template that configures the cloud's stack and the environment file which contains the provider resource mappings and cloud's configuration values. Note: The names of these files as depicted in the diagram are not final.

The files listed on the left are provider resource templates from TripleO. They are not edited by Tuskar and are used as building blocks for the cloud's stack.

Step 2: Select Roles


The Icehouse release of Tuskar uses the term "role" to describe an individual function of the cloud. For the purposes of this discussion, they are considered to map 1:1 with provider resource template files. Note: This is likely not 100% accurate but is a sufficient abstraction for now.

In the diagram above, the user has selected both alpha and beta for inclusion in the cloud. At this point, Tuskar makes the following changes to its generated files:
 * A reference to the template file is added to the environment. The example simply names them X and Y; a better naming scheme will be determined in the future. More details on what this reference looks like are discussed below.
 * A resource for each provider resource is added to the plan template.

Step 3: Configuration Consolidation


The plan template needs to expose the configurable parameters of each provider resource. The example in the diagram is intentionally simplistic; there is no overlap in parameter names between provider resources. Resolving conflicts is potentially complicated. There are a few scenarios to consider:
 * The same value should be used across multiple resources. For instance, if both alpha and beta expose a value called "key_name" for the SSH keypair and the same keypair should be used for each resource.
 * Multiple provider resources use the same name for a parameter but will need separate values. For instance, if alpha and beta both simply use "image_id", however the likely usage is that they will be created from different images.
 * A single provider resource, used multiple times and configured differently in each case. For instance, two uses of the provider resource that use a different flavor.

Further discussion on possible solutions can be found in the Open Questions section.

Step 4: Configuration Mapping


In addition to consolidating the configurable parameters, the generated plan template needs to map the parameters to the appropriate resources. How much work needs to be done here is contingent on how the consolidation takes place in step 3. If there is a renaming of the values, they will need to be properly mapped here. If the names are taken directly from the provider resource templates, this step can be omitted as Heat will automatically pass the parameters in a parent stack to its nested stacks.

Summary


The diagram above is a summary of the steps necessary for Tuskar to generate an environment and overall plan for a cloud.

= Storage =

Provider Resource Templates
There are two approaches being discussed with regard to how to store the provider templates and their inclusion in a deployment plan. Keep in mind that provider resource templates refers to both the TripleO Heat templates as well as any custom Heat templates uploaded by a user.

The approaches that follow are conceptual. Notes on particular implementations will be provided, but the purpose of the following sections is to focus on the desired approach. Tuskar should be written that the actual implementation backend be pluggable to support integration with existing processes (for instance, the ability to use a git-based backend for CI systems).

When considering these approaches, the following use cases should be taken into account:
 * Initial creation of the cloud and selection of which provider resources to include
 * Making changes to a provider resource template (either by the user or through an upgrade of Tuskar) and how those changes are propagated
 * Migrating changes from one cloud to another, such as in a promotion workflow (e.g. testing in a development cloud and then migrating the new templates to a QE cloud)

In both cases, the deployment plan constitutes multiple files (at very least, an environment file and an overall Heat template). Where and how that directory of files is stored should be comparable for both of these approaches.

Referenced


This approach focuses around a global repository of hosted provider resource templates. Each template is immutable and versioned, which allows templates to be changed but the changes not made live in the clouds until the user explicitly wishes them to be.

The environment file references a specific provider template (including its version) in the resource_registry section. The simplest solution is for Tuskar to use the Heat client libraries for making stack requests, which currently support HTTP URLs.

One of the drawbacks to using strict version numbering is that Heat templates do not have the concept of a version. One approach is to assume the version information is in the URL for the referenced template.

Pros:
 * Strong notion of template versioning and accountability for changes
 * Easy mechanism for determining the differences between two templates (for example, in the event that a template is changed globally and we need to see which clouds would be affected)

Cons:
 * Places more requirements on the storage backend, such as the ability to expose multiple versions of a template with unique, static URLs
 * Long term will likely need APIs for culling old versions that takes into account if they are in use

Copied


This approach stores the entire contents of the deployment plan together. When the user elects to include a provider resource in a cloud, a copy is made of the template and placed in the plan. Changes can then be made on a per cloud basis.

Pros:
 * Less overhead involved in making custom changes for a particular cloud; no need for a new version, the changes are made directly in the cloud
 * Simpler workflow around deleting the original provider templates

Cons:
 * More complicated to determine the difference between two provider templates

Deployment Plan
As previous stated, the deployment plan consists of multiple files. Again, Tuskar should be written in such a way that the backend storage for these files is configurable.

= Tuskar APIs =

Below are some thoughts on the behavior of the Tuskar APIs. The intent is not to be full fledged REST API documentation (however the grouping of the calls is similar to how REST APIs would be structured) but rather a conceptual discussion of what each call's implementation needs to take into consideration.

Cloud Collection
Example URL:

Create: Creates a new cloud to be managed by Tuskar. This will create the empty environment and plan templates, as well as creating the empty stack in Heat.

List: Returns a list of all defined clouds. The format of what is returned needs to be determined and may be as simple as a list of names or enhanced include its current configuration.

Individual Cloud
Example URL:

Get: Retrieve the full details of the specified cloud. The format of what is returned need s to be determined, but should at least include a list of all of the roles (and their versions) and the full list of configuration values for the cloud.

Update: Adds/removes/changes values for the configuration parameters found in the environment file. This should not trigger a call to update Heat, allowing the user to stage and review multiple changes before making them live.

Delete: Deletes the given cloud's deployment plan from Tuskar and the corresponding stack in Heat.

Deploy: Trigger the current state of the cloud to be deployed/updated in Heat. Note: This is another case where the APIs are more conceptual than literal; from a REST point of view we'll need to figure out the right approach.

Cloud Roles Collection
Example URL:

Create: Adds an entry for the role to the cloud's environment file and consolidates the stack's configuration parameters. Additional steps may be taken depending on the storage model discussion above.

List: Return a list of role names, versions, and UUIDs that are present in the cloud.

Individual Cloud Role
Example URL:

Delete: Removes the given role from the specified cloud. The configuration parameter consolidation will need to occur to remove the role's parameters from both the overall template and the parameter values in the environment file.

Roles
Example URL:

List: List the names and versions of all roles known to Tuskar.

''Note: Create/Update/Delete: Future functionality for managing custom roles. For the immediate future, a Tuskar installation step will take care of getting the TripleO templates in the correct location.''

Individual Role
Example URL:

Get: Retrieve details of the specific role. This can either be the template directly or a parsed version that simply describes it's possible configuration parameters.

= Open Questions =

Post-install Configuration Steps
The biggest problem with this approach is that not everything is done in the Heat templates themselves. For TripleO specifically, the os-cloud-config project exists to perform these post-Heat configuration of the cloud. In working with purely the provider resource templates, these steps are not represented.

Parameter Consolidation
This was touched on earlier, but there are a number of things that need to be taken into account when arbitrarily selecting provider resources:
 * In the event that two provider resources request the same parameter, there is a question of whether or not it should be the same across the stack or unique for each resource.
 * There needs to be a mechanism for differentiating between two provider resources that define the same parameter. This should also take into consideration the possibility of using the same provider resource multiple times in a stack. For instance, having multiple the same resource deployed with different flavors.
 * This mechanism should provide some form of UI clue as to their grouping/relationship.

Other Cloud Data
The deployment plan already consists of two files: the environment and the overall Heat template. Since Tuskar is already storing a directory of files for a given cloud, it would be simple to add a Tuskar-specific file that contains extra information. This may be necessary for Tuskar to track a dirty bit that indicates if any changes have been made to the cloud but not yet sent to Heat to be made live.

Display Name
A minor issue surrounds the fact that Heat templates have a description but no user-frienedly name. When displaying a list of possible roles to select, there is currently no simple way to present a user-friendly list.