metadata
packagemodule
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
Stable versionWhen a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Open Source Insights
README¶
Compute API
This is a utility library for communicating with Google Cloud metadata serviceon Google Cloud.
Install
go get cloud.google.com/go/compute/metadataGo Version Support
See theGo Versions Supportedsection in the root directory's README.
Contributing
Contributions are welcome. Please, see theCONTRIBUTINGdocument 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. SeeContributor Code of Conductfor 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 athttps://cloud.google.com/compute/docs/metadata/overview.
Index¶
- func Email(serviceAccount string) (string, error)deprecated
- func EmailWithContext(ctx context.Context, serviceAccount string) (string, error)
- func ExternalIP() (string, error)deprecated
- func ExternalIPWithContext(ctx context.Context) (string, error)
- func Get(suffix string) (string, error)deprecated
- func GetWithContext(ctx context.Context, suffix string) (string, error)
- func Hostname() (string, error)deprecated
- func HostnameWithContext(ctx context.Context) (string, error)
- func InstanceAttributeValue(attr string) (string, error)deprecated
- func InstanceAttributeValueWithContext(ctx context.Context, attr string) (string, error)
- func InstanceAttributes() ([]string, error)deprecated
- func InstanceAttributesWithContext(ctx context.Context) ([]string, error)
- func InstanceID() (string, error)deprecated
- func InstanceIDWithContext(ctx context.Context) (string, error)
- func InstanceName() (string, error)deprecated
- func InstanceNameWithContext(ctx context.Context) (string, error)
- func InstanceTags() ([]string, error)deprecated
- func InstanceTagsWithContext(ctx context.Context) ([]string, error)
- func InternalIP() (string, error)deprecated
- func InternalIPWithContext(ctx context.Context) (string, error)
- func NumericProjectID() (string, error)deprecated
- func NumericProjectIDWithContext(ctx context.Context) (string, error)
- func OnGCE() bool
- func OnGCEWithContext(ctx context.Context) bool
- func ProjectAttributeValue(attr string) (string, error)deprecated
- func ProjectAttributeValueWithContext(ctx context.Context, attr string) (string, error)
- func ProjectAttributes() ([]string, error)deprecated
- func ProjectAttributesWithContext(ctx context.Context) ([]string, error)
- func ProjectID() (string, error)deprecated
- func ProjectIDWithContext(ctx context.Context) (string, error)
- func Scopes(serviceAccount string) ([]string, error)deprecated
- func ScopesWithContext(ctx context.Context, serviceAccount string) ([]string, error)
- func Subscribe(suffix string, fn func(v string, ok bool) error) errordeprecated
- func SubscribeWithContext(ctx context.Context, suffix string, ...) error
- func Zone() (string, error)deprecated
- func ZoneWithContext(ctx context.Context) (string, error)
- type Client
- func (c *Client) Email(serviceAccount string) (string, error)deprecated
- func (c *Client) EmailWithContext(ctx context.Context, serviceAccount string) (string, error)
- func (c *Client) ExternalIP() (string, error)deprecated
- func (c *Client) ExternalIPWithContext(ctx context.Context) (string, error)
- func (c *Client) Get(suffix string) (string, error)deprecated
- func (c *Client) GetWithContext(ctx context.Context, suffix string) (string, error)
- func (c *Client) Hostname() (string, error)deprecated
- func (c *Client) HostnameWithContext(ctx context.Context) (string, error)
- func (c *Client) InstanceAttributeValue(attr string) (string, error)deprecated
- func (c *Client) InstanceAttributeValueWithContext(ctx context.Context, attr string) (string, error)
- func (c *Client) InstanceAttributes() ([]string, error)deprecated
- func (c *Client) InstanceAttributesWithContext(ctx context.Context) ([]string, error)
- func (c *Client) InstanceID() (string, error)deprecated
- func (c *Client) InstanceIDWithContext(ctx context.Context) (string, error)
- func (c *Client) InstanceName() (string, error)deprecated
- func (c *Client) InstanceNameWithContext(ctx context.Context) (string, error)
- func (c *Client) InstanceTags() ([]string, error)deprecated
- func (c *Client) InstanceTagsWithContext(ctx context.Context) ([]string, error)
- func (c *Client) InternalIP() (string, error)deprecated
- func (c *Client) InternalIPWithContext(ctx context.Context) (string, error)
- func (c *Client) NumericProjectID() (string, error)deprecated
- func (c *Client) NumericProjectIDWithContext(ctx context.Context) (string, error)
- func (c *Client) OnGCEWithContext(ctx context.Context) bool
- func (c *Client) ProjectAttributeValue(attr string) (string, error)deprecated
- func (c *Client) ProjectAttributeValueWithContext(ctx context.Context, attr string) (string, error)
- func (c *Client) ProjectAttributes() ([]string, error)deprecated
- func (c *Client) ProjectAttributesWithContext(ctx context.Context) ([]string, error)
- func (c *Client) ProjectID() (string, error)deprecated
- func (c *Client) ProjectIDWithContext(ctx context.Context) (string, error)
- func (c *Client) Scopes(serviceAccount string) ([]string, error)deprecated
- func (c *Client) ScopesWithContext(ctx context.Context, serviceAccount string) ([]string, error)
- func (c *Client) Subscribe(suffix string, fn func(v string, ok bool) error) errordeprecated
- func (c *Client) SubscribeWithContext(ctx context.Context, suffix string, ...) error
- func (c *Client) Zone() (string, error)deprecated
- func (c *Client) ZoneWithContext(ctx context.Context) (string, error)
- type Error
- type NotDefinedError
- type Options
Examples¶
Constants¶
This section is empty.
Variables¶
This section is empty.
Functions¶
funcEmaildeprecated
Email calls Client.EmailWithContext on the default client.
Deprecated: Please use the context aware variantEmailWithContext.
funcEmailWithContext¶added inv0.4.0
EmailWithContext calls Client.EmailWithContext on the default client.
funcExternalIPdeprecated
ExternalIP returns the instance's primary external (public) IP address.
Deprecated: Please use the context aware variantExternalIPWithContext.
funcExternalIPWithContext¶added inv0.4.0
ExternalIPWithContext returns the instance's primary external (public) IP address.
funcGetdeprecated
Get calls Client.GetWithContext on the default client.
Deprecated: Please use the context aware variantGetWithContext.
funcGetWithContext¶added inv0.3.0
GetWithContext calls Client.GetWithContext on the default client.
funcHostnamedeprecated
Hostname returns the instance's hostname. This will be of the form"<instanceID>.c.<projID>.internal".
Deprecated: Please use the context aware variantHostnameWithContext.
funcHostnameWithContext¶added inv0.4.0
HostnameWithContext returns the instance's hostname. This will be of the form"<instanceID>.c.<projID>.internal".
funcInstanceAttributeValuedeprecated
InstanceAttributeValue calls Client.InstanceAttributeValueWithContext on the default client.
Deprecated: Please use the context aware variantInstanceAttributeValueWithContext.
funcInstanceAttributeValueWithContext¶added inv0.4.0
InstanceAttributeValueWithContext calls Client.InstanceAttributeValueWithContext on the default client.
funcInstanceAttributesdeprecated
funcInstanceAttributesWithContext¶added inv0.4.0
InstanceAttributesWithContext calls Client.ProjectAttributesWithContext on the default client.
funcInstanceIDdeprecated
InstanceID returns the current VM's numeric instance ID.
Deprecated: Please use the context aware variantInstanceIDWithContext.
funcInstanceIDWithContext¶added inv0.4.0
InstanceIDWithContext returns the current VM's numeric instance ID.
funcInstanceNamedeprecated
InstanceName returns the current VM's instance ID string.
Deprecated: Please use the context aware variantInstanceNameWithContext.
funcInstanceNameWithContext¶added inv0.4.0
InstanceNameWithContext returns the current VM's instance ID string.
funcInstanceTagsdeprecated
InstanceTags returns the list of user-defined instance tags,assigned when initially creating a GCE instance.
Deprecated: Please use the context aware variantInstanceTagsWithContext.
funcInstanceTagsWithContext¶added inv0.4.0
InstanceTagsWithContext returns the list of user-defined instance tags,assigned when initially creating a GCE instance.
funcInternalIPdeprecated
InternalIP returns the instance's primary internal IP address.
Deprecated: Please use the context aware variantInternalIPWithContext.
funcInternalIPWithContext¶added inv0.4.0
InternalIPWithContext returns the instance's primary internal IP address.
funcNumericProjectIDdeprecated
NumericProjectID returns the current instance's numeric project ID.
Deprecated: Please use the context aware variantNumericProjectIDWithContext.
funcNumericProjectIDWithContext¶added inv0.4.0
NumericProjectIDWithContext returns the current instance's numeric project ID.
funcOnGCE¶
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 serveris accessible from this process and have all the metadata defined.
funcOnGCEWithContext¶added inv0.7.0
OnGCEWithContext reports whether this process is running on Google Compute Platforms.This function's return value is memoized for better performance.NOTE: True returned from `OnGCEWithContext` does not guarantee that the metadata serveris accessible from this process and have all the metadata defined.
funcProjectAttributeValuedeprecated
ProjectAttributeValue calls Client.ProjectAttributeValueWithContext on the default client.
Deprecated: Please use the context aware variantProjectAttributeValueWithContext.
funcProjectAttributeValueWithContext¶added inv0.4.0
ProjectAttributeValueWithContext calls Client.ProjectAttributeValueWithContext on the default client.
funcProjectAttributesdeprecated
ProjectAttributes calls Client.ProjectAttributesWithContext on the default client.
Deprecated: Please use the context aware variantProjectAttributesWithContext.
funcProjectAttributesWithContext¶added inv0.4.0
ProjectAttributesWithContext calls Client.ProjectAttributesWithContext on the default client.
funcProjectIDdeprecated
ProjectID returns the current instance's project ID string.
Deprecated: Please use the context aware variantProjectIDWithContext.
funcProjectIDWithContext¶added inv0.4.0
ProjectIDWithContext returns the current instance's project ID string.
funcScopesdeprecated
Scopes calls Client.ScopesWithContext on the default client.
Deprecated: Please use the context aware variantScopesWithContext.
funcScopesWithContext¶added inv0.4.0
ScopesWithContext calls Client.ScopesWithContext on the default client.
funcSubscribeWithContext¶added inv0.3.0
func SubscribeWithContext(ctxcontext.Context, suffixstring, fn func(ctxcontext.Context, vstring, okbool)error)error
SubscribeWithContext calls Client.SubscribeWithContext on the default client.
funcZonedeprecated
Zone returns the current VM's zone, such as "us-central1-b".
Deprecated: Please use the context aware variantZoneWithContext.
Types¶
typeClient¶
type Client struct {// contains filtered or unexported fields}A Client provides metadata.
funcNewClient¶
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¶
This example demonstrates how to use your own transport when using this package.
package mainimport ("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 stringbase 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)}funcNewWithOptions¶added inv0.6.0
NewWithOptions returns a Client that is configured with the provided Options.
func (*Client)EmailWithContext¶added inv0.4.0
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)ExternalIPdeprecated
ExternalIP returns the instance's primary external (public) IP address.
Deprecated: Please use the context aware variantClient.ExternalIPWithContext.
func (*Client)ExternalIPWithContext¶added inv0.4.0
ExternalIPWithContext returns the instance's primary external (public) IP address.
func (*Client)Getdeprecated
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 variantClient.GetWithContext.
func (*Client)GetWithContext¶added inv0.3.0
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)Hostnamedeprecated
Hostname returns the instance's hostname. This will be of the form"<instanceID>.c.<projID>.internal".
Deprecated: Please use the context aware variantClient.HostnameWithContext.
func (*Client)HostnameWithContext¶added inv0.4.0
HostnameWithContext returns the instance's hostname. This will be of the form"<instanceID>.c.<projID>.internal".
func (*Client)InstanceAttributeValuedeprecated
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 variantClient.InstanceAttributeValueWithContext.
func (*Client)InstanceAttributeValueWithContext¶added inv0.4.0
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)InstanceAttributesdeprecated
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 variantClient.InstanceAttributesWithContext.
func (*Client)InstanceAttributesWithContext¶added inv0.4.0
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)InstanceIDdeprecated
InstanceID returns the current VM's numeric instance ID.
Deprecated: Please use the context aware variantClient.InstanceIDWithContext.
func (*Client)InstanceIDWithContext¶added inv0.4.0
InstanceIDWithContext returns the current VM's numeric instance ID.
func (*Client)InstanceNamedeprecated
InstanceName returns the current VM's instance ID string.
Deprecated: Please use the context aware variantClient.InstanceNameWithContext.
func (*Client)InstanceNameWithContext¶added inv0.4.0
InstanceNameWithContext returns the current VM's instance ID string.
func (*Client)InstanceTagsdeprecated
InstanceTags returns the list of user-defined instance tags.
Deprecated: Please use the context aware variantClient.InstanceTagsWithContext.
func (*Client)InstanceTagsWithContext¶added inv0.4.0
InstanceTagsWithContext returns the list of user-defined instance tags,assigned when initially creating a GCE instance.
func (*Client)InternalIPdeprecated
InternalIP returns the instance's primary internal IP address.
Deprecated: Please use the context aware variantClient.InternalIPWithContext.
func (*Client)InternalIPWithContext¶added inv0.4.0
InternalIPWithContext returns the instance's primary internal IP address.
func (*Client)NumericProjectIDdeprecated
NumericProjectID returns the current instance's numeric project ID.
Deprecated: Please use the context aware variantClient.NumericProjectIDWithContext.
func (*Client)NumericProjectIDWithContext¶added inv0.4.0
NumericProjectIDWithContext returns the current instance's numeric project ID.
func (*Client)OnGCEWithContext¶added inv0.7.0
OnGCEWithContext reports whether this process is running on Google Compute Platforms.NOTE: True returned from `OnGCEWithContext` does not guarantee that the metadata serveris accessible from this process and have all the metadata defined.
func (*Client)ProjectAttributeValuedeprecated
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 variantClient.ProjectAttributeValueWithContext.
func (*Client)ProjectAttributeValueWithContext¶added inv0.4.0
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)ProjectAttributesdeprecated
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 variantClient.ProjectAttributesWithContext.
func (*Client)ProjectAttributesWithContext¶added inv0.4.0
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)ProjectIDdeprecated
ProjectID returns the current instance's project ID string.
Deprecated: Please use the context aware variantClient.ProjectIDWithContext.
func (*Client)ProjectIDWithContext¶added inv0.4.0
ProjectIDWithContext returns the current instance's project ID string.
func (*Client)Scopesdeprecated
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 variantClient.ScopesWithContext.
func (*Client)ScopesWithContext¶added inv0.4.0
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)Subscribedeprecated
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 variantClient.SubscribeWithContext.
func (*Client)SubscribeWithContext¶added inv0.3.0
func (c *Client) SubscribeWithContext(ctxcontext.Context, suffixstring, fn func(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)Zonedeprecated
Zone returns the current VM's zone, such as "us-central1-b".
Deprecated: Please use the context aware variantClient.ZoneWithContext.
typeError¶
type Error struct {// Code is the HTTP response status code.Codeint// Message is the server response message.Messagestring}Error contains an error response from the server.
typeNotDefinedError¶
type NotDefinedErrorstring
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
typeOptions¶added inv0.6.0
type Options struct {// 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 aClient.
Source Files
Directories