ZenPack:ConstructionKit

From Zenoss Wiki
This is the approved revision of this page, as well as being the most recent.
Jump to: navigation, search
Author(s)
Joseph Anderson
Current Maintainer(s)
Joseph Anderson
License
GNU General Public License, Version 2, or later
ZenPack name
ZenPacks.community.ConstructionKit
More Information
GitHub page/HomePage
Git sources (for cloning)
Link




ConstructionKit ZenPack

Automate the development of custom component-based ZenPacks

Warning

The ZenPack Catalog has moved to its new home at https://www.zenoss.com/product/zenpacks as of January 17, 2017. The following information may be out of date, and this page will eventually be removed.

Support

This ZenPack is developed by the Zenoss user community and supported via our online forums. Zenoss, Inc. does not provide direct support for this ZenPack.

Releases

Version 1.0- Download
Released on 2013/03/19
Compatible with Zenoss Core 3.2.x, Zenoss Core 4.2.x
Version 1.0.1- Download
Summary of changes: changed component id generator, support password GUI non-display
Released on 2013/03/22
Compatible with Zenoss Core 3.2.x, Zenoss Core 4.2.x
Version 1.1.0- Download
Summary of changes: support for multiple components, various fixes
Released on 2013/04/01
Compatible with Zenoss Core 3.2.x, Zenoss Core 4.2.x
Version 2.0- Download
Summary of changes: complete rewrite
Released on 2013/11/01
Compatible with Zenoss Core 4.2.x
Incompatible with Zenoss Core 2.5.x, Zenoss Core 3.1.x, Zenoss Core 3.2.x
Version 2.5- Download
Summary of changes: -fixed type-handling errors for various property types

-better documentation of code -general code cleanup -added some "pass-through" functions for later amendment

Released on 2014/05/13
Compatible with Zenoss Core 3.2.x, Zenoss Core 4.2.x

Background

============================

ZenPacks.community.ConstructionKit

============================

About


This ZenPacks automates to a large extent the development of other ZenPacks. It eliminates the bulk of "boilerplate" code that accompanies the typical "custom component" type of zenpack while providing many nice features.

The goal is to reduce the maintenance cost (development time) associated with dependent ZenPacks by removing most of their code. ConstructionKit-dependent ZenPacks should consist only of a Definition.py class file that subclasses the provided "BasicDefinition" class, as well as any additional ZenPack-specific files such as modeler plugins, check scripts, and exported Zenoss templates, event classes, etc (objects.xml).


Requirements


Zenoss


You must first have, or install, Zenoss 4 or later. This ZenPack was tested against Zenoss 4.2.4.


Release Notes


This version (2.0) is a major revision from version 1.0 and has been almost completely redesigned/rewritten. It is much closer to my originial design goals. I ran into a major hurdle when designing the first version that directed me towards the use of "here docs" that is so present throughout its architecture. I later learned that the problem i ran into was due to a bug in the initial Zenoss 4.x versions that has since been corrected. While "here docs" are still in use, they are vastly simplified and used primarily as placeholders to guarantee correct python module loading paths. They are also used to generate the javascript and configure.zcml files for dependent ZenPacks.

The sheer number of changes may make upgrading difficult. I have written and tested a few helper scripts to aid the proces, so please see the notes below before upgrading.

Changes are far too numerous to list, but include: - much more dependent on class inheritance instead of per-ZenPack "here docs" - Inclusion of CustomComponent and CustomDatasource, the parent classes for dependent ZenPacks - Ability to specify additional parent classes for dependent zenpack (for property and relation inheritance) - Ability to add new class methods to subclassed components (via Definition.py) - Ability to add new class attributes to subclassed components (via Definition.py) - Ability to add new relations to subclassed components (via Definition.py) - new scripts to save/load custom components to/from a file (all or ZenPack-specific) - new script to rebuild all or specific dependent ZenPacks - migrate.py to rewrite old Definition.py classes to newer style (part of upgrade process) - install-zp.sh script to facilitate upgrade from ConstructionKit 1.0-based ZenPack to ConstructionKit 2.0-based ZenPack - many handy functions in ZenPackHelper class file to facilitate common development tasks

Installation


If no previous ConstructionKit version is installed, then install by the usual method. Otherwise, please refer to the Upgrade section.


Upgrade


As this is a major revision of ConstructionKit, some precautions should be taken prior to upgrading this ZenPack. I recommend running a full backup of the Zenoss installation prior to performing the upgrade.

First, in previous versions of the ConstructionKit, dependent ZenPacks are pretty close to being standalone in that the generated class files do not refer to the ConstructionKit at all. In fact, if you remove any mention of the ConstructionKit modules, classes, methods, etc. in the __init__.py, then the derived ZenPack is effectively standalone. We can take advantage of this fact when upgrading.

