imds

package module
v1.16.29 Latest Latest
Warning

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

 Go to latest Published: Feb 18, 2025 License: Apache-2.0 Imports: 27 Imported by: 224

Documentation

Overview

Package imds provides the API client for interacting with the Amazon EC2 Instance Metadata Service.

All Client operation calls have a default timeout. If the operation is not completed before this timeout expires, the operation will be canceled. This timeout can be overridden through the following:

  • Set the options flag DisableDefaultTimeout
  • Provide a Context with a timeout or deadline with calling the client's operations.

See the EC2 IMDS user guide for more information on using the API. https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html

Index

Constants

View Source 
const ServiceID = "ec2imds"

ServiceID provides the unique name of this API client

Variables

This section is empty.

Functions

func WithAPIOptions 

func WithAPIOptions(optFns ...func(*middleware.Stack) error) func(*Options)

WithAPIOptions wraps the API middleware functions, as a functional option for the API Client Options. Use this helper to add additional functional options to the API client, or operation calls.

Types

type Client 

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

Client provides the API client for interacting with the Amazon EC2 Instance Metadata Service API.

func New 

func New(options Options, optFns ...func(*Options)) *Client

New returns an initialized Client based on the functional options. Provide additional functional options to further configure the behavior of the client, such as changing the client's endpoint or adding custom middleware behavior.

func NewFromConfig 

func NewFromConfig(cfg aws.Config, optFns ...func(*Options)) *Client

NewFromConfig returns an initialized Client based the AWS SDK config, and functional options. Provide additional functional options to further configure the behavior of the client, such as changing the client's endpoint or adding custom middleware behavior.

func (*Client) GetDynamicData 

func (c *Client) GetDynamicData(ctx context.Context, params *GetDynamicDataInput, optFns ...func(*Options)) (*GetDynamicDataOutput, error)

GetDynamicData uses the path provided to request information from the EC2 instance metadata service for dynamic data. The content will be returned as a string, or error if the request failed.

func (*Client) GetIAMInfo 

func (c *Client) GetIAMInfo(
	ctx context.Context, params *GetIAMInfoInput, optFns ...func(*Options),
) (
	*GetIAMInfoOutput, error,
)

GetIAMInfo retrieves an identity document describing an instance. Error is returned if the request fails or is unable to parse the response.

func (*Client) GetInstanceIdentityDocument 

func (c *Client) GetInstanceIdentityDocument(
	ctx context.Context, params *GetInstanceIdentityDocumentInput, optFns ...func(*Options),
) (
	*GetInstanceIdentityDocumentOutput, error,
)

GetInstanceIdentityDocument retrieves an identity document describing an instance. Error is returned if the request fails or is unable to parse the response.

func (*Client) GetMetadata 

func (c *Client) GetMetadata(ctx context.Context, params *GetMetadataInput, optFns ...func(*Options)) (*GetMetadataOutput, error)

GetMetadata uses the path provided to request information from the Amazon EC2 Instance Metadata Service. The content will be returned as a string, or error if the request failed.

func (*Client) GetRegion 

func (c *Client) GetRegion(
	ctx context.Context, params *GetRegionInput, optFns ...func(*Options),
) (
	*GetRegionOutput, error,
)

GetRegion retrieves an identity document describing an instance. Error is returned if the request fails or is unable to parse the response.

func (*Client) GetUserData 

func (c *Client) GetUserData(ctx context.Context, params *GetUserDataInput, optFns ...func(*Options)) (*GetUserDataOutput, error)

GetUserData uses the path provided to request information from the EC2 instance metadata service for dynamic data. The content will be returned as a string, or error if the request failed.

type ClientEnableState 

type ClientEnableState = internalconfig.ClientEnableState

ClientEnableState provides an enumeration if the client is enabled, disabled, or default behavior. 

const (
	ClientDefaultEnableState ClientEnableState = internalconfig.ClientDefaultEnableState // default behavior
	ClientDisabled           ClientEnableState = internalconfig.ClientDisabled           // client disabled
	ClientEnabled            ClientEnableState = internalconfig.ClientEnabled            // client enabled
)

