Тегирование (Tagging)#

Тегирование позволяет объединять компоненты с помощью тегов для их логической связи. Наиболее распространенные сценарии использования тегов включают следующее:

  • Идентификатор сборки CI, например, project-abc-build-142;

  • Конвейер непрерывных поставок - координация нескольких проектов как единого целого, например, release-train-13.

Примечание

Теги применяются на уровне компонентов, а не отдельных ресурсов.

Операции тегирования#

Функционал тегирования доступен через REST API. Для выполнения команд curl всем пользователям, кроме администратора, необходимы соответствующие Права.

Создание тега#

POST /service/rest/v1/tags

Пример запроса на создание тега:

curl -u admin:admin123 -X POST --header 'Content-Type: application/json' http://127.0.0.1:8081/service/rest/v1/tags \
  -d '{
    "name": "project-abc-142",
    "attributes": {
        "jvm": "9",
        "built-by": "jenkins"
        }
    }

Ограничения#

  • Поле name: не может превышать 256 символов, разрешены буквы, цифры, подчеркивания, дефисы и точки. Название не должно начинаться с подчеркивания или точки.

  • Поле attributes может содержать любые допустимые JSON-данные для дополнительной информации. Максимальный размер — 20 КБ.

Ответ сервера содержит два поля с временными метками:

  • Дата создания тега;

  • Дата последнего обновления.

Эти два поля устанавливаются автоматически и игнорируются при отправке в запросах POST или PUT.

Пример ответа#

{
  "name": "project-abc-142",
  "attributes": {
    "jvm": "9",
    "built-by": "jenkins"
  },
  "firstCreated": "2017-06-12T22:42:55.019+0000",
  "lastUpdated": "2017-06-12T22:42:55.019+0000"
}

Список тегов#

Представленный ниже запрос позволяет просмотреть список всех тегов.

GET /service/rest/v1/tags

Запрос не имеет параметров:

curl -u admin:admin123 -X GET http://127.0.0.1:8081/service/rest/v1/tags

Пример ответа#

{
    "items": [
        {
            "name": "project-abc-142",
            "attributes": {
                "jvm": "9",
                "built-by": "jenkins"
            },
            "firstCreated": "2017-06-12T22:42:55.019+0000",
            "lastUpdated": "2017-06-12T22:42:55.019+0000"
         },
         {
            "name": "project-abc-456",
            "attributes": {
                "jvm": "9",
                "built-by": "jenkins"
            },
            "firstCreated": "2017-06-13T22:24:55.019+0000",
            "lastUpdated": "2017-06-13T22:24:55.019+0000"
         }
    ],
    "continuationToken": null
}

Данный запрос использует стратегию постраничной навигации(пагинации), что позволяет поэтапно просматривать все теги при необходимости.

Обратите внимание

Порядок отображения тегов не является алфавитным, но будет одинаковым для всех запросов

Информация о теге#

GET /service/rest/v1/tags/{tagName}

Запрос позволяет получить подробную информацию об конкретном теге.

curl -u admin:admin123 -X GET http://127.0.0.1:8081/service/rest/v1/tags/project-abc-142

Пример ответа#

{
  "name": "project-abc-142",
  "attributes": {
    "jvm": "9",
    "built-by": "jenkins"
  },
  "firstCreated": "2017-06-12T22:42:55.019+0000",
  "lastUpdated": "2017-06-12T22:42:55.019+0000"
}

Обновление атрибутов тега#

PUT /service/rest/v1/tags/{tagName}

Запрос позволяет обновить атрибуты тега. Стоит заметить, имя тега и временные метки изменить нельзя.

curl -u admin:admin123 -X PUT --header 'Content-Type: application/json' http://127.0.0.1:8081/service/rest/v1/tags/project-abc-142 -d '{
    "attributes": {
        "jvm": "9",
        "built-by": "bob"
    }
}'

Пример ответа#

{
  "name": "project-abc-142",
  "attributes": {
    "jvm": "9",
    "built-by": "bob"
  },
  "firstCreated": "2017-06-12T22:42:55.019+0000",
  "lastUpdated": "2017-06-13T21:42:55.019+0000"
}

Привязка компонентов к тегу#

POST /service/rest/v1/tags/associate/{tagName}

