aristanetworks/go-cvprac

go-cvprac - Golang CloudVision Portal RESTful API and Client

Table of Contents

1. Overview
2. Requirements
3. Installation
4. Usage
5. Development
6. Testing
7. Versioning
8. Contributing
9. Support
10. License

Overview

This module provides a RESTful API client for Cloudvision® Portal (CVP) which can be used for building applications that work with Arista CVP.

There are two pieces to go-cvprac:

• api - Provides all the formated request/response to CVP in a nice to use interface.
• client - Client implementation using the API.

If you would like to spin your own version of a client, then you only need to implement the API interface.

Requirements

• Go 1.6.3+

CVP Versions supported for each go-cvprac release:

CVP Version	go-cvprac Version
2016.x-2017.x	v1
2018.1.x, 2018.2.x, 2019.1.x	v2
2020.1.x, 2020.2.x	v3

Installation

First, it is assumed you have a standard Go workspace, as described in http://golang.org/doc/code.html, with proper GOPATH set.

Please refer section Versioning for detailed info.

To download and install go-cvprac:

$ go get -u gopkg.in/aristanetworks/go-cvprac.v2

After setting up Go and installing go-cvprac, any required build tools can be installed by bootstrapping your environment via:

$ make bootstrap

Usage

Basic usage:

The included client can be used to connect/interact with CVP:

package main

import (
	"fmt"
	"log"

	"gopkg.in/aristanetworks/go-cvprac.v2/client"
)

func main() {
	hosts := []string{"10.81.110.85"}
	cvpClient, _ := client.NewCvpClient(
		client.Protocol("https"),
		client.Port(443),
		client.Hosts(hosts...),
		client.Debug(false))

	if err := cvpClient.Connect("cvpadmin", "cvp123"); err != nil {
		log.Fatalf("ERROR: %s", err)
	}

	// verify we have at least one device in inventory
	data, err := cvpClient.API.GetCvpInfo()
	if err != nil {
		log.Fatalf("ERROR: %s", err)
	}

	fmt.Printf("Data: %v\n", data)
}

If you want to use your own client (to leverage some custom behavior), you merely need to implement the provided ClientInterface:

type ClientInterface interface {
	Get(string, *url.Values) ([]byte, error)
	Post(string, *url.Values, interface{}) ([]byte, error)
}

You then can access/interact with CVP using your clients underlying behavior. Example:

import (
	"fmt"
	"log"

	"gopkg.in/aristanetworks/go-cvprac.v2/api"
)

type YourCustomClient struct {
  ...
}
func NewYourCustomClient(host string) *YourCustomClient {
  ...
}
func (c *YourCustomClient) Get(url string, params *url.Values) ([]byte, error) {
  ...
}
func (c *YourCustomClient) Post(url string, params *url.Values, data interface{}) ([]byte, error) {
  ...
}

yourClient := NewYourCustomClient("10.10.1.2")
cvpClient := cvpapi.NewCvpRestAPI(yourClient)
cvpClient.Login(user, passwd)

Development

Please refer to Contributing section on contribution guidelines. To install the needed packages for lint/vet/etc. run the bootstrap provided:

$ make bootstrap

Testing

The go-cvprac library provides various tests. To run System specific tests, you will need to update the cvp_node.gcfg file (found in api/) to include CVP specifics/credentials for your setup.

System Test Requirements:

• Need one CVP node for test with a test user account. Create the same account on the switch used for testing.
• Test has dedicated access to the CVP node.
• CVP node contains at least one device in a container.
• Container or device has at least one configlet applied.

For running System tests, issue the following from the root of the go-cvprac directory:

$ make systest

Similarly, Unit tests can be run via:

$ make unittest

Note: Test cases live in respective XXX_test.go files and have the following function signature:

Unit Tests: TestXXX_UnitTest(t *testing.T){... System Tests: TestXXX_SystemTest(t *testing.T){...

Any tests written must conform to this standard.

Versioning

Releases are done according to Semantic Versioning

• gopkg.in/aristanetworks/go-cvprac.v{X} points to appropriate tagged versions; {X} denotes version series number and it's a stable release for production use. For e.g. gopkg.in/arsitanetworks/go-cvprac.v1

Contributing

Bug reports and pull requests are welcome on GitHub. Please note that all contributions that modify the library behavior require corresponding test cases. Otherwise the pull request will be rejected.

This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Support

For support, please open an issue on GitHub or contact [email protected]. Commercial support agreements are available through your Arista account team.

License

BSD 3-Clause License

Copyright (c) 2017, Arista Networks EOS+ All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

• Neither the name Arista nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

go-cvprac's Issues

AddToInventory Depreciated

As the new CVP backend merges, we have a new way of importing a device. Quote from a email thread in cvp-dev:

Going forward, for importing devices into CVP, you need to issue a POST request
to: cvpservice/inventory/devices
Expected request body format:
{
"host":"172.1.1.1"
}

Note that value in the request body can be hostname or IP address.

If the above is successful, you should see the device appearing in undefined container. You can then move it to a different container like before from the provisioning page.

Also CSV import is not supported now for the new cvp backend, therefore #23 could be closed, and probably reopened if in the future csv is supported again.

CVAAS authentication using service account

Is there a way to use this project for CVAAS with service accounts?

Add methods to Apply/Remove configlets from Container

Add GetRole/GetAllRoles api

Deprecate POST /inventory/deleteDevices.do

We need to deprecate DeleteDevices(). The endpoint/inventory/deleteDevices.do is:

• Marked as deprecated starting 2020.1
• Replaced by DELETE on /inventory/devices starting 2020.1.0
• Planned deletion after 2020.3.0 train.

The initial plan for go-cvprac is to change/rename DeleteDevices() to DeleteDevicesByMac(), and add an additional method called DeleteDevicesBySerial(). These changes will reside in v3 branch and be tagged v3.x. Anyone updating to v3.x of go-cvprac will have a compile failure if they are using DeleteDevices()...users can easily address the change once they get the compile time error.

v3.x will only be supported on cvp >= 2020.1.0

RemoveConfigletsFromDevice seems inefficient

We have a test environment with CVP which already ramped up more than 3000 configlets. This causes the removal of configlets from a device to take over a minute.

RemoveConfigletsFromDevice() in

go-cvprac/api/provisioning.go

Line 637 in 16ade42

var cKeys, cbKeys, rmKeys, rmbKeys []string

seems to call getConfiglets 4 times, for reasons I cannot deduce.

The remConfiglets parameter already includes the to-be-removed configlet keys and names, so why are they retrieved from the expensive getConfiglet api endpoint?

GetParentContainerForDevice needs to account for Simularity in Container names

Two containers: Spine and Spines.
SearchTopology will return

  "netElementContainerList": [
    {
      "netElementKey": "44:4c:a8:a5:0d:a1",
      "containerKey": "container_7011_1546263883299862",
      "containerName": "Spine"
    },
    {
      "netElementKey": "44:4c:a8:a5:0d:a2",
      "containerKey": "container_690_327531534203857",
      "containerName": "Spines"
    }
  ]

Need to return device that matches netElementKey.

Add runtime CVP version checking for endpoints

Go-cvprac could move towards checking the version of a connected CVP instance within client methods, as is used by cvprac. This would allow a single package version to support a wider range of CVP versions by either throwing an error or selecting another suitable endpoint.

This follows on from discussions with @cheynearista about the versioning impact of implementing #83.

TestCvpRac_CheckCompliance_SystemTest fails for CVP2018.2

Merge functionality from v2 to v3

In our project we are still using v2, because we need functionality like

• #70
• #76
• #77

which is not in v3.

I think it was once proposed 1 by @cheynearista to merge functionality from v2 to v3 -- I this still on the maintainers' radar?

Conversion to table tests

Most of the unit tests currently have 1 test case per main test. Writing table test where all test cases are run as subtests in one main test (per API call function) would be a better option, considering that it shortens the code.
Start by converting user unit tests. api/user_test.go

`ApplyConfigletToDevice` does not create TempAction if configlet is already on device.

IIUC, ApplyConfigletToDevice does two things:

• actually set the configlet on a a device.
• create a tempaction

However this function does not create a tempaction when the configlet is already on the device. In fact, with the current functions in go-cvprac, I have no idea how to create a tempaction now in the scenario that a device already holds a configlet, but does not have an accompanying tempaction yet.

Note that this behaviour does not seem to be in the Python version of cvprac.

Add support for Change Control Scheduling

go-cvprac is currently missing support for change control scheduling, as well as other convenience methods around the ChangeControlConfig endpoint.

Equivalent code for scheduling can be found here for the python CVPrac bindings.

This slightly violates go-cvprac v3's version compatibility of "2020.1.x, 2020.2.x": the endpoint specifies a min version of "CVP 2021.2.0 or newer" , while scheduling requires CVP 2022.1.0.

Fix GetUser/GetAllUsers api to use correct CVP API path

Use exact match for fqdn in GetDeviceByName

We need to only return the exact match for devices fqdn

Task methods use int for taskID. Look into changing to string

Seems things would be simpler if we took taskID of string for:

• CancelTask
• ExecuteTask
• AddNoteToTask
• GetLogsByID
• GetLogs
• GetTaskByID

We perform an ItoA() within these calls, but ideally we should just allow users to use string instead for the taskID param.

Add Import of devices and save devices to inventory function

• Import and save devices to a container, by hitting /inventory/add/addToInventory.do and /inventory/add/saveInventory.do endpoints
• Need delete device from inventory

Migrate to golang v2+ modules

Add method to return container a device is part of

Need to add a method to return the Container for a device.

Expose capability to add device to inventory

Expose api to client to add device to inventory.

Use /workflow instead of /task for executeTask

Update to use v2/validateAndCompareConfiglets.do

The endpoint /provisioning/validateAndCompareConfiglets.do is marked as deprecated starting 2020.2.
Replaced by /provisioning/v2/validateAndCompareConfiglets.do, available starting 2018.2.3
Planned deletion in 2020.3.0

makeRequest: Refresh session on '401' response

From 2018.2.0 onwards, a '401' response is returned for an 'Unauthorized' user, unlike previous releases where a CvpError with code '112498' was returned. This might happen if the session expires, which is after 12 hours of inactivity. In this case, the session must be refreshed.

Some feature requests regarding inventory and provisioning

1. Import and save devices to a container, by hitting /inventory/add/addToInventory.do and /inventory/add/saveInventory.do endpoints

2. Import devices using csv file, by hitting /inventory/importInventoryData.do endpoint

3. ImageInfo struct in provisioning.go should also include a field called “sha512”. When you do a GET on /image/getImages.do, the response would actually contain a field called sha512, so simply adding a field in ImageInfo struct should be sufficient.

4. Support GetImageByName. I am surprised that we can only get image bundle by name but not the image it self. It should just be implemented by getting all the images using GetImages, and do a search in the list, as we don’t have generic GetImageByName endpoint in CVP itself.

Create Container SystemTest fails on CVP2018.2

Add Import of devices using CSV

Import devices using csv file, by hitting /inventory/importInventoryData.do endpoint

GetDevicesInContainer returns devices not within a given container

We use GetInventory and search for the name of the container. We should be getting the container key and filtering each device on the container parent.

Add GetTempAction

Need ability to get list of tempActions from CVP

Add ability to perform device reset

this is needed for specific cases where automation needs to revert a device back to Undefined container to restart.

SaveTopology Race Condition

When saving topology at the same time among multiple devices, duplicate tasks are created causing the inability to execute those tasks. Is there a good way to be more selective on the save topology call so that the call is at the scope of a device or temp action and not the entire topology?

Add support for GetImageByName

• ImageInfo struct in provisioning.go should also include a field called “sha512”. When you do a GET on /image/getImages.do, the response would actually contain a field called sha512, so simply adding a field in ImageInfo struct should be sufficient.
• Support GetImageByName. I am surprised that we can only get image bundle by name but not the image it self. It should just be implemented by getting all the images using GetImages, and do a search in the list, as we don’t have generic GetImageByName endpoint in CVP itself.

Add table to README detailing CVP support

Allow setting device target IP during deploy

GetUndefinedDevice returns no devices in Undef Container

no NetElements returned when devices exist in Undef Container

makeRequest: Refresh session with same node

When an 'Unauthorized' response is received, the session is refreshed by sending a login request to the next node. However, in case of a single-node setup, there is no next node and hence the session is never refreshed.

possibility to add configlets at certain position on a netdevice

as it seems, applying new Configlets to devices, always adds them to the end of list of configlets.
However in CVP, configlet order is important. As such in our case we'd like to position some configlets at a certain position.

Expose api to run a configlet builder via API

Providing a builder name and expected input variables executing a defined builder from CVP. Also, allow api to create a configlet by name via same api as result of builder execution.

MoveDeviceToContainer: Handle parent container not being set

Need to handle case where devices are being moved from undef cont

Add GetUser and GetAllUsers API

Add support for cloudvision as a service

GetConfigletByName returns error when no configlet exists

This should return nil. Only error if the underlying request fails.