Merge pull request #738 from jasonnovichRunAI/v2.17-RUN-16823-whats-new-only

V2.17-RUN-16823-whats-new-only

Author: jasonnovichRunAI

docs/developer/overview-developer.md

@@ -1,11 +1,23 @@
 ---
 title: Developer Documentation Overview
+summary: This article is an overview of the developer documentation for the Run:ai platform.
+authors:
+    - Jason Novich
+date: 2024-Apr-10
 ---
 
-# Overview: Developer Documentation
+Developers can access Run:ai through various programmatic interfaces.
 
-Developers can access Run:ai through various programmatic interfaces. 
+## API Support
 
+The endpoints and parameters specified in the API reference are the ones that are officially supported by Run:ai. Endpoints and parameters that are **NOT** listed in the reference are not officially supported.
+
+Endpoints and parameters marked as `deprecated` means they remain operational and can be used; however, Run:ai will **NO LONGER RECOMMEND USING THEM**, **WILL NOT ADD FUNCTIONALITY TO THEM**, and **WILL NO LONGER BE SUPPORTED AFTER**
+
+Option1 : <#of versions>
+Option 2: <time period>.
+
+For details, see the [Deprecation notifications](../home/whats-new-2-17.md#deprecation-notifications).
 
 ## API Architecture
 
@@ -19,32 +31,31 @@ Below is a diagram of the Run:ai API Architecture. A developer may:
 
 ![api architecture image](img/api-architecture.png)
 
-
 ## Administrator API
 
-Add, delete, modify and list Run:ai meta-data objects such as Projects, Departments, Users, and more. 
+Add, delete, modify and list Run:ai meta-data objects such as Projects, Departments, Users, and more.
 
 The API is provided as REST and is accessible via the control plane endpoint.  
 
-For more information see [Administrator REST API](admin-rest-api/overview.md). 
+For more information see [Administrator REST API](admin-rest-api/overview.md).
 
 ## Cluster API
 
-Submit and delete Workloads. 
+Submit and delete Workloads.
 
 The API is provided as [Kubernetes API](./cluster-api/submit-yaml.md).
 
-Cluster API is accessible via the GPU cluster itself. As such, __multiple clusters may have multiple endpoints__.
+Cluster API is accessible via the GPU cluster itself. As such, **multiple clusters may have multiple endpoints**.
 
 !!! Note
-    The same functionality is also available via the [Run:ai Command-line interface](../Researcher/cli-reference/Introduction.md). The CLI provides an alternative for automating with shell scripts. 
+    The same functionality is also available via the [Run:ai Command-line interface](../Researcher/cli-reference/Introduction.md). The CLI provides an alternative for automating with shell scripts.
+
 ## Metrics API
 
-Retrieve metrics from multiple GPU clusters. 
+Retrieve metrics from multiple GPU clusters.
 
 See the [Metrics API](metrics/metrics.md) document.
 
 ## API Authentication
 
 See [API Authentication](rest-auth.md) for information on how to gain authenticated access to Run:ai APIs.
-

docs/developer/rest-auth.md

@@ -1,75 +1,67 @@
 
 # API Authentication
 
+The following document explains how to authenticate with Run:ai APIs.
 
-The following document explains how to authenticate with Run:ai APIs. 
-
-Run:ai APIs are accessed using _bearer tokens_. A token can be obtained in several ways:
+Run:ai APIs are accessed using *bearer tokens*. A token can be obtained in several ways:
 
 * When logging into the Run:ai user interface, you enter an email and password (or authenticated via single sign-on) which are used to obtain a token.
 * When using the Run:ai command-line, you use a Kubernetes profile and are authenticated by pre-running `runai login` (or oc login with OpenShift). The command attaches a token to the profile and allows you access to Run:ai functionality.
-* When using Run:ai APIs, you need to create an __Application__ through the Run:ai user interface. The Application is created with specific roles and contains a _secret_. Using the secret you can obtain a token and use it within subsequent API calls.
+* When using Run:ai APIs, you need to create an **Application** through the Run:ai user interface. The Application is created with specific roles and contains a *secret*. Using the secret you can obtain a token and use it within subsequent API calls.
 
 ## Create a Client Application
 
 * Open the Run:ai Run:ai User Interface.
-* Go to `Settings | Application` and create a new Application. 
-* Set the required roles:
-    * Select `Researcher` to manipulate _Jobs_ using the [Cluster API](cluster-api/submit-rest.md). To provide access to a specific project, you will also need to go to `Application | Projects` and provide the Application with access to specific projects. 
-    * Select `Editor` to manipulate _Projects_ and _Departments_ using the [Administrator REST API](admin-rest-api/overview.md). 
-    * Select `Administrator` to manipulate _Users_, _Tenant Settings_ and _Clusters_ using the [Administrator REST API](admin-rest-api/overview.md).
-* Copy the `<APPLICATION-NAME>` and `<CLIENT-SECRET>` to be used below
-* Go to `Settings | General`, under `Researcher Authentication` copy `<REALM>`.
+* Go to `Settings & Tools`, `Application` and create a new Application.
+* Copy the `<APPLICATION>` and `<SECRET KEY>` to be used below
 
-!!! Important Note
-    Creating Client Application tokens is only available with SaaS installations where the tenant has been created post-January 2022 or any Self-hosted installation. If you are an administrator but do not see the `Settings | Application` area, please contact Run:ai customer support.  
+### Access rules for the Application
+
+* Set the required roles:
+    * Select `Researcher` to manipulate *Jobs* using the [Cluster API](cluster-api/submit-rest.md). To provide access to a specific project, you will also need to go to `Application | Projects` and provide the Application with access to specific projects.
+    * Select `Editor` to manipulate *Projects* and *Departments* using the [Administrator REST API](admin-rest-api/overview.md).
+    * Select `Administrator` to manipulate *Users*, *Tenant Settings* and *Clusters* using the [Administrator REST API](admin-rest-api/overview.md).
 
 ## Request an API Token
 
-Use the above parameters to get a temporary token to access Run:ai as follows. 
+Use the above parameters to get a temporary token to access Run:ai as follows.
 
-### Example command to get an API token 
+### Example command to get an API token
 
-Replace `<COMPANY-URL>` below with  `app.run.ai` for SaaS installations (not `<company>.run.ai`) or the Run:ai user interface URL for Self-hosted installations.
+Replace `<COMPANY-URL>` below with:
+
+  * For SaaS installations use `<company>.run.ai` 
+  * For self-hosted use the Run:ai user interface URL.
 
 === "cURL"
     ``` bash
-    curl -X POST 'https://<COMPANY-URL>/auth/realms/<REALM>/protocol/openid-connect/token' \
-    --header 'Content-Type: application/x-www-form-urlencoded' \
-    --data-urlencode 'grant_type=client_credentials' \
-    --data-urlencode 'scope=openid' \
-    --data-urlencode 'response_type=id_token' \
-    --data-urlencode 'client_id=<APPLICATION-NAME>' \
-    --data-urlencode 'client_secret=<CLIENT-SECRET>'
+        curl  -X POST \
+          'https://<runai_url>/api/v1/token' \
+          --header 'Accept: */*' \
+          --header 'Content-Type: application/json' \
+          --data-raw '{
+          "grantType":"app_token",
+          "AppId":"<APPLICATION NAME>",
+          "AppSecret" : "<SECRET KEY>"
+        }'
     ```
 
 === "Python"
     ``` python
-    import requests
-    import json
-
-    COMPANY_URL = "app.run.ai"
-    COMPANY_REALM = "acme"
-    APPLICATION_NAME = "app-name"
-    CLIENT_SECRET = "secret"
-
-    def  runai_authenticate():    
-        url = "https://" + COMPANY_URL + "/auth/realms/" +  \
-            COMPANY_REALM + "/protocol/openid-connect/token"
-
-        payload = 'grant_type=client_credentials&scope=openid&response_type=id_token&client_id=' + \
-            APPLICATION_NAME + '&client_secret=' + CLIENT_SECRET
-        headers = {
-            'Content-Type': 'application/x-www-form-urlencoded'
+        import requests
+        import json
+        reqUrl = "https://cp-590d-run-13764-kc-upgrade.runailabs.com/api/v1/token"
+        headersList = {
+         "Accept": "*/*",
+         "Content-Type": "application/json"
         }
-        
-        response = requests.request("POST", url, headers=headers, data=payload)
-        if response.status_code //100 == 2:
-            j = json.loads(response.text)
-            return j["access_token"]
-        else:
-            print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))
-            return
+        payload = json.dumps({
+          "grantType":"app_token",
+          "AppId":"<APPLICATION NAME>",
+          "AppSecret" : "<SECRET KEY>"
+        })
+        response = requests.request("POST", reqUrl, data=payload,  headers=headersList)
+        print(response.text)
     ```
 
 ### Response
@@ -78,19 +70,11 @@ The API response will look as follows:
 
 ``` JSON title="API Response"
 {
-  "access_token": "...", // (1)
-  "expires_in": 36000,
-   ....
-  "token_type": "bearer"
-  "id_token": "..."
+  "accessToken": "<TOKEN>", 
 }
 ```
 
-1. Use the `id_token` as the Bearer token below.
-
-
-To call APIs, the application must pass the retrieved `access_token` as a Bearer token in the Authorization header of your HTTP request.
-
-* To retrieve and manipulate Workloads, use the [Cluster API](cluster-api/workload-overview-dev.md). Researcher API works at the cluster level and you will have different endpoints for different clusters. 
-* To retrieve and manipulate other metadata objects, use the [Administrator REST API](admin-rest-api/overview.md). Administrator API works at the control-plane level and you have a single endpoint for all clusters. 
+To call APIs, the application must pass the retrieved `accessToken` as a *Bearer token* in the Authorization header of your HTTP request.
 
+* To retrieve and manipulate Workloads, use the [Cluster API](cluster-api/workload-overview-dev.md). Researcher API works at the cluster level and you will have different endpoints for different clusters.
+* To retrieve and manipulate other metadata objects, use the [Administrator REST API](admin-rest-api/overview.md). Administrator API works at the control-plane level and you have a single endpoint for all clusters.