Manage events affecting an organization

This document explains how-tos for using the Service Health API to manage events affecting your organization.

Personalized Service Health provides the OrganizationEvents and OrganizationImpacts API resources, which let you get information on events that affect your organization. This information includes:

  • Service health events that may impact one or more projects in an organization.
  • List of projects that may be or are impacted by an event affecting your organization.

The API resources don't get all events that affect an organization, nor have them appear in the Service Health dashboard.

Before you begin

  1. Enable the Service Health API for at least one project under your organization. The OrganizationEvents and OrganizationImpacts API resources get information only for projects that have the Service Health API enabled.
  2. Set permissions to access the Service Health API.

  3. Configure Identity and Access Management (IAM) permissions on your organization to use the OrganizationEvents and OrganizationImpacts API resources. Run the following command: 

    gcloud organizations add-iam-policy-binding $ORGANIZATION_ID \
  --member {USER|GROUP|SERVICE_ACCOUNT} \
  --role roles/servicehealth.viewer

    To get your ORGANIZATION_ID, see Getting your organization resource ID.

    The IAM policies granted on an organization are inherited by all projects in the organization. These policies allow you to access organization and project event APIs across the organization.

References

See the OrganizationEvents and OrganizationImpacts API reference for the methods you can use, and the meaning of the fields in the response.

When setting the product or location, use the values found at Google Cloud products and locations.

List projects under an organization that may be affected by an event

See the quickstart.

List all active incidents for an organization

See the quickstart.

Get details for an event affecting an organization

You can use the Get API to view detailed information about an event affecting an organization.

Before using any of the request data, make the following replacements:

  • API_VERSION: The API version to use. Use v1 or v1beta.
  • ORGANIZATION_ID: your Google Cloud organization ID.

HTTP method and URL: 

GET https://servicehealth.googleapis.com/API VERSION/organizations/ORGANIZATION_ID/locations/global/organizationEvents/EVENT_ID

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "organizations/ORGANIZATION_ID/locations/global/organizationEvents/EVENT_ID",
     "title": "We are experiencing a connectivity issue affecting Google Cloud SQL in us-east1, australia-southeast2.",
      "description": "The issue with Google Cloud SQL has been resolved for all affected projects as of Tuesday, 2022-10-18 11:00 US/Pacific. We thank you for your patience while we worked on resolving the issue.",
      "category": "INCIDENT",
      "detailedCategory": "CONFIRMED_INCIDENT",
      "state": "CLOSED",
      "detailedState": "RESOLVED",
      "eventImpacts": [
        {
          "product": {
            "productName": "Google Cloud SQL",
          },
          "location": {
            "locationName": "us-central1",
          }
        }
      ],
   "updates": [
    {
      "updateTime": "2022-10-18T17:41:20.112287Z",
              "title": "We are experiencing a connectivity issue affecting Google Cloud SQL in us-east1, australia-southeast2.",
      "description": "We are experiencing an intermittent issue with Google Cloud SQL. Our engineering team continues to investigate the issue.",
      "symptom": "None at this time.",
      "workaround": "None at this time."
    },
    {
      "updateTime": "2022-10-18T18:00:05.690761Z",
      "title": "We are experiencing a connectivity issue affecting Google Cloud SQL in us-east1, australia-southeast2.",
      "description": "The issue with Google Cloud SQL has been resolved for all affected projects as of Tuesday, 2022-10-18 11:00 US/Pacific.\n\nWe thank you for your patience while we worked on resolving the issue.",
      "symptom": "None at this time.",
      "workaround": "None at this time."
    }
  ],
  "updateTime": "2022-10-18T18:00:05.690761Z",
  "startTime": "2022-10-18T17:41:20.112287Z",
  "endTime":  "2022-10-18T18:00:05.690761Z",
}

If you don't have permissions to get events, you will get the following PERMISSION_DENIED error.

{
  "error": {
    "code": 403,
    "message": "Permission 'servicehealth.organizationEvents.get' denied on resource '//servicehealth.googleapis.com/organizations/ORGANIZATION_ID/locations/global/organizationEvents/EVENT_ID' (or it may not exist).",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "IAM_PERMISSION_DENIED",
        "domain": "servicehealth.googleapis.com",
        "metadata": {
          "resource": "organizations/ORGANIZATION_ID/locations/global/organizationEvents/EVENT_ID",
          "permission": "servicehealth.organizationEvents.get"
        }
      }
    ]
  }
}

To fix this error, set the required permissions.

Get details for a project under an organization that may be affected by an event

For a given event, the event ID remains the same between your project and organization events. OrganizationImpact contains an EVENT_ID and a PROJECT_NUMBER, which you can use to get details for an event affecting your project. These details include state and relevance.

PROJECT_NUMBER is interchangeable with PROJECT_ID, which the Get API returns.