imds

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 by providing 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
• func WithAPIOptions(optFns ...func(*middleware.Stack) error) func(*Options)
• type Client
  • func New(options Options, optFns ...func(*Options)) *Client
  • func NewFromConfig(cfg aws.Config, optFns ...func(*Options)) *Client
  • func (c *Client) GetDynamicData(ctx context.Context, params *GetDynamicDataInput, optFns ...func(*Options)) (*GetDynamicDataOutput, error)
  • func (c *Client) GetIAMInfo(ctx context.Context, params *GetIAMInfoInput, optFns ...func(*Options)) (*GetIAMInfoOutput, error)
  • func (c *Client) GetInstanceIdentityDocument(ctx context.Context, params *GetInstanceIdentityDocumentInput, ...) (*GetInstanceIdentityDocumentOutput, error)
  • func (c *Client) GetMetadata(ctx context.Context, params *GetMetadataInput, optFns ...func(*Options)) (*GetMetadataOutput, error)
  • func (c *Client) GetRegion(ctx context.Context, params *GetRegionInput, optFns ...func(*Options)) (*GetRegionOutput, error)
  • func (c *Client) GetUserData(ctx context.Context, params *GetUserDataInput, optFns ...func(*Options)) (*GetUserDataOutput, error)
• type ClientEnableState
• type EndpointModeState
• type GetDynamicDataInput
• type GetDynamicDataOutput
• type GetIAMInfoInput
• type GetIAMInfoOutput
• type GetInstanceIdentityDocumentInput
• type GetInstanceIdentityDocumentOutput
• type GetMetadataInput
• type GetMetadataOutput
• type GetRegionInput
• type GetRegionOutput
• type GetUserDataInput
• type GetUserDataOutput
• type HTTPClient
• type IAMInfo
• type InstanceIdentityDocument
• type Options
  • func (o Options) Copy() Options

Constants

const ServiceID = "ec2imds"

ServiceID provides the unique name of this API client

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

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
	// 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.