Viewing References Between Resources

This page describes how view a list of resources that refer to a specific resource, such a particular VM instances.

The List Referrers API allows you to explore the relationships between resources in your project. You can make a listReferrers request to get a list of resources that refer to the resource in question, such as a virtual machine (VM) instance, or to get a list of resources within a scoped collection of resources, such as a list of referrers to all VM instances in a particular zone.

When you use this API, the server returns a list of references with a source (the resource referring to the resource in question), a target (the resource in question), and a reference type (the relationship between the target and source).

Before you begin

Limitations

  • You can only list relationships between VM instances and instance groups (both managed and unmanaged).
  • The API can only be used in the Compute Engine Beta API. It is not possible to list referrers using the gcloud tool, the Google Cloud Platform Console, or the V1 API.

Listing a single referrer

A referrer is a resource that refers to another resource. For VM instances, a common referrer is a instance group.

For example, assume that you have an instance named example-ig-a1 which lives in zone us-central1-a. The VM instance is a member of an instance group called example-ig which lives in the same zone, as shown in the diagram below:

To see this relationship, call the listReferrers method on example-ig-a1 with the following HTTP request:

GET https://www.googleapis.com/compute/beta/projects/myproject/zones/us-central1-a/instances/example-ig-a1/referrers

The server returns standard list response containing the following items:

"items": [
  {
    "target": https://www.googleapis.com/compute/beta/projects/myproject/zones/us-central1-a/instances/example-ig-a1,
    "referenceType": MEMBER_OF,
    "referrer": https://www.googleapis.com/compute/beta/projects/myproject/zones/us-central1-a/instanceGroups/example-ig
  }
]

In this case, the target is example-ig-a1, which is a MEMBER_OF the referrer, the example-ig instance group.

Listing multiple referrers

If a resource has more than one referrer, the response will return a list of all referrers for the target resource. If an instance belongs to two instance groups, the API returns a list that contains both instance groups.

For example, the following response indicates that the instance named example-instance-a2 belongs to two instance groups, example-ig and example-ig-2:

"items": [
  {
    "target": https://www.googleapis.com/compute/beta/projects/myproject/zones/us-central1-a/instances/example-instance-a2,
    "referenceType": MEMBER_OF,
    "referrer": https://www.googleapis.com/compute/beta/projects/myproject/zones/us-central1-a/instanceGroups/example-ig
  },
  {
    "target": https://www.googleapis.com/compute/beta/projects/myproject/zones/us-central1-a/instances/example-instance-a2,
    "referenceType": MEMBER_OF,
    "referrer": https://www.googleapis.com/compute/beta/projects/myproject/zones/us-central1-a/instanceGroups/example-ig-2
  }
]

Listing cross-scope referrers

The listReferrers method also returns information about referrers that exist inside other scopes, such as other regions or zones. For example, assume that you have a VM instance that belongs to a regional managed instance group:

You call the listReferrers method targeting this instance with the following HTTP request:

GET https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/new-instance-a3/referrers

The server returns a standard list response containing the following items:

"items": [
  {
    "target": https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/new-instance-a3,
    "referenceType": MEMBER_OF,
    "referrer": https://www.googleapis.com/compute/v1/projects/myproject/regions/us-central1/instanceGroups/example-rig
  }
]

The response contains the regional managed instance group in the list of referrers.

Listing referrers to all resources within a collection

You do not need to make separate API calls for each of the instances in a zone. By using the wildcard character (-), you can request a list of all referrers to all VM instances within the specified zone. The request can be made with an HTTP request that is similar to the following:

GET https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/-/referrers

The server returns a response containing a list of VM instances in the zone and references to the instance. For example:

"items": [
  {
    "target": https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-ig-a1,
    "referenceType": MEMBER_OF,
    "referrer": https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instanceGroups/example-ig
  },
  {
    "target": https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-ig-a2,
    "referenceType": MEMBER_OF,
    "referrer": https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instanceGroups/example-ig
  },
  {
    "target": https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-ig-a2,
    "referenceType": MEMBER_OF,
    "referrer": https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instanceGroups/example-ig-2
  },
  {
    "target": https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/new-instance-a3,
    "referenceType": MEMBER_OF,
    "referrer": https://www.googleapis.com/compute/v1/projects/myproject/regions/us-central1/instanceGroups/example-rig
  }
]

What's next

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Compute Engine Documentation