strikepackage 0.5.3
A command line tool to deploy virtual machines on XenServer.
License: MIT
Keywords: XenServer XenAPI virtualization automation

Strikepackage
        =============
        
        Overview
        --------
        
        Strikepackage is a command line tool for creating and provisioning VMs on Citrix XenServer. It supports any XenServer that will work with the XenSever 6.2 SDK.
        It's been tested on XenServer 5.6, 6.0.2, 6.1 and 6.2.
        
        Although you can use this tool to simply clone VMs, the main purpose of Strikepackage is to get a VM that is configured with `cloud-init <http://cloudinit.readthedocs.org/en/latest/index.html>`_ online, on the right IP, and attached to a Puppet server so it can run its manifests. To this end, Strikepackage supports integration with `MCHM <https://github.com/pwyliu/magna-carta-holy-metadata>`_, a simple Flask application for hosting cloud-init userdata, and the `Puppet HTTP API <http://docs.puppetlabs.com/guides/rest_api.html>`_. Together these APIs provide a way to automatically deploy a machine without having to use XenCenter at all. Which is good, because XenCenter is a huge pain in the ass sometimes.
        
        A Strikepackage run that uses MCHM and Puppet works like this:
        
        #. Strikepackage gathers network, hostname and other info from user.
        #. Strikepackage generates cloud-init userdata based on templates you provide. Templates are written in the `jinja2 templating language <http://jinja.pocoo.org/docs/>`_ (see below for more details).
        #. Strikepackage then uploads the userdata to MCHM and clones the VM with the XenAPI.
        #. The VM starts with a "url=" kernel parameter. cloud-init uses this kernel param to grab the userdata from MCHM and bootstrap the VM.
        #. After the VM is up, cloud-init has `phoned home <http://cloudinit.readthedocs.org/en/latest/topics/examples.html#call-a-url-when-finished>`_ to MCHM, and the Puppet agent has requested a certificate, Strikepackage uses the Puppet API to sign the new node CSR.
        #. Puppet manifests run and all is right with the world. Success!
        
        Requirements
        ------------
        
        * Python 2.7.6+
        
        Installation And Configuration
        ------------------------------
        
        1. Install strikepackage with pip.
        
        .. code:: bash
        
          pip install strikepackage
        
        2. Before you can use strikepackage, you need to create a *config.yaml* file and edit it for your environment. The example config contains more info.
        
        .. code:: bash
        
          # When you run strikepackage, it looks for a config file in the current
          # directory first, then in /home/$USER/.strikepackage/.
          # If you specify an alternate path with --conf, this will be used instead.
        
          # mkconfig creates /home/$USER/.strikepackage and places example files.
          strikepackage mkconfig
          cd ~/.strikepackage
          cp examples/config.yaml config.yaml
          vim config.yaml
        
        3. In XenCenter, tag the XenServer templates you would like to clone with the string you configured in *config.yaml*.
        
        4. If you are using MCHM, create *userdata.jinja2* and *metadata.jinja2* in the template directory you configured in *config.yaml*.
        
        .. code:: bash
        
          cd ~/.strikepackage
          cp examples/*.jinja2 templates/
          cd templates/
          vim userdata.jinja2
          vim metadata.jinja2
        
        5. If you are using Puppet, make sure you've got a key and cert and have configured *config.yaml*.
        
        6. Now you are ready to run Strikepackage. The main invocation looks like this
        
        .. code:: bash
        
          strikepackage deploy https://myxenserver.ho.domain.local
        
        
        Configuring Puppet API Access
        -----------------------------
        
        In order to configure access to the `Puppet API <https://docs.puppetlabs.com/guides/rest_api.html>`_ you will need to do two things:
        
        1. Generate a certificate and key on the Puppet master for use with Strikepackage
        
        2. Configure *auth.conf* on the Puppet master to allow access to the */certificate_status* endpoint
        
        Generate the certificate with `puppet cert generate <https://docs.puppetlabs.com/references/3.stable/man/cert.html>`_. You should be creating a unique certificate for every user.
        
        .. code:: bash
        
          # Generate a certificate for myusername
          puppet cert generate strikepackage-myusername
        
          # The certificate and key will be located in $ssldir/certs and
          # $ssldir/private_keys respectively. Copy these files and the CA cert to
          # /home/$USER/.strikepackage/keys on your workstation.
          cd $(puppet master --configprint ssldir)
          find . | grep strikepackage
          find . | grep ca_crt
        
        Allow access to */certificate_status* by creating an ACL in *auth.conf*. Below is an example. See the `auth.conf documentation <https://docs.puppetlabs.com/guides/rest_auth_conf.html>`_ for more details.
        
        .. code:: bash
        
          # /etc/puppet/auth.conf
          path /certificate_status
          auth yes
          allow strikepackage-myusername
        
        Creating MCHM Templates
        -----------------------
        
        Template are written in the `jinja2 templating language <http://jinja.pocoo.org/docs/>`_. MCHM works by using cloud-init's `NoCloudNet <http://cloudinit.readthedocs.org/en/latest/topics/datasources.html#no-cloud>`_ `data source <http://smoser.brickies.net/ubuntu/nocloud/>`_. Strikepackage looks in the template dir for two files to render and upload to MCHM: *userdata.jinja2* and *metadata.jinja2*.
        
        You can put whatever cloud-config you want in these templates. The only hard requirement is that cloud-init must `phone home <http://cloudinit.readthedocs.org/en/latest/topics/examples.html#call-a-url-when-finished>`_ to MCHMs phonehome API endpoint when it's done. This is how Strikepackage knows the VM came online and finished booting. See the example userdata template in ~/.strikepackage/examples for more details.
        
        A giant dict gets passed to templates as *params*. You can use any of these variables:
        
        .. code:: python
        
          {
            'sp_tag': 'strikepackage',                                                        # from config.yaml
            'poolmaster': ('my_xenserver_name', 'ad26311d-da4b-48af-ab84-5aa82be42f8d'),      # a tuple of (name, xen_uuid)
            'template': ('my_template_name', '26982928-e8d5-6aab-7ade-66cdf3a900da'),         # a tuple of (name, xen_uuid)
            'network': ('my_network_name', '0c2cda95-f642-e0e2-5042-c1e597a435fa'),           # a tuple of (name, xen_uuid)
            'iid': '4b98060580f341dfa255cac95d01287d',                                        # uuid.uuid4().hex
            'rand_pass': '2905922eb1f34110ba81080206bb9b02e85c8faf6e554311a2b801027dbe1b78',  # a randomly generated password. For temporary use only!
        
            'hostname': 'my_hostname',                                   # user input
            'fqdn': 'my_hostname.ho.mydomain.local',                     # user input
            'dhcp': False,                                               # user input
            'ip': '192.168.10.42',                                       # user input
            'gw': '192.168.10.1',                                        # user input
            'nw': '192.168.10.0',                                        # user input
            'broadcast': '192.168.10.255',                               # user input
            'netmask': '255.255.255.0',                                  # user input
            'dns_servers': '192.168.10.15 192.168.10.16 192.168.10.17',  # from config.yaml. It's "dns_servers" in the template and "dns_serverstring" in the config.
            'dns_searchdomain': 'ho.mydomain.local',                     # from config.yaml
        
            'mchm_enable': True,                                                     # from config.yaml
            'mchm_use_zeroconf': True,                                               # from config.yaml
            'mchm_max_polltime': 600,                                                # from config.yaml
            'mchm_templatedir': '/home/my_user/.strikepackage/templates',            # from config.yaml
            'mchm_url': 'https://mchm.mydomain.local',                               # from config.yaml
            'mchm_vm_url': u'http://169.254.169.254/api/53c7218b4ecee3043ee6e638/',  # returned by MCHM API call
            'mchm_id': u'53c7218b4ecee3043ee6e638'                                   # returned by MCHM API call
        
            'puppet_enable': True,                                                 # from config.yaml
            'puppet_cacert': '/home/my_user/.strikepackage/keys/ca_crt.pem',       # from config.yaml
            'puppet_key': '/home/my_user/.strikepackage/keys/strikepackage.crt',   # from config.yaml
            'puppet_cert': '/home/my_user/.strikepackage/keys/strikepackage.key',  # from config.yaml
            'puppet_url': 'https://puppet.mydomain.local:8140',                    # from config.yaml
            'puppet_environment': 'ops',                                           # from config.yaml
            'puppet_cooldown': 30,                                                 # from config.yaml
        
            'hipchat_enable': True,           # from config.yaml
            'hipchat_api_token': 'a_token',   # from config.yaml
            'hipchat_roomid': 'chatopzzzzz',  # from config.yaml
            'hipchat_from': 'strikepkg',      # from config.yaml
          }
        
        Contributing
        ------------
        
        All pull requests welcome! I ain't fancy.
        
        Setup.py creates the strikepackage command. When running from source, execute
        *run.py* instead.
        
        .. code:: bash
        
          git clone https://github.com/pwyliu/strikepackage.git
          cd strikepackage
          ./run.py mkconfig
          ./run.py --help
        
        
        Release History
        ===============
        
        0.5.3
        -----
        - Fix dash in hostname bug
        
        0.5.2
        -----
        - Minor bug fixes
        - Documentation improvements
        
        0.5.1
        -----
        - Fix manifest
        
        0.5.0
        -----
        - First open source release