updates

pages/api-component.md

@@ -5,7 +5,7 @@
 Это могут быть:
 
 - API для работы с файлами.
-- API для работы с пайплайнами и их запусками в общем.
+- API для работы с пайплайнами и их запусками.
 - API для работы с одним конкретным ML-компонентом.
 - API для работы с одним конкретным пайплайном.
 
@@ -19,33 +19,34 @@ metadata:
   namespace: pu-username-pa-appname
 spec:
   published: true
-  # <вид API>
+  # <тип API>
   restfulApi:
     auth:
       basic:
-        credentials: appname-apis-cred
+        credentials: appname-apis-cred 
       identityPassThrough: true
 ```
 
 Здесь,
 
 - `metadata.name` - имя API-компонента, должно быть уникальным среди API-компонентов в одном модуле
-- `metadata.namespace` - полное название приложение
+- `metadata.namespace` - полное название приложения
 - `spec.published` - "включен" ли API - возможно добавить API-компонент, но временно его "выключить" - тогда запросы к нему не будут работать.
 - `spec.restfulAPI` - раздел настроек доступа. Поддерживается базовая авторизация и Open ID Connect.
+- `appname-apis-cred` - имя секрета, которое может быть любым.
 
-## Вид API-компонента
+## Типы API-компонентов
 
 Выше в шаблоне комментарий "<вид API>" должен быть заменён одной из секций ниже в зависимости от типа API-компонента.
 
-### Файловый APi
+### Файловый API
 
 ```yaml
   files:
     enabled: true
 ```
 
-### API для пайплайнов в целом
+### API для списка пайплайнов
 
 ```yaml
   pipelines:
@@ -80,11 +81,11 @@ spec:
 
 Подробнее - в разделе [о пайплайнах](./pipeline.md).
 
-## Авторизация/аутентификация
+## Аутентификация и настройка доступа
 
-В шаблоне выше приведён пример Basic авторизации. В таком случае используется набор реквизитов, который присутствует в модуле. В данном случае, реквизиты хранятся в компоненте `appname-apis-cred`.
+В шаблоне выше приведён пример Basic авторизации. В таком случае используется набор реквизитов, который присутствует в модуле. В примере выше реквизиты хранятся в секрете `appname-apis-cred`.
 
-Помимо базовой авторизации можно использовать OIDC. Для этого в раздел `spec.restfulApi.auth` нужно добавить поле `oidc`.
+Помимо базовой авторизации, можно использовать OIDC. Для этого в раздел `spec.restfulApi.auth` нужно добавить поле `oidc`.
 
 Пример:
 
@@ -102,11 +103,63 @@ spec:
     auth:
       identityPassThrough: true
       oidc: {}
-        # groups: ["/dev-multi-auth"]
+        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` - список разрешённых групп