Control Plane API

Control Plane API#

The platform’s control plane provides access to the cluster-management using REST APIs. Using a CRUD-like HTTP client, you can: get, list, create, update, and delete resources, and trigger operations against the Iguazio System.

Initialize#

import igz_mgmt

Create a control plane client#

client = igz_mgmt.Client(access_key="some-access-id")

If an access_key is not provided and the environment variable V3IO_ACCESS_KEY is set, the client uses it by default. You can also use your password to authenticate against the management API, but you must log in immediately after. For example:

import igz_mgmt
client = igz_mgmt.Client(endpoint='https://dashboard.default-tenant.app.mysys.iguazio.com/',
                         username="someone",
                         password="my-pass")
client.login()

If a username is not provided and the environment variable V3IO_USERNAME is set, the client uses it by default.

You can get the access key from the platform dashboard: press the user-profile picture or icon from the top right corner of any page, and press Access Keys from the menu. In the Access Keys window, either copy an existing access key or create a new key (making sure you assign it with control plane) and copy it.

When running python code on a local machine that connects to a remote Iguazio platform, you can obtain the URL of your cluster by copying the API URL.

Create a control plane client with custom logger#

You can pass a custom logger to the client, for example:

import logging

import igz_mgmt

custom_logger = logging.getLogger("a")
custom_logger.setLevel(logging.DEBUG)
customer_handler = logging.FileHandler("customer.log")
custom_logger.addHandler(customer_handler)
formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
customer_handler.setFormatter(formatter)

client = igz_mgmt.Client(access_key="some-access-id",
                         endpoint="https://dashboard.default-tenant.app.mysys.iguazio.com/",
                         logger=custom_logger)
client.login()

RESTful API#

Most of the resources support all CRUD methods. Some endpoints within the management API are considered “operations”, which means that the response may not represent a resource. Some operations are long-living, which means that a background job is created and the response holds its job-id. See Jobs API.

wait_for_completion#

By default, the flag wait_for_completion is set to True, which means that the called function will return only after the job it has created was completed (or failed). If a job will take a long time, and you don’t want to wait for its completion, you can set wait_for_completion=False.

These functions support wait_for_completion:

  • User.delete, Group.delete, AccessKey.delete, Job.delete, Project.delete. The argument is named wait_for_job_deletion and if the job was created, it returns the job object.

  • AppServicesManifest functions (create_or_update, restart, remove_service, scale_from_zero). The argument is named wait_for_completion. It returns the job object.

  • AppServices functions (create_or_update, restart, remove, enable, disable, scale_from_zero). The argument is named wait_for_completion. It returns the job object. See more about the wait_for_completion function in Jobs API.

Resources API#

Get#

To retrieve a record, use the relevant resource (e.g.: user) and call its .get() function while providing its record id This creates a GET request to the Iguazio Management API and returns the record.

user = igz_mgmt.User.get(client, "some-user-id")

List#

Same as get, but using .list(). The return value is a list of records for the specific resource. Listing options:

  • Filter by field values: filter_by={"field-name": "field-value"}

  • Include related resources: include=["resource-kind-a", "resource-kind-b"]

  • Sort by field names: sort_by=["field_a", "field_b"]

  • Paginate: paging=igz_mgmt.ResourceListPagingQueryParams(size=50, number=0)

Example of: filter / sort / include

# returns all users whose last name equals "xyz", sorted by creation date
# include the groups record for each user

igz_mgmt.User.list(client,
                   filter_by={"last_name":"xyz"},
                   sort_by=["created_at"],
                   include=["user_groups"],
                  )

Pagination example:

# paginate over all users, slicing response to 20 records at a time
import igz_mgmt

page_number = 0
while True:
    users = igz_mgmt.User.list(client, paging=igz_mgmt.ResourceListPagingQueryParams(number=page_number, size=20))
    if len(users) == 0:

        # no more users, stop here
        break

    # go to next page
    page_number += 1
    print(len(users))

Create#

To create a record, use the relevant resource (e.g.: User) and call its .create() function. This makes a POST request to the Iguazio Management API and returns the created record.

Update#

To update a record, use the relevant resource (e.g.: user) and call its .update() function. This makes a PUT request to the Iguazio Management API and returns the updated record.

By default, when updating a record, it sends all record fields at once. To perform a “patch” update, which only sends the “changed” fields, you need to first create the record instance, change the fields to patch, then invoke the .update() function. For example:

user_to_update = SomeResource(id="existing-resource-id")
user_to_update.some_field = "change-me-only"
updated_user = user_to_update.update(client)

Delete#

To delete a record, use the relevant resource (e.g. user) and call its .delete() function.

In case the record does not exist, an error is raised (as a result of the HTTP code 404). To quietly delete a record, use the .delete() function with ignore_missing=True.

Contents