doc/orchestra.tex

   1 \documentclass[a4paper]{article}
   2 \usepackage[T1]{fontenc}
   3 \usepackage{textcomp}
   4 \usepackage{mathptmx}
   5 \begin{document}
   6 \title{Orchestra}
   7 \author{Christopher Collins}
   8 \maketitle
   9
  10 \section{Introduction}
  11
  12 Orchestra is a suite for managing the reliable execution of tasks over
  13 a number of hosts.  It is intended to be simple and secure, leaving
  14 more complicated coordination and tasks to tools better suited for
  15 those jobs.
  16
  17 To accomodate the needs of web interfaces and other transactional
  18 interface methods, the main mode of operation for clients using
  19 Orchestra is asynchronous with respect to the execution of the jobs.
  20
  21 \section{Operating Principles}
  22
  23 The fundamental ideas behing Orchestra is that a client (the
  24 ``Audience'') requests that a job (the ``Score'') is excuted by one or
  25 more agents (the ``Players'').  This process is managed by the
  26 ``Conductor'' which mediates between the Audience and the Players.
  27
  28 A request consists of the name of the Score to execute, and a scope of
  29 execution which defines if the score is to be executed on a single
  30 player or multiple players, and which players are allowed to service
  31 the request.
  32
  33 Once a request has been received by a conductor, it is broken down
  34 into one or more tasks which represent a single execution of the
  35 requests score on a single machine.  These tasks are communicated to
  36 the players, which perform the task, and report back outcomes, which
  37 are then collated by the conductor back into a response.
  38
  39 \section{Scores}
  40
  41 Scores are an executable object, be it a script or binary executable,
  42 which is optionally accompanied by a configuration file.
  43
  44 In order for a Score to be considered for execution by a Player, it
  45 must have the executable bit set, and must be in the Score Directory
  46 ({\tt /usr/lib/orchestra/scores} by default).  The filename of the
  47 Score itself is used to identify it in Job requests.
  48
  49 The optional configuration file contains directives which may tell the
  50 Player how to behave when executing the score.
  51
  52 Currently, the score configuration file allows you to set which
  53 communication interface to use when exchanging information with the
  54 Score, the initial working directory and the initial path for the
  55 score.
  56
  57 Intended future features includes the ability to have the Player
  58 change the effective User ID prior to execution of the score.
  59
  60 Because we allow bidirectional communication between Scores and
  61 Players, we need to establish a mechanism to do this.  The interface
  62 option controls this, and currently can be set to either ``{\tt env}''
  63 or ``{\tt pipe}''.
  64
  65 The Player only loads score information at start up, or when prompted
  66 to by a {\tt SIGHUP}.  Adding or removing files from this directory
  67 will not change what the Player considers valid, or the parameters for
  68 executing a score, until a {\tt SIGHUP} has been issued.
  69
  70 \subsection{env Interface}
  71
  72 The ``{\tt env}'' interface is a one-way communication interface which
  73 allows the Player to communicate paramaters to the Score, but not
  74 vice-versa.
  75
  76 It does this by preprending ``{\tt ORC\_}'' to the key name, and
  77 setting it in the environment appropriately.
  78
  79 The ``{\tt env}'' interface connects the Score's {\tt STDIN} and {\tt
  80   STDOUT} to {\tt /dev/null}.
  81
  82 If the process exits with a exit status of 0, it is treated as a
  83 success.  All other outcomes are treated as failures.
  84
  85 \subsection{pipe Interface}
  86
  87 The ``{\tt pipe}'' interface is a two-way communication interface that
  88 operates in a very similar manner to the {\tt env} interface.
  89
  90 Rather than connecting {\tt STDOUT} to {\tt /dev/null}, it's connected
  91 to a pipe which it listens on for lines of the format ``{\tt
  92   <key>=<value>}''.  When it receives such a line, it is set into the
  93 Response set, replacing any existing values for {\tt <key>}.
  94
  95 Just as with {\tt env}, if the process exits with a exit status of 0,
  96 it is treated as a success.  All other outcomes are treated as
  97 failures.
  98
  99 \section{Audience Requests}
 100
 101 At present, there are only two operations available to the audience:
 102
 103 \begin{itemize}
 104 \item Submit Job
 105 \item Query Status of Job
 106 \end{itemize}
 107
 108 \subsection{Submit Job}
 109
 110 The Submit Job operation allows an audience member to submit a request
 111 for a score to be executed.
 112
 113 The request contains the Score's name, a scope (``One of'' or ``All
 114 of''), the valid players list, and a series of key/value parameters to
 115 be passed to the score.
 116
 117 The Conductor responds to this by either rejecting the request with an
 118 error, or by returning the ID for this request.
 119
 120 Once accepted, the job is then completed as per the considerations
 121 listed under ``Job Execution''.
 122
 123 \subsection{Query Status of Job}
 124
 125 The Query Status of Job operation allows an audience member to get the
 126 status of a previous job sumission.
 127
 128 The request contains the ID for the job to check.
 129
 130 The Conductor responds to this by either rejecting the request with an
 131 error, or by returning an aggregate status for the Job, and detailed
 132 individual response data.
 133
 134 The Aggregate status is either a Success, Partial Success or Failure
 135 status.
 136
 137 With a ``One Of'' job, the aggregate status is simply the outcome from
 138 the execution attempt.
 139
 140 With an ``All Of'' job, the aggregate status only indicates success or
 141 failure if the result is unanimous.  Partial Success is returned for
 142 any mixed outcome jobs.
 143
 144 \section{Job Execution}
 145
 146 When a Job is accepted, it is refactored as a series of single machine
 147 tasks which are then appened to a FIFO queue.
 148
 149 Players, when idle, send requests for tasks to the Conductor, which
 150 then drains the first task from the queue which the Player can
 151 service, and sends the data to that Player, committing the Task to
 152 that specific player if it has ``One of'' scope.
 153
 154 The Player then attempts to execute a score according to the details
 155 in the task.  This returns a result upon completion or error, and if
 156 successful, may also contain a key/value pair set response.  This is
 157 then reported back to the Conductor.
 158
 159 Score results are either Hard outcomes (such as Success, Failure,
 160 Internal Error, Host Error During Execution) or Soft outcomes (Error
 161 starting score, Score unknown).  When a soft failure outcome is
 162 reported back to the Conductor for a ``One Of'' job, the conductor
 163 records the result, removes the player from the valid destinations
 164 list, and reschedules the task for execution at the head of the queue.
 165
 166 In the interest of security, all network communication performed
 167 between the Conductor and Player is encrypted using TLS.
 168
 169 \section{The Conductor}
 170
 171 The Conductor is the single most imporant process in an Orchestra
 172 deployment.  It manages the work queue, and services requests from the
 173 Audience.
 174
 175 Access to the Conductor by Players is controlled by a combination of
 176 the player list, a simple text file which lists the full hostname of
 177 all authorised players, and verification of the Player's TLS
 178 certificate.
 179
 180 \subsection{Audience Interface}
 181
 182 The Conductor listens for audience requests on a Unix Domain Socket.
 183 The path can be configured via the {\tt conductor.conf} configuration
 184 file, but defaults to {\tt /var/run/audience.sock}.
 185
 186 The audience socket accepts a connection from any local user, and
 187 expects the client to send a single JSON encoded object.  It will then
 188 either send back a JSON encoded response or close the socket
 189 immediately if it couldn't understand the request.
 190
 191 It is expected that the service time for such requests is fast enough
 192 that it will not interfere with web applications polling for job
 193 execution status.
 194
 195 Further documentation about this interface can be found in {\tt
 196   doc/audience\_api.txt}.
 197
 198 \subsection{Status Interface}
 199
 200 The Condcutor implements a very basic human readable status interface
 201 accessible via HTTP on port 2259.  This interface tells you how many
 202 tasks are currently pending dispatch, and which hosts are currently
 203 idle, pending Tasks.
 204
 205 \subsection{Player Interface}
 206
 207 The Player interface is a TCP TLS listener on port 2258 which
 208 implements the Orchestra Player/Conductor protocol.
 209
 210 The Protocol is a binary protocol that uses a well defined 3 byte
 211 header combined with message bodies encoded using the Google Protocol
 212 Buffers toolkit.
 213
 214 The protocol was constructed this way in order to make it easy to
 215 implement a new Player in another language.  This was to allow for the
 216 implementation of Orchestra Players on systems that do not have a Go
 217 compiler.
 218
 219 \section{Security Considerations}
 220
 221 To ensure security, the Players and Conductor mutually authenticate
 222 each other using X.509 certificates - the players verify that the
 223 conductor's name matches it's certificate, and that it has a trust
 224 chain to a trusted Certificate Authority, and the conductor verifies
 225 that each connecting player's certificate matches who it claims to be
 226 and that the certificate has a trust chain back to it's trusted
 227 Certificate Authorities.  This allows both parties to be assured that
 228 they're communicating with the correct entity.
 229
 230 As the whole concept of Orchestra is to allow the remote execution of
 231 work, it was an intentional design decision to restrict execution to
 232 existing scripts or executables on the system which have been
 233 explicitly configured to be invocable.  The distribution or
 234 installation of these materials is left for either manual deployment,
 235 or for other automated management systems to handle (such as Chef, or
 236 Puppet).
 237
 238 \end{document}
 239