1) To upgrade (from the command line), perform:

       zenpack --install=ZenPacks.community.ConstructionKit-2.0.0-py2.7.egg ; zopectl restart ; zenhub restart 
       CDIR="/opt/zenoss/ZenPacks/ZenPacks.community.ConstructionKit-2.0.0-py2.7.egg/ZenPacks/community/ConstructionKit"; # your path may differ
       $CDIR/bin/save-components.py

The second step will create pickle files in /tmp that store any custom-created components from dependent ZenPacks.

Additionally, a helper function is included that can be run via zendmd to report the numbers and types of custom components. To run this check (in zendmd):

       from ZenPacks.community.ConstructionKit.ZenPackHelper import *
       countConstructs(dmd)

You should save this output to a text file for later reference.


2) After upgrading the ZenPack, the Definition.py files (within dependent ZenPacks) should be updated to reflect the new style. To do this, run:

       $CDIR/bin/migrate.py -w ; zopectl restart ; zenhub restart 


3) After migrating the Definition.py files, new ZenPack files can be generated with:

       $CDIR/bin/rebuild.py ; zopectl restart ;zenhub restart 


4) At this point it is a good idea to count the components again with:

       from ZenPacks.community.ConstructionKit.ZenPackHelper import *
       countConstructs(dmd)

and compare it to the previous results.


5) The upgrade is completed at this point. Optionally (or if errors are noticed), run the following from zendmd:

       from ZenPacks.community.ConstructionKit.ZenPackHelper import *
       updateRelations(dmd, True)


6) Newer versions of dependent ZenPacks are forthcoming. Installing these versions will likely delete existing instances of their custom components, but included save/load scripts can be used to mitigate this damage.

A script (install-zp.sh) has been included to automate this process, and should be used like:

       CDIR="/opt/zenoss/ZenPacks/ZenPacks.community.ConstructionKit-2.0.0-py2.7.egg/ZenPacks/community/ConstructionKit"; # your path may differ
       $CDIR/bin/install-zp.sh ZENPACKFILE.egg

This script will save the custom components to a file, run the zenpack installer, then reload the components from the file.


Developing with ConstructionKit



To create a ZenPack with a new custom component, perform the following:

1) Begin creating a ZenPack from the GUI in the usual fashion (as documented)

       a) be sure to set dependency on Zenpacks.community.ConstructionKit

2) From the command line:

       a) cd $ZENPACKHOME/ZENPACKS.NAME1.NAME2/ZENPACKS/NAME1/NAME2(replace with correct path to your Zenpack)
       b) rm -Rf *
       c) cp $ZENPACKHOME/ZenPacks.community.ConstructionKit/ZenPacks/community/ConstructionKit/example/* ./

3) Modify the "Definition.py" file as needed to suit needed component attributes and data collection methods

4) Reinstall the ZenPack from the command line with:

       zenpack --link --install=$ZENPACKHOME/ZENPACKS.NAME1.NAME2
       zopectl restart ; zenhub restart
       

5) Rebuild the Zenpack files with:

CDIR="/opt/zenoss/ZenPacks/ZenPacks.community.ConstructionKit-2.0.0-py2.7.egg/ZenPacks/community/ConstructionKit"; # your path may differ $CDIR/bin/rebuild.py "ZENPACKS.NAME1.NAME2" ; zopectl restart ; zenhub restart

5) Manually copy any plugins/scripts you intend to distribute to:

       $ZENPACKHOME/ZENPACKS.NAME1.NAME2/ZENPACKS/NAME1/NAME2/libexec

6) Create any desired component-based RRD templates and add to the ZenPack

7) Zenpack can now be exported from Zenoss GUI and installed elsewhere (make sure the ConstructionKit dependency is set).

Installation

Normal Installation (packaged egg)

  1. Download the appropriate egg file for the version of Zenoss you are running.
  2. Ensure you are logged in as the zenoss user:
    $ sudo su - zenoss
  3. Install the ZenPack:
    $ zenpack --install ZenPacks.community.ConstructionKit-*.egg
  4. Restart these services:
    $ zenoss restart

Developer Mode Installation

In order to do a development mode installation you will want to clone the existing git repository, and then use the --link flag with the zenpack command:

  1. Ensure you are logged in as the zenoss user:
    $ sudo su - zenoss
  2. Start by cloning the upstream repository:
    $ git clone git://github.com/j053ph4/ZenPacks.community.ConstructionKit.git
  3. Next, perform the installation:
    $ zenpack --link --install ZenPacks.community.ConstructionKit
  4. Finally, restart these serivices:
    $ zenoss restart

Discuss

Purplemarker.png New: Don't forget to add yourself to the Zenoss User Map!

blog comments powered by Disqus