Overview
The NDSLabs API is a RESTful interface to the NDSLabs system. The API is implemented via the NDSLabs API Server.
Key Concepts
- Project: A named configuration that relates an administrative user, likely represented by a client certificate, to a set of resource allocations (quotas), and re
sources (namespace, pods/services, volumes, configurations). - Service definition: A specification of a logical "service" that includes a name, description, storage requirements, configuration options, and relationshi
ps to other services. An NDSLabs "service" may be composed of multiple related containers. - Service library: A collection of service definitions and procedures for adding official/trusted as well as local/development services.
- Service instance: An instance of a service configured and running in a project namespace.
- Resource quota: A set of soft and hard limits assigned to a project (storage and compute).
- Volume: A named, allocated storage resource that counts against the project quota and can be mounted by one or more services.
A Simple Use Case
Using the CLI for simplicity: a project administrator wants to add a set of services to their project configuration:
| Command | What it does | Response |
|---|---|---|
| list services | Lists the services in the service library that can be added to this project. |
|
| list resources | Lists the storage resources available to this project | storage quota: 1TB |
| get service clowder | Gets the service specification | <spec> |
| add service clowder | Adds the specified service to the project | OK |
| get config clowder | Gets the configuration options available for the service | <config> |
| set config clowder smtp-host smtp.ncsa.illinois.edu | Sets a configuration option for the named services | OK |
| create volume clowder-vol 10GB | Creates and formats a volume named "clowder-vol" | OK |
| attach clowder-vol clowder | Makes the volume available to the service | OK |
| start clowder | Starts the service | <status> |
| status clowder | Returns the service status | <status> |
| endpoint clowder | Returns the service endpoint | <endpoint> |
| add service image-preview | Adds the specified service to the project | OK |
| link image-preview clowder | Links the specified services (in this case, by adding required rabbitmq) | OK |
| start image-preview | Starts the image preview service and updates the clowder service? | <status> |
| stop services | Stops everything | <status> |
| delete volume clowder-vol | Removes the specified volume | OK |
| delete clowder image-preview | Removes the services from the project | OK |
Entities
The following is a simple entity-relationship diagram intended to capture the entities, attributes, and relationships for the NDSLabs API.
| Gliffy Diagram | ||||||
|---|---|---|---|---|---|---|
|
Draft REST API
This is a first pass at a set of REST APIs that support the following workflows. For actor definitions, see NDS Labs Use Cases.
...
| Gliffy Diagram | ||||
|---|---|---|---|---|
|
API Authentication
- For the CLI, we could follow the Kubernetes API server authentication model using client certificates. They use openssl/easyrsa to sign client certificates where the common name is the username (or in our case, project namespace).
- This is not useful for the GUI, which might require user authentication. Perhaps we can pre-generate a password?