This document discusses how to set permissions and enable access so you can:

- View Personalized Service Health events using the Service Health dashboard.
- Pull Service Health information using the Service Health API.
- Configure alerts relevant to your projects.

## Before you begin


[Verify that billing is enabled for your Google Cloud project](https://docs.cloud.google.com/billing/docs/how-to/verify-billing-enabled.md.txt#confirm_billing_is_enabled_on_a_project).

## Access the Service Health API and dashboard


To get the permissions that
you need to access the Service Health API and dashboard,

ask your administrator to grant you the
[Personalized Service Health Viewer](https://docs.cloud.google.com/iam/docs/roles-permissions/servicehealth.md.txt#servicehealth.viewer) (`roles/servicehealth.viewer`) IAM role on your project.


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

You can use the roles and permissions directly through the gcloud CLI
to set up proper access controls. For example, you can grant the role directly
with the following command:

```bash
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member {USER|GROUP|SERVICE_ACCOUNT} \
  --role roles/servicehealth.viewer
```

You can view the Identity and Access Management (IAM) policy for the given project with the
following command:

```bash
gcloud projects get-iam-policy PROJECT_ID
```

Alternatively, you can add the permissions directly to an existing role:

```bash
gcloud iam roles update ROLE_ID \
  --project=PROJECT_ID \
  --permissions="servicehealth.events.get,servicehealth.events.list,servicehealth.impacts.get,servicehealth.impacts.list,servicehealth.locations.get,servicehealth.locations.list,servicehealth.organizationEvents.get,servicehealth.organizationEvents.list,servicehealth.organizationImpacts.get,servicehealth.organizationImpacts.list,servicehealth.statuses.get,resourcemanager.projects.get,resourcemanager.projects.list"
```

### Control access to impacted resource details (Preview)

> [!WARNING]
>
> **Preview**
>
>
> This product or feature is
>
> subject to the "Pre-GA Offerings Terms" in the General Service Terms section
> of the [Service Specific
> Terms](https://docs.cloud.google.com/terms/service-terms#1).
>
> Pre-GA products and features are available "as is" and might have limited support.
>
> For more information, see the
> [launch stage descriptions](https://cloud.google.com/products/#product-launch-stages).

The `servicehealth.impacts.list` and `servicehealth.impacts.get` permissions
are included in the predefined Service Health Viewer role
(`roles/servicehealth.viewer`) and the basic Viewer, Editor, and Owner roles
(`roles/viewer`, `roles/editor`, `roles/owner`).

When a service disruption affects specific resources in your project, these
permissions allow principals to view the full resource names (`assetName`) and
resource types (`assetType`) of the impacted resources across the project.

If you want a principal to view project-level Service Health
events without seeing the names of individual impacted resources in the project,
create a custom role that includes `servicehealth.events.get` and
`servicehealth.events.list` but omits `servicehealth.impacts.get` and
`servicehealth.impacts.list`:

```bash
gcloud iam roles create EVENT_ONLY_ROLE_ID --project=PROJECT_ID \
--title="Service Health Event-Only Viewer" \
--description="Grants access to Service Health project events without resource-level impact details" \
--permissions="servicehealth.events.get,servicehealth.events.list,servicehealth.locations.get,servicehealth.locations.list,servicehealth.statuses.get,resourcemanager.projects.get"
```

## Use APIs and services in your projects

1. [Enable the Service Health API](https://docs.cloud.google.com/service-health/docs/manage-access.md.txt#enable-service-health-api-single-project) for the project.
2. Grant the [Service Usage Consumer](https://docs.cloud.google.com/iam/docs/roles-permissions/serviceusage.md.txt#serviceusage.serviceUsageConsumer) role (`roles/serviceusage.serviceUsageConsumer`).

## Access logs and configure log alerts

Do the following:

1. [Enable the Service Health API](https://docs.cloud.google.com/service-health/docs/manage-access.md.txt#enable-service-health-api-single-project) for the project.
2. Get [permissions for log-based alerts](https://docs.cloud.google.com/logging/docs/access-control.md.txt#lba-permissions).

If you don't want to grant the [Monitoring NotificationChannel Editor](https://docs.cloud.google.com/monitoring/access-control.md.txt#notification_channels_2) role
(`roles/monitoring.notificationChannelEditor`), you can grant the [Monitoring NotificationChannel Viewer](https://docs.cloud.google.com/monitoring/access-control.md.txt#notif_roles_desc) role (`roles/monitoring.notificationChannelViewer`) instead to allow you to link to a notification channel to an alerting policy.

For more information about granting roles, see [Manage access](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).

You might also be able to get the required permissions through [custom roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles.md.txt) or other [predefined roles](https://docs.cloud.google.com/iam/docs/understanding-roles).

## Enable Service Health API for a single project

Setting up alerts and pulling Service Health information require
enabling the Service Health API. You can enable the API through the
Google Cloud console or Google Cloud CLI.

### Console

1. In the APIs and Services library, go to the Service Health API.


   [Go to the Service Health API](https://console.cloud.google.com/apis/library/servicehealth.googleapis.com)

   <br />

   Alternatively, you can go to the
   [API Library](https://console.cloud.google.com/apis/library) and search
   "Service Health API".
2. Select the project.

3. Select the **Enable** button.

### gcloud


1. In the Google Cloud console, activate Cloud Shell.

   [Activate Cloud Shell](https://console.cloud.google.com/?cloudshell=true)
2. Make sure that the most recent version of Google Cloud CLI is installed. Run
   the following command from the Cloud Shell:

   <br />

   ```
     gcloud components update
   ```

   <br />

3. Create or select a new project,
   `PROJECT_ID`.

   - Create a Google Cloud project:

     ```
     gcloud projects create PROJECT_ID
     ```
   - Select the Google Cloud project that you created:

     ```
     gcloud projects config set project PROJECT_ID
     ```
4. Enable the Service Health API in the project that you just created.

   ```
   gcloud services enable servicehealth.googleapis.com \
    --project PROJECT_ID
   ```

### Script

You can use a [script](https://docs.cloud.google.com/service-health/docs/script-enable-api.md.txt) to enable the
Service Health API for projects in your organization or folder.

> [!NOTE]
> **Note:** If you enable the Service Health API for the first time, recovery of events from the past 90 days can take up to 24 hours. To receive [impacted resource details (Preview)](https://docs.cloud.google.com/service-health/docs/concepts.md.txt#impacted-resources) for a project, the Service Health API must be enabled on the project at least 24 hours before an incident starts.

The Service Health API and alerts will recognize new events a few hours after
API enablement.