py-nvidia-cumulus

Unofficial Python API client for Nvidia Cumulus Linux.

📖 General information

The client aims to provide a thin wrapper over the Cumulus OpenAPI specification.
Therefore, it abstracts endpoints in a Pythonic fashion.

🛠 Installation

To install the package, run the following command:

pip install py-nvidia-cumulus

To install the package locally, clone this repository and run the following command:

pip install .

🚀 Quickstart

To start using the client, instantiate the Cumulus class with the host and authentication details

from cumulus import Cumulus

nv = Cumulus(
    url="https://127.0.0.1:8765",
    auth=("cumulus", "password")
)
# nv.http_session = requests.Session() # set your own session if necessary
nv.http_session.verify = False # disable SSL verification if necessary

📄 Examples

1. Get the IP address of an interface relative to the OpenAPI endpoint

# Instantiate the Cumulus class first
loopback = nv.interface.get('lo/ip/address')
print(loopback) # {'127.0.0.1/8': {}, '::1/128': {}}

2. Update interface configuration relative to the OpenAPI endpoint:

# Instantiate the Cumulus class first
nv.revision.create() # create a revision
# patch an interface by providing the created revision ID, new data, and path to the object
nv.interface.patch(rev=nv.revision.rev,
                   data={"10.255.255.2/32": {}},
                   target_path="lo/ip/address")
nv.revision.apply() # apply the changes
nv.revision.is_applied() # watch the switch to make sure the changes were applied successfully

3. Here is a more complex example on how to deploy the entire switch configuration using the root endpoint. We will also see how to get the diff between the current revision and the one we are applying.

from cumulus import Cumulus

configuration = {"key": "value"}
nv = Cumulus(
    url="https://127.0.0.1:8765",
    auth=("cumulus", "password")
)
nv.http_session.verify = False # by default the switch uses self-signed certificate

nv.revision.create()
# remove previous configuration completely.
# Otherwise, only new keys will be applied and old ones won't be removed
nv.root.delete(nv.revision.rev)
nv.root.patch(rev=nv.revision.rev, data=configuration)

# see the changes between the current and pending revisions
print(nv.root.diff(nv.revision.rev))

nv.revision.apply()

# check switch status for 3 minutes
nv.revision.is_applied(retries=180)
# update revision to get the success/error message
nv.revision.refresh()
print(nv.revision.config)

4. Due to the very dynamic nature of Nvidia Cumulus API, there may not always be a model to cover the endpoint you want to use. Adding your own model is very simple.

from cumulus import Cumulus
from cumulus.models import BaseModel

nv = Cumulus(
    url="https://127.0.0.1:8765",
    auth=("cumulus", "password")
)
programming = BaseModel(client=nv, endpoint="system/forwarding/programming")
print(programming.get(endpoint_params={"rev": "applied"}))

🏷️ Versioning

We use SemVer for versioning. To see the available versions, check the PyPI page or tags in this repository.

🤝 Contribution

We welcome contributions, issues, and feature requests! Also, please refer to our contribution guidelines for details.

Made with ♥ by Namecheap Cloud Team