174 lines
6.7 KiB
Markdown
174 lines
6.7 KiB
Markdown
# Настройка доступа к компонентам модуля через API (уточняется)
|
||
|
||
Чтобы внешние пользователи могли использовать компоненты приложения - запускать расчёты в ML-компонентах и пайплайнах, работать с файлами в DataBox - нужно добавить в приложение соответствующие API-компоненты.
|
||
|
||
Это могут быть:
|
||
|
||
- API для работы с файлами.
|
||
- API для работы с пайплайнами и их запусками.
|
||
- API для работы с одним конкретным ML-компонентом.
|
||
- API для работы с одним конкретным пайплайном.
|
||
|
||
## Общий шаблон API-компонента
|
||
|
||
```yaml
|
||
apiVersion: "unified-platform.cs.hse.ru/v1"
|
||
kind: APIComponent
|
||
metadata:
|
||
name: my-api
|
||
namespace: pu-username-pa-appname
|
||
spec:
|
||
published: true
|
||
# <тип API>
|
||
restfulApi:
|
||
auth:
|
||
basic:
|
||
credentials: appname-apis-cred
|
||
identityPassThrough: true
|
||
```
|
||
|
||
Здесь,
|
||
|
||
- <тип API> - см. ниже;
|
||
- `metadata.name` - имя API-компонента, должно быть уникальным среди API-компонентов в одном модуле;
|
||
- `metadata.namespace` - полное название приложения;
|
||
- `spec.published` - "включен" ли API - возможно добавить API-компонент, но временно его "выключить" - тогда запросы к нему не будут работать;
|
||
- `spec.restfulAPI` - раздел настроек доступа. Поддерживается базовая авторизация и Open ID Connect;
|
||
- `appname-apis-cred` - имя секрета, которое может быть любым.
|
||
|
||
## Типы API-компонентов
|
||
|
||
Выше в шаблоне комментарий "<тип API>" должен быть заменён одной из секций ниже в зависимости от типа API-компонента.
|
||
|
||
### Файловый API
|
||
|
||
```yaml
|
||
files:
|
||
enabled: true
|
||
```
|
||
|
||
### API для списка пайплайнов
|
||
|
||
```yaml
|
||
pipelines:
|
||
enabled: true
|
||
```
|
||
|
||
### API для ML-компонента
|
||
|
||
Помимо вида API, в раздел `restfulApi` нужно добавить путь, по которому будет осуществляться доступ к модулю.
|
||
|
||
```yaml
|
||
mlComponent:
|
||
name: my-mlcmp
|
||
restfulApi:
|
||
path: image
|
||
auth:
|
||
```
|
||
|
||
Здесь `mlComponent.name` - это имя компонента `MLComponent`, а `restfulApi.path` - путь, который нужно указывать в URL в запросах к ML-компоненту.
|
||
|
||
Например, манифесту выше соответствует ссылка для запуска расчётов `https://platform.stratpro.hse.ru/pu-username-pa-appname/image/predict`.
|
||
|
||
|
||
### API для конкретного пайплайна
|
||
|
||
```yaml
|
||
experimentPipeline:
|
||
name: my-pipeline
|
||
```
|
||
|
||
Если в API-компоненте указан раздел `experimentPipeline`, то в таком компоненте обязательно должен присутствовать раздел `spec.apiSpec` со спецификацией интерфейса конкретного пайплайна.
|
||
|
||
Подробнее - в разделе [о пайплайнах](./pipeline.md).
|
||
|
||
## Аутентификация и настройка доступа
|
||
|
||
В шаблоне выше приведён пример Basic авторизации. В таком случае используется набор реквизитов, который присутствует в модуле. В примере выше реквизиты хранятся в секрете `appname-apis-cred`.
|
||
|
||
Помимо базовой авторизации, можно использовать OIDC. Для этого в раздел `spec.restfulApi.auth` нужно добавить поле `oidc`.
|
||
|
||
Пример:
|
||
|
||
```yaml
|
||
apiVersion: "unified-platform.cs.hse.ru/v1"
|
||
kind: APIComponent
|
||
metadata:
|
||
name: my-api
|
||
namespace: pu-username-pa-appname
|
||
spec:
|
||
published: true
|
||
files:
|
||
enabled: true
|
||
restfulApi:
|
||
auth:
|
||
identityPassThrough: true
|
||
oidc: {}
|
||
```
|
||
|
||
В самом простом случае поле `oidc` можно оставить пустым словарём - `oidc: {}`. Также можно контролировать настройки OIDC:
|
||
|
||
- `groups` - список разрешённых групп
|
||
```yaml
|
||
oidc:
|
||
groups: ["/group1"]
|
||
```
|
||
- `roles` - список разрешённых ролей
|
||
```yaml
|
||
oidc:
|
||
roles: ["/test"]
|
||
```
|
||
- `enabled` - включена ли OIDC аутентификация (по умолчанию включена, указанием этого пункта можно выключить)
|
||
```yaml
|
||
oidc: {}
|
||
enabled: false # default - true
|
||
```
|
||
|
||
## ComponentLink
|
||
|
||
`ComponentLink` служит для предоставления доступа к API сервисов отдельным пользователям KeyCloak.
|
||
|
||
```yaml
|
||
apiVersion: "unified-platform.cs.hse.ru/v1"
|
||
kind: ComponentLink
|
||
metadata:
|
||
name: test-link
|
||
namespace: pu-username
|
||
spec:
|
||
platformAppName: pu-username-pa-test
|
||
targets:
|
||
- name: service-api
|
||
platformAppName: pu-username-pa-test
|
||
keycloakGroup:
|
||
userRegistryRef:
|
||
name: test-keycloak-user-registry
|
||
secretRef:
|
||
name: secret1
|
||
```
|
||
Здесь,
|
||
|
||
- `metadata.name` - имя ComponentLink, должно быть уникальным среди ComponentLink в одном модуле
|
||
- `metadata.namespace` - пространство имен пользователя
|
||
- `spec.platformAppName` - полное название приложения
|
||
- `spec.targets.name` - название API, к которому будет предоставлен доступ
|
||
- `spec.secretRef.name` - имя секрета, которое может быть любым.
|
||
|
||
|
||
В секрете перечислены имена пользователей, которым будет предоставлен доступ к API, указанному в ComponentLink. Будут созданы специальные группы в KeyCloak, в которые будут добавлены указанные пользователи. Пример секрете представлен ниже
|
||
|
||
```yaml
|
||
apiVersion: v1
|
||
kind: Secret
|
||
metadata:
|
||
namespace: pu-username
|
||
name: secret1
|
||
stringData:
|
||
emails: |-
|
||
emaildoesntexist@example.com
|
||
usernames: |-
|
||
user4
|
||
user5
|
||
robots: |-
|
||
robot1
|
||
robot2
|
||
```
|