From 7c1ecdfa39d79cebbd7cbd805c2fa02f3e302971 Mon Sep 17 00:00:00 2001 From: Yaron Date: Wed, 7 Aug 2024 16:05:42 +0300 Subject: [PATCH 1/2] api-overview --- docs/developer/metrics/metrics.md | 2 +- docs/developer/overview-developer.md | 37 +++++++++++++++++----------- mkdocs.yml | 3 +-- 3 files changed, 24 insertions(+), 18 deletions(-) diff --git a/docs/developer/metrics/metrics.md b/docs/developer/metrics/metrics.md index d8ad040726..23e84af729 100644 --- a/docs/developer/metrics/metrics.md +++ b/docs/developer/metrics/metrics.md @@ -1,5 +1,5 @@ --- -title: Metrics +title: Metrics API summary: This article shows the available metrics supported by Run:ai. authors: - Jason Novich diff --git a/docs/developer/overview-developer.md b/docs/developer/overview-developer.md index d2c995916e..827408598f 100644 --- a/docs/developer/overview-developer.md +++ b/docs/developer/overview-developer.md @@ -8,34 +8,40 @@ date: 2024-Apr-10 Developers can access Run:ai through various programmatic interfaces. -## API Support - -The endpoints and fields specified in the [API reference](https://app.run.ai/api/docs) are the ones that are officially supported by Run:ai. Endpoints and fields that are not listed in the API reference are not supported. - -Run:ai does not recommend using API endpoints and fields marked as `deprecated` and will not add functionality to them. Once an API endpoint or field is marked as `deprecated`, Run:ai will stop supporting it after 2 major releases for self-hosted deployments, and after 6 months for SaaS deployments. - -For details, see the [Deprecation notifications](../home/whats-new-2-17.md#deprecation-notifications). ## API Architecture Run:ai is composed of a single, multi-tenant control plane. Each tenant can be connected to one or more GPU clusters. See [Run:ai system components](../home/components.md) for detailed information. -Below is a diagram of the Run:ai API Architecture. A developer may: +The following programming interfaces are available: + +| API | Description | Purpose | +|---------|--------------|--------------| +| __Control Plane API__ | Access the control plane for getting and modifying business objects | This is the API mostly used by system developers. The API is also used by the Run:ai user interface as well as the __new__ command-line interface | +| __Cluster API__ | Submit Workloads directly to the Cluster | A YAML-based API allowing submittion of Workloads directly to the Cluster. With Run:ai 2.18, this API is replaced by a Control-plane API to submit jobs, which is now the recommended method | +| __Metrics API__ (deprecated) | Get cluster metrics | Get utilization metrics directly from the monitoring agent (Prometheus). This API is in the process of being deprecated and is replaced with metric-specific control plane API | -1. Access the control plane via the _Control Plane API_. -2. Access any one of the GPU clusters via _Cluster API_. -3. Access cluster metrics via the _Metrics API_. + -![api architecture image](img/api-architecture.png) + ## Control Plane API -Add, delete, modify and list Run:ai meta-data objects such as Projects, Departments, Users, and more. +Allows you to Add, delete, modify and list Run:ai meta-data objects such as Projects, Departments, Users. +For Clusters of Run:ai 2.18 and above, allows the submitting of Workloasd. The API is provided as REST and is accessible via the control plane endpoint. For more information see [Control Plane REST API](admin-rest-api/overview.md). + +!!! Important + The endpoints and fields specified in the [API reference](https://app.run.ai/api/docs) are the ones that are officially supported by Run:ai. Endpoints and fields that are not listed in the API reference are not supported. + + Run:ai does not recommend using API endpoints and fields marked as `deprecated` and will not add functionality to them. Once an API endpoint or field is marked as `deprecated`, Run:ai will stop supporting it after 2 major releases for self-hosted deployments, and after 6 months for SaaS deployments. + + For details, see the [Deprecation notifications](../home/whats-new-2-17.md#deprecation-notifications). + ## Cluster API Submit and delete Workloads. @@ -44,8 +50,9 @@ 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**. -!!! 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. +!!! Important + * With Run:ai 2.18, this API is replaced by a Control-plane API to submit jobs, which is now the recommended method for cluster versions of 2.18 and above. + * If you are looking to automate tasks, it's best to use the [Run:ai Command-line interface](../Researcher/cli-reference/Introduction.md) which provides forward compatibility. ## Metrics API diff --git a/mkdocs.yml b/mkdocs.yml index 08eb8200af..eb5c044d0b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -395,8 +395,7 @@ nav: - 'Kubernetes Workloads' : 'developer/cluster-api/other-resources.md' - 'Data Volumes': 'developer/admin-rest-api/data-volumes.md' - 'Reference' : 'developer/cluster-api/reference.md' - - 'Metrics API' : - - 'Metrics' : 'developer/metrics/metrics.md' + - 'Metrics API' : 'developer/metrics/metrics.md' # - 'Deprecated APIs' : # - 'Researcher API' : # - 'REST API' : 'developer/deprecated/researcher-rest-api/overview.md' From 621056b031037047cde0f7965989eff9d7a451c3 Mon Sep 17 00:00:00 2001 From: Yaron Date: Wed, 7 Aug 2024 16:11:51 +0300 Subject: [PATCH 2/2] api-overview --- docs/developer/overview-developer.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/developer/overview-developer.md b/docs/developer/overview-developer.md index 827408598f..bfff0a52d6 100644 --- a/docs/developer/overview-developer.md +++ b/docs/developer/overview-developer.md @@ -44,15 +44,15 @@ For more information see [Control Plane REST API](admin-rest-api/overview.md). ## Cluster API -Submit and delete Workloads. +The [Cluster API](cluster-api/workload-overview-dev.md) allows you to submit and delete Workloads directly to the cluster itself. 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**. !!! Important - * With Run:ai 2.18, this API is replaced by a Control-plane API to submit jobs, which is now the recommended method for cluster versions of 2.18 and above. - * If you are looking to automate tasks, it's best to use the [Run:ai Command-line interface](../Researcher/cli-reference/Introduction.md) which provides forward compatibility. + * This API is replaced by a Control-plane API to submit jobs, which is now the recommended method for cluster versions of 2.18 and above. + * If you are looking to automate tasks with older versions of Run:ai, it's best to use the [Run:ai Command-line interface](../Researcher/cli-reference/Introduction.md) which provides forward compatibility. ## Metrics API