diff --git a/docs/guides/considerations-set-up-runtime.mdx b/docs/guides/considerations-set-up-runtime.mdx
index d96260f2bd82..5e8c6f27ab0b 100644
--- a/docs/guides/considerations-set-up-runtime.mdx
+++ b/docs/guides/considerations-set-up-runtime.mdx
@@ -7,56 +7,56 @@ description: Considerations for setting up IBM Quantum Platform in an organizati
# Considerations for setting up IBM Quantum Platform for an organization
-In an organization where individuals might work on several projects, IBM Quantum Platform governance can seem complex. However, access management can be used to easily enable user collaboration and to restrict visibility of users and projects when necessary. Managing access becomes more relevant with IBM Quantum Platform resources that are not free - that is, service instances that use paid plans (which organizations are charged for).
+IBM Quantum® Platform is the dashboard for your IBM Cloud® account's IBM Quantum Compute Service instances and workloads, and provides a simplified view of access management. An organization's IBM Cloud account can have multiple users and multiple Quantum Compute instances, each with its own allocation. Identity and Access Management (IAM) controls which users can access which service instances, so you can enable collaboration while restricting visibility where needed. Access management becomes more relevant if you have service instances on paid plans. See [IBM Cloud account structure](/docs/guides/cloud-account-structure) for an overview of how accounts, users, instances, and access fit together. Refer to the [IBM Cloud IAM documentation](https://cloud.ibm.com/docs/account?topic=account-iamoverview) for full details on the IAM concepts referenced in this guide, such as access groups, policies, roles, and resource groups.
+
+This guide describes the decisions and tradeoffs involved in setting up access for an organization with multiple service instances — for example, assigning one instance per team or workload.
+
+
+If your organization has multiple IBM Cloud accounts — for example, separate accounts per business unit, each with its own Quantum Compute instances — you can link them under a single IBM Cloud Enterprise account, which has one main account responsible for billing and one or more child accounts. To redistribute Premium or Flex Plan allocation between child accounts, contact IBM Quantum support through the [IBM Cloud Support Center](https://cloud.ibm.com/unifiedsupport/cases/form). See the [IBM Cloud Enterprise account documentation](https://cloud.ibm.com/docs/account?topic=account-what-is-enterprise) for full details.
+
## Overview
- IBM Cloud® provides various ways to implement these mechanisms described in this guide. There are several ways to achieve these objectives. Additionally, most of the steps in this guide are generic to IBM Cloud and not specific to IBM Quantum Platform, except the custom role details.
+ IBM Cloud® provides several ways to implement the mechanisms described in this guide. Most of the steps are generic to IBM Cloud and not specific to Quantum Compute, except the custom role details.
### Involved personas
-The are several main personas that are mentioned in this guide:
+The following personas are mentioned in this guide:
-* **User**: Someone who gets access to IBM Quantum Platform resources (_service instances_) and can potentially collaborate with other users on these resources. Users' access is controlled by an administrator and they cannot create or delete service instances.
-* **Cloud administrator**: An IBM Cloud account owner who owns IBM Quantum Platform resources and manages which users can access these resources. As the resource owner, the administrator is charged for any paid resource use.
+* **User**: Someone who gets access to Quantum Compute resources (_service instances_) and can potentially collaborate with other users on these resources. Users' access is controlled by an administrator, and they cannot create or delete service instances.
+* **Cloud administrator**: An IBM Cloud account owner who owns the Quantum Compute resources and manages which users can access these resources. As the resource owner, the administrator is charged for any paid resource use.
* **IDP administrator**: An administrator who defines identities and their attributes in an identity provider (IDP).
### Terminology
This guide uses the following terms:
-* _Resource_: A generic IBM Cloud term that refers to an object that can be managed through the Cloud user interface, CLI, or API. For this guide, a _resource_ is an IBM Quantum Platform service instance.
-* _Service instance_: A service instance is used to access Cloud services - specifically, quantum computers. It is defined through the catalog. You can define several service instances based on the same or different plans, which offer access to different quantum computing backends. See [Available IBM Cloud plan](/docs/guides/plans-overview) for details.
-* _Project_: A grouping unit that enables users to work on the same resources. This guide uses two projects: `ml` and `finance`. See [Hierarchical project structures](#nest-org) for more information.
-
-
- This project is not related to the "project" concept in the classic IBM Quantum® Platform.
-
+* _Resource_: A generic IBM Cloud term that refers to an object that can be managed through the Cloud user interface, CLI, or API. For this guide, a _resource_ is a Qiskit Runtime service instance.
+* _Service instance_: A service instance is used to access Cloud services - specifically, quantum computers, through the Qiskit Runtime service. It is defined through the catalog. You can define several service instances based on the same or different plans, which offer access to different quantum computing backends. See [Available IBM Cloud plans](/docs/guides/plans-overview) for details.
## Plan your setup
Before you set up IBM Quantum Platform for your organization, you need to make these decisions:
-* How are user identities defined? You can set up IBM Cloud users, users from another identity provider (IDP), or both.
- * If you are using a different IDP, does the Cloud administrator or the IDP administrator assign users to project resources?
- * If the IDP administrator assigns users to projects, you need a string to be used as a key, such as `project` (which this guide uses) for project comparisons.
-* What are the projects and which service instances will belong to each? You must plan your project names carefully.
- * Do not make project names substrings of another. For example, if you use `ml` and `chemlab` for project names, then later you set up a project match for `ml`, it triggers on both values, accidentally granting more access than expected. Instead, use unique names such as `ml` and `chem-lab`. Alternatively, use prefix or suffix values to avoid such unintended substring matches.
- * Using naming conventions along with prefix or suffix values can help you easily allow access to several projects.
- * Quantum experiments (jobs) belong to service instances, and users that have access to an instance can see its jobs.
- * Service instances can be based on different plans, allowing access to different backends.
-* Which users need to access which projects?
-* Should users be able to delete jobs? Keeping jobs in service instances gives more traceability for billing costs.
-* Will you use access groups that directly reference IBM Quantum Platform service instances or organize services into resource groups?
- * **Access groups** are a convenient and common way of controlling user access for IBM Cloud resources. They are a simple but powerful means to consistently assign user access. We create an access group for each project and map users to access groups. Each access group uses a custom role that allows users to access specific service instances or resource groups.
- * **Resource groups** are used only when you need to maintain a clear separation of service instances. If more service instances are created in a resource group, all users that have access to the resource group see them automatically without updating access groups. If you choose to use resource groups, you will create access groups and then assign them to resource groups.
+* **How are user identities defined?** You can set up IBM Cloud users, users from another identity provider (IDP), or both.
+ * If you are using a different IDP, does the Cloud administrator or the IDP administrator assign users to access groups?
+ * If the IDP administrator assigns users through dynamic rules, you need a custom IDP user attribute to use as a matching key (for example, a `team` attribute).
+* **How many service instances do you need, and what will each be used for?** Plan your instance names carefully. Whenever you create a service instance through the IBM Quantum Platform user interface, the platform makes an additional call to IAM on your behalf to create a matching access group (with the same name as the instance, with "Collaborators" appended) that grants write access to that instance. Therefore, instance names become access group names too. This extra step only happens when you create an instance through the IBM Quantum Platform user interface. It does not happen if you create the instance by using Terraform, the IBM Cloud CLI, or the IBM Cloud API.
+ * Workloads belong to service instances, and users who have access to an instance can see its workloads.
+ * Service instances can be based on different plans, allowing access to different backends and allocations.
+* **Which users need to access which service instances?**
+* **Should users be able to delete workloads?** Keeping workloads in service instances gives more traceability for billing costs.
+* **Will you use the access group that's automatically created for each instance, create additional access groups of your own, assign access to individual users directly, or organize instances into resource groups?**
+ * **Access groups** are a convenient and common way of controlling user access to IBM Cloud resources. Every service instance you create through the IBM Quantum Platform user interface already has its own "Collaborators" access group. You can use that group as-is, or create additional access groups in the IBM Cloud console to group users by team or workload (for example, `ml` and `finance`) across one or more instances. Each access group uses a custom role that allows users to access specific service instances or resource groups. If you don't need a group of users to share the same access, you can also assign access to individual users directly, without an access group.
+ * If you use dynamic rules based on IDP attributes to assign users to access groups, avoid attribute values that are substrings of one another. For example, if you use `ml` and `chemlab` as attribute values, a rule matching `ml` would also match `chemlab`, accidentally granting more access than expected. Use unique values such as `ml` and `chem-lab`, or add prefixes or suffixes to avoid unintended substring matches.
+ * **Resource groups** are used only when you need to maintain a clear separation of service instances. When creating a service instance from IBM Quantum Platform, you can select which resource group it belongs to (and add tags), but you must use the IBM Cloud console to create or manage the resource groups. If more service instances are created in a resource group, all users who have access to the resource group see them automatically, without updating access groups. If you choose to use resource groups, first create access groups and then assign them to resource groups.
- A service instance can belong to only one resource group. After instances are assigned into resource groups, they cannot be changed. This also means that the resource group assignment can happen only at service instance creation. Therefore, resource groups might not provide enough flexibility if assignments of service instances to resource groups might need to change.
+ A service instance can belong to only one resource group, and that assignment cannot be changed after the instance is created. Therefore, resource groups might not provide enough flexibility if service instances might need to move between resource groups later.
## Considerations
@@ -65,39 +65,32 @@ You should understand the following considerations when setting up your environm
### Define more fine-grained roles
-The actions in the custom roles can be used for more fine-grained access control. For example, some users might need full access to work on service instances, while others might only need Read access to service instances, programs, and jobs.
+Custom roles can be used for more fine-grained access control. For example, some users might need full access to work on service instances, while others might only need read access to service instances, programs, and workloads.
-To achieve that, define two different custom roles, such as `MLreader` and `MLwriter`. Remove all cancel, delete, and update roles from the `MLreader` custom role, and include all actions in the `MLwriter` custom role. Next, add the roles to two different access groups accordingly.
+To achieve that, define two different custom roles, such as `MLreader` and `MLwriter`. Remove all cancel, delete, and update actions from the `MLreader` custom role, and include all actions in the `MLwriter` custom role. Then add the roles to two different access groups accordingly.
-When using dynamic rules, that is, when the identity provider (IDP) administrator manages access through custom IDP user attributes, do not use IDP custom user attributes that are substrings of each other. For instance, don't use `ml` and `mlReader`, as the string comparison of `ml` would also accept `mlReader`. You could use `MLreader` and `MLwriter` to avoid this conflict.
+When using dynamic rules, that is, when the IDP administrator manages access through custom IDP user attributes, do not use IDP custom user attributes that are substrings of each other. For instance, don't use `ml` and `mlReader`, as the string comparison of `ml` would also accept `mlReader`. You could use `MLreader` and `MLwriter` to avoid this conflict.
-For an example of setting up custom roles, see [Create access groups for projects](/docs/guides/custom-roles).
+For an example, see [Set up custom roles](/docs/guides/custom-roles#custom).
### Shared workload access
-It is important to note that access applies to service instances. Thus, users with 'write' access to an instance can cancel their own workloads, but can also view and cancel other users' workloads. This is a function of how IAM works and cannot be changed.
-
-
-### Other Cloud resources
-
-The steps in this guide can be used to manage access to other Cloud resources as well. Include the appropriate permissions to the access groups of the relevant projects.
+Access applies to service instances. Thus, users with write access to an instance (including through the "Collaborators" access group automatically created for instances made by the IBM Quantum Platform user interface) can cancel their own workloads, but can also view and cancel other users' workloads in that instance. This is a function of how IAM works and cannot be changed.
-### Hierarchical project structures
-
-In this guide, the mapping of users to projects and service instances was kept simple. However, by associating several users with access groups and referencing service instances from several access groups, more complex mappings can be implemented.
+### Simulate hierarchical structures
-This method can accommodate a hierarchical structure. That is, it can align to how users might be assigned to the Hub/Group/Project access structure in the classic version of IBM Quantum® Platform. For example, a _group_ could be an access group that is assigned to all service instances of the group's projects. Users who should get access to all of the group's projects would then only have to be added to the group's access group.
+By default, each service instance's access is managed independently, for example, through the "Collaborators" access group automatically created for instances that were made through the IBM Quantum Platform user interface. IAM doesn't have a built-in hierarchy of groups, but you can approximate one by creating access groups that reference multiple teams' service instances. Users who need broad access only need to be added to one "top level" group, instead of to each team's individual access group.
### Consistent and repeatable deployment of the configuration
-The steps of this guide can be automated for consistent and repeatable management of users, projects, and the mapping between those. Refer to the [Terraform IBM Cloud® Provider documentation](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs) for templates.
+The steps in this guide can be automated for consistent and repeatable management of users, service instances, and the access mappings between them. Refer to the [Terraform IBM Cloud® Provider documentation](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs) for templates.
-You can use Terraform to set allocation and limits, as well as restrict backend access for `quantum-computing` service instances. See the [Getting started with Terraform on IBM Cloud](https://cloud.ibm.com/docs/ibm-cloud-provider-for-terraform?topic=ibm-cloud-provider-for-terraform-getting-started) for more information.
+You can use Terraform to set allocation and limits, as well as restrict backend access, for `quantum-computing` service instances. See [Getting started with Terraform on IBM Cloud](https://cloud.ibm.com/docs/ibm-cloud-provider-for-terraform?topic=ibm-cloud-provider-for-terraform-getting-started) for more information.
Example:
@@ -111,7 +104,7 @@ resource "ibm_resource_instance" "instance1" {
usage_allocation_seconds = "10" # Mandatory
usage_limit_seconds = "20" # Optional. If omitted, it can
# continue using time after reaching the allocation
- backends = ["ibm_brisbane"] # Optional
+ backends = ["ibm_boston"] # Optional
}
}
```
@@ -122,7 +115,9 @@ resource "ibm_resource_instance" "instance1" {
* See [Configure IBM Quantum Platform for an organization](/docs/guides/quickstart-steps-org) for the steps to set up IBM Quantum Platform.
* [Understand available plans](/docs/guides/plans-overview).
* [Create instances](/docs/guides/instances).
- * [Understand the IBM Cloud structure](/docs/guides/cloud-account-structure).
+ * [Understand the IBM Cloud account structure](/docs/guides/cloud-account-structure).
* [Create policies and access groups](/docs/guides/access-groups).
* [Manage users](/docs/guides/invite-and-manage-users).
+ * [IBM Cloud IAM documentation](https://cloud.ibm.com/docs/account?topic=account-iamoverview) for full IAM details.
+ * [IBM Cloud Enterprise documentation](https://cloud.ibm.com/docs/account?topic=account-what-is-enterprise) for managing multiple linked accounts.