Service Metadata API - Package cloud.google.com/go/compute/metadata (v0.9.0)

Note: To get more information about this package, such as access to older versions, viewthis package on pkg.go.dev.

Package metadata provides access to Google Compute Engine (GCE)metadata and API service accounts.

This package is a wrapper around the GCE metadata service,as documented athttps://cloud.google.com/compute/docs/metadata/overview.

Functions

func Email (deprecated)

funcEmail(serviceAccountstring)(string,error)

Email calls Client.EmailWithContext on the default client.

Deprecated: Please use the context aware variant [EmailWithContext].

func EmailWithContext

funcEmailWithContext(ctxcontext.Context,serviceAccountstring)(string,error)

EmailWithContext calls Client.EmailWithContext on the default client.

func ExternalIP (deprecated)

funcExternalIP()(string,error)

ExternalIP returns the instance's primary external (public) IP address.

Deprecated: Please use the context aware variant [ExternalIPWithContext].

func ExternalIPWithContext

funcExternalIPWithContext(ctxcontext.Context)(string,error)

ExternalIPWithContext returns the instance's primary external (public) IP address.

func Get (deprecated)

funcGet(suffixstring)(string,error)

Get calls Client.GetWithContext on the default client.

Deprecated: Please use the context aware variant [GetWithContext].

func GetWithContext

funcGetWithContext(ctxcontext.Context,suffixstring)(string,error)

GetWithContext calls Client.GetWithContext on the default client.

func Hostname (deprecated)

funcHostname()(string,error)

Hostname returns the instance's hostname. This will be of the form"

Deprecated: Please use the context aware variant [HostnameWithContext].

func HostnameWithContext

funcHostnameWithContext(ctxcontext.Context)(string,error)

HostnameWithContext returns the instance's hostname. This will be of the form"

func InstanceAttributeValue (deprecated)

funcInstanceAttributeValue(attrstring)(string,error)

InstanceAttributeValue calls Client.InstanceAttributeValueWithContext on the default client.

Deprecated: Please use the context aware variant [InstanceAttributeValueWithContext].

func InstanceAttributeValueWithContext

funcInstanceAttributeValueWithContext(ctxcontext.Context,attrstring)(string,error)

InstanceAttributeValueWithContext calls Client.InstanceAttributeValueWithContext on the default client.

func InstanceAttributes (deprecated)

funcInstanceAttributes()([]string,error)

InstanceAttributes calls Client.InstanceAttributesWithContext on the default client.

