...
▽

Package metadata

import "cloud.google.com/go/compute/metadata"
Overview
Index
Examples
Subdirectories

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 ▾

func Email(serviceAccount string) (string, error)
func ExternalIP() (string, error)
func Get(suffix string) (string, error)
func GetWithContext(ctx context.Context, suffix string) (string, error)
func Hostname() (string, error)
func InstanceAttributeValue(attr string) (string, error)
func InstanceAttributes() ([]string, error)
func InstanceID() (string, error)
func InstanceName() (string, error)
func InstanceTags() ([]string, error)
func InternalIP() (string, error)
func NumericProjectID() (string, error)
func OnGCE() bool
func ProjectAttributeValue(attr string) (string, error)
func ProjectAttributes() ([]string, error)
func ProjectID() (string, error)
func Scopes(serviceAccount string) ([]string, error)
func Subscribe(suffix string, fn func(v string, ok bool) error) error
func SubscribeWithContext(ctx context.Context, suffix string, fn func(ctx context.Context, v string, ok bool) error) error
func Zone() (string, error)
type Client
    func NewClient(c *http.Client) *Client
    func (c *Client) Email(serviceAccount string) (string, error)
    func (c *Client) ExternalIP() (string, error)
    func (c *Client) Get(suffix string) (string, error)
    func (c *Client) GetWithContext(ctx context.Context, suffix string) (string, error)
    func (c *Client) Hostname() (string, error)
    func (c *Client) InstanceAttributeValue(attr string) (string, error)
    func (c *Client) InstanceAttributes() ([]string, error)
    func (c *Client) InstanceID() (string, error)
    func (c *Client) InstanceName() (string, error)
    func (c *Client) InstanceTags() ([]string, error)
    func (c *Client) InternalIP() (string, error)
    func (c *Client) NumericProjectID() (string, error)
    func (c *Client) ProjectAttributeValue(attr string) (string, error)
    func (c *Client) ProjectAttributes() ([]string, error)
    func (c *Client) ProjectID() (string, error)
    func (c *Client) Scopes(serviceAccount string) ([]string, error)
    func (c *Client) Subscribe(suffix string, fn func(v string, ok bool) error) error
    func (c *Client) SubscribeWithContext(ctx context.Context, suffix string, fn func(ctx context.Context, v string, ok bool) error) error
    func (c *Client) Zone() (string, error)
type Error
    func (e *Error) Error() string
type NotDefinedError
    func (suffix NotDefinedError) Error() string

Examples

NewClient

Package files

metadata.go retry.go retry_linux.go

func Email 

func Email(serviceAccount string) (string, error)

Email calls Client.Email on the default client.

func ExternalIP 

func ExternalIP() (string, error)

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

func Get 

func Get(suffix string) (string, error)

Get calls Client.GetWithContext on the default client.

Deprecated: Please use the context aware variant GetWithContext.

func GetWithContext 

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

GetWithContext calls Client.GetWithContext on the default client.

func Hostname 

func Hostname() (string, error)

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

func InstanceAttributeValue 

func InstanceAttributeValue(attr string) (string, error)

InstanceAttributeValue calls Client.InstanceAttributeValue on the default client.

func InstanceAttributes 

func InstanceAttributes() ([]string, error)

InstanceAttributes calls Client.InstanceAttributes on the default client.

func InstanceID 

func InstanceID() (string, error)

InstanceID returns the current VM's numeric instance ID.

func InstanceName 

func InstanceName() (string, error)

InstanceName returns the current VM's instance ID string.

func InstanceTags 

func InstanceTags() ([]string, error)

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

func InternalIP 

func InternalIP() (string, error)

InternalIP returns the instance's primary internal IP address.

func NumericProjectID 

func NumericProjectID() (string, error)

NumericProjectID returns the current instance's numeric project ID.

func OnGCE 

func OnGCE() bool

OnGCE reports whether this process is running on Google Compute Engine.

func ProjectAttributeValue 

func ProjectAttributeValue(attr string) (string, error)

ProjectAttributeValue calls Client.ProjectAttributeValue on the default client.

func ProjectAttributes 

func ProjectAttributes() ([]string, error)

ProjectAttributes calls Client.ProjectAttributes on the default client.

func ProjectID 

func ProjectID() (string, error)

ProjectID returns the current instance's project ID string.

func Scopes 

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

Scopes calls Client.Scopes on the default client.

func Subscribe 

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

Subscribe calls Client.SubscribeWithContext on the default client.

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 

func Zone() (string, error)

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

type Client

A Client provides metadata. 

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

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.

Code:

package metadata_test

import (
    "context"
    "net/http"

    "cloud.google.com/go/compute/metadata"
)

// This example demonstrates how to use your own transport when using this package.
func ExampleNewClient() {
    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 (*Client) Email 

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

Email returns the email address associated with the service account. The account may be empty or the string "default" to use the instance's main account.

func (*Client) ExternalIP 

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

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

func (*Client) Get 

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 

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.

func (*Client) Hostname 

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

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

func (*Client) InstanceAttributeValue 

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.

func (*Client) InstanceAttributes 

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.

func (*Client) InstanceID 

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

InstanceID returns the current VM's numeric instance ID.

func (*Client) InstanceName 

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

InstanceName returns the current VM's instance ID string.

func (*Client) InstanceTags 

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

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

func (*Client) InternalIP 

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

InternalIP returns the instance's primary internal IP address.

func (*Client) NumericProjectID 

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

NumericProjectID returns the current instance's numeric project ID.

func (*Client) ProjectAttributeValue 

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.

func (*Client) ProjectAttributes 

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.

func (*Client) ProjectID 

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

ProjectID returns the current instance's project ID string.

func (*Client) Scopes 

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.

func (*Client) Subscribe 

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 

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 

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

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

type Error

Error contains an error response from the server. 

type Error struct {
    // Code is the HTTP response status code.
    Code int
    // Message is the server response message.
    Message string
}

func (*Error) Error 

func (e *Error) Error() string

type NotDefinedError

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. 

type NotDefinedError string

func (NotDefinedError) Error 

func (suffix NotDefinedError) Error() string

Subdirectories

Name Synopsis
..