arista-eos 1.1.0

data/guide/faq.rst

@@ -0,0 +1,30 @@
+FAQ
+===
+
+.. contents:: :local:
+
+Server: Error: ... cannot load such file -- rbeapi/client
+---------------------------------------------------------
+
+If you see the following error on the master::
+
+  Server: Error: Could not autoload puppet/provider/eos_vlan/default: cannot load such file -- rbeapi/client
+
+Install the rbeapi rubygem on the server::
+
+  sudo gem install rbeapi
+
+Server: Error: ... provider 'eos': undefined method `api' for nil:NilClass`
+---------------------------------------------------------------------------
+
+If you try to apply a class or nmanifest and receive the following error::
+
+  Server: Error: Could not prefetch eos_vlan provider 'eos': undefined method `api' for nil:NilClass`
+
+The eos provider requires a connection to an EOS device and cannot be applied on an OS that does not support Arista eAPI except in development mode.
+
+Either ensure this manifest/class only gets applied to EOS devices or redirect eAPI communications on this system to a real or virtual EOS device::
+
+  export RBEAPI_CONF=/path/to/my/.eapi.conf
+  export RBEAPI_CONNECTION=<connection-name>
+

data/guide/index.rst

@@ -0,0 +1,25 @@
+.. puppet_eos documentation master file, created by
+   sphinx-quickstart on Mon Apr  6 20:46:10 2015.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Arista EOS Module for Puppet
+============================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
+   quickstart
+   installation
+   types
+   cookbook
+   troubleshooting
+   developing
+   testing
+   faq
+   release-notes
+   license
+

data/guide/installation.rst