Enumeration values for ClientEnableState

type EndpointModeState added in v1.3.0 

type EndpointModeState = internalconfig.EndpointModeState

EndpointModeState is an enum configuration variable describing the client endpoint mode. Not configurable directly, but used when using the NewFromConfig. 

const (
	EndpointModeStateUnset EndpointModeState = internalconfig.EndpointModeStateUnset
	EndpointModeStateIPv4  EndpointModeState = internalconfig.EndpointModeStateIPv4
	EndpointModeStateIPv6  EndpointModeState = internalconfig.EndpointModeStateIPv6
)

Enumeration values for EndpointModeState

type GetDynamicDataInput 

type GetDynamicDataInput struct {
	// The relative dynamic data path to retrieve. Can be empty string to
	// retrieve a response containing a new line separated list of dynamic data
	// resources available.
	//
	// Must not include the dynamic data base path.
	//
	// May include leading slash. If Path includes trailing slash the trailing
	// slash will be included in the request for the resource.
	Path string
}

GetDynamicDataInput provides the input parameters for the GetDynamicData operation.

type GetDynamicDataOutput 

type GetDynamicDataOutput struct {
	Content io.ReadCloser

	ResultMetadata middleware.Metadata
}

GetDynamicDataOutput provides the output parameters for the GetDynamicData operation.

type GetIAMInfoInput 

type GetIAMInfoInput struct{}

GetIAMInfoInput provides the input parameters for GetIAMInfo operation.

type GetIAMInfoOutput 

type GetIAMInfoOutput struct {
	IAMInfo

	ResultMetadata middleware.Metadata
}

GetIAMInfoOutput provides the output parameters for GetIAMInfo operation.

type GetInstanceIdentityDocumentInput 

type GetInstanceIdentityDocumentInput struct{}

GetInstanceIdentityDocumentInput provides the input parameters for GetInstanceIdentityDocument operation.

type GetInstanceIdentityDocumentOutput 

type GetInstanceIdentityDocumentOutput struct {
	InstanceIdentityDocument

	ResultMetadata middleware.Metadata
}

GetInstanceIdentityDocumentOutput provides the output parameters for GetInstanceIdentityDocument operation.

type GetMetadataInput 

type GetMetadataInput struct {
	// The relative metadata path to retrieve. Can be empty string to retrieve
	// a response containing a new line separated list of metadata resources
	// available.
	//
	// Must not include the metadata base path.
	//
	// May include leading slash. If Path includes trailing slash the trailing slash
	// will be included in the request for the resource.
	Path string
}

GetMetadataInput provides the input parameters for the GetMetadata operation.

type GetMetadataOutput 

type GetMetadataOutput struct {
	Content io.ReadCloser

	ResultMetadata middleware.Metadata
}

GetMetadataOutput provides the output parameters for the GetMetadata operation.

type GetRegionInput 

type GetRegionInput struct{}

GetRegionInput provides the input parameters for GetRegion operation.

type GetRegionOutput 

type GetRegionOutput struct {
	Region string

	ResultMetadata middleware.Metadata
}

GetRegionOutput provides the output parameters for GetRegion operation.

type GetUserDataInput 

type GetUserDataInput struct{}

GetUserDataInput provides the input parameters for the GetUserData operation.

type GetUserDataOutput 

type GetUserDataOutput struct {
	Content io.ReadCloser

	ResultMetadata middleware.Metadata
}

GetUserDataOutput provides the output parameters for the GetUserData operation.

type HTTPClient 

type HTTPClient interface {
	Do(*http.Request) (*http.Response, error)
}

HTTPClient provides the interface for a client making HTTP requests with the API.

type IAMInfo 

type IAMInfo struct {
	Code               string
	LastUpdated        time.Time
	InstanceProfileArn string
	InstanceProfileID  string
}

IAMInfo provides the shape for unmarshaling an IAM info from the metadata API.

