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
The response is the text of your instance's IAM policy. See the following for an example. 
{
  "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