From 611ecb5d624708b81a4d96a16f98aa8f71fcc189 Mon Sep 17 00:00:00 2001
From: Abraham Egnor <abraham.egnor@mongodb.com>
Date: Mon, 28 Aug 2023 08:55:55 -0400
Subject: [PATCH] DRIVERS-2570 Report docker or kubernetes environment in
 handshake (#1454)

---
 source/mongodb-handshake/handshake.rst | 48 ++++++++++++++++++++------
 1 file changed, 38 insertions(+), 10 deletions(-)

diff --git a/source/mongodb-handshake/handshake.rst b/source/mongodb-handshake/handshake.rst
index d92acef001..90e6156800 100644
--- a/source/mongodb-handshake/handshake.rst
+++ b/source/mongodb-handshake/handshake.rst
@@ -167,10 +167,15 @@ provided as a BSON object. This object has the following structure::
             platform: "<string>",
             /* OPTIONAL */
             env: {
-                name: "<string>",         /* REQUIRED */
+                name: "<string>",         /* OPTIONAL */
                 timeout_sec: 42,          /* OPTIONAL */
                 memory_mb: 1024,          /* OPTIONAL */
-                region: "<string>"        /* OPTIONAL */
+                region: "<string>",       /* OPTIONAL */
+                /* OPTIONAL */
+                container: {
+                    runtime: "<string>",  /* OPTIONAL */
+                    orchestrator: "<string>"  /* OPTIONAL */
+                }
             }
         }
     }
@@ -313,8 +318,19 @@ client.env
 
 This value is optional and is not application configurable.
 
-Information about the Function-as-a-Service (FaaS) environment, captured from environment
-variables.  The ``client.env.name`` field is determined by which of the following environment
+Information about the execution environment, including Function-as-a-Service (FaaS)
+identification and container runtime.
+
+The contents of ``client.env`` MUST be adjusted to keep the handshake below the size limit;
+see `Limitations`_ for specifics.
+
+If no fields of ``client.env`` would be populated, ``client.env`` MUST be entirely omitted.
+
+FaaS
+^^^^
+
+FaaS details are captured in the ``name``, ``timeout_sec``, ``memory_mb``, and ``region`` fields
+of ``client.env``. The ``name`` field is determined by which of the following environment
 variables are populated:
 
 +----------------+----------------------------------------------------------+
@@ -329,12 +345,12 @@ variables are populated:
 
 .. [#] ``AWS_EXECUTION_ENV`` must start with the string ``"AWS_Lambda_"``.
 
-If none of those variables are populated the ``client.env`` value MUST be entirely omitted.  When
+If none of those variables are populated the other FaaS values MUST be entirely omitted.  When
 variables for multiple ``client.env.name`` values are present, ``vercel`` takes precedence over
-``aws.lambda``; any other combination MUST cause ``client.env`` to be entirely omitted.
+``aws.lambda``; any other combination MUST cause the other FaaS values to be entirely omitted.
 
-Depending on which ``client.env.name`` has been selected, other fields in ``client.env`` SHOULD
-be populated:
+Depending on which ``client.env.name`` has been selected, other FaaS fields in ``client.env``
+SHOULD be populated:
 
 +----------------+----------------------------+-------------------------------------+---------------+
 | Name           | Field                      | Environment Variable                | Expected Type |
@@ -355,8 +371,19 @@ be populated:
 Missing variables or variables with values not matching the expected type MUST cause the
 corresponding ``client.env`` field to be omitted and MUST NOT cause a user-visible error.
 
-The contents of ``client.env`` MUST be adjusted to keep the handshake below the size limit;
-see `Limitations`_ for specifics.
+Container
+^^^^^^^^^
+
+Container runtime information is captured in ``client.env.container``.
+
+``client.env.container.runtime`` MUST be set to ``"docker"`` if the file ``.dockerenv``
+exists in the root directory.
+
+``client.env.container.orchestrator`` MUST be set to ``"kubernetes"`` if the environment
+variable ``KUBERNETES_SERVICE_HOST`` is populated.
+
+If no fields of ``client.env.container`` would be populated, ``client.env.container`` MUST
+be entirely omitted.
 
 --------------------------
 Speculative Authentication
@@ -647,3 +674,4 @@ Changelog
 :2023-03-13: Add ``env`` to ``client`` document
 :2023-04-03: Simplify truncation for metadata
 :2023-05-04: ``AWS_EXECUTION_ENV`` must start with ``"AWS_Lambda_"``
+:2023-08-24: Added container awareness