@@ -0,0 +1,174 @@
+Installation
+============
+
+.. contents:: :local:
+
+Configuring the Puppet Master
+-----------------------------
+
+Follow the standard practices for installing either Puppet Enterprise or Puppet Open-source master servers and your environment(s). As the paths to various items and specifics may vary from system to system, you might need to make minor adjustments to the instructions, below, to conform to your particular system.  The command ``puppet confing print`` can assist you in locating the right directories.
+
+On the master, install the `Forge: puppet-eos`_ module (Source: `GitHub: puppet-eos`_). This module is self-contained including the types and providers specific to EOS.  There is also a `netdev_stdlib <https://forge.puppetlabs.com/netdevops/netdev_stdlib>`_ module in which PuppetLabs maintains a common set of Types in netdev_stdlib and the EOS providers are in `netdev_stdlib_eos <https://forge.puppetlabs.com/aristanetworks/netdev_stdlib_eos>`_.
+
+Add the puppet-eos module to your server's modulepath:
+
+Puppet installer::
+
+  $ puppet module install puppet-eos [--environment production ] [--modulepath $basemodulepath ]
+
+Install from source::
+
+  $ git clone https://github.com/arista-eosplus/puppet-eos.git modulepath/eos
+  $ git checkout <version or branch>
+
+Link using Git submodules::
+
+  $ git submodule add https://github.com/arista-eosplus/puppet-eos.git modulepath/eos
+
+Bootstrapping EOS switches
+--------------------------
+
+There are a number of ways to bootstrap the necessary components on to a switch, and automatically load the minimal, initial configuration.  We strongly suggest _`ZTP Server` to automate the steps from initial power-on to contacting the Puppet master.
+
+Sample minimal configuration on a switch includes basic IP connectivity, hostname and domain-name which are used to generate the switch's SSL certificate, a name-server or host entry for "puppet", the default master name unless otherwise specified, and enabling eAPI (management api http-commands):
+
+.. code-block:: console
+
+  !
+  hostname my-switch
+  ip name-server vrf default 8.8.8.8
+  ip domain-name example.com
+  ip host puppet 192.2.2.5
+  !
+  interface Management1
+     ip address 192.2.2.101/24
+     no shutdown
+  !
+  ip route 0.0.0.0/0 192.2.2.1
+  !
+
+  If EOS version is 4.14.5 or later
+  !
+  management api http-commands
+     no protocol https
+     protocol unix-socket
+     no shutdown
+  !
+
+  If EOS version is below 4.14.5
+  username eapi privilege 15 secret icanttellyou
+  !
+  management api http-commands
+     no shutdown
+  !
+
+Install the puppet agent from `PuppetLabs`_::
+
+  Arista#copy http://myserver/puppet-enterprise-3.7.2-eos-4-i386.swix extensions:
+  Arista#extension puppet-enterprise-3.7.2-eos-4-i386.swix
+  Arista#copy installed-extensions boot-extensions
+
+Install the rbeapi extension::
+
+  Arista#copy http://myserver/rbeapi-0.1.0.swix extensions:
+  Arista#extension rbeapi-0.1.0.swix
+  Arista#copy installed-extensions boot-extensions
+
+Additional Puppet Master configuration
+--------------------------------------
+
+Configuring rbeapi
+^^^^^^^^^^^^^^^^^^
+
+Rbeapi, in many cases, requires a configuration file describing its connection method and credentials to eAPI on the switch. Available transports include https, http, http-local, and unix socket (EOS 4.14.5).  Unix socket is recommended if available in the running version of EOS due to ease of configuration and security posture.  
+The /mnt/flash/eapi.conf file (also flash:eapi.conf) can be installed at bootstrap time or by puppet afterward. To do so with puppet, modify the sample files, below, to meet your needs.
+
+Create the module skeleton on the Puppet master::
+
+  cd <modulepath>
+  puppet module generate <username-modulename>
+  mkdir <username-modulename>/templates/
+
+Create an eapi.conf template in <modulepath>/<username-modulename>/templates/eapi.conf.erb
+
+.. code-block:: erb
+
+  <%# rbeapi/templates/eapi.conf.erb %>
+  # Managed by Class['rbeapi']
+  [connection:localhost]
+  <% if @host -%>
+  host: <%= @host %>
+  <% end -%>
+  <% if @_transport != "http" -%>
+  transport: <%= @_transport %>
+  <% end -%>
+  <% if @_username != "admin" -%>
+  username: <%= @_username %>
+  <% end -%>
+  <% if @_password != "" -%>
+  password: <%= @_password %>
+  <% end -%>
+  <% if @port -%>
+  port: <%= @port %>
+  <% end -%>
+
+Create a class that can be applied to nodes in <modulepath>/<username-modulename>/manifests/init.pp
+
+.. code-block:: ruby
+
+  # modules/rbeapi/manifests/init.pp
+  # Example to configure eAPI for use with rbeapi
+  #   class { rbeapi:
+  #    username => eapi,
+  #    password => icanttellyou,
+  #  }
+  class rbeapi ($host = "localhost",
+                $transport = https,
+                $username = admin,
+                $password = "") {
+
+    package { 'rbeapi':
+      ensure => installed,
+      provider => 'gem',
+    }
+
+    # Check the EOS version (split in to major.minor.patch)
+    $section = split($::operatingsystemrelease, '\.')
+    $major = $section[0]
+    $minor = $section[1]
+    if $section[2] =~ /^(\d+)/ {
+      $patch = $1
+    } else {
+      $patch = 0
+    }
+
+    # eapi.conf can use "socket" starting with EOS 4.14.5
+    if $major >= 4 and $minor >= 14 and $patch >= 5 {
+      $_transport = socket
+      # The following defaults cause the template to skip
+      #   user/pass sections
+      $_username = admin
+      $_password = ""
+    } else {
+      # Just pass through values we received
+      $_transport = $transport
+      $_username = $username
+      $_password = $password
+    }
+
+    # Populate the eapi.conf file
+    file { 'eapi.conf':
+      path => '/mnt/flash/eapi.conf',
+      ensure => file,
+      content => template("rbeapi/eapi.conf.erb"),
+      require => Package['rbeapi'],
+    }
+  }
+
+.. target-notes::
+
+.. _`Forge: puppet-eos`: https://forge.puppetlabs.com/aristanetworks/puppet-eos
+.. _`Github: puppet-eos`: https://github.com/arista-eosplus/puppet-eos
+.. _`ZTP Server`: https://github.com/arista-eosplus/ztpserver
+.. _`PuppetLabs`: https://puppetlabs.com/download-puppet-enterprise-all#eos
+

data/guide/license.rst

@@ -0,0 +1,5 @@
+License
+=======
+
+.. include:: ../LICENSE
+   :literal:

data/guide/overview.rst

