Viewing referrers to VM instances

Stay organized with collections Save and categorize content based on your preferences.

If you want to view the relationships between VM instances and other Compute Engine resources, use the listReferrers API method.

When you use this API method, Compute Engine returns a list of references that describe:

  • The source resource: the resource that is pointing to the target resource
  • The target resource: the resource in question
  • The reference type: the relationship between the two resources

For example, you can use this API to conveniently view a list of instance groups that a VM instance belongs to.

Before you begin

Limitations

  • You can only list relationships between VM instances and instance groups (both managed and unmanaged).
  • You can only list referrers by using the API.

Listing a single referrer

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

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

A virtual machine instance is a member of an instance group in the same zone.

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

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

The server returns standard list response containing the following items:

"items": [
  {
    "target": https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-ig-a1,
    "referenceType": MEMBER_OF,
    "referrer": https://compute.googleapis.com/compute/v1/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 returns a list of all referrers for the target resource. If an instance belongs to two instance groups, the response contains both instance groups.

If a virtual machine instance is a member of two instance groups, the response 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://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance-a2,
    "referenceType": MEMBER_OF,
    "referrer": https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instanceGroups/example-ig
  },
  {
    "target": https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance-a2,
    "referenceType": MEMBER_OF,
    "referrer": https://compute.googleapis.com/compute/v1/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 (regional MIG):

In region us-central1, instance new-instance-a3 in zone us-central1-a is a member of the example-rmig regional instance group.

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

GET https://compute.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://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/new-instance-a3,
    "referenceType": MEMBER_OF,
    "referrer": https://compute.googleapis.com/compute/v1/projects/myproject/regions/us-central1/instanceGroups/example-rmig
  }
]

The response shows the regional instance group in the list of referrers.

Listing referrers to all resources within a collection

By using the wildcard character (-), you can request a list of all referrers to all VM instances within a specific zone. The request can be made with an HTTP request that is similar to the following:

GET https://compute.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://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-ig-a1,
    "referenceType": MEMBER_OF,
    "referrer": https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instanceGroups/example-ig
  },
  {
    "target": https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-ig-a2,
    "referenceType": MEMBER_OF,
    "referrer": https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instanceGroups/example-ig
  },
  {
    "target": https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-ig-a2,
    "referenceType": MEMBER_OF,
    "referrer": https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instanceGroups/example-ig-2
  },
  {
    "target": https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/new-instance-a3,
    "referenceType": MEMBER_OF,
    "referrer": https://compute.googleapis.com/compute/v1/projects/myproject/regions/us-central1/instanceGroups/example-rmig
  }
]

What's next