Merge pull request #2094 from aiven/staceys-users-groups-doc-481

Update docs for users and groups GA release

docs/platform/concepts/projects_accounts_access.rst

@@ -21,6 +21,8 @@ Grouping your projects in organizations and organizational units lets you centra
 
   * ACLs for service plans are inherited, meaning all projects within an organization or organizational unit will have the same service plan.
 
+* Groups - User groups managed at the organization level and assigned to projects
+
 * Teams - Specific to a single organization or organizational unit and cannot be shared between them
 
 * Support contracts - Specific to a single organization or organizational unit and cannot be shared between them
@@ -38,69 +40,27 @@ Projects are collections of services and user permissions. Each project must hav
 
 * Project-based: Each project contains all the services for an internal project, with naming that highlights the relevant environment; for example: ``customer-success-prod`` and ``business-analytics-test``.
 
-Service access management
---------------------------
-
-There are two ways that you can manage access to Aiven services:
-
-* Direct access via projects
-* Indirectly via role-based access controls (RBAC)
-
-Smaller teams usually favor direct access, while larger teams favor RBAC to simplify complex access requirements.
-
-Project members and roles
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Project and service access management
+--------------------------------------
 
-You can define different levels of access for each project member using roles:
+You can grant users access to services at the project level by adding them as project members, either individually or in :doc:`groups </docs/platform/howto/add-groups-projects>`.
 
-* **Administrator**: Can change and view billing information, remove members, and create, edit, and delete services. When you create a project, you automatically receive this access level. 
+The Aiven platform lets you use a mix of group and individual access rights for projects. One example of this is to grant read-only access to all projects in an organization or unit for a group of external contractors. 
 
-* **Operator**: Full access to services, but can't modify billing information or project members.
+Groups
+~~~~~~
 
-* **Developer**: Can manage existing services (for example, creating databases and connecting to them), but can't make any changes that would affect billing (for example, starting or stopping services).
-
-* **Read Only**: Can view services, but can't make any changes to them.
-
-
-.. list-table::
-   :header-rows: 1
-
-   * - Role
-     - View status
-     - Connect
-     - Deploy
-     - Billing/editing access
-   * - Administrator
-     - |tick|
-     - |tick|
-     - |tick|
-     - |tick|
-   * - Operator
-     - |tick|
-     - |tick|
-     - |tick|
-     - 
-   * - Developer
-     - |tick|
-     - |tick|
-     - 
-     - 
-   * - Read Only
-     - |tick|
-     - 
-     - 
-     - 
-.. Note::
-    The Read-Only role cannot view or copy service account passwords, but the Administrator, Operator and Developer roles have full access to manage service accounts.
+:doc:`Organization users </docs/platform/howto/manage-org-users>` can be :doc:`added to groups </docs/platform/howto/manage-groups>`, making it easy to control access to the services in a project. When you :doc:`add a group to a project </docs/platform/howto/add-groups-projects>`, you also select the role for that group. This role gives all users in that group the same level of access to all services in the project.
 
 Teams
 ~~~~~
 
-You can also use teams within organizations or organizational units to control access to projects for a group of users instead of specifying them per project. When you create a team, you choose which projects to associate it to and define the roles.
-
-One example of this is to grant read-only access to all projects in an organization or unit for a team of external contractors. The Aiven platform lets you use a mix of team and individual access rights for projects.
+.. important::
+    **Teams are becoming groups**
+
+    :doc:`Groups </docs/platform/howto/manage-groups>` are an easier way to control access to your organization's projects and services for a group of users.
 
-Another option is to set up :doc:`SAML single sign-on (SSO) </docs/platform/howto/list-saml>` for an organization that automatically adds users to a team when they sign up. For greater security, you may want to use a combination of SAML and RBAC regardless of the size of team.
+You can also use teams within organizations or organizational units to control access to projects for a group of users. When you create a team, you choose which projects to add it to. Another option is to set up :doc:`SAML single sign-on (SSO) </docs/platform/howto/list-saml>` for an organization that automatically adds users to a team when they sign up. For greater security, you may want to use a combination of SAML and RBAC regardless of the size of team.
 
 Best practices for organizations
 ---------------------------------
@@ -119,4 +79,4 @@ You could, for example, group projects into organizational units that correspond
 
 **Large organizations**
 