@@ -0,0 +1,35 @@
+Overview
+========
+
+.. contents:: :local:
+
+Introduction
+------------
+
+Puppet is a configuration management platform which operates by way of the user defining the desired state for a resource, puppet comparing that to the current state, then resolving any differences.  By having an agent running on each node, puppet can not only be operated from a master, but can also be used in a standalone (masterless, headless) configuration.
+
+This Type / Provider module enables Types specific for managing Arista EOS device configuration from Puppet.  By defining profile classes around these types, network device management can be refocused to managing network applications such as ntp, stp, ospf, vxlan, or even abstracted away from a network-centric perspective in to higher level business goals such as deploying a new application service or site.
+
+Puppet masters can be deployed in Enterprise or Open Source varieties providing various levels of tools and support, including dashboards and reporting. Such additional toolsets provide simplified configuration and rich analysis and auditing of an environment.
+
+Terminology
+-----------
+
+When working with Puppet there is some basic terminology which is helpful to understand.  A Type is resource that Puppet knows how to manage; a hostname, VLAN, layer-2 interface, etc.   A Provider is the implementation-specific code that evaluates and effects change to the respective Type. There can be multiple Providers for a Type; for example: VLAN configuration may have a different provider for each OS vendor that it supports.  A Module can consist of one or more Types and/or Providers packaged together or, it could be a grouping of related manifest classes, files, and templates.
+
+Prerequisites
+-------------
+
+`PuppetLabs <http://puppetlabs.com/>`_ provides an EOS extension (SWIX file) for Arista switches that contains Ruby, the Puppet Enterprise agent and a number of dependencies for use with either Puppet Enterprise or Open Source Puppet masters.
+
+On EOS, `eAPI <https://eos.arista.com/arista-eapi-101/>`_ must be initially enabled and the `rbeapi <https://github.com/arista-eosplus/rbeapi>`_ rubygem extension installed.  These 2 components are used by the puppet modules to review the current state of resources and to bring them into compliance with the desired state.
+
+On-switch Requirements:
+
+* Puppet agent
+
+  * Ruby, etc.
+
+* rbeapi rubygem
+* eAPI enabled
+

data/guide/quickstart.rst

