Project: Armada (Orchestration & Management / Scheduling & Orchestration)
File: api.md

Armada exposes an API via gRPC or REST. The API is defined in `/pkg/api` folder with `*.proto` files as source for all generated code. Folder `/pkg/api` also contains generated clients and together with helper methods from `/pkg/client` provides a convenient way to call Armada API from go code. See armadactl code for . Following subset of API defined in `/pkg/api` is intended for public use. /api.Submit/SubmitJobs - submitting jobs to be run /api.Submit/CancelJobs - cancel jobs /api.Submit/CreateQueue - create a new queue /api.Submit/UpdateQueue - update an existing queue /api.Submit/DeleteQueue - remove queue /api.Submit/GetQueue - get information about queue (name, permissions) /api.Submit/GetQueueInfo - get information about queued (active jobs, including those currently running) /api.Event/GetJobSetEvents - read events of jobs running under particular JobSet There are additional API methods defined in proto specifications, which are used by Armada executor and not intended to be used by external users. This API can change in any version. - methods for event reporting - methods related to job leasing by executor The REST API only exposes the public part of the gRPC API and it is implemented using . Swagger json specification can be found and is also served by Armada under `my.armada.deployment/api/swagger.json` Both gRPC and REST API support the same set of authentication methods. In the case of gRPC all authentication methods uses `authorization` key in grpc metadata. The REST API use standard http Authorization header (which is translated by grpc-gateway to `authorization` metadata). See helm chart for different server authentication schemes setup. For testing, Armada can be configured to accept no authentication. All operations will use user `anonymous` in this case. When server is configured with OpenID, it will accept authorization header or metadata in the form `Bearer {oauth_token}`. For basic authentication API accepts standard authorization header or metadata in the form `basic {base64(user:password)}`. For Kerberos authentication API accepts the same authorization metadata for gRPC as standard Kerberos http SPNEGO authorization headers, the API responds with `WWW-Authenticate` header or metadata. Armada will determine which actions you are able to perform based on your user's permissions. These are defined as global or on a per queue basis. Below is the list of global Armada permissions (defined ): `submitanyjobs` `create_queue` `delete_queue` `cancelanyjobs` `reprioritizeanyjobs` `watchallevents` In addition, the following queue-specific permission verbs control what actions can be taken per individual queues (defined ): `submit` `cancel` `reprioritize` `watch` The table below shows which permissions are required for a user to access each API endpoint (either directly or via a group). Note queue-specific permission require a user to be bound to a global permission as well (shown as tuples in the table below). | Endpoint | Global Permissions | Queue Permissions | |--|-|-| | `SubmitJobs` | `submitanyjobs` | `submit` | | `CancelJobs` | `cancelanyjobs` | `cancel` | | `ReprioritizeJobs` | `reprioritizeanyjobs` | `reprioritize` | | `CreateQueue` | `create_queue` | | | `UpdateQueue` | `create_queue` | | | `DeleteQueue` | `delete_queue` | | | `GetQueue` | | | | `GetQueueInfo` | `watchallevents` | `watch` | | `GetJobSetEvents` | `watchallevents` | `watch` |