-For large organizations, it's best to keep all of your projects in organizational units instead of organizations. By keeping all of your projects in organizational units you can define teams, support contracts, and billing groups for each group of projects.
+For large organizations, it's best to keep all of your projects in organizational units instead of organizations. By keeping all of your projects in organizational units you can centrally manage things like support contracts and billing groups for each group of projects.

docs/platform/howto/add-groups-projects.rst

@@ -1,9 +1,6 @@
 Add groups to projects
 ======================
 
-.. important::
-    Groups are available as a feature preview and must be :doc:`enabled in the user profile </docs/platform/howto/feature-preview>`.
-
 Give :doc:`groups </docs/platform/howto/manage-groups>` of organization users access to a project and the services in it by adding groups to it. When you add a group, you set the permission level by assigning the group a :doc:`role </docs/platform/reference/project-member-privileges>` for that specific project.
 
 Add groups to a project 
@@ -15,7 +12,7 @@ Add groups to a project
 
 #. Select the groups that you want to add to the project. 
 
-#. Select a **Role**. This role will be assigned to all users in all selected groups.
+#. Select a **Role**. This :doc:`role </docs/platform/reference/project-member-privileges>` will be assigned to all users in all selected groups.
 
 #. Click **Add groups**.
 

docs/platform/howto/manage-groups.rst

@@ -1,9 +1,6 @@
 Create and manage groups in an organization
 ============================================
 
-.. important::
-    Groups are available as a feature preview and must be :doc:`enabled in the user profile </docs/platform/howto/feature-preview>`.
-
 Create groups of users in your organization to make it easier to :doc:`give users with similar roles access to projects </docs/platform/howto/add-groups-projects>`. You need to :doc:`invite users to your organization </docs/platform/howto/manage-org-users>` before adding them to a group.
 
 Create a group 

docs/platform/howto/manage-org-users.rst

@@ -1,9 +1,6 @@
 Manage users in an organization
 ================================
 
-.. important::
-    Organization users is an early availability feature. To use it, :doc:`enable the feature preview </docs/platform/howto/feature-preview>` in your user profile.
-
 Adding users to your organization lets you give them access to specific organizational units, projects, and services within that organization. 
 
 Invite users to an organization
@@ -27,7 +24,7 @@ The users receive an email with instructions to sign up (for new users) and acce
 Remove users from an organization
 ----------------------------------
 
-If you remove a user from an organization, they will also be removed from all teams and projects and no longer have access to any resources in the organization. 
+If you remove a user from an organization, they will also be removed from all groups and projects and no longer have access to any resources in the organization. 
 
 To remove a user from an organization: 
 

docs/platform/howto/manage-unassigned-projects.rst

@@ -41,11 +41,11 @@ If you don't have any organization yet, you can create one:
 
 #. If you want to invite admin users to the organization, set the toggle to **Yes** and enter their email addresses. They will receive an email invitation with a confirmation link.
 
-   .. important:: When admin users accept the invitation, they are added to the default team that has full control over the organization and the projects assigned to it.
+   .. important:: When admin users accept the invitation, they have full control over the organization and the projects assigned to it.
 
 #. Click **Create organization**.
 
-The **Admin** page opens, where you can add organizational units, and manage teams, projects, and other settings. 
+The **Admin** page opens, where you can add organizational units, and manage users, groups, and other settings. 
 
 
 Manage unassigned projects with the API 

docs/platform/howto/saml/saml-authentication.rst

@@ -32,7 +32,7 @@ SAML Authentication methods are configured at the organization level:
 
 #. Click on **Add authentication method**.
 
-#. Enter a name and select SAML. You can also select the teams that users will be added to when they sign up or log in through this authentication method.
+#. Enter a name and select SAML. You can also select the groups that users will be added to when they sign up or log in through this authentication method.
 
 You are shown the two parameters needed for the SAML authentication setup in your Identity Provider:
 

docs/platform/howto/saml/setup-saml-auth0.rst

@@ -12,7 +12,7 @@ Prerequisite steps in Aiven Console
 
 #. Click **Add authentication method**.
 
-#. Enter a name and select SAML. You can also select the teams that users will be added to when they sign up or log in through this authentication method.
+#. Enter a name and select SAML. You can also select the groups that users will be added to when they sign up or log in through this authentication method.
 
 You are shown two parameters needed to set up the SAML authentication in Auth0:
 

