If you want to view the relationships between VM instances and other
Compute Engine resources, use the listReferrers
REST API method
.
When you use REST, 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 REST to conveniently view a list of instance groups that a VM instance belongs to.
Before you begin
- If you haven't already, set up authentication
.
Authentication verifies your identity for access to Google Cloud services and APIs. To run
code or samples from a local development environment, you can authenticate to
Compute Engine by selecting one of the following options:
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:
gcloud init
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
Limitations
- You can only list relationships between VM instances and instance groups (both managed and unmanaged).
- You can only list referrers by using REST.
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:
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.
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):
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
- Learn more about instance groups .
- See a list of applicable zones and regions .
