Zugriff auf eine nutzerverwaltete Notebookinstanz verwalten

In dieser Anleitung wird beschrieben, wie Sie einer bestimmten verwalteten Instanz von Vertex AI Workbench verwaltete Notebooks gewähren. Informationen zum Verwalten des Zugriffs auf Vertex AI-Ressourcen finden Sie auf der Seite Vertex AI-Seite zur Zugriffssteuerung.

Sie gewähren einer verwalteten Notebook-Instanz Zugriff, indem Sie eine IAM-Richtlinie (Identity and Access Management) für die Instanz festlegen. Die Richtlinie bindet ein oder mehrere Hauptkonten, z. B. einen Nutzer oder ein Dienstkonto, an eine oder mehrere Rollen. Jede Rolle enthält eine Reihe von Berechtigungen, mit denen das Hauptkonto mit der Instanz interagieren kann.

Sie können Zugriff auf eine Instanz statt auf eine übergeordnete Ressource wie ein Projekt, einen Ordner oder eine Organisation gewähren, um das Prinzip der geringsten Berechtigung anzuwenden.

Wenn Sie Zugriff auf eine übergeordnete Ressource gewähren (z. B. auf ein Projekt), erteilen Sie implizit auch Zugriff auf alle ihr untergeordneten Ressourcen, etwa auf alle Instanzen in diesem Projekt. Sie können den Zugriff auf Ressourcen auch beschränken. Legen Sie dazu die IAM-Richtlinien nach Möglichkeit auf untergeordneten Ebenen fest, anstatt auf Projektebene oder darüber.

Allgemeine Informationen zum Gewähren, Ändern und Entziehen des Zugriffs auf Ressourcen, die nichts mit Vertex AI Workbench zu tun haben, z. B. auf ein Google Cloud-Projekt, finden Sie in der IAM-Dokumentation für Verwalten des Zugriffs auf Projekte, Ordner und Organisationen

Zugriffsbeschränkungen

Der Zugriff auf eine Instanz kann eine Vielzahl von Funktionen umfassen, je nach der Rolle, die Sie dem Hauptkonto zuweisen. Beispielsweise können Sie einem Hauptkonto die Möglichkeit geben, den Systemstatus einer Instanz zu starten, zu stoppen, zu aktualisieren und zu überwachen. Eine vollständige Liste der verfügbaren IAM-Berechtigungen finden Sie unter IAM-Rollen für vordefinierte verwaltete Notebooks.

Auch wenn einem Hauptkonto vollständiger Zugriff auf eine vom Nutzer verwaltete Notebook-Instanz gewährt wird, kann nicht die JupyterLab-Schnittstelle der Instanz verwendet werden. Informationen zum Gewähren des Zugriffs auf die JupyterLab-Oberfläche finden Sie unter Zugriff auf die JupyterLab-Schnittstelle einer nutzerverwalteten Notebook-Instanz verwalten.

Zugriff auf nutzerverwaltete Notebook-Instanzen gewähren

Wenn Sie Nutzern Zugriff auf eine bestimmte Instanz mit verwalteten Notebooks gewähren möchten, legen Sie eine IAM-Richtlinie für die Instanz fest.

gcloud

Wenn Sie einem Hauptkonto auf einer nutzerverwalteten Notebookinstanz eine Rolle zuweisen möchten, verwenden Sie den Befehl get-iam-policy, um die aktuelle Richtlinie abzurufen. Bearbeiten Sie dann den Zugriff auf die aktuelle Richtlinie und aktualisieren Sie dann mit dem Befehl set-iam-policy die Richtlinie für die Instanz.

Aktuelle Richtlinie abrufen

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

INSTANCE_NAME: Der Name Ihrer nutzerverwalteten Notebookinstanz
PROJECT_ID: Ihre Google Cloud-Projekt-ID
ZONE: Die Zone, in der sich Ihre Instanz befindet

Führen Sie folgenden Befehl aus:

Linux, macOS oder Cloud Shell

