The cloud compute api provides access to cloud compute functions through a restful api.


https://github.com/USACE/cloudcompute-api


This project is under construction, this section of the document provides minimal insights into the path forward, but no guarantee it will be developed exactly this way.


Primary API Objectives

The API has many endpoints which are documented with the library. This documentation describes the primary objectives of the API. 

Plugin Registration

Plugins must be registered with the API to be available for use in a compute. Plugin registration associates a plugin with a compute provider, and requires the input of a plugin id and a plugin registration manifest.


Manage Directed Acyclic Graphs

The API provides endpoints to create and modify Directed Acyclic Graphs. Each node in a DAG is a plugin with a specific set of manifest overrides. A DAG can be used to compute one event, or paired with an Event Generator to perform many events.


Compute

The API provides the ability to perform a compute on a dag with an event generator on a compute environment. 


Authentication and Authorization

Authentication and Authorization have not yet been implemented in the API.

Authentication

Authentication will be managed through KeyCloak managed for CWBI with Login.gov providing the service of Authentication. This will allow PIV/CAC/Username and Password access that meets 2FA authentication requirements for our services. 


Authorization

For cloud compute our design for authorization will leverage keycloak and the role based access similar to Model Library.


Terms:

  • MetaGroup: This is a collection of groups. (e.g. OFAs, FEMA, USACE, USACE-MMC, USACE-MMC-FOUO)
  • Group: This is a collection of users that can interact with cloud-compute api.  E.g. A group has one or more members.
  • Group Grant: A member of a group (e.g. user) can have any combination of four roles within the group (R/W/C/A).
  • User: An individual.
  • Role: R=Read, W=Write (create a simulation), A=Admin, E=Execute a Simulation

 

Rules:

  • A simulation belongs to a Group.  Groups can own any number of simulations. *A group provides the context to allow a user to execute a simulation.
  • Members of a group can have roles assigned at the user level.
  • The roles assigned within a group inherently apply to all simulations owned by the group.
  • Only group administrators can change roles for group members
  • Other groups can also be granted roles on Simulations owned by a group.
    • Semantically referred to as a “Simulation Grant”.
    • Simulation Grant roles are limited to R and will apply equally to all members of the non-owning group regardless of their roles within a group.
    • If a user is a member of multiple groups with differing roles for a model, the logic is to take the most permissive combination of roles for that user across all of the model and group grants. 
      • For example, a user User1 belongs to a group Group1 and has the “R” "W" and "E" role within Group1. Group 1 owns a simulation Simulation1, therefore User1 has the read role on Simulation1.  The administrator for Group1 then grants access to Simulation1 to another group Group2 (e.g. a simulation grant), and grants the R roles to Group2.  If User1 is also a member of Group2, then User1 maintains "R" "W" and "E" roles for Simulation1 in spite of the Simulation Grant. 
  • Only administrators of the group that own a simulation can perform simulation Grants
  • A User does not have a personal group unique to cloud compute permissions to avoid excessive individual charges for computes 
  • By default when a new user (must be CAC/PIV authenticated) loads the site *they have no authority to do anything until being added to a group



   → Group grant is a role granted to a member of a group.

Simulation grant is granting a group to a model -

   → Simulation Grant is granting a role on a specific simulation to another group

So we are naming them based on what you are being granted to - not who to which unit the grant is being applied.



  • Specifications of Roles via Grants
    • There are Simulation Grants and Group Grants these can only be performed by Administrators of a group
    • If a user is a member of multiple groups with differing roles for a simulation, the logic is to take the most permissive combination of roles for that user across all of the simulation and group grants. 
    • Group Grant specifications
      • Group Grant applies roles at the User level
      • Group Grant is the assignment of roles within a group
      • These roles apply to all simulations owned by the group
      • Group Grant roles can include R W or A * or E 
    • Simulation Grant Specifications
      • Simulation Grant applies roles at the Group level
      • Simulation Grant is the assignment of roles to a simulation owned by a group to another external group  
      • Simulation Grant roles are limited to R and will apply equally to all members of the non-owning group regardless of the members roles within the non-owning group.