Deprecated: Please use the context aware variant [InstanceAttributesWithContext.

func InstanceAttributesWithContext

funcInstanceAttributesWithContext(ctxcontext.Context)([]string,error)

InstanceAttributesWithContext calls Client.ProjectAttributesWithContext on the default client.

func InstanceID (deprecated)

funcInstanceID()(string,error)

InstanceID returns the current VM's numeric instance ID.

Deprecated: Please use the context aware variant [InstanceIDWithContext].

func InstanceIDWithContext

funcInstanceIDWithContext(ctxcontext.Context)(string,error)

InstanceIDWithContext returns the current VM's numeric instance ID.

func InstanceName (deprecated)

funcInstanceName()(string,error)

InstanceName returns the current VM's instance ID string.

Deprecated: Please use the context aware variant [InstanceNameWithContext].

func InstanceNameWithContext

funcInstanceNameWithContext(ctxcontext.Context)(string,error)

InstanceNameWithContext returns the current VM's instance ID string.

func InstanceTags (deprecated)

funcInstanceTags()([]string,error)

InstanceTags returns the list of user-defined instance tags,assigned when initially creating a GCE instance.

Deprecated: Please use the context aware variant [InstanceTagsWithContext].

func InstanceTagsWithContext

funcInstanceTagsWithContext(ctxcontext.Context)([]string,error)

InstanceTagsWithContext returns the list of user-defined instance tags,assigned when initially creating a GCE instance.

func InternalIP (deprecated)

funcInternalIP()(string,error)

InternalIP returns the instance's primary internal IP address.

Deprecated: Please use the context aware variant [InternalIPWithContext].

func InternalIPWithContext

funcInternalIPWithContext(ctxcontext.Context)(string,error)

InternalIPWithContext returns the instance's primary internal IP address.

func NumericProjectID (deprecated)

funcNumericProjectID()(string,error)

NumericProjectID returns the current instance's numeric project ID.

Deprecated: Please use the context aware variant [NumericProjectIDWithContext].

func NumericProjectIDWithContext

funcNumericProjectIDWithContext(ctxcontext.Context)(string,error)

NumericProjectIDWithContext returns the current instance's numeric project ID.

func OnGCE

funcOnGCE()bool

OnGCE reports whether this process is running on Google Compute Platforms.NOTE: True returned fromOnGCE does not guarantee that the metadata serveris accessible from this process and have all the metadata defined.

func OnGCEWithContext

funcOnGCEWithContext(ctxcontext.Context)bool

OnGCEWithContext reports whether this process is running on Google Compute Platforms.This function's return value is memoized for better performance.NOTE: True returned fromOnGCEWithContext does not guarantee that the metadata serveris accessible from this process and have all the metadata defined.

func ProjectAttributeValue (deprecated)

funcProjectAttributeValue(attrstring)(string,error)

ProjectAttributeValue calls Client.ProjectAttributeValueWithContext on the default client.

Deprecated: Please use the context aware variant [ProjectAttributeValueWithContext].

func ProjectAttributeValueWithContext

funcProjectAttributeValueWithContext(ctxcontext.Context,attrstring)(string,error)

ProjectAttributeValueWithContext calls Client.ProjectAttributeValueWithContext on the default client.

func ProjectAttributes (deprecated)

funcProjectAttributes()([]string,error)

ProjectAttributes calls Client.ProjectAttributesWithContext on the default client.

Deprecated: Please use the context aware variant [ProjectAttributesWithContext].

func ProjectAttributesWithContext

funcProjectAttributesWithContext(ctxcontext.Context)([]string,error)

ProjectAttributesWithContext calls Client.ProjectAttributesWithContext on the default client.

func ProjectID (deprecated)

funcProjectID()(string,error)

ProjectID returns the current instance's project ID string.

Deprecated: Please use the context aware variant [ProjectIDWithContext].

func ProjectIDWithContext

funcProjectIDWithContext(ctxcontext.Context)(string,error)

ProjectIDWithContext returns the current instance's project ID string.

func Scopes (deprecated)

funcScopes(serviceAccountstring)([]string,error)

Scopes calls Client.ScopesWithContext on the default client.

Deprecated: Please use the context aware variant [ScopesWithContext].

func ScopesWithContext

funcScopesWithContext(ctxcontext.Context,serviceAccountstring)([]string,error)

ScopesWithContext calls Client.ScopesWithContext on the default client.

func Subscribe (deprecated)

funcSubscribe(suffixstring,fnfunc(vstring,okbool)error)error

Subscribe calls Client.SubscribeWithContext on the default client.

Deprecated: Please use the context aware variant [SubscribeWithContext].

func SubscribeWithContext

funcSubscribeWithContext(ctxcontext.Context,suffixstring,fnfunc(ctxcontext.Context,vstring,okbool)error)error

SubscribeWithContext calls Client.SubscribeWithContext on the default client.

func Zone (deprecated)

funcZone()(string,error)

Zone returns the current VM's zone, such as "us-central1-b".

Deprecated: Please use the context aware variant [ZoneWithContext].

func ZoneWithContext

funcZoneWithContext(ctxcontext.Context)(string,error)

ZoneWithContext returns the current VM's zone, such as "us-central1-b".

Client

typeClientstruct{// contains filtered or unexported fields}

A Client provides metadata.

func NewClient

funcNewClient(c*http.Client)*Client

NewClient returns a Client that can be used to fetch metadata.Returns the client that uses the specified http.Client for HTTP requests.If nil is specified, returns the default internal Client that isalso used in functions such as GetWithContext. This is useful for sharinga single TCP connection pool across requests.

Example

packagemainimport("context""net/http""cloud.google.com/go/compute/metadata")// This example demonstrates how to use your own transport when using this package.funcmain(){ctx:=context.Background()c:=metadata.NewClient(&http.Client{Transport:userAgentTransport{userAgent:"my-user-agent",base:http.DefaultTransport,}})pID,err:=c.GetWithContext(ctx,"project/project-id")iferr!=nil{// TODO: Handle error.}_=pID// TODO: Use p.}// userAgentTransport sets the User-Agent header before calling base.typeuserAgentTransportstruct{userAgentstringbasehttp.RoundTripper}// RoundTrip implements the http.RoundTripper interface.func(tuserAgentTransport)RoundTrip(req*http.Request)(*http.Response,error){req.Header.Set("User-Agent",t.userAgent)returnt.base.RoundTrip(req)}

func NewWithOptions

funcNewWithOptions(opts*Options)*Client

NewWithOptions returns a Client that is configured with the provided Options.

func (*Client) Email (deprecated)

func(c*Client)Email(serviceAccountstring)(string,error)

Email returns the email address associated with the service account.

Deprecated: Please use the context aware variant [Client.EmailWithContext].

func (*Client) EmailWithContext

func(c*Client)EmailWithContext(ctxcontext.Context,serviceAccountstring)(string,error)

EmailWithContext returns the email address associated with the service account.The serviceAccount parameter default value (empty string or "default" value)will use the instance's main account.

func (*Client) ExternalIP (deprecated)

func(c*Client)ExternalIP()(string,error)

ExternalIP returns the instance's primary external (public) IP address.

Deprecated: Please use the context aware variant [Client.ExternalIPWithContext].

func (*Client) ExternalIPWithContext

func(c*Client)ExternalIPWithContext(ctxcontext.Context)(string,error)

ExternalIPWithContext returns the instance's primary external (public) IP address.

func (*Client) Get (deprecated)

func(c*Client)Get(suffixstring)(string,error)

Get returns a value from the metadata service.The suffix is appended to "http://${GCE_METADATA_HOST}/computeMetadata/v1/".

If the GCE_METADATA_HOST environment variable is not defined, a default of169.254.169.254 will be used instead.

If the requested metadata is not defined, the returned error willbe of type NotDefinedError.

Deprecated: Please use the context aware variant [Client.GetWithContext].

func (*Client) GetWithContext

func(c*Client)GetWithContext(ctxcontext.Context,suffixstring)(string,error)

GetWithContext returns a value from the metadata service.The suffix is appended to "http://${GCE_METADATA_HOST}/computeMetadata/v1/".

If the GCE_METADATA_HOST environment variable is not defined, a default of169.254.169.254 will be used instead.

If the requested metadata is not defined, the returned error willbe of type NotDefinedError.

NOTE: Without an extra deadline in the context this call can take in theworst case, with internal backoff retries, up to 15 seconds (e.g. when serveris responding slowly). Pass context with additional timeouts when needed.

func (*Client) Hostname (deprecated)

func(c*Client)Hostname()(string,error)

Hostname returns the instance's hostname. This will be of the form"

Deprecated: Please use the context aware variant [Client.HostnameWithContext].

func (*Client) HostnameWithContext

func(c*Client)HostnameWithContext(ctxcontext.Context)(string,error)

HostnameWithContext returns the instance's hostname. This will be of the form"

func (*Client) InstanceAttributeValue (deprecated)

func(c*Client)InstanceAttributeValue(attrstring)(string,error)

InstanceAttributeValue returns the value of the provided VMinstance attribute.

If the requested attribute is not defined, the returned error willbe of type NotDefinedError.

InstanceAttributeValue may return ("", nil) if the attribute wasdefined to be the empty string.

Deprecated: Please use the context aware variant [Client.InstanceAttributeValueWithContext].

func (*Client) InstanceAttributeValueWithContext

func(c*Client)InstanceAttributeValueWithContext(ctxcontext.Context,attrstring)(string,error)

InstanceAttributeValueWithContext returns the value of the provided VMinstance attribute.

If the requested attribute is not defined, the returned error willbe of type NotDefinedError.

InstanceAttributeValue may return ("", nil) if the attribute wasdefined to be the empty string.

func (*Client) InstanceAttributes (deprecated)

func(c*Client)InstanceAttributes()([]string,error)

InstanceAttributes returns the list of user-defined attributes,assigned when initially creating a GCE VM instance. The value of anattribute can be obtained with InstanceAttributeValue.

Deprecated: Please use the context aware variant [Client.InstanceAttributesWithContext].

func (*Client) InstanceAttributesWithContext

func(c*Client)InstanceAttributesWithContext(ctxcontext.Context)([]string,error)

InstanceAttributesWithContext returns the list of user-defined attributes,assigned when initially creating a GCE VM instance. The value of anattribute can be obtained with InstanceAttributeValue.

func (*Client) InstanceID (deprecated)

func(c*Client)InstanceID()(string,error)

InstanceID returns the current VM's numeric instance ID.

Deprecated: Please use the context aware variant [Client.InstanceIDWithContext].

func (*Client) InstanceIDWithContext

func(c*Client)InstanceIDWithContext(ctxcontext.Context)(string,error)

InstanceIDWithContext returns the current VM's numeric instance ID.

func (*Client) InstanceName (deprecated)

func(c*Client)InstanceName()(string,error)

InstanceName returns the current VM's instance ID string.

Deprecated: Please use the context aware variant [Client.InstanceNameWithContext].

func (*Client) InstanceNameWithContext

func(c*Client)InstanceNameWithContext(ctxcontext.Context)(string,error)

InstanceNameWithContext returns the current VM's instance ID string.

func (*Client) InstanceTags (deprecated)

func(c*Client)InstanceTags()([]string,error)

InstanceTags returns the list of user-defined instance tags.

Deprecated: Please use the context aware variant [Client.InstanceTagsWithContext].

func (*Client) InstanceTagsWithContext

func(c*Client)InstanceTagsWithContext(ctxcontext.Context)([]string,error)

InstanceTagsWithContext returns the list of user-defined instance tags,assigned when initially creating a GCE instance.

func (*Client) InternalIP (deprecated)

func(c*Client)InternalIP()(string,error)

InternalIP returns the instance's primary internal IP address.

Deprecated: Please use the context aware variant [Client.InternalIPWithContext].

func (*Client) InternalIPWithContext

func(c*Client)InternalIPWithContext(ctxcontext.Context)(string,error)

InternalIPWithContext returns the instance's primary internal IP address.

func (*Client) NumericProjectID (deprecated)

func(c*Client)NumericProjectID()(string,error)

NumericProjectID returns the current instance's numeric project ID.

Deprecated: Please use the context aware variant [Client.NumericProjectIDWithContext].

func (*Client) NumericProjectIDWithContext

func(c*Client)NumericProjectIDWithContext(ctxcontext.Context)(string,error)

NumericProjectIDWithContext returns the current instance's numeric project ID.

func (*Client) OnGCEWithContext

func(c*Client)OnGCEWithContext(ctxcontext.Context)bool

OnGCEWithContext reports whether this process is running on Google Compute Platforms.NOTE: True returned fromOnGCEWithContext does not guarantee that the metadata serveris accessible from this process and have all the metadata defined.

func (*Client) ProjectAttributeValue (deprecated)

func(c*Client)ProjectAttributeValue(attrstring)(string,error)

ProjectAttributeValue returns the value of the providedproject attribute.

If the requested attribute is not defined, the returned error willbe of type NotDefinedError.

ProjectAttributeValue may return ("", nil) if the attribute wasdefined to be the empty string.

Deprecated: Please use the context aware variant [Client.ProjectAttributeValueWithContext].

func (*Client) ProjectAttributeValueWithContext

func(c*Client)ProjectAttributeValueWithContext(ctxcontext.Context,attrstring)(string,error)

ProjectAttributeValueWithContext returns the value of the providedproject attribute.

If the requested attribute is not defined, the returned error willbe of type NotDefinedError.

ProjectAttributeValue may return ("", nil) if the attribute wasdefined to be the empty string.

func (*Client) ProjectAttributes (deprecated)

func(c*Client)ProjectAttributes()([]string,error)

ProjectAttributes returns the list of user-defined attributesapplying to the project as a whole, not just this VM. The value ofan attribute can be obtained with ProjectAttributeValue.

Deprecated: Please use the context aware variant [Client.ProjectAttributesWithContext].

func (*Client) ProjectAttributesWithContext

func(c*Client)ProjectAttributesWithContext(ctxcontext.Context)([]string,error)

ProjectAttributesWithContext returns the list of user-defined attributesapplying to the project as a whole, not just this VM. The value ofan attribute can be obtained with ProjectAttributeValue.

func (*Client) ProjectID (deprecated)

func(c*Client)ProjectID()(string,error)

ProjectID returns the current instance's project ID string.

Deprecated: Please use the context aware variant [Client.ProjectIDWithContext].

func (*Client) ProjectIDWithContext

func(c*Client)ProjectIDWithContext(ctxcontext.Context)(string,error)

ProjectIDWithContext returns the current instance's project ID string.

func (*Client) Scopes (deprecated)

func(c*Client)Scopes(serviceAccountstring)([]string,error)

Scopes returns the service account scopes for the given account.The account may be empty or the string "default" to use the instance'smain account.

Deprecated: Please use the context aware variant [Client.ScopesWithContext].

func (*Client) ScopesWithContext

func(c*Client)ScopesWithContext(ctxcontext.Context,serviceAccountstring)([]string,error)

ScopesWithContext returns the service account scopes for the given account.The account may be empty or the string "default" to use the instance'smain account.

func (*Client) Subscribe (deprecated)

func(c*Client)Subscribe(suffixstring,fnfunc(vstring,okbool)error)error

Subscribe subscribes to a value from the metadata service.The suffix is appended to "http://${GCE_METADATA_HOST}/computeMetadata/v1/".The suffix may contain query parameters.

Deprecated: Please use the context aware variant [Client.SubscribeWithContext].

func (*Client) SubscribeWithContext

func(c*Client)SubscribeWithContext(ctxcontext.Context,suffixstring,fnfunc(ctxcontext.Context,vstring,okbool)error)error

SubscribeWithContext subscribes to a value from the metadata service.The suffix is appended to "http://${GCE_METADATA_HOST}/computeMetadata/v1/".The suffix may contain query parameters.

SubscribeWithContext calls fn with the latest metadata value indicated by theprovided suffix. If the metadata value is deleted, fn is called with theempty string and ok false. Subscribe blocks until fn returns a non-nil erroror the value is deleted. Subscribe returns the error value returned from thelast call to fn, which may be nil when ok == false.

func (*Client) Zone (deprecated)

func(c*Client)Zone()(string,error)

Zone returns the current VM's zone, such as "us-central1-b".

Deprecated: Please use the context aware variant [Client.ZoneWithContext].

func (*Client) ZoneWithContext

func(c*Client)ZoneWithContext(ctxcontext.Context)(string,error)

ZoneWithContext returns the current VM's zone, such as "us-central1-b".

Error

typeErrorstruct{// Code is the HTTP response status code.Codeint// Message is the server response message.Messagestring}

Error contains an error response from the server.

func (*Error) Error

func(e*Error)Error()string

NotDefinedError

typeNotDefinedErrorstring

NotDefinedError is returned when requested metadata is not defined.

The underlying string is the suffix after "/computeMetadata/v1/".

This error is not returned if the value is defined to be the emptystring.

func (NotDefinedError) Error

func(suffixNotDefinedError)Error()string

Options

typeOptionsstruct{// Client is the HTTP client used to make requests. Optional.// If UseDefaultClient is true, this field is ignored.// If this field is nil, a new default http.Client will be created.Client*http.Client// Logger is used to log information about HTTP request and responses.// If not provided, nothing will be logged. Optional.Logger*slog.Logger// UseDefaultClient specifies that the client should use the same default// internal http.Client that is used in functions such as GetWithContext.// This is useful for sharing a single TCP connection pool across requests.// The difference vs GetWithContext is the ability to use this struct// to provide a custom logger. If this field is true, the Client// field is ignored.UseDefaultClientbool}

Options for configuring a [Client].

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-10-30 UTC.