docs/platform/howto/saml/setup-saml-azure.rst

@@ -13,7 +13,7 @@ Prerequisite steps in Aiven Console
 
 #. Click **Add authentication method**.
 
-#. Enter a name and select SAML. You can also select the teams that users will be added to when they sign up or log in through this authentication method.
+#. Enter a name and select SAML. You can also select the groups that users will be added to when they sign up or log in through this authentication method.
 
 You are shown two parameters needed to set up the SAML authentication in Microsoft Azure AD:
 

docs/platform/howto/saml/setup-saml-fusionauth.rst

@@ -12,7 +12,7 @@ Prerequisite steps in Aiven Console
 
 #. Click **Add authentication method**.
 
-#. Enter a name and select SAML. You can also select the teams that users will be added to when they sign up or log in through this authentication method.
+#. Enter a name and select SAML. You can also select the groups that users will be added to when they sign up or log in through this authentication method.
 
 #. Click **Add method**.
 

docs/platform/howto/saml/setup-saml-google.rst

@@ -12,7 +12,7 @@ Prerequisite steps in Aiven Console
 
 #. Click **Add authentication method**.
 
-#. Enter a name and select SAML. You can also select the teams that users will be added to when they sign up or log in through this authentication method.
+#. Enter a name and select SAML. You can also select the groups that users will be added to when they sign up or log in through this authentication method.
 
 You are shown two parameters needed to set up the SAML authentication in Google:
 

docs/platform/howto/saml/setup-saml-jumpcloud.rst

@@ -12,7 +12,7 @@ Prerequisite steps in Aiven Console
 
 #. Click **Add authentication method**.
 
-#. Enter a name and select SAML. You can also select the teams that users will be added to when they sign up or log in through this authentication method.
+#. Enter a name and select SAML. You can also select the groups that users will be added to when they sign up or log in through this authentication method.
 
 You are shown two parameters needed to set up the SAML authentication in JumpCloud:
 

docs/platform/howto/saml/setup-saml-okta.rst

@@ -12,7 +12,7 @@ Prerequisite steps in Aiven Console
 
 #. Click **Add authentication method**.
 
-#. Enter a name and select SAML. You can also select the teams that users will be added to when they sign up or log in through this authentication method.
+#. Enter a name and select SAML. You can also select the groups that users will be added to when they sign up or log in through this authentication method.
 
 You are shown two parameters needed to set up the SAML authentication in Okta:
 

docs/platform/howto/saml/setup-saml-onelogin.rst

@@ -12,7 +12,7 @@ Prerequisite steps in Aiven Console
 
 #. Click **Add authentication method**.
 
-#. Enter a name and select SAML. You can also select the teams that users will be added to when they sign up or log in through this authentication method.
+#. Enter a name and select SAML. You can also select the groups that users will be added to when they sign up or log in through this authentication method.
 
 You are shown two parameters needed to set up the SAML authentication in OneLogin:
 

docs/platform/reference/project-member-privileges.rst

@@ -1,22 +1,17 @@
 Project member roles
 =====================
 
-User permissions are assigned at the project level by role. Each user added to a project - individually or as part of a :doc:`group </docs/platform/howto/manage-groups>` - is assigned a role for that project.
+User permissions are assigned at the project level by role. Each user added to a project - individually or as part of a :doc:`group </docs/platform/howto/manage-groups>` - becomes a project member and is assigned a role for that project.
 
-.. important::
+You can grant different levels of access to project members using roles:
 
-    Roles can only be managed by project **Admin** users on the **Members** page.
-
-Project roles and their permissions
-------------------------------------
-
-The project roles and their permissions are:
 
 * **Admin**: Full access to the project and its services. 
 
   * Do not have access to organization settings such as billing. 
   * Are the only users allowed to add more users to the project.
-
+  * When you create a project, you automatically have this access level.
+
   .. note::
 
     Every project must have at least one admin user.
@@ -36,3 +31,43 @@ The project roles and their permissions are:
 * **Read-only**: Only allowed to view services.
 
   * Cannot make any changes to the project or its services.
