Getting Started
Authentication Mechanisms
The Rubrik SDK for Python provides two mechanisms for supplying credentials to the rubrik_cdm.Connect()
function. Credentials may be accessed through the use of environment variables or manually passed into the function as parameters.
Authenticating with Environment Variables
Storing credentials in environment variables is a more secure process than directly hard coding them into scripts and ensures that your credentials are not accidentally shared if your code is uploaded to an internal or public version control system such as GitHub. If no arguments are passed to the rubrik_cdm.Connect()
function, it will attempt to read the Rubrik Cluster credentials from the following environment variables:
rubrik_cdm_node_ip
(Contains the IP/FQDN of a Rubrik node)rubrik_cdm_username
(Contains a username with configured access to the Rubrik cluster)rubrik_cdm_password
(Contains the password for the above user)rubrik_cdm_token
(Contains the the API token used for authentication)
Note: The rubrik_cdm_username
and rubrik_cdm_password
must be supplied together and may not be provided if the rubrik_cdm_token
variable is present
The way in which to populate these environment variables differs depending on the operating system running Python. Below are examples for Windows, Linux, and Mac OS.
Setting Environment Variables in Microsoft Windows
For Microsoft Windows-based operating systems the environment variables can be set utilizing the setx
command as follows:
Setting Environment Variables in macOS and *nix
For macOS and *nix based operating systems the environment variables can be set utilizing the export command as follows:
In order for the environment variables to persist across terminal sessions, add the above three export commands to the ~\.bash_profile
or ~.profile file and then run source ~\.bash_profile
or source ~\.profile
to ensure the environment variables are present in your current terminal session.
Once set, the rubrik_cdm.Connect()
function will automatically utilize the data within the environment variables to perform its connection unless credentials are specifically passed in the arguments of the function.
Authenticate by Providing Username and Password or API Token
Although the use of environment variables are recommended, there may be scenarios where directly sending credentials to the rubrik_cdm.Connect()
function as parameters makes sense. When arguments are provided, any environment variable information, populated or unpopulated, is ignored. To pass connection and credential information, simply call the rubrik_cdm.connect()
function, passing the node IP, username, and password as follows:
Or by passing the node IP and API Token as follows:
Mixing the usage of both environment and hard coded variables is supported. The below example is run under the pretense that the rubrik_cdm_node_ip
and rubrik_cdm_password
environment variables have been set, providing only the password to the connect function.
rubrik = rubrik_cdm.Connect(password="SecretPassword")
Connecting to a Rubrik Cluster
The Rubrik SDK for Python utilizes the rubrik_cdm.Connect()
function as a mechanism to provide credentials to Rubrik CDM. rubrik_cdm.Connect()
only needs to be called once, assigning the response to a variable to be used for subsequent calls throughout the remainder of the Python session. To initiate the function, first import the rubrik_cdm
package and assign the response of rubrik_cdm.Connect()
to a variable as follows:
Note: You may use any variable name to connect to the Rubrik cluster.
Any subsequent calls to methods or functions within the rubrik_cdm package are now executed through the context of the variable used to store the response from the Connect() method. For example, to retrieve the VMware VMs within the Gold SLA Domain the following code is used:
For a full list of functions, methods, and their associated arguments see the official Rubrik SDK for Python documentation.
Certificate Validation
When connecting to a Rubrik cluster without certificate validation enabled you will receive the following warning message:
This warning may be suppressed utilizing the urllib3
library and inserting the following code within your script:
Note: It is strongly advised that valid certificates are installed and utilized on the Rubrik cluster. For more information see the Rubrik CDM Security Guide.
Rubrik SDK for Python Quick Start
The following section outlines how to get started using the Rubrik SDK for Python, including installation, configuration, as well as sample code.
Prerequisites
The following are the prerequisites in order to successfully install and run the sample code included in this quickstart guide:
Python (Tested against v2.7.6 and v3.7.4)
Rubrik CDM
Installation
The Rubrik SDK for Python can be installed into a Python environment either by utilizing the pip package manager or installing from source.
Note: Installing from source should only be used when performing development work on the Rubrik SDK for Python or if the environment does not allow for pip installations. The easiest and most common way to install the Rubrik SDK for Python is through the pip package manager.
Install using the pip package manager
Due to the popular uptake of the pip package manager Rubrik also maintains a copy of the Rubrik SDK for Python hosted within the Python Package Index. This allows for developers and operations to install the Rubrik SDK for Python using pip as follows.
The pip installation method will take care of downloading and installing all dependencies of the Rubrik SDK for Python.
Install from Source
As the Rubrik SDK for Python is hosted on GitHub, installing from source allows for the added benefit of being able to access newly created and “beta” type features as they are developed and pushed to the repository.
To install the Rubrik SDK for Python from source run the following commands.
Note: After executing setup.py
install, all dependencies will be automatically downloaded and installed.
Sample Syntax - VMware Virtual Machine Operations
The following code will walk through a number of real-world examples of protecting and restoring VMware Virtual Machines. For a complete listing of available functionality see the complete Rubrik SDK for Python documentation.
Setting up the Sample Workflow
Create a file named vmwarevms.py
in your working directory and copy in the following code:
Breaking Down the Sample Workflow
After importing the needed modules, disabling certificate warnings and connecting to the Rubrik cluster, the main examples start on Line 8.
Lines 8 through 18 show an example of associating an existing SLA Domain with a VMware VM. The assign_sla(
) function is utilized to accomplish this, taking in three arguments; the VM name, SLA Domain name, and Object Type (VMware).
Lines 20 through 30 illustrate performing an on-demand snapshot of a VMware VM. The on_demand_snapshot()
function is utilized to accomplish this, taking in three arguments; the VM name, object type (VMware), and SLA Domain name to apply to the snapshot. The SLA Domain name is an optional requirement and if not specified the currently associated SLA Domain of the VM will be used.
Lines 32 through 49 illustrate a couple of different recovery options for VMware VMs. The first, on Line 42 is a Live Mount of a specific snapshot to the same host which is running the production VM. Line 46 shows a Live Mount of the same VM, only utilizing the most recent snapshot and specifying a host on which to mount the VM. Line 49 performs an Instant Recovery of the VM utilizing the most recent available snapshot.
Note: the vpshere_live_mount()
and vsphere_instant_recovery()
functions support many more arguments and options which are utilized in this sample. For the complete list of functionality available for managing VMware VMs see the Rubrik SDK for Python documentation.
Running the Sample Workflow
Once vmwarevms.py
is saved within the working directory execute the code with the following statement:
Sample Syntax - Physical Host Operations
The following code will walk through a number of real-world examples of protecting physical Windows and Linux hosts. For a complete listing of available functionality see the complete Rubrik SDK for Python documentation. Setting up the Sample Workflow
Create a file named physicalhosts.py
in your working directory and copy in the following code:
Breaking Down the Sample Workflow
After importing the needed modules, disabling certificate warnings and connecting to the Rubrik cluster, the main examples start on Line 8.
Lines 8 through 16 illustrate how to add a physical host to the Rubrik CDM utilizing the add_physical_host()
function.
Lines 18 through 30 illustrate how to create a fileset within Rubrik CDM, containing all of the inclusion and exclusion rules. The fileset is created utilizing the create_physical_fileset()
function.
Lines 32 through 43 complete the physical protection process by assigning both the fileset and an SLA Domain to the physical host. This is accomplished utilizing the assign_physical_host_fileset()
function.
Note: Functions and methods here do not reflect all of the arguments and options available. For the complete list of functionality read the complete Rubrik SDK for Python documentation.
Running the Sample Workflow
Once physicalhosts.py
is saved within the working directory execute the code with the following statement:
Accessing the Built-in Sample Code
To help accelerate development the Rubrik SDK for Python source contains many files containing common activities often performed against a Rubrik cluster. Sample files may be found on the Rubrik SDK for Python GitHub page.
Sample code may be executed using the following syntax:
Rubrik SDK for Python Documentation
This guide acts only as a quick start to get up and running with the Rubrik SDK for Python. For detailed information on all of the functions and features included see the complete Rubrik SDK for Python documentation.
API Documentation
The Rubrik SDK for Python supports the majority of the functionality available within the Rubrik CDM. That said, the release cycles between the SDK and Rubrik CDM are not simultaneous. This means there may be times when new features or enhancements are added to the product but methods and functions to utilize them may be missing from the SDK. In these situations Python may be used to make native calls to Rubrik’s RESTful API. The following syntax outlines a common piece of Rubrik functionality, assigning a VM to an SLA Domain, however, it does so by creating raw API requests to Rubrik CDM utilizing the Python requests library:
Rubrik prides itself upon its API-first architecture, ensuring everything available within the HTML5 interface, and more, is consumable via a RESTful API. For more information on Rubrik’s API architecture and complete API documentation, please see the official Rubrik API Documentation.
Troubleshooting
The Rubrik SDK for Python contains built-in functions and configurations to help assist with troubleshooting any errors that may arise.
Enabling Logging
The rubrik_cdm.Connect()
function contains a built-in, verbose logging mechanism which is disabled by default. To enable the logging mechanism, set the enable_logging
argument to true when connecting to the Rubrik cluster as follows:
The logging_level
argument can then be used to set the specific logging level you wish to use. The following levels are valid choices:
debug
(default value)critical
error
warning
info
When doing so, more verbose debug messages will be displayed on the console when executing various commands and functions within the Rubrik SDK for Python. For example, the Connect()
function itself displays no information by default, however running the same function specifying enable_logging=True outputs the following:
Note: enable_logging
only needs to be specified on the initial connection to Rubrik when running the Connect()
function. All subsequent calls to functions and methods within the Rubrik SDK for Python will then display verbose logging to the console thereafter.
Contributing to the Rubrik SDK for Python
The Rubrik SDK for Python is hosted on a public repository on GitHub. If you would like to get involved and contribute to the SDK please follow the below guidelines.
Common Environment Setup
Clone the Rubrik SDK for Python repository
Change to the repository root directory
Switch to the devel branch
Create a virtual environment
For Python 3:
For Python 2:
Activate the virtual environment
Install the SDK from Source
New Function Development
The /rubrik-sdk-for-python/rubrik_cdm
directory contains all functions for the SDK.
At a high level the directory contains the following:
api.py
- Base API Functions (get, post, etc.) that should only be touched for bug fixes.cloud.py
- Cloud related functionscluster.py
- Functions involving the configuration of the Rubrik cluster itself (think Day 0 configurations)data_management.py
- Functions related to Data Protection tasks (ex. On-demand snapshots)physical.py
- Functions involving the management of physical serversrubrik_cdm.py
- Several internal functions as well as the Connect class which all other functions are accessed through. This should only be touched for bug fixes.
When adding a new function it ideally should be categorized to fit into one of the above files. Each function should meet the following requirements:
Each function must be idempotent. Before making any configuration changes (post, patch, delete) you should first check to see if that change is necessary. If it's not you must return a message formatted as
No change required. {message}:
For example, the assign_sla function first checks to see if the Rubrik object is already assigned to the provided SLA domain.A doc string using the docBlockr format. Visual Studio Code users can take advantage of the autoDocstring extension to simplify this process.
Each API call made in the function should have a
self.log()
call made explaining what the API call is doing. The log message should be formatted asfunction_name: message
.A corresponding example in the
/rubrik-sdk-for-python/sample
directory named the same as the function_name.Each function also must have associated documentation which can be auto generated through
cd docs && python create_docs.py
Once a new function has been added you will then submit a new Pull Request which will be reviewed before merging into the devel branch.
For more information around contributing to the Rubrik SDK for Python see the Rubrik SDK for Python Development Guide documentation on GitHub.
Further Reading
Last updated