documentation/pages/api-component.md

# Настройка доступа к компонентам модуля через 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
```

Здесь,

- `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: {}
        groups: ["/group1"]
        # enabled: false # default - true
        # roles: ["/test"]
```

## 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, в которые будут добавлены указанные пользователи.

```
apiVersion: v1
kind: Secret
metadata:
  namespace: pu-username
  name: secret1
stringData:
  emails: |-    
    emaildoesntexist@example.com  
  usernames: |-
    user4
    user5
  robots: |-
    robot1
    robot2
```




В самом простом случае поле `oidc` можно оставить пустым словарём - `oidc: {}`. Также можно контролировать настройки OIDC:

- `groups` - список разрешённых групп
- `roles` - список разрешённых ролей
- `enabled` - включена ли OIDC аутентификация (по умолчанию включена, указанием этого пункта можно выключить)