|
|
@@ -0,0 +1,108 @@
|
|
|
+# identity-role-access-matrix
|
|
|
+
|
|
|
+Этот документ описывает новый формат хранения данных о well-known сущностях IAM'а.
|
|
|
+
|
|
|
+Пермишены и сервисные роли хранятся в отдельном каталоге для сервиса, который ими управляет.
|
|
|
+Например, пермишен `compute.instances.start` может быть задан в файле `compute/permissions.yaml`, а роль `resource-manager.clouds.member` — в файле `resource-manager/roles.yaml`.
|
|
|
+Внутри своего каталога команда сервиса может организовать данные как угодно, одним файлом или несколькими, положить их в одном каталоге или раскидать по поддиректориям.
|
|
|
+Обязательное требование — файлы внутри подкаталогов должны называться `permissions.yaml`, `roles.yaml`, `stages.yaml`, `resources.yaml` для описания набора прав, ролей, стейджей и типов ресурсов соответсвенно.
|
|
|
+В каждом файле можно сослаться на сущность из любого другого файла — точно так же, как если бы сущности были описаны рядом, явно ссылаться на файл не нужно.
|
|
|
+
|
|
|
+Если эта документация противоречит тому, что на самом деле творится в файлах — значит, в файлах неправильно :)
|
|
|
+
|
|
|
+## Тулинг
|
|
|
+
|
|
|
+Для проверки того, что yaml'ы написаны верно, можно воспользоваться `yc-iam-compile-role-fixtures` из Python-пакета [yc_iam_tools](https://bb.yandex-team.ru/projects/CLOUD/repos/identity/browse/iam_tools/yc_iam_tools/). А можно и не пользоваться, такая же проверка запускается в TeamCity на каждый PR.
|
|
|
+
|
|
|
+## Роли
|
|
|
+
|
|
|
+```yaml
|
|
|
+roles:
|
|
|
+ # В этом dict'е перечисляются роли: ключ — название роли, значение — dict со свойствами
|
|
|
+
|
|
|
+ example.editor: # название роли
|
|
|
+
|
|
|
+ # Описание роли на английском для документации.
|
|
|
+ summary: |>
|
|
|
+ Edit different things that are managed by ExampleService.
|
|
|
+ Users with this role are also allowed to whisper to horses.
|
|
|
+
|
|
|
+ # Видимость роли: может быть public или internal. Роли public видят пользователи, а internal роли — нет.
|
|
|
+ # Public роль не должна включать в себя internal-пермишены, сейчас это warning при компиляции,
|
|
|
+ # в будущем повысим до error.
|
|
|
+ visibility: public
|
|
|
+
|
|
|
+ # Минимальный тип ресурса, на который можно назначить роль.
|
|
|
+ resourceType: resource-manager.folder
|
|
|
+ # Эту роль можно назначить на фолдер или на клауд, но нельзя на SA или на биллинг-аккаунт.
|
|
|
+ # Такая роль может содержать пермишены, у которых resourceType фолдер или какой-нибудь вложенный в него ресурс,
|
|
|
+ # но не может содержать никакие другие пермишены.
|
|
|
+
|
|
|
+ # Другие роли, входящие в состав этой.
|
|
|
+ # Параметр можно не указывать, если не нужно инклюдить никакие другие роли.
|
|
|
+ includedRoles:
|
|
|
+ - example.viewer
|
|
|
+ - horse.whisperer
|
|
|
+ # Роль `example.editor` содержит все пермишены из `example.viewer` и `horse.whisperer`.
|
|
|
+ # `includedRoles` работает транзитивно: если в определении `example.viewer` тоже инклюдятся какие-то роли,
|
|
|
+ # то их пермишены входят и в `example.editor`.
|
|
|
+
|
|
|
+ # Пермишены, входящие в роль.
|
|
|
+ # Параметр можно не указывать, если роль не включает никаких пермишенов напрямую.
|
|
|
+ permissions:
|
|
|
+ - example.things.edit
|
|
|
+ - example.things.manage
|
|
|
+ # Есть сокращённая форма записи:
|
|
|
+ - example.thingCollections.{create,update,delete}
|
|
|
+ # Фигурные скобки можно использовать в любом месте записи:
|
|
|
+ # `sample.{horses,mice,chickens}.{feed,pet}` тоже можно сказать,
|
|
|
+ # эта запись разресолвится в 6 пермишенов.
|
|
|
+ # (Но лучше таким не злоупотреблять.)
|
|
|
+
|
|
|
+ # В итоге получается, что в роль `example.editor` входят пермишены:
|
|
|
+ # `example.things.edit`, `example.things.manage`,
|
|
|
+ # `example.thingCollections.create`, `example.thingCollections.update`, `example.thingCollections.delete`,
|
|
|
+ # а также все пермишены, которые входят в роли `example.viewer` и `horse.whisperer`.
|
|
|
+
|
|
|
+ # Ещё одна роль.
|
|
|
+ example.viewer:
|
|
|
+ # Эта роль используется в роли `example.editor` выше.
|
|
|
+ # Но это не значит, что `example.viewer` в файле должна идти после `example.editor` —
|
|
|
+ # можно расположить их хоть как или вообще положить в разные файлы.
|
|
|
+ ...
|
|
|
+```
|
|
|
+
|
|
|
+Роли задаются аддитивно: можно создать роль "`viewer` плюс `compute.editor` плюс `iam.serviceAccounts.create`", но нельзя задать "`viewer` минус `billing.viewer`" или "все пермишены `serverless.*.*`, кроме `serverless.*.delete`". Это сделано специально, чтобы при добавлении новой роли/пермишена вся система вела себя более предсказуемо.
|
|
|
+
|
|
|
+Некоторые роли помечены как "псевдороли", у них есть поле `pseudorole: true`. Это временные сущности, они нужны только для того, чтобы из них составить общеоблачные роли типа `viewer`. Ни внешние, ни внутренние пользователи не могут видеть псевдороли в API и назначать на ресурсы. Сервисам рекомендуется заменить их на правильные сервисные роли.
|
|
|
+
|
|
|
+## Пермишены
|
|
|
+
|
|
|
+```yaml
|
|
|
+permissions:
|
|
|
+
|
|
|
+ iam.accessBinding.delete: # имя пермишена
|
|
|
+
|
|
|
+ # Описание роли на английском для документации.
|
|
|
+ description: Delete access binding.
|
|
|
+
|
|
|
+ # Стейдж. Чаще всего это GA.
|
|
|
+ # Список стейджей лежит в `stages.yaml`.
|
|
|
+ stage: GA
|
|
|
+
|
|
|
+ # Видимость пермишена: может быть public или internal.
|
|
|
+ # Связана с видимостью ролей: internal пермишены не должны входить в public роли.
|
|
|
+ visibility: public
|
|
|
+
|
|
|
+ # Здесь задаются условия, когда пермишен может действовать.
|
|
|
+ allowedWhen:
|
|
|
+
|
|
|
+ # Сейчас можно задать только условие на статус клауда.
|
|
|
+ cloud:
|
|
|
+ status:
|
|
|
+ - BLOCKED_BY_BILLING
|
|
|
+ - ACTIVE
|
|
|
+ # Этим пермишеном можно воспользоваться только тогда, когда клауд
|
|
|
+ # находится в статусе ACTIVE или BLOCKED_BY_BILLING.
|
|
|
+ # А если клауд в другом статусе — например, BLOCKED — пермишен запрещён.
|
|
|
+```
|
hrustyashko