Skip to main content

Check out Port for yourself 

Examples

In this section we'll show you a few examples of ways to use catalog permissions in your organization, and how to apply them.

Use cases 💡​

The following configurations, among others, are available when using catalog permissions management:

  1. Entities can be made immutable/partially immutable (can only read/create/delete/modify) for specific users/roles. For example:
    1. Deployment entities are immutable for all roles, and Cluster entities are editable only by the blueprint Moderators.
    2. Members can create a new Microservice entity, but are not permitted to delete a Microservice entity.
  2. Each entity property/relation can be readable or immutable separately for specific users/roles. For example, the repository_link property can be immutable for all roles (except Admin).
  3. Allow specific users/roles to read or modify only entities owned by their team. For example, Members can edit only Microservices that belong to their team.
  4. Action execution permissions can be given to specific users or roles. For example, you can allow every Member to create a new Deployment entity, however only Deployment Moderators can perform a day-2 action of "adding resources".

Setting blueprint permissions​

To set permissions for a blueprint, click on the permissions button of the desired blueprint in the DevPortal Builder page. This will open a modal that contains the permissions JSON and allows you to control every operation that can be performed on the blueprint or its entities.

Role examples​

If you want to enable Members to register entities of a blueprint, you can change the JSON as follows:

{
  "entities": {
    "register": {
      "roles": ["Admin", "Env-moderator", "Member"], // changed from ["Admin", "Env-moderator"]
      "users": [],
      "teams": [],
      "ownedByTeam": false
    }
  }
}

User examples​

To grant permissions for a specific user to edit the deployedAt relation, add them to the users array:

{
  "entities": {
    "updateRelations": {
      "deployedAt": {
        "roles": ["Admin", "Env-moderator"],
        "users": ["some-user@myorg.com"], // changed from []
        "teams": [],
        "ownedByTeam": false
      }
    }
  }
}

Team examples​

To grant permissions for a specific team to edit the deployedAt relation, add them to the teams array:

{
  "entities": {
    "updateRelations": {
      "deployedAt": {
        "roles": ["Admin", "Env-moderator"],
        "users": [],
        "teams": ["ServiceMaintainers"], // changed from []
        "ownedByTeam": false
      }
    }
  }
}

Team ownership examples​

Some operations have the ownedByTeam flag. This allows you to set permissions by team ownership, rather than by roles or direct assignment to users.

For example, the following JSON will allow every user, regardless of their role, to perform the action delete_env on Env entities that belong to a team they are a part of (entities that have the team property set):

{
  "actions": {
    "delete_env": {
      "execute": {
        "roles": ["Admin", "Env-moderator"],
        "users": [],
        "teams": [],
        "ownedByTeam": true // changed from false
      }
    }
  }
}

Team inheritance​

Team inheritance allows you to utilize relations to automatically assign and manage entity ownership.

By using team inheritance, you can configure entities to automatically inherit their team from entities they are related to.

Team inheritance can be configured by adding the teamInheritance key to the blueprint structure. The teamInheritance object has a path key that represents the relation path to the blueprint whose entity's teams we want to inherit.

Path
  • The path key works similarly to the path key in mirror properties;
  • The path does not need to end with the $team meta-property since it is inferred;
  • Team inheritance can only be configured using a path of single type relations.

For example, the following JSON (added to the blueprint definition) will configure the myBlueprint blueprint's entities to inherit their teams from the myExtraRelatedBlueprint blueprint's entities:

{
  "identifier": "myBlueprint",
  // ...blueprint properties
  "teamInheritance": {
    "path": "myRelatedBlueprint.myExtraRelatedBlueprint"
  }
}
note

In the example above, the relation chain is: myBlueprint -> myRelatedBlueprint -> myExtraRelatedBlueprint

Global VS granular permissions​

When granting write permissions for entities of a blueprint, you have 2 levels of control:

  1. Global permissions - create/update an entity as a whole. For example, allow Member users to update Env entities (all properties and relations).
  2. Granular permissions - control which properties and relations a user/role can update when creating or updating an entity. For example, allow Member users to only update the property slackChannelUrl of Env entities.

To apply granular permissions for a blueprint, use the updateProperties and updateRelations fields in the JSON, see the examples below:

The following change will allow Member users to update only the slackChannelUrl property of Env entities:

{
  "entities": {
    "updateProperties": {
      "slackChannelUrl": {
        "roles": ["Admin", "Env-moderator", "Member"], // changed from ["Admin", "Env-moderator"]
        "users": [],
        "teams": [],
        "ownedByTeam": false
      }
    }
  }
}
warning

Using global permissions override any granular permission that have been set.

If both permission types are set, then the global setting will be used when evaluating permissions.

info

update, updateProperties and updateRelations settings apply when registering new entities as well. This means that a user can't register a new entity with a property (or relation) that he doesn't have permissions to edit.