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 at https://cloud.google.com/compute/docs/metadata/overview .
Functions
func Email (deprecated)
Email calls Client.EmailWithContext on the default client.
Deprecated: Please use the context aware variant [EmailWithContext].
func EmailWithContext
EmailWithContext calls Client.EmailWithContext on the default client.
func ExternalIP (deprecated)
ExternalIP returns the instance's primary external (public) IP address.
Deprecated: Please use the context aware variant [ExternalIPWithContext].
func ExternalIPWithContext
ExternalIPWithContext returns the instance's primary external (public) IP address.
func Get (deprecated)
Get calls Client.GetWithContext on the default client.
Deprecated: Please use the context aware variant [GetWithContext].
func GetWithContext
GetWithContext calls Client.GetWithContext on the default client.
func Hostname (deprecated)
Hostname returns the instance's hostname. This will be of the form "
Deprecated: Please use the context aware variant [HostnameWithContext].
func HostnameWithContext
HostnameWithContext returns the instance's hostname. This will be of the form "
func InstanceAttributeValue (deprecated)
InstanceAttributeValue calls Client.InstanceAttributeValueWithContext on the default client.
Deprecated: Please use the context aware variant [InstanceAttributeValueWithContext].
func InstanceAttributeValueWithContext
InstanceAttributeValueWithContext calls Client.InstanceAttributeValueWithContext on the default client.
func InstanceAttributes (deprecated)
InstanceAttributes calls Client.InstanceAttributesWithContext on the default client.
Deprecated: Please use the context aware variant [InstanceAttributesWithContext.
func InstanceAttributesWithContext
InstanceAttributesWithContext calls Client.ProjectAttributesWithContext on the default client.
func InstanceID (deprecated)
InstanceID returns the current VM's numeric instance ID.
Deprecated: Please use the context aware variant [InstanceIDWithContext].
func InstanceIDWithContext
InstanceIDWithContext returns the current VM's numeric instance ID.
func InstanceName (deprecated)
InstanceName returns the current VM's instance ID string.
Deprecated: Please use the context aware variant [InstanceNameWithContext].
func InstanceNameWithContext
InstanceNameWithContext returns the current VM's instance ID string.
func InstanceTags (deprecated)
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
InstanceTagsWithContext returns the list of user-defined instance tags, assigned when initially creating a GCE instance.
func InternalIP (deprecated)
InternalIP returns the instance's primary internal IP address.
Deprecated: Please use the context aware variant [InternalIPWithContext].
func InternalIPWithContext
InternalIPWithContext returns the instance's primary internal IP address.
func NumericProjectID (deprecated)
NumericProjectID returns the current instance's numeric project ID.
Deprecated: Please use the context aware variant [NumericProjectIDWithContext].
func NumericProjectIDWithContext
NumericProjectIDWithContext returns the current instance's numeric project ID.
func OnGCE
func
OnGCE
()
bool
OnGCE reports whether this process is running on Google Compute Platforms.
NOTE: True returned from OnGCE
does not guarantee that the metadata server
is accessible from this process and have all the metadata defined.
func ProjectAttributeValue (deprecated)
ProjectAttributeValue calls Client.ProjectAttributeValueWithContext on the default client.
Deprecated: Please use the context aware variant [ProjectAttributeValueWithContext].
func ProjectAttributeValueWithContext
ProjectAttributeValueWithContext calls Client.ProjectAttributeValueWithContext on the default client.
func ProjectAttributes (deprecated)
ProjectAttributes calls Client.ProjectAttributesWithContext on the default client.
Deprecated: Please use the context aware variant [ProjectAttributesWithContext].
func ProjectAttributesWithContext
ProjectAttributesWithContext calls Client.ProjectAttributesWithContext on the default client.
func ProjectID (deprecated)
ProjectID returns the current instance's project ID string.
Deprecated: Please use the context aware variant [ProjectIDWithContext].
func ProjectIDWithContext
ProjectIDWithContext returns the current instance's project ID string.
func Scopes (deprecated)
Scopes calls Client.ScopesWithContext on the default client.
Deprecated: Please use the context aware variant [ScopesWithContext].
func ScopesWithContext
ScopesWithContext calls Client.ScopesWithContext on the default client.
func Subscribe (deprecated)
Subscribe calls Client.SubscribeWithContext on the default client.
Deprecated: Please use the context aware variant [SubscribeWithContext].
func SubscribeWithContext
func
SubscribeWithContext
(
ctx
context
.
Context
,
suffix
string
,
fn
func
(
ctx
context
.
Context
,
v
string
,
ok
bool
)
error
)
error
SubscribeWithContext calls Client.SubscribeWithContext on the default client.
func Zone (deprecated)
Zone returns the current VM's zone, such as "us-central1-b".
Deprecated: Please use the context aware variant [ZoneWithContext].
func ZoneWithContext
ZoneWithContext returns the current VM's zone, such as "us-central1-b".
Client
type
Client
struct
{
// contains filtered or unexported fields
}
A Client provides metadata.
func NewClient
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 client.
Example
package
main
import
(
"context"
"net/http"
"cloud.google.com/go/compute/metadata"
)
// This example demonstrates how to use your own transport when using this package.
func
main
()
{
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"
)
if
err
!=
nil
{
// TODO: Handle error.
}
_
=
pID
// TODO: Use p.
}
// userAgentTransport sets the User-Agent header before calling base.
type
userAgentTransport
struct
{
userAgent
string
base
http
.
RoundTripper
}
// RoundTrip implements the http.RoundTripper interface.
func
(
t
userAgentTransport
)
RoundTrip
(
req
*
http
.
Request
)
(
*
http
.
Response
,
error
)
{
req
.
Header
.
Set
(
"User-Agent"
,
t
.
userAgent
)
return
t
.
base
.
RoundTrip
(
req
)
}
func NewWithOptions
NewWithOptions returns a Client that is configured with the provided Options.
func (*Client) Email (deprecated)
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
(
ctx
context
.
Context
,
serviceAccount
string
)
(
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)
ExternalIP returns the instance's primary external (public) IP address.
Deprecated: Please use the context aware variant [Client.ExternalIPWithContext].
func (*Client) ExternalIPWithContext
ExternalIPWithContext returns the instance's primary external (public) IP address.
func (*Client) Get (deprecated)
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 of 169.254.169.254 will be used instead.
If the requested metadata is not defined, the returned error will be of type NotDefinedError.
Deprecated: Please use the context aware variant [Client.GetWithContext].
func (*Client) GetWithContext
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 of 169.254.169.254 will be used instead.
If the requested metadata is not defined, the returned error will be of type NotDefinedError.
NOTE: Without an extra deadline in the context this call can take in the worst case, with internal backoff retries, up to 15 seconds (e.g. when server is responding slowly). Pass context with additional timeouts when needed.
func (*Client) Hostname (deprecated)
Hostname returns the instance's hostname. This will be of the form "
Deprecated: Please use the context aware variant [Client.HostnameWithContext].
func (*Client) HostnameWithContext
HostnameWithContext returns the instance's hostname. This will be of the form "
func (*Client) InstanceAttributeValue (deprecated)
InstanceAttributeValue returns the value of the provided VM instance attribute.
If the requested attribute is not defined, the returned error will be of type NotDefinedError.
InstanceAttributeValue may return ("", nil) if the attribute was defined to be the empty string.
Deprecated: Please use the context aware variant [Client.InstanceAttributeValueWithContext].
func (*Client) InstanceAttributeValueWithContext
func
(
c
*
Client
)
InstanceAttributeValueWithContext
(
ctx
context
.
Context
,
attr
string
)
(
string
,
error
)
InstanceAttributeValueWithContext returns the value of the provided VM instance attribute.
If the requested attribute is not defined, the returned error will be of type NotDefinedError.
InstanceAttributeValue may return ("", nil) if the attribute was defined to be the empty string.
func (*Client) InstanceAttributes (deprecated)
InstanceAttributes returns the list of user-defined attributes, assigned when initially creating a GCE VM instance. The value of an attribute can be obtained with InstanceAttributeValue.
Deprecated: Please use the context aware variant [Client.InstanceAttributesWithContext].
func (*Client) InstanceAttributesWithContext
InstanceAttributesWithContext returns the list of user-defined attributes, assigned when initially creating a GCE VM instance. The value of an attribute can be obtained with InstanceAttributeValue.
func (*Client) InstanceID (deprecated)
InstanceID returns the current VM's numeric instance ID.
Deprecated: Please use the context aware variant [Client.InstanceIDWithContext].
func (*Client) InstanceIDWithContext
InstanceIDWithContext returns the current VM's numeric instance ID.
func (*Client) InstanceName (deprecated)
InstanceName returns the current VM's instance ID string.
Deprecated: Please use the context aware variant [Client.InstanceNameWithContext].
func (*Client) InstanceNameWithContext
InstanceNameWithContext returns the current VM's instance ID string.
func (*Client) InstanceTags (deprecated)
InstanceTags returns the list of user-defined instance tags.
Deprecated: Please use the context aware variant [Client.InstanceTagsWithContext].
func (*Client) InstanceTagsWithContext
InstanceTagsWithContext returns the list of user-defined instance tags, assigned when initially creating a GCE instance.
func (*Client) InternalIP (deprecated)
InternalIP returns the instance's primary internal IP address.
Deprecated: Please use the context aware variant [Client.InternalIPWithContext].
func (*Client) InternalIPWithContext
InternalIPWithContext returns the instance's primary internal IP address.
func (*Client) NumericProjectID (deprecated)
NumericProjectID returns the current instance's numeric project ID.
Deprecated: Please use the context aware variant [Client.NumericProjectIDWithContext].
func (*Client) NumericProjectIDWithContext
NumericProjectIDWithContext returns the current instance's numeric project ID.
func (*Client) ProjectAttributeValue (deprecated)
ProjectAttributeValue returns the value of the provided project attribute.
If the requested attribute is not defined, the returned error will be of type NotDefinedError.
ProjectAttributeValue may return ("", nil) if the attribute was defined to be the empty string.
Deprecated: Please use the context aware variant [Client.ProjectAttributeValueWithContext].
func (*Client) ProjectAttributeValueWithContext
func
(
c
*
Client
)
ProjectAttributeValueWithContext
(
ctx
context
.
Context
,
attr
string
)
(
string
,
error
)
ProjectAttributeValueWithContext returns the value of the provided project attribute.
If the requested attribute is not defined, the returned error will be of type NotDefinedError.
ProjectAttributeValue may return ("", nil) if the attribute was defined to be the empty string.
func (*Client) ProjectAttributes (deprecated)
ProjectAttributes returns the list of user-defined attributes applying to the project as a whole, not just this VM. The value of an attribute can be obtained with ProjectAttributeValue.
Deprecated: Please use the context aware variant [Client.ProjectAttributesWithContext].
func (*Client) ProjectAttributesWithContext
ProjectAttributesWithContext returns the list of user-defined attributes applying to the project as a whole, not just this VM. The value of an attribute can be obtained with ProjectAttributeValue.
func (*Client) ProjectID (deprecated)
ProjectID returns the current instance's project ID string.
Deprecated: Please use the context aware variant [Client.ProjectIDWithContext].
func (*Client) ProjectIDWithContext
ProjectIDWithContext returns the current instance's project ID string.
func (*Client) Scopes (deprecated)
Scopes returns the service account scopes for the given account. The account may be empty or the string "default" to use the instance's main account.
Deprecated: Please use the context aware variant [Client.ScopesWithContext].
func (*Client) ScopesWithContext
func
(
c
*
Client
)
ScopesWithContext
(
ctx
context
.
Context
,
serviceAccount
string
)
([]
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's main account.
func (*Client) Subscribe (deprecated)
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
(
ctx
context
.
Context
,
suffix
string
,
fn
func
(
ctx
context
.
Context
,
v
string
,
ok
bool
)
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 the provided suffix. If the metadata value is deleted, fn is called with the empty string and ok false. Subscribe blocks until fn returns a non-nil error or the value is deleted. Subscribe returns the error value returned from the last call to fn, which may be nil when ok == false.
func (*Client) Zone (deprecated)
Zone returns the current VM's zone, such as "us-central1-b".
Deprecated: Please use the context aware variant [Client.ZoneWithContext].
func (*Client) ZoneWithContext
ZoneWithContext returns the current VM's zone, such as "us-central1-b".
Error
type
Error
struct
{
// Code is the HTTP response status code.
Code
int
// Message is the server response message.
Message
string
}
Error contains an error response from the server.
func (*Error) Error
NotDefinedError
type
NotDefinedError
string
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 empty string.
func (NotDefinedError) Error
func
(
suffix
NotDefinedError
)
Error
()
string
Options
type
Options
struct
{
// Client is the HTTP client used to make requests. Optional.
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
}
Options for configuring a [Client].
