Repository: skypilot-org/skypilot
Pull request: Add doc for IAM permissions required by SkyPilot
<!-- Describe the changes in this PR -->

Describe the changes in this PR:

To close https://github.com/skypilot-org/skypilot/issues/1443, we'd like to add some documents for required IAM permissions to run SkyPilot.

<!-- Describe tests ran in a "Tested:" section -->
<!-- Unit tests (tests/test_*.py) are part of Github CI; the below are additional tests. -->

TODO in next PR:
- [ ] AWS IAM
- [ ] Azure IAM?

Problem statement:
[Docs] Cloud IAM access requirements for SkyPilot
When assigning people to our shared cloud account, I was wondering what's the minimal IAM access needed for SkyPilot to work instead of granting a full access owner. This can be relevant for people in industry who may not have full access to their shared corp account.
We probably want to investigate the access requirements in each cloud provider and document it in FAQ or even quick-start.

Hints from issue discussion:
After discussing offline, @infwinston and I found the following role list for the user is sufficient to launch the VM on GCP when the `ray-autoscaler` account is already setup.
```
roles/browser
roles/compute.admin
roles/iam.serviceAccountUser
roles/serviceusage.serviceUsageConsumer
roles/storage.admin
```
To set up the `ray-autoscaler` account, we need the `serviceAccount.setIAMPolicy` (can be done by the admin) to grant the following roles to the account:
```
roles/compute.admin
roles/iam.roleViewer
roles/iam.serviceAccountUser
roles/storage.objectAdmin
roles/tpu.admin
```
For TPU user, `TPU Admin` role needs to be added.

Commit message: role

Patch to review:
diff --git a/docs/source/getting-started/installation.rst b/docs/source/getting-started/installation.rst
index ecd92246886..996e4f6c96b 100644
--- a/docs/source/getting-started/installation.rst
+++ b/docs/source/getting-started/installation.rst
@@ -75,6 +75,10 @@ If running :code:`conda install -c conda-forge google-cloud-sdk` produces the er
 
 Note: if you encounter *Authorization Error (Error 400: invalid_request)* with the url generated by :code:`gcloud auth login`, try installing the latest version of the `Google Cloud SDK <https://cloud.google.com/sdk/docs/install>`_ (e.g., with :code:`conda install -c conda-forge google-cloud-sdk`) on **your local machine** (which opened the browser) and rerun the command.
 
+.. note::
+
+  If you are using multiple GCP projects, list all the configs by :code:`gcloud config configurations list` and activate one by :code:`gcloud config configurations activate <CONFIG_NAME>` (See `GCP docs <https://cloud.google.com/sdk/docs/configurations#activating_a_configuration>`_).
+
 **Azure**
 
 .. code-block:: console
diff --git a/docs/source/reference/faq.rst b/docs/source/reference/faq.rst
index 50698008a76..024f81ec622 100644
--- a/docs/source/reference/faq.rst
+++ b/docs/source/reference/faq.rst
@@ -76,6 +76,29 @@ If you have edited the ``file_mounts`` section (e.g., by adding some files) and
 To avoid rerunning the ``setup`` commands, pass the ``--no-setup`` flag to ``sky launch``.
 
 
+What are the required IAM permissons on GCP for SkyPilot?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use SkyPilot, your GCP account needs to be granted the following IAM roles.
+
+.. code-block:: yaml
+
+  roles/browser
+  roles/compute.admin
+  roles/iam.serviceAccountAdmin
+  roles/iam.serviceAccountUser
+  roles/serviceusage.serviceUsageConsumer
+  roles/storage.admin
+
+If you want to use TPUs, an additional role
+
+.. code-block:: yaml
+
+  roles/tpu.admin
+
+is required. You can grant those accesses via the `GCP IAM console <https://console.cloud.google.com/iam-admin/iam>`_.
+
+
 (Advanced) How to make SkyPilot use all global regions?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/source/reference/tpu.rst b/docs/source/reference/tpu.rst
index 2c762470a05..016bb8c2952 100644
--- a/docs/source/reference/tpu.rst
+++ b/docs/source/reference/tpu.rst
@@ -86,6 +86,7 @@ Here is a complete task YAML that runs `MNIST training <https://cloud.google.com
          pip install "jax[tpu]>=0.2.16" -f https://storage.googleapis.com/jax-releases/libtpu_releases.html
          pip install --upgrade clu
          pip install -e flax
+         pip install tensorflow tensorflow-datasets
       fi
 
    run: |


Code review comments:
diff_hunk: @@ -76,6 +76,29 @@ If you have edited the ``file_mounts`` section (e.g., by adding some files) and
 To avoid rerunning the ``setup`` commands, pass the ``--no-setup`` flag to ``sky launch``.
 
 
+What are the required IAM permissons on GCP for SkyPilot?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use SkyPilot, your GCP account needs to be granted the following IAM roles.
+
+.. code-block:: yaml
+
+  roles/browser
+  roles/compute.admin
+  roles/iam.serviceAccountAdmin
+  roles/iam.serviceAccountUser
+  roles/serviceusage.serviceUsageConsumer
+  roles/storage.admin
+
+If you want to use TPUs, an additional role
path: docs/source/reference/faq.rst
text: @user1:
```suggestion
Optionally, to use TPUs, an additional role is required:
```

@user2:
@user1 I don't understand the suggested change. How can something be both optional and required?

@user1:
How about “Optionally, to use TPUs, add the following role”?

@user2:
I think that is better. I still feel it is not clear that "optionally" is describing "to use TPUs", but maybe that's just me.