Difference between revisions of "Heat/Blueprints/hot-software-config-spec"
(Fixed nesting of depends_on which should be at the same level as properties, not inside properties.) |
|||
Line 16: | Line 16: | ||
= High level overview = | = High level overview = | ||
− | + | Re-usable software components are modeled as <code>SoftwareConfig</code> resources. Those SoftwareConfig definitions point to the actual automation to later perform software configuration (e.g. Chef, Puppet, scripts, ...) and they provide the metadata that is necessary for a generic <code>SoftwareDeployment</code> resource to deploy a given software on a server. The <code>SoftwareDeployment</code> resource represents one incarnation, i.e. one concrete use, of a software component in a template. It provide specific input parameters for that deployment, it will provide outputs produced by that deployment, and most importantly it maps the deployment to a specific target server. | |
− | + | It is assumed that there will be different pluggable implementations for <code>SoftwareConfig</code> and <code>SoftwareDeployment</code> - one per backend configuration tool like Chef, Puppet, scripting etc. - since each configuration tool will have specific requirements on metadata and runtime implementation. | |
− | [[File:HOT-software-config- | + | The following figure shows those concepts based on a Wordpress example. Assume that there are Chef cookbooks for configuring the Wordpress application and MySQL. Those are referenced by two <code>SoftwareConfig</code> resources, along with the respective metadata for each automtion. The automation plus the corresponding SoftwareConfig definitions are the re-usable entities; they are not mapped to any concrete deployment target, and they do not define specific input values. There is one <code>SoftwareDeployment</code> resource for MySQL and one for Wordpress, each mapping the deployment to a separate server. A data dependency exists between the Wordpress deployment and the MySQL deployment (see also snippets later on this page) to get endpoint information about the MySQL database for configuring the Worpress application. |
+ | [[File:HOT-software-config-overview2.png|400px|none|center]] | ||
+ | For simple template, it is possible to define all elements (SoftwareConfig, SoftwareDeployment and other base resources) in one template file. For more complex scenarios, and to increase composability, a subset of resources can be split into separate provider templates that can be bound via environments. This is explained in more detail and with example snippets in section [[Heat/Blueprints/hot-software-config-WIP#Provider_Templates|Provider Templates]]. | ||
− | |||
− | |||
− | + | = Software Configs = | |
− | + | <code>SoftwareConfig</code> resources contain definition of metadata for automation like Chef cookbooks, scripts, etc. along with a reference to the actual automation. Once defined, they can be mapped to one or more deployment targets (servers) by means of <code>ServerDeployment</code> resources (see [[Heat/Blueprints/hot-software-config-WIP#Software_Deployments|Software Deployments]]). SoftwareConfig definitions are specific to the used software configuration tool, since they provide tool specific metadata. The following example shows a snippet for a Chef Software Config resource (the complete example is given in section [[Heat/Blueprints/hot-software-config-WIP#Wordpress_all_in_one_Example|Wordpress all-in-one Example]]): | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
resources: | resources: | ||
− | + | wordpress_sw_config: | |
− | type: OS::Heat:: | + | type: OS::Heat::SoftwareConfig::Chef |
properties: | properties: | ||
− | + | cookbook: http://www.example.com/hot/chef/wordpress.zip | |
− | + | role: wordpress | |
− | + | # parameters that the chef role(s) need | |
− | # ... | + | parameters: |
+ | wp_admin_user: | ||
+ | type: string | ||
+ | mapping: wordpress/admin_user | ||
+ | wp_admin_pw: | ||
+ | type: string | ||
+ | mapping: wordpress/admin_password | ||
+ | db_endpoint_url: | ||
+ | type: string | ||
+ | mapping: wordpress/db_url | ||
+ | # more input parameters ... | ||
+ | # output data that the chef automation produces | ||
+ | outputs: | ||
+ | wp_url: | ||
+ | type: string | ||
+ | mapping: wordpress/url | ||
− | The | + | The resource type <code>OS::Heat::SoftwareConfig::Chef</code> indicates that this is a Chef-specific software config definition. The <code>cookbook</code> property points to the used Chef cookbook, and the <code>role</code> property points to the role to set up via this software config. The <code>parameters</code> section contains the definition of parameters that have to be passed to Chef for configuring the role. Parameters are defined in terms of name and type. In addition, a <code>mapping</code> specifies to which role attribute the respective input parameters needs to be assigned. |
− | + | The <code>outputs</code> section defines attributes that can be retrieved once the software deployment at runtime has completed. Those values will be available as attributes of the corresponding <code>SoftwareDeployment</code> resource at runtime (see also [[Heat/Blueprints/hot-software-config-WIP#Software_Deployments|Software Deployments]]). | |
− | |||
+ | = Software Deployments = | ||
+ | A <code>SoftwareDeployment</code> resource represents one concrete use of a piece of software (defined via a <code>SoftwareConfig</code> resource) in a template. It points to the SoftwareConfig that shall be applied to a deployment target, and it points to the actual deployment target (server). As with SoftwareConfig, it is assumed that SoftwareDeployment implementations will be specific to the used software configuration tools, since tool specific steps will have to be performed at runtime. | ||
− | + | The following example show a SoftwareDeployment definition for the Wordpress component defined earlier using Chef. For brevity, definitions of overall template parameters, outputs or other resources have been left out - please refer to section [[Heat/Blueprints/hot-software-config-WIP#Wordpress_all_in_one_Example|Wordpress all-in-one Example]] for the complete example: | |
− | The definition | ||
− | + | resources: | |
+ | wordpress_sw_config: | ||
+ | type: OS::Heat::SoftwareConfig::Chef | ||
+ | properties: | ||
+ | # ... | ||
− | + | wordpress_deployment: | |
− | + | type: OS::Heat::SoftwareDeployment::Chef | |
− | + | properties: | |
+ | software_config: wordpress_sw_config | ||
+ | server: wp_server | ||
+ | parameters: | ||
+ | wp_admin_user: { get_param: wp_admin_user } | ||
+ | wp_admin_pw: { get_param: wp_admin_pw } | ||
+ | # more input parameters ... | ||
− | + | wp_server: | |
− | + | type: OS::Nova::Server | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | type: OS:: | ||
properties: | properties: | ||
− | + | # ... | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | The <code> | + | The <code>wordpress_deployment</code> resource points to the <code>wordpress_sw_config</code> SoftwareConfig resource and specifies that one incarnation of it shall be deployed on (applied to) server <code>wp_server</code>. In the <code>parameters</code> section of the SoftwareDeployment properties, input for the configurable parameters of the Wordpress deployment is provided, for example, by getting global template parameters specified by the user at deployment time. Those parameters map to those defined in the <code>wordpress_sw_config</code> resource shown earlier. |
− | The <code> | + | The output parameters defined under <code>outputs</code> in the <code>wordpress_sw_config</code> resource can be observed as attributes of the <code>wordpress_deployment</code> resource via the <code>get_attr</code> instrinsic function. For example, the following snippet in a HOT template would pass the URL of the deployed Wordpress application to the user as an output value: |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
+ | outputs: | ||
+ | wordpress_url: | ||
+ | description: URL to access deployed Wordpress application | ||
+ | value: { get_attr: [ wordpress_deployment, wp_url ]} | ||
− | = | + | = Responsibilities of the Software Deployment Resource = |
− | + | There are several aspects to be covered by implementations of Software Deployment resources. First of all, the resource code is responsible to injecting metadata into the referened deployed target (server) for doing bootstrapping of the respective software config tool (Chef etc.). Furthermore, the resource is responsible to triggering deployment of the respective software (by invoking the underlying software config tool) when all dependencies are met. Up completing of software deployment, the resource has to update its state to CREATE_COMPLETE so overall orchestration thru Heat can progress (or failures have to be indicated via the appropriate failure state). Finally, attributes specified in the associated Software Config resource have to be obtained from the underlying software config tool so uses of the <code>get_attr</code> can be resolved. | |
− | + | = Dependencies between Software Deployments = | |
− | + | Software Deployments in many cases depend on other Software Deployments. For example, the Wordpress application requires a MySQL database to be set up for storing content. There are two ways for declaring dependencies between Software Deployments: ''data flow based'' and ''explicit definition''. | |
− | |||
− | |||
− | = Dependencies between | ||
− | There are two ways for declaring dependencies between | ||
== Data flow based == | == Data flow based == | ||
− | A data flow based dependency between two software deployments exists, when a property (input) of one | + | 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: | resources: | ||
− | + | wordpress_deployment: | |
− | type: | + | type: OS::Heat::SoftwareDeployment::Chef |
properties: | properties: | ||
− | server: | + | software_config: wordpress_sw_config |
− | + | server: wp_server | |
+ | parameters: | ||
wp_admin_user: { get_param: wp_admin_user } | wp_admin_user: { get_param: wp_admin_user } | ||
wp_admin_pw: { get_param: wp_admin_pw } | wp_admin_pw: { get_param: wp_admin_pw } | ||
− | + | db_endpoint_url: { get_attr: [ mysql_deployment, db_url ] } | |
− | + | # more input parameters ... | |
− | + | mysql_deployment: | |
− | type: | + | type: OS::Heat::SoftwareDeployment::Chef |
properties: | properties: | ||
− | server | + | software_config: mysql_sw_config |
− | + | server: db_server | |
− | + | parameters: | |
− | + | # input parameters for MySQL deployment ... | |
− | |||
− | |||
− | |||
− | would introduce a dependency from <code> | + | would introduce a dependency from <code>wordpress_deployment</code> to <code>mysql_deployment</code> since one of the properties of <code>wordpress_deployment</code> is set using the <code>get_attr</code> function refering to an attribute of the <code>mysql_deployment</code> resource. As a result, resource <code>mysql_deployment</code> must be in state CREATE_COMPLETE before processing of resource <code>wordpress_deployment</code> starts. The complete example is shown in section [[Heat/Blueprints/hot-software-config-WIP#Wordpress_all_in_one_Example|Wordpress all-in-one Example]]. |
== Explicit dependency == | == 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 explicitly defining dependencies of a software deployment in a <code>depends_on</code> clause which is a list of resource IDs of other resources that a | + | 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 explicitly defining dependencies of a software deployment in a <code>depends_on</code> clause which is a list of resource IDs of other resources that a Software Deployment depends on, for example: |
resources: | resources: | ||
client: | client: | ||
− | type: | + | type: OS::Heat::SoftwareDeployment::Chef |
properties: | properties: | ||
+ | software_config: { get_resource: client_sw_config } | ||
server: { get_resource: my_server } | server: { get_resource: my_server } | ||
params: | params: | ||
Line 192: | Line 140: | ||
server_process1: | server_process1: | ||
− | type: | + | type: OS::Heat::SoftwareDeployment::Chef |
properties: | properties: | ||
+ | software_config: { get_resource: server_process1_sw_config } | ||
server: { get_resource: my_server } | server: { get_resource: my_server } | ||
params: | params: | ||
Line 199: | Line 148: | ||
server_process2: | server_process2: | ||
− | type: | + | type: OS::Heat::SoftwareDeployment::Chef |
properties: | properties: | ||
+ | software_config: { get_resource: server_process2_sw_config } | ||
server: { get_resource: my_server } | server: { get_resource: my_server } | ||
params: | params: | ||
Line 208: | Line 158: | ||
type: OS::Nova::Server | type: OS::Nova::Server | ||
properties: | properties: | ||
− | + | # ... | |
− | |||
In the example above, <code>client</code> would depend on both <code>server_process1</code> and <code>server_process2</code> to be completed. | In the example above, <code>client</code> would depend on both <code>server_process1</code> and <code>server_process2</code> to be completed. | ||
+ | |||
+ | |||
+ | |||
+ | work in progress - to be completed | ||
+ | |||
= Implemenation considerations = | = Implemenation considerations = |
Revision as of 10:02, 18 November 2013
Contents
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. * Reference to software component outputs: 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
Re-usable software components are modeled as SoftwareConfig
resources. Those SoftwareConfig definitions point to the actual automation to later perform software configuration (e.g. Chef, Puppet, scripts, ...) and they provide the metadata that is necessary for a generic SoftwareDeployment
resource to deploy a given software on a server. The SoftwareDeployment
resource represents one incarnation, i.e. one concrete use, of a software component in a template. It provide specific input parameters for that deployment, it will provide outputs produced by that deployment, and most importantly it maps the deployment to a specific target server.
It is assumed that there will be different pluggable implementations for SoftwareConfig
and SoftwareDeployment
- one per backend configuration tool like Chef, Puppet, scripting etc. - since each configuration tool will have specific requirements on metadata and runtime implementation.
The following figure shows those concepts based on a Wordpress example. Assume that there are Chef cookbooks for configuring the Wordpress application and MySQL. Those are referenced by two SoftwareConfig
resources, along with the respective metadata for each automtion. The automation plus the corresponding SoftwareConfig definitions are the re-usable entities; they are not mapped to any concrete deployment target, and they do not define specific input values. There is one SoftwareDeployment
resource for MySQL and one for Wordpress, each mapping the deployment to a separate server. A data dependency exists between the Wordpress deployment and the MySQL deployment (see also snippets later on this page) to get endpoint information about the MySQL database for configuring the Worpress application.
For simple template, it is possible to define all elements (SoftwareConfig, SoftwareDeployment and other base resources) in one template file. For more complex scenarios, and to increase composability, a subset of resources can be split into separate provider templates that can be bound via environments. This is explained in more detail and with example snippets in section Provider Templates.
Software Configs
SoftwareConfig
resources contain definition of metadata for automation like Chef cookbooks, scripts, etc. along with a reference to the actual automation. Once defined, they can be mapped to one or more deployment targets (servers) by means of ServerDeployment
resources (see Software Deployments). SoftwareConfig definitions are specific to the used software configuration tool, since they provide tool specific metadata. The following example shows a snippet for a Chef Software Config resource (the complete example is given in section Wordpress all-in-one Example):
resources: wordpress_sw_config: type: OS::Heat::SoftwareConfig::Chef properties: cookbook: http://www.example.com/hot/chef/wordpress.zip role: wordpress # parameters that the chef role(s) need parameters: wp_admin_user: type: string mapping: wordpress/admin_user wp_admin_pw: type: string mapping: wordpress/admin_password db_endpoint_url: type: string mapping: wordpress/db_url # more input parameters ... # output data that the chef automation produces outputs: wp_url: type: string mapping: wordpress/url
The resource type OS::Heat::SoftwareConfig::Chef
indicates that this is a Chef-specific software config definition. The cookbook
property points to the used Chef cookbook, and the role
property points to the role to set up via this software config. The parameters
section contains the definition of parameters that have to be passed to Chef for configuring the role. Parameters are defined in terms of name and type. In addition, a mapping
specifies to which role attribute the respective input parameters needs to be assigned.
The outputs
section defines attributes that can be retrieved once the software deployment at runtime has completed. Those values will be available as attributes of the corresponding SoftwareDeployment
resource at runtime (see also Software Deployments).
Software Deployments
A SoftwareDeployment
resource represents one concrete use of a piece of software (defined via a SoftwareConfig
resource) in a template. It points to the SoftwareConfig that shall be applied to a deployment target, and it points to the actual deployment target (server). As with SoftwareConfig, it is assumed that SoftwareDeployment implementations will be specific to the used software configuration tools, since tool specific steps will have to be performed at runtime.
The following example show a SoftwareDeployment definition for the Wordpress component defined earlier using Chef. For brevity, definitions of overall template parameters, outputs or other resources have been left out - please refer to section Wordpress all-in-one Example for the complete example:
resources: wordpress_sw_config: type: OS::Heat::SoftwareConfig::Chef properties: # ... wordpress_deployment: type: OS::Heat::SoftwareDeployment::Chef properties: software_config: wordpress_sw_config server: wp_server parameters: wp_admin_user: { get_param: wp_admin_user } wp_admin_pw: { get_param: wp_admin_pw } # more input parameters ... wp_server: type: OS::Nova::Server properties: # ...
The wordpress_deployment
resource points to the wordpress_sw_config
SoftwareConfig resource and specifies that one incarnation of it shall be deployed on (applied to) server wp_server
. In the parameters
section of the SoftwareDeployment properties, input for the configurable parameters of the Wordpress deployment is provided, for example, by getting global template parameters specified by the user at deployment time. Those parameters map to those defined in the wordpress_sw_config
resource shown earlier.
The output parameters defined under outputs
in the wordpress_sw_config
resource can be observed as attributes of the wordpress_deployment
resource via the get_attr
instrinsic function. For example, the following snippet in a HOT template would pass the URL of the deployed Wordpress application to the user as an output value:
outputs: wordpress_url: description: URL to access deployed Wordpress application value: { get_attr: [ wordpress_deployment, wp_url ]}
Responsibilities of the Software Deployment Resource
There are several aspects to be covered by implementations of Software Deployment resources. First of all, the resource code is responsible to injecting metadata into the referened deployed target (server) for doing bootstrapping of the respective software config tool (Chef etc.). Furthermore, the resource is responsible to triggering deployment of the respective software (by invoking the underlying software config tool) when all dependencies are met. Up completing of software deployment, the resource has to update its state to CREATE_COMPLETE so overall orchestration thru Heat can progress (or failures have to be indicated via the appropriate failure state). Finally, attributes specified in the associated Software Config resource have to be obtained from the underlying software config tool so uses of the get_attr
can be resolved.
Dependencies between Software Deployments
Software Deployments in many cases depend on other Software Deployments. For example, the Wordpress application requires a MySQL database to be set up for storing content. 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_deployment: type: OS::Heat::SoftwareDeployment::Chef properties: software_config: wordpress_sw_config server: wp_server parameters: wp_admin_user: { get_param: wp_admin_user } wp_admin_pw: { get_param: wp_admin_pw } db_endpoint_url: { get_attr: [ mysql_deployment, db_url ] } # more input parameters ... mysql_deployment: type: OS::Heat::SoftwareDeployment::Chef properties: software_config: mysql_sw_config server: db_server parameters: # input parameters for MySQL deployment ...
would introduce a dependency from wordpress_deployment
to mysql_deployment
since one of the properties of wordpress_deployment
is set using the get_attr
function refering to an attribute of the mysql_deployment
resource. As a result, resource mysql_deployment
must be in state CREATE_COMPLETE before processing of resource wordpress_deployment
starts. The complete example is shown in section Wordpress all-in-one Example.
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 explicitly defining dependencies of a software deployment in a depends_on
clause which is a list of resource IDs of other resources that a Software Deployment depends on, for example:
resources: client: type: OS::Heat::SoftwareDeployment::Chef properties: software_config: { get_resource: client_sw_config } server: { get_resource: my_server } params: # params ... depends_on: - get_resource: server_process1 - get_resource: server_process2 server_process1: type: OS::Heat::SoftwareDeployment::Chef properties: software_config: { get_resource: server_process1_sw_config } server: { get_resource: my_server } params: # params ... server_process2: type: OS::Heat::SoftwareDeployment::Chef properties: software_config: { get_resource: server_process2_sw_config } server: { get_resource: my_server } params: # params ... my_server: type: OS::Nova::Server properties: # ...
In the example above, client
would depend on both server_process1
and server_process2
to be completed.
work in progress - 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-collect-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.