gcloud notebooks instances get-iam-policy INSTANCE_NAME --project=PROJECT_ID --location=ZONE

Windows (PowerShell)

gcloud notebooks instances get-iam-policy INSTANCE_NAME --project=PROJECT_ID --location=ZONE

Windows (cmd.exe)

gcloud notebooks instances get-iam-policy INSTANCE_NAME --project=PROJECT_ID --location=ZONE

Die Antwort ist der Text der IAM-Richtlinie Ihrer Instanz. Im Folgenden finden Sie ein Beispiel.

{
  "bindings": [
    {
      "role": "roles/notebooks.viewer",
      "members": [
        "user:email@example.com"
      ]
    }
  ],
  "etag": "BwWWja0YfJA=",
  "version": 3
}

Richtlinie bearbeiten

Bearbeiten Sie die Richtlinie mit einem Texteditor, um Hauptkonten und die zugehörigen Rollen hinzuzufügen oder zu entfernen. Beispiel: Fügen Sie der Richtlinie im Abschnitt "bindings" die folgende neue Bindung hinzu, um eve@example.com die Rolle notebooks.admin zu gewähren:

{
  "role": "roles/notebooks.admin",
  "members": [
    "user:eve@example.com"
  ]
}

Nach dem Hinzufügen der neuen Bindung kann die Richtlinie in etwa so aussehen:

{
  "bindings": [
    {
      "role": "roles/notebooks.viewer",
      "members": [
        "user:email@example.com"
      ]
    },
    {
      "role": "roles/notebooks.admin",
      "members": [
        "user:eve@example.com"
      ]
    }
  ],
  "etag": "BwWWja0YfJA=",
  "version": 3
}

Speichern Sie die aktualisierte Richtlinie in einer Datei mit dem Namen request.json.

Richtlinie für die Instanz aktualisieren

Geben Sie im Anfragetext die aktualisierte IAM-Richtlinie aus dem vorherigen Schritt verschachtelt in einem "policy"-Abschnitt ein.

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

INSTANCE_NAME: Der Name Ihrer nutzerverwalteten Notebookinstanz
PROJECT_ID: Ihre Google Cloud-Projekt-ID
ZONE: Die Zone, in der sich Ihre Instanz befindet

Speichern Sie den folgenden Inhalt in einer Datei mit dem Namen request.json:

{
  "policy": {
    "bindings": [
      {
        "role": "roles/notebooks.viewer",
        "members": [
          "user:email@example.com"
        ]
      },
      {
        "role": "roles/notebooks.admin",
        "members": [
          "user:eve@example.com"
        ]
      }
    ],
    "etag": "BwWWja0YfJA=",
    "version": 3
  }
}

Führen Sie folgenden Befehl aus:

Linux, macOS oder Cloud Shell

gcloud notebooks instances set-iam-policy INSTANCE_NAME --project=PROJECT_ID --location=ZONE request.json --format=json

Windows (PowerShell)

gcloud notebooks instances set-iam-policy INSTANCE_NAME --project=PROJECT_ID --location=ZONE request.json --format=json

Windows (cmd.exe)

gcloud notebooks instances set-iam-policy INSTANCE_NAME --project=PROJECT_ID --location=ZONE request.json --format=json

Zugriff auf die JupyterLab-Schnittstelle gewähren

Wenn Sie einem Hauptzugriff auf eine verwaltete Notebookinstanz zuweisen, kann nicht die JupyterLab-Schnittstelle der Instanz verwendet werden. Informationen zum Gewähren des Zugriffs auf die JupyterLab-Oberfläche finden Sie unter Zugriff auf die JupyterLab-Schnittstelle einer nutzerverwalteten Notebook-Instanz verwalten.

API

Wenn Sie einem Hauptkonto auf einer vom Nutzer verwalteten Notebookinstanz eine Rolle zuweisen möchten, verwenden Sie die Methode getIamPolicy, um die aktuelle Richtlinie abzurufen. Ändern Sie den Zugriff auf die aktuelle Richtlinie und verwenden Sie die Methode setIamPolicy, um die Richtlinie für die Instanz zu aktualisieren.

