Merge pull request #41 from iamhopaul123/add-v4-doc

Add doc for v4 metadata usage

Author: iamhopaul123

README.md

@@ -20,6 +20,8 @@ This repository contains the source code for the project. To use it, pull the [a
   * [Metadata](docs/features.md#metadata)
     * [Task Metadata V2](docs/features.md#task-metadata-v2)
     * [Task Metadata V3](docs/features.md#task-metadata-v3)
+    * [Task Metadata V4](docs/features.md#task-metadata-v4)
+    * [Generic Metadata](docs/features.md#generic-metadata-injection)
 
 #### Security disclosures
 

docs/features.md

@@ -48,4 +48,14 @@ V3 Metadata uses the `ECS_CONTAINER_METADATA_URI` environment variable. Unlike V
 
 In most cases, you can set `ECS_CONTAINER_METADATA_URI` to `http://169.254.170.2/v3`.
 
-However, in a few cases, this will not work. This is because the Local Endpoints container needs to be able to determine which container a request for V3 metadata came from. Local Endpoints attempts to use the IP address in the request to determine this. If you use the [example Docker Compose file](examples/docker-compose.yml) with a bridge network, then this IP lookup will work. However, if you use different network settings, then the Local Endpoints will not be able to determine which container a request came from. In this case, set `ECS_CONTAINER_METADATA_URI` to `http://169.254.170.2/v3/containers/{container name}`. The value for `container name` can be any unique substring of your container's name. By setting a custom request URL, the Local Endpoints container can determine which container a request came from.
+However, in a few cases, this will not work. This is because the Local Endpoints container needs to be able to determine which container a request for V3 metadata came from. Local Endpoints attempts to use the IP address in the request to determine this. If you use the [example Docker Compose file](../examples/docker-compose.yml) with a bridge network, then this IP lookup will work. However, if you use different network settings, then the Local Endpoints will not be able to determine which container a request came from. In this case, set `ECS_CONTAINER_METADATA_URI` to `http://169.254.170.2/v3/containers/{container name}`. The value for `container name` can be any unique substring of your container's name. By setting a custom request URL, the Local Endpoints container can determine which container a request came from.
+
+#### Task Metadata V4
+
+V4 Metadata uses `ECS_CONTAINER_METADATA_URI_V4` environment variable. In most cases, you can set `ECS_CONTAINER_METADATA_URI_V4` to `http://169.254.170.2/v3`. Similarly, in a few cases when Local Endpoints container doesn't know which container a request came from, you have to set `ECS_CONTAINER_METADATA_URI_V4` to `http://169.254.170.2/v3/containers/{container name}`. Please see the description above on V3 to understand why you'll need to specify the container name in the path.
+
+However, compared to V3, V4 includes additional network metadata when querying the task metadata endpoint (see [here](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-metadata-endpoint-v4.html)). Please refer to this [example](../examples/v4) if you want to include those additional V4 metadata. You can use the generic metadata injection feature (described below) to add the additional metadata fields included in V4.
+
+#### Generic Metadata Injection
+
+As mentioned above in the previous section, to inject generic metadata, you'll need to have those additional metadata in JSON files. Then specify paths for the JSON files by using `CONTAINER_METADATA_PATH` and `TASK_METADATA_PATH` environment variables. More specifically, `CONTAINER_METADATA_PATH` is the metadata for each container, which will override their counterparts in the normal response. Also, `TASK_METADATA_PATH` is for task level metadata, which is used only for overriding the top level fields in the task metadata response. If you specify both `CONTAINER_METADATA_PATH` and `TASK_METADATA_PATH`, then the metadata from `CONTAINER_METADATA_PATH` will be included in the `Containers` section of the task metadata response. See example for overriding task metadata response [here](../example/generic).

examples/generic/task-metadata.json

@@ -0,0 +1,15 @@
+{
+  "Cluster": "arn:aws:ecs:us-west-2:ExampleAWSAccountNo1;:cluster/default",
+  "TaskARN": "arn:aws:ecs:us-west-2:ExampleAWSAccountNo1;:task/default/febee046097849aba589d4435207c04a",
+  "Family": "query-metadata",
+  "Revision": "7",
+  "DesiredStatus": "RUNNING",
+  "KnownStatus": "RUNNING",
+  "Limits": {
+      "CPU": 0.25,
+      "Memory": 512
+  },
+  "PullStartedAt": "2020-03-26T22:25:40.420726088Z",
+  "PullStoppedAt": "2020-03-26T22:26:22.235177616Z",
+  "AvailabilityZone": "us-west-2c"
+}

examples/v4/container-metadata.json

@@ -0,0 +1,21 @@
+{
+    "Networks": [
+        {
+            "NetworkMode": "awsvpc",
+            "IPv4Addresses": [
+                "10.0.0.61"
+            ],
+            "AttachmentIndex": 0,
+            "IPv4SubnetCIDRBlock": "10.0.0.0/24",
+            "MACAddress": "0a:d2:d0:80:b6:b4",
+            "DomainNameServers": [
+                "10.0.0.2"
+            ],
+            "DomainNameSearchList": [
+                "us-west-2.compute.internal"
+            ],
+            "PrivateDNSName": "ip-10-0-0-61.us-west-2.compute.internal",
+            "SubnetGatewayIpv4Address": ""
+        }
+    ]
+}