Manage access to a managed notebooks instance
This guide describes how you can grant access to a specific Vertex AI Workbench managed notebooks instance. To manage access to Vertex AI resources, see the Vertex AI page on access control.
You grant access to a managed notebooks instance by setting an Identity and Access Management (IAM) policy on the instance. The policy binds one or more principals, such as a user or a service account, to one or more roles. Each role contains a list of permissions that let the principal interact with the instance.
You can grant access to an instance, instead of to a parent resource such as a project, folder, or organization, to exercise the principle of least privilege.
If you grant access to a parent resource (for example, to a project), you implicitly grant access to all its child resources (for example, to all instances in that project). To limit access to resources, set IAM policies on lower-level resources when possible, instead of at the project level or above.
For general information about how to grant, change, and revoke access to resources unrelated to Vertex AI Workbench, for example, to grant access to a Google Cloud project, see the IAM documentation for Granting, changing, and revoking access to resources.
Access limitations
Access to an instance can include a broad range of abilities, depending on the role you assign to the principal. For example, you might grant a principal the ability to start, stop, upgrade, and monitor the health status of an instance. For the complete list of IAM permissions available, see Predefined managed notebooks IAM roles.
However, even granting a principal full access to a managed notebooks instance doesn't grant the ability to use the instance's JupyterLab interface. To grant access to the JupyterLab interface, see Manage access to a managed notebooks instance's JupyterLab interface.
Grant access to managed notebooks instances
To grant users permission to access a specific managed notebooks instance, set an IAM policy on the instance.
To grant a role to a principal on
a managed notebooks instance, use the
getIamPolicy
method to retrieve the current policy,
edit the current policy's access, and then use the
setIamPolicy
method to update the policy on the instance.
Retrieve the current policy
Before using any of the request data, make the following replacements:
- INSTANCE_NAME: The name of your managed notebooks instance
HTTP method and URL:
GET https://notebooks.googleapis.com/v1/INSTANCE_NAME:getIamPolicy
To send your request, choose one of these options:
curl
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://notebooks.googleapis.com/v1/INSTANCE_NAME:getIamPolicy"
PowerShell
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://notebooks.googleapis.com/v1/INSTANCE_NAME:getIamPolicy" | Select-Object -Expand Content
{ "bindings": [ { "role": "roles/notebooks.viewer", "members": [ "user:email@example.com" ] } ], "etag": "BwWWja0YfJA=", "version": 3 }
Edit the policy
Edit the policy with a text editor to add or remove principals and their
associated roles. For example, to grant the notebooks.admin
role to
eve@example.com, add the following new binding to the policy
in the "bindings"
section:
{
"role": "roles/notebooks.admin",
"members": [
"user:eve@example.com"
]
}
After adding the new binding, the policy might look like the following:
{
"bindings": [
{
"role": "roles/notebooks.viewer",
"members": [
"user:email@example.com"
]
},
{
"role": "roles/notebooks.admin",
"members": [
"user:eve@example.com"
]
}
],
"etag": "BwWWja0YfJA=",
"version": 3
}
Update the policy on the instance
In the body of the request, provide the updated IAM
policy from the previous step, nested inside a "policy"
section.
Before using any of the request data, make the following replacements:
- INSTANCE_NAME: The name of your managed notebooks instance
HTTP method and URL:
POST https://notebooks.googleapis.com/v1/INSTANCE_NAME:setIamPolicy
Request JSON body:
{ "policy": { "bindings": [ { "role": "roles/notebooks.viewer", "members": [ "user:email@example.com" ] }, { "role": "roles/notebooks.admin", "members": [ "user:eve@example.com" ] } ], "etag": "BwWWja0YfJA=", "version": 3 } }
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://notebooks.googleapis.com/v1/INSTANCE_NAME:setIamPolicy"
PowerShell
Save the request body in a file named request.json
,
and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://notebooks.googleapis.com/v1/INSTANCE_NAME:setIamPolicy" | Select-Object -Expand Content
You should receive a successful status code (2xx) and an empty response.
Grant access to the JupyterLab interface
Granting a principal access to a managed notebooks instance doesn't grant the ability to use the instance's JupyterLab interface. To grant access to the JupyterLab interface, see Manage access to a managed notebooks instance's JupyterLab interface.
What's next
To learn about Identity and Access Management (IAM) and how IAM roles can help grant and restrict access, see the IAM documentation.
Learn about the IAM roles available to Vertex AI Workbench managed notebooks.
Learn how to create and manage custom roles.
To learn how to grant access to other Google resources, see Manage access to other resources.