diff --git a/docs/about.md b/docs/about.md index d2ab6e6f..03fb3fbc 100644 --- a/docs/about.md +++ b/docs/about.md @@ -1,4 +1,4 @@ -# About +# Acknowledgements OSCAR has been developed by the [Grid and High Performance Computing Group (GRyCAP)](https://www.grycap.upv.es/) @@ -9,10 +9,19 @@ from the [Universitat Politècnica de València (UPV)](http://www.upv.es/). [![i3M)](images/i3m.png)](https://www.i3m.upv.es/) [![UPV](images/upv.png)](http://www.upv.es/) -This development is partially funded by the -[EGI Strategic and Innovation Fund](https://www.egi.eu/about/egi-council/egi-strategic-and-innovation-fund/) -and it can be deployed in the EGI Platform through the -[EGI Applications on Demand portal](https://www.egi.eu/services/applications-on-demand/). +OSCAR has been supported by the following projects: + + - [EGI Strategic and Innovation Fund](https://documents.egi.eu/public/ShowDocument?docid=3298). + - OSCARISER (Open Serverless Computing for the Adoption of Rapid Innovation on Secure Enterprise-ready Resources). Project PDC2021-120844-I00 funded by MICIU/AEI/10.13039/501100011033 and by the European Union NextGenerationEU/PRTR + - SERCLOCO (Serverless Scientific Computing Across the Hybrid Cloud Continuum). Grant PID2020-113126RB-I00 funded by MICIU/AEI/10.13039/501100011033. + - [AI-SPRINT](http://ai-sprint-project.eu) (AI in Secure Privacy-Preserving Computing Continuum) that has received funding from the European Union’s Horizon 2020 Research and Innovation Programme under Grant 101016577. + - [AI4EOSC](http://ai4eosc.eu) (Artificial Intelligence for the European Open Science Cloud) that has received funding from the European Union’s Horizon Europe Research and Innovation Programme under Grant 101058593. + - [interTwin](https://www.intertwin.eu) (An interdisciplinary Digital Twin Engine for science) that has received funding from the European Union’s Horizon Europe Programme under Grant 101058386. + + + + + ## Contact diff --git a/docs/api.md b/docs/api.md index 53f05d1f..07afb9af 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,8 +1,7 @@ -# OpenAPI Specification +# OSCAR API OSCAR exposes a secure REST API available at the Kubernetes master's node IP -through an ingress. This API has been described following the -[OpenAPI Specification](https://www.openapis.org/) and it can be -consulted below. +through an Ingress Controller. This API has been described following the +[OpenAPI Specification](https://www.openapis.org/) and it is available below. !!swagger api.yaml!! diff --git a/docs/deploy-ec3.md b/docs/deploy-ec3.md index edf6c4a0..5a4effcd 100644 --- a/docs/deploy-ec3.md +++ b/docs/deploy-ec3.md @@ -1,8 +1,11 @@ # Deployment with EC3 +> ❗️ +> The deployment of OSCAR with EC3 is deprecated. Please, consider using the [IM Dashboard](deploy-im-dashboard.md). + In order to deploy an elastic Kubernetes cluster with the OSCAR platform, it is preferable to use the -[IM Dashboard](https://appsgrycap.i3m.upv.es:31443/im-dashboard). +[IM Dashboard](https://im.egi.eu). Alternatively, you can also use [EC3](https://github.com/grycap/ec3), a tool that deploys elastic virtual clusters. EC3 uses the [Infrastructure Manager (IM)](https://www.grycap.upv.es/im) to deploy such diff --git a/docs/deploy-helm.md b/docs/deploy-helm.md index 9eadf11c..4cd1d082 100644 --- a/docs/deploy-helm.md +++ b/docs/deploy-helm.md @@ -1,4 +1,4 @@ -# Deployment on an existing Kubernetes cluster using Helm +# Deployment with Helm OSCAR can also be deployed on any existing Kubernetes cluster through its [helm chart](https://github.com/grycap/helm-charts/tree/master/oscar). diff --git a/docs/deploy-im-dashboard.md b/docs/deploy-im-dashboard.md index a6c2c426..d853d258 100644 --- a/docs/deploy-im-dashboard.md +++ b/docs/deploy-im-dashboard.md @@ -1,11 +1,10 @@ -# Deployment with the IM Dashboard +# Deployment with IM -An OSCAR cluster can be easily deployed on multiple Cloud back-ends without -requiring any installation by using the +An OSCAR cluster can be easily deployed on multiple Cloud platforms via the [Infrastructure Manager](https://www.grycap.upv.es/im)'s Dashboard -([IM Dashboard](https://appsgrycap.i3m.upv.es:31443/im-dashboard/login)). This -is a managed service provided by the [GRyCAP](https://www.grycap.upv.es) +([IM Dashboard](https://im.egi.eu)). This +is a managed service provided by [EGI](https://www.egi.eu) and operated by the [GRyCAP](https://www.grycap.upv.es) research group at the [Universitat Politècnica de València](https://www.upv.es) to deploy customized virtual infrastructures across many Cloud providers. @@ -16,19 +15,19 @@ services (e.g. MinIO). This example shows how to deploy an OSCAR cluster on [Amazon Web Services (AWS)](https://aws.amazon.com) with two nodes. Thanks to -the IM, the very same procedure applies to deploy the OSCAR cluster in an +the IM, the very same procedure allows to deploy the OSCAR cluster in an on-premises Cloud (such as OpenStack) or any other Cloud provider supported by the IM. These are the steps: -1. Access the [IM Dashboard](https://appsgrycap.i3m.upv.es:31443/im-dashboard/login) +1. Access the [IM Dashboard](https://im.egi.eu) ![login](images/im-dashboard/im-dashboard-00.png) You will need to authenticate via [EGI Check-In](https://www.egi.eu/services/check-in/), which supports - mutiple Identity Providers (IdP). + mutiple Identity Providers (IdP). There is no need to register and the service is provided free of charge. 1. Configure the Cloud Credentials @@ -43,41 +42,49 @@ These are the steps: ![credentials](images/im-dashboard/im-dashboard-00-4.png) - In our case we indicate an identifier for the set of credentials, + In our case, we indicate an identifier for the set of credentials, [the Access Key ID and the Secret Access Key](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html) for an [IAM](https://aws.amazon.com/iam/) user that has privileges to - deploy Virtual Machines in [Amazon EC2](https://aws.amazon.com/ec2). + deploy Virtual Machines in [Amazon EC2](https://aws.amazon.com/ec2). With the default values indicated in this tutorial, you will need privileges to deploy the following instance types: ```t3a.xlarge``` for the front-end node and ```t3a.medium``` for the working node. 1. Select the OSCAR template ![template](images/im-dashboard/im-dashboard-01.png) + + + There are optional features than can be included in the OSCAR cluster to fit particular user needs. We'll skip them. + + ![template-config](images/im-dashboard/im-dashboard-01-2.png) + + 1. Customize and deploy the OSCAR cluster In this panel you can specify the number of Working Nodes (WNs) of the cluster together with the computational requirements for each node. We leave the default values. - - Number of WNs in the oscar cluster: Number of working nodes. - - Number of CPUs for the front-end node: Number of CPUs in the primary node. - - Amount of Memory for the front-end node: RAM in the primary node. - - Flavor name of the front-end node. Only required in case of special flavors i.e. with GPUs: Type of instance that will be selected in the front node. - - Number of CPUs for the WNs: number of CPUs per working node. - - Amount of Memory for the WNs: RAM per working node. - - Flavor name of the WNs. Only required in case of special flavors i.e. with GPUs: Type of instance that will be selected in the working nodes. - - Size of the extra HD added to the instance: Extra memory in the primary node. + + - Number of WNs in the OSCAR cluster. + - Number of CPUs for the front-end node. + - Amount of Memory (RAM) for the front-end node + - Flavor name of the front-end node. This is only required in case of special flavors (i.e. with GPUs): Instance type that will be selected for the front-end node. + - Number of CPUs for the WNs (Working Nodes). + - Amount of Memory (RAM) for the WNs. + - Flavor name of the WNs. Again, this is only required in case of special flavors + - Size of the extra HD (Hard Disk) added to the node. ![template-hw](images/im-dashboard/im-dashboard-02.png) - In this panel, specify the passwords to be employed to access the - Kubernetes Web UI (Dashboard), to access the OSCAR web UI and to access - the MinIO dashboard. These tokens can also be used for programmatic access + In the following panel, specify the passwords to be employed to access the + Kubernetes Web UI (Dashboard), to access OSCAR and to access + the MinIO dashboard. These passwords/tokens can also be used for programmatic access to the respective services. - - Access Token for the Kubernetes admin user: It is the token to connect to the Dashboard of Kubernetes. - - OSCAR password: password to OSCAR. - - MinIO password 8 characters min.: password to MinIO. - - Email to be used in the Lets Encrypt issuer: It is an Email linked with the certificates in case the user has any questions. - - ID of the user that creates the infrastructure: unique identifier. Do not touch. - - VO to support: It supports OIDC log in. If there is nothing, only can connect the user who deploys, in case there is a VO, it can be the user who deploys and all people in the VO. + - Access Token for the Kubernetes admin user: Used to connect to the Kubernetes Dashboard. + - OSCAR password: To log in to the OSCAR cluster as an admin user. + - MinIO password (8 characters min.). + - Email to be used in the Let's Encrypt issuer. + - ID of the user that creates the infrastructure. + - VO (Virtual Organization) to support: It supports OIDC (OpenID Connect) log in. If empty, only the user who deploys the cluster can log in. If a VO is specified, all the members of the VO can log in the OSCAR cluster. - Flag to add NVIDIA support: if you want to use NVIDIA. - Flag to install Apache YuniKorn: if you are going to use YuniKorn. ![template-param](images/im-dashboard/im-dashboard-03.png) @@ -100,8 +107,8 @@ These are the steps: 1. Check the status of the deployment OSCAR cluster You will see that the OSCAR cluster is being deployed and the - infrastructure reaches the status "running". The process will not finish - until it reaches the state "configured". + infrastructure reaches the status "running". The process will finish + when it reaches the state "configured". ![status-general](images/im-dashboard/im-dashboard-05.png) @@ -115,17 +122,13 @@ These are the steps: Once reached the "configured" state, see the "Outputs" to obtain the different endpoints: - * console_minio_endpoint: This endpoint brings access to the MinIO web - user interface. - * dashboard_endpoint: This endpoint redirects to the Kubernetes dashboard - where the OSCAR cluster is deployed. - * local_oscarui_endpoint: This endpoint is where the OSCAR backend is - listening. It supports authentication only via basic-auth. + * console_minio_endpoint: To access the MinIO web UI. + * dashboard_endpoint: To access the Kubernetes dashboard. + * local_oscarui_endpoint: To access the OSCAR UI. It supports username/password authentication. * minio_endpoint: Endpoint where the MinIO API is listening. If you access it through a web browser, you will be redirected to "console_minio_endpoint". - * oscarui_endpoint: Public endpoint of the OSCAR web user interface. It - supports OIDC connections via EGI Check-in, as well as basic auth. + * oscarui_endpoint: To access the OSCAR UI. This one supports both username/password authentication and authentication via EGI Check-In for the user who deployed the OSCAR cluster and the users belonging to the VO specified at deployment time, if any. ![outputs](images/im-dashboard/im-dashboard-07.png) diff --git a/docs/deploy-ansible.md b/docs/deploy-k3s-ansible.md similarity index 98% rename from docs/deploy-ansible.md rename to docs/deploy-k3s-ansible.md index 4fb55e54..beb2fcb7 100644 --- a/docs/deploy-ansible.md +++ b/docs/deploy-k3s-ansible.md @@ -1,4 +1,4 @@ -# Ansible playbook to deploy K3s and the OSCAR platform +# Deployment on K3s with Ansible The folder [`deploy/ansible`](https://github.com/grycap/oscar/tree/master/deploy/ansible) diff --git a/docs/devel-docs.md b/docs/devel-docs.md new file mode 100644 index 00000000..6b020783 --- /dev/null +++ b/docs/devel-docs.md @@ -0,0 +1,17 @@ +# Documentation development + +OSCAR uses [MKDocs](https://www.mkdocs.org) for the documentation. In particular, [Material for MKDocs](https://squidfunk.github.io/mkdocs-material/). + +Install the following dependencies: + +```sh +pip install mkdocs mkdocs-material mkdocs-render-swagger-plugin +``` + +The from the main folder `oscar` run: + +```sh +mkdocs serve +``` + +The documentation will be available in [http://127.0.0.1:8000](http://127.0.0.1:8000) diff --git a/docs/egi-integration.md b/docs/egi-integration.md deleted file mode 100644 index e7d285cd..00000000 --- a/docs/egi-integration.md +++ /dev/null @@ -1,54 +0,0 @@ -# Integration with the EGI Federated Cloud - -[EGI](https://www.egi.eu/) is a federation of many cloud providers and -hundreds of data centres, spread across Europe and worldwide that delivers -advanced computing services to support scientists, multinational projects and -research infrastructures. - -The [EGI Federated Cloud](https://www.egi.eu/federation/egi-federated-cloud/) -is an IaaS-type cloud, made of academic private clouds and virtualised -resources and built around open standards. Its development is driven by -requirements of the scientific communities. - -## EGI Applications on Demand: IM Dashboard - -The OSCAR platform can be deployed on the EGI Federated Cloud resources -through the [IM Dashboard](https://appsgrycap.i3m.upv.es:31443/im-dashboard/) -available in the -[EGI Applications on Demand](https://marketplace.egi.eu/42-applications-on-demand) -service. - -The [IM Dashboard documentation](https://docs.egi.eu/users/compute/orchestration/im/dashboard/) -can be followed in order to deploy the platform. - -![OSCAR on IM](images/oscar-egi-im.png) - -## EGI DataHub - -[EGI DataHub](https://datahub.egi.eu/), based on -[Onedata](https://onedata.org/#/home), provides a global data access solution -for science. Integrated with the EGI AAI, it allows users to have Onedata -spaces supported by providers across Europe for replicated storage and -on-demand caching. - -EGI DataHub can be used as an output storage provider for OSCAR, allowing -users to store the resulting files of their OSCAR services on a Onedata -space. This can be done thanks to the -[FaaS Supervisor](https://github.com/grycap/faas-supervisor). Used in OSCAR -and [SCAR](https://github.com/grycap/scar), responsible for managing the data -Input/Output and the user code execution. - -To deploy a function with Onedata as output storage provider you only have to -specify an identifier, the URL of the Oneprovider host, your access token and -the name of your Onedata space in the "Storage" tab of the service creation -wizard: - -![Onedata provider](images/onedata-provider.png) - -And the path where you want to store the files in the "OUTPUTS" tab: - -![Onedata output](images/onedata-output.png) - -This means that scientists can store their output files on their Onedata space -in the EGI DataHub for long-time persistence and easy sharing of experimental -results between researchers. diff --git a/docs/expose_services.md b/docs/exposed-services.md similarity index 57% rename from docs/expose_services.md rename to docs/exposed-services.md index 2000725f..00ed25d6 100644 --- a/docs/expose_services.md +++ b/docs/exposed-services.md @@ -1,43 +1,59 @@ +# Exposed Services -OSCAR supports the deployment and elasticity management of long-running services that must be directly reachable outside the cluster. This functionality answers the need to support the fast inference of pre-trained AI models that require close to real-time processing with high throughput. In a traditional serverless approach, the AI model weights would be loaded in memory for each service invocation. Exposed services are also helpful when stateless services created out of large containers require too much time to start processing a service invocation. -Instead, by exposing an OSCAR service, the AI model weights could be loaded just once, and the service would perform the AI model inference for each subsequent request. An auto-scaled load-balanced approach for these stateless services is supported. When the average CPU exceeds a certain user-defined threshold, additional service instances (i.e. pods) will be dynamically created (and removed when no longer necessary) within the user-defined boundaries As mentioned previously, this kind of service provides elasticity management with a load-balanced approach. When the average CPU exceeds a certain user-defined threshold, additional service instances will be dynamically created (and removed when no longer necessary). The user can also define the minimum and maximum instances of the service to be present on the cluster (see the parameters `min_scale` and `max_scale` in [ExposeSettings](https://docs.oscar.grycap.net/fdl/#exposesettings)). +OSCAR supports the deployment and elasticity management of long-running stateless services whose internal API or web-based UI must be directly reachable outside the cluster. + +> ℹ️ +> +> This functionality can be used to support the fast inference of pre-trained AI models that require close to real-time processing with high throughput. +> In a traditional serverless approach, the AI model weights would be loaded in memory for each service invocation. +> Exposed services are also helpful when stateless services created out of large containers require too much time to start processing a service invocation. +> By exposing an OSCAR service, the AI model weights could be loaded just once, and the service would perform the AI model inference for each subsequent request. + +![OSCAR Exposed Service](images/oscar-exposed-service.png) + + + An auto-scaled load-balanced approach for these stateless services is supported. When the average CPU exceeds a certain user-defined threshold, additional service pods are dynamically created (and removed when no longer necessary) within the user-defined boundaries. The user can also define the minimum and maximum replicas of the service to be present on the cluster (see the parameters `min_scale` and `max_scale` in [ExposeSettings](fdl.md/#exposesettings)). ### Prerequisites in the container image -The container image needs to have an HTTP server that binds to a specific port (see the parameter `port` in [ExposeSettings](https://docs.oscar.grycap.net/fdl/#exposesettings)`). If developing a service from scratch in Python, you can use [FastAPI](https://fastapi.tiangolo.com/) or [Flask](https://flask.palletsprojects.com/en/2.3.x/) to create an API. In Go, you can use [Gin](https://gin-gonic.com/) or [Sinatra](https://sinatrarb.com/) in Ruby. +The container image needs to have an HTTP server that binds to a specific port (see the parameter `port` in [ExposeSettings](fdl.md/#exposesettings)). If developing a service from scratch in Python, you can use [FastAPI](https://fastapi.tiangolo.com/) or [Flask](https://flask.palletsprojects.com/en/2.3.x/) to create an API. In Go, you can use [Gin](https://gin-gonic.com/). For Ruby, you can use [Sinatra](https://sinatrarb.com/). + -Notice that if the service exposes a web-based UI, you must ensure that the content cannot only be served from the root document ('/') since the service will be exposed in a certain subpath. +> ⚠️ +> +> If the service exposes a web-based UI, you must ensure that the content cannot only be served from the root document ('/') since the service will be exposed in a certain subpath. +> ### How to define an exposed OSCAR service -The minimum definition to expose an OSCAR service is to indicate in the corresponding [FDL](https://docs.oscar.grycap.net/fdl/) the port inside the container where the service will be listening. +The minimum definition to expose an OSCAR service is to indicate in the corresponding [FDL](fdl.md) the port inside the container where the service will be listening. ``` yaml expose: api_port: 5000 ``` -Once the service is deployed, you can check if it was created correctly by making an HTTP request to the exposed endpoint, which would look like the following. +Once the service is deployed, you can check if it was created correctly by making an HTTP request to the exposed endpoint: ``` bash https://{oscar_endpoint}/system/services/{service_name}/exposed/{path_resource} ``` -Notice that if you get a `502 Bad Gateway` error, it is most likely because the specified port on the service doesn't match the API port. +Notice that if you get a `502 Bad Gateway` error, it is most likely because the specified port on the service does not match the API port. Additional options can be defined in the "expose" section of the FDL (some previously mentioned), such as: - `min_scale`: The minimum number of active pods (default: 1). - `max_scale`: The maximum number of active pods (default: 10) or the CPU threshold, which, once exceeded, will trigger the creation of additional pods (default: 80%). -- `rewrite_target`: Target the URI where the traffic is redirected. (default: false) -- `NodePort`: The access method from the domain name to the public ip :. +- `rewrite_target`: Target the URI where the traffic is redirected (default: false). +- `NodePort`: The access method from the domain name to the public ip `:`. - `default_command`: Selects between executing the container's default command and executing the script inside the container. (default: false, it executes the script) -- `set_auth`: The credentials are composed of the service name as the user and the service token as the password. Turn off this field if the container has an authentication itself. It does not work with `NodePort`.(default: false, it has no authentication) +- `set_auth`: The credentials are composed of the service name as the user and the service token as the password. Turn off this field if the container provides its own authentication method. It does not work with `NodePort` (default: false, it has no authentication). -Below is an example of the expose setion of the FDL, showing that there will be between 5 to 15 active pods and that the service will expose an API in port 4578. The number of active pods will grow when the use of CPU increases by more than 50% and the active pods will decrease when the CPU use decreases. +Below is an example of the `expose` section of the FDL, showing that there will be between 5 to 15 active pods and that the service will expose an API in port 4578. The number of active pods will grow when the use of CPU increases by more than 50% and the active pods will decrease when the CPU use decreases below that threshold. ``` yaml expose: @@ -50,7 +66,7 @@ expose: default_command: true ``` -In addition, you can see there a full example of a recipe to expose a service from the [AI4EOSC/DEEP Open Catalog](https://marketplace.deep-hybrid-datacloud.eu/) +In addition, you can see below a full example of a recipe to expose a service from the [AI4EOSC Marketplace](https://dashboard.cloud.ai4eosc.eu/marketplace): ``` yaml functions: @@ -67,7 +83,7 @@ functions: expose: min_scale: 1 max_scale: 10 - port: 5000 + api_port: 5000 cpu_threshold: 20 set_auth: true input: diff --git a/docs/fdl-composer.md b/docs/fdl-composer.md index 0b743304..9af27457 100644 --- a/docs/fdl-composer.md +++ b/docs/fdl-composer.md @@ -1,18 +1,23 @@ -# Functions Definition Language Composer +# FDL Composer -Writing an entire workflow in plain text could be a difficult task for many -users. To simplify the process you can use -[FDL Composer](http://composer.oscar.grycap.net), a web-based user interface +OSCAR Services can be aggregated into data-driven workflows where the output data of one service is stored in the object store that triggers another service, potentially in a different OSCAR cluster. This allows to execute the different phases of the workflow in disparate computing infrastructures. + + +However, writing an entire workflow in an [FDL](fdl.md) file can be a difficult task for some users. + + +To simplify the process you can use +[FDL Composer](http://composer.oscar.grycap.net), a web-based application to facilitate the definition of [FDL](https://docs.oscar.grycap.net/fdl/) YAML files for [OSCAR](https://oscar.grycap.net/) and [SCAR](https://scar.readthedocs.io). ![fdl-composer-workflow.png](images/fdl-composer/fdl-composer-workflow.png) -## How to access FDl Composer +## How to access FDL Composer + -It does not require to be installed. Just access -[FDL Composer web](https://composer.oscar.grycap.net/). If you prefer to +Just access [FDL Composer](https://composer.oscar.grycap.net/) which is a Single Page Application (SPA) running entirely in your browser. If you prefer to execute it on your computer instead of using the web, clone the git repository by using the following command: @@ -67,7 +72,7 @@ services.** ### Download and load state -The graphic workflow can be saved in a file using the "Download state" button. +The defined workflow can be saved in a file using the "Download state" button. OSCAR services, Storage Providers, and Buckets are kept in the file. The graphic workflow can be edited later by loading it with the "Load state" button. @@ -98,6 +103,6 @@ SCAR. ## Example -There is an example of fdl-composer implementing the +There is an example of FDL Composer implementing the [video-process](https://github.com/grycap/oscar/tree/master/examples/video-process) use case in our [blog](https://oscar.grycap.net/blog/post-oscar-fdl-composer/). diff --git a/docs/fdl.md b/docs/fdl.md index 53ce5db2..52e7f9a7 100644 --- a/docs/fdl.md +++ b/docs/fdl.md @@ -1,4 +1,12 @@ -# Functions Definition Language (OSCAR) +# Functions Definition Language (FDL) + + OSCAR services are typically defined via the Functions Definition Language (FDL) to be deployed via the [OSCAR CLI](oscar-cli.md). Alternative approaches are using the web-based wizard in the [OSCAR UI](usage-ui.md) or, for a programmatic integration, via the [OSCAR API](api.md). + +> ℹ️ +> +> It is called _Functions Definition Language_ instead of _Services Definition Language_, because the definition was initially designed for [SCAR](https://github.com/grycap/scar), which supports Lambda functions. + + Example: @@ -58,7 +66,7 @@ storage_providers: |------------------------------| --------------------------------------------| | `functions`
*[Functions](#functions)* | Mandatory parameter to define a Functions Definition Language file. Note that "functions" instead of "services" has been used in order to keep compatibility with [SCAR](https://github.com/grycap/scar) | | `storage_providers`
*[StorageProviders](#storageproviders)* | Parameter to define the credentials for the storage providers to be used in the services | -| `clusters`
*map[string][Cluster](#cluster)* | configuration for the OSCAR clusters that can be used as service's replicas, being the key the user-defined identifier for the cluster. Optional | +| `clusters`
*map[string][Cluster](#cluster)* | Configuration for the OSCAR clusters that can be used as service's replicas, being the key the user-defined identifier for the cluster. Optional | ## Functions @@ -71,26 +79,26 @@ storage_providers: | Field | Description | |------------------------------| --------------------------------------------| | `name`
*string* | The name of the service | -| `cluster_id`
*string* | Identifier for the current cluster, used to specify the cluster's StorageProvider in job delegations. OSCAR-CLI sets it using the ClusterID from the FDL. Optional. (default: "") | +| `cluster_id`
*string* | Identifier for the current cluster, used to specify the cluster's StorageProvider in job delegations. OSCAR-CLI sets it using the _cluster_id_ from the FDL. Optional. (default: "") | | `image`
*string* | Docker image for the service | | `vo`
*string* | Virtual Organization (VO) in which the user creating the service is enrolled. Optional (default: "") | -| `allowed_users`
*string array* | Array EGI UIDs to grant specific users permissions over the service. If empty, the service is viewed as public. (Enabled since OSCAR version v3.0.0). | -| `alpine`
*boolean* | Alpine parameter to set if image is based on Alpine. If `true` a custom release of faas-supervisor will be used. Optional (default: false) | -| `script`
*string* | Local path to the user script to be executed in the service container | -| `file_stage_in`
*bool* | Parameter to skip the download of the input files by the FaaS Supervisor (default: false) | +| `allowed_users`
*string array* | Array of EGI UIDs to grant specific user permissions on the service. If empty, the service is considered as accesible to all the users with access to the OSCAR cluster. (Enabled since OSCAR version v3.0.0). | +| `alpine`
*boolean* | Set if the Docker image is based on Alpine. If `true`, a custom release of the [faas-supervisor](https://github.com/grycap/faas-supervisor) will be used. Optional (default: false) | +| `script`
*string* | Local path to the user script to be executed inside the container created out of the service invocation | +| `file_stage_in`
*bool* | Skip the download of the input files by the [faas-supervisor](https://github.com/grycap/faas-supervisor) (default: false) | | `image_pull_secrets`
*string array* | Array of Kubernetes secrets. Only needed to use private images located on private registries. | `allowed_users`
*string array* | Array of EGI UIDS to allow specific users to interact with the service. (Can be used since version of OSCAR v3.0.0) | | `memory`
*string* | Memory limit for the service following the [kubernetes format](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-memory). Optional (default: 256Mi) | | `cpu`
*string* | CPU limit for the service following the [kubernetes format](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu). Optional (default: 0.2) | -| `enable_gpu`
*bool* | Parameter to enable the use of GPU for the service. Requires a device plugin deployed on the cluster (More info: [Kubernetes device plugins](https://kubernetes.io/docs/tasks/manage-gpus/scheduling-gpus/#using-device-plugins)). Optional (default: false) | -| `enable_sgx`
*bool* | Parameter to enable the use of SGX plugin on the cluster containers. (More info: [SGX plugin documentation](https://sconedocs.github.io/helm_sgxdevplugin/)). Optional (default: false) | -| `image_prefetch`
*bool* | Parameter to enable the use of image caching. Optional (default: false) | -| `total_memory`
*string* | Limit for the memory used by all the service's jobs running simultaneously. Apache YuniKorn scheduler is required to work. Same format as Memory, but internally translated to MB (integer). Optional (default: "") | -| `total_cpu`
*string* | Limit for the virtual CPUs used by all the service's jobs running simultaneously. Apache YuniKorn scheduler is required to work. Same format as CPU, but internally translated to millicores (integer). Optional (default: "") | +| `enable_gpu`
*bool* | Enable the use of GPU. Requires a device plugin deployed on the cluster (More info: [Kubernetes device plugins](https://kubernetes.io/docs/tasks/manage-gpus/scheduling-gpus/#using-device-plugins)). Optional (default: false) | +| `enable_sgx`
*bool* | Enable the use of SGX plugin on the cluster containers. (More info: [SGX plugin documentation](https://sconedocs.github.io/helm_sgxdevplugin/)). Optional (default: false) | +| `image_prefetch`
*bool* | Enable the use of image prefetching (retrieve the container image in the nodes when creating the service). Optional (default: false) | +| `total_memory`
*string* | Limit for the memory used by all the service's jobs running simultaneously. [Apache YuniKorn](https://yunikorn.apache.org)'s' scheduler is required to work. Same format as Memory, but internally translated to MB (integer). Optional (default: "") | +| `total_cpu`
*string* | Limit for the virtual CPUs used by all the service's jobs running simultaneously. [Apache YuniKorn](https://yunikorn.apache.org)'s' scheduler is required to work. Same format as CPU, but internally translated to millicores (integer). Optional (default: "") | | `synchronous`
*[SynchronousSettings](#synchronoussettings)* | Struct to configure specific sync parameters. This settings are only applied on Knative ServerlessBackend. Optional. | -| `expose`
*[ExposeSettings](#exposesettings)* | Struct to expose services. Optional. | +| `expose`
*[ExposeSettings](#exposesettings)* | Allows to expose the API or UI of the application run in the OSCAR service outside of the Kubernetes cluster. Optional. | | `replicas`
*[Replica](#replica) array* | List of replicas to delegate jobs. Optional. | | `rescheduler_threshold`
*string* | Time (in seconds) that a job (with replicas) can be queued before delegating it. Optional. | -| `log_level`
*string* | Log level for the FaaS Supervisor. Available levels: NOTSET, DEBUG, INFO, WARNING, ERROR and CRITICAL. Optional (default: INFO) | +| `log_level`
*string* | Log level for the [faas-supervisor](https://github.com/grycap/faas-supervisor). Available levels: NOTSET, DEBUG, INFO, WARNING, ERROR and CRITICAL. Optional (default: INFO) | | `input`
*[StorageIOConfig](#storageioconfig) array* | Array with the input configuration for the service. Optional | | `output`
*[StorageIOConfig](#storageioconfig) array* | Array with the output configuration for the service. Optional | | `environment`
*[EnvVarsMap](#envvarsmap)* | The user-defined environment variables assigned to the service. Optional | @@ -129,7 +137,7 @@ storage_providers: | Field | Description | |------------------------------| --------------------------------------------| -| `storage_provider`
*string* | Reference to the storage provider defined in [storage_providers](#storage_providers). This string is composed by the provider's name (minio, s3, onedata) and identifier (defined by the user), separated by a point (e.g. "minio.myidentifier") | +| `storage_provider`
*string* | Reference to the storage provider defined in [storage_providers](#storage_providers). This string is composed by the provider's name (minio, s3, onedata) and the identifier (defined by the user), separated by a point (e.g. "minio.myidentifier") | | `path`
*string* | Path in the storage provider. In MinIO and S3 the first directory of the specified path is translated into the bucket's name (e.g. "bucket/folder/subfolder") | | `suffix`
*string array* | Array of suffixes for filtering the files to be uploaded. Only used in the `output` field. Optional | | `prefix`
*string array* | Array of prefixes for filtering the files to be uploaded. Only used in the `output` field. Optional | @@ -145,9 +153,9 @@ storage_providers: | Field | Description | | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `minio`
*map[string][MinIOProvider](#minioprovider)* | Map to define the credentials for a MinIO storage provider, being the key the user-defined identifier for the provider | -| `s3`
*map[string][S3Provider](#s3provider)* | Map to define the credentials for a Amazon S3 storage provider, being the key the user-defined identifier for the provider | +| `s3`
*map[string][S3Provider](#s3provider)* | Map to define the credentials for an Amazon S3 storage provider, being the key the user-defined identifier for the provider | | `onedata`
*map[string][OnedataProvider](#onedataprovider)* | Map to define the credentials for a Onedata storage provider, being the key the user-defined identifier for the provider | -| `webdav`
*map[string][WebDavProvider](#webdavprovider)* | Map to define the credentials for a storage provider accesible via WebDav protocol, being the key the user-defined identifier for the provider | +| `webdav`
*map[string][WebDavProvider](#webdavprovider)* | Map to define the credentials for a storage provider accesible via WebDAV protocol, being the key the user-defined identifier for the provider | ## Cluster diff --git a/docs/images/im-dashboard/im-dashboard-00-2.png b/docs/images/im-dashboard/im-dashboard-00-2.png index fb6e8398..38dc7282 100644 Binary files a/docs/images/im-dashboard/im-dashboard-00-2.png and b/docs/images/im-dashboard/im-dashboard-00-2.png differ diff --git a/docs/images/im-dashboard/im-dashboard-00-3.png b/docs/images/im-dashboard/im-dashboard-00-3.png index 4f05d8d8..7d840c60 100644 Binary files a/docs/images/im-dashboard/im-dashboard-00-3.png and b/docs/images/im-dashboard/im-dashboard-00-3.png differ diff --git a/docs/images/im-dashboard/im-dashboard-00-4.png b/docs/images/im-dashboard/im-dashboard-00-4.png index bab1ffad..a1377c6e 100644 Binary files a/docs/images/im-dashboard/im-dashboard-00-4.png and b/docs/images/im-dashboard/im-dashboard-00-4.png differ diff --git a/docs/images/im-dashboard/im-dashboard-00.png b/docs/images/im-dashboard/im-dashboard-00.png index 8200d465..65447ed4 100644 Binary files a/docs/images/im-dashboard/im-dashboard-00.png and b/docs/images/im-dashboard/im-dashboard-00.png differ diff --git a/docs/images/im-dashboard/im-dashboard-01-2.png b/docs/images/im-dashboard/im-dashboard-01-2.png new file mode 100644 index 00000000..ba44ca34 Binary files /dev/null and b/docs/images/im-dashboard/im-dashboard-01-2.png differ diff --git a/docs/images/im-dashboard/im-dashboard-01.png b/docs/images/im-dashboard/im-dashboard-01.png index bc2e4945..694e87aa 100644 Binary files a/docs/images/im-dashboard/im-dashboard-01.png and b/docs/images/im-dashboard/im-dashboard-01.png differ diff --git a/docs/images/im-dashboard/im-dashboard-02.png b/docs/images/im-dashboard/im-dashboard-02.png index 3fdf0b66..ea7744fd 100644 Binary files a/docs/images/im-dashboard/im-dashboard-02.png and b/docs/images/im-dashboard/im-dashboard-02.png differ diff --git a/docs/images/im-dashboard/im-dashboard-03.png b/docs/images/im-dashboard/im-dashboard-03.png index d83c9abb..97d0891d 100644 Binary files a/docs/images/im-dashboard/im-dashboard-03.png and b/docs/images/im-dashboard/im-dashboard-03.png differ diff --git a/docs/images/im-dashboard/im-dashboard-04.png b/docs/images/im-dashboard/im-dashboard-04.png index f35a88d3..99d5cecc 100644 Binary files a/docs/images/im-dashboard/im-dashboard-04.png and b/docs/images/im-dashboard/im-dashboard-04.png differ diff --git a/docs/images/im-dashboard/im-dashboard-05.png b/docs/images/im-dashboard/im-dashboard-05.png index e064d87a..2b824f51 100644 Binary files a/docs/images/im-dashboard/im-dashboard-05.png and b/docs/images/im-dashboard/im-dashboard-05.png differ diff --git a/docs/images/im-dashboard/im-dashboard-06.png b/docs/images/im-dashboard/im-dashboard-06.png index 3721fbf6..6cdaf2c8 100644 Binary files a/docs/images/im-dashboard/im-dashboard-06.png and b/docs/images/im-dashboard/im-dashboard-06.png differ diff --git a/docs/images/integrations/AI-SPRINT-architecture-UPV-view-v1-BSC-UC.png b/docs/images/integrations/AI-SPRINT-architecture-UPV-view-v1-BSC-UC.png new file mode 100644 index 00000000..2ec5a050 Binary files /dev/null and b/docs/images/integrations/AI-SPRINT-architecture-UPV-view-v1-BSC-UC.png differ diff --git a/docs/images/interlink.png b/docs/images/interlink.png index cdf4bbd4..67d8f8d5 100644 Binary files a/docs/images/interlink.png and b/docs/images/interlink.png differ diff --git a/docs/images/oidc/oscar-ui.png b/docs/images/oidc/oscar-ui.png index c19b706a..b0858244 100644 Binary files a/docs/images/oidc/oscar-ui.png and b/docs/images/oidc/oscar-ui.png differ diff --git a/docs/images/oscar-async.png b/docs/images/oscar-async.png new file mode 100644 index 00000000..97d7f14c Binary files /dev/null and b/docs/images/oscar-async.png differ diff --git a/docs/images/oscar-components.png b/docs/images/oscar-components.png index 37908d61..bf8eb418 100644 Binary files a/docs/images/oscar-components.png and b/docs/images/oscar-components.png differ diff --git a/docs/images/oscar-exposed-service.png b/docs/images/oscar-exposed-service.png new file mode 100644 index 00000000..783a210b Binary files /dev/null and b/docs/images/oscar-exposed-service.png differ diff --git a/docs/images/oscar-logo.png b/docs/images/oscar-logo.png deleted file mode 100644 index fe8c6de6..00000000 Binary files a/docs/images/oscar-logo.png and /dev/null differ diff --git a/docs/images/oscar-sync.png b/docs/images/oscar-sync.png index 1ab4a9ff..5b0d0f32 100644 Binary files a/docs/images/oscar-sync.png and b/docs/images/oscar-sync.png differ diff --git a/docs/index.md b/docs/index.md index 8f3cc4fc..120e7df3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,30 +1,41 @@ # Introduction -![OSCAR-logo](images/oscar3.png) +![OSCAR logo](images/oscar3.png) -OSCAR is an open-source platform to support the event-driven serverless -computing model for data-processing applications. -It can be automatically deployed on multi-Clouds, and even on low-powered devices. -It represents the porting to an on-premises scenario of the +OSCAR is an open-source platform to support the event-driven serverless computing model for data-processing applications. It can be automatically deployed on multi-Clouds, and even on low-powered devices, to create highly-parallel event-driven data-processing serverless applications along the computing continuum. These applications execute on customized runtime environments provided by Docker containers that run on elastic Kubernetes clusters. It is also integrated with the [SCAR framework](https://github.com/grycap/scar), which supports a [High Throughput Computing Programming Model](https://scar.readthedocs.io/en/latest/prog_model.html) to create highly-parallel event-driven data-processing serverless applications that execute on customized runtime environments provided by Docker containers -run on AWS Lambda. +run on AWS Lambda and AWS Batch. -## Goal -Users upload files to a bucket and this automatically triggers the execution -of parallel invocations to a function responsible for processing each file. -Output files are delivered into an output bucket for the convenience of the -user. Highly scalable HTTP-based endpoints can also be offered to expose a generic -application. A user-provided shell script is executed inside -the container run from the user-defined Docker image to achieve the -right execution environment for the application. +## Concepts +- **OSCAR Cluster**: A Kubernetes cluster (either fixed size or elastic) configured with the OSCAR services and components. The cluster must have at least one front-end node, which executes the OSCAR control plane and one or several working nodes. +- **OSCAR Service**: The execution unit in the OSCAR framework, typically defined in [FDL](fdl.md), by a: + - Docker image, providing the customized runtime environment for an application. + - Execution requirements. + - User-defined shell script that will be executed in a dynamically-provisioned container. + - (Optional) The object storage that will trigger the execution of the OSCAR service upon a file upload. + - (Optional) The object storage(s) on which the output results of the OSCAR service will be stored. + - (Optional) Deployment strategy and additional configuration. -## Components -![oscar arch](images/oscar-arch.png) +## Rationale + +Users create OSCAR services to: + + - Execute a containerized command-line application or web service in response to: + - a file upload to an object store (e.g. [MinIO](http://min.io)), thus supporting loosely-coupled High-Throughput Computing use cases where many files need to be processed in parallel in a distributed computing platform. + - a request to a load-balanced auto-scaled HTTP-based endpoints, thus allowing to exposed generic scientific applications as highly-scalable HTTP endpoints. + - Execute a pipeline of multiple OSCAR service where the output data of one triggers the execution of another OSCAR service, potentially running in different clusters, thus creating event-driven scalable pipelines along the computing continuum. + +An admin user can deploy an OSCAR cluster on a Cloud platform so that other users belonging to a Virtual Organization (VO) can create OSCAR services. A VO is a group of people (e.g. scientists, researchers) with common interests and requirements, who need to work collaboratively and/or share resources (e.g. data, software, expertise, CPU, storage space) regardless of geographical location. OSCAR supports the VOs defined in [EGI](https://egi.eu), which are listed in the ['Operations Portal'](https://operations-portal.egi.eu/vo/a/list). EGI is the European's largest federation of computing and storage resource providers united by a mission of delivering advanced computing and data analytics services for research and innovation. + + +## Architecture & Components + +![OSCAR architecture](images/oscar-arch.png) OSCAR runs on an elastic [Kubernetes](http://kubernetes.io) cluster that is deployed using: @@ -68,7 +79,11 @@ only MinIO can be used as input.* An OSCAR cluster can be easily deployed via the [IM Dashboard](http://im.egi.eu) on any major public and on-premises Cloud provider, including the EGI Federated Cloud. +A summary of the components used: + +![OSCAR components](images/oscar-components.png) + An OSCAR cluster can be accessed via its -[REST API](https://grycap.github.io/oscar/api/), the -[web-based [UI](https://github.com/grycap/oscar-ui) and the command-line interface provided by -[oscar-cli](https://github.com/grycap/oscar-cli). +[REST API](https://grycap.github.io/oscar/api/), the web-based +[OSCAR UI](https://github.com/grycap/oscar-ui) and the command-line interface provided by +[OSCAR CLI](https://github.com/grycap/oscar-cli). diff --git a/docs/integration-compss.md b/docs/integration-compss.md new file mode 100644 index 00000000..23eaf8d1 --- /dev/null +++ b/docs/integration-compss.md @@ -0,0 +1,10 @@ +# Integration with COMPSs + +[COMPSs](https://compss-doc.readthedocs.io/en/stable/) is a task-based programming model which aims to ease the development of applications for distributed infrastructures, such as large High-Performance clusters (HPC), clouds and container managed clusters. COMPSs provides a programming interface for the development of the applications and a runtime system that exploits the inherent parallelism of applications at execution time. + + +COMPSs support was introduced in OSCAR for the [AI-SPRINT](https://ai-sprint-project.eu) project to tackle the [Personalized Healthcare use case](https://ai-sprint-project.eu/use-cases/personalised-healthcare) in which OSCAR is employed to perform the inference phase of pre-trained models out of sensitive data captured from wearable devices. COMPSs, in particular, its Python binding named [PyCOMPSs](https://compss-doc.readthedocs.io/en/stable/Sections/09_PyCOMPSs_Notebooks/syntax/1_Basic.html), was integrated to exploit parallelism across the multiple virtual CPUs of each pod resulting from each [OSCAR service asynchronous invocation](invoking-async.md). This use case was coordinated by the [Barcelona Supercomputing Center (BSC)](https://www.bsc.es) + +![OSCAR integration with COMPSs](images/integrations/AI-SPRINT-architecture-UPV-view-v1-BSC-UC.png) + +There are several examples that showcase the COMPSs integration with OSCAR in the [examples/compss](https://github.com/grycap/oscar/tree/master/examples/compss) folder in GitHub. \ No newline at end of file diff --git a/docs/integration-egi.md b/docs/integration-egi.md new file mode 100644 index 00000000..632897d0 --- /dev/null +++ b/docs/integration-egi.md @@ -0,0 +1,89 @@ +# Integration with EGI + +[EGI](https://www.egi.eu/) is a federation of many cloud providers and +hundreds of data centres, spread across Europe and worldwide that delivers +advanced computing services to support scientists, multinational projects and +research infrastructures. + +## Deployment on the EGI Federated Cloud + +The [EGI Federated Cloud](https://www.egi.eu/federation/egi-federated-cloud/) +is an IaaS-type cloud, made of academic private clouds and virtualised +resources and built around open standards. Its development is driven by +requirements of the scientific communities. + +The OSCAR platform can be deployed on the EGI Federated Cloud resources +through the [IM Dashboard](https://im.egi.ei). + +You can follow [EGI's IM Dashboard documentation](https://docs.egi.eu/users/compute/orchestration/im/dashboard/) or the [OSCAR's IM Dasboard](deploy-im-dashboard.md) documentation. + +![OSCAR on IM](images/oscar-egi-im.png) + +## Integration with EGI Datahub (Onedata) + +[EGI DataHub](https://datahub.egi.eu/), based on +[Onedata](https://onedata.org/#/home), provides a global data access solution +for science. Integrated with the EGI AAI, it allows users to have Onedata +spaces supported by providers across Europe for replicated storage and +on-demand caching. + +EGI DataHub can be used as an output storage provider for OSCAR, allowing +users to store the resulting files of their OSCAR services on a Onedata +space. This can be done thanks to the +[FaaS Supervisor](https://github.com/grycap/faas-supervisor). Used in OSCAR +and [SCAR](https://github.com/grycap/scar), responsible for managing the data +Input/Output and the user code execution. + +To deploy a function with Onedata as output storage provider you only have to +specify an identifier, the URL of the Oneprovider host, your access token and +the name of your Onedata space in the "Storage" tab of the service creation +wizard: + +![Onedata provider](images/onedata-provider.png) + +And the path where you want to store the files in the "OUTPUTS" tab: + +![Onedata output](images/onedata-output.png) + +This means that scientists can store their output files on their Onedata space +in the EGI DataHub for long-time persistence and easy sharing of experimental +results between researchers. + + +## Integration with EGI Check-In (OIDC) + +[OSCAR API](api.md) supports OIDC (OpenID Connect) access tokens to authorize users +since release `v2.5.0`. By default, OSCAR clusters deployed via the +[IM Dashboard](deploy-im-dashboard.md) are configured to allow authorization +via basic auth and OIDC tokens using the +[EGI Check-in](https://www.egi.eu/service/check-in/) issuer. From the IM +Dashboard deployment window, users can add one +[EGI Virtual Organization](https://operations-portal.egi.eu/vo/a/list) to +grant access for all users from that VO. + +![oscar-ui.png](images/oidc/im-dashboard-oidc.png) + +### Accessing from OSCAR UI + +The static web interface of OSCAR has been integrated with EGI Check-in and +published in [ui.oscar.grycap.net](https://ui.oscar.grycap.net) to facilitate +the authorization of users. To login through EGI Checkín using OIDC tokens, +users only have to put the endpoint of its OSCAR cluster and click on the +"EGI CHECK-IN" button. + +![im-dashboard-oidc.png](images/oidc/oscar-ui.png) + +### Integration with OSCAR-CLI via OIDC Agent + +Since version `v1.4.0` [OSCAR CLI](oscar-cli.md) supports API authorization +via OIDC tokens thanks to the integration with +[oidc-agent](https://indigo-dc.gitbook.io/oidc-agent/). + +Users must install `oidc-agent` following its +[instructions](https://indigo-dc.gitbook.io/oidc-agent/installation) and +create a new account configuration for the +`https://aai.egi.eu/auth/realms/egi/` issuer. + +After that, clusters can be +added with the command [`oscar-cli cluster add`](oscar-cli.md#add) specifying +the oidc-agent account name with the `--oidc-account-name` flag. diff --git a/docs/integration-interlink.md b/docs/integration-interlink.md new file mode 100644 index 00000000..29cfb54d --- /dev/null +++ b/docs/integration-interlink.md @@ -0,0 +1,35 @@ +# Integration with interLink + + +[interLink](https://intertwin-eu.github.io/interLink/) is an open-source development that aims to provide an abstraction for executing a Kubernetes pod on any remote resource capable of managing a Container execution lifecycle. + +OSCAR uses the Kubernetes Virtual Node to translate a job request from the Kubernetes pod into a remote call. We have been using Interlink to interact with an HPC cluster. For more infomation check the [interLink landing page](https://intertwin-eu.github.io/interLink). + +![Diagram](images/interlink.png) + +## Installation and use of Interlink Node in OSCAR cluster + +The cluster Kubernetes must have at least one virtual kubelet node. Those nodes will have tagged as `type=virtual-kubelet`. So, follow these steps to [add the Virtual node](https://intertwin-eu.github.io/interLink/docs/tutorial-admins/deploy-interlink) to the Kubernetes cluster. OSCAR detects these nodes by itself. + +Once the Virtual node and OSCAR are installed correctly, you use this node by adding the name of the virtual node in the `InterLinkNodeName` variable. +Otherwise, to use a normal node of the Kubernetes cluster, leave it blank `""` + + +## Annotations, restrictions, and other things to keep in mind + +- The [OSCAR services annotations](https://docs.oscar.grycap.net/fdl/#service) persist in the virtual node and affect the behavior of the offloaded jobs. + +- The memory and CPU defined in the OSCAR services field do not affect the offloaded job. + +- To request resources in the offloaded job, use the [slurm flags](https://curc.readthedocs.io/en/latest/running-jobs/job-resources.html#slurm-resource-flags) `slurm-job.vk.io/flags`( `--job-name`, `--time=02:30:00`, `--cpus-per-task`, `--nodes`, `--mem`). For example, you can mount a system folder in an HPC cluster with the key annotation `job.vk.io/singularity-mounts` and value pattern `"--bind :"`. The offload jobs are executed in a remote HPC cluster. So, a persistent volume claim cannot be mounted. Another example is the annotation `job.vk.io/pre-exec`, which will execute a command before each execution. + +- Any environment variable with a special character could create an error in the translation between the virtual node and the remote job. As a good practice, pass the environment variable encode in Base64 and decode it inside the execution of the script. + +Please note that interLink uses singularity to run a container with these characteristics: + +- You must reference the image container as singularity pattern `docker://ghcr.io/intertwin-eu/itwinai:0.0.1-3dgan-0.2`. Once the image is pulled, the image can be referenced by path `/itwinaiv6.sif`. +- Your script will not run as a privileged user in the container. Therefore, you cannot write in the regular file system. Use the `/tmp` folder. +- The working directory is not the same in the container. Therefore, use absolute paths. + + +The support for interLink was integrated in the context of the [interTwin](https://www.intertwin.eu) project, with support from [Istituto Nazionale di Fisica Nucleare - INFN](https://home.infn.it/it/), who developed interLink, and [CERN](https://home.cern), who provided the development of [itwinai](https://github.com/interTwin-eu/itwinai), used as a platform for advanced AI/ML workflows in digital twin applications and a use case. Special thanks to the [IZUM Center](https://en-vegadocs.vega.izum.si) in Slovenia for providing access to the [HPC Vega](https://en-vegadocs.vega.izum.si) supercomputing facility to perform the testing. \ No newline at end of file diff --git a/docs/integration-scone.md b/docs/integration-scone.md new file mode 100644 index 00000000..313f52f8 --- /dev/null +++ b/docs/integration-scone.md @@ -0,0 +1,26 @@ +# Integration with SCONE + +SCONE is a tool that allows confidential computing on the cloud thus protecting the data, code and application secrets on a Kubernetes cluster. By leveraging hardware-based security features such as [Intel SGX (Software Guard Extensions)](https://www.intel.com/content/www/us/en/products/docs/accelerator-engines/software-guard-extensions.html), SCONE ensures that sensitive data and computations remain protected even in potentially untrusted environments. This end-to-end encryption secures data both at rest and in transit, significantly reducing the risk of data breaches. Additionally, SCONE simplifies the development and deployment of secure applications by providing a seamless integration layer for existing software, thus enhancing security without requiring major code changes. + +> ⚠️ +> +> Please note that the usage of SCONE introduces a non-negligible overhead when executing the container for the OSCAR service. + + +More info about SCONE and Kubernetes [here](https://sconedocs.github.io/k8s_concepts/). + +To use SCONE on a Kubernetes cluster, Intel SGX has to be enabled on the machines, and for these, the SGX Kubernetes plugin needs to be present on the cluster. Once the plugin is installed you only need to specify the parameter `enable_sgx` on the FDL of the services that are going to use a secured container image like in the following example. + +``` yaml +functions: + oscar: + - oscar-cluster: + name: sgx-service + memory: 1Gi + cpu: '0.6' + image: your_image + enable_sgx: true + script: script.sh +``` + +SCONE support was introduced in OSCAR for the [AI-SPRINT](https://ai-sprint-project.eu) project to tackle the [Personalized Healthcare use case](https://ai-sprint-project.eu/use-cases/personalised-healthcare) in which OSCAR is employed to perform the inference phase of pre-trained models out of sensitive data captured from wearable devices. This use case was coordinated by the [Barcelona Supercomputing Center (BSC)](https://www.bsc.es) and [Technische Universität Dresden — TU Dresden](https://tu-dresden.de) was involved for the technical activities regarding SCONE. \ No newline at end of file diff --git a/docs/interlink_integration.md b/docs/interlink_integration.md deleted file mode 100644 index 12d39f55..00000000 --- a/docs/interlink_integration.md +++ /dev/null @@ -1,33 +0,0 @@ -# InterLink integration - -InterLink aims to provide an abstraction for executing a Kubernetes pod on any remote resource capable of managing a Container execution lifecycle. - -OSCAR uses the Kubernetes Virtual Node to translate a job request from the Kubernetes pod into a remote call. We have been using Interlink to interact with an HPC cluster. For more infomation check the [Interlink landing page](https://intertwin-eu.github.io/interLink). - -![Diagram](images/interlink.png) - -## Installation and use of Interlink Node in OSCAR cluster - -The cluster Kubernetes must have at least one virtual kubelet node. Those nodes will have tagged as `type=virtual-kubelet`. So, follow these steps to [add the Virtual node](https://intertwin-eu.github.io/interLink/docs/tutorial-admins/deploy-interlink) to the Kubernetes cluster. OSCAR detects these nodes by itself. - -Once the Virtual node and OSCAR are installed correctly, you use this node by adding the name of the virtual node in the `InterLinkNodeName` variable. -Otherwise, to use a normal node of the Kubernetes cluster, let in blank `""` - - -### Annotations, Restrictions, and other things to keep in mind - -The [OSCAR services annotations](https://docs.oscar.grycap.net/fdl/#service) persist in the virtual node and affect the behavior of the offload jobs. - -The memory and CPU defined in the OSCAR services field do not affect the offload job. To request resources in the offload job, use the [slurm flags](https://curc.readthedocs.io/en/latest/running-jobs/job-resources.html#slurm-resource-flags) `slurm-job.vk.io/flags`( `--job-name`, `--time=02:30:00`, `--cpus-per-task`, `--nodes`, `--mem`) - -For example, you can mount a system folder in an HPC cluster with the key annotation `job.vk.io/singularity-mounts` and value pattern `"--bind :"`. The offload jobs are executed in a remote HPC cluster. So, a persistent volume claim cannot be mounted. - -Another example is the annotation `job.vk.io/pre-exec`, which will execute a command before each execution. - -Any environment variable with a special character could create an error in the translation between the virtual node and the remote job. As a good practice, pass the environment variable encode in base64 and decode inside the execution of the script. - -As a reminder, Interlink uses singularity to run a container with this characteristic: - -- You must reference the image container as singularity pattern `docker://ghcr.io/intertwin-eu/itwinai:0.0.1-3dgan-0.2`. Once the image is pulled, the image can be referenced by path `/itwinaiv6.sif`. -- You are not a superuser. You cannot write in the regular file system. Use the /tmp folder. -- That the working directory is not the same as the container. So, work with the absolute paths. diff --git a/docs/invoking-async.md b/docs/invoking-async.md new file mode 100644 index 00000000..60119924 --- /dev/null +++ b/docs/invoking-async.md @@ -0,0 +1,12 @@ +# Asynchronous invocations + +For event-driven file processing, OSCAR automatically manages the creation +and [notification system](https://docs.min.io/minio/baremetal/monitoring/bucket-notifications/bucket-notifications.html#minio-bucket-notifications) +of MinIO buckets in order to allow the event-driven invocation of services +using asynchronous requests, generating a Kubernetes job for every file to be +processed. + + +![oscar-async.png](images/oscar-async.png) + + diff --git a/docs/invoking-sync.md b/docs/invoking-sync.md new file mode 100644 index 00000000..56fcc000 --- /dev/null +++ b/docs/invoking-sync.md @@ -0,0 +1,103 @@ +# Synchronous invocations + +Synchronous invocations allow obtaining the execution output as the response +to the HTTP call to the `/run/` path of the [OSCAR API](api.md). For this, OSCAR delegates +the execution to a serverless back-end (e.g. [Knative](https://knative.dev)) which uses an auto-scaled set of pods to process the requests. + +> ℹ️ +> +> You may find references in the documentation or examples to [OpenFaaS](https://openfaas.com), which was used in older versions of OSCAR. +> Recent versions of OSCAR use Knative as the serverless back-end for synchronous invocations, which provides several benefits such as scale-to-zero or load-balanced auto-scaled set of pods. + + +![oscar-sync.png](images/oscar-sync.png) + +Synchronous invocations can be made through [OSCAR CLI](oscar-cli.md), using the command +`oscar-cli service run`: + +```sh +oscar-cli service run [SERVICE_NAME] {--input | --text-input} {-o | -output } +``` + +You can check these examples: + +- [plant-classification-sync](https://oscar.grycap.net/blog/post-oscar-faas-sync-ml-inference/) +- [text-to-speech](https://oscar.grycap.net/blog/post-oscar-text-to-speech/). + +The input can be sent as a file via the `--input` flag, and the result of the +execution will be displayed directly in the terminal: + +```sh +oscar-cli service run plant-classification-sync --input images/image3.jpg +``` + +Alternatively, it can be sent as plain text using the `--text-input` flag and +the result stored in a file using the `--output` flag: + +```sh +oscar-cli service run text-to-speech --text-input "Hello everyone" --output output.mp3 +``` + + +### Synchronous Invocations via OSCAR CLI + +[OSCAR CLI](oscar-cli.md) simplifies the execution of services synchronously via the +[`oscar-cli service run`](oscar-cli.md#run) command. This command requires the +input to be passed as text through the `--text-input` flag or directly a file +to be sent by passing its path through the `--input` flag. Both input types +are automatically encoded in [Base64](https://en.wikipedia.org/wiki/Base64). + +It also allow setting the `--output` flag to indicate a path for storing +(and decoding if needed) the output body in a file, otherwise the output will +be shown in stdout. + +An illustration of triggering a service synchronously through OSCAR-CLI can be +found in the [cowsay example](https://github.com/grycap/oscar/tree/master/examples/cowsay#oscar-cli). + +```sh +oscar-cli service run cowsay --text-input '{"message":"Hello World"}' +``` + +### Synchronous Invocations via OSCAR API + +OSCAR services can also be invoked via traditional HTTP clients +such as [cURL](https://curl.se/) using the path `/run/` defined in the [OSCAR API](api.md) . However, +you must take care to properly format the input to one of the two supported +formats (JSON or Base64 encode) and include the +[service access token](#service-access-tokens) in the request. + +An illustration of triggering a service synchronously through cURL can be +found in the +[cowsay example](https://github.com/grycap/oscar/tree/master/examples/cowsay#curl). + +To send an input file through cURL, you must encode it in base64 or json. To avoid +issues with the output in synchronous invocations remember to put the +`log_level` as `CRITICAL`. Output, which is encoded in base64 or in json, should be +decoded as well. Save output in the expected format of the use-case. + +``` sh +base64 input.png | curl -X POST -H "Authorization: Bearer " \ + -d @- https:///run/ | base64 -d > result.png +``` + + +## Service access tokens + +As detailed in the [API specification](api.md), invocation paths require the +service access token in the request header for authentication. Service access +tokens are auto-generated in service creation and update, and MinIO eventing +system is automatically configured to use them for event-driven file +processing. Tokens can be obtained through the API, using the +[`oscar-cli service get`](oscar-cli.md#get) command or directly from the web +interface. + +![oscar-ui-service-token.png](images/usage/oscar-ui-service-token.png) + + + +### Limitations + +Although the use of the Knative Serverless Backend for synchronous invocations provides elasticity similar to the one provided by their counterparts in public clouds, such as AWS Lambda, synchronous invocations are not still the best option for run long-running resource-demanding applications, like deep learning inference or video processing. + +The synchronous invocation of long-running resource-demanding applications may lead to timeouts on Knative pods. Therefore, we consider asynchronous invocations (which generate Kubernetes jobs) as the optimal approach to handle event-driven file processing. + diff --git a/docs/invoking.md b/docs/invoking.md index ae096027..25a0664a 100644 --- a/docs/invoking.md +++ b/docs/invoking.md @@ -1,130 +1,8 @@ -# Invoking services +# Service Execution Types -OSCAR services can be invoked synchronously and asynchronously sending an -HTTP POST request to paths `/run/` and `/job/` -respectively. For file processing, OSCAR automatically manages the creation -and [notification system](https://docs.min.io/minio/baremetal/monitoring/bucket-notifications/bucket-notifications.html#minio-bucket-notifications) -of MinIO buckets in order to allow the event-driven invocation of services -using asynchronous requests, generating a Kubernetes job for every file to be -processed. +OSCAR services can be executed: -## Service access tokens + - [Synchronously](invoking-sync.md), so that the invocation to the service blocks the client until the response is obtained. Useful for short-lived service invocations. + - [Asynchronously](invoking-async.md), typically in response to a file upload to MinIO or via the OSCAR API. + - As an [exposed service](exposed-services.md), where the application executed already provides its own API or user interface (e.g. a Jupyter Notebook) -As detailed in the [API specification](api.md), invocation paths require the -service access token in the request header for authentication. Service access -tokens are auto-generated in service creation and update, and MinIO eventing -system is automatically configured to use them for event-driven file -processing. Tokens can be obtained through the API, using the -[`oscar-cli service get`](oscar-cli.md#get) command or directly from the web -interface. - -![oscar-ui-service-token.png](images/usage/oscar-ui-service-token.png) - -## Synchronous invocations - -Synchronous invocations allow obtaining the execution output as the response -to the HTTP call to the `/run/` path. For this, OSCAR delegates -the execution to a Serverless Backend ([Knative](https://knative.dev) or -[OpenFaaS](https://www.openfaas.com/)). Unlike asynchronous invocations, that -are translated into Kubernetes jobs, synchronous invocations use a "function" -pod to handle requests. This is possible thanks to the -[OpenFaaS Watchdog](https://github.com/openfaas/classic-watchdog), which is -injected into each service and is in charge of forking the process to be -executed for each request received. - -![oscar-sync.png](images/oscar-sync.png) - -Synchronous invocations can be made through OSCAR-CLI, using the comand -`oscar-cli service run`: - -```sh -oscar-cli service run [SERVICE_NAME] {--input | --text-input} {-o | -output } -``` - -You can check these use-cases: - -- [plant-classification-sync](https://oscar.grycap.net/blog/post-oscar-faas-sync-ml-inference/) -- [text-to-speech](https://oscar.grycap.net/blog/post-oscar-text-to-speech/). - -The input can be sent as a file via the `--input` flag, and the result of the -execution will be displayed directly in the terminal: - -```sh -oscar-cli service run plant-classification-sync --input images/image3.jpg -``` - -Alternatively, it can be sent as plain text using the `--text-input` flag and -the result stored in a file using the `--output` flag: - -```sh -oscar-cli service run text-to-speech --text-input "Hello everyone" --output output.mp3 -``` - -### Input/Output - -[FaaS Supervisor](https://github.com/grycap/faas-supervisor), the component in -charge of managing the input and output of services, allows JSON or base64 -encoded body in service requests. The body of these requests will be -automatically decoded into the invocation's input file available from the -script through the `$INPUT_FILE_PATH` environment variable. - -The output of synchronous invocations will depend on the application itself: - -1. If the script generates a file inside the output dir available through the - `$TMP_OUTPUT_DIR` environment variable, the result will be the file encoded in - base64. -1. If the script generates more than one file inside `$TMP_OUTPUT_DIR`, the - result will be a zip archive containing all files encoded in base64. -1. If there are no files in `$TMP_OUTPUT_DIR`, FaaS Supervisor will return its - logs, including the stdout of the user script run. - **To avoid FaaS Supervisor's logs, you must set the service's `log_level` - to `CRITICAL`.** - -This way users can adapt OSCAR's services to their own needs. - -### OSCAR-CLI - -OSCAR-CLI simplifies the execution of services synchronously via the -[`oscar-cli service run`](oscar-cli.md#run) command. This command requires the -input to be passed as text through the `--text-input` flag or directly a file -to be sent by passing its path through the `--input` flag. Both input types -are automatically encoded in base64. - -It also allow setting the `--output` flag to indicate a path for storing -(and decoding if needed) the output body in a file, otherwise the output will -be shown in stdout. - -An illustration of triggering a service synchronously through OSCAR-CLI can be -found in the [cowsay example](https://github.com/grycap/oscar/tree/master/examples/cowsay#oscar-cli). - -```sh -oscar-cli service run cowsay --text-input '{"message":"Hello World"}' -``` - -### cURL - -Naturally, OSCAR services can also be invoked via traditional HTTP clients -such as [cURL](https://curl.se/) via the path `/run/`. However, -you must take care to properly format the input to one of the two supported -formats (JSON or base64 encoded) and include the -[service access token](#service-access-tokens) in the request. - -An illustration of triggering a service synchronously through cURL can be -found in the -[cowsay example](https://github.com/grycap/oscar/tree/master/examples/cowsay#curl). - -To send an input file through cURL, you must encode it in base64 or json. To avoid -issues with the output in synchronous invocations remember to put the -`log_level` as `CRITICAL`. Output, which is encoded in base64 or in json, should be -decoded as well. Save output in the expected format of the use-case. - -``` sh -base64 input.png | curl -X POST -H "Authorization: Bearer " \ - -d @- https:///run/ | base64 -d > result.png -``` - -### Limitations - -Although the use of the Knative Serverless Backend for synchronous invocations provides elasticity similar to the one provided by their counterparts in public clouds, such as AWS Lambda, synchronous invocations are not still the best option to run long-running resource-demanding applications, like deep learning inference or video processing. - -The synchronous invocation of long-running resource-demanding applications may lead to timeouts on Knative pods. Therefore, we consider Kubernetes job generation as the optimal approach to handle event-driven file processing through asynchronous invocations in OSCAR, being the execution of synchronous services a convenient way to support general lightweight container-based applications. diff --git a/docs/local-testing.md b/docs/local-testing.md index 8cd72e2e..b312f9f1 100644 --- a/docs/local-testing.md +++ b/docs/local-testing.md @@ -1,4 +1,10 @@ -# Local Testing with kind +# Local Deployment + +> ❗️ +> +> The local deployment of OSCAR is just recommended for testing. Please, consider using the [IM](deploy-im-dashboard.md) to deploy a fully-featured OSCAR cluster in a Cloud platform. + + The easiest way to test the OSCAR platform locally is using [kind](https://kind.sigs.k8s.io/). Kind allows the deployment of Kubernetes @@ -9,18 +15,18 @@ access them. - [Docker](https://docs.docker.com/get-docker/), required by kind to launch the Kubernetes nodes on containers. -- [Kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) to +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/), to communicate with the Kubernetes cluster. -- [Helm](https://helm.sh/docs/intro/install/) to easily deploy applications on Kubernetes. -- [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) to +- [Helm](https://helm.sh/docs/intro/install/), to easily deploy applications on Kubernetes. +- [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation), to deploy the local Kubernetes cluster. -**Other prerequisites** - -- Although the use of local Docker images has yet to be implemented as a feature on OSCAR clusters, the local deployment for testing allows you to use a local Docker registry to use this kind of images. -The registry uses by default the port 5001, so each image you want to use must be tagged as `localhost:5001/[image_name]` and pushed to the repository through the `docker push localhost:5001/[image_name]` command. - -- Port 80 must be available to avoid errors during the deployment since OSCAR-UI uses it. Check [Frequently Asked Questions (FAQ)](faq.md) for more info. +> ⚠️ +> +> Although the use of local Docker images has yet to be implemented as a feature on OSCAR clusters, the local deployment for testing allows you to use a local Docker registry to use this kind of images. +>The registry uses by default the port 5001, so each image you want to use must be tagged as `localhost:5001/[image_name]` and pushed to the repository through the `docker push localhost:5001/[image_name]` command. +> +>Also, port 80 must be available to avoid errors during the deployment since OSCAR-UI uses it. Check [Frequently Asked Questions (FAQ)](faq.md) for more info. ## Automated local testing diff --git a/docs/oidc-auth.md b/docs/oidc-auth.md deleted file mode 100644 index 10f37af6..00000000 --- a/docs/oidc-auth.md +++ /dev/null @@ -1,35 +0,0 @@ -# OpenID Connect Authorization - -OSCAR REST API supports OIDC (OpenID Connect) access tokens to authorize users -since release `v2.5.0`. By default, OSCAR clusters deployed via the -[IM Dashboard](deploy-im-dashboard.md) are configured to allow authorization -via basic auth and OIDC tokens using the -[EGI Check-in](https://www.egi.eu/service/check-in/) issuer. From the IM -Dashboard deployment window, users can add one -[EGI Virtual Organization](https://operations-portal.egi.eu/vo/a/list) to -grant access for all users from that VO. - -![oscar-ui.png](images/oidc/im-dashboard-oidc.png) - -## Accessing from OSCAR-UI - -The static web interface of OSCAR has been integrated with EGI Check-in and -published in [ui.oscar.grycap.net](https://ui.oscar.grycap.net) to facilitate -the authorization of users. To login through EGI Checkín using OIDC tokens, -users only have to put the endpoint of its OSCAR cluster and click on the -"EGI CHECK-IN" button. - -![im-dashboard-oidc.png](images/oidc/oscar-ui.png) - -## Integration with OSCAR-CLI via OIDC Agent - -Since version `v1.4.0` [OSCAR-CLI](oscar-cli.md) supports API authorization -via OIDC tokens thanks to the integration with -[oidc-agent](https://indigo-dc.gitbook.io/oidc-agent/). - -Users must install the oidc-agent following its -[instructions](https://indigo-dc.gitbook.io/oidc-agent/installation) and -create a new account configuration for the -`https://aai.egi.eu/auth/realms/egi/` issuer. After that, clusters can be -added with the command [`oscar-cli cluster add`](oscar-cli.md#add) specifying -the oidc-agent account name with the `--oidc-account-name` flag. diff --git a/docs/oscar-cli.md b/docs/oscar-cli.md index 34a9e4ed..b30e1598 100644 --- a/docs/oscar-cli.md +++ b/docs/oscar-cli.md @@ -1,57 +1,53 @@ -# OSCAR-CLI +# OSCAR CLI -OSCAR-CLI provides a command line interface to interact with -[OSCAR](https://github.com/grycap/oscar) clusters in a simple way. It supports -service management, workflows definition from FDL (Functions Definition -Language) files and the ability to manage files from OSCAR's compatible +OSCAR CLI provides a command line interface to interact with +OSCAR. It supports cluster registrations, +service management, workflows definition from [FDL](fdl.md) files and the ability to manage files from OSCAR's compatible storage providers (MinIO, AWS S3 and Onedata). The folder [`example-workflow`](https://github.com/grycap/oscar-cli/tree/main/example-workflow) contains all the necessary files to create a simple workflow to test the tool. + ## Download ### Releases -The easy way to download OSCAR-CLI is through the github +The easy way to download OSCAR-CLI is through the GitHub [releases page](https://github.com/grycap/oscar-cli/releases). There are binaries for multiple platforms and OS. If you need a binary for another platform, please open an [issue](https://github.com/grycap/oscar-cli/issues). ### Install from source -If you have [go](https://golang.org/doc/install) installed and -[configured](https://github.com/golang/go/wiki/SettingGOPATH), you can get it -from source directly by executing: +If you have the [Go](https://golang.org/doc/install) programming language installed and +[configured](https://github.com/golang/go/wiki/SettingGOPATH), you can get it directly +from the source by executing: ```sh go install github.com/grycap/oscar-cli@latest ``` -### OpenID Connect +### OIDC (OpenID Connect) -Once the service is created, follow the next steps to use oscar_cli to interact with an OSCAR cluster using the OpenID Connect. +If your cluster has OIDC avaliable, follow these steps to use `oscar-cli` to interact with it using the OpenID Connect. - Install [oidc-agent](https://indigo-dc.gitbook.io/oidc-agent/intro) -- Registry the [EGI client](https://indigo-dc.gitbook.io/oidc-agent/user/oidc-gen/provider/egi) -- Add a cluster in oscar-cli with oidc credentians +- Register the [EGI client](https://indigo-dc.gitbook.io/oidc-agent/user/oidc-gen/provider/egi) +- Add a cluster in `oscar-cli` with oidc credentians (More info about the usage of the `cluster add` command [here](#add)) ``` bash oscar-cli cluster add IDENTIFIER ENDPOINT --oidc-account-name SHORTNAME ``` -- Run the service - -``` bash -oscar-cli service run plant-classification -i -c -``` - ## Available commands -- [OSCAR-CLI](#oscar-cli) + +- [OSCAR CLI](#oscar-cli) - [Download](#download) - [Releases](#releases) - [Install from source](#install-from-source) + - [OIDC (OpenID Connect)](#oidc-openid-connect) - [Available commands](#available-commands) - [apply](#apply) - [cluster](#cluster) diff --git a/docs/oscar-service.md b/docs/oscar-service.md new file mode 100644 index 00000000..b06e0ec1 --- /dev/null +++ b/docs/oscar-service.md @@ -0,0 +1,45 @@ +# OSCAR Service + +OSCAR allows the creation of serverless file-processing services based on +container images. These services require a user-defined script with the +commands responsible of the processing. The platform automatically mounts a +volume on the containers with the +[FaaS Supervisor](https://github.com/grycap/faas-supervisor) component, which +is in charge of: + +- Downloading the file that invokes the service and make it accessible through + the `INPUT_FILE_PATH` environment variable. +- Execute the user-defined script. +- Upload the content of the output folder accessible via the `TMP_OUTPUT_DIR` + environment variable. + + + +### Input/Output + +[FaaS Supervisor](https://github.com/grycap/faas-supervisor), the component in +charge of managing the input and output of services, allows JSON or base64 +encoded body in service requests. The body of these requests will be +automatically decoded into the invocation's input file available from the +script through the `$INPUT_FILE_PATH` environment variable. + +The output of synchronous invocations will depend on the application itself: + +1. If the script generates a file inside the output dir available through the + `$TMP_OUTPUT_DIR` environment variable, the result will be the file encoded in + base64. +1. If the script generates more than one file inside `$TMP_OUTPUT_DIR`, the + result will be a zip archive containing all files encoded in base64. +1. If there are no files in `$TMP_OUTPUT_DIR`, FaaS Supervisor will return its + logs, including the stdout of the user script run. + **To avoid FaaS Supervisor's logs, you must set the service's `log_level` + to `CRITICAL`.** + +This way users can adapt OSCAR's services to their own needs. + + +You can follow one of the +[examples](https://github.com/grycap/oscar/tree/master/examples) +in order to test the OSCAR framework for specific applications. We recommend +you to start with the +[plant classification example](https://github.com/grycap/oscar/tree/master/examples/plant-classification-sync). diff --git a/docs/sgx-integration.md b/docs/sgx-integration.md deleted file mode 100644 index db894706..00000000 --- a/docs/sgx-integration.md +++ /dev/null @@ -1,17 +0,0 @@ -# Integration with SCONE - -SCONE is a tool that allows confidential computing on the cloud thus protecting the data, code and application secrets on a Kubernetes cluster (More info about SCONE and Kubernetes [here](https://sconedocs.github.io/k8s_concepts/)). - -To use SCONE on a Kubernetes cluster Intel SGX has to be enabled on the machines, and for these, the SGX Kubernetes plugin needs to be present on the cluster. Once the plugin is installed you only need to specify the parameter `enable_sgx` on the FDL of the services that are going to use a secured container image like in the following example. - -``` yaml -functions: - oscar: - - oscar-cluster: - name: sgx-service - memory: 1Gi - cpu: '0.6' - image: your_image - enable_sgx: true - script: script.sh -``` \ No newline at end of file diff --git a/docs/training.md b/docs/training.md new file mode 100644 index 00000000..bf6df6f4 --- /dev/null +++ b/docs/training.md @@ -0,0 +1,12 @@ +# Presentations and Webinars + + +### Deploy your AI-based service for inference using OSCAR + +Delivered for the [AI4EOSC](https://ai4eosc.eu) and [iMagine](https://imagine-ai.eu) projects in March 2024. + + + + + + diff --git a/docs/usage.md b/docs/usage-ui.md similarity index 82% rename from docs/usage.md rename to docs/usage-ui.md index b204b457..d1594c49 100644 --- a/docs/usage.md +++ b/docs/usage-ui.md @@ -1,34 +1,19 @@ -# Using OSCAR through the web-based UI - -OSCAR allows the creation of serverless file-processing services based on -container images. These services require a user-defined script with the -commands responsible of the processing. The platform automatically mounts a -volume on the containers with the -[FaaS Supervisor](https://github.com/grycap/faas-supervisor) component, which -is in charge of: - -- Downloading the file that invokes the service and make it accessible through - the `INPUT_FILE_PATH` environment variable. -- Execute the user-defined script. -- Upload the content of the output folder accessible via the `TMP_OUTPUT_DIR` - environment variable. - -You can follow one of the -[examples](https://github.com/grycap/oscar/tree/master/examples) -in order to test the OSCAR framework for specific applications. We recommend -you to start with the -[plant classification example](https://github.com/grycap/oscar/tree/master/examples/plant-classification-sync) -detailed below. - -If you prefer to use the command-line interface rather than the web-based UI, -there is an example in -[oscar-cli's repository](https://github.com/grycap/oscar-cli/tree/main/example-workflow). +# OSCAR UI + +> ❗️ +> +> For simple OSCAR services you may use the UI, but its features may not be on par with the latest changes in the [FDL](fdl.md). +> Therefore, it is recommended to use [OSCAR CLI](oscar-cli.md) to deploy an OSCAR service. + + +This section details the usage of the OSCAR UI with the +[plant classification](https://github.com/grycap/oscar/tree/master/examples/plant-classification-sync) example, from the +[OSCAR examples](https://github.com/grycap/oscar/tree/master/examples). ## Login -OSCAR is exposed via a Kubernetes ingress and it is accessible via the -Kubernetes master node IP. If you deployed it using EC3 you can find the -credentials [here](deploy-ec3.md#default-service-endpoints). +OSCAR UI is exposed via a Kubernetes ingress and it is accessible via the +Kubernetes master node IP. ![login](images/usage/usage-01.png) @@ -39,7 +24,7 @@ After a correct login, you should see the main view: ## Deploying services In order to create a new service, you must click on the "DEPLOY NEW SERVICE" -button and follow the wizard. Remember that a script must be provided for the +button and follow the wizard. For an [OSCAR Service](oscar-service.md) a script must be provided for the processing of files. This script must use the environment variables `INPUT_FILE_PATH` and `TMP_OUTPUT_DIR` to refer to the input file and the folder where to save the results respectively: diff --git a/mkdocs.yml b/mkdocs.yml index 4b9ee86f..3d11f724 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,37 +1,64 @@ site_name: OSCAR Documentation repo_url: https://github.com/grycap/oscar nav: -- Introduction: index.md -- Getting started: - - Local testing: local-testing.md - - Deployment with IM Dashboard: deploy-im-dashboard.md - - Deployment with EC3: deploy-ec3.md - - Deployment with Helm: deploy-helm.md - - Deployment on K3s with Ansible: deploy-ansible.md -- Third party integrations: - - Integration with EGI: egi-integration.md - - OIDC Authorization: oidc-auth.md - - Integration with SCONE: sgx-integration.md - - Interlink: interlink_integration.md -- usage.md -- invoking.md -- Functions Definition Language (FDL): fdl.md -- FDL Composer: fdl-composer.md -- oscar-cli.md -- OpenAPI Specification: api.md -- Multitenancy: multitenancy.md -- Expose services: expose_services.md -- MinIO bucket replication: minio-bucket-replication.md -- Frequently Asked Questions (FAQ): faq.md +- Introduction: + - index.md + - Multitenancy: multitenancy.md + +- Deployment: + - local-testing.md + - deploy-im-dashboard.md + - deploy-ec3.md + - deploy-helm.md + - deploy-k3s-ansible.md + +- Service Definition: + - oscar-service.md + - fdl.md + - fdl-composer.md + +- Interfaces: + - oscar-cli.md + - usage-ui.md + - api.md + +- Service Execution: + - invoking.md + - invoking-sync.md + - invoking-async.md + - exposed-services.md + +- Integrations: + - integration-egi.md + - integration-scone.md + - integration-interlink.md + - integration-compss.md + +- Tutorials: + - training.md + - faq.md + +- Advanced Features: + - MinIO bucket replication: minio-bucket-replication.md + +- Development: + - Documentation: devel-docs.md - license.md - about.md + theme: favicon: images/logo.png logo: images/logo.png name: material palette: primary: teal + features: + - instant + - toc.integrate + - content.code.copy + plugins: - search - render_swagger -copyright: "© 2022, GRyCAP - i3M - Universitat Politècnica de València, Spain." \ No newline at end of file + +copyright: "© GRyCAP - I3M - Universitat Politècnica de València, Spain." \ No newline at end of file