<commit_before># Topo::Provision

This utility allows you to generate chef-provisioning recipes from
a topology JSON file. 

The format is an extended version of the JSON used by the knife-topo 
plugin. In addition, it is possible to convert from other formats. The
only converter currently implemented is for CloudFormation.

This utility IS NOT READY FOR PRODUCTION USE. It is best described as a
"proof of concept". It has been tested with a pre-release version of 
chef-provisioning 1.0.

## Features

'Nodes' in the topology JSON are generated as machine resources, if
provisioning is specified; otherwise they are generated as chef nodes.

'Node groups' in the topology JSON are generated as combinations of
different resources, depending on the driver and options specified.
Currently, for AWS if 'auto_scaling' is specified, it
generates a machine_image (unless an explicit image_id) is specified;
a launch configuration and an auto-scaling group. For vagrant, the action
is to generate multiple machines using machine_batch.

'Services' can be used to specify other sorts of resource, such as 
a load balancer.

Node attributes can use a special topo_ref to indicate when an attribute
should be set based on attributes of another node. topo-provision will
generate the appropriate 'lazy' evaluation of the attribute value using
a node search, and will use the information to order the resources in the
generated recipe appropriately.

## Usage

    $ topo-provision topofile.json
    
    $ topo-provision cloudformation_template --format=cloudformation --output-topo cloudformation.json
    
    $ topo-provision topofile.json --output topo_deploy.json
    
    $ topo-provision topofile.json --action=undeploy --output topo_undeploy.json
    
    $ topo-provision --help

## Structure

### Generators

Driver Generators support a particular chef provisioning driver, e.g. vagrant,
aws, fog. They live in `lib/topo/provision/#{driver}/` and register themselves using the
name of the driver. They should extend the base `Topo::Provision::Generator`
class and override its methods as needed to process the topo elements (context, node, service)
and call the appropriate Resource Generators.

Resource Generators live in `lib/topo/provision/#{driver}/generators` and
should extend `Topo::Provision::ResourceGenerator`. They are initialized
from a topo context, node or service element and generate the actual output 
for the actions that are supported on the specific resource type (e.g. deploy, undeploy, stop).

The Topology Generator `Topo::Provision::TopologyGenerator` is the top-level generator that calls the appropriate
driver generators and generates a resource graph based on topo_ref dependencies, that it traverses in either
a forward or reverse direction, depending on the actions.

### Converters

Converters accept a format other than topology JSON, and convert it to
the standard topo format. They live in `lib/topo/converter` and register themselves using the
name that should be passed in using the --format option. They should extend
`Topo::Converter` and provide a 'convert' method that takes a data hash and returns a topo hash.


## Known Limitations

Only supports the vagrant and aws drivers.

Only covers the following resources:
* machine
* machine_image (as part of creating a node group)
* load_balancer
* aws_auto_scaling_group (as part of creating a node group)
* aws_launch_configuration (as part of creating a node group)

## Future Directions
<commit_msg>Add gem install to readme<commit_after># Topo::Provision

This utility allows you to generate chef-provisioning recipes from
a topology JSON file. 

The format is an extended version of the JSON used by the knife-topo 
plugin. In addition, it is possible to convert from other formats. The
only converter currently implemented is for CloudFormation.

This utility IS NOT READY FOR PRODUCTION USE. It is best described as a
"proof of concept". It has been tested with a pre-release version of 
chef-provisioning 1.0.

## Features

'Nodes' in the topology JSON are generated as machine resources, if
provisioning is specified; otherwise they are generated as chef nodes.

'Node groups' in the topology JSON are generated as combinations of
different resources, depending on the driver and options specified.
Currently, for AWS if 'auto_scaling' is specified, it
generates a machine_image (unless an explicit image_id) is specified;
a launch configuration and an auto-scaling group. For vagrant, the action
is to generate multiple machines using machine_batch.

'Services' can be used to specify other sorts of resource, such as 
a load balancer.

Node attributes can use a special topo_ref to indicate when an attribute
should be set based on attributes of another node. topo-provision will
generate the appropriate 'lazy' evaluation of the attribute value using
a node search, and will use the information to order the resources in the
generated recipe appropriately.

## Usage

    $ topo-provision topofile.json
    
    $ topo-provision cloudformation_template --format=cloudformation --output-topo cloudformation.json
    
    $ topo-provision topofile.json --output topo_deploy.json
    
    $ topo-provision topofile.json --action=undeploy --output topo_undeploy.json
    
    $ topo-provision --help

## Structure

### Generators

Driver Generators support a particular chef provisioning driver, e.g. vagrant,
aws, fog. They live in `lib/topo/provision/#{driver}/` and register themselves using the
name of the driver. They should extend the base `Topo::Provision::Generator`
class and override its methods as needed to process the topo elements (context, node, service)
and call the appropriate Resource Generators.

Resource Generators live in `lib/topo/provision/#{driver}/generators` and
should extend `Topo::Provision::ResourceGenerator`. They are initialized
from a topo context, node or service element and generate the actual output 
for the actions that are supported on the specific resource type (e.g. deploy, undeploy, stop).

The Topology Generator `Topo::Provision::TopologyGenerator` is the top-level generator that calls the appropriate
driver generators and generates a resource graph based on topo_ref dependencies, that it traverses in either
a forward or reverse direction, depending on the actions.

### Installation

gem install topo-provision

### Converters

Converters accept a format other than topology JSON, and convert it to
the standard topo format. They live in `lib/topo/converter` and register themselves using the
name that should be passed in using the --format option. They should extend
`Topo::Converter` and provide a 'convert' method that takes a data hash and returns a topo hash.


## Known Limitations

Only supports the vagrant and aws drivers.

Only covers the following resources:
* machine
* machine_image (as part of creating a node group)
* load_balancer
* aws_auto_scaling_group (as part of creating a node group)
* aws_launch_configuration (as part of creating a node group)

## Future Directions

{'fraction_non_alphanumeric': 0.05391600454029512, 'fraction_numerical': 0.0005675368898978433, 'mean_word_length': 4.625698324022347, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3884811', 'n_tokens_mistral': 1828, 'n_tokens_neox': 1783, 'n_words': 936}