| Copyright | (c) 2013-2023 Brendan Hay |
|---|---|
| License | Mozilla Public License, v. 2.0. |
| Maintainer | Brendan Hay <brendan.g.hay+amazonka@gmail.com> |
| Stability | provisional |
| Portability | non-portable (GHC extensions) |
| Safe Haskell | Safe-Inferred |
| Language | Haskell2010 |
Amazonka.EC2.Metadata
Description
This module contains functions for retrieving various EC2 metadata from an
instance's local metadata endpoint. It assumes that you're running the code
on an EC2 instance or have a compatible instance-data endpoint available.
It is intended to be usable when you need to make metadata calls prior to
initialisation of the Env.
Synopsis
- isEC2 :: MonadIO m => Manager -> m Bool
- dynamic :: MonadIO m => Manager -> Dynamic -> m ByteString
- metadata :: MonadIO m => Manager -> Metadata -> m ByteString
- userdata :: MonadIO m => Manager -> m (Maybe ByteString)
- identity :: MonadIO m => Manager -> m (Either String IdentityDocument)
- data Dynamic
- data Metadata
- = AMIId
- | AMILaunchIndex
- | AMIManifestPath
- | AncestorAMIIds
- | Autoscaling !Autoscaling
- | BlockDevice !Mapping
- | ElasticGpus !ElasticGpus
- | ElasticInference !ElasticInference
- | Events !Events
- | Hostname
- | IAM !IAM
- | IdentityCredentialsEC2 !IdentityCredentialsEC2
- | InstanceAction
- | InstanceId
- | InstanceLifeCycle
- | InstanceType
- | IPV6
- | KernelId
- | LocalHostname
- | LocalIPV4
- | MAC
- | Network !Text !Interface
- | Placement !Placement
- | ProductCodes
- | PublicHostname
- | PublicIPV4
- | OpenSSHKey
- | RAMDiskId
- | ReservationId
- | SecurityGroups
- | Services !Services
- | Spot !Spot
- | Tags !Tags
- data Autoscaling = TargetLifecycleState
- data Mapping
- newtype ElasticGpus = EGAssociations Text
- newtype ElasticInference = EIAssociations Text
- data Events
- data Maintenance
- data Recommendations = Rebalance
- data IAM
- = Info
- | SecurityCredentials (Maybe Text)
- data IdentityCredentialsEC2
- data Interface
- = IDeviceNumber
- | IInterfaceId
- | IIPV4Associations !Text
- | IIPV6s
- | ILocalHostname
- | ILocalIPV4s
- | IMAC
- | INetworkCardIndex
- | IOwnerId
- | IPublicHostname
- | IPublicIPV4s
- | ISecurityGroups
- | ISecurityGroupIds
- | ISubnetId
- | ISubnetIPV4_CIDRBlock
- | ISubnetIPV6_CIDRBlock
- | IVPCId
- | IVPCIPV4_CIDRBlock
- | IVPCIPV4_CIDRBlocks
- | IVPCIPV6_CIDRBlocks
- data Placement
- data Services
- data Spot
- data Tags = Instance
- data IdentityDocument = IdentityDocument {
- devpayProductCodes :: Maybe [Text]
- billingProducts :: Maybe [Text]
- version :: Maybe Text
- privateIp :: Maybe Text
- availabilityZone :: Text
- region :: Region
- instanceId :: Text
- instanceType :: Text
- accountId :: Text
- imageId :: Maybe Text
- kernelId :: Maybe Text
- ramdiskId :: Maybe Text
- architecture :: Maybe Text
- pendingTime :: Maybe ISO8601
- identityDocument_devpayProductCodes :: Lens' IdentityDocument (Maybe [Text])
- identityDocument_billingProducts :: Lens' IdentityDocument (Maybe [Text])
- identityDocument_version :: Lens' IdentityDocument (Maybe Text)
- identityDocument_privateIp :: Lens' IdentityDocument (Maybe Text)
- identityDocument_availabilityZone :: Lens' IdentityDocument Text
- identityDocument_region :: Lens' IdentityDocument Region
- identityDocument_instanceId :: Lens' IdentityDocument Text
- identityDocument_instanceType :: Lens' IdentityDocument Text
- identityDocument_accountId :: Lens' IdentityDocument Text
- identityDocument_imageId :: Lens' IdentityDocument (Maybe Text)
- identityDocument_kernelId :: Lens' IdentityDocument (Maybe Text)
- identityDocument_ramdiskId :: Lens' IdentityDocument (Maybe Text)
- identityDocument_architecture :: Lens' IdentityDocument (Maybe Text)
- identityDocument_pendingTime :: Lens' IdentityDocument (Maybe ISO8601)
EC2 Instance Check
isEC2 :: MonadIO m => Manager -> m Bool Source #
Test whether the underlying host is running on EC2 by
making an HTTP request to http://instance-data/latest.
Retrieving Instance Data
dynamic :: MonadIO m => Manager -> Dynamic -> m ByteString Source #
Retrieve the specified Dynamic data.
Throws HttpException if HTTP communication fails.
metadata :: MonadIO m => Manager -> Metadata -> m ByteString Source #
Retrieve the specified Metadata.
Throws HttpException if HTTP communication fails.
userdata :: MonadIO m => Manager -> m (Maybe ByteString) Source #
Retrieve the user data. Returns Nothing if no user data is assigned
to the instance.
Throws HttpException if HTTP communication fails.
identity :: MonadIO m => Manager -> m (Either String IdentityDocument) Source #
Path Constructors
Constructors
| FWS | Value showing whether the customer has enabled detailed one-minute monitoring in CloudWatch. Valid values: |
| Document | JSON containing instance attributes, such as instance-id,
private IP address, etc.
See: |
| PKCS7 | Used to verify the document's authenticity and content against the signature. |
| Signature | Data that can be used by other parties to verify its origin and authenticity. |
Instances
| ToText Dynamic Source # | |
Defined in Amazonka.EC2.Metadata | |
| Generic Dynamic Source # | |
| Show Dynamic Source # | |
| Eq Dynamic Source # | |
| Ord Dynamic Source # | |
Defined in Amazonka.EC2.Metadata | |
| type Rep Dynamic Source # | |
Defined in Amazonka.EC2.Metadata type Rep Dynamic = D1 ('MetaData "Dynamic" "Amazonka.EC2.Metadata" "amazonka-2.0-48plDWnPMAk3PGO79vdSa0" 'False) ((C1 ('MetaCons "FWS" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Document" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "PKCS7" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Signature" 'PrefixI 'False) (U1 :: Type -> Type))) | |
Instance metadata categories. The list of supported categories are listed in the EC2 Documentation.
Constructors
| AMIId | The AMI ID used to launch the instance. |
| AMILaunchIndex | If you started more than one instance at the same time, this value indicates the order in which the instance was launched. The value of the first instance launched is 0. |
| AMIManifestPath | The path to the AMI's manifest file in Amazon S3.
If you used an Amazon EBS-backed AMI to launch the instance,
the returned result is |
| AncestorAMIIds | The AMI IDs of any instances that were rebundled to create this AMI.
This value will only exist if the AMI manifest file contained an
|
| Autoscaling !Autoscaling | See: |
| BlockDevice !Mapping | See: |
| ElasticGpus !ElasticGpus | See: |
| ElasticInference !ElasticInference | See |
| Events !Events | See |
| Hostname | If the EC2 instance is using IP-based naming (IPBN), this is the private IPv4 DNS hostname of the instance. If the EC2 instance is using Resource-based naming (RBN), this is the RBN. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). For more information about IPBN and RBN, see Amazon EC2 instance hostname types. |
| IAM !IAM | See: |
| IdentityCredentialsEC2 !IdentityCredentialsEC2 | See: |
| InstanceAction | Notifies the instance that it should reboot in preparation for bundling.
Valid values: |
| InstanceId | The ID of this instance. |
| InstanceLifeCycle | The purchasing option of this instance. For more information, see Instance purchasing options. |
| InstanceType | The type of instance. For more information, see Instance types. |
| IPV6 | The IPv6 address of the instance. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0) network interface and the first IPv6 address assigned. If no IPv6 address exists on network interface[0], this item is not set and results in an HTTP 404 response. |
| KernelId | The ID of the kernel launched with this instance, if applicable. |
| LocalHostname | In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). If the EC2 instance is using IP-based naming (IPBN), this is the private IPv4 DNS hostname of the instance. If the EC2 instance is using Resource-based naming (RBN), this is the RBN. For more information about IPBN, RBN, and EC2 instance naming, see Amazon EC2 instance hostname types. |
| LocalIPV4 | The private IPv4 address of the instance. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). If this is an IPv6-only instance, this item is not set and results in an HTTP 404 response. |
| MAC | The instance's media access control (MAC) address. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). |
| Network !Text !Interface | See: |
| Placement !Placement | See: |
| ProductCodes | AWS Marketplace product codes associated with the instance, if any. |
| PublicHostname | The instance's public DNS (IPv4). This category is only
returned if the |
| PublicIPV4 | The public IP address. If an Elastic IP address is associated with the instance, the value returned is the Elastic IP address. |
| OpenSSHKey | Public key. Only available if supplied at instance launch time. |
| RAMDiskId | The ID of the RAM disk specified at launch time, if applicable. |
| ReservationId | ID of the reservation. |
| SecurityGroups | The names of the security groups applied to the instance. After launch, you can change the security groups of the
instances. Such changes are reflected here and in
|
| Services !Services | See: |
| Spot !Spot | See: |
| Tags !Tags | See: |
Instances
data Autoscaling Source #
Metadata keys for autoscaling/*.
Constructors
| TargetLifecycleState | Value showing the target Auto Scaling lifecycle state that an
Auto Scaling instance is transitioning to. Present when the
instance transitions to one of the target lifecycle states
after March 10, 2022. Possible values: |
Instances
| ToText Autoscaling Source # | |
Defined in Amazonka.EC2.Metadata Methods toText :: Autoscaling -> Text # | |
| Generic Autoscaling Source # | |
Defined in Amazonka.EC2.Metadata Associated Types type Rep Autoscaling :: Type -> Type # | |
| Show Autoscaling Source # | |
Defined in Amazonka.EC2.Metadata Methods showsPrec :: Int -> Autoscaling -> ShowS # show :: Autoscaling -> String # showList :: [Autoscaling] -> ShowS # | |
| Eq Autoscaling Source # | |
Defined in Amazonka.EC2.Metadata | |
| Ord Autoscaling Source # | |
Defined in Amazonka.EC2.Metadata Methods compare :: Autoscaling -> Autoscaling -> Ordering # (<) :: Autoscaling -> Autoscaling -> Bool # (<=) :: Autoscaling -> Autoscaling -> Bool # (>) :: Autoscaling -> Autoscaling -> Bool # (>=) :: Autoscaling -> Autoscaling -> Bool # max :: Autoscaling -> Autoscaling -> Autoscaling # min :: Autoscaling -> Autoscaling -> Autoscaling # | |
| type Rep Autoscaling Source # | |
Metadata keys for block-device-mapping/*.
Constructors
| AMI | The virtual device that contains the root/boot file system. |
| EBS !Int | The virtual devices associated with Amazon EBS volumes, if present. This value is only available in metadata if it is present at launch time. The N indicates the index of the Amazon EBS volume (such as ebs1 or ebs2). |
| Ephemeral !Int | The virtual devices associated with ephemeral devices, if present. The N indicates the index of the ephemeral volume. |
| Root | The virtual devices or partitions associated with the root devices, or partitions on the virtual device, where the root (/ or C:) file system is associated with the given instance. |
| Swap | The virtual devices associated with swap. Not always present. |
Instances
| ToText Mapping Source # | |
Defined in Amazonka.EC2.Metadata | |
| Generic Mapping Source # | |
| Show Mapping Source # | |
| Eq Mapping Source # | |
| Ord Mapping Source # | |
Defined in Amazonka.EC2.Metadata | |
| type Rep Mapping Source # | |
Defined in Amazonka.EC2.Metadata type Rep Mapping = D1 ('MetaData "Mapping" "Amazonka.EC2.Metadata" "amazonka-2.0-48plDWnPMAk3PGO79vdSa0" 'False) ((C1 ('MetaCons "AMI" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "EBS" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int))) :+: (C1 ('MetaCons "Ephemeral" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int)) :+: (C1 ('MetaCons "Root" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Swap" 'PrefixI 'False) (U1 :: Type -> Type)))) | |
newtype ElasticGpus Source #
Metadata keys for elastic-gpus/*.
Constructors
| EGAssociations Text | If there is an Elastic GPU attached to the instance, contains a JSON string with information about the Elastic GPU, including its ID and connection information. |
Instances
newtype ElasticInference Source #
Metadata keys for elastic-inference/*.
Constructors
| EIAssociations Text | If there is an Elastic Inference accelerator attached to the instance, contains a JSON string with information about the Elastic Inference accelerator, including its ID and type. |
Instances
Metadata keys for events/*.
Constructors
| Maintenance !Maintenance | |
| Recommendations !Recommendations |
Instances
| ToText Events Source # | |
Defined in Amazonka.EC2.Metadata | |
| Generic Events Source # | |
| Show Events Source # | |
| Eq Events Source # | |
| Ord Events Source # | |
| type Rep Events Source # | |
Defined in Amazonka.EC2.Metadata type Rep Events = D1 ('MetaData "Events" "Amazonka.EC2.Metadata" "amazonka-2.0-48plDWnPMAk3PGO79vdSa0" 'False) (C1 ('MetaCons "Maintenance" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Maintenance)) :+: C1 ('MetaCons "Recommendations" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Recommendations))) | |
data Maintenance Source #
Metadata keys for eventsmaintenance*.
Constructors
| History | If there are completed or canceled maintenance events for the instance, contains a JSON string with information about the events. For more information, see To view event history about completed or canceled events. |
| Scheduled | If there are active maintenance events for the instance, contains a JSON string with information about the events. For more information, see View scheduled events. |
Instances
| ToText Maintenance Source # | |
Defined in Amazonka.EC2.Metadata Methods toText :: Maintenance -> Text # | |
| Generic Maintenance Source # | |
Defined in Amazonka.EC2.Metadata Associated Types type Rep Maintenance :: Type -> Type # | |
| Show Maintenance Source # | |
Defined in Amazonka.EC2.Metadata Methods showsPrec :: Int -> Maintenance -> ShowS # show :: Maintenance -> String # showList :: [Maintenance] -> ShowS # | |
| Eq Maintenance Source # | |
Defined in Amazonka.EC2.Metadata | |
| Ord Maintenance Source # | |
Defined in Amazonka.EC2.Metadata Methods compare :: Maintenance -> Maintenance -> Ordering # (<) :: Maintenance -> Maintenance -> Bool # (<=) :: Maintenance -> Maintenance -> Bool # (>) :: Maintenance -> Maintenance -> Bool # (>=) :: Maintenance -> Maintenance -> Bool # max :: Maintenance -> Maintenance -> Maintenance # min :: Maintenance -> Maintenance -> Maintenance # | |
| type Rep Maintenance Source # | |
data Recommendations Source #
Metadata keys for events/recommendations/*.
Constructors
| Rebalance | The approximate time, in UTC, when the EC2 instance rebalance
recommendation notification is emitted for the instance. The
following is an example of the metadata for this category:
|
Instances
Metadata keys for iam/*.
Constructors
| Info | If there is an IAM role associated with the instance, contains information about the last time the instance profile was updated, including the instance's LastUpdated date, InstanceProfileArn, and InstanceProfileId. Otherwise, not present. |
| SecurityCredentials (Maybe Text) | If there is an IAM role associated with the instance,
See: |
Instances
| ToText IAM Source # | |
Defined in Amazonka.EC2.Metadata | |
| Generic IAM Source # | |
| Show IAM Source # | |
| Eq IAM Source # | |
| Ord IAM Source # | |
| type Rep IAM Source # | |
Defined in Amazonka.EC2.Metadata type Rep IAM = D1 ('MetaData "IAM" "Amazonka.EC2.Metadata" "amazonka-2.0-48plDWnPMAk3PGO79vdSa0" 'False) (C1 ('MetaCons "Info" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "SecurityCredentials" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 (Maybe Text)))) | |
data IdentityCredentialsEC2 Source #
Metadata keys for identity-credentials/ec2/*.
Constructors
| ICEInfo | Information about the credentials in
|
| ICESecurityCredentials | Credentials for the instance identity role that allow on-instance software to identify itself to AWS to support features such as EC2 Instance Connect and AWS Systems Manager Default Host Management Configuration. These credentials have no policies attached, so they have no additional AWS API permissions beyond identifying the instance to the AWS feature. For more information, see Instance identity roles. |
Instances
Metadata keys for network/interfaces/macs/${mac}/*.
Constructors
| IDeviceNumber | The unique device number associated with that interface. The
device number corresponds to the device name; for example, a
|
| IInterfaceId | The ID of the network interface. |
| IIPV4Associations !Text | The private IPv4 addresses that are associated with each public-ip address and assigned to that interface. |
| IIPV6s | The IPv6 addresses associated with the interface. Returned only for instances launched into a VPC. |
| ILocalHostname | The private IPv4 DNS hostname of the instance. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). If this is a IPv6-only instance, this is the resource-based name. For more information about IPBN and RBN, see Amazon EC2 instance hostname types. |
| ILocalIPV4s | The private IPv4 addresses associated with the interface. If this is an IPv6-only network interface, this item is not set and results in an HTTP 404 response. |
| IMAC | The instance's MAC address. |
| INetworkCardIndex | The index of the network card. Some instance types support multiple network cards. |
| IOwnerId | The ID of the owner of the network interface. In multiple-interface environments, an interface can be attached by a third party, such as Elastic Load Balancing. Traffic on an interface is always billed to the interface owner. |
| IPublicHostname | The interface's public DNS (IPv4). This category is only
returned if the |
| IPublicIPV4s | The Elastic IP addresses associated with the interface. There may be multiple IP addresses on an instance. |
| ISecurityGroups | Security groups to which the network interface belongs. |
| ISecurityGroupIds | The IDs of the security groups to which the network interface belongs. |
| ISubnetId | The ID of the subnet in which the interface resides. |
| ISubnetIPV4_CIDRBlock | The IPv4 CIDR block of the subnet in which the interface resides. |
| ISubnetIPV6_CIDRBlock | The IPv6 CIDR block of the subnet in which the interface resides. |
| IVPCId | The ID of the VPC in which the interface resides. |
| IVPCIPV4_CIDRBlock | The primary IPv4 CIDR block of the VPC. |
| IVPCIPV4_CIDRBlocks | The IPv4 CIDR blocks for the VPC. |
| IVPCIPV6_CIDRBlocks | The IPv6 CIDR block of the VPC in which the interface resides. |
Instances
Metadata keys for placement/*.
Constructors
| AvailabilityZone | The Availability Zone in which the instance launched. |
| AvailabilityZoneId | The static Availability Zone ID in which the instance is launched. The Availability Zone ID is consistent across accounts. However, it might be different from the Availability Zone, which can vary by account. |
| GroupName | The name of the placement group in which the instance is launched. |
| HostId | The ID of the host on which the instance is launched. Applicable only to Dedicated Hosts. |
| PartitionNumber | The number of the partition in which the instance is launched. |
| Region | The AWS Region in which the instance is launched. |
Instances
| ToText Placement Source # | |
Defined in Amazonka.EC2.Metadata | |
| Generic Placement Source # | |
| Show Placement Source # | |
| Eq Placement Source # | |
| Ord Placement Source # | |
| type Rep Placement Source # | |
Defined in Amazonka.EC2.Metadata type Rep Placement = D1 ('MetaData "Placement" "Amazonka.EC2.Metadata" "amazonka-2.0-48plDWnPMAk3PGO79vdSa0" 'False) ((C1 ('MetaCons "AvailabilityZone" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "AvailabilityZoneId" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "GroupName" 'PrefixI 'False) (U1 :: Type -> Type))) :+: (C1 ('MetaCons "HostId" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "PartitionNumber" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Region" 'PrefixI 'False) (U1 :: Type -> Type)))) | |
Metadata keys for services/*.
Constructors
| Domain | The domain for AWS resources for the Region. |
| Partition | The partition that the resource is in. For standard AWS
Regions, the partition is |
Metadata keys for spot/*.
Constructors
| SInstanceAction | The action (hibernate, stop, or terminate) and the approximate time, in UTC, when the action will occur. This item is present only if the Spot Instance has been marked for hibernate, stop, or terminate. For more information, see instance-action. |
| STerminationTime | The approximate time, in UTC, that the operating system for your Spot Instance will receive the shutdown signal. This item is present and contains a time value (for example, 2015-01-05T18:02:00Z) only if the Spot Instance has been marked for termination by Amazon EC2. The termination-time item is not set to a time if you terminated the Spot Instance yourself. For more information, see termination-time. |
Metadata keys for tags/*.
Constructors
| Instance | The instance tags associated with the instance. Only available if you explicitly allow access to tags in instance metadata. For more information, see Allow access to tags in instance metadata. |
Identity Document
data IdentityDocument Source #
Represents an instance's identity document.
Note: Fields such as _instanceType are represented as unparsed Text and
will need to be manually parsed using fromText when the relevant types
from a library such as Amazonka.EC2 are brought into scope.
Constructors
| IdentityDocument | |
Fields
| |