Support AWS Instance Metadata Service (IMDS) Versions 1 and 2 (#38)

Author: zackproser

.circleci/config.yml

@@ -23,27 +23,49 @@ jobs:
           path: /tmp/logs
       - store_test_results:
           path: /tmp/logs
-  bats_ubuntu1604:
+  bats_ubuntu1604_imds_v1:
     # We need to run Docker Compose with privileged settings, which isn't supported by CircleCI's Docker executor, so
     # we have to use the machine executor instead.
     machine: true
     steps:
       - checkout
-      - run: docker-compose up --exit-code-from bats_ubuntu1604 bats_ubuntu1604
-  bats_ubuntu1804:
+      - run: docker-compose up --exit-code-from bats_ubuntu1604_imds_v1 bats_ubuntu1604_imds_v1
+  bats_ubuntu1604_imds_v2:
     # We need to run Docker Compose with privileged settings, which isn't supported by CircleCI's Docker executor, so
     # we have to use the machine executor instead.
     machine: true
     steps:
       - checkout
-      - run: docker-compose up --exit-code-from bats_ubuntu1804 bats_ubuntu1804
-  bats_ubuntu2004:
+      - run: docker-compose up --exit-code-from bats_ubuntu1604_imds_v2 bats_ubuntu1604_imds_v2
+
+  bats_ubuntu1804_imds_v1:
+    # We need to run Docker Compose with privileged settings, which isn't supported by CircleCI's Docker executor, so
+    # we have to use the machine executor instead.
+    machine: true
+    steps:
+      - checkout
+      - run: docker-compose up --exit-code-from bats_ubuntu1804_imds_v1 bats_ubuntu1804_imds_v1
+  bats_ubuntu1804_imds_v2:
+    # We need to run Docker Compose with privileged settings, which isn't supported by CircleCI's Docker executor, so
+    # we have to use the machine executor instead.
+    machine: true
+    steps:
+      - checkout
+      - run: docker-compose up --exit-code-from bats_ubuntu1804_imds_v2 bats_ubuntu1804_imds_v2
+  bats_ubuntu2004_imds_v1:
+    # We need to run Docker Compose with privileged settings, which isn't supported by CircleCI's Docker executor, so
+    # we have to use the machine executor instead.
+    machine: true
+    steps:
+      - checkout
+      - run: docker-compose up --exit-code-from bats_ubuntu2004_imds_v1 bats_ubuntu2004_imds_v1
+  bats_ubuntu2004_imds_v2:
     # We need to run Docker Compose with privileged settings, which isn't supported by CircleCI's Docker executor, so
     # we have to use the machine executor instead.
     machine: true
     steps:
       - checkout
-      - run: docker-compose up --exit-code-from bats_ubuntu2004 bats_ubuntu2004
+      - run: docker-compose up --exit-code-from bats_ubuntu2004_imds_v2 bats_ubuntu2004_imds_v2
 
 workflows:
   version: 2
@@ -53,6 +75,9 @@ workflows:
       - integration_test:
           context:
             - Gruntwork Admin
-      - bats_ubuntu1604
-      - bats_ubuntu1804
-      - bats_ubuntu2004
+      - bats_ubuntu1604_imds_v1
+      - bats_ubuntu1604_imds_v2
+      - bats_ubuntu1804_imds_v1
+      - bats_ubuntu1804_imds_v2
+      - bats_ubuntu2004_imds_v1
+      - bats_ubuntu2004_imds_v2

README.md

@@ -71,6 +71,17 @@ cp -r bash-commons/modules/bash-commons/src /opt/gruntwork/bash-commons
 sudo chown -R "my-os-username:my-os-group" /opt/gruntwork/bash-commons
 ```
 
+## Instance Metadata Service versions
+
+`bash-commons` supports both Instance Metadata Service (IMDS) version 1 and 2. Gruntwork and AWS both recommend using version 2 of the Instance Metadata Service whenever possible. Although version 1 is still supported and considered fully secure by AWS, version 2 has been specially hardened against specific threat vectors and is therefore preferable.
+
+To understand more about Instance Metadata Service version 2 and its features, read [the official AWS documentation on IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html).
+
+There are two ways to specify the version of the Instance Metadata Service that `bash-commons` should use:
+
+1. Set the environment variable `GRUNTWORK_BASH_COMMONS_IMDS_VERSION` to the version of IMDS that you wish to use. Valid values are either `1` or `2`.
+2. Change the value of `default_instance_metadata_version` to either `1` or `2`.
+
 #### Example of `dynamic-ubuntu-wait.sh` usage:
 
 You can use the `dynamic-ubuntu-wait.sh` command after you [install bash-commons](#install):

docker-compose.yml

@@ -1,4 +1,4 @@
-version: '3'
+version: "3"
 services:
   shellcheck:
     build:
@@ -8,7 +8,7 @@ services:
       - ./:/usr/local/src/bash-commons
     working_dir: /usr/local/src/bash-commons/.circleci
     command: ./shellcheck.sh
-  bats_ubuntu1604:
+  bats_ubuntu1604_imds_v1:
     build:
       context: ./
       dockerfile: Dockerfile.ubuntu16.04.bats
@@ -19,7 +19,34 @@ services:
     command: bats test
     # Necessary so we can run a mock EC2 metadata service on port 80 on a special IP
     privileged: true
-  bats_ubuntu1804:
+    # We intentionally omit the GRUNTWORK_BASH_COMMONS_IMDS_VERSION env var here to ensure the default behavior works as expected
+  bats_ubuntu1604_imds_v2:
+    build:
+      context: ./
+      dockerfile: Dockerfile.ubuntu16.04.bats
+    volumes:
+      # Mount all the files so you have "hot reload" of all changes from the host
+      - ./:/usr/local/src/bash-commons
+    working_dir: /usr/local/src/bash-commons
+    command: bats test
+    # Necessary so we can run a mock EC2 metadata service on port 80 on a special IP
+    privileged: true
+    environment:
+      # Signal to bash-commons module to use Instance Metadata Service version 2
+      - GRUNTWORK_BASH_COMMONS_IMDS_VERSION=2
+  bats_ubuntu1804_imds_v1:
+    build:
+      context: ./
+      dockerfile: Dockerfile.ubuntu18.04.bats
+    volumes:
+      # Mount all the files so you have "hot reload" of all changes from the host
+      - ./:/usr/local/src/bash-commons
+    working_dir: /usr/local/src/bash-commons
+    command: bats test
+    # Necessary so we can run a mock EC2 metadata service on port 80 on a special IP
+    privileged: true
+    # We intentionally omit the GRUNTWORK_BASH_COMMONS_IMDS_VERSION env var here to ensure the default behavior works as intended
+  bats_ubuntu1804_imds_v2:
     build:
       context: ./
       dockerfile: Dockerfile.ubuntu18.04.bats
@@ -30,7 +57,24 @@ services:
     command: bats test
     # Necessary so we can run a mock EC2 metadata service on port 80 on a special IP
     privileged: true
-  bats_ubuntu2004:
+    environment:
+      # Signal to bash-commons module to use Instance Metadata Service version 2
+      - GRUNTWORK_BASH_COMMONS_IMDS_VERSION=2
+  bats_ubuntu2004_imds_v1:
+    build:
+      context: ./
+      dockerfile: Dockerfile.ubuntu20.04.bats
+    volumes:
+      # Mount all the files so you have "hot reload" of all changes from the host
+      - ./:/usr/local/src/bash-commons
+    working_dir: /usr/local/src/bash-commons
+    command: bats test
+    # Necessary so we can run a mock EC2 metadata service on port 80 on a special IP
+    privileged: true
+    environment:
+      # Signal to bash-commons module to use Instance Metadata Service version 1
+      - GRUNTWORK_BASH_COMMONS_IMDS_VERSION=1
+  bats_ubuntu2004_imds_v2:
     build:
       context: ./
       dockerfile: Dockerfile.ubuntu20.04.bats
@@ -41,3 +85,6 @@ services:
     command: bats test
     # Necessary so we can run a mock EC2 metadata service on port 80 on a special IP
     privileged: true
+    environment:
+      # Signal to bash-commons module to use Instance Metadata Service version 2
+      - GRUNTWORK_BASH_COMMONS_IMDS_VERSION=2