type InstanceIdentityDocument 

type InstanceIdentityDocument struct {
	DevpayProductCodes      []string  `json:"devpayProductCodes"`
	MarketplaceProductCodes []string  `json:"marketplaceProductCodes"`
	AvailabilityZone        string    `json:"availabilityZone"`
	PrivateIP               string    `json:"privateIp"`
	Version                 string    `json:"version"`
	Region                  string    `json:"region"`
	InstanceID              string    `json:"instanceId"`
	BillingProducts         []string  `json:"billingProducts"`
	InstanceType            string    `json:"instanceType"`
	AccountID               string    `json:"accountId"`
	PendingTime             time.Time `json:"pendingTime"`
	ImageID                 string    `json:"imageId"`
	KernelID                string    `json:"kernelId"`
	RamdiskID               string    `json:"ramdiskId"`
	Architecture            string    `json:"architecture"`
}

InstanceIdentityDocument provides the shape for unmarshaling an instance identity document

type Options 

type Options struct {
	// Set of options to modify how an operation is invoked. These apply to all
	// operations invoked for this client. Use functional options on operation
	// call to modify this list for per operation behavior.
	APIOptions []func(*middleware.Stack) error

	// The endpoint the client will use to retrieve EC2 instance metadata.
	//
	// Specifies the EC2 Instance Metadata Service endpoint to use. If specified it overrides EndpointMode.
	//
	// If unset, and the environment variable AWS_EC2_METADATA_SERVICE_ENDPOINT
	// has a value the client will use the value of the environment variable as
	// the endpoint for operation calls.
	//
	//    AWS_EC2_METADATA_SERVICE_ENDPOINT=http://[::1]
	Endpoint string

	// The endpoint selection mode the client will use if no explicit endpoint is provided using the Endpoint field.
	//
	// Setting EndpointMode to EndpointModeStateIPv4 will configure the client to use the default EC2 IPv4 endpoint.
	// Setting EndpointMode to EndpointModeStateIPv6 will configure the client to use the default EC2 IPv6 endpoint.
	//
	// By default if EndpointMode is not set (EndpointModeStateUnset) than the default endpoint selection mode EndpointModeStateIPv4.
	EndpointMode EndpointModeState

	// The HTTP client to invoke API calls with. Defaults to client's default
	// HTTP implementation if nil.
	HTTPClient HTTPClient

	// Retryer guides how HTTP requests should be retried in case of recoverable
	// failures. When nil the API client will use a default retryer.
	Retryer aws.Retryer

	// Changes if the EC2 Instance Metadata client is enabled or not. Client
	// will default to enabled if not set to ClientDisabled. When the client is
	// disabled it will return an error for all operation calls.
	//
	// If ClientEnableState value is ClientDefaultEnableState (default value),
	// and the environment variable "AWS_EC2_METADATA_DISABLED" is set to
	// "true", the client will be disabled.
	//
	//    AWS_EC2_METADATA_DISABLED=true
	ClientEnableState ClientEnableState

	// Configures the events that will be sent to the configured logger.
	ClientLogMode aws.ClientLogMode

	// The logger writer interface to write logging messages to.
	Logger logging.Logger

	// Configure IMDSv1 fallback behavior. By default, the client will attempt
	// to fall back to IMDSv1 as needed for backwards compatibility. When set to [aws.FalseTernary]
	// the client will return any errors encountered from attempting to fetch a token
	// instead of silently using the insecure data flow of IMDSv1.
	//
	// See [configuring IMDS] for more information.
	//
	// [configuring IMDS]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html
	EnableFallback aws.Ternary

	// By default, all IMDS client operations enforce a 5-second timeout. You
	// can disable that behavior with this setting.
	DisableDefaultTimeout bool
	// contains filtered or unexported fields
}

Options provides the fields for configuring the API client's behavior.

func (Options) Copy 

func (o Options) Copy() Options

Copy creates a copy of the API options.

Source Files

View all Source files

Directories

Path Synopsis
internal
config
configtesting Module

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.