Skip to content
38 changes: 13 additions & 25 deletions docs/guides/considerations-set-up-runtime.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ 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).
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). In this guide it is assumed that you set up a separate instance for each internal project.
Comment thread
beckykd marked this conversation as resolved.
Outdated

<span id="overview-org"></span>
## Overview
Expand All @@ -30,29 +30,24 @@ 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.

<Admonition type="note">
This project is not related to the "project" concept in the classic IBM Quantum&reg; Platform.
</Admonition>

<span id="xplanning-orgx"></span>
## 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.
* If you are using a different IDP, does the Cloud administrator or the IDP administrator assign users to instances?
* If the IDP administrator assigns users to instance, you need a string to be used as a key, such as `project` (which this guide uses) for comparisons.
* What are the projects and which service instances will belong to each? You must plan your instance names carefully.
* Do not make instance names substrings of another. For example, if you use `ml` and `chemlab` for instance names, then later you set up an instance 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 instances.
* 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?
* Which users need to access which instances?
* 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.
* **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 instance 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.

<Admonition type="note">
Expand All @@ -73,29 +68,22 @@ To achieve that, define two different custom roles, such as `MLreader` and `MLwr
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.
</Admonition>

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).

<span id="shared-access"></span>
### 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.

<span id="other-cloud-rsc-org"></span>
### 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.

<span id="nest-org"></span>
### 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.
### 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&reg; 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.
In this guide, mapping users to 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.

<span id="repeat-org"></span>
### 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&reg; Provider documentation](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs) for templates.
The steps of this guide can be automated for consistent and repeatable management of users, instances, and the mapping between those. Refer to the [Terraform IBM Cloud&reg; 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.

Expand All @@ -111,7 +99,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
}
}
```
Expand Down
Loading