metadata

package module
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 13, 2024 License: Apache-2.0 Imports: 16 Imported by: 2,015

README

Compute API

Go Reference

This is a utility library for communicating with Google Cloud metadata service on Google Cloud.

Install

go get cloud.google.com/go/compute/metadata

Go Version Support

See the Go Versions Supported section in the root directory's README.

Contributing

Contributions are welcome. Please, see the CONTRIBUTING document for details.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See Contributor Code of Conduct for more information.

Documentation

Overview

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.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Email deprecated 

func Email(serviceAccount string) (string, error)

Email calls Client.EmailWithContext on the default client.

Deprecated: Please use the context aware variant EmailWithContext.

func EmailWithContext added in v0.4.0 

func EmailWithContext(ctx context.Context, serviceAccount string) (string, error)

EmailWithContext calls Client.EmailWithContext on the default client.

func ExternalIP deprecated 

func ExternalIP() (string, error)

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

Deprecated: Please use the context aware variant ExternalIPWithContext.

func ExternalIPWithContext added in v0.4.0 

func ExternalIPWithContext(ctx context.Context) (string, error)

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

func Get deprecated 

func Get(suffix string) (string, error)

Get calls Client.GetWithContext on the default client.

Deprecated: Please use the context aware variant GetWithContext.

func GetWithContext added in v0.3.0 

func GetWithContext(ctx context.Context, suffix string) (string, error)

GetWithContext calls Client.GetWithContext on the default client.

func Hostname deprecated 

func Hostname() (string, error)

Hostname returns the instance's hostname. This will be of the form "<instanceID>.c.<projID>.internal".

Deprecated: Please use the context aware variant HostnameWithContext.

func HostnameWithContext added in v0.4.0 

func HostnameWithContext(ctx context.Context) (string, error)

HostnameWithContext returns the instance's hostname. This will be of the form "<instanceID>.c.<projID>.internal".

func InstanceAttributeValue deprecated 

func InstanceAttributeValue(attr string) (string, error)

InstanceAttributeValue calls Client.InstanceAttributeValueWithContext on the default client.

Deprecated: Please use the context aware variant InstanceAttributeValueWithContext.

func InstanceAttributeValueWithContext added in v0.4.0 

func InstanceAttributeValueWithContext(ctx context.Context, attr string) (string, error)

InstanceAttributeValueWithContext calls Client.InstanceAttributeValueWithContext on the default client.

func InstanceAttributes deprecated 

func InstanceAttributes() ([]string, error)

InstanceAttributes calls Client.InstanceAttributesWithContext on the default client.

