diff --git a/.gitignore b/.gitignore index 5d67726..ca63303 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,7 @@ ivoatexmeta.tex gitmeta.tex role_diagram.svg -ExecutionPlanner.pdf +ExecutionBroker.pdf draft-background.pdf *.aux *.bbl diff --git a/ExecutionPlanner-draft.pdf b/ExecutionBroker-draft.pdf similarity index 100% rename from ExecutionPlanner-draft.pdf rename to ExecutionBroker-draft.pdf diff --git a/ExecPlanner.bib b/ExecutionBroker.bib similarity index 100% rename from ExecPlanner.bib rename to ExecutionBroker.bib diff --git a/ExecutionPlanner.tex b/ExecutionBroker.tex similarity index 86% rename from ExecutionPlanner.tex rename to ExecutionBroker.tex index 81d69b5..65a46d8 100644 --- a/ExecutionPlanner.tex +++ b/ExecutionBroker.tex @@ -15,16 +15,16 @@ \newcommand{\http} {HTTP} \newcommand{\datamodel} {data~model} -\newcommand{\webservice} {webservice} +\newcommand{\webservice} {web service} \newcommand{\webbrowser} {web browser} \newcommand{\ivoa} {IVOA} \newcommand{\uws} {UWS} \newcommand{\vospace} {VOSpace} -\newcommand{\execplanner} {ExecutionPlanner} -\newcommand{\execworker} {ExecutionWorker} -\newcommand{\executionplanner} {Execution~Planner} +\newcommand{\execbrokerclass} {ExecutionBroker} +\newcommand{\execworkerclass} {ExecutionWorker} +\newcommand{\executionbroker} {Execution~Broker} \newcommand{\executionplanning} {Execution~Planning} \newcommand{\jupyter} {Jupyter} @@ -146,7 +146,7 @@ \hyphenation{Exe-cut-able-Thing} -\title{IVOA Execution Planner} +\title{IVOA Execution Broker} % see ivoatexDoc for what group names to use here; use \ivoagroup[IG] for % interest groups. @@ -175,13 +175,13 @@ %\footurl{https://www.skao.int/en/explore/big-data} %\footurl{https://www.lsst.org/scientists/keynumbers} -The \ivoa{} \executionplanner{} provides a step towards making this possible. +The \ivoa{} \executionbroker{} provides a step towards making this possible. -The \ivoa{} \executionplanner{} is designed to address a specific question; +The \ivoa{} \executionbroker{} is designed to address a specific question; given an executable thing, e.g. a \pythonprogram{} or \jupyternotebook{}. What facilities are available to run it? -To do this, the \ivoa{} \executionplanner{} specification defines +To do this, the \ivoa{} \executionbroker{} specification defines a \datamodel{} and \webservice{} API for describing executable things and the resources needed to execute them. @@ -217,11 +217,11 @@ \section{Preface} \label{preface} The current version of this document contains a significant amount of exposition -explaning the details of the ideas behind the design of the \ivoa{} \executionplanner{}. +explaning the details of the ideas behind the design of the \ivoa{} \executionbroker{}. As we transition from 'one guy with a good idea' to a team of people building prototypes and implementing services we will develop a common understanding of how we want -the \executionplanner{} to function. +the \executionbroker{} to function. In the process, I hope we will be able to edit a lot of the exposition and explanation down to make a more concise and readable document. @@ -236,8 +236,8 @@ \section{Preface} \section{Introduction} \label{introduction} -The \ivoa{} \executionplanner{} specification defines two \webservice{} interfaces, -the \execplanner{} and the \execworker{}, and a common \datamodel{} for describing +The \ivoa{} \executionbroker{} specification defines two \webservice{} interfaces, +the \execbrokerclass{} and the \execworkerclass{}, and a common \datamodel{} for describing executable tasks. Together these provide a common interface for service discovery, resource allocation @@ -245,9 +245,9 @@ \section{Introduction} execution platform. \begin{itemize} - \item \execplanner{} \webservice{} – a discovery service to find execution platforms, allocate resources and schedule execution. - \item \execworker{} \webservice{} – an asynchronous service for executing tasks (based on the \ivoa{} \uws{} pattern). - \item \execplanner{} \datamodel{} – a common data model for describing an executable thing and its resource requirements. + \item \execbrokerclass{} \webservice{} – a discovery service to find execution platforms, allocate resources and schedule execution. + \item \execworkerclass{} \webservice{} – an asynchronous service for executing tasks (based on the \ivoa{} \uws{} pattern). + \item \execbrokerclass{} \datamodel{} – a common data model for describing an executable thing and its resource requirements. \end{itemize} \subsection{Role within the VO Architecture} @@ -261,14 +261,14 @@ \subsection{Role within the VO Architecture} \begin{figure} \centering \includegraphics[width=0.9\textwidth]{role_diagram.pdf} -\caption{Architecture diagram showing the \ivoa{} \executionplanner{}'s role in the \ivoa} +\caption{Architecture diagram showing the \ivoa{} \executionbroker{}'s role in the \ivoa} \label{fig:archdiag} \end{figure} The IVOA Architecture\citep{2010ivoa.rept.1123A} provides a high-level view of how IVOA standards work together to connect users and applications with providers of data and services. -Fig.~\ref{fig:archdiag} shows the role the \ivoa{} \executionplanner{} plays within this architecture. +Fig.~\ref{fig:archdiag} shows the role the \ivoa{} \executionbroker{} plays within this architecture. In response to the increasing size and complexity of the next generation of science \dataset{}s a number of \ivoa{} members are developing intergrated \scienceplatform{}s which bring @@ -283,30 +283,30 @@ \subsection{Role within the VO Architecture} However, to date the \ivoa{} does not provide any APIs or \webservice{} interfaces that enable \scienceplatform{}s to exchange the software used to analyse the data. -The \ivoa{} \executionplanner{} provides a step towards making this possible. +The \ivoa{} \executionbroker{} provides a step towards making this possible. -This places the \ivoa{} \executionplanner{} in the same region of the \ivoa{} architecture +This places the \ivoa{} \executionbroker{} in the same region of the \ivoa{} architecture as the \ivoa{} \vospace{} specification \citep{2009ivoa.specQ1007G}, providing an infrastructure level service that enables service discovery, resource allocation and execution scheduling across a heterogeneous federation of execution platforms. -The \ivoa{} \executionplanner{} specification refers to the +The \ivoa{} \executionbroker{} specification refers to the \ivoa{} Single-Sign-On standard \citep{2017ivoa.spec.0524T} for authentication (see section xx )%\ref{subsec:authentication} and the \ivoa{} Credential Delegation Protocol \citep{2010ivoa.spec.0218P} for delegating credentials to other services. -The \ivoa{} \executionplanner{} specification also describes how to register -an \execplanner{} service in the +The \ivoa{} \executionbroker{} specification also describes how to register +an \execbrokerclass{} service in the \ivoa{} Registry \citep{2009ivoa.spec.1104B}, making it findable within the wider context of the VO. \subsection{Executable things} \label{executablething} -To understand the problem that the \ivoa{} \executionplanner{} is trying to solve +To understand the problem that the \ivoa{} \executionbroker{} is trying to solve it is useful to describe what an \executablething{} is in this context. In general terms, this document refers to something that can be executed, or run, as an \executable{}. @@ -362,7 +362,7 @@ \subsection{Executable things} need to consider adding extra storage to handle the input data and the results. For a large \dataset{} it may also be worth using a \gpu{} to accelerate the calculation steps. -The \ivoa{} \executionplanner{} \datamodel{} provides a way to describe what each of these \executablething{}s +The \ivoa{} \executionbroker{} \datamodel{} provides a way to describe what each of these \executablething{}s are and what resources are needed to execute them. This can include things like number of \cpu{} cores and amount of memory it needs, whether it needs a \gpu{}, the location of the input data, the storage space needed to perform @@ -372,7 +372,7 @@ \section{Service interaction} \label{service-interaction} The interaction between user, client and services can be described as a conversation between the client -and one or more \execplanner{} services to discover where, how, and when, an \executablething{} can be +and one or more \execbrokerclass{} services to discover where, how, and when, an \executablething{} can be executed. \subsection{Discovery services} @@ -395,9 +395,9 @@ \subsection{Discovery services} coordinate system. The programming language the software is written in and the file format of the \dataset{} are at best secondary criteria. -Ideally, if the \executionplanner{} services function as intended, a science user should not +Ideally, if the \executionbroker{} services function as intended, a science user should not need to know about programming languages or file formats. -The \executionplanner{} services should make all of the technical details invisible, +The \executionbroker{} services should make all of the technical details invisible, enabling the science user to get on with science. The interfaces for the discovery services should be designed to be domain agnostic. @@ -418,13 +418,13 @@ \subsubsection{Separation of concerns} \item The user who is running the analysis \end{itemize} -\subsection{Execution planner} -\label{execution-planner-desc} +\subsection{Execution broker} +\label{execution-broker-desc} Once the client has built a description of the \executablething{} the user wants to execute, it send the description to one or more -\execplanner{} services, asking them if they can execute the task. -Each \execplanner{} service evaluates the task and responds with a top level +\execbrokerclass{} services, asking them if they can execute the task. +Each \execbrokerclass{} service evaluates the task and responds with a top level \codeword{YES|NO} answer, and if the answer is \codeword{YES}, a list of offers describing how it could be executed on that platform. @@ -442,7 +442,7 @@ \subsection{Execution planner} describing when and how the task would be executed. \begin{lstlisting}[] -# ExecutionPlanner service response. +# ExecutionBroker service response. response: result: 'YES' offers: @@ -470,7 +470,7 @@ \subsection{Execution planner} The client can then ask its user to choose which of the offers best fits their requirements and replies with a message accepting the offer. -In response, the \execplanner{} will initiate a \workerjob{} in an \execworker{} service +In response, the \execbrokerclass{} will initiate a \workerjob{} in an \execworkerclass{} service to execute the task and reply with details of how to access it. %\begin{lstlisting}[] @@ -480,60 +480,60 @@ \subsection{Execution planner} \includegraphics[width=0.9\textwidth]{diagrams/accept-offer.pdf} -Once the client has accepted an offer, the conversation between the client and the \execplanner{} -is finished. Once one offer has been accepted, the \execplanner{} will cancel the other offers and +Once the client has accepted an offer, the conversation between the client and the \execbrokerclass{} +is finished. Once one offer has been accepted, the \execbrokerclass{} will cancel the other offers and release their resources. -The client does not need to cancel the offers made by the other \execplanner{} services. +The client does not need to cancel the offers made by the other \execbrokerclass{} services. Offers are only valid for a limited period of time and they will expire naturally when they reach the end of their lifetime. -How the \execplanner{} and \execworker{} services are linked is up the implementation architecture. +How the \execbrokerclass{} and \execworkerclass{} services are linked is up the implementation architecture. One implementation may package both service interfaces into a single web-application. \includegraphics[width=0.9\textwidth]{diagrams/single-webapp.pdf} -Another implementation may package each of them as separate micro-services, with one \execplanner{} -service providing the front-end for multiple \execworker{} services. +Another implementation may package each of them as separate micro-services, with one \execbrokerclass{} +service providing the front-end for multiple \execworkerclass{} services. \includegraphics[width=0.9\textwidth]{diagrams/micro-services.pdf} \subsection{Execution worker} \label{execution-worker-desc} -The client can use the \workerjob{} details in the \execplanner{} response to contact -the \execworker{} service and track its status. +The client can use the \workerjob{} details in the \execbrokerclass{} response to contact +the \execworkerclass{} service and track its status. \includegraphics[width=0.9\textwidth]{diagrams/job-status.pdf} -A \workerjob{} in an \execworker{} service goes through the following stages in its lifecycle. +A \workerjob{} in an \execworkerclass{} service goes through the following stages in its lifecycle. \begin{itemize} \item \codeword{PENDING} The \workerjob{} has been created, but the resources have not be prepared yet. - \item \codeword{SETUP} The \execworker{} service is setting up the resources needed to execute the \workerjob{}. + \item \codeword{SETUP} The \execworkerclass{} service is setting up the resources needed to execute the \workerjob{}. This includes things like staging any \dataset{}s that will be needed locally. \item \codeword{READY} The \workerjob{} is ready and waiting to start. \item \codeword{RUNNING} The \workerjob{} is running. - \item \codeword{TEARDOWN} The execution has finished and the \execworker{} service is clearing up the resources that were used. + \item \codeword{TEARDOWN} The execution has finished and the \execworkerclass{} service is clearing up the resources that were used. This includes things like transferring the results to permanent storage and releasing local resources. \item \codeword{COMPLETED} The \workerjob{} has been completed. \item \codeword{FAILED} The \workerjob{} failed to complete. \item \codeword{CANCELLED} The \workerjob{} was cancelled. \end{itemize} -When a \execplanner{} creates a \workerjob{} in an \execworker{} service the +When a \execbrokerclass{} creates a \workerjob{} in an \execworkerclass{} service the \workerjob{} starts with the \codeword{phase} set to \codeword{PENDING}. -It is up to the \execworker{} to select the right time to change the \workerjob{} +It is up to the \execworkerclass{} to select the right time to change the \workerjob{} \codeword{phase} to \codeword{SETUP} and start preparing the resources so that the \workerjob{} is \codeword{READY} in time for the \codeword{starttime} declared in the \execoffer{}. If it will take 2 hours to transfer the input \dataset{} specified in the \execplan{} from cold storage to live storage co-located with the compute resources, -then the \execworker{} needs to start the \codeword{SETUP} phase at least 2 hours +then the \execworkerclass{} needs to start the \codeword{SETUP} phase at least 2 hours before the \codeword{starttime} declared in the \execoffer{}. -Once all the resources are ready, the \execworker{} changes the \workerjob{} +Once all the resources are ready, the \execworkerclass{} changes the \workerjob{} \codeword{phase} to \codeword{READY} to indicate that the all the resources are ready and the \workerjob{} is waiting to start. @@ -548,7 +548,7 @@ \subsection{Execution worker} When the \workerjob{} finishes executing, because the \ocicontainer{} finished executing, the user closed their \jupyternotebook, or the \codeword{maxduration} was reached, -the \execworker{} will change the \workerjob{} \codeword{phase} to \codeword{TEARDOWN} and +the \execworkerclass{} will change the \workerjob{} \codeword{phase} to \codeword{TEARDOWN} and begin the process of releasing the resources. If the \execplan{} declared some persistent storage that will last beyond the end of the \workerjob{}, @@ -559,7 +559,7 @@ \subsection{Execution worker} If an error occurs at any time in the process, the \workerjob{} \codeword{phase} is changed to \codeword{FAILED}. This includes any errors that occur during the \teardown{} process; for example, because -the \execworker{} was unable to transfer the results onto persistent storage. +the \execworkerclass{} was unable to transfer the results onto persistent storage. Then the \workerjob{} \codeword{phase} is changed to \codeword{FAILED}, even if the main part of the execution completed successfully. This is because any workflow steps that follow after this step, will depend not only on the execution being @@ -588,9 +588,9 @@ \section{The \executable{}} % Type URLs % https://www.purl.org/ivoa.net/executable-types/example -% https://github.com/Zarquan/ExecutionPlanner/blob/main/types/executable-types/example-executable.md +% https://github.com/ivoa-std/ExecutionBroker/blob/main/types/executable-types/example-executable.md \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. request: # Details of the executable. executable: @@ -611,9 +611,9 @@ \subsection{\jupyternotebook{}} % Type URLs % https://www.purl.org/ivoa.net/executable-types/jupyter-notebook -% https://github.com/Zarquan/ExecutionPlanner/blob/main/types/executable-types/jupyter-notebook.md +% https://github.com/ivoa-std/ExecutionBroker/blob/main/types/executable-types/jupyter-notebook.md \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. request: # Details of the executable. executable: @@ -628,7 +628,7 @@ \subsection{\jupyternotebook{}} It may also include a reference to a \codeword{requirements.txt} file that describes any additional \python{} libraries needed to run the notebook. \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. request: # Details of the executable. executable: @@ -648,9 +648,9 @@ \subsection{\ocicontainer{}} % Type URLs % https://www.purl.org/ivoa.net/executable-types/oci-container -% https://github.com/Zarquan/ExecutionPlanner/blob/main/types/executable-types/oci-container.md +% https://github.com/ivoa-std/ExecutionBroker/blob/main/types/executable-types/oci-container.md \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. request: # Details of the executable. executable: @@ -666,7 +666,7 @@ \subsection{\ocicontainer{}} This pattern of using a \codeword{type} URI to identify the type of thing, and then a \codeword{spec} block to add the type specific details is used in several places in the -\executionplanner{} \datamodel{}. +\executionbroker{} \datamodel{}. This enables us to keep the core \datamodel{} relatively small, defining the common aspects needed to describe an \executablething{} and the resources it needs while allowing the \datamodel{} to be extended to describe a wide range of different types of things. @@ -698,14 +698,14 @@ \subsection{Compute resources} \label{compute-resources} The \datamodel{} for describing compute resources is, in most cases, common to all types of \executable{}, -so the \datamodel{} for these requirements are defined as part of the core \executionplanner{} \datamodel{}. +so the \datamodel{} for these requirements are defined as part of the core \executionbroker{} \datamodel{}. It is important to note that all of the resource requirements are optional. As in the example from the previous section, a request to execute a simple \jupyternotebook{} does not need to include any resource details. \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. request: # Details of the executable. executable: @@ -727,13 +727,13 @@ \subsection{Compute resources} % Type URLs % https://www.purl.org/ivoa.net/resource-types/generic-compute -% https://github.com/Zarquan/ExecutionPlanner/blob/main/types/resource-types/generic-compute.md +% https://github.com/ivoa-std/ExecutionBroker/blob/main/types/resource-types/generic-compute.md % Type URLs % https://tinyurl.com/nvidia-ad104 % https://www.purl.org/ivoa.net/resource-types/nvidia-ad104 -% https://github.com/Zarquan/ExecutionPlanner/blob/main/types/resource-types/nvidia-ad104.md +% https://github.com/ivoa-std/ExecutionBroker/blob/main/types/resource-types/nvidia-ad104.md \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. request: # Details of the executable. executable: @@ -782,9 +782,9 @@ \subsection{Compute resources} % Type URLs % https://tinyurl.com/nvidia-ad104 % https://www.purl.org/ivoa.net/resource-types/nvidia-ad104 -% https://github.com/Zarquan/ExecutionPlanner/blob/main/types/resource-types/nvidia-ad104.md +% https://github.com/ivoa-std/ExecutionBroker/blob/main/types/resource-types/nvidia-ad104.md \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. request: # Details of the executable. executable: @@ -812,9 +812,9 @@ \subsection{Compute resources} % Type URLs % https://tinyurl.com/xilinx-vu19p % https://www.purl.org/ivoa.net/resource-types/xilinx-vu19p -% https://github.com/Zarquan/ExecutionPlanner/blob/main/types/resource-types/xilinx-vu19p.md +% https://github.com/ivoa-std/ExecutionBroker/blob/main/types/resource-types/xilinx-vu19p.md \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. request: # Details of the executable. executable: @@ -855,7 +855,7 @@ \subsection{Compute resources} \codeword{[https://tinyurl.com/nvidia-ad104]} \item The PURL service\footurl{https://purl.archive.org/} provided by the internet archive\footurl{http://www.archive.org/}.\\ \codeword{[https://www.purl.org/ivoa.net/resource-types/nvidia-ad104]}. -\item A page in our GitHub repository that directs the reader to more resources\footurl{https://github.com/Zarquan/ExecutionPlanner/blob/main/types/resource-types/nvidia-ad104.md}.\\ +\item A page in our GitHub repository that directs the reader to more resources\footurl{https://github.com/ivoa-std/ExecutionBroker/blob/main/types/resource-types/nvidia-ad104.md}.\\ \codeword{[https://github.com/..../resource-types/nvidia-ad104.md]}. \end{itemize} @@ -871,7 +871,7 @@ \subsection{Compute resources} %\item A URL shortening service \codeword{[https://tinyurl.com/xilinx-vu19p]}. \item A PURL redirect to provide a long lasting URL.\\ \codeword{[https://www.purl.org/ivoa.net/resource-types/xilinx-vu19p]} -\item A page in our GitHub repository describing the FPGA and the tools needed to use it\footurl{https://github.com/Zarquan/ExecutionPlanner/blob/main/types/resource-types/xilinx-vu19p.md}.\\ +\item A page in our GitHub repository describing the FPGA and the tools needed to use it\footurl{https://github.com/ivoa-std/ExecutionBroker/blob/main/types/resource-types/xilinx-vu19p.md}.\\ \codeword{[https://github.com/..../resource-types/xilinx-vu19p.md]} \end{itemize} @@ -885,7 +885,7 @@ \subsection{Minimum and maximum} to be able to perform its calculations, then this can be specified in the compute resource. \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. request: # Details of the executable. executable: @@ -902,7 +902,7 @@ \subsection{Minimum and maximum} All of the \datamodel{} elements for specifying the size or number of resources are defined as pairs of minimum and maximum values. -This allows a conversation between the \execplanner{} client and services +This allows a conversation between the \execbrokerclass{} client and services to discover the best platform to execute the task. The client requests the minimun resources it needs, @@ -914,7 +914,7 @@ \subsection{Minimum and maximum} then it can indicate this by specifying higher maximum values in its response. \begin{lstlisting}[] -# ExecutionPlanner service response. +# ExecutionBroker service response. response: # Details of the executable. executable: @@ -949,7 +949,7 @@ \subsection{Minimum and maximum} then the service can represent that by setting the minimum values in its offer to match available resources. \begin{lstlisting}[] -# ExecutionPlanner service response. +# ExecutionBroker service response. response: # Details of the executable. executable: @@ -968,7 +968,7 @@ \subsection{Minimum and maximum} This response represents an offer to start with a fixed allocation of 16 \cpu{} cores and 24G of memory. -An \execplanner{} MAY NOT make an offer with less than the minimum resources requested. +An \execbrokerclass{} MAY NOT make an offer with less than the minimum resources requested. For example, if an \openstack{} platform only has a virtual machine flavor with 1 \cpu{} core and 2G of memory, then it MAY NOT offer this resource as it is less than the requested minimum. @@ -1010,9 +1010,9 @@ \subsection{Storage resources} % Type URLs % https://www.purl.org/ivoa.net/storage-types/ephemeral-storage -% https://github.com/Zarquan/ExecutionPlanner/blob/main/types/storage-types/ephemeral-storage.md +% https://github.com/ivoa-std/ExecutionBroker/blob/main/types/storage-types/ephemeral-storage.md \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. request: # Details of the executable. executable: @@ -1037,7 +1037,7 @@ \subsection{Storage resources} storage resource. \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. request: # Details of the executable. executable: @@ -1074,9 +1074,9 @@ \subsection{Storage resources} % Type URLs % https://www.purl.org/ivoa.net/storage-types/amazon-s3 -% https://github.com/Zarquan/ExecutionPlanner/blob/main/types/storage-types/amazon-s3.md +% https://github.com/ivoa-std/ExecutionBroker/blob/main/types/storage-types/amazon-s3.md \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. request: # Details of the executable. executable: @@ -1111,9 +1111,9 @@ \subsection{Storage resources} % Type URLs % https://www.purl.org/ivoa.net/storage-types/persistent-storage -% https://github.com/Zarquan/ExecutionPlanner/blob/main/types/storage-types/persistent-storage.md +% https://github.com/ivoa-std/ExecutionBroker/blob/main/types/storage-types/persistent-storage.md \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. request: # Details of the executable. executable: @@ -1140,22 +1140,22 @@ \subsection{Storage resources} By setting the storage resource type to \codeword{https://.../persistent}, and setting the \codeword{lifecycle} to \codeword{managed}, -the client is asking the \execplanner{} service to take care of allocating +the client is asking the \execbrokerclass{} service to take care of allocating the storage and managing its lifecycle. -It is up to the \execplanner{} service to decide where to store the data and +It is up to the \execbrokerclass{} service to decide where to store the data and how make it accessible after the \job{} has completed. For example, a science platform may have a \rucio{} storage system co-located with the compute platform which it uses to store user generated data. -In which case the \execplanner{} service would respond with an offer that +In which case the \execbrokerclass{} service would respond with an offer that stores the results in the \rucio{} system and provides details of how the user can access it after the \job{} has completed. % Type URLs % https://www.purl.org/ivoa.net/storage-types/rucio-storage -% https://github.com/Zarquan/ExecutionPlanner/blob/main/types/storage-types/rucio-storage.md +% https://github.com/ivoa-std/ExecutionBroker/blob/main/types/storage-types/rucio-storage.md \begin{lstlisting}[] -# ExecutionPlanner service response. +# ExecutionBroker service response. response: # Details of the executable. executable: @@ -1200,7 +1200,7 @@ \subsection{Storage resources} It is important to note that at this point in time the storage is proposed, but not yet allocated. The persistent storage is only allocated if the client accepts this particular offer. -This allows an \execplanner{} service to make multiple offers with different storage options, +This allows an \execbrokerclass{} service to make multiple offers with different storage options, allowing the client to select and accept the one that best fits its use case. The same \datamodel{} can be used the other way around as well. @@ -1209,9 +1209,9 @@ \subsection{Storage resources} % Type URLs % https://www.purl.org/ivoa.net/storage-types/vospace-storage -% https://github.com/Zarquan/ExecutionPlanner/blob/main/types/storage-types/vospace-storage.md +% https://github.com/ivoa-std/ExecutionBroker/blob/main/types/storage-types/vospace-storage.md \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. request: # Details of the executable. executable: @@ -1235,23 +1235,23 @@ \subsection{Storage resources} lifecycle: "unmanaged" \end{lstlisting} -It is up to the \execplanner{} service to work out if it is able to access the +It is up to the \execbrokerclass{} service to work out if it is able to access the \vospace{} location and mount it as a volume in the compute resource, using either its own authentication, or a delegated form of the authentication provided by the client. -If it can access the \vospace{} location, then the \execplanner{} MAY respond +If it can access the \vospace{} location, then the \execbrokerclass{} MAY respond with an offer, otherwise if it can't access the \vospace{} location for whatever -reason the \execplanner{} MUST respond with \codeword{NO}. +reason the \execbrokerclass{} MUST respond with \codeword{NO}. Note that in this example, the client has specified the lifecycle as \codeword{unmanaged}, -which means that the \execplanner{} is not involved in managing the creation or deletion +which means that the \execbrokerclass{} is not involved in managing the creation or deletion of the data in \vospace. -It is also possible for the client to ask the \execplanner{} service to manage +It is also possible for the client to ask the \execbrokerclass{} service to manage data in an external resource. \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. request: # Details of the executable. executable: @@ -1271,12 +1271,12 @@ \subsection{Storage resources} \end{lstlisting} In this example, the client is specifying an external \vospace{} location to store the data, -but it is asking the \execplanner{} service to manage the lifecycle, creating the location +but it is asking the \execbrokerclass{} service to manage the lifecycle, creating the location in \vospace{} at the start of the \job{} and deleting it 2 days after the \job{} completes. This negotiation of who is responsible for creating and deleting storage resources enables a client to put together a workflow of interconnected steps, with the -\execplanner{} services +\execbrokerclass{} services managing the lifecycle of the resources and releasing them automatically after they are no longer needed. @@ -1289,22 +1289,22 @@ \section{Authentication} This is equivalent to asking: \textit{"Do I have permission to use these resources to run this \jupyternotebook{}?"} -There are two ways for the \execplanner{} service to check the user's identity, +There are two ways for the \execbrokerclass{} service to check the user's identity, using implicit and explicit authentication. -The implicit method is for the client to authenticate to the \execplanner{} service +The implicit method is for the client to authenticate to the \execbrokerclass{} service as normal and the service will use the identity from the request headers to check if the user has sufficient access rights and resource quota to execute the \job{}. -If the \webservice{} call to the \execplanner{} service is authenticated +If the \webservice{} call to the \execbrokerclass{} service is authenticated using OpenIDConnect (OIDC)\footurl{https://auth0.com/docs/authenticate/protocols/openid-connect-protocol}, -then the \execplanner{} MUST include a reference to the implicit +then the \execbrokerclass{} MUST include a reference to the implicit authentication in its reply, including enough non-secret information to identify the authenticated identity. \begin{lstlisting}[] -# ExecutionPlanner server response. +# ExecutionBroker server response. response: .... # Details of the authentication offered. @@ -1317,9 +1317,9 @@ \section{Authentication} \end{lstlisting} If the client uses an unknown authentication method in the \webservice{} call and -the \execplanner{} service recognises that an anthentication attempt has been made, +the \execbrokerclass{} service recognises that an anthentication attempt has been made, then it MUST reject the \webservice{} call with a 401 "Unauthenticated" response. -If the \execplanner{} service does not realise that an anthentication attempt has been made, +If the \execbrokerclass{} service does not realise that an anthentication attempt has been made, then this MAY result in the request being treated as an anonymous unauthenticated call. The \datamodel{} also allows for an explicit statement of identity in the request. @@ -1330,7 +1330,7 @@ \section{Authentication} For example, to explicitly include a basic authentication with username and password in the request: \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. request: # Details of the executable. executable: @@ -1345,7 +1345,7 @@ \section{Authentication} \end{lstlisting} This pattern allows the client to supply multiple authentication methods -in the request. The \execplanner{} service can select the authentication +in the request. The \execbrokerclass{} service can select the authentication methods it accepts from those in the request and include the name and type of the methods in its offer along with enough non-secret information to identify the authenticated identity. @@ -1353,7 +1353,7 @@ \section{Authentication} For example, if the client supplies both basic and token authentication in the request: \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. request: # Details of the executable. executable: @@ -1373,12 +1373,12 @@ \section{Authentication} token: "..." \end{lstlisting} -If the \execplanner{} service only accepts the token authentication, it should +If the \execbrokerclass{} service only accepts the token authentication, it should skip the basic authentication and only include a reference to the token based authentication in its offer. \begin{lstlisting}[] -# ExecutionPlanner server response. +# ExecutionBroker server response. response: .... # Details of the authentication offered. @@ -1390,7 +1390,7 @@ \section{Authentication} .... \end{lstlisting} -If the \execplanner{} service does not recognise or support any of the authentication methods +If the \execbrokerclass{} service does not recognise or support any of the authentication methods included in the request, then the service MUST reject the request and reply with \codeword{NO}. \begin{lstlisting}[] @@ -1398,21 +1398,21 @@ \section{Authentication} Response - NO \end{lstlisting} -The result is that an offer made by an \execplanner{} service should only include details +The result is that an offer made by an \execbrokerclass{} service should only include details of the authenticated identities that are allowed to use the offer. If the original question is equivalent to: \textit{"Do \textbf{these identities} have sufficient access rights and quota to run this \jupyternotebook{}?"} -Then the response from the \execplanner{} service is equivalent to: +Then the response from the \execbrokerclass{} service is equivalent to: \textit{"This offer asserts that \textbf{these identities} have sufficient access rights and quota to run this \jupyternotebook{}?"} The client MUST use one of the authentication methods listed in the offer when -contacting the \execplanner{} service to accept the offer and start the \job{}. +contacting the \execbrokerclass{} service to accept the offer and start the \job{}. The client MUST continue to use the same authentication method when making subsequent -requests to the \execworker{} service to access the \job{} status and results. +requests to the \execworkerclass{} service to access the \job{} status and results. -The \executionplanner{} specification includes an initial set of authentication methods +The \executionbroker{} specification includes an initial set of authentication methods corresponding to the methods defined in the \ivoa{} Single-Sign-On standard\citep{2017ivoa.spec.0524T} @@ -1421,13 +1421,13 @@ \section{Authentication} \item .... \end{itemize} -However, the \datamodel{} also allows an \execplanner{} service to accept authentication +However, the \datamodel{} also allows an \execbrokerclass{} service to accept authentication methods that are not covered by the \ivoa{} SSO standard. A client is free to use any authentication method, including ones not covered by the -\ivoa{} SSO standard. It is up to the \execplanner{} service to decide how it +\ivoa{} SSO standard. It is up to the \execbrokerclass{} service to decide how it handles the authentication infomation it receives. -This means that the \executionplanner{} services can be deployed in other domains outside the \ivoa{}, +This means that the \executionbroker{} services can be deployed in other domains outside the \ivoa{}, without requiring them to adopt the full \ivoa{} SSO standard. \section{Date and time} @@ -1439,7 +1439,7 @@ \section{Date and time} The client can specify one or more time periods when it would like to start the \job{}, and the minimum duration that it thinks would be needed to complete the \job{}. -The \execplanner{} service may respond with one or more offers that specify when the \job{} +The \execbrokerclass{} service may respond with one or more offers that specify when the \job{} would start and the maximum duration that the \job{} would be allowed to consume. It is then up to the client to select which of the offers best suits its use case. @@ -1455,7 +1455,7 @@ \section{Date and time} If no duration is specified, this means an absolute start time; e.g. the \job{} SHOULD start at 11:30 on 14 August. \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. .... datetime: - start: "2023-08-14T11:30Z" @@ -1465,7 +1465,7 @@ \section{Date and time} the start and end values; e.g. the \job{} SHOULD start between 11:30 and 12:00 on 14 August. \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. .... datetime: - start: "2023-08-14T11:30Z/T12:00Z" @@ -1475,13 +1475,13 @@ \section{Date and time} start and the start plus duration; e.g. the \job{} SHOULD start between 11:30 and 12:00 on 14 August. \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. .... datetime: - start: "2023-08-14T11:30Z/PT30M" \end{lstlisting} -The \execplanner{} service SHOULD respond with one or more offers that start within +The \execbrokerclass{} service SHOULD respond with one or more offers that start within the ranges specified in the request. The start times in the offers MAY be more precise than the start times in the request, but they MUST all occur within at least one of the ranges specified in the request. @@ -1494,18 +1494,18 @@ \section{Date and time} In which case, the client may simply request a minimum duration of 1 hour. \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. .... datetime: - minduration: "1H" \end{lstlisting} -The \execplanner{} service MAY respond with offers that start at different times and +The \execbrokerclass{} service MAY respond with offers that start at different times and set different values for the maximum duration. It MAY offer a maximum duration of 1 hour in the morning, starting at 11:00. \begin{lstlisting}[] -# ExecutionPlanner server response. +# ExecutionBroker server response. .... datetime: - start: "2023-08-14T11:30Z" @@ -1516,7 +1516,7 @@ \section{Date and time} It MAY also offer a longer allocation of 4 hours later in the evening, starting sometime between 22:00 and 23:00. \begin{lstlisting}[] -# ExecutionPlanner server response. +# ExecutionBroker server response. .... datetime: - start: "2023-08-14T22:00Z/PT1H" @@ -1529,7 +1529,7 @@ \section{Date and time} For example, if a client asks for 2 cores and 2G of memory for 1 hour sometime on 14 August: \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. ... resources: compute: @@ -1540,13 +1540,13 @@ \section{Date and time} minduration: "P1H" \end{lstlisting} -The \execplanner{} service may respond with 2 offers, +The \execbrokerclass{} service may respond with 2 offers, the minimum 2 cores and 2G of memory for 1 hour starting at 11:30, and a larger offer of up to 8 cores and 8Gb of memory for up to 4 hours starting between 22:00 and 23:00. \begin{lstlisting}[] -# ExecutionPlanner server response. +# ExecutionBroker server response. offers: - name: "offer-001" executable: @@ -1581,10 +1581,10 @@ \section{Date and time} Accept the limited offer in the morning, or accept the more generous offer with more resources and more time later in the day. -If an \execplanner{} service is offering more than one option for the \codeword{datetime} +If an \execbrokerclass{} service is offering more than one option for the \codeword{datetime} section it MUST make separate offers for each different option. Even if all of the other parameters are the same, e.g. compute and storage resources, the -\execplanner{} service MUST NOT include more than one time slot in the same offer. +\execbrokerclass{} service MUST NOT include more than one time slot in the same offer. Technically the \datamodel allows an array of values for the \codeword{datetime} section, but this would impose unnecessary complexity on the client for no real gain in user experience. @@ -1595,7 +1595,7 @@ \subsection{Triggers} \label{triggers} The \codeword{triggers} section of the \datamodel{} defines triggers that -enable an external system to control the state of an \execworker{} \job{}. +enable an external system to control the state of an \execworkerclass{} \job{}. The core \datamodel{} for \codeword{triggers} uses the \codeword{type} and \codeword{spec} pattern to support different types of \codeword{triggers} @@ -1604,10 +1604,10 @@ \subsection{Triggers} \subsubsection{HTTP trigger} \label{http-trigger} -The \executionplanner{} specification includes a \datamodel{} extension for +The \executionbroker{} specification includes a \datamodel{} extension for a \http{} \webservice{} trigger which can be called by an external system. -The following example asks the \execplanner{} service to set up a \http{} \webservice{} +The following example asks the \execbrokerclass{} service to set up a \http{} \webservice{} endpoint that expects the \codeword{POST} data to contain a \yaml{} document with the following fields: @@ -1620,7 +1620,7 @@ \subsubsection{HTTP trigger} \codeword{trigger.colour} in the \yaml{} document that it receives. \begin{lstlisting}[] -# ExecutionPlanner client request. +# ExecutionBroker client request. .... triggers: - name: "trigger-001" @@ -1645,22 +1645,22 @@ \subsubsection{HTTP trigger} Defining a \codeword{start} action in the \codeword{triggers} section will modify the effect of the \codeword{starttime} declared in the \codeword{datetime} section. -The \execworker{} service will not automatically start the \job{} when the specified \codeword{starttime} is reached. -Instead the \execworker{} service will wait until the start action has been triggered before it starts the \job{}. +The \execworkerclass{} service will not automatically start the \job{} when the specified \codeword{starttime} is reached. +Instead the \execworkerclass{} service will wait until the start action has been triggered before it starts the \job{}. \begin{itemize} - \item If the trigger is called before the specified \codeword{starttime} is reached, the \execworker{} will + \item If the trigger is called before the specified \codeword{starttime} is reached, the \execworkerclass{} will wait until the \codeword{starttime} is reached before starting the \job{}. - \item If the \codeword{starttime} is reached before the trigger has been called, the \execworker{} will wait + \item If the \codeword{starttime} is reached before the trigger has been called, the \execworkerclass{} will wait until the trigger is called before starting the \job{}. - \item If the trigger is called within the \codeword{starttime} range, the \execworker{} service will start \job{}. - \item If the \codeword{starttime} range expires before the trigger has been called, the \execworker{} will cancel the \job{}. + \item If the trigger is called within the \codeword{starttime} range, the \execworkerclass{} service will start \job{}. + \item If the \codeword{starttime} range expires before the trigger has been called, the \execworkerclass{} will cancel the \job{}. \item If the trigger is called after the \codeword{starttime} range, it has no effect. The \job{} should already have been cancelled. \end{itemize} In effect, the \codeword{starttime} range acts as a constraint on the action of the trigger. Preventing it from starting the \job{} too early or too late. -The \execworker{} service is responsible for allocating the required compute and storage resources +The \execworkerclass{} service is responsible for allocating the required compute and storage resources before the beginning of the \codeword{starttime}, making sure that the \job{} is ready to start as soon as the trigger is called. If the \codeword{starttime} range expires before the trigger has been called, the resources are released as normal @@ -1669,19 +1669,19 @@ \subsubsection{HTTP trigger} \subsection{Actions} \label{actions} -The \codeword{actions} part of the \datamodel{} enables a client to ask the \execworker{} service +The \codeword{actions} part of the \datamodel{} enables a client to ask the \execworkerclass{} service to perform user defined actions at specific points in the lifecycle of a \job{}. The core \datamodel{} for actions uses the \codeword{type} and \codeword{spec} pattern to support different types of \codeword{actions} using \datamodel{} extensions. -The \executionplanner{} specification includes \datamodel{} extensions for two types of \codeword{actions}, +The \executionbroker{} specification includes \datamodel{} extensions for two types of \codeword{actions}, one for sending an email and one for calling a HTTP \webservice{}. \subsubsection{Email action} \label{email-action} -The following definition asks the \execworker{} service to send an email to the user +The following definition asks the \execworkerclass{} service to send an email to the user when the \codeword{status} of their \jupyternotebook{} \job{} changes to \codeword{RUNNING}. \begin{lstlisting}[] @@ -1707,25 +1707,25 @@ \subsubsection{Email action} From the user's perspective their notebook is \textit{'running'} when they login and click the \textit{'run'} button. -From the \execworker{} service's perspective, the \job{} \codeword{status} changes to \codeword{RUNNING} +From the \execworkerclass{} service's perspective, the \job{} \codeword{status} changes to \codeword{RUNNING} once the compute resources have been allocated, the data staging has been completed and the \job{} \codeword{starttime} is reached. In many cases, the \jupyternotebook{} service \codeword{endpoint} will not be available until the -\execworker{} \job{} is \codeword{RUNNING}. +\execworkerclass{} \job{} is \codeword{RUNNING}. -In the simple case with no data staging, the \execworker{} \job{} \codeword{status} may change to +In the simple case with no data staging, the \execworkerclass{} \job{} \codeword{status} may change to \codeword{RUNNING} almost immediately, in which case the notification email is not necessary. -However, in a more complex case where the the \execworker{} service needs to do a lot of work +However, in a more complex case where the the \execworkerclass{} service needs to do a lot of work allocating the resources and staging the data, there may be a significant delay before for the -\execworker{} \job{} \codeword{status} changes to \codeword{RUNNING}. +\execworkerclass{} \job{} \codeword{status} changes to \codeword{RUNNING}. In which case, being able send the user an email when their session is ready improves the user experience. \subsubsection{HTTP action} \label{http-action} -The following definition asks the \execworker{} service to \codeword{POST} content from a \yaml{} template +The following definition asks the \execworkerclass{} service to \codeword{POST} content from a \yaml{} template to a HTTP \webservice{} at \codeword{http://foo.example.org/update} when the status of this \job{} changes. \begin{lstlisting}[] @@ -1750,7 +1750,7 @@ \subsubsection{HTTP action} \end{lstlisting} When the status of this \job{} changes to one of the specified values, the -\execworker{} service will \codeword{POST} the document described in the +\execworkerclass{} service will \codeword{POST} the document described in the \codeword{content} template to the HTTP \codeword{endpoint}, filling in the \codeword{\{\{...\}\}} markers in the template with values from the \datamodel{} representing the \job{} at that point in time. @@ -1814,9 +1814,9 @@ \subsection{Linked worflow} \end{lstlisting} Note that the client doesn't set the endpoint location for the \codeword{trigger}, that will -come from the \execplanner{} service when it makes an offer. +come from the \execbrokerclass{} service when it makes an offer. The \webservice{} endpoint location for the trigger may be different for each of the -offers in the \execplanner{} service response. +offers in the \execbrokerclass{} service response. \begin{lstlisting}[] .... @@ -1876,7 +1876,7 @@ \subsection{Linked worflow} \end{lstlisting} The client can also set up a \codeword{managed} storage resource in \vospace{} to transfer data -between the steps which is automatically created and deleted by the \execplanner{} service. +between the steps which is automatically created and deleted by the \execbrokerclass{} service. Adding a \codeword{managed} storage resource to step-a which points a location in a \vospace{} service with a \codeword{maxlifetime} and \codeword{minlifetime} set to 1 day means that the \vospace{} location @@ -1921,7 +1921,7 @@ \subsection{Linked worflow} \end{lstlisting} If all goes to plan, when the \codeword{starttime} for step-a is reached, -the first \execworker{} service will allocate the managed space in \vospace{}, +the first \execworkerclass{} service will allocate the managed space in \vospace{}, and then start the execution of step-a. The executable in step-a can access the storage location using an internal @@ -1957,7 +1957,7 @@ \subsection{Linked worflow} filesystem directory at \codeword{/results}. The code inside the \executable{} does not need to know anything about the details of where the data is stored. -The \execworker{} service for step-a is responsible for ensuring that anything written to +The \execworkerclass{} service for step-a is responsible for ensuring that anything written to \codeword{/results} in the local filesystem is transferred to \codeword{/step-a/results} in the remote \vospace{} service during the \codeword{TEARDONW} phase of step-a. @@ -1994,8 +1994,8 @@ \subsection{Linked worflow} details of where the data is stored. As soon as step-a starts, the \job{} status changes to \codeword{RUNNING}, -the \codeword{http-action} on this \execworker{} will call the \codeword{http-trigger} -on the \execworker{} running step-b. +the \codeword{http-action} on this \execworkerclass{} will call the \codeword{http-trigger} +on the \execworkerclass{} running step-b. This first call will have no effect, as the \codeword{http-trigger} on step-b will only perform an action when the \codeword{job.status} value is \codeword{COMPLETED}, \codeword{FAILED} or \codeword{CANCELLED}. @@ -2010,11 +2010,11 @@ \subsection{Linked worflow} which means that the space will not be deleted until a day after step-a has completed. This allows sufficient time for step-b to execute, reading its input data from the results of step-a. -The second \execworker{} service runs step-b to completion as normal, +The second \execworkerclass{} service runs step-b to completion as normal, freeing up any resources it was allocated at the end. Finally, the \codeword{managed} \vospace{} storage location is automatically -deleted a day after the completion of step-a by the \execworker{} service +deleted a day after the completion of step-a by the \execworkerclass{} service that was assigned to manage its lifecycle. \pagebreak @@ -2022,9 +2022,9 @@ \subsection{Linked worflow} \section{Federated architecture} \label{federation} -The \execplanner{} and \execworker{} services are designed to be used at multiple levels within an organization. +The \execbrokerclass{} and \execworkerclass{} services are designed to be used at multiple levels within an organization. -At the low level, an \execplanner{} and \execworker{} pair may be implemented as a +At the low level, an \execbrokerclass{} and \execworkerclass{} pair may be implemented as a single web-application linked to a simple \docker{} execution service. The configuration may be hard coded to only accept a fixed white list of container images and a fixed allocation of compute resources for each job{}. @@ -2041,7 +2041,7 @@ \section{Federated architecture} This information could come from the \ivoa{} Registry, or it could simply be provided as a flat list in a configuration file for the client. -A more flexible architecture could add another \execplanner{} service +A more flexible architecture could add another \execbrokerclass{} service a level above the low level task specific services. This service would be configured with a list of the local task specific services and act as an aggregator service sitting between the client and the low level services. @@ -2058,26 +2058,26 @@ \section{Federated architecture} The aggregator service may also have an understanding of the location of \dataset{}s within the organization and be able to route requests to different low level services depending on which \dataset{}s were required. -The aggregator service may expose the low level \execworker{} endpoints in its responses, -or it may implement a proxy interface acting as an aggregator for the \execworker{} +The aggregator service may expose the low level \execworkerclass{} endpoints in its responses, +or it may implement a proxy interface acting as an aggregator for the \execworkerclass{} services as well. -This configuration could be used to provide \execplanner{} and \execworker{} service interfaces +This configuration could be used to provide \execbrokerclass{} and \execworkerclass{} service interfaces that bridged a firewall. Providing a public interface for external clients and forwarding the requests -to the internal \execplanner{} and \execworker{} services that are not accessible from outside the +to the internal \execbrokerclass{} and \execworkerclass{} services that are not accessible from outside the firewall. -A large organization with multiple sites couls also deploy a single high level \execplanner{} and \execworker{} +A large organization with multiple sites couls also deploy a single high level \execbrokerclass{} and \execworkerclass{} interface that handles task execution for the whole organization, forwarding the requests to mid-level -\execplanner{} and \execworker{} services at each site which in turn forwards the requests to -individual low-level \execplanner{} and \execworker{} services within the local site networks. +\execbrokerclass{} and \execworkerclass{} services at each site which in turn forwards the requests to +individual low-level \execbrokerclass{} and \execworkerclass{} services within the local site networks. The implementation at each level may be different, providing different levels of routing and aggregation based on internal knowledge of the capabilities of the level below, -but the \execplanner{} and \execworker{} interfaces would be the same at each level +but the \execbrokerclass{} and \execworkerclass{} interfaces would be the same at each level in the organization. -This could be expanded to include another level of \execplanner{} and \execworker{} services that +This could be expanded to include another level of \execbrokerclass{} and \execworkerclass{} services that cross organization bondaries, providing a gateway that allows users from one project to access services from other projects and organizations. This gateway service may also provide an authentication translation layer between external public accounts internal project specific identities and authentication methods. @@ -2233,20 +2233,20 @@ \subsection{General requirements} \item .... \end{itemize} -\subsection{ExecutionPlanner} +\subsection{ExecutionBroker} \label{execution-planner-spec} -The main \execplanner{} \webservice{} implements two interfaces; +The main \execbrokerclass{} \webservice{} implements two interfaces; a \codeword{POST} method for sending requests, and a \codeword{GET/POST} interface for accessing offers and updating their status. \subsubsection{Request method} \label{execution-planner-request} -The main \execplanner{} \webservice{} method is a \codeword{POST} \webservice{} that accepts +The main \execbrokerclass{} \webservice{} method is a \codeword{POST} \webservice{} that accepts a \codeword{request} as defined in section \ref{datamodel-request} of the \datamodel{}. -An \execplanner{} \webservice{} MUST be able to accept both \yaml{} or \json{} serializations +An \execbrokerclass{} \webservice{} MUST be able to accept both \yaml{} or \json{} serializations of the \codeword{request}. The serialization SHOULD be declared in the HTTP request using the \codeword{Content-Type} header. \begin{itemize} @@ -2283,11 +2283,11 @@ \subsubsection{Request method} } \end{lstlisting} -The \execplanner{} service will evaluate the request and respond with either a positive +The \execbrokerclass{} service will evaluate the request and respond with either a positive or negative \codeword{response} depending on whether the platform is able to execute the task descibed in the \codeword{request}. -An \execplanner{} service MUST be able to provide both \yaml{} and \json{} serializations +An \execbrokerclass{} service MUST be able to provide both \yaml{} and \json{} serializations of the \codeword{response}. The serialization is determined by the \codeword{Accept} header in the HTTP request. \begin{itemize} @@ -2355,7 +2355,7 @@ \subsubsection{Offer GET} The \datamodel{} for the content of the \codeword{offer} response is described in section \ref{datamodel-offer}. -An \execplanner{} service MUST be able to provide both \yaml{} and \json{} serializations +An \execbrokerclass{} service MUST be able to provide both \yaml{} and \json{} serializations of the \codeword{offer}. The serialization is determined by the \codeword{Accept} header in the HTTP request. \begin{itemize} @@ -2410,7 +2410,7 @@ \subsubsection{Offer POST} \end{itemize} \end{itemize} -An \execplanner{} \webservice{} MUST be able to accept both \yaml{} or \json{} serializations +An \execbrokerclass{} \webservice{} MUST be able to accept both \yaml{} or \json{} serializations of the \codeword{offer}. The serialization SHOULD be declared in the HTTP request using the \codeword{Content-Type} header. \begin{itemize} @@ -2455,13 +2455,13 @@ \subsubsection{Offer POST} \subsection{ExecutionWorker} \label{execution-worker-spec} -Accepting an offer from an \execplanner{} service creates a \job{} on an associated \execworker{}, -with status \codeword{PENDING} until the \job{} is started automatically by the \execworker{}. +Accepting an offer from an \execbrokerclass{} service creates a \job{} on an associated \execworkerclass{}, +with status \codeword{PENDING} until the \job{} is started automatically by the \execworkerclass{}. -The offer from the \execplanner{} will contain the URL \job{} in the \execworker{}. +The offer from the \execbrokerclass{} will contain the URL \job{} in the \execworkerclass{}. \begin{itemize} - \item \execplanner{} is responsible for creating and starting the \job{}. + \item \execbrokerclass{} is responsible for creating and starting the \job{}. \item Client can use a HEAD request to check network access at anytime. \item Client can use a GET request to check the status of the \job{} at anytime. \item Client can cancel the \job{} at anytime. @@ -2475,14 +2475,14 @@ \section{The \datamodel{}} The following section describes the core \datamodel{} using a YAML syntax to define the structure with comments to describe the elements. -Note that this does not tie the \execplanner specification to a YAML representation. +Note that this does not tie the \execbrokerclass specification to a YAML representation. The intention is to define a portable \datamodel{} that can be serialised into a number of different formats, including YAML, JSON and XML. \subsection{Type URIs and specifications} \label{type-and-spec} -Several parts of the \ivoa{} \executionplanner{} \datamodel{} follow a common pattern, using a URI +Several parts of the \ivoa{} \executionbroker{} \datamodel{} follow a common pattern, using a URI to identify a \codeword{type} followed a \codeword{spec} section to fill in the details. This pattern is adopted from a similar pattern used by \kubernetes{}. @@ -2497,7 +2497,7 @@ \subsection{Type URIs and specifications} .... \end{lstlisting} -However, the \executionplanner{} \datamodel{} specifically recomends using a long lasting resolvable +However, the \executionbroker{} \datamodel{} specifically recomends using a long lasting resolvable HTTP URL as the type identifier. \begin{lstlisting}[] @@ -2536,18 +2536,18 @@ \subsection{Type URIs and specifications} recomends using a simple HTTP URLs. This lowers the barrier to entry and makes it simpler for the end user to resolve the URL into a description. -\subsection{\execplanner{} request} +\subsection{\execbrokerclass{} request} \label{datamodel-request} -The main section of the \execplanner{} \datamodel{} describes the \codeword{request} block, +The main section of the \execbrokerclass{} \datamodel{} describes the \codeword{request} block, which describes an \executablething{} and the resources needed to execute it. \\ \\ The \codeword{request} block is used in several places in the \datamodel{}: \begin{itemize} - \item The main body of an \execplanner{} \codeword{request}. - \item The main body of each \codeword{offer} in an \execplanner{} response. - \item The main body of an \execworker{} \job{} record. + \item The main body of an \execbrokerclass{} \codeword{request}. + \item The main body of each \codeword{offer} in an \execbrokerclass{} response. + \item The main body of an \execworkerclass{} \job{} record. \end{itemize} \subsubsection{Executable} @@ -2594,7 +2594,7 @@ \subsubsection{Jupyter notebook} \end{itemize} \item An \codeword{endpoint} URL that points to the live notebook platform. \begin{itemize} - \item The \codeword{endpoint} URL is set by the \execworker{} once the \job{} is \codeword{READY}. + \item The \codeword{endpoint} URL is set by the \execworkerclass{} once the \job{} is \codeword{READY}. \end{itemize} \end{itemize} @@ -2634,7 +2634,7 @@ \subsubsection{Zeppelin notebook} \end{itemize} \item An \codeword{endpoint} URL that points to the live notebook platform. \begin{itemize} - \item The \codeword{endpoint} URL is set by the \execworker{} once the \job{} is \codeword{READY}. + \item The \codeword{endpoint} URL is set by the \execworkerclass{} once the \job{} is \codeword{READY}. \end{itemize} \end{itemize} @@ -2802,10 +2802,10 @@ \subsubsection{Generic compute resources} \hfill \break The \codeword{spec} for a generic computing resource may contain the following optional properties: \begin{itemize} - \item The minimum number of cpu cores needed, set by the client in the \execplanner{} \codeword{request}. - \item The maximum number of cpu cores available, set by the \execplanner{} service in an \codeword{offer}. - \item The minimum amount of memory needed (in GiB), set by the client in the \execplanner{} \codeword{request}. - \item The maximum amount of memory available (in GiB), set by the \execplanner{} service in an \codeword{offer}. + \item The minimum number of cpu cores needed, set by the client in the \execbrokerclass{} \codeword{request}. + \item The maximum number of cpu cores available, set by the \execbrokerclass{} service in an \codeword{offer}. + \item The minimum amount of memory needed (in GiB), set by the client in the \execbrokerclass{} \codeword{request}. + \item The maximum amount of memory available (in GiB), set by the \execbrokerclass{} service in an \codeword{offer}. \end{itemize} \begin{lstlisting}[] @@ -2912,7 +2912,7 @@ \subsection{Response} \subsubsection{Positive response} \label{datamodel-positive-response} -A positive (yes, this platform can execute the task) \execplanner{} service response contains \codeword{result} +A positive (yes, this platform can execute the task) \execbrokerclass{} service response contains \codeword{result} set to \codeword{YES}, and a list of offers. \subsubsection{Offer} @@ -2920,7 +2920,7 @@ \subsubsection{Offer} Each offer contains a unique identifier a status value and an expiry time for the offer followed by an updated copy of the \codeword{request} with details -filled in by the \execplanner{} service. +filled in by the \execbrokerclass{} service. The \codeword{offer} \codeword{status} .... @@ -2949,7 +2949,7 @@ \subsubsection{Offer} \subsubsection{Negative response} \label{datamodel-negative-response} -A negative (no, this platform cannot execute the task) \execplanner{} service response contains \codeword{result} +A negative (no, this platform cannot execute the task) \execbrokerclass{} service response contains \codeword{result} set to \codeword{NO}, followed by an optional list of reasons explaining why the request was rejected. @@ -2973,10 +2973,10 @@ \subsubsection{Negative response} \subsection{Job} \label{datamodel-job} -An \execworker{} \workerjob{} record consists of a unique identifier for the job, +An \execworkerclass{} \workerjob{} record consists of a unique identifier for the job, and a \codeword{phase} indicating what execution stage the \workerjob{} has reached. -Followed by an updated copy of the request \codeword{body} from the \execplanner{} -offer with details filled in by the \execworker{} as the \workerjob{} is executed. +Followed by an updated copy of the request \codeword{body} from the \execbrokerclass{} +offer with details filled in by the \execworkerclass{} as the \workerjob{} is executed. \begin{lstlisting}[] job: @@ -3035,49 +3035,49 @@ \section{Resource type URLs} https://www.purl.org/ivoa.net/executable-types/example -https://github.com/Zarquan/ExecutionPlanner/blob/main/types/executable-types/example-executable.md +https://github.com/ivoa-std/ExecutionBroker/blob/main/types/executable-types/example-executable.md https://www.purl.org/ivoa.net/executable-types/jupyter-notebook -https://github.com/Zarquan/ExecutionPlanner/blob/main/types/executable-types/jupyter-notebook.md +https://github.com/ivoa-std/ExecutionBroker/blob/main/types/executable-types/jupyter-notebook.md https://www.purl.org/ivoa.net/executable-types/oci-container -https://github.com/Zarquan/ExecutionPlanner/blob/main/types/executable-types/oci-container.md +https://github.com/ivoa-std/ExecutionBroker/blob/main/types/executable-types/oci-container.md https://www.purl.org/ivoa.net/resource-types/generic-compute -https://github.com/Zarquan/ExecutionPlanner/blob/main/types/resource-types/generic-compute.md +https://github.com/ivoa-std/ExecutionBroker/blob/main/types/resource-types/generic-compute.md https://www.purl.org/ivoa.net/resource-types/nvidia-ad104 -https://github.com/Zarquan/ExecutionPlanner/blob/main/types/resource-types/nvidia-ad104.md +https://github.com/ivoa-std/ExecutionBroker/blob/main/types/resource-types/nvidia-ad104.md https://www.purl.org/ivoa.net/resource-types/xilinx-vu19p -https://github.com/Zarquan/ExecutionPlanner/blob/main/types/resource-types/xilinx-vu19p.md +https://github.com/ivoa-std/ExecutionBroker/blob/main/types/resource-types/xilinx-vu19p.md https://www.purl.org/ivoa.net/storage-types/ephemeral-storage -https://github.com/Zarquan/ExecutionPlanner/blob/main/types/storage-types/ephemeral-storage.md +https://github.com/ivoa-std/ExecutionBroker/blob/main/types/storage-types/ephemeral-storage.md https://www.purl.org/ivoa.net/storage-types/amazon-s3 -https://github.com/Zarquan/ExecutionPlanner/blob/main/types/storage-types/amazon-s3.md +https://github.com/ivoa-std/ExecutionBroker/blob/main/types/storage-types/amazon-s3.md https://www.purl.org/ivoa.net/storage-types/persistent-storage -https://github.com/Zarquan/ExecutionPlanner/blob/main/types/storage-types/persistent-storage.md +https://github.com/ivoa-std/ExecutionBroker/blob/main/types/storage-types/persistent-storage.md https://www.purl.org/ivoa.net/storage-types/rucio-storage -https://github.com/Zarquan/ExecutionPlanner/blob/main/types/storage-types/rucio-storage.md +https://github.com/ivoa-std/ExecutionBroker/blob/main/types/storage-types/rucio-storage.md https://www.purl.org/ivoa.net/storage-types/vospace-storage -https://github.com/Zarquan/ExecutionPlanner/blob/main/types/storage-types/vospace-storage.md +https://github.com/ivoa-std/ExecutionBroker/blob/main/types/storage-types/vospace-storage.md https://www.purl.org/ivoa.net/authentication-types/basic-auth -https://github.com/Zarquan/ExecutionPlanner/blob/main/types/authentication-types/basic-auth.md +https://github.com/ivoa-std/ExecutionBroker/blob/main/types/authentication-types/basic-auth.md https://www.purl.org/ivoa.net/authentication-types/oidc-auth -https://github.com/Zarquan/ExecutionPlanner/blob/main/types/authentication-types/oidc-auth.md +https://github.com/ivoa-std/ExecutionBroker/blob/main/types/authentication-types/oidc-auth.md https://www.purl.org/ivoa.net/authentication-types/rfc7519-token -https://github.com/Zarquan/ExecutionPlanner/blob/main/types/authentication-types/rfc7519-token.md +https://github.com/ivoa-std/ExecutionBroker/blob/main/types/authentication-types/rfc7519-token.md https://www.purl.org/ivoa.net/webservice-types/value-update -https://github.com/Zarquan/ExecutionPlanner/blob/main/types/webservice-types/value-update.md +https://github.com/ivoa-std/ExecutionBroker/blob/main/types/webservice-types/value-update.md YAML specification https://yaml.org/spec/ diff --git a/ExecutionPlanner.edit b/ExecutionPlanner.edit deleted file mode 100644 index a25e7f7..0000000 --- a/ExecutionPlanner.edit +++ /dev/null @@ -1,1682 +0,0 @@ -\documentclass[11pt,a4paper]{ivoa} -\input tthdefs - -\usepackage{xspace} -% Standard terms used throughout the document, -% defined as macro commands to maintain consistency - -% Using non-breaking space character. -% https://stackoverflow.com/a/1012891 - -\newcommand{\xml} {XML} -\newcommand{\json} {JSON} -\newcommand{\yaml} {YAML} - -\newcommand{\datamodel} {data~model} -\newcommand{\webservice} {webservice} -\newcommand{\webbrowser} {web browser} - -\newcommand{\ivoa} {IVOA} -\newcommand{\uws} {UWS} -\newcommand{\vospace} {VOSpace} - -\newcommand{\execplanner} {ExecutionPlanner} -\newcommand{\execworker} {ExecutionWorker} -\newcommand{\executionplanner} {Execution~Planner} -\newcommand{\executionplanning} {Execution~Planning} - -\newcommand{\jupyter} {Jupyter} -\newcommand{\jupyterhub} {JupyterHub} -\newcommand{\binderhub} {BinderHub} -\newcommand{\jupyternotebook} {Jupyter notebook} - -\newcommand{\esap} {ESAP} -\newcommand{\escape} {ESCAPE} -\newcommand{\datalake} {DataLake} -\newcommand{\rucio} {Rucio} - -\newcommand{\python} {Python} -\newcommand{\pythonprogram} {Python program} - -\newcommand{\apache} {Apache} -\newcommand{\spark} {Spark} -\newcommand{\pyspark} {PySpark} -\newcommand{\zeppelin} {Zeppelin} - -\newcommand{\ocicontainer} {OCI~container} -\newcommand{\docker} {Docker} -\newcommand{\dockercompose} {Docker compose} -\newcommand{\dockercontainer} {Docker container} - -\newcommand{\openstack} {Openstack} -\newcommand{\kubernetes} {Kubernetes} - -\newcommand{\codeword}[1] {\texttt{#1}} -\newcommand{\footurl}[1] {\footnote{\url{#1}}} - -\newcommand{\dataset} {dataset} -\newcommand{\datascience} {data~science} -\newcommand{\scienceplatform} {science~platform} - -\newcommand{\executable} {\textit{executable}} -\newcommand{\executablething} {\textit{executable}~thing} -\newcommand{\excutabletask} {\textit{executable} task} -\newcommand{\workerjob} {\textit{job}} - -\newcommand{\cpu} {CPU} -\newcommand{\gpu} {GPU} -\newcommand{\nvidiagpu} {NVIDIA~AD104~GPU} - -\newcommand{\job} {\textit{job}} -\newcommand{\task} {task} - -\newcommand{\scalable} {scalable} - -\usepackage{listings} -\usepackage{xcolor} - -%\colorlet{punct}{red!60!black} -\colorlet{numb}{magenta!60!black} -\definecolor{html-gray}{HTML}{EEEEEE} -\definecolor{light-gray}{gray}{0.95} -\definecolor{delim}{RGB}{20,105,176} - -\lstset{ - basicstyle=\small\ttfamily, - columns=fullflexible, - frame=none, - backgroundcolor=\color{light-gray}, - stepnumber=1, - %numbers=left, - numbers=none, - numberstyle=\small, - numbersep=8pt, - %xleftmargin=\parindent, - xrightmargin=1cm, - showstringspaces=false, - keepspaces=true, - breaklines=true, - linewidth=14cm, - frame=none -} - -% https://tex.stackexchange.com/questions/83085/how-to-improve-listings-display-of-json-files -% https://tex.stackexchange.com/a/83100 -% https://tex.stackexchange.com/questions/10828/indent-a-code-listing-in-latex -% https://tex.stackexchange.com/a/10831 -\lstdefinelanguage{json}{ - literate= - *{0}{{{\color{numb}0}}}{1} - {1}{{{\color{numb}1}}}{1} - {2}{{{\color{numb}2}}}{1} - {3}{{{\color{numb}3}}}{1} - {4}{{{\color{numb}4}}}{1} - {5}{{{\color{numb}5}}}{1} - {6}{{{\color{numb}6}}}{1} - {7}{{{\color{numb}7}}}{1} - {8}{{{\color{numb}8}}}{1} - } - -\lstdefinelanguage{yaml}{ - literate= - *{0}{{{\color{numb}0}}}{1} - {1}{{{\color{numb}1}}}{1} - {2}{{{\color{numb}2}}}{1} - {3}{{{\color{numb}3}}}{1} - {4}{{{\color{numb}4}}}{1} - {5}{{{\color{numb}5}}}{1} - {6}{{{\color{numb}6}}}{1} - {7}{{{\color{numb}7}}}{1} - {8}{{{\color{numb}8}}}{1} - } - -\hyphenation{Exe-cut-able-Thing} - -\title{IVOA Execution Planner} - -% see ivoatexDoc for what group names to use here; use \ivoagroup[IG] for -% interest groups. -\ivoagroup{GWS} - -\author[http://www.ivoa.net/twiki/bin/view/IVOA/DaveMorris] - {Dave Morris} - -\editor[http://www.ivoa.net/twiki/bin/view/IVOA/DaveMorris] - {Dave Morris} - -% \previousversion[????URL????]{????Concise Document Label????} -\previousversion{This is the first public release} - -\begin{document} -\begin{abstract} -\label{abstract} - -One of the long term goals of the IVOA has been to enable users to -move the code to the data. -This is becoming more and more important as the size and complexity -of the \dataset{}s available in the virtual observatory increases. -%\citep{gaia-at-esac} -%\footurl{https://www.skao.int/en/explore/big-data} -%\footurl{https://www.lsst.org/scientists/keynumbers} - -The \ivoa{} \executionplanner{} provides a step towards making this possible. - -The \ivoa{} \executionplanner{} is designed to address a specific question; -given an executable thing, e.g. a \pythonprogram{} or \jupyternotebook{}. -What facilities are available to run it? - -To do this, the \ivoa{} \executionplanner{} specification defines -a \datamodel{} and \webservice{} API for describing executable things -and the resources needed to execute them. - -Together these components enable a user to ask a simple question -\textit{"Where (and when) can I execute my program?"} - -This in turn enables users to move code between \scienceplatform{}s. -Allowing them to develop their code on one platform and then apply it to a different -\dataset{} by sending it to execute on another platform. - -\end{abstract} - -\section*{Acknowledgments} -\label{acknowledgments} - -The authors would like to thank all the participants in the IVOA and ESCAPE projects -who have contributed their ideas, critical reviews, and suggestions to this document. - -\section*{Conformance-related definitions} - -The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'', and -``OPTIONAL'' (in upper or lower case) used in this document are to be -interpreted as described in IETF standard RFC2119 \citep{std:RFC2119}. - -The \emph{Virtual Observatory (VO)} is a general term for a collection of -federated resources that can be used to conduct astronomical research, -education, and outreach. -The \href{https://www.ivoa.net}{International Virtual Observatory Alliance (IVOA)} -is a global collaboration of separately funded projects to develop standards and -infrastructure that enable VO applications. - -\section{Introduction} -\label{introduction} - -The \ivoa{} \executionplanner{} specification defines two \webservice{} interfaces, -the \execplanner{} and the \execworker{}, and a common \datamodel{} for describing -executable tasks. - -Together these provide a common interface for service discovery, resource allocation -and execution scheduling across a heterogeneous federation of different types of -execution platform. - -\begin{itemize} - \item \execplanner{} \webservice{} – a discovery service to find execution platforms, allocate resources and schedule execution. - \item \execworker{} \webservice{} – an asynchronous service for executing tasks (based on the \ivoa{} \uws{} pattern). - \item \execplanner{} \datamodel{} – a common data model for describing an executable thing and its resource requirements. -\end{itemize} - -\subsection{Role within the VO Architecture} -\label{subsec:ivoarole} - -% As of ivoatex 1.2, the architecture diagram is generated by ivoatex in -% SVG; copy ivoatex/archdiag-full.xml to role_diagram.xml and throw out -% all lines not relevant to your standard. -% Notes don't generally need this. If you don't copy role_diagram.xml, -% you must remove role_diagram.pdf from SOURCES in the Makefile. -\begin{figure} -\centering -\includegraphics[width=0.9\textwidth]{role_diagram.pdf} -\caption{Architecture diagram showing the \ivoa{} \executionplanner{}'s role in the \ivoa{}} -\label{fig:archdiag} -\end{figure} - -The IVOA Architecture\citep{2010ivoa.rept.1123A} provides a high-level view of how \ivoa{} -standards work together to connect users and applications with providers of data -and services. -Fig.~\ref{fig:archdiag} shows the role the \ivoa{} \executionplanner{} plays within this architecture. - -In response to the increasing size and complexity of the next generation of science \dataset{}s -a number of \ivoa{} members are developing intergrated \scienceplatform{}s which bring -together the \dataset{}s co-located with the compute resources needed to analyse -them.\footurl{https://data.lsst.cloud/}\footurl{https://rsp.lsst.io/index.html} - -The \scienceplatform{}s make extensive use of the \ivoa{} data models and -vocabularies to describe their \dataset{}s, and use the \ivoa{} data access -services to find and access data from other data providers. -In addition, some of the \scienceplatform{}s use \ivoa{} \vospace{} services to manage -data transfers to and from local storage co-located with the compute resources. - -However, to date the \ivoa{} does not provide any APIs or \webservice{} interfaces that -enable \scienceplatform{}s to exchange the software used to analyse the data. -The \ivoa{} \executionplanner{} provides a step towards making this possible. - -This places the \ivoa{} \executionplanner{} in the same region of the \ivoa{} architecture -as the \ivoa{} \vospace{} specification \citep{2009ivoa.specQ1007G}, -providing an infrastructure level service that enables service discovery, -resource allocation and execution scheduling across a heterogeneous federation -of execution platforms. - -The \ivoa{} \executionplanner{} specification refers to the -\ivoa{} Single-Sign-On standard \citep{2017ivoa.spec.0524T} -for authentication (see section xx )%\ref{subsec:authentication} -and the -\ivoa{} Credential Delegation Protocol \citep{2010ivoa.spec.0218P} -for delegating credentials to other services. - -The \ivoa{} \executionplanner{} specification also describes how to register -an \execplanner{} service in the -\ivoa{} Registry \citep{2009ivoa.spec.1104B}, -making it findable within the wider context of the VO. - -\subsection{Executable things} -\label{executablething} - -To understand the problem that the \ivoa{} \executionplanner{} is trying to solve -it is useful to describe what an \executablething{} is in this context. -In general terms, this document refers to something that can be executed, or run, -as an \executable{}. - -To explain what this means we can start with a science domain function that we want to perform. -For example, the mathematical concept of the square root of a number. -We can calculate the square root of a positive number using the Newton–Raphson -algorithm\footurl{https://en.wikipedia.org/wiki/Newton\%27s_method} -which produces successively closer approximations to the result. -However, in general case, this mathematical description of the algorithm would not be -considered to be an \executablething{}. - -We can write a \pythonprogram{} to use this algorithm to calculate the square root of a number. -This is the first identifiable \executablething{} in our example. -To be able to use this \executablething{}, you would need a computing resource with the appropriate -hardware and software environment. In this case, a computing resource with the \python{} interpreter -installed along with any additional \python{} modules required by the program. -This environment is often referred to as the \python{} runtime. - -In the context of \scienceplatform{}s and \datascience{}, a common pattern is to provide this environment -using an OCI\footurl{https://opencontainers.org/}, -or Docker\footurl{https://docs.docker.com/get-started/what-is-a-container/} container, -to package the \pythonprogram{} and runtime together as a single binary object. -This package, or container, is itself an \executablething{}. One which requires a different execution -environment than the original \pythonprogram{}. -The aim of containerization is to package \executablething{}s together with the software environment -they need as a binary object that interfaces with a standard execution environment, -referred to as the \textit{container runtime}. -To be able to use this \executablething{}, you would need a computing resource with the appropriate -hardware and software environment. In this case, a computing resource with the \ocicontainer{} runtime installed. - -We could also create a \jupyternotebook{} that demonstrates how to use our \pythonprogram{}. -This is the third \executablething{} in our example. -One which provides an interactive environment for the user to experiment with. -As before, to be able to use this \executablething{}, we would need a computing resource with -the appropriate hardware and software environment. -In this case, a computer with the \jupyternotebook{} platform installed along with all the \python{} modules -needed by our \pythonprogram{}. -In the context of \scienceplatform{}s and \datascience{}, a common pattern is to provide this environment as a \webservice{} -that allows the user to connect to the \jupyternotebook{} via a \webbrowser. - -From one algorithm that implements a science domain function, we have created three different \executablething{}s. -A \pythonprogram{}, an \ocicontainer{} packaging the \pythonprogram{}, and an interactive \jupyternotebook{} -that demonstrates how to use the \pythonprogram{}. -Each of which requires a different computing environment to execute. -A basic \python{} runtime, the \ocicontainer{} runtime, and a \jupyternotebook{} service. - -We may also want to consider the data that we are applying the algorithm to. -If we are running some small experiments to learn how to use the algorithm, then a basic computing -resource will probably be sufficient. -However, if we have a \dataset{} of ten million numbers that we want to process, then we may -need to consider adding extra storage to handle the input data and the results. -For a large \dataset{} it may also be worth using a \gpu{} to accelerate the calculation steps -for such a large \dataset{}. - -The \ivoa{} \executionplanner{} \datamodel{} provides a way to describe what each of these \executablething{}s -are and what resources are needed to execute them. -This can include things like number of \cpu{} cores and amount of memory it needs, -whether it needs a \gpu{}, the location of the input data, the storage space needed to perform -the calculation and the storage space needed to save the results. - -\section{Client-server conversation} -\label{conversation} - -The core idea behind the \ivoa{} \executionplanner{} is based on a conversation between a client -and one or more \execplanner{} services to discover where, how, and when, an \executablething{} can be -executed. - -The conversation starts with the client sending a description of the \executablething{} they want to -run to the -\execplanner{} services, which respond with a top level \codeword{YES|NO} answer, and if -the answer is \codeword{YES}, a list of offers describing how it -can be executed on their platform. - -\begin{lstlisting}[] -Request - Can this platform execute ? -Response - YES, list of [] -\end{lstlisting} - -The client can then choose which of the offers it wants to use and reply -with a message accepting the offer. -In response the \execplanner{} will mark the resources in the offer as reserved, -initiate a \workerjob{} in an \execworker{} service to execute the task -and reply with details of how to access it. - -\begin{lstlisting}[] -Request - I accept [n] -Response - -\end{lstlisting} - -The client can then uses the connection details in the \workerjob{} response to contact -the \execworker{} service and track its status. - -Note that the client does not need to cancel the offers made by the other \execplanner{} services. -Offers are only valid for a limited period of time, and expire naturally when they reach the end -of their lifetime. - -A good way of explaining how a client would use the \datamodel{} to describe the \executablething{} -that it wants to execute is to think about the questions that a client would ask to discover if a platform has the -resources available to execute the task. - -\subsection{The \executable{}} -\label{executable} - -At the simplest level the client just needs to check whether a platform is able to execute a particular -type of \excutabletask{}. -For example, \textit{"Is this platform able to run a \jupyternotebook{}?"} - -In order to do this, the request needs to specify the task type, e.g. \jupyternotebook{}, -along with details about it, e.g. where to fetch the notebook from. - -The information in this part of the \datamodel{} will be different for each type of \executable{}. -Rather than try to model every possible type of \executable{} in one large \datamodel{}, -the \datamodel{} for each type is described in an extension to the core \datamodel{}. - -To support this, the core \datamodel{} defines two fields: -\begin{itemize} - \item \codeword{type} - a URI identifying the type of \executable{}. - \item \codeword{spec} - a place holder for type specific details. -\end{itemize} - -\begin{lstlisting}[] -# ExecutionPlanner client request. -# Details of the executable. -executable: - - # A URI identifying the type of executable. - # e.g. - # https://www.purl.org/ivoa.net/ep/task-type/oci-container - # https://www.purl.org/ivoa.net/ep/task-type/jupyter-notebook - type: "https://www.purl.org/ivoa.net/ep/task-type/example" - - # The details, specific to the type of executable. - spec: {} -\end{lstlisting} - -The \datamodel{} for each type of \executable{} defines the metadata needed to -describe that particular type. -For example, the \datamodel{} for a \jupyternotebook{} needs to describe where -to fetch the source code for the notebook from. -\begin{lstlisting}[] -# ExecutionPlanner client request. -# Details of the executable. -executable: - # A URI identifying the type of executable. - type: "https://www.purl.org/ivoa.net/ep/task-type/jupyter-notebook" - - # The details, specific to a Jupyter notebook. - spec: - notebook: "https://.../example.jpnb" -\end{lstlisting} - -It may also include a reference to a \codeword{requirements.txt} file that describes any additional \python{} -libraries needed to run the notebook. -\begin{lstlisting}[] -# ExecutionPlanner client request. -# Details of the executable. -executable: - # A URI identifying the type of executable. - type: "https://www.purl.org/ivoa.net/ep/task-type/jupyter-notebook" - - # The details, specific to a Jupyter notebook. - spec: - notebook: "https://.../example.jpnb" - requirements: "https://.../requirements.txt" -\end{lstlisting} - -The \datamodel{} for an \ocicontainer{} needs to describe what operating system and system architecture -the container is built for, and where to fetch the binary image from. - -\begin{lstlisting}[] -# ExecutionPlanner client request. -# Details of the executable. -executable: - # A URI identifying the type of executable. - type: "https://www.purl.org/ivoa.net/ep/task-type/oci-container" - - # The details, specific to an OCI container. - spec: - os: "linux" - arch: "amd64" - repo: "ghcr.io" - image: "ivoa/oligia-webtop" - version: "ubuntu-2022.01.13" -\end{lstlisting} - -This pattern of using a \codeword{type} URI to identify the type of thing, and then a -\codeword{spec} block to add the type specific details is used in several places in the -\executionplanner{} \datamodel{}. -This enables us to keep the core \datamodel{} relatively small, defining the common aspects -needed to describe an \executablething{} and the resources it needs, while allowing the -\datamodel{} to be extended to describe a wide range of different types of things. - -This pattern makes it easy for projects outside the core \ivoa{} community to add new -types of \executablething{}s and resources appropriate for their science domain. - -Using a URI to identify the task type means that implementations do not need to understand -all of the different possible types of \executable{}. -If a service doesn’t recognize a particular type, it can simply reply \codeword{NO}. - -\begin{lstlisting}[] -Request - Can this platform execute ? -Response - NO -\end{lstlisting} - -\subsection{Resources} -\label{resources} - -At the next level the client may need to check whether a platform has sufficient compute resources -needed to execute a particular task. -For example, \textit{"Can this platform provide enough resources to run this \jupyternotebook{}?"} - -In order to do this the request would not only need to describe the \executable{} itself, -but also the minimum level of compute resources needed in terms of \cpu{} cores, memory, \gpu{}s -and disc space needed to execute it. - -\subsubsection{Level 2a - compute resources} -\label{compute-resources} - -The \datamodel{} for describing compute resources is, in most cases, common to all types of \executable{}, -so the \datamodel{} for these requirements are defined as part of the core \executionplanner{} \datamodel{}. - -It is important to note that all of the resource requirements are optional. -As in the example from the previous section, a request to execute a simple \jupyternotebook{} -would not need to include any resource details. - -\begin{lstlisting}[] -# ExecutionPlanner client request. -# Details of the executable. -executable: - # A URI identifying the type of executable. - type: "https://www.purl.org/ivoa.net/ep/task-type/jupyter-notebook" - - # The details, specific to a Jupyter notebook. - spec: - notebook: "https://.../example.jpnb" -\end{lstlisting} - -As long as this \jupyternotebook{} only needs a minimal set of resources to run, e.g. -2 \cpu{} cores, 2G of memory and 20G of disc space, then this task probably doesn't need -any additional resources. - -However, if this \jupyternotebook{} needs a specific type of \gpu{} to function properly, -then it can be added to the request by specifying a compute resource with the specific type -of \gpu{}. - -\begin{lstlisting}[] -# ExecutionPlanner client request. -# Details of the executable. -executable: - # A URI identifying the type of executable. - type: "https://www.purl.org/ivoa.net/ep/task-type/jupyter-notebook" - # The details, specific to a Jupyter notebook. - spec: - notebook: "https://.../example.jpnb" - -# Details of the resources needed. -resources: - compute: - - name: "compute-001" - type: "https://.../generic-compute" - spec: - gpu: - # A URI identifying the type of GPU. - type: "https://www.techpowerup.com/gpu-specs/nvidia-ad104.g1013" -\end{lstlisting} -%TODO purl URI for the GPU type. - -With this detail added to the request, platforms that are not able to provide this kind of \gpu{} -would simply reply \codeword{NO}. - -\begin{lstlisting}[] -Request - Can this platform provide a 'NVIDIA AD104 GPU' ? -Response - NO -\end{lstlisting} - -Note that a platform does not need to know what a "\nvidiagpu{}" is to be able to reply with a sensible aswer. -If a platform receives a request for a resource that it doesn't understand, it MAY simply reply \codeword{NO}. - -\begin{lstlisting}[] -Request - Can this platform provide ? -Response - NO -\end{lstlisting} - -The only platforms that will reply \codeword{YES} are ones that understand what a "\nvidiagpu{}" -is and are able to provide access to one. - -The \datamodel{} for the \gpu{} resource follows the same extendable pattern as the \datamodel{} for -the \executable{}. A \codeword{type} URI to identify the type of \gpu{}, -and a \codeword{spec} section for type specific details, -e.g. the minimum amount of memory and number of shaders. - -\begin{lstlisting}[] -# ExecutionPlanner client request. - .... -# Details of the resources needed. -resources: - compute: - - name: "compute-001" - type: "https://.../generic-compute" - spec: - gpu: - # A URI identifying the type of GPU. - type: "https://www.techpowerup.com/gpu-specs/nvidia-ad104.g1013" - # The details, specific to a 'NVIDIA AD104 GPU'. - spec: - minmemory: 20 - minshaders: 6144 -\end{lstlisting} - -\subsubsection{Minimum and maximum} -\label{minandmax} - -The \datamodel{} for describing compute resources includes elements for specifying the numeric size -and number of resources such as \cpu{} cores, memory and storage. - -If the \jupyternotebook{} in our example needs a minimum of 8 \cpu{} cores and 16G of memory -to be able to perform its calculations, then this can be specified in the compute resource. - -\begin{lstlisting}[] -# ExecutionPlanner client request. - .... -# Details of the resources needed. -resources: - compute: - - name: "compute-001" - type: "https://.../generic-compute" - spec: - mincores: 8 - minmemory: 16 -\end{lstlisting} - -All of the \datamodel{} elements for specifying the size or number of resources are defined -as pairs of minimum and maximum values. -This allows a conversation between the \execplanner{} client and services -to discover the best platform to execute the task. - -The client requests the minimun resources it needs, -and each service responds with a set of offers which specify the maximum -level of resources they can offer. - -For example, if a platform is able to provide double the compute resources, -16 \cpu{} cores and 32G of memory, -then it can indicate this by specifying higher maximum values in its response. - -\begin{lstlisting}[] -# ExecutionPlanner service response. - .... -# Details of the resources offered. -resources: - compute: - - name: "compute-001" - type: "https://.../generic-compute" - spec: - mincores: 8 - maxcores: 16 - minmemory: 16 - maxmemory: 32 -\end{lstlisting} - -This response represents an offer to start with a minimum of 8 \cpu{} cores and 16G of memory -as requested, with the option to use a maximum of 16 \cpu{} cores and 32G of memory if needed. - -The client may receive different offers from different platforms and can pass this information -on the the user to allow them to choose the offer that best fits their use case. -The our example notebook may specify a minimum of 8 \cpu{} cores and 16G of memory, -but an offer of twice the resources allows the user more scope for experimenting with -more data or more complex algorithms. - -This \scalable{} compute resource represents something like a \kubernetes{} platform where the -execution can start with a minimum configuration and scale on demand up to a maximum limit. - -This is slightly different to a platform like \openstack{} which allocates resources -in specific blocks, defined by the set of \textit{'flavors'} available on that particular platform. -If the smallest flavor of virtual machine available on the platform has 16 \cpu{} cores and 24G of memory, -then the service can represent that by setting the minimum values in its offer to match available resources. - -\begin{lstlisting}[] -# ExecutionPlanner service response. - .... -# Details of the resources offered. -resources: - compute: - - name: "compute-001" - type: "https://.../generic-compute" - spec: - mincores: 16 - maxcores: 16 - minmemory: 24 - maxmemory: 24 -\end{lstlisting} - -This response represents an offer to start with a fixed allocation of 16 \cpu{} cores and 24G of memory. - -An \execplanner{} MAY NOT make an offer with less than the minimum resources requested. -For example, if an \openstack{} platform only has a virtual machine flavor with 1 \cpu{} core and 2G of memory, -then it MAY NOT offer this resource as it is less than the requested minimum. - -Note that the term \textit{'compute resource'} specifically avoids stating whether the -notebook will be run in an \openstack{} virtual machine or a \kubernetes{} cluster. -As far as the user is concerned, it should not matter, as long as the compute resource provides -sufficient \cpu{} cores and memory for the notebook to execute, the technical details of how the -platform implements are not relevant at this level of abstraction. - -\subsubsection{Storage resources} -\label{storage-resources} - -The resources section of the request can also be used to specify storage resources. - -There are two main types of storage resources: -\begin{itemize} - \item Internal storage resources that are provided by the platform. - \item External storage resources that are provided by an external source. -\end{itemize} - -There are two types of internal storage resources: -\begin{itemize} - \item Ephemeral storage available for the duration of the \job{}, created when the \job{} starts and released when the \job{} is completed. - \item Persistent storage that exists beyond the lifetime of the \job{}, created before the \job{} starts and remaining after the \job{} has completed. -\end{itemize} - -There are two levels of persistent storage: -\begin{itemize} - \item Managed resources that are created and deleted by the platform. - \item Unmanaged resources that are created and deleted by an external entity. -\end{itemize} - -The simplest of these are ephemeral storage resources managed by the execution platform. -For example, if the \jupyternotebook{} in our example requires 1024G of space to perform its calculations, -then this can be specified in the request by defining an ephemeral storage resource. - -\begin{lstlisting}[] -# ExecutionPlanner client request. - .... -# Details of the resources needed. -resources: - .... - storage: - - name: "scratch-space" - type: "https://.../ephemeral" - spec: - size: 1024 -\end{lstlisting} - -To enable the \jupyternotebook{} to access this storage, we need to add a -corresponding \codeword{volume} element to the compute resource that describes -where to mount the storage resource. - -For example, the following request asks for 1024G of ephemeral storage -that is mounted at \codeword{/temp} in the filesystem of the compute resource. -The compute volume is linked to the storage resource by the name of the -storage resource. - -\begin{lstlisting}[] -# ExecutionPlanner client request. - .... -# Details of the resources needed. -resources: - .... - compute: - - name: "compute-001" - .... - volumes: - - name: "temp-volume" - resource: "scratch-space" - path: "/temp" - mode: "rw" - storage: - - name: "scratch-space" - type: "https://.../ephemeral" - spec: - size: 1024 -\end{lstlisting} - -This pattern of separating the details of how a storage resource is implemented -from the details of how it is mounted inside a computing resource is based on a -pattern used by \kubernetes{} to describe storage volumes and their mount points -within containers\footurl{https://kubernetes.io/docs/concepts/storage/volumes/}. - -This pattern can also be used to define a storage resource that imports data from -an external source. -For example, if the user wanted to use the \jupyternotebook{} to analyse data stored -in an external S3 system, this can be done by defining an external storage resource -that describes where the data is, -and a corresponding volume mount inside the compute resource. - -\begin{lstlisting}[] -# ExecutionPlanner client request. - .... -# Details of the resources needed. -resources: - .... - compute: - - name: "compute-001" - .... - volumes: - - name: "data-volume" - resource: "source-data" - path: "/data" - mode: "r" - storage: - - name: "source-data" - type: "https://.../amazon-S3" - spec: - endpoint: "https://.../echo" - bucket: "example-data" -\end{lstlisting} - -Again, this pattern of separating how the data is stored outside the system -and how it appears inside the compute resource borrows heavily from the -pattern used by \kubernetes{} to describe persistent -volumes\footurl{https://kubernetes.io/docs/concepts/storage/persistent-volumes/}. - -The same pattern can be used to describe a storage resource that can be used -to save the analysis results, by defining a persistent storage resource -allocated by the system, and a corresponding volume mount inside the compute resource. - -\begin{lstlisting}[] -# ExecutionPlanner client request. - .... -# Details of the resources needed. -resources: - .... - compute: - - name: "compute-001" - .... - volumes: - - name: "results-volume" - resource: "results-storage" - path: "/results" - mode: "rw" - storage: - - name: "results-storage" - type: "https://.../persistent" - spec: - lifecycle: "managed" - minlifetime: "1D" - minsize: 100 -\end{lstlisting} - -By setting the storage resource type to \codeword{https://.../persistent}, -and setting the \codeword{lifecycle} to \codeword{managed}, -the client is asking the \execplanner{} service to take care of allocating -the storage and managing its lifecycle. -It is up to the \execplanner{} service to decide where to store the data and -how make it accessible after the \job{} has completed. - -For example, a science platform may have a \rucio{} storage system co-located -with the compute platform which it uses to store user generated data. -In which case the \execplanner{} service would respond with an offer that -stores the results in the \rucio{} system and provides details of how the user -can access it after the \job{} has completed. - -\begin{lstlisting}[] -# ExecutionPlanner service response. - .... -# Details of the resources offered. -resources: - .... - compute: - - name: "compute-001" - .... - volumes: - - name: "results-volume" - resource: "results-storage" - path: "/results" - mode: "rw" - storage: - - name: "results-storage" - type: "https://.../rucio" - spec: - lifecycle: "managed" - minlifetime: "1D" - maxlifetime: "5D" - minsize: 100 - maxsize: 200 - endpoint: "http://...." - objectid: "cdc78e7d-8032-497e-9a5b-01c720ea2223" -\end{lstlisting} - -In this example, the client requested at least 100G of storage available for 1 day -and in response the service is offering up to 220G available for 5 days stored in a -\rucio{} system co-located close to the compute platform. -It is up to the client to check if it can access the particular \rucio{} system -described in the response before it accepts the offer. - -Making an offer with the \codeword{lifecycle} set to \codeword{managed} and the -\codeword{maxlifetime} set to \codeword{5D} -means that the service will manage the lifecycle. -The storage will be available for 5 days after the \job{} completes and then it -will be deleted automatically. -The client doesn't need to worry about tidying up afterwards. - -It is important to note that at this point in time the storage is proposed, but not yet allocated. -The persistent storage is only allocated if the client accepts this particular offer. -This allows an \execplanner{} service to make multiple offers with different storage options, -allowing the client to select and accept the one that best fits its use case. - -The same \datamodel{} can be used the other way around as well. -If the client already knows where it wants the data to be stored, for example at a specific -\vospace{} location, then it can specify this in the request. - -\begin{lstlisting}[] -# ExecutionPlanner client request. - .... -# Details of the resources needed. -resources: - .... - compute: - - name: "compute-001" - .... - volumes: - - name: "results" - path: "/results" - mode: "rw" - storage: - - name: "results" - type: "https://.../vospace" - spec: - endpoint: "http://...." - path: "/experiment-21/results" - lifecycle: "unmanaged" -\end{lstlisting} - -It is up to the \execplanner{} service to work out if it is able to access the -\vospace{} location and mount it as a volume in the compute resource, -using either its own authentication, or a delegated form of the authentication -provided by the client. - -If it can access the \vospace{} location, then the \execplanner{} MAY respond -with an offer, otherwise if it can't access the \vospace{} location for whatever -reason the \execplanner{} MUST respond with \codeword{NO}. - -Note that in this example, the client has specified the lifecycle as \codeword{unmanaged}, -which means that the \execplanner{} is not involved in managing the creation or deletion -of the data in \vospace. -It is also possible for the client to ask the \execplanner{} service to manage -data in an external resource. - -\begin{lstlisting}[] -# ExecutionPlanner client request. - .... -# Details of the resources needed. -resources: - .... - storage: - - name: "results" - type: "https://.../vospace" - spec: - endpoint: "http://...." - path: "/experiment-21/results" - lifecycle: "managed" - maxlifetime: "2D" -\end{lstlisting} - -In this example, the client is specifying an external \vospace{} location to store the data, -but it is asking the \execplanner{} service to manage the lifecycle, creating the location -in \vospace{} at the start of the \job{} and deleting it 2 days after the \job{} completes. - -This negotiation of who is responsible for creating and deleting storage resources -enables a client to put together a workflow of interconnected steps, with the -\execplanner{} services -managing the lifecycle of the resources and releasing them automatically after they -are no longer needed. - -\subsection{Authentication} -\label{authentication} - -The client may also want to check whether the user account making the request -has sufficient access rights and resource quota needed to execute a \task{}. - -This is equivalent to asking: -\textit{"Do I have permission to use these resources to run this \jupyternotebook{}?"} - -There are two ways for the \execplanner{} service to check the user's identity, -using implicit and explicit authentication. - -The implicit method is for the client to authenticate to the \execplanner{} service -as normal and the service will use the identity from the request headers to check if the -user has sufficient access rights and resource quota to execute the \job{}. - -If the \webservice{} call to the \execplanner{} service is authenticated -using OpenIDConnect -(OIDC)\footurl{https://auth0.com/docs/authenticate/protocols/openid-connect-protocol}, -then the \execplanner{} MUST include a reference to the implicit -authentication in its reply, including enough non-secret -information to identify the authenticated identity. - -\begin{lstlisting}[] -# ExecutionPlanner server response. -.... -authentication: -- name: "http-request" - type: "https://.../oidc" - mode: "implicit" - spec: - subject: "user@domain" -\end{lstlisting} - -If the client uses an unknown authentication method in the \webservice{} call and -the \execplanner{} service recognises that an anthentication attempt has been made, -then it MUST reject the \webservice{} call with a 401 "Unauthenticated" response. -If the \execplanner{} service does not realise that an anthentication attempt has been made, -then this MAY result in the request being treated as an anonymous unauthenticated call. - -The \datamodel{} also allows for an explicit statement of identity in the request. -The \datamodel{} for authentication follows the same pattern as previous sections, -defining a \codeword{type} URI to identify the type of authentication method, -and a \codeword{spec} section for the type specific details. - -For example, to explicitly include a basic authentication with username and password -in the request: -\begin{lstlisting}[] -# ExecutionPlanner client request. -.... -authentication: -- name: "basic-auth" - type: "https://.../basic" - spec: - username: "..." - password: "..." -\end{lstlisting} - -This pattern allows the client to supply multiple authentication methods -in the request. The \execplanner{} service SHOULD select the authentication -methods it accepts from those in the request and include the name and -type of the methods in its reply along with enough non-secret -information to identify the authenticated identity. - -For example, if the client supplies both basic and token authentication -in the request: -\begin{lstlisting}[] -# ExecutionPlanner client request. -.... -authentication: -- name: "basic-auth" - type: "https://.../basic" - mode: "explicit" - spec: - username: "..." - password: "..." -- name: "token-auth" - type: "https://.../token" - mode: "explicit" - spec: - subject: "user@domain" - token: "..." -\end{lstlisting} - -If the \execplanner{} service only accepts the token authentication, it MUST -skip the basic authentication and only include the name and type of the token -based authentication in its reply. - -\begin{lstlisting}[] -# ExecutionPlanner server response. -.... -authentication: -- name: "token-auth" - type: "https://.../rfc7519" - mode: "explicit" - spec: - subject: "user@domain" -\end{lstlisting} - -If the \execplanner{} service does not recognise or support any of the authentication methods -included in the request, then the service MUST reject the request and reply with \codeword{NO}. - -\begin{lstlisting}[] -Request - Can I authenticate with ? -Response - NO -\end{lstlisting} - -The result is that an offer made by an \execplanner{} service SHOULD include details -of all the authenticated identities that are allowed to use the offer. - -If the original question is equivalent to: -\textit{"Do \textbf{these identities} have sufficient access rights and quota to run this \jupyternotebook{}?"} - -Then the response from the \execplanner{} service is equivalent to: -\textit{"This offer asserts that \textbf{these identities} have sufficient access rights and quota to run this \jupyternotebook{}?"} - -The client MUST use one of the authentication methods listed in the offer when -contacting the \execplanner{} service to accept the offer and start the \job{}. -The client MUST continue to use the same authentication method when making subsequent -requests to the \execworker{} service to access the \job{} status and results. - -The \executionplanner{} specification includes an initial set of authentication methods -corresponding to the methods defined in the -\ivoa{} Single-Sign-On standard\citep{2017ivoa.spec.0524T} - -\begin{itemize} - \item .... - \item .... -\end{itemize} - -However, the \datamodel{} also allows an \execplanner{} service to accept authentication -methods that are not covered by the \ivoa{} SSO standard. -A client is free to use any authentication method, including ones not covered by the -\ivoa{} SSO standard. It is up to the \execplanner{} service to decide how it -handles the authentication infomation it receives. - -This means that the \executionplanner{} services can be deployed in other domains outside the \ivoa{}, -without requiring them to adopt the full \ivoa{} SSO standard. - -\subsection{Date and time} -\label{date-time} - -The \codeword{datetime} part of the \datamodel{} enables the client and server to have a -conversation about when a \job{} can be executed. - -The client can specify one or more time periods when it would like to start the \job{}, -and the minimum duration that it thinks would be needed to complete the \job{}. - -The \execplanner{} service may respond with one or more offers that specify when the \job{} -would start and the maximum duration that the \job{} would be allowed to consume. -It is then up to the client to select which of the offers best suits its use case. - -The start time for a \job{} is expressed as an array of time intervals, as defined by -ISO 8601 \citep{std:iso8601}. -Specifically, type 1 or type 2 intervals (start/end and start/duration), excluding type 3 and 4 intervals -(duration/end and duration only) and excluding -repeats\footurl{https://www.iso.org/iso-8601-date-and-time-format.html}\footurl{https://en.wikipedia.org/wiki/ISO_8601}. - -Note that the duration part of the interval applies to the start time, specifying a -time range during which the \job{} may start. - -If no duration is specified, this means an absolute start time; -e.g. the \job{} SHOULD start at 11:30 on 14 August. -\begin{lstlisting}[] -# ExecutionPlanner client request. -.... -datetime: -- start: "2023-08-14T11:30Z" -\end{lstlisting} - -If the start and end are specified, this means the \job{} SHOULD start somewhere between -the start and end values; -e.g. the \job{} SHOULD start between 11:30 and 12:00 on 14 August. -\begin{lstlisting}[] -# ExecutionPlanner client request. -.... -datetime: -- start: "2023-08-14T11:30Z/T12:00Z" -\end{lstlisting} - -If a duration is specified, this means the \job{} SHOULD start somewhere between -start and the start plus duration; -e.g. the \job{} SHOULD start between 11:30 and 12:00 on 14 August. -\begin{lstlisting}[] -# ExecutionPlanner client request. -.... -datetime: -- start: "2023-08-14T11:30Z/PT30M" -\end{lstlisting} - -The \execplanner{} service SHOULD respond with one or more offers that start within -the ranges specified in the request. -The start times in the offers MAY be more precise than the start times in the request, -but they MUST all occur within at least one of the ranges specified in the request. - -The client MAY also specify the maximum and minimum execution duration, -expressed as time periods as defined by ISO 8601. - -For example, for the unattended batch mode execution of an \ocicontainer, the user might not be concerned about -when their \job{} starts, but they may want to specify the minimum duration needed to complete the task. - -In which case, the client may simply request a minimum duration of 1 hour. -\begin{lstlisting}[] -# ExecutionPlanner client request. -.... -datetime: -- minduration: "1H" -\end{lstlisting} - -The \execplanner{} service MAY respond with offers that start at different times and -set different values for the maximum duration. - -It MAY offer a maximum duration of 1 hour in the morning, starting at 11:00. -\begin{lstlisting}[] -# ExecutionPlanner server response. -.... -datetime: -- start: "2023-08-14T11:30Z" - minduration: "1H" - maxduration: "1H" -\end{lstlisting} - -It MAY also offer a longer allocation of 4 hours later in the evening, -starting sometime between 22:00 and 23:00. -\begin{lstlisting}[] -# ExecutionPlanner server response. -.... -datetime: -- start: "2023-08-14T22:00Z/PT1H" - minduration: "P1H" - maxduration: "P4H" -\end{lstlisting} - -Different values for start time and duration can be combined with different values for the -compute resources to make a range of different offers to the client. - -For example, if a client asks for 2 cores and 2G of memory for 1 hour sometime on 14 August: -\begin{lstlisting}[] -# ExecutionPlanner client request. - ... -resources: - compute: - mincores: 2 - minmemory: 2 -datetime: - - start: "2023-08-14/P1D" - minduration: "P1H" -\end{lstlisting} - -The \execplanner{} service may respond with 2 offers, -the minimum 2 cores and 2G of memory for 1 hour starting at 11:30, -and a larger offer of up to 8 cores and 8Gb of memory for up to 4 hours -starting between 22:00 and 23:00. - -\begin{lstlisting}[] -# ExecutionPlanner server response. -offers: -- name: "offer-001" - executable: - ... - resources: - compute: - mincores: 2 - maxcores: 2 - minmemory: 2 - maxmemory: 2 - datetime: - - start: "2023-08-14T11:30Z" - minduration: "P1H" - maxduration: "P1H" - -- name: "offer-002" - executable: - ... - resources: - compute: - mincores: 2 - maxcores: 8 - minmemory: 2 - maxmemory: 8 - datetime: - - start: "2023-08-14T22:00Z/T23:00Z" - minduration: "P1H" - maxduration: "P4H" -\end{lstlisting} - -It is then up to the client to decide which offer better suits their use case. -Accept the limited offer in the morning, or accept the more generous offer with -more resources and more time later in the day. - -If an \execplanner{} service is offering more than one option for the \codeword{datetime} -section it MUST make separate offers for each different option. -Even if all of the other parameters are the same, e.g. compute and storage resources, the -\execplanner{} service MUST NOT include more than one time slot in the same offer. -Technically the \datamodel allows an array of values for the \codeword{datetime} section, -but this would impose unnecessary complexity on the client for no real gain in user experience. - -\subsection{Triggers and callouts} -\label{triggers-callouts} - -The final part of the \datamodel{} enables the client to set up -\webservice{} API calls both to and from the \execplanner{} service -that can be used to control the state of a \job{}. - -\subsubsection{Level 5a - triggers} -\label{triggers} - -The \codeword{triggers} section of the \datamodel{} allows the client to -set up \webservice{} endpoints that will trigger actions that control the -state of a \job{} in an \execworker service. - -The simplest of these \webservice{} calls is a \codeword{value-update} endpoint. -This sets up a \codeword{POST} \webservice{} endpoint that a remote system can -call with a set of name-value pairs. - -\begin{lstlisting}[] -POST -name1: value1 -name2: value2 -name3: value3 -\end{lstlisting} - -The following example asks the \execplanner{} service to set up a \webservice{} endpoint -that will trigger an action depending on the value of the \codeword{status} -element in the \codeword{POST} data it receives. - -\begin{lstlisting}[] -# ExecutionPlanner client request. -.... -triggers: -- name: "trigger-001" - type: "https://.../value-update" - spec: - method: "POST" - content-type: "yaml" - conditions: - - name: "status" - value: "COMPLETED" - action: "start" - - name: "status" - value: "FAILED,CANCELLED" - action: "cancel" -\end{lstlisting} - -Which action taken is defined in the \codeword{conditions} section of the \codeword{trigger}. -In this case the action depends on the value of the \codeword{status} field in the \codeword{POST} data. -\begin{itemize} - \item If the value of \codeword{status} is \codeword{COMPLETED}, then start this \job{}. - \item If the value of \codeword{status} is \codeword{FAILED} or \codeword{CANCELLED}, then cancel this \job{}. -\end{itemize} - -Setting up a trigger to start a \job{} if the value of a \codeword{status} field is \codeword{COMPLETED} -may sound counter-intuitive, but the typical use case for triggers like this is to -control this \job{} based on the result of a \job{} in an upstream service that is performing the -step before this in a workflow. -In which case, we want this \job{} to wait until the previous step has completed before starting. -Hence the trigger that waits until the \codeword{status} of the \textbf{previous} step is -\codeword{COMPLETED} before starting this step. - -Defining a \codeword{start} action in the \codeword{triggers} section will modify the effect of a -start time defined in the \codeword{datetime} section. -The \execplanner{} service will not automatically start the \job{} when the start time range is reached. -Instead the \execplanner{} service will wait until the start action has been triggered before it starts the \job{}. - -\begin{itemize} - \item If the trigger is called before the start time range is reached, the event is recorded, - but no action is taken. - The \execplanner{} service will wait until the start time range is reached before starting the \job{}. - \item If the start time range is reached before the trigger has been called, - no action is taken. The \execplanner{} service will wait until the trigger is called before starting the \job{}. - \item If the trigger is called within the start time range, the \execplanner{} service will start \job{}. - \item If the start time range expires before the trigger has been called, the \execplanner{} service will cancel the \job{}. - \item If the trigger is called after the start time range, it has no effect. The \job{} should already have been cancelled. -\end{itemize} - -\subsubsection{Level 5b - callouts} -\label{callouts} - -The \codeword{callouts} section of the \datamodel{} allows the client to set up one or more remote -\webservice{} API calls that the \execplanner{} service will call at specific points in the lifecycle -of a \job{}. - -The following definition asks the \execplanner{} service to POST the name-value list defined in the -\codeword{template} to a remote \webservice{} endpoint when the status of this \job{} changes to be one -of \codeword{RUNNING}, \codeword{COMPLETED}, \codeword{FAILED} or \codeword{CANCELLED}. - -\begin{lstlisting}[] -.... -callouts: -- name: "callout-001" - type: "https://.../value-update" - spec: - method: "POST" - endpoint: "http://...." - triggers: - - state: "RUNNING,COMPLETED,FAILED,CANCELLED" - template: | - name: {{name}} - date: {{date}} - ident: {{ident}} - state: {{state}} -\end{lstlisting} - -The \codeword{callouts} part of the \datamodel{} forms the other half of a callout-trigger pair, -enabling a client to set up a chain of workflow steps that will be executed one after the other. - -\subsubsection{Level 5c - linked worflow} -\label{linked-worflow} - -If a user wants to set up a 2 step workflow containing step-A and step-B, -they can use callouts and triggers to link the steps together. - -The user would start by setting up step-B with a trigger that would wait until it received -a value-update \webservice{} API call with the value of \codeword{status} set to -\codeword{COMPLETED} before starting the \job{}. - -\begin{lstlisting}[] -name: "step-B" -executable: - ... -resources: - ... -triggers: -- name: "trigger-001" - type: "https://.../value-update" - spec: - method: "POST" - content-type: "yaml" - conditions: - - name: "status" - value: "COMPLETED" - action: start - - name: "status" - value: "FAILED,CANCELLED" - action: cancel -\end{lstlisting} - -Note that the client doesn't set the endpoint location for the trigger, that needs to -come from the \execplanner{} service. -The \webservice{} endpoint location for each trigger will be different for each of the -offers in the \execplanner{} service response. - -\begin{lstlisting}[] -.... -offers: -- name: "offer-001" - .... - triggers: - - name: "trigger-001" - type: "https://.../value-update" - spec: - method: "POST" - content-type: "yaml" - endpoint: "https://..../offer-001/trigger-001" - .... -\end{lstlisting} - -The user can then use this \webservice{} endpoint to set up step-A with a -remote \webservice{} API callout to trigger step-B when step-A completes. - -\begin{lstlisting}[] -name: "step-A" -executable: - ... -resources: - ... -datetime: - - start: "2023-08-14/P1D" -.... -callouts: -- name: "callout-001" - type: "https://.../value-update" - spec: - method: "POST" - content-type: "yaml" - endpoint: "https://..../offer-001/trigger-001" - triggers: - - state: "RUNNING,COMPLETED,FAILED,CANCELLED" - template: | - name: {{name}} - date: {{date}} - ident: {{ident}} - state: {{state}} -\end{lstlisting} - -The user can set a start time range on the steps that starts today and lasts for a day. -This will ensure that even if the triggers don't get called the \job{}s will -be cancelled and the resources released when the start time range expires at the end of the day. - -\begin{lstlisting}[] -executable: - ... -resources: - ... -datetime: - - start: "2023-08-14/P1D" -\end{lstlisting} - -The user can also set up a location in \vospace to transfer data between the steps. -In step-A they can set up a \codeword{managed} storage resource that points a location -in a \vospace service. Setting this up as \codeword{managed} with athe \codeword{maxlifetime} -and \codeword{minlifetime} set to 1 day means that the \vospace location will be created -automatically when step-A starts, and then be automatically deleted 1 day after step-A completes. - -This gives step-B enough time to collect the results but also ensures that the storage resource -is eventually released after a day. - -\begin{lstlisting}[] -name: "step-A" -executable: - ... -resources: - .... - storage: - - name: "results" - type: "https://.../vospace" - spec: - endpoint: "http://...." - path: "/step-A/results" - lifecycle: "managed" - minlifetime: "1D" - maxlifetime: "1D" -\end{lstlisting} - -In step-B the user just needs to create an \codeword{unmanaged} \vospace resource -that points to the same location in \vospace. - -\begin{lstlisting}[] -name: "step-B" -executable: - ... -resources: - .... - storage: - - name: "inputs" - type: "https://.../vospace" - spec: - endpoint: "http://...." - path: "/step-A/results" - lifecycle: "unmanaged" -\end{lstlisting} - -\section{Separation of concerns} -\label{separate-concerns} - -Separate who knows what .. -The players: -\begin{itemize} - \item The researcher who creates the notebook - \item The developer who creates the container - \item The publisher who publishes the data - \item The user who is running the analysis -\end{itemize} - - -\pagebreak - -\section{Request and response} -\label{request-response} - -Details of the request and response messages. -Timeline of request, offer and accept. - -\subsection{ExecutionPlanner} -\label{execution-planner} - -.... -.... - -\subsection{ExecutionWorker} -\label{execution-worker} - -Derived from IVOA UWS, using a similar \datamodel{}. -Accepting an offer on an \execplanner{} creates a job on the associated \execworker{}, -with status PENDING until the \job{} is started by the \execplanner{}. -\execplanner{} offer contains the Job URL of the \execworker{}. -Client can cancel the \job{} at anytime. -Client can use a HEAD request to check network access at anytime. - - -\pagebreak - -\section{General requirements} -\label{general-requirements} - -\begin{itemize} - \item .... -\end{itemize} - - -\section{Federated architecture} -\label{federation} - -The \execplanner{} and \execworker{} services are designed to be used at multiple levels within an organization. - -At the low level, an \execplanner{} and \execworker{} pair may be implemented as a -single web-application linked to a simple \docker execution service. -The configuration may be hard coded to only accept a fixed white list of container images -and a fixed allocation of compute resources for each job. - -e.g. container images xxxx and yyyy, 2 cpu cores, 2G of memory, max 1HR duration. - -A project or organization may deploy several of these low level services, -providing a range of different capabilities. - -Given a new task to execute a client can poll each of the services to see which one will -make an offer to execute it. - -The client does not need to have any prior knowledge about the services apart from their -endpoint address and perhaps the version of the API that they implement. -This information could come from an \ivoa{} Registry instance, or it could simply -be provided as a flat list in a configuration file for the client. - -A more flexible architecture could add another \execplanner{} service -a level above the low level task specific services. -This service would be configured with a list of the local task specific services -and act as an aggregator service sitting between the client and the low level services. -This aggregator service would forward a copy of each request it receives to each of the low level services and -then aggregate the offers from the individual responses into a single response that is sent back to the client. - -A simple aggregator service would just forward every request to all the low level services below it, -regardless of what the request contained. - -A more complex aggregator service may have some prior knowledge about what types of task or compute resources -each of the lower level services were able to offer, enabling it to make more informed decisions about -which low level serviecs to send the requests to. - -The aggregator service may also have an understanding of the location of data sets within the organization and -be able to route requests for tasks to different low level services depending on which data sets the tasks required. - -The aggregator service may expose the low level \execworker{} endpoints in its responses, -or it may also implement proxy interface acting as an aggregator for the \execworker{} -services. - -This configuration could be used to provide \execplanner{} and \execworker{} service interfaces -that bridged a firewall. Providing a public interface for external clients and forwarding the requests -to the internal \execplanner{} and \execworker{} services that are not accessible from outside the -firewall. - -A large organization with multiple sites may deploy a single high level \execplanner{} and \execworker{} -interface that handles task execution for the whole organization, forwarding the requests to mid-level -\execplanner{} and \execworker{} services at each site which in turn forwards the requests to -individual low-level \execplanner{} and \execworker{} services within the local site networks. - -The implementation at each level may be different, providing different levels of routing -and aggregation based on internal knowledge of the capabilities of the level below, -but the \execplanner{} and \execworker{} interfaces are the same at every level -in the organization. - -This could be expanded to include another level of \execplanner{} and \execworker{} services that -cross organization bondaries, providing a gateway that allows users from one project to access services -from other projects and organizations. - - -\begin{itemize} - \item Project - SKA - \begin{itemize} - \item Project gateway - \item Regional centers - \item Local data centers - \item Low level services - \begin{itemize} - \item Slurm batch service - \item Docker container service - \item JupterHub notebook service - \end{itemize} - \end{itemize} -\end{itemize} - -\begin{itemize} - \item Project - LSST - \begin{itemize} - \item Project gateway - \item Regional centers - \item Local data centers - \item Low level services - \begin{itemize} - \item Slurm batch service - \item Docker container service - \item JupterHub notebook service - \end{itemize} - \end{itemize} -\end{itemize} - -\begin{itemize} - \item Project - CTA - \begin{itemize} - \item Project gateway - \item Regional centers - \item Local data centers - \item Low level services - \begin{itemize} - \item Slurm batch service - \item Docker container service - \item JupterHub notebook service - \end{itemize} - \end{itemize} -\end{itemize} - -\begin{itemize} - \item Project - CERN - \begin{itemize} - \item Project gateway - \item Regional centers - \item Local data centers - \item Low level services - \begin{itemize} - \item Slurm batch service - \item Docker container service - \item JupterHub notebook service - \end{itemize} - \end{itemize} -\end{itemize} - - - - -\section{Example use cases} -\label{example-usecases} - -\begin{itemize} - \item .... -\end{itemize} - -\section{Even more stuff ...} -\label{more-stuff} - - - -\pagebreak -\appendix -\section{Changes from Previous Versions} - -No previous versions yet. -% these would be subsections "Changes from v. WD-..." -% Use itemize environments. - - -% NOTE: IVOA recommendations must be cited from docrepo rather than ivoabib -% (REC entries there are for legacy documents only) -\bibliography{ivoatex/ivoabib,ivoatex/docrepo} - - -\end{document} diff --git a/Makefile b/Makefile index c696c04..e44baaf 100644 --- a/Makefile +++ b/Makefile @@ -2,13 +2,13 @@ # for the targets available. # short name of your document (edit $DOCNAME.tex; would be like RegTAP) -DOCNAME = ExecutionPlanner +DOCNAME = ExecutionBroker # count up; you probably do not want to bother with versions <1.0 DOCVERSION = 1.0 # Publication date, ISO format; update manually for "releases" -DOCDATE = 2023-07-01 +DOCDATE = 2024-04-25 # What is it you're writing: NOTE, WD, PR, REC, PEN, or EN DOCTYPE = WD diff --git a/README.md b/README.md index 0de55a6..7a56943 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -[![PDF-Preview](https://img.shields.io/badge/Preview-PDF-blue)](../../releases/download/auto-pdf-preview/ExecutionPlanner-draft.pdf) +[![PDF-Preview](https://img.shields.io/badge/Preview-PDF-blue)](../../releases/download/auto-pdf-preview/ExecutionBroker-draft.pdf) -An initial draft for the IVOA ExecutionPlanner and ExecutionWorker web-services and the associated data model. +An initial draft for the IVOA ExecutionBroker and ExecutionWorker web-services and the associated data model. This document is distributed under CC-BY-SA. diff --git a/diagrams/accept-offer.pdf b/diagrams/accept-offer.pdf index cca8993..80ec7e9 100644 Binary files a/diagrams/accept-offer.pdf and b/diagrams/accept-offer.pdf differ diff --git a/diagrams/accept-offer.svg b/diagrams/accept-offer.svg index b644d54..31071be 100644 --- a/diagrams/accept-offer.svg +++ b/diagrams/accept-offer.svg @@ -1,276 +1,1143 @@ - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - - - - - - - - + + + + + + + + + + + + + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - - - - Client software + + + + + + Client software - - - - - - + + + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - - + + + + + + - - - - - - edit + + + + + + edit - - - - - - submit + + + + + + submit - - - - Execution Planner + + + + ExecutionBroker - - - - - + + + + + - - - - Execution Worker + + + + ExecutionWorker - - - - - + + + + + - - - - - - - + + + + + + + - - - - Job #### + + + + Job #### - - - - Accept offer {####} + + + + Accept offer {####} - - - - Accept {####} + + + + Accept {####} - - - - - + + + + + - - - - - + + + + + - - - - - - - + + + + + + + - - - - Offer #### + + + + Offer #### - - - - - + + + + + - - - - http://worker/job/#### + + + + http://worker/job/#### - - - - - + + + + + - \ No newline at end of file + diff --git a/diagrams/data-discovery.pdf b/diagrams/data-discovery.pdf index 74dc92d..b947738 100644 Binary files a/diagrams/data-discovery.pdf and b/diagrams/data-discovery.pdf differ diff --git a/diagrams/data-discovery.svg b/diagrams/data-discovery.svg index 5aa78ea..a961856 100644 --- a/diagrams/data-discovery.svg +++ b/diagrams/data-discovery.svg @@ -1,362 +1,1478 @@ - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - - - - Data discovery + + + + + + Data discovery - - - - - - + + + + + + - - - - API + + + + API - - - - implementation + + + + implementation - - - - - - - - + + + + + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - Software discovery + + + + Software discovery - - - - - - + + + + + + - - - - API + + + + API - - - - implementation + + + + implementation - - - - - - - - + + + + + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - - Client software + + + + + Client software - - - - - - + + + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - - + + + + + + - - - - - - edit + + + + + + edit - - - - - - submit + + + + + + submit - - - - Discovery + + + + Discovery - - - - Task description + + + + Execution request - - - - - - - - + + + + + + + + - - - - executable:.resources:. + + + + executable:.resources:. - - - - - + + + + + - - - - - + + + + + - - - - + + + + - - - - + + + + - - - - - + + + + + - \ No newline at end of file + diff --git a/diagrams/job-status.pdf b/diagrams/job-status.pdf index ea28acf..e4784a1 100644 Binary files a/diagrams/job-status.pdf and b/diagrams/job-status.pdf differ diff --git a/diagrams/job-status.svg b/diagrams/job-status.svg index a3aec14..d7eb7b1 100644 --- a/diagrams/job-status.svg +++ b/diagrams/job-status.svg @@ -1,245 +1,1008 @@ - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - - - - - - - - - + + + + + + + + + + + + + + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - - - - Client software + + + + + + Client software - - - - - - + + + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - - + + + + + + - - - - - - edit + + + + + + edit - - - - - - submit + + + + + + submit - - - - Execution Planner + + + + ExecutionBroker - - - - - + + + + + - - - - Execution Worker + + + + ExecutionWorker - - - - - + + + + + - - - - - - - + + + + + + + - - - - Job #### + + + + Job #### - - - - Job status {####} + + + + Job status {####} - - - - - - - + + + + + + + - - - - Offer #### + + + + Offer #### - - - - + + + + - - - - - + + + + + - - - - Status {####} ? + + + + Status {####} ? - \ No newline at end of file + diff --git a/diagrams/micro-services.pdf b/diagrams/micro-services.pdf index b480975..6281a3d 100644 Binary files a/diagrams/micro-services.pdf and b/diagrams/micro-services.pdf differ diff --git a/diagrams/micro-services.svg b/diagrams/micro-services.svg index d73adc3..ea37b80 100644 --- a/diagrams/micro-services.svg +++ b/diagrams/micro-services.svg @@ -1,381 +1,1549 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - - - - Client software + + + + + + Client software - - - - - - + + + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - - + + + + + + - - - - - - edit + + + + + + edit - - - - - - submit + + + + + + submit - - - - ExecutionPlanner + + + + ExecutionBroker - - - - - + + + + + - - - - Separate micro-services + + + + Separate micro-services - - - - implementation + + + + implementation - - - - - - - - + + + + + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - API + + + + API - - - - - + + + + + - - - - + + + + - - - - - - ExecutionWorker + + + + + + ExecutionWorker - - - - - + + + + + - - - - implementation + + + + implementation - - - - - - - - + + + + + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - API + + + + API - - - - - ExecutionWorker + + + + + ExecutionWorker - - - - - + + + + + - - - - API + + + + API - - - - implementation + + + + implementation - - - - - - - - + + + + + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - \ No newline at end of file + diff --git a/diagrams/request-offers.pdf b/diagrams/request-offers.pdf index 5e409ca..cb567cc 100644 Binary files a/diagrams/request-offers.pdf and b/diagrams/request-offers.pdf differ diff --git a/diagrams/request-offers.svg b/diagrams/request-offers.svg index 7cc9a80..cae4fba 100644 --- a/diagrams/request-offers.svg +++ b/diagrams/request-offers.svg @@ -1,327 +1,1344 @@ - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - - - - Client software + + + + + + Client software - - - - - - + + + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - - + + + + + + - - - - - - edit + + + + + + edit - - - - - - submit + + + + + + submit - - - - Execution Planner + + + + ExecutionBroker - - - - - + + + + + - - - - Execution Planner + + + + ExecutionBroker - - - - - + + + + + - - - - Execution Planner + + + + ExecutionBroker - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - - - + + + + + + + - - - - - - - - + + + + + + + + - - - - YES, offers[] + + + + YES, offers[] - - - - - - - + + + + + + + - - - - - - - + + + + + + + - - - - - - - + + + + + + + - - - - - - - + + + + + + + - - - - - - - + + + + + + + - - - - NO + + + + NO - - - - YES, offers[] + + + + YES, offers[] - - - - Request offers + + + + Request offers - - - - Can I do {this} ? + + + + Can I do {this} ? - \ No newline at end of file + diff --git a/diagrams/service-interactions.odg b/diagrams/service-interactions.odg index 7ab216f..3bd8351 100644 Binary files a/diagrams/service-interactions.odg and b/diagrams/service-interactions.odg differ diff --git a/diagrams/single-webapp.pdf b/diagrams/single-webapp.pdf index 1087f56..98d5735 100644 Binary files a/diagrams/single-webapp.pdf and b/diagrams/single-webapp.pdf differ diff --git a/diagrams/single-webapp.svg b/diagrams/single-webapp.svg index ec05285..1b34772 100644 --- a/diagrams/single-webapp.svg +++ b/diagrams/single-webapp.svg @@ -1,250 +1,1040 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - - - - Client software + + + + + + Client software - - - - - - + + + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - - + + + + + - - - - - - + + + + + + - - - - - - edit + + + + + + edit - - - - - - submit + + + + + + submit - - - - ExecutionPlanner + + + + ExecutionWorker - - - - - + + + + + - - - - ExecutionWorker + + + + - - - - - + + + + + - - - - Single web application + + + + Single web application - - - - API + + + + API - - - - implementation + + + + implementation - - - - - - - - + + + + + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - API + + + + API - - - - - + + + + + - - - - - + + + + + - - - - + + + + - + ExecutionWorker - \ No newline at end of file + diff --git a/role_diagram.pdf b/role_diagram.pdf index b24c01e..7092ae8 100644 Binary files a/role_diagram.pdf and b/role_diagram.pdf differ diff --git a/role_diagram.xml b/role_diagram.xml index 1e90475..4c731de 100644 --- a/role_diagram.xml +++ b/role_diagram.xml @@ -98,7 +98,7 @@ of the various sections) to have the box centered. - +