@@ -0,0 +1,184 @@
+Quick Start
+===========
+
+.. contents:: :local:
+
+Bootstrapping a switch
+----------------------
+
+There are a number of ways to bootstrap the necessary components on to a switch, and automatically load the minimal, initial configuration.  We strongly suggest _`ZTP Server` to automate the steps from initial power-on to contacting the Puppet master.
+
+Sample minimal configuration on a switch includes basic IP connectivity, hostname and domain-name which are used to generate the switch's SSL certificate, a name-server or host entry for "puppet", the default master name unless otherwise specified, and enabling eAPI (management api http-commands):
+
+.. code-block:: console
+
+  !
+  hostname my-switch
+  ip domain-name example.com
+  !
+  ip name-server vrf default 8.8.8.8
+  ! OR
+  ip host puppet 192.2.2.5
+  !
+  interface Management1
+     ip address 192.2.2.101/24
+     no shutdown
+  !
+  ip route 0.0.0.0/0 192.2.2.1
+  !
+
+  ! If EOS version is 4.14.5 or higher, use unix-sockets
+  !
+  management api http-commands
+     no protocol https
+     protocol unix-socket
+     no shutdown
+  !
+
+  ! If EOS version is below 4.14.5
+  username eapi privilege 15 secret icanttellyou
+  !
+  management api http-commands
+     no shutdown
+  !
+
+If you configured eAPI (``management api http-commands``) for anything other than
+``unix-socket``, then an ``flash:eapi.conf`` is also required.  Ensure that the connection is ``localhost`` and enter the transport, port, username, and password required for the puppet module to connect to eAPI.  See more about configuring `eapi.conf`_.
+
+Example ``flash:eapi.conf``:
+
+.. code-block:: console
+
+  [connection:localhost]
+  transport: https
+  port: 1234
+  username: eapi
+  password: password
+  enablepwd: itsasecret
+
+Install the puppet agent from `PuppetLabs`_::
+
+  Arista#copy http://myserver/puppet-enterprise-3.7.2-eos-4-i386.swix extensions:
+  Arista#extension puppet-enterprise-3.7.2-eos-4-i386.swix
+
+Install the `rbeapi extension`_::
+
+  Arista#copy http://myserver/rbeapi-0.1.0.swix extensions:
+  Arista#extension rbeapi-0.1.0.swix
+
+Save the installed extensions::
+
+  Arista#copy installed-extensions boot-extensions
+
+EOS Command Aliases
+^^^^^^^^^^^^^^^^^^^
+
+If working with puppet manually from the CLI, it may be convenient to add the following aliases to your systems
+
+.. code-block:: console
+
+  alias pa bash sudo puppet agent --environment demo --waitforcert 30 --onetime true
+  alias puppet bash sudo puppet
+
+With the above aliases, repetitive typing can be reduced to, for example:
+
+.. code-block:: console
+
+  Arista#pa --test
+  Arista#puppet resource eos_vlan
+  Arista#puppet describe eos_vlan
+
+Configuring the Puppet Master
+-----------------------------
+
+Follow the standard instructions for `installing either a Puppet Enterprise or Puppet Open-source master <https://docs.puppetlabs.com/>`_ server and setup your environment(s). (Standalone Puppet, also known as headless or masterless puppet, is covered in a separate section.) As the paths to various items and specifics may vary from system to system, you may need to make minor adjustments to the ommands, below, to conform to your particular system.  Use ``puppet config print`` to locate the correct paths.
+
+On the master, install the `Forge: puppet-eos`_ module (Source: `GitHub: puppet-eos`_). This module is self-contained including the types and providers specific to EOS.
+
+.. note::
+  There is also a `netdev_stdlib <https://forge.puppetlabs.com/netdevops/netdev_stdlib>`_ module in which PuppetLabs maintains a cross-platform set of Types in netdev_stdlib and the EOS-specific providers are in `netdev_stdlib_eos <https://forge.puppetlabs.com/aristanetworks/netdev_stdlib_eos>`_.
+
+Install the rbeapi rubygem on the server::
+
+  $ sudo gem install rbeapi
+
+Add the puppet-eos module to your server's modulepath:
+
+Puppet installer::
+
+  $ sudo puppet module install puppet-eos [--environment production ] [--modulepath $basemodulepath ]
+
+Install from source::
+
+  $ sudo git clone https://github.com/arista-eosplus/puppet-eos.git <environment>/modules/eos
+  $ cd <environment>/modules/eos/
+  $ sudo git checkout <version or branch>
+
+Link using Git submodules::
+
+  $ cd $moduledir
+  $ git submodule add https://github.com/arista-eosplus/puppet-eos.git eos
+  $ git submodule status
+  $ git submodule init
+  $ git status
+
+Verifying the agent on EOS
+--------------------------
+
+Run the puppet agent on EOS.  This performs several key tasks:
+* Generate a keypair and request a certificate from the master
+* Retrieve the CA and Master certificates
+* Run pluginsync (enabled by default) to download the types and providers
+* Run the defined manifests, if configured
+
+.. code-block:: console
+
+  Arista#bash sudo puppet agent [--environment <env_name>] --test --onetime --no-daemonize --waitforcert 30
+
+On the Master, sign the node's certificate request:
+
+.. code-block:: console
+
+  $puppet cert list
+  $puppet cert sign <certname>
+
+If you did not include ``waitforcert``, above, then re-run the puppet agent command to install the signed certificate from the server:
+
+.. code-block:: console
+
+  Arista#bash sudo puppet agent [--environment <env_name>] --test --onetime --waitforcert 30
+
+Verify that the ``eos_*`` types are available on the switch:
+
+.. code-block:: console
+
+  Arista#bash sudo puppet resource --types [| grep eos]
+
+View the current state of a type:
+
+.. code-block:: console
+
+  Arista#bash sudo puppet resource eos_vlan
+  eos_vlan { '1':
+    ensure    => 'present',
+    enable    => 'true',
+    vlan_name => 'default',
+  }
+
+View the description for a type:
+
+.. code-block:: console
+
+  Arista#bash sudo puppet describe eos_vlan
+
+If the steps, above, were not successful, proceed to the :ref:`troubleshooting` chapter.
+
+.. target-notes::
+
+.. _`eapi.conf`: https://github.com/arista-eosplus/rbeapi#example-eapiconf-file
+.. _`Forge: puppet-eos`: https://forge.puppetlabs.com/aristanetworks/puppet-eos
+.. _`Github: puppet-eos`: https://github.com/arista-eosplus/puppet-eos
+.. _`ZTP Server`: https://github.com/arista-eosplus/ztpserver
+.. _`PuppetLabs`: https://puppetlabs.com/download-puppet-enterprise-all#eos
+.. _`rbeapi extension`: https://github.com/arista-eosplus/rbeapi
+