Revision as of 16:50, 11 November 2013

Background

This page presents a work-in-progress design for the HOT software configuration feature. It should be seen as an evolution a previous hot-software-config proposal, but factoring in result of design discussion at the recent OpenStack summit in Hong Kong. This refined proposal is captured as a new wiki page for readability reasons. Once the design is finalized, we will consolidate the various wiki pages into a single one.

Discussions page: https://wiki.openstack.org/wiki/Talk:Heat/hot-software-config-WIP

Requirements

A number of requirements have been stated during design discussions, and they are also captures in the design summit etherpad. The most important ones to be addressed by this design proposal are summarized below again.

• Composability and re-use: It must be possible to define software components once and compose and re-use them in different contexts without duplicating definitions.
• Separation of component definitions and deployment: It must be possible to define multiple deployments of a software component, e.g. a software component defined once must be able to be deployed on different servers in a template.
• Software components as stateful entities: It must be possible to track state of software components, i.e. whether a software deployment is in progress, has completed, or has failed. It must be possible to retrieve outputs (attributes) of software components.
• Ability to express dependencies between software components: It must be possible to define dependencies between software component, e.g. that input for one component is obtained from output of another component.

High level overview

The following figure shows a high level overview of the design idea. Software components are defined in a separate file that can be referenced from templates that want to make use of the respective software component definition. The component definition defines inputs (configurable parameters) and outputs of the software component, it points to the automation like Chef, Puppet or scripts for doing the actual software configuration, and it includes specifics for the respective automation being used (e.g. chef specific parameters).

A "Software Deployment" resource in a HOT template represents one specific use of the software component, i.e. a concrete deployment on a server. There can be multiple deployments of the same software component, e.g. on two servers, which would be modeled as two separate software deployment resources.

Software Deployment modeling in a HOT template

One concrete deployment of a software component (i.e. one instance of the software installed at runtime) is modeled in a HOT template as one resource which points to the software component definition and defines the data flow (inputs as properties, outputs as attributes references from other parts of the template) in the context of the template. The resource fuirther has a reference to the server on which the software gets installed.

heat_template_version: 2013-05-23

resources:
  mysql:
    type: My::Software::MySQL
    properties:
      server: { get_resource: db_server }
      params:
        db_name: { get_param: db_name }
        db_user: { get_param: db_user }
        db_pw: { get_param: db_pw }

  db_server:
    type: OS::Nova::Server
    properties:
      image: F19-x86_64-cfntools
      flavor: m1.small

The mysql resource in the snippet above is of type My::Software::MySQL (which is an arbitrary resource type) and represents a deployment of MySQL on a server. By means of an environment resource mapping, that type name gets bound to a concrete software component definition (see below). The server property is a reference to the server on which the software will be installed. The server itself is modeled as the db_server resource in the template.

The advantage of using an environment mapping of the resource type name of the mysql resource is that the template itself does not point to one concrete software component definition in a hardcoded fashion, but that alternative definitions can be used thru the respective environment mapping as long as they have the same signature (inputs and outputs). For example, this would allow for having one component definition that will work on F19 images and another one that will work on Ubuntu images. Another example is that the current provider template resource implementation can be used (probably without any changes).

Design alternative

As an alternative, we could implement generic SoftwareDeployment resource type (OS::Heat::SoftwareDeployment) and let it point to the software component definition via a property, e.g. a component property:

resources:
  mysql:
    type: OS::Heat::SoftwareDeployment
    properties:
      component: http://www.example.com/hot/components/MySQL.yaml
      server: { get_resource: db_server }
      params:
        # ...

The referenced component definition (MySQL.yaml in the example above) is like a nested template, but the SoftwareDeployment resource could implement specific code (to be defined) that is not necessary in the generic provide template resource.

Pros: more obvious modeling of a "software deployment"; ability to have special code in the SoftwareDeployment resource

Cons: pretty close to provide template concept, but not really the same (which could be confusing); hardcoded pointer to one specific software component definition, which requires change to the template for pointing to an alternative definition.

Software component definition

The definition of a software component, i.e. its inputs, outputs, pointer to the actual automation for deploying the software etc. is provided as a separate template file that uses the exact same syntax as any other HOT template file. For example, the template below would contain the definition of the MySQL component used in the snippets shown earlier.

heat_template_version: 2013-05-23

description: >
  This template contains the definition of the MySQL software component.
  It defines configuration parameters (inputs), outputs, and links to the actual automation.

parameters:
  server:
    description: The server onto which to deploy the MySQL software component.
    type: string
  db_name:
    description: The name of the database to be created.
    type: string
    constraints:
      - length: { min: 6, max: 10 }
        description: DB name must be between 6 and 10 characters.
  db_user:
    description: The username for the DB admin user.
    type: string
  db_pw:
    description: The password for the DB admin user.
    type: string
    hidden: true

resources:
  mysql:
    type: OS::Heat::ChefSoftwareComponent
    properties:
      server: { get_param: server }
      cookbook: http://www.example.com/hot/chef/mysql.zip
      params:
        db_name: { get_param: db_name }
        db_user: { get_param: db_user }
        db_pw: { get_param: db_pw }

outputs:
  mysql_port:
    description: The port assigned to the MySQL database.
    value: { get_attr: [ mysql, port ] }