Запрос позволяет искать компоненты и привязывать их к существующему тегу. Стоит заметить, если тег отсутствует, он не будет создан автоматически.

curl -u admin:admin123 -X POST 'http://127.0.0.1:8081/service/rest/v1/tags/associate/project-abc-142?repository=my-company&group=com.mycompany&name=project-abc&version=2.1.1'

В этом примере показан запрос по указанным параметрам: репозиторий, группа, имя и версия.

Пример ответа#

{
    "status": 200,
    "message": "Association successful",
    "data": {
        "components associated": [
            {
                "name": "project-abc",
                "group": "com.mycompany",
                "version": "2.2.0"
            }
        ]
    }
}

Ответ содержит список всех компонентов, которые были успешно привязаны к тегу. Ответ можно использовать для подтверждения успешной привязки.

Тегирование при загрузке компонентов#

Существует возможность добавлять тег сразу при загрузке компонента через REST API. Необходимо указать тег в запросе, добавив параметр -Ftag=project-abc-142. Возможность тегирования компонентов при загрузке доступна через пользовательский интерфейс.

curl -v -u admin:admin123 -X POST 'http://localhost:8081/service/rest/v1/components?repository=my-company' \
-F groupId=com.mycompany \
-F artifactId=project-abc \
-F version=2.1.1 \
-F asset1=@project-abc-2.1.1.jar \
-F asset1.extension=jar \
-F tag=project-abc-142

Отвязка компонентов от тега#

DELETE /service/rest/v1/tags/associate/{tagName}

Запрос позволяет искать компоненты и отвязывать их от указанного тега. Обратите внимание, что данный запрос аналогичен привязке, но вместо метода POST используется DELETE.

curl -u admin:admin123 -X DELETE 'http://127.0.0.1:8081/service/rest/v1/tags/associate/project-abc-142?repository=my-company&group=com.mycompany&name=project-abc&version=2.1.1'

Пример ответа#

{
    "status": 200,
    "message": "Disassociation successful",
    "data": {
        "components disassociated": [
            {
                "name": "project-abc",
                "group": "com.mycompany",
                "version": "2.1.1"
            }
        ]
    }
}

Безопасность#

Доступ к функции тегирования управляется следующими правами.

Права

Описание

nx-tags-all

Позволяет выполнять все операции с тегами

nx-tags-associate

Позволяет просматривать теги и привязывать их к компонентам в репозиториях, где у пользователя есть право на просмотр

nx-tags-create

Позволяет создавать и просматривать теги

nx-tags-delete

Позволяет удалять и просматривать теги

nx-tags-disassociate

Позволяет просматривать и отвязывать теги от компонентов в репозиториях, где у пользователя есть право на просмотр

nx-tags-read

Позволяет просматривать теги

nx-tags-update

Позволяет обновлять теги

Внимание

Для операций привязки и отвязки пользователь также должен иметь права nx-repository-view просмотра компонентов в репозитории.

Задача очистки#

Автоматическое тегирование всех сборок через CI может привести к накоплению ненужных тегов. Задача Admin - Cleanup Tags позволяет администраторам удалять теги по следующим критериям:

  • Возраст тега (в днях) с момента создания (по умолчанию 0 дней);

  • Возраст тега с момента последнего изменения (по умолчанию 0 дней);

  • Регулярное выражение для имени тега (например, project-abc-.*).

Если выбрано несколько критериев, тег должен соответствовать всем условиям для удаления. Также доступно удаление связанных компонентов, уменьшая выборку по конкретному репозиторию или формату.

Обратите внимание

Если компонент связан с двумя тегами, а задача очистки настроена на удаление компонентов, система удалит его даже при совпадении только с одним тегом. Например, если компонент имеет теги build-123 и dev-build-123, а задача настроена на очистку dev-build-123, компонент будет удален. Наличие у компонента тега build-123 не предотвратит удаление.

Журнал задачи Admin - Cleanup tags включает список удаленных тегов и компонентов.

Рекомендации по использованию тегов#

  • Используйте короткие имена тегов и атрибутов, для повышения производительности операций и эффективного использования хранилища.

  • Регулярно используйте задачу Admin - Cleanup tags для удаления устаревших или неиспользуемых тегов.

  • Используйте уникальные схемы именования тегов, это поможет избежать конфликтов имен и сбоев в работе процессов CI-конвейера.