Aktuelle Richtlinie abrufen

Ersetzen Sie dabei folgende Werte für die Anfragedaten:

INSTANCE_NAME: Der Name Ihrer nutzerverwalteten Notebookinstanz

HTTP-Methode und URL:

GET https://notebooks.googleapis.com/v1/INSTANCE_NAME:getIamPolicy

Senden Sie die Anfrage mithilfe einer der folgenden Optionen:

curl

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto bei der gcloud CLI angemeldet haben. Dazu haben Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt, die Sie automatisch bei der gcloud CLI anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Führen Sie folgenden Befehl aus:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://notebooks.googleapis.com/v1/INSTANCE_NAME:getIamPolicy"

PowerShell

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto bei der gcloud CLI angemeldet haben. Dazu führen Sie gcloud init oder gcloud auth login aus. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Führen Sie diesen Befehl aus:

$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

Die Antwort ist der Text der IAM-Richtlinie Ihrer Instanz. Im Folgenden finden Sie ein Beispiel.

{
  "bindings": [
    {
      "role": "roles/notebooks.viewer",
      "members": [
        "user:email@example.com"
      ]
    }
  ],
  "etag": "BwWWja0YfJA=",
  "version": 3
}

Richtlinie bearbeiten

Bearbeiten Sie die Richtlinie mit einem Texteditor, um Hauptkonten und die zugehörigen Rollen hinzuzufügen oder zu entfernen. Beispiel: Fügen Sie der Richtlinie im Abschnitt "bindings" die folgende neue Bindung hinzu, um eve@example.com die Rolle notebooks.admin zu gewähren:

{
  "role": "roles/notebooks.admin",
  "members": [
    "user:eve@example.com"
  ]
}

Nach dem Hinzufügen der neuen Bindung kann die Richtlinie in etwa so aussehen:

{
  "bindings": [
    {
      "role": "roles/notebooks.viewer",
      "members": [
        "user:email@example.com"
      ]
    },
    {
      "role": "roles/notebooks.admin",
      "members": [
        "user:eve@example.com"
      ]
    }
  ],
  "etag": "BwWWja0YfJA=",
  "version": 3
}

Richtlinie für die Instanz aktualisieren

Geben Sie im Anfragetext die aktualisierte IAM-Richtlinie aus dem vorherigen Schritt verschachtelt in einem "policy"-Abschnitt ein.

Ersetzen Sie dabei folgende Werte für die Anfragedaten:

INSTANCE_NAME: Der Name Ihrer nutzerverwalteten Notebookinstanz

HTTP-Methode und URL:

POST https://notebooks.googleapis.com/v1/INSTANCE_NAME:setIamPolicy

JSON-Text der Anfrage:

{
  "policy": {
    "bindings": [
      {
        "role": "roles/notebooks.viewer",
        "members": [
          "user:email@example.com"
        ]
      },
      {
        "role": "roles/notebooks.admin",
        "members": [
          "user:eve@example.com"
        ]
      }
    ],
    "etag": "BwWWja0YfJA=",
    "version": 3
  }
}

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

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

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$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

Sie sollten einen erfolgreichen Statuscode (2xx) und eine leere Antwort als Ausgabe erhalten.

Zugriff auf die JupyterLab-Schnittstelle gewähren

Nächste Schritte

Einem Hauptkonto Zugriff auf JupyterLab gewähren.
Informationen zur Identitäts- und Zugriffsverwaltung (Identity and Access Management, IAM) und dazu, wie IAM-Rollen beim Gewähren und Einschränken des Zugriffs helfen können, finden Sie in der IAM-Dokumentation.
Mehr über die IAM-Rollen erfahren, die für von Nutzern verwaltete Vertex AI Workbench-Notebooks verfügbar sind.
Mehr über das Erstellen und Verwalten benutzerdefinierter Rollen erfahren.
Informationen zum Gewähren des Zugriffs auf andere Google-Ressourcen finden Sie unter Zugriff auf andere Ressourcen verwalten.