The parameters sections define any input parameters that should be configurable by the user of this component definition such as the database name in the example above. By convention, software component definitions will always define a server property to allow the server on which to install the software be specified by the user.

The mysql resource contains the definition of who MySQL gets installed. The type OS::Heat:ChefSoftwareComponent indicates that installation will be done using chef. The assumption is that we will have a set of "adapters" for commonly used software configuration tools as resource plugins to Heat, for example for Chef, Puppet, scripts etc. We can probably have a base class that implements generic behavior such as interpretation of the server property to do bootstrapping actions. Specific adapter resources can then inherit common behavior and we have some extension point for adding custom adapter resources.

Software component inputs

By means of the parameters section, the component author can clearly define, what input the software component requires or allows, also leveraging constraints for inputs. It defines the properties schema of the "software deployment" resource in the actual template (see earlier). Thus it is possible to make sure the input actually maps the actually used implementation (e.g. the used chef cookbook). All the code for supporting this already exists (provide template resource etc.), the syntax is described for HOT, so we do not have to do anything for leveraging this feature.

Software component outputs

The outputs section declares what data the software deployment produces that can be used in other parts of the template, e.g. as input for other software components. For example, the port assigned to the MySQL database by the underlying Chef automation can be returned so that an application can bind to it. The code for mapping outputs as attributes of a provider resource again already exists in the provider template resource, and the syntax is document thru the HOT specification.

Software config resource

The actual software config resource (mysql resource in the example above) makes use of generic implementations to adapt to a given software config tool (e.g. Chef). The responsibility of such resource implementations is to:

• perform bootstrapping of the respective software config tool on the server provided thru the server property
• invoke the respective software config tool, passing to it all the additional parameters in the params sub-section of the properties section (data type of the params section in the properties schema would be a map.
• wait for completion of the invoked automation
• collect return values and provide them as attributes of the software deployment resource
• signal completion of the software configuration task so that dependent deployment steps can be started

Note that since the software config resource (mysql resource in example above) is just like any other resource, it could also be directly used in a HOT template without having to define a software component definition in a separate template file. You would lose aspects like re-use of component definition, lose coupling to a concrete implementation etc. in this case, though.

Composite software components

Since a software component definition as described in the previous section is just a regular HOT template, it is easy to also define composite software components that include multiple, potentially dependent modules that look from the outside like a single software components. Inputs to the composite software component (via the parameters section of the software component template file) can be distributed to properties of internal components.

Data flow between software deployments

Since software deployments (uses of software components in a concrete template) are modeled as normal Heat resources, any mechanism for passing data between resources that works for Heat resources today will work for passing data between software components should just work.

Inputs to software deployments can be provided by setting properties of the "software deployment" resources in a template.

Outputs from software deployments can be read by means of the get_attr intrinsic function.

Dependencies between software deployments

There are two ways for declaring dependencies between software deployments: data flow based and explicit definition.

Data flow based

A data flow based dependency between two software deployments exists, when a property (input) of one software deployment is obtained from an attribute (output) of another software deployment. A dependency between the two "software deployment" resources is enforced by the Heat engine implicitly. For example

resources:
  wordpress:
    type:  My::Software::Wordpress
    properties:
      server: { get_resource: web_server }
      params:
        wp_admin_user: { get_param: wp_admin_user }
        wp_admin_pw: { get_param: wp_admin_pw }
        mysql_host: { get_attr: [ db_server, first_address ] }
        mysql_port: { get_attr: [ msql, port ] }

  mysql:
    type: My::Software::MySQL
    properties:
      server: { get_resource: db_server }
      params:
        db_name: { get_param: db_name }
        db_user: { get_param: db_user }
        db_pw: { get_param: db_pw }

would introduce a dependency from wordpress to mysql since two of the properties of wordpress are set using the get_attr function refering to attributes of the mysql resource. As a result, resource mysql must be in state CREATE_COMPLETE before processing of resource wordpress starts.

Explicit dependency

If no data dependency exists, but there is still a timing dependency (e.g. a process must be up before a client can connect to it), a mechanism for declaring an explicit dependency is required. This can be solved by giving each software deployment a depends_on property which is a list of resource IDs of other resources that a software deployment depends on, for example:

resources:
  client:
    type: My::Software::SomeClient
    properties:
      server: { get_resource: my_server }
      depends_on:
        - get_resource: server_process1
        - get_resource: server_process2
      params:
        # params ...

  server_process1:
    type: My::Software::SomeServer
    properties:
      server: { get_resource: my_server }
      params:
        # params ...

  server_process2:
    type: My::Software::SomeOtherServer
    properties:
      server: { get_resource: my_server }
      params:
        # params ...

In the example above, client would depend on both server_process1 and server_process2 to be completed.

Implemenation considerations

This section is still very much in progress, but more or less a collection of some thoughts for now.

Bootstrapping of software configuration tools could be done using cloud-init. The software configuration resource implementation will have to inject the respective metadata into the server resource definition on which it is hosted.

Implementations like os-collection-config etc. could be used for collecting software config metadata etc.

For synchronization purposed (e.g. in case of an explicit dependency), existing mechanisms (e.g. WaitCondition signaling) could be used under the covers, however, without surfacing them in templates.