Deprecated: Please use the context aware variant [InstanceAttributesWithContext.

func InstanceAttributesWithContext added in v0.4.0 

func InstanceAttributesWithContext(ctx context.Context) ([]string, error)

InstanceAttributesWithContext calls Client.ProjectAttributesWithContext on the default client.

func InstanceID deprecated 

func InstanceID() (string, error)

InstanceID returns the current VM's numeric instance ID.

Deprecated: Please use the context aware variant InstanceIDWithContext.

func InstanceIDWithContext added in v0.4.0 

func InstanceIDWithContext(ctx context.Context) (string, error)

InstanceIDWithContext returns the current VM's numeric instance ID.

func InstanceName deprecated 

func InstanceName() (string, error)

InstanceName returns the current VM's instance ID string.

Deprecated: Please use the context aware variant InstanceNameWithContext.

func InstanceNameWithContext added in v0.4.0 

func InstanceNameWithContext(ctx context.Context) (string, error)

InstanceNameWithContext returns the current VM's instance ID string.

func InstanceTags deprecated 

func InstanceTags() ([]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 added in v0.4.0 

func InstanceTagsWithContext(ctx context.Context) ([]string, error)

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

func InternalIP deprecated 

func InternalIP() (string, error)

InternalIP returns the instance's primary internal IP address.

Deprecated: Please use the context aware variant InternalIPWithContext.

func InternalIPWithContext added in v0.4.0 

func InternalIPWithContext(ctx context.Context) (string, error)

InternalIPWithContext returns the instance's primary internal IP address.

func NumericProjectID deprecated 

func NumericProjectID() (string, error)

NumericProjectID returns the current instance's numeric project ID.

Deprecated: Please use the context aware variant NumericProjectIDWithContext.

func NumericProjectIDWithContext added in v0.4.0 

func NumericProjectIDWithContext(ctx context.Context) (string, error)

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 

func ProjectAttributeValue(attr string) (string, error)

ProjectAttributeValue calls Client.ProjectAttributeValueWithContext on the default client.

Deprecated: Please use the context aware variant ProjectAttributeValueWithContext.

func ProjectAttributeValueWithContext added in v0.4.0 

func ProjectAttributeValueWithContext(ctx context.Context, attr string) (string, error)

ProjectAttributeValueWithContext calls Client.ProjectAttributeValueWithContext on the default client.

func ProjectAttributes deprecated 

func ProjectAttributes() ([]string, error)

ProjectAttributes calls Client.ProjectAttributesWithContext on the default client.

Deprecated: Please use the context aware variant ProjectAttributesWithContext.

func ProjectAttributesWithContext added in v0.4.0 

func ProjectAttributesWithContext(ctx context.Context) ([]string, error)

ProjectAttributesWithContext calls Client.ProjectAttributesWithContext on the default client.

func ProjectID deprecated 

func ProjectID() (string, error)

ProjectID returns the current instance's project ID string.

Deprecated: Please use the context aware variant ProjectIDWithContext.

func ProjectIDWithContext added in v0.4.0 

func ProjectIDWithContext(ctx context.Context) (string, error)

ProjectIDWithContext returns the current instance's project ID string.

func Scopes deprecated 

func Scopes(serviceAccount string) ([]string, error)

Scopes calls Client.ScopesWithContext on the default client.

Deprecated: Please use the context aware variant ScopesWithContext.

func ScopesWithContext added in v0.4.0 

func ScopesWithContext(ctx context.Context, serviceAccount string) ([]string, error)

ScopesWithContext calls Client.ScopesWithContext on the default client.

func Subscribe deprecated 

func Subscribe(suffix string, fn func(v string, ok bool) error) error

Subscribe calls Client.SubscribeWithContext on the default client.

Deprecated: Please use the context aware variant SubscribeWithContext.

func SubscribeWithContext added in v0.3.0 

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 

func Zone() (string, error)

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

Deprecated: Please use the context aware variant ZoneWithContext.

func ZoneWithContext added in v0.4.0 

func ZoneWithContext(ctx context.Context) (string, error)

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

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

A Client provides metadata.

func NewClient 

func NewClient(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 client.

Example

This example demonstrates how to use your own transport when using this package. 

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)
}

Output:

func NewWithOptions added in v0.6.0 

func NewWithOptions(opts *Options) *Client

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

func (*Client) Email deprecated 

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

Email returns the email address associated with the service account.

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

func (*Client) EmailWithContext added in v0.4.0 

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 

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 added in v0.4.0 

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

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

func (*Client) Get deprecated 

func (c *Client) Get(suffix string) (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 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 added in v0.3.0 

func (c *Client) GetWithContext(ctx context.Context, suffix string) (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 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 

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

Hostname returns the instance's hostname. This will be of the form "<instanceID>.c.<projID>.internal".

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

func (*Client) HostnameWithContext added in v0.4.0 

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

HostnameWithContext returns the instance's hostname. This will be of the form "<instanceID>.c.<projID>.internal".

func (*Client) InstanceAttributeValue deprecated 

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

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 added in v0.4.0 

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 

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 an attribute can be obtained with InstanceAttributeValue.

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

func (*Client) InstanceAttributesWithContext added in v0.4.0 

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

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 

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 added in v0.4.0 

func (c *Client) InstanceIDWithContext(ctx context.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 added in v0.4.0 

func (c *Client) InstanceNameWithContext(ctx context.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 added in v0.4.0 

func (c *Client) InstanceTagsWithContext(ctx context.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 added in v0.4.0 

func (c *Client) InternalIPWithContext(ctx context.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 added in v0.4.0 

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

NumericProjectIDWithContext returns the current instance's numeric project ID.

func (*Client) ProjectAttributeValue deprecated 

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

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 added in v0.4.0 

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 

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

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 added in v0.4.0 

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

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 

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 added in v0.4.0 

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

ProjectIDWithContext returns the current instance's project ID string.

func (*Client) Scopes deprecated 

func (c *Client) Scopes(serviceAccount string) ([]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's main account.

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

func (*Client) ScopesWithContext added in v0.4.0 

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 

func (c *Client) Subscribe(suffix string, fn func(v string, ok bool) 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 added in v0.3.0 

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 

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 added in v0.4.0 

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

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

type 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 

func (e *Error) Error() string

type 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

type Options added in v0.6.0 

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.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.