Use Cases for Tenant Management API

Owned by Jason Hoekstra
Last updated: Aug 09, 2024
4 min read

Overview

The Ed-Fi Community has identified the need for programmatic methods to manage tenants of the Ed-Fi Platform. Current large-scale deployments may require the management of hundreds, if not thousands, of Ed-Fi instances. This includes tasks such as provisioning databases, launching containers, and coordinating other deployment activities within various environments.

Ed-Fi implementors currently utilize web portals and automated scripting to handle these activities. Although platform installations vary between cloud providers and on-premise configurations, the deployment practices tend to follow a consistent pattern.

The "Tenant Management API" is envisioned as a technology component designed to manage Ed-Fi instances via an API interface. This document outlines common use cases that the Tenant Management API might support for Ed-Fi deployments.

Assumptions

Purpose

The Tenant Management API is designed to facilitate the secure and efficient operation of multiple large-scale instances of the Ed-Fi Platform. Its capabilities include:

  • Creating new databases for tenant onboarding

  • Decommissioning databases that are no longer in use

  • Populating initial data for new instances

  • Performing health checks to ensure system integrity

  • Supporting other functions essential to meeting organizational needs for Ed-Fi services

By streamlining these processes, the API ensures reliable and scalable management of Ed-Fi Platform installations.

User Roles

The Tenant Management API is a web service with no user interface, accessible only via API clients. Utilization requires developer tools (such as Postman), custom scripting (such as Python or PowerShell), or integration into a web portal.

Primary Intended User Roles

  1. Cloud, DevOps, and IT System Administrators:

    • Responsibilities:

      • Managing Ed-Fi infrastructure

      • Deploying new instances and archiving/deleting old instances

      • Ensuring instances are operational

      • Supporting API clients for multi-site implementations

    • Usage: These users will utilize the API to perform infrastructure-related tasks, ensuring seamless operation and scalability of Ed-Fi instances.

  2. Software Engineers:

    • Responsibilities:

      • Integrating and building new functionalities in end-user-facing web portals

      • Providing data and managing aspects of educational environments through web portals

      • Developing new products and integrations that leverage the Tenant Management API

    • Usage: These users will implement the API to enable end-users to manage Ed-Fi instances, monitor instance uptime, and handle other administrative tasks within the Ed-Fi ecosystem.

Preconditions

For the purposes of this document, the following conditions are assumed to be in place for the Tenant Management API. In this document, when “Ed-Fi Platform” is mentioned, it assumes these pre-conditions. These experiences too will be utilized for future Ed-Fi technology and platforms.

  • Active and supported Ed-Fi ODS / API multi-tenant environment. ODS / API 7.x only will be targeted as provides multi-instance and multi-tenant features, which was heavily advised by the Ed-Fi Community, and provides the necessary constructs for large implementations.

  • The target for the Tenant Management API is cloud-based implementations. On-premise environments, mostly Docker-based, will be available as a reference implementation for development purposes.

Use Cases

Instance Management

Ed-Fi instances, at an infrastructure level, are typically databases that are partitioned according to the rules of their customers or sponsoring agency. Typically, databases are partitioned once per school year at minimum. Some implementations may partition further by school district and/or environment (i.e. dev, QA, production, analytics read-only copy, et al.). Furthermore, some implementations may be partitioned in tenants, which is a grouping such as an educational-service center or other intermediary managing body.

The Tenant Management API must be able to manage Ed-Fi database instances for large, multi-instance implementations and support the array of configuration options for the Ed-Fi Platform. This includes the creation of databases, verification of online readiness for the databases, population of initial value data, deletion of databases. The Tenant Management API should support these use cases to allow providers the ability to scale-up and scale-down instances as their demanded by their implementations.

Considerations

  • Ed-Fi implementers use various cloud platforms. Docker appears to be a common technology between many at-scale implementations.

  • This is a highly privileged operation and providing API services for these needs will be highly destructive. It must be utilized with care and with proper access controls to utilize its services.

Health Checks

Implementors working at-scale have signaled the need for understanding the uptime and health status of active Ed-Fi instances. This includes understanding and reporting status on the following instance data:

  • Instance uptime and availability (started, stopped, offline, etc)

  • Summary counts of major elements (number of education organizations, number of students, number of sections, et al).

Considerations

  • Ed-Fi implementers use various cloud platforms and database technologies. Docker appears to be a common technology between many at-scale implementations.

  • This may overlap with Data Checker functionality and should be considered how it may play a role in health checks.

Implementation Notes

These are draft notes on implementation, subject to refinement of both the business and infrastructure requirements.

Conceptual sequence diagram

image-20240809-153333.png
sequenceDiagram     Tenant API->>+DB Service: create db(name)     Tenant API->>+Admin API: post /v2/odsInstances(name)     Tenant API->>+ODS/API: this is problematic...

  • If there is a single deployed instance of Admin API supporting multiple ODS instances, then the “Tenant API” and “Admin API” specifications could be in the same application.

    • Otherwise, the “Tenant API” specification needs to be implemented in a separate service, so that there is only one per environment.

  • The method for creating a database will differ not only between PostgreSQL and MSSQL, but also likely between cloud providers. Needs a plugin architecture allowing support for several different ways of handling this out of the box, or drop-in a custom plugin with locally-flavored approach.

  • ODS/API needs connection strings for each instance. Should the Tenant API return the connection string so that a human operator can reconfigure the appSettings file? Or is there something more automated that we can do there? Must again take into account hosting environment differences in how configuration is being managed.

    • Maybe argues for the Tenant API application to become a requirement. The ODS/API could have a call out to the Tenant API to look up all of its connection strings.