+
+
+.. list-table::
+   :header-rows: 1
+
+   * - Role
+     - View services
+     - Create services
+     - Manage services
+     - Connect
+     - Power services on/off
+     - Edit members and roles
+   * - Administrator
+     - |tick|
+     - |tick|
+     - |tick|
+     - |tick|
+     - |tick|
+     - |tick|
+   * - Operator
+     - |tick|
+     - |tick|
+     - |tick|
+     - |tick|
+     - |tick|
+     - 
+   * - Developer
+     - |tick|
+     - |tick|
+     - |tick|
+     - |tick|
+     - 
+     - 
+   * - Read Only
+     - |tick|
+     - 
+     - 
+     - 
+     - 
+     - 

docs/tools/aiven-console.rst

@@ -43,14 +43,14 @@ The :doc:`organization or organizational unit </docs/platform/concepts/projects_
 
 If you don't have an organization, click **Create organization** to :doc:`create your first organization</docs/tools/aiven-console/howto/create-accounts>`. 
 
-.. note:: We strongly recommend creating an organization. It makes managing your projects much easier and comes with many additional features, such as teams (user groups), billing groups, and SAML authentication.
+.. note:: We strongly recommend creating an organization. It makes managing your projects much easier and comes with many additional features, such as groups, billing groups, and SAML authentication.
 
 Organization and organizational unit settings are available on the **Admin** page. Here you can:
 
-* :doc:`Manage your teams</docs/tools/aiven-console/howto/create-manage-teams>` 
+* :doc:`Manage your groups</docs/platform/howto/manage-groups>` 
 * Create new projects under an organization or organizational unit
 * Configure :doc:`authentication methods for an organization </docs/platform/howto/list-saml>`
-* View logs of activity such as the adding or removing of team members, changing authentication methods, and more
+* View logs of activity such as the adding or removing of users, changing authentication methods, and more
 * Rename or delete an organization or organizational unit 
 
 Projects and services

docs/tools/aiven-console/howto/create-accounts.rst

@@ -1,7 +1,7 @@
 Create organizations and organizational units
 ==============================================
 
-**Organizations** and **organizational units** (or **units**) can be used to group projects and apply common settings like authentication and teams (user groups). For details and recommendations on creating hierarchical organizations in Aiven, see :doc:`Organizations, projects, and managing access permissions </docs/platform/concepts/projects_accounts_access>`.
+**Organizations** and **organizational units** (or **units**) can be used to group projects and apply common settings like authentication and access for groups of users. For details and recommendations on creating hierarchical organizations in Aiven, see :doc:`Organizations, projects, and managing access permissions </docs/platform/concepts/projects_accounts_access>`.
 
 Create an organizational unit
 ---------------------------------
@@ -22,7 +22,7 @@ You can create an organizational unit within an organization to group your proje
 
 #. Click **Create organizational unit**.
 
-Your organizational unit is shown in the **Organizational units** section. Click the unit name to view and manage it's teams and projects. 
+Your organizational unit is shown in the **Organizational units** section. Click the unit name to view and manage it's groups and projects. 
 
 .. note::
    Only one level of nesting is supported. This means that organizational units cannot be created within other units.
@@ -34,7 +34,7 @@ Create an organization
 .. important::
    We recommend using **only one organization** and creating organizational units to group your projects. 
 
-   Creating a new organization requires you to manually configure organization-level settings again such as :doc:`billing groups, authentication settings, and teams </docs/platform/concepts/projects_accounts_access>`.
+   Creating a new organization requires you to manually configure organization-level settings again such as :doc:`billing groups, authentication settings, and groups </docs/platform/concepts/projects_accounts_access>`.
 
 #. Click the user information icon and select **Organizations**. 
 
@@ -46,8 +46,8 @@ Create an organization
 
 #. If you want to invite admin users to the organization, set the toggle to **Yes** and enter their email addresses. They will receive an email invitation with a confirmation link.
 
-   .. important:: When admin users accept the invitation, they are added to the default team that has full control over the organization and the projects assigned to it.
+   .. important:: Admin users have full control over the organization and the projects assigned to it after they accept the invitation,.
 
 #. Click **Create organization**.
 
-The **Admin** page opens, where you can add organizational units, and manage teams, projects, and other settings. 
+The **Admin** page opens, where you can add organizational units, and manage groups, projects, and other settings.