Metadata-Version: 2.4
Name: cvproxy
Version: 1.0.4
Summary: CVProxy - CloudVision Proxy
Author-email: Chris Mason <chris@netnix.org>
License-Expression: MIT
Project-URL: Repository, https://github.com/cmason3/cvproxy.git
Project-URL: Issues, https://github.com/cmason3/cvproxy/issues
Project-URL: Changelog, https://github.com/cmason3/cvproxy/blob/main/CHANGELOG.md
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyavd>=5.7.2
Requires-Dist: jsonschema
Dynamic: license-file

# Arista CloudVision Proxy

Arista are transitioning their CloudVision provisioning model to use Studios and Workspaces, but the HTTP REST API only supports the legacy provisioning model, which has now been deprecated. The new API uses gRPC and is rather complex, but Arista provides a Python library to talk to the API, which is used by Ansible via the `arista.avd.cv_deploy` role. The purpose of this tool is to use `pyavd` to handle the complexity and to provide a HTTP proxy to convert between simplified JSON and gRPC using the same workflow that Ansible uses via `pyavd._cv.workflows.deploy_to_cv`.

### Installation

```
python3 -m venv /opt/cvproxy
/opt/cvproxy/bin/python3 -m pip install cvproxy
```
```
tee /etc/systemd/system/cvproxy.service >/dev/null <<-EOF
[Unit]
Description=CVProxy - CloudVision Proxy

[Service]
Environment="VIRTUAL_ENV=/opt/cvproxy"
ExecStart=/opt/cvproxy/bin/python3 -u -m cvproxy -s -l 127.0.0.1 -p 8080
SyslogIdentifier=cvproxy
TimeoutStartSec=60
Restart=always

[Install]
WantedBy=multi-user.target
EOF
```
```
systemctl enable --now cvproxy
```

### Usage

```
 cvproxy -s [-l <address>] [-p <port>] [-xff]

   -s                         - start CVProxy
   -l <address>               - specify a listen address (default is '127.0.0.1')
   -p <port>                  - specify a listen port (default is 8080)
   -xff                       - use X-Forwarded-For
```

It works by accepting a HTTP POST request with a `Content-Type` of `application/json`, which should adhere to the following schema:

```json
"unevaluatedProperties": false,
"required": ["devices", "cv_server", "cv_token"],
"properties": {
  "devices": {
    "minProperties": 1,
    "unevaluatedProperties": false,
    "patternProperties": {
      "^[a-z][a-z0-9_.-]*$": {
        "unevaluatedProperties": false,
        "required": ["configlet"],
        "properties": {
          "serial_number": { "type": "string", "pattern": "^[A-Z][A-Z0-9]{10}$" },
          "configlet": { "type": "string", "pattern": "^(?=(.{4})+$)[A-Za-z0-9+/-]+={0,2}$" },
          "tags": {
            "minProperties": 1,
            "additionalProperties": { "type": "string" }
          }
        }
      }
    }
  },
  "cv_server": { "type": "string", "pattern": "\\S+" },
  "cv_token": { "type": "string", "pattern": "\\S+" },
  "cv_change_control_name": { "type": "string", "pattern": "\\S+" },
  "cv_delete_workspace": { "type": "boolean" },
  "cv_strict_tags": { "type": "boolean" }
}
```

The `serial_number` attribute is optional as it should be able to identify the device based on the hostname, unless it is a new device and there is no existing configlet.
The `configlet` attribute is mandatory and is the configlet for the device, which must be Base64 encoded.

Example:

```json
"devices": {
  "leaf-1a": {
    "configlet": "<base64 encoded configlet>",
    "tags": {
      "type": "leaf"
    }
  },
  "leaf-1b": {
    "configlet": "<base64 encoded configlet>",
    "tags": {
      "type": "leaf"
    }
  }
},
"cv_server": "www.cv-prod-uk-1.arista.io",
"cv_token": "<service token>",
"cv_strict_tags": true
```

If the HTTP POST request succeeds and there are any changes then a Change Control will be created in CloudVision ready for you to review and approve.
The `cv_change_control_name` attribute is optional and if not provided will use the AVD default.
The `cv_delete_workspace` attribute is also optional and if set to "true" will cleanup and delete the submitted Workspace.
The `cv_strict_tags` attribute is also optional and defaults to "false".

Successful HTTP responses will be JSON encoded and will always contain a `status` attribute, which will either be "ok" or "error".
If it is set to "ok" then an optional `change_control` attribute will be included if a Change Control was generated.
If it is set to "error" then an `errors` attribute will also be provided with details of why it failed.

The recommended deployment is to deploy HAProxy in front of CVProxy, as HAProxy is better equipped to deal with TLS termination and it also supports HTTP/2 and HTTP/3 transports.
