{"id":13676525,"url":"https://github.com/aws/amazon-ec2-metadata-mock","last_synced_at":"2025-05-14T23:02:16.353Z","repository":{"id":37799042,"uuid":"240406135","full_name":"aws/amazon-ec2-metadata-mock","owner":"aws","description":"A tool to simulate Amazon EC2 instance metadata","archived":false,"fork":false,"pushed_at":"2025-04-27T17:01:18.000Z","size":564,"stargazers_count":280,"open_issues_count":5,"forks_count":46,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-05-08T00:07:54.375Z","etag":null,"topics":["aws-ec2","ec2-instance-metadata","ec2-instance-metadata-mock","hacktoberfest","scheduled-events-mock","spot-interruption-mock"],"latest_commit_sha":null,"homepage":"https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-02-14T01:45:44.000Z","updated_at":"2025-05-05T14:33:55.000Z","dependencies_parsed_at":"2025-02-28T12:07:51.935Z","dependency_job_id":"0be20a23-d88b-4992-8661-0ef6cc4d4cdd","html_url":"https://github.com/aws/amazon-ec2-metadata-mock","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Famazon-ec2-metadata-mock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Famazon-ec2-metadata-mock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Famazon-ec2-metadata-mock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Famazon-ec2-metadata-mock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws","download_url":"https://codeload.github.com/aws/amazon-ec2-metadata-mock/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254243353,"owners_count":22038044,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws-ec2","ec2-instance-metadata","ec2-instance-metadata-mock","hacktoberfest","scheduled-events-mock","spot-interruption-mock"],"created_at":"2024-08-02T13:00:28.966Z","updated_at":"2025-05-14T23:02:16.272Z","avatar_url":"https://github.com/aws.png","language":"Go","funding_links":[],"categories":["Go","Workloads"],"sub_categories":["Tools"],"readme":"# Amazon EC2 Metadata Mock\n\n**Amazon EC2 Metadata Mock (AEMM)** is a tool to simulate [Amazon EC2 instance metadata service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) for local testing.\n\n\u003cbr/\u003e\n\u003cp\u003e\n   \u003ca href=\"https://gallery.ecr.aws/aws-ec2/amazon-ec2-metadata-mock\"\u003e\n   \u003cimg src=\"https://img.shields.io/github/v/release/aws/amazon-ec2-metadata-mock?color=yellowgreen\u0026label=latest%20release\u0026sort=semver\" alt=\"latest release\"\u003e\n   \u003c/a\u003e\n   \u003ca href=\"https://go.dev/doc/go1.23\"\u003e\n   \u003cimg src=\"https://img.shields.io/github/go-mod/go-version/aws/amazon-ec2-metadata-mock?color=blueviolet\" alt=\"go-version\"\u003e\n   \u003c/a\u003e\n   \u003ca href=\"https://opensource.org/licenses/Apache-2.0\"\u003e\n   \u003cimg src=\"https://img.shields.io/badge/License-Apache%202.0-ff69b4.svg?color=orange\" alt=\"license\"\u003e\n   \u003c/a\u003e\n   \u003ca href=\"https://gallery.ecr.aws/aws-ec2/amazon-ec2-metadata-mock\"\u003e\n   \u003cimg src=\"https://img.shields.io/docker/pulls/amazon/amazon-ec2-metadata-mock\" alt=\"docker-pulls\"\u003e\n   \u003c/a\u003e\n\u003c/p\u003e\n\n![EC2 Metadata Mock CI and Release](https://github.com/aws/amazon-ec2-metadata-mock/workflows/EC2%20Metadata%20Mock%20CI%20and%20Release/badge.svg)\n\n# Table of Contents\n\n   * [Project Summary](#project-summary)\n   * [Major Features](#major-features)\n   * [Supported Metadata Categories](#supported-metadata-categories)\n   * [Getting Started](#getting-started)\n      * [Installation](#installation)\n      * [Starting AEMM](#starting-aemm)\n      * [Making a Request](#making-a-request)\n   * [Configuration](#configuration)\n      * [Defaults](#defaults)\n      * [Overrides](#overrides)\n   * [Usage](#usage)\n      * [Spot Interruption](#spot-interruption)\n      * [Scheduled Events](#events)\n      * [Auto Scaling Group Lifecycle Termination](#Auto-Scaling-Group-Lifecycle-Termination)\n      * [Instance Metadata Service Versions](#instance-metadata-service-versions)\n      * [Static Metadata](#static-metadata)\n   * [Troubleshooting](#troubleshooting)\n      * [Warnings and Expected Outcome](#warnings-and-expected-outcome)\n   * [Integrations](#integrations)\n   * [Building](#building)\n   * [Communication](#communication)\n   * [Contributing](#contributing)\n   * [License](#license)\n\n# Summary\nAWS EC2 Instance metadata is data about your instance that you can use to configure or manage the running instance. Instance metadata is divided into categories like hostname, instance id, maintenance events, spot instance action, autoscaling target-lifecycle-state. See the complete list of metadata categories [here](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html).\n\nThe instance metadata can be accessed from within the instance. Some instance metadata is available only when an instance is affected by the event. E.g. A Spot instance's metadata item `spot/instance-action` is available only when AWS decides to interrupt the Spot instance.\nThese bring forth some challenges like not being able to test one's application in the event of Spot interruption or other such events and requiring an EC2 instance for testing.\nThis project attempts to bridge these gaps by providing mocks for **most** of these metadata categories. The mock responses are designed to replicate those from the actual instance metadata service for accurate, local testing.\n\n# Major Features\n- Simulate Spot Instance Interruption (ITN) \u0026 EC2 Rebalance Recommendation events for Spot instances\n- Delay mock response from the mock serve start time\n- Configure metadata in mock responses via CLI flags, config file, env variables\n- IMDSv1 and v2 support (configurable for IMDSv2 support only)\n- Save processed configuration to a local file\n\n# Supported Metadata Categories\nAEMM supports most [metadata categories](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html) **except for:**\n* ancestor-ami-ids\n* events/maintenance/history\n\nPRs for any of the above paths are always welcome! Please see our [Contributing](#contributing) section for details.\n\n## Windows Metadata\nPaths specific to Windows instances such as `elastic-gpus/associations/elastic-gpu-id` will **not** be supported at this time. Feel free to open\nan issue to discuss if you would like AEMM to support these paths in the future.\n\n# Getting Started\nAEMM is simple to get up and running.\n\n## Installation\n\n### Install w/ Homebrew\n\n```\nbrew tap aws/tap\nbrew install ec2-metadata-mock\n```\n### Install w/ Curl\n\n#### MacOS/Linux\n```\ncurl -Lo ec2-metadata-mock https://github.com/aws/amazon-ec2-metadata-mock/releases/download/v1.13.0/ec2-metadata-mock-`uname | tr '[:upper:]' '[:lower:]'`-amd64\nchmod +x ec2-metadata-mock\n```\n\n#### ARM Linux\n```\ncurl -Lo ec2-metadata-mock https://github.com/aws/amazon-ec2-metadata-mock/releases/download/v1.13.0/ec2-metadata-mock-linux-arm\n```\n\n```\ncurl -Lo ec2-metadata-mock https://github.com/aws/amazon-ec2-metadata-mock/releases/download/v1.13.0/ec2-metadata-mock-linux-arm64\n```\n\n#### Windows\n```\ncurl -Lo ec2-metadata-mock https://github.com/aws/amazon-ec2-metadata-mock/releases/download/v1.13.0/ec2-metadata-mock-windows-amd64.exe\n```\n\n### Install w/ Docker\n```\ndocker pull public.ecr.aws/aws-ec2/amazon-ec2-metadata-mock:v1.13.0\ndocker run -it --rm -p 1338:1338 public.ecr.aws/aws-ec2/amazon-ec2-metadata-mock:v1.13.0\n```\n\n### On Kubernetes\n#### Supported versions\n* Kubernetes \u003e= 1.14\n\n#### Helm\nWe are hosting helm-charts for Amazon EC2 Metadata Mock in ecr-public. The chart for this project is hosted in [helm/amazon-ec2-metadata-mock](https://gallery.ecr.aws/aws-ec2/helm/amazon-ec2-metadata-mock).\n\nDetailed instructions on installing Amazon EC2 Metadata Mock using Helm can be found here [Helm README](https://github.com/aws/amazon-ec2-metadata-mock/blob/main/helm/amazon-ec2-metadata-mock/README.md)\n\n#### kubectl\nkubectl apply -f https://github.com/aws/amazon-ec2-metadata-mock/releases/download/v1.13.0/all-resources.yaml\n\n## Starting AEMM\nUse `ec2-metadata-mock --help` to view examples and explanations of supported flags and commands:\n\n```\n$ ec2-metadata-mock --help\n\nec2-metadata-mock is a tool to mock Amazon EC2 instance metadata.\n\nUsage:\n  ec2-metadata-mock \u003ccommand\u003e [arguments] [flags]\n  ec2-metadata-mock [command]\n\nExamples:\n  ec2-metadata-mock --mock-delay-sec 10\tmocks all metadata paths\n  ec2-metadata-mock spot --action terminate\tmocks spot ITN only\n\nAvailable Commands:\n  events        Mock EC2 maintenance events\n  help          Help about any command\n  spot          Mock EC2 Spot interruption notice\n  asglifecycle  Mock ASG target-lifecycle-state changes from InService to Terminated\n\nFlags:\n      --asg-termination-delay-sec int      asg termination delay in seconds, relative to the application start time (default: 0 seconds)\n      --asg-termination-trigger-time int   asg termination trigger time in RFC3339 format. This takes priority over asg-termination-delay-sec (default: none)\n  -c, --config-file string                 config file for cli input parameters in json format (default: $HOME/aemm-config.json)\n  -h, --help                               help for ec2-metadata-mock\n  -n, --hostname string                    the HTTP hostname for the mock url (default: 0.0.0.0)\n  -I, --imdsv2                             whether to enable IMDSv2 only, requiring a session token when submitting requests (default: false, meaning both IMDS v1 and v2 are enabled)\n  -d, --mock-delay-sec int                 spot itn delay in seconds, relative to the application start time (default: 0 seconds)\n  -x, --mock-ip-count int                  number of IPs in a cluster that can receive a Spot Interrupt Notice and/or Scheduled Event (default 2)\n      --mock-trigger-time string           spot itn trigger time in RFC3339 format. This takes priority over mock-delay-sec (default: none)\n  -p, --port string                        the HTTP port where the mock runs (default: 1338)\n      --rebalance-delay-sec int            rebalance rec delay in seconds, relative to the application start time (default: 0 seconds)\n      --rebalance-trigger-time string      rebalance rec trigger time in RFC3339 format. This takes priority over rebalance-delay-sec (default: none)\n  -s, --save-config-to-file                whether to save processed config from all input sources in .ec2-metadata-mock/.aemm-config-used.json in $HOME or working dir, if homedir is not found (default: false)\n  -v, --version                            version for ec2-metadata-mock\n\nUse \"ec2-metadata-mock [command] --help\" for more information about a command.\n```\n\nStarting AEMM with default configurations using `ec2-metadata-mock` will start the server on the default host and port:\n\n```\n$ ec2-metadata-mock\n\nInitiating ec2-metadata-mock for all mocks on port 1338\nServing the following routes: /latest/meta-data/product-codes, /latest/meta-data/iam/info, /latest/meta-data/instance-type, ...(truncated for readability)\n```\n\n## Making a Request\nWith the server running, send a request to one of the supported routes above using `curl localhost:1338/\u003croute\u003e`. Example request to display all supported routes:\n\n```\n$ curl localhost:1338/latest/meta-data\n\nami-id\nami-launch-index\nami-manifest-path\nautoscaling/\nblock-device-mapping/\nelastic-inference/\nevents/\nhostname\niam/\ninstance-action\ninstance-id\ninstance-life-cycle\ninstance-type\nkernel-id\nlocal-hostname\nlocal-ipv4\nmac\nnetwork/\nplacement/\nproduct-codes\npublic-hostname\npublic-ipv4\npublic-keys/\nramdisk-id\nreservation-id\nsecurity-groups\nservices/\nspot/\ntags/\n```\n\n\n# Configuration\nAEMM's wide-range of configurability ranges from overriding port numbers to enabling IMDSv2-only to updating specific metadata values and paths.\nThese configurations can be loaded from various sources with a deterministic precedence.\n\n## Defaults\nDefaults for AEMM configuration are sourced throughout code. Examples below:\n* **CLI flags**\n  * [server config defaults](https://github.com/aws/amazon-ec2-metadata-mock/blob/master/pkg/config/server.go#L22)\n* **Metadata mock responses**\n  * [aemm-metadata-default-values.json](https://github.com/aws/amazon-ec2-metadata-mock/blob/master/pkg/config/defaults/aemm-metadata-default-values.json)\n* **Commands**\n  * [events](https://github.com/aws/amazon-ec2-metadata-mock/blob/master/pkg/cmd/events/events.go#L72)\n\n## Overrides\nAEMM supports configuration from various sources including: cli flags, env variables, and config files. Details regarding\nconfiguration steps, behavior, and precedence are outlined [here](https://github.com/aws/amazon-ec2-metadata-mock/blob/master/docs/configuration.md).\n\n# Usage\nAEMM is primarily used as a developer tool to help test behavior related to Metadata Service. Popular use cases include: emulating spot instance interrupts after a designated delay, mocking scheduled maintenance events, IMDSv2 migrations,\nand requesting static metadata. This section outlines the common use cases of AEMM; advanced usage and behavior are documented [here](https://github.com/aws/amazon-ec2-metadata-mock/blob/master/docs/usage.md).\n\n## Spot Interruption\nTo view the available flags for the Spot Interruption command use `spot --help`:\n```\n$ ec2-metadata-mock spot --help\nMock EC2 Spot interruption notice\n\nUsage:\n  ec2-metadata-mock spot [--action ACTION] [flags]\n\nAliases:\n  spot\n\nExamples:\n  ec2-metadata-mock spot -h \tspot help\n  ec2-metadata-mock spot -d 5 --action terminate\t\tmocks spot interruption only\n\nFlags:\n  -a, --action string                  action in the spot interruption notice (default: terminate)\n                                       action can be one of the following: terminate,hibernate,stop\n  -h, --help                           help for spot\n  -r, --rebalance-rec-time string      rebalance rec time specifies the approximate time when the rebalance recommendation notification will be emitted in RFC3339 format\n  -t, --time string                    termination time specifies the approximate time when the spot instance will receive the shutdown signal in RFC3339 format to execute instance action E.g. 2020-01-07T01:03:47Z (default: request time + 2 minutes in UTC)\n\nGlobal Flags:\n      --asg-termination-delay-sec int      asg termination delay in seconds, relative to the application start time (default: 0 seconds)\n      --asg-termination-trigger-time int   asg termination trigger time in RFC3339 format. This takes priority over asg-termination-delay-sec (default: none)\n  -c, --config-file string                 config file for cli input parameters in json format (default: $HOME/aemm-config.json)\n  -h, --help                               help for ec2-metadata-mock\n  -n, --hostname string                    the HTTP hostname for the mock url (default: 0.0.0.0)\n  -I, --imdsv2                             whether to enable IMDSv2 only, requiring a session token when submitting requests (default: false, meaning both IMDS v1 and v2 are enabled)\n  -d, --mock-delay-sec int                 spot itn delay in seconds, relative to the application start time (default: 0 seconds)\n  -x, --mock-ip-count int                  number of IPs in a cluster that can receive a Spot Interrupt Notice and/or Scheduled Event (default 2)\n      --mock-trigger-time string           spot itn trigger time in RFC3339 format. This takes priority over mock-delay-sec (default: none)\n  -p, --port string                        the HTTP port where the mock runs (default: 1338)\n      --rebalance-delay-sec int            rebalance rec delay in seconds, relative to the application start time (default: 0 seconds)\n      --rebalance-trigger-time string      rebalance rec trigger time in RFC3339 format. This takes priority over rebalance-delay-sec (default: none)\n  -s, --save-config-to-file                whether to save processed config from all input sources in .ec2-metadata-mock/.aemm-config-used.json in $HOME or working dir, if homedir is not found (default: false)\n  -v, --version                            version for ec2-metadata-mock\n```\n\n1.) **Starting AEMM with `spot`**:  `spot` routes available immediately:\n```\n$ ec2-metadata-mock spot\nInitiating ec2-metadata-mock for EC2 Spot interruption notice on port 1338\nServing the following routes: ... (truncated for readability)\n```\nSend the request:\n```\n$ curl localhost:1338/latest/meta-data/spot/instance-action\n{\n\t\"action\": \"terminate\",\n\t\"time\": \"2020-04-24T17:11:44Z\"\n}\n```\n\n\n2.) **Starting AEMM with `spot` after Delay**: Users can apply a *delay* duration in seconds for when the `spot` metadata will become available:\n\n```\n$ ec2-metadata-mock spot -d 10\nInitiating ec2-metadata-mock for EC2 Spot interruption notice on port 1338\n\nFlags:\nmock-delay-sec: 10\n\nServing the following routes: ... (truncated for readability)\n```\n\nSending a request to `spot` paths before the delay has passed will return **404 - Not Found:**\n```\n$ curl localhost:1338/latest/meta-data/spot/instance-action\n\n\u003c?xml version=\"1.0\" encoding=\"iso-8859-1\"?\u003e\n\u003c!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"\n\t\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\"\u003e\n\u003chtml xmlns=\"http://www.w3.org/1999/xhtml\" xml:lang=\"en\" lang=\"en\"\u003e\n \u003chead\u003e\n  \u003ctitle\u003e404 - Not Found\u003c/title\u003e\n \u003c/head\u003e\n \u003cbody\u003e\n  \u003ch1\u003e404 - Not Found\u003c/h1\u003e\n \u003c/body\u003e\n\u003c/html\u003e\n\n\n// Server log\nDelaying the response by 10s as requested. The mock response will be available in 2s. Returning `notFoundResponse` for now\n```\n\nOnce the delay is complete, querying `spot` paths return expected results:\n```\n$ curl localhost:1338/latest/meta-data/spot/instance-action\n\n{\n\t\"action\": \"terminate\",\n\t\"time\": \"2020-04-24T17:19:32Z\"\n}\n\n```\n\nAlternatively a trigger time can be configured using `--mock-trigger-time` which can be useful to synchronize spot interruption simulation over multiple instances.\n\n### EC2 Instance Rebalance Recommendation\nThe Rebalance Recommendation notification is also available under the **spot** command as it is sent when EC2 emits this signal when Spot Instances are at an elevated risk of interruption:\n```\n$ ec2-metadata-mock spot\nInitiating ec2-metadata-mock for EC2 Spot interruption notice on port 1338\nServing the following routes: ... (truncated for readability)\n```\nSend the request:\n```\n$ curl localhost:1338/latest/meta-data/events/recommendations/rebalance\n{\n        \"noticeTime\": \"2020-10-16T19:18:24Z\"\n}\n```\n*Note: although Rebalance Recommendation path contains `events` it will **not be available** when starting AEMM with the `events` command*\n\n\n## Events\nSimilar to spot, the `events` command, view the local flags using `events --help`:\n\n```\n$ ec2-metadata-mock events --help\nMock EC2 Scheduled Events\n\nUsage:\n  ec2-metadata-mock events [--code CODE] [--state STATE] [--not-after] [--not-before-deadline] [flags]\n\nAliases:\n  events, se, scheduledevents\n\nExamples:\n  ec2-metadata-mock events -h \tevents help\n  ec2-metadata-mock events -o instance-stop --state active -d\t\tmocks an active and upcoming scheduled event for instance stop with a deadline for the event start time\n\nFlags:\n  -o, --code string                  event code in the scheduled event (default: system-reboot)\n                                     event-code can be one of the following: instance-reboot,system-reboot,system-maintenance,instance-retirement,instance-stop\n  -h, --help                         help for events\n  -a, --not-after string             the latest end time for the scheduled event in RFC3339 format E.g. 2020-01-07T01:03:47Z default: application start time + 7 days in UTC))\n  -b, --not-before string            the earliest start time for the scheduled event in RFC3339 format E.g. 2020-01-07T01:03:47Z (default: application start time in UTC)\n  -l, --not-before-deadline string   the deadline for starting the event in RFC3339 format E.g. 2020-01-07T01:03:47Z (default: application start time + 9 days in UTC)\n  -t, --state string                 state of the scheduled event (default: active)\n                                     state can be one of the following: active,completed,canceled\n\n(Truncated Global Flags for readability)\n```\n\n1.) **Starting AEMM with `events`**: `events` route available immediately and `spot` routes will no longer be available due to the implementation of Commands [detailed here](https://github.com/aws/amazon-ec2-metadata-mock/blob/master/docs/usage.md):\n\n```\n$ ec2-metadata-mock events --code instance-reboot -a 2020-01-07T01:03:47Z  -b 2020-01-01T01:03:47Z -l 2020-01-10T01:03:47Z --state completed\nInitiating ec2-metadata-mock for EC2 Events on port 1338\nServing the following routes: ... (truncated for readability)\n\n```\n\nSend the request:\n```\n$ curl localhost:1338/latest/meta-data/events/maintenance/scheduled\n{\n\t\"Code\": \"instance-reboot\",\n\t\"Description\": \"The instance is scheduled for instance-reboot\",\n\t\"State\": \"completed\",\n\t\"EventId\": \"instance-event-1234567890abcdef0\",\n\t\"NotBefore\": \"1 Jan 2020 01:03:47 GMT\",\n\t\"NotAfter\": \"7 Jan 2020 01:03:47 GMT\",\n\t\"NotBeforeDeadline\": \"10 Jan 2020 01:03:47 GMT\"\n}\n```\n\n## Auto Scaling Group Lifecycle Termination\nThe `asglifecycle` command will generate a asg lifecycle termination event after a user-specified delay or termination time.\n\n```\n$ ec2-metadata-mock asglifecycle --help\nMock EC2 Auto Scaling Group Lifecycle Termination State\n\nUsage:\n  ec2-metadata-mock asglifecycle\n\nAliases:\n  asglifecycle, autoscaling, asg\n```\n\nSend the request:\n```\n$ curl localhost:1338/latest/meta-data/autoscaling/target-lifecycle-state\nTerminated\n```\n\n## Instance Metadata Service Versions\nAEMM supports [both versions](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html) of Instance Metadata service. By default, AEMM starts with supporting v1 and v2; however, it is possible to enable **IMDSv2 only** via overrides.\n\n1.) **Starting AEMM with IMDSv2 only:** session tokens are required for all requests; v1 requests will return **401 - Unauthorized:**\n\n```\n$ ec2-metadata-mock --imdsv2\n```\nSend a v1 request:\n```\n$ curl localhost:1338/latest/meta-data/mac\n\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\"\u003e\n\u003chtml xmlns=\"http://www.w3.org/1999/xhtml\" xml:lang=\"en\" lang=\"en\"\u003e\n   \u003chead\u003e\n      \u003ctitle\u003e401 - Unauthorized\u003c/title\u003e\n   \u003c/head\u003e\n   \u003cbody\u003e\n      \u003ch1\u003e401 - Unauthorized\u003c/h1\u003e\n   \u003c/body\u003e\n\u003c/html\u003e\n```\n\nSend a v2 request:\n```\nTOKEN=`curl -X PUT \"localhost:1338/latest/api/token\" -H \"X-aws-ec2-metadata-token-ttl-seconds: 21600\"` \\\n\u0026\u0026 curl -H \"X-aws-ec2-metadata-token: $TOKEN\" localhost:1338/latest/meta-data/mac\n0e:49:61:0f:c3:11\n```\n\nRequesting a token outside the TTL bounds (between 1-2600 seconds) will return **400 - Bad Request:**\n```\n$ curl -X PUT \"localhost:1338/latest/api/token\" -H \"X-aws-ec2-metadata-token-ttl-seconds: 0\"\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\"\u003e\n\u003chtml xmlns=\"http://www.w3.org/1999/xhtml\" xml:lang=\"en\" lang=\"en\"\u003e\n   \u003chead\u003e\n      \u003ctitle\u003e400 - Bad Request\u003c/title\u003e\n   \u003c/head\u003e\n   \u003cbody\u003e\n      \u003ch1\u003e400 - Bad Request\u003c/h1\u003e\n   \u003c/body\u003e\n\u003c/html\u003e\n```\n\nProviding an expired token is synonymous to no token at all resulting in **401 - Unauthorized**.\n\n## Static Metadata\nStatic metadata is classified as instance-specific metadata that is **always** available regardless of which command is used to start the tool.\n\nExamples of static metadata include *all* [metadata categories](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html) from the non-dynamic category table (ami-id, instance-id, mac) **except for events and spot categories (classified as commands in AEMM).**\n\n*Note that 'static' naming is used within the context of this tool ONLY*\n\n1.) **Requesting static metadata `instance-id`**:\n```\n$ ec2-metadata-mock\n```\n\nSend the request:\n```\n$ curl localhost:1338/latest/meta-data/instance-id\ni-1234567890abcdef0\n```\n\nDetails on overriding static metadata values and behavior can be found [here](https://github.com/aws/amazon-ec2-metadata-mock/blob/master/docs/usage.md#static-metadata)\n\n# Troubleshooting\n\n## Warnings and Expected Outcome\n|Warning Displayed|Cause|Effect|\n|---|---|---|\n|Warning: Config File _file name_ Not Found in _locations_ |input configuration file not found|other input sources are used (See above for details)|\n|Warning: Failed to save the final configuration to local file - Failed to create directory for final configuration at _path/to/dir_: _error string_|Failure to create the hidden directory `.amazon-ec2-metadata-mock` to store the final configuration file| configuration used by the tool is NOT saved to a local file. The tool continues with its primary job of mocking metadata paths |\n|Warning: Failed to save the final configuration to local file - The destination '_path/to/dir_' for saving the configuration already exists, but is not a directory |Failure to create the hidden directory `.amazon-ec2-metadata-mock` to store the final configuration file, because a resource by that name already exists| configuration used by the tool is NOT saved to a local file. The tool continues with its primary job of mocking metadata paths |\n|Warning: Failed to save the final configuration to local file _path/to/local/file_: _error string_  |Failure to save final configuration to a file |configuration used by the tool is NOT saved to a local file. The tool continues with its primary job of mocking metadata paths |\n|Warning: Failed to find home directory due to error: _error string_|Failure to get home directory| working directory is used instead|\n\n# Integrations\n[aws-node-termination-handler](https://github.com/aws/aws-node-termination-handler) uses AEMM in its [e2e test suite](https://github.com/aws/aws-node-termination-handler/tree/master/test/e2e)\nto mock the metadata service and interrupt events.\n\nIn the [NTH imds-v2-test](https://github.com/aws/aws-node-termination-handler/blob/master/test/e2e/imds-v2-test), Helm is used\nto download the latest AEMM release, install it onto the cluster, and start it with imdsv2-only access. NTH then acquires the v2 token from AEMM, consumes the interrupt event, then\ncordons the worker node and evicts the test pod, thus validating NTH functionality. For more details on NTH e2e tests refer to the documentation [here](https://github.com/aws/aws-node-termination-handler/blob/master/test/README.md).\n\n# Building\nFor build instructions, please consult [BUILD.md](https://github.com/aws/amazon-ec2-metadata-mock/blob/master/BUILD.md)\n\n# Communication\nIf you've run into a bug or have a new feature request, please open an [issue](https://github.com/aws/amazon-ec2-metadata-mock/issues/new).\n\nCheck out the open source [Amazon EC2 Spot Instances Integrations Roadmap](https://github.com/aws/ec2-spot-instances-integrations-roadmap) to see what we're working on and give us feedback!\n\n# Contributing\nContributions are welcome! Please read our [guidelines](https://github.com/aws/amazon-ec2-metadata-mock/blob/master/CONTRIBUTING.md) and our [Code of Conduct](https://github.com/aws/amazon-ec2-metadata-mock/blob/master/CODE_OF_CONDUCT.md)\n\n# License\nThis project is licensed under the Apache-2.0 License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Famazon-ec2-metadata-mock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws%2Famazon-ec2-metadata-mock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Famazon-ec2-metadata-mock/lists"}