Комплекс RESTful-веб-сервисов для удаленного доступа к суперкомпьютерным ресурсам с учетом особенностей задач моделирования в области нанонаук обеспечивает возможность удаленного запуска задач на суперкомпьютерах с использованием локальных менеджеров ресурсов кластеров.
Назначение данного сервиса — обработка запросов пользователей на запуск задач на суперкомпьютере. Сервис реализован как RESTful-грид-сервис, использующий протоколы HTTPS и X.509 для аутентификации запросов и систему управления виртуальными организациями VOMS для авторизации запросов. В процессе работы сервер помещает информацию о задачах пользователей в СУБД, используемую другими сервисами комплекса для дальнейшей обработки. Эта же база данных используется в качестве источника информации о состоянии задач и т.п.
Ниже приводится проект REST-интерфейса данного сервиса с описанием используемых форматов данных.
Интерфейс прикладного программирования сервиса запуска задач реализован как RESTful-грид-сервис. Входные данные в запросах сервера, если это не оговорено отдельно, могут быть представлены в одном из следующих форматов: JSON, YAML. При этом используются одни и те же структуры данных, формат представления изменяет только способ сериализации данных. В данном документе все примеры и спецификации будут приводиться в формате JSON, поскольку он является ,более выразительным для восприятия человеком форматом, чем YAML: Любой объект JSON может быть представлен в виде функционально эквивалентного описания YAML, обратное в общем случае не верно.
Обязательным требованием к формату запроса серверу является обязательное и правильное указание заголовка Content-Type в запросе.
Ответы сервера, если это не оговаривается специально, могут быть представлены в одном из следующих форматов: JSON, YAML. Кроме того, ответы на многие запросы сервера, выполняемые методом GET и не содержащие тела запроса, могут быть возвращены в формате HTML. Выбор формата возвращаемого представления определяется в порядке приоритета, указанном в заголовке Accept, посылаемом клиентом, при отсутствии заголовка Accept используется формат JSON.
Соединения с сервером всегда устанавливаются по протоколу HTTPS (транспорт TLSv1), с использованием клиентских сертификатов X.509 либо прокси-сертификатов RFC3820. Прокси-сертификаты могут иметь дополнительные расширения (атрибутные сертификаты), используемые для авторизации запросов.
Все запросы, имеющие не пустое тело запроса, должны содержать заголовок Content-Length.
При обработке запроса сервер проверяет подлинность сертификата пользователя, использованного при установлении соединения. При этом обязательно используются списки отозванных сертификатов (CRL), если они доступны для сертификационного центра, выдавшего сертификат пользователя. Помимо проверок, требуемых в рамках протоколов TLSv1 и HTTPS, проводится проверка принадлежности имени в сертификате (DN) к пространству имен, допустимому для данного CA. Пространства имен всех CA хранятся в соответствующих файлах в формате Signing Policy, используемом IGTF.
Для авторизации запросов, требующих уточнения принадлежности пользователя к виртуальной организации, проводится проверка атрибутного сертификата VOMS, содержащегося в прокси-сертификате. Полная семантика атрибутов FQAN описывается в Artifact artf6312: The VOMS Attribute Certificate Format (http://forge.gridforum.org/sf/go/artf6312). Атрибуты FQAN могут содержать информацию о членстве в группах и о ролях в группах.
‒.Членство в группе:
/«vo name»/«subgroup»/.../«subgroup» |
‒.Роль в группе:
/«vo name»/«subgroup»/.../«subgroup»/Role=«role name»/Capability=«capability name» |
В случаях, если особенной роли или особенной возможности (Capability) у пользователя нет, соответствующие значения принимают вид /Role=NULL и /Capability=NULL. Кроме того, части атрибута, имеющие такие значения можно не указывать. То есть следующие значения атрибутов являются эквивалентными:
- /testbed - /testbed/Role=NULL - /testbed/Capability=NULL - /tesbted/Role=NULL/Capability=NULL` |
Порядок атрибутов FQAN является значимым. Обработка атрибутов FQAN должна проводиться именно в том порядке, в котором они присутствуют в сертификате.
В цепочке делегирования прокси-сертификата VOMS-расширения могут присутствовать в любом из прокси-сертификатов цепочки. Для авторизации необходимо использовать наиболее близкие к концу цепочки voms-расширения, то есть те расширения, которые находятся в самых последних делегациях.
Задачи каждого пользователя образуют коллекцию задач SERVER/jobs/ (здесь и далее строка SERVER используется для обозначения базового URI сервиса).
Запрос GET к коллекции возвращает список всех задач пользователя, имеющий вид:
[ { «uri»: «job_uri», «job_id»: «some_id» }, ... ] |
Здесь job_uri — полный URI задачи пользователя, используемый для действий с задачами, some_id — некоторый внутренний идентификатор задачи.
Создание задач возможно с использованием двух протоколов создания ресурсов, упрощенного и идемпотентного.
а) Упрощенный протокол.
Для создания новых задач используется запрос POST по адресу SERVER/jobs/, содержащий объект с описанием задачи.
б) Идемпотентный протокол.
Клиент генерирует строку-идентификатор задачи job_id, используя алгоритм UUID в модификации time-based UUID (описание алгоритма см. в разделе 4.2 RFC 4122). Далее с использованием протокола HTTP/1.1 выполняется условный запрос PUT по адресу SERVER/jobs/job_id, с заголовками Expect: 100-continue и If-None-Match: *. В случае получения от сервера кода ошибки 417 клиент должен сгенерировать новый идентификатор задачи и повторить попытку запроса. В случае получения ответа с кодом 100, клиент должен продолжить передачу данных на сервер.
В случае успешного создания ресурса клиент получает ответ сервера с кодом 201 а также URI созданной задачи в заголовке Location. Также ответ сервера содержит заголовок Termination-Time, указывающий время жизни созданного ресурса-задачи. По умолчанию новые задачи имеют очень небольшое время жизни (единицы минут), которое должно быть увеличено клиентами при последующих обращениях к серверу. Создание новой задачи не приводит к ее автоматическому запуску или постановке в очередь.
Для получения информации о состоянии задачи используется запрос GET к URI задачи, имеющему вид SERVER/jobs/«jobid»/, где «jobid» — идентификатор задачи.
Ответ на запрос является объектом, имеющим следующие атрибуты:
‒.created, modified, строка
‒.Дата/время создания задания и дата/время последнего изменения задания или его состояния.
‒.server_policy_url, строка
‒.URL документа, описывающего политику сервера, применяемую к данному заданию. Политика сервера описывает используемые сервером умолчания, и ограничения.
‒.owner, строка
‒.DN владельца задания
‒.vo, строка
‒.Виртуальная организация, от имени которой запущено задание. null если неизвестно.
‒.state, список объектов
‒.История изменений состояния задачи. Каждый объект имеет атрибуты:
‒.s, строка
‒.Состояние задачи. Возможные значения:
‒.new: только что созданная задача;
‒.pending: задача ожидает обработки;
‒.queued: задача поставлена в очередь;
‒.running:задача выполняется;
‒.paused: выполнение задачи приостановлено;
‒.finished: выполнение задачи завершено;
‒.aborted: выполнение задачи отменено.
‒.ts, строка
‒.Дата/время, когда наступило соответствующее состояние.
‒.Объект состояния может так же иметь другие атрибуты, не определенные в данном списке. Состояния в списке перечисляются в историческом порядке, начиная с самого старого состояния. Последние состояние в списке является текущим.
‒.operation, список объектов
‒.Текущие операции и история выполнения операций над задачей. Каждый объект имеет атрибуты:
‒.op, строка
‒.Операция. Возможные значения:
‒.start: запуск задачи на выполнение;
‒.pause: приостановка выполнения задачи;
‒.abort: отмена выполнения задачи.
‒.id, строка
‒.Уникальный идентификатор операции.
‒.created, строка
‒.Дата и время помещения данной операции в очередь.
‒.completed, строка
‒.Дата и время завершения данной операции.
‒.success, boolean
‒.Было ли завершение операции успешным.
‒.result, объект Расширенный результат завершения операции, произвольный объект.
‒.Объект операция может так же иметь другие атрибуты, не определенные в данном списке.
‒.Операции обрабатываются системой в хронологическом порядке. Порядок, в котором объекты присутствуют в списке, может быть произвольным.
‒.definition, объект
‒.Описание задачи.
‒.deleted, boolean
‒.Значение True означает, что данное задание помечено как удаленное. Удаленные задания доступны только для чтения.
Задача во время выполнения может использовать делегированный ей прокси-сертификат. Для работы с делегацией сертификата используется ресурс, имеющий адрес SERVER/jobs/job_id/delegation.
Делегация является JSON-объектом со следующими атрибутами (часть из них опциональны):
{ "vo": "«vo_name»", "fqans": [ "«fqan1»", ... ], "next_expiration": "«timestamp»" } |
vo строка, только для чтения
Виртуальная организация, к которой относится данная делегация.
fqans список строк, только для чтения
Список атрибутов FQAN из VOMS-расширений делегации.
next_expiration строка, дата/время, только для чтения
Срок окончания действия текущего экземпляра делегации.
По умолчанию задача не имеет делегации. Для создания или обновления существующей делегации задачи используется следующий протокол.
‒.Клиент должен получить ключ новой делегации, который необходимо подписать. Это можно сделать следующими способами:
‒.Получить публичный ключ, отправив запрос GET по адресу SERVER/jobs/job_id/delegation/pubkey. Ключ может быть возвращен в одном из следующих форматов:
‒.application/x-pkcs1, application/x-pkcs1+der: публичный ключ в формате PKCS#1 [RFC 3447, Appendix A.1.1];
‒.application/x-pkcs1+pem: публичный ключ в формате PKCS#1 в кодировании PEM (Base64+заголовки).
‒.По умолчанию используется формат application/x-pkcs1+pem.
‒.Получить запрос на сертификат, отправив запрос GET по адресу SERVER/jobs/job_id/delegation/request. В случае, если обновление делегации происходит впервые (то есть при создании новой делегации), subject запроса будет содержать некорректное значение. Запрос может быть возвращен в одном из следующих форматов:
‒.application/pkcs10, application/pkcs10+der: запрос в формате PKCS#10 [RFC 2986]
‒.application/pkcs10+pem: запрос в формате PKCS#10 в кодировании PEM (Base64+заголовки).
‒.По умолчанию используется формат application/pkcs10.
‒.Создать и подписать прокси-сертификат, использовав публичный ключ из предыдущего пункта.
‒.Отправить прокси-сертификат со всей цепочкой сертификатов на сервер, используя запрос PUT по адресу SERVER/jobs/job_id/delegation/renew. Элементы цепочки должны передоваться в порядке от конца (нового прокси-сертификата) к началу (сертификату пользователя). Цепочка может быть отправлена в одном из следующих форматов:
‒.application/x-pkix-chain+pem: последовательность сертификатов в «текстовом» представлении PEM, от конца цепочки к началу.
‒.application/x-pkix-chain, application/x-pkix-chain+der: ASN.1 Sequence, состоящий из сертификатов, от конца цепочки к началу (т.е. результат паковки стека сертификатов OpenSSL при помощи функции ASN1_seq_pack_X509 из OpenSSL).
По умолчанию используется формат application/x-pkix-chain+pem.
Если обработка задачи еще не была начата сервером (задача находится в состоянии new), возможно изменение описания задачи. Для этого используется запрос PUT по адресу SERVER/jobs/job_id/, содержащий новое описание задачи.
Для выполнения операций над задачей (например, запуск задачи), используются запросы методом PUT по URI задачи, который имеет вид SERVER/jobs/«jobid»/operation.
Запрос является объектом, имеющим следующие атрибуты:
‒.op, строка
‒.Выполняемая операция. Возможные значения:
‒.start: запустить задачу на выполнение;
‒.pause: приостановить выполнение задачи;
‒.abort: отменить выполнение задачи.
‒.id, строка
‒.Уникальный в рамках одного задания идентификатор операции. Генерация уникального id является ответственностью клиента, в качестве id рекомендуется использовать, например, uuid4.
Для удаления задач используются запросы методом DELETE по адресу задачи. Удаление задачи также приводит к отмене ее выполнения и удаления всех файлов задачи с сервера.
Удаление задач также производится сервером автоматически по истечении времени жизни задачи, которое сообщается во всех ответах сервера в заголовке Termination-Time.
Для контроля времени жизни ресурсов и управления им предлагается использовать заголовки протокола HTTP. Для обозначения времени жизни ресурса предлагается использовать нестандартный заголовок Termination-Time, спецификация которого в расширенной форме Бэкуса-Наура [rfc5234] приводится ниже:
Termination-Time = "Termination-Time" ": " rfc1123-date rfc1123-date = wkday ", " date " " time " GMT" wkday = "Mon" / "Tue" / "Wed" / "Thu" / "Fri" / "Sat" / "Sun" date = 2*DIGIT " " month " " 4*DIGIT month = "Jan" / "Feb" / "Mar" / "Apr" / "May" / "Jun" / "Jul" / "Aug" / "Sep" / "Oct" / "Nov" / "Dec" time = 2*DIGIT ":" 2*DIGIT ":" 2*DIGIT |
Поле date содержит дату в формате день месяц год; поле time содержит время, в диапазоне 00:00:00 --- 23:59:59.
Необходимость использования отдельного заголовка для указания времени жизни вызвана тем, что другие близкие по смыслу стандартные заголовки имеют интерпретацию, связанную с конкретным представлением ресурса, а не ресурсом в целом. Так, например, заголовок Expires имеет стандартную интерпретацию как актуальность/время жизни данного представления, и, поэтому, не может использоваться для указания времени жизни ресурса.
Заголовок Termination-Time является опциональным, и может присутствовать как в запросе, так и в ответе.
Наличие заголовка Termination-Time в запросе используется для изменения времени жизни ресурса. В случае возможности изменения времени жизни ресурса, грид-сервис должен выполнить действия, соответствующие запросу и изменить время жизни ресурса. В ответе на запрос должен присутствовать заголовок Termination-Time, содержащий новое время жизни ресурса. В случае если указанное изменение времени жизни невозможно или не поддерживается для данного ресурса, грид-сервис не должен выполнять действие, соответствующее запросу и должен вернуть ответ с кодом состояния 409 содержащий заголовок Location: urn:X-RESTful-Grid:invalid-termination-time.
Наличие заголовка Termination-Time в ответе грид-сервиса указывает, что данный ресурс может быть автоматически уничтожен сервисом в указанный момент времени, однако не гарантирует уничтожения ресурса. Отсутствие заголовка Termination-Time в ответе грид-сервиса означает, что время жизни ресурса не определено явно, и клиент не должен делать предположений о времени жизни ресурса.
Для изменения времени жизни ресурса без совершения каких-либо операций с ресурсом предлагается использовать расширенное указание Pragma: only-termination-time. Чтобы изменить время жизни ресурса не совершая операций, клиент отправляет серверу запрос методом PUT, в котором присутствует заголовок Pragma: only-termination-time и желаемое значение времени жизни ресурса в заголовке Termination-Time, но отсутствует представление ресурса. Запрос, содержащий представление ресурса и такой набор заголовков считается ошибочным, сервер должен вернуть ответ с кодом состояния 400 и заголовком Location: urn:X-RESTful-Grid:invalid-pragma-combination.Сервис запуска задач и отслеживания состояния задач (сервис интерфейса с локальным менеджером ресурсов).
Назначение данного сервиса — запуск и отслеживание состояния задач, на основе информации, содержащейся в СУБД системы запуска задач.
Данный сервис обеспечивает выполнение логики обработки задач, запускает задачи с использованием локального менеджера ресурсов и следит за ходом их выполнения. Сервис содержит следующие компоненты:
‒.обработчик задач. Занимается анализом заданий и задач, хранящихся в базе данных; направляет задачи в очередь исполнения;
‒.очередь исполнения задач. Задачи попадают в эту очередь по мере готовности к постановке в очередь локального менеджера ресурсов. Обработчик этой очереди запускает задачи с использованием локального менеджера ресурсов кластера или суперкомпьютера.;
‒.очередь опроса состояния. Обработчик этой очереди опрашивает локальный менеджер ресурсов о состоянии выполняющихся задач.
Назначение данного сервиса — подбор необходимых параметров запуска задачи на кластере, с учетом требований к ресурсам и предустановленному программному обеспечению задачи. Данный сервис используется сервисом запуска и отслеживания состояния задач для выбора очереди, в котору производится постановка задачи. Реализован как RESTful-веб-сервис.
Назначение данного сервиса — преобразование унифицированного описания задачи, используемой клиентами RESTful-веб-сервиса для удаленного доступа к суперкомпьютерным ресурсам с учетом особенностей задач моделирования в области нанонаук в язык описания, используемый локальным менеджером ресурсов данного кластера или суперкомпьютера.
Сервис используется сервисом запуска и отслеживания состояния задач. Реализован как RESTful-веб-сервис.
Учетная информация о выполненных задачах предоставляется в виде отдельного RESTful-грид-сервиса. Сервис использует процедуру доступа, авторизации и аутентификации аналогичную описанной в разделе .
Записи из журналов учетной информации могут быть возвращены в форматах JSON, YAML, CSV, HTML. Формат представления, выбранный клиентом, необходимо указать в заголовке Accept.
Запрос производится по URI вида SERVER/accounting/«ts1»-«ts2»/, где «ts1» и «ts2» могут иметь одно из следующих значений:
‒.current: текущее дата/время на сервере.
‒.Дата и время во временной зоне UTC, в формате YYYYmmddHHMMSS[.FFFFFF], где YYYY — год, mm — месяц, dd — день, HH — час, MM — минуты, SS — секунды, [.FFFFFF] — доли секунды. Например: 20091124124337 соответствует 24 ноября 2009 года, 15:43:34 по Московскому зимнему времени, 20051211182733.832922 соответствует 11 декабря 2005 года, 21:27:33 и 0.832922 секунды по Московскому зимнему времени.
‒.Невыполнение следующих требований приведет к ответу с кодом 400:
‒.«ts1» не может иметь значение current;
‒.«ts2» должен быть больше «ts1».
Примеры URI запросов.
Аккаунтинговая информация с 00:00:00 UTC 24 ноября 2009 года по текущий момент:
SERVER/accounting/period/20091124000000-current/ |
Аккаунтинговая информация с 00:00:00 UTC 24 ноября 2009 года по 12:43:37 и 0.291323 секунды UTC 24 ноября 2009 года:
SERVER/accounting/period/20091124000000-20091124124337.291323/ |
Запрос производится по URI вида SERVER/accounting/last/N/, где N — количество возвращаемых записей. Возвращаются последние N записей учетной информации.
Ответы сервиса в любоим представлении могут содержать одно или несколько полей из перечисленных ниже для каждой из возвращенных записей. Возможные поля:
‒.ts, строка
‒.Дата и время соответствующей записи аккаунтинга, в формате ISO 8601, во временной зоне UTC с долями секунды.
‒.user_dn, строка
‒.Subject сертификата пользователя, являющегося владельцем задания.
‒.job_id, строка
‒.Идентификатор задания
‒.vo, строка
‒.Виртуальная организация, к которой относится данная операция (если известна); null, если виртуальная организация не может быть определена.
‒.event, строка
‒.Учитываемое событие. Возможные значения:
‒.job_started: задача была запущена. В detail содержится информация об очереди и, возможно, имени хоста, на котором запущена задача. Для событий этого типа обязательно присутствуют поля job_id, user_dn, и detail.
‒.job_finished: задача завершилась успешно. Для событий этого типа обязательно присутствуют поля job_id, user_dn. Может присутствовать поле detail, содержащее код завершения задачи.
‒.job_aborted: задача заверешилась не успешно. Для событий этого типа обязательно присутствуют поля job_id, user_dn. Может присутствовать поле detail, содержащее код завершения задачи.
‒.detail, строка, опциональный параметр
‒.Дополнительная информация о событии. См. описание значений в описании параметра event. null, если дополнительной информации нет.
‒.info, объект
Дополнительная информация о событии, если известна; null, если дополнительной информации нет. Имеет различные значения для разных типов событий.
Сервисы – для своей работы используют общую базу данных, содержащую информацию о задачах, которые были обработаны сервисами, а также находятся в очереди на обработку или выполняются.
Все отношения кроме jobs находятся в третьей нормальной форме Кодда, небольшая денормализация вызвана соображениями производительности. Для обеспечения целостности данных с учетом денормализации используются хранимые процедуры, вызываемые триггерами обновления соответствующих таблиц.
Информация о задачах хранится в таблицах jobs. Таблица job_operations содержит информацию об операциях с задачами, которые выполнялись, или должны быть выполнены. Таблица job_states используется для хранения истории состояний задач. Состояния последовательно нумеруются в поле seq, текущему состоянию соответствует строка с максимальным значением seq. Кроме того, для текущего состояния задачи поле s таблицы job_state дублируется в поле current_state в таблице jobs. Это делается из соображений производительности: запросы с выборкой по текущему состоянию часто используются многими сервисами системы, такая денормализация позволяет существенно их ускорить, ликвидируя необходимость дополнительных запросов для выяснения текущего состояния. Хранимые процедуры триггеров обновления и добавления записей таблицы job_states предотвращают нарушение целостности данных, автоматически обновляя поле current_state связанной таблицы.
История состояний и операций, помимо уже описанных выше таблиц, хранится в альтернативном виде в таблице accounting_log, организованной как учетный журнал всех событий, которые происходят внутри сервиса запуска задач.
Сервис предосталяет информацию о текущем состоянии суперкомпьютера или кластера в виде JSON-ресурса. Для получения информации о состоянии кластера и его очередей необходимо послать запрос методом GET по адресу SERVER/status/
Ответ в формате JSON содержит общую информацию о кластере, информацию об очередях и их загрузке, информацию о доступном предустановленном программном обеспечении и правах доступа к нему.
Данный интерфейс предназначен для программ локального менеджера ресурсов суперкомпьютера и предоставляет возможность обновления информации о состоянии кластера или суперкомпьютера со стороны локального менеджера ресурсов.
Для обновления информации необходимо отправить запрос методом POST по адресу http://localhost:44000/, содержащий обновленные значения полей. Например:
$ curl -H 'Content-Type: application/json' --data-binary '{"workq": > {"TotalJobs": 3, "RunningJobs": 2, "WaitingJobs": 1} > }' http://localhost:44080 |
Аттрибутами передаваемого объекта являются названия очередей (“workq” в примере). Разрешается передовать любые свойства ComputingShare (стр. 26-29 спецификации GLUE 2.0), например, TotalJobs, RunningJobs, MaxCPUTime, и так далее.