Python Guide

Overview

This overview defines italicized terms and essential concepts and introduces the Python module classes you will use.

Identities

Users and API accounts are identities, and identities are members of an organization. Identities are granted permissions on organizations, networks, and network groups by way of role assignments.

Roles

Roles are sets of permissions that are granted to identities for organizations, networks, and network groups. An example of a role assignment is “Network Admin - ACME Net” which grants permission to manage network “ACME Net”, but not to delete it nor grant new permissions.

The default roles for new users and API accounts are “organization admin” and “network group admin”. Taken together, these default roles grant all permissions for the organization and networks inside the network group.

Organizations

An organization contains identities. An instance of class Organization represents a particular organization. There is typically only one organization, and the organization of the caller’s identity is used by default.

# become identity in organization
identity = 'credentials.json'                                # relative to PWD or in ~/.netfoundry or /netfoundry
organization = netfoundry.Organization(credentials=identity) # use the calling identity's organization
caller_identity = organization.caller                        # Who am I?

# built-in docs
❯ pydoc netfoundry.Organization

Networks

A NetFoundry network contains the entities and policies that compose your AppWANs. An instance of class Network represents a particular network. The network may be selected by name or ID. This provides attributes and methods to describe and manage the network. A network is always a member of exactly one network group.

# use a network
network = netfoundry.network(network_group, network_id=created_network['id'])
status = network.status           # read the status attribute
endpoints = network.endpoints()   # call a method to get live results

# built-in docs
❯ pydoc netfoundry.Network

Network Groups

A network group organizes networks for billing and administration purposes. Roles that grant permissions on a network are granted to an identity at the network level or network group level or both. An instance of class NetworkGroup represents a particular network group and may be used to find, create, and delete networks in that group. Most users have only the default network group and it is selected automatically when there is only one.

# use group as organization
network_group = netfoundry.NetworkGroup(organization)
network_name = 'ACME Net'
created_network = network_group.create_network(name=network_name)

# built-in docs
❯ pydoc netfoundry.NetworkGroup

Installation

Installing the Python3 module is easy with pip.

Python Package Index module

Python3 interface to the NetFoundry API

❯ pip install netfoundry

Docker

A container image with the latest Python module already installed: netfoundry/python:latest

Demo Script

A sample Python script is provided which uses this module to create a network with a functioning service.

Link to demo.py source file on the web.

# or find the installed source file for demo.py under FILE heading of the built-in doc
❯ pydoc netfoundry.demo

There’s a separate article here all about using demo.py which is included with the module.