From 517e5d5a7e12ecc377b90e77a48cb66e748d0471 Mon Sep 17 00:00:00 2001 From: Abraham Egnor Date: Thu, 24 Aug 2023 10:47:24 -0400 Subject: [PATCH 1/5] DRIVERS-2570: Report docker or kubernetes environment in handshake --- source/mongodb-handshake/handshake.rst | 36 ++++++++++++++++++++------ 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/source/mongodb-handshake/handshake.rst b/source/mongodb-handshake/handshake.rst index d92acef001..5cd4995a22 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: "", /* OPTIONAL */ env: { - name: "", /* REQUIRED */ + name: "", /* OPTIONAL */ timeout_sec: 42, /* OPTIONAL */ memory_mb: 1024, /* OPTIONAL */ - region: "" /* OPTIONAL */ + region: "", /* OPTIONAL */ + /* OPTIONAL */ + container: { + runtime: "", /* OPTIONAL */ + orchestrator: "" /* OPTIONAL */ + } } } } @@ -313,8 +318,11 @@ 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. + +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 +337,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,6 +363,18 @@ 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. +Container runtime information is captured in ``client.env.container``. + +``client.env.container.runtime`` SHOULD be set to ``"docker"`` if the file ``.dockerenv`` +exists in the root directory. + +``client.env.container.orchestrator`` SHOULD 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. Similarly, if no fields of ``client.env`` would be populated, +``client.env`` MUST be entirely omitted. + The contents of ``client.env`` MUST be adjusted to keep the handshake below the size limit; see `Limitations`_ for specifics. From b7865fe6cd8ac05c7fe6e1c2be7780cf1bb9a82e Mon Sep 17 00:00:00 2001 From: Abraham Egnor Date: Thu, 24 Aug 2023 10:51:36 -0400 Subject: [PATCH 2/5] reorg --- source/mongodb-handshake/handshake.rst | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/source/mongodb-handshake/handshake.rst b/source/mongodb-handshake/handshake.rst index 5cd4995a22..e93296e453 100644 --- a/source/mongodb-handshake/handshake.rst +++ b/source/mongodb-handshake/handshake.rst @@ -321,6 +321,14 @@ This value is optional and is not application configurable. 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: @@ -363,6 +371,9 @@ SHOULD 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. +Container +^^^^^^^^^ + Container runtime information is captured in ``client.env.container``. ``client.env.container.runtime`` SHOULD be set to ``"docker"`` if the file ``.dockerenv`` @@ -372,11 +383,7 @@ exists in the root directory. variable ``KUBERNETES_SERVICE_HOST`` is populated. If no fields of ``client.env.container`` would be populated, ``client.env.container`` MUST -be entirely omitted. Similarly, if no fields of ``client.env`` would be populated, -``client.env`` MUST be entirely omitted. - -The contents of ``client.env`` MUST be adjusted to keep the handshake below the size limit; -see `Limitations`_ for specifics. +be entirely omitted. -------------------------- Speculative Authentication From 568e9ad2e5bd937dc5e9de74db383f082877ed1e Mon Sep 17 00:00:00 2001 From: Abraham Egnor Date: Thu, 24 Aug 2023 12:53:01 -0400 Subject: [PATCH 3/5] changelog --- source/mongodb-handshake/handshake.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/mongodb-handshake/handshake.rst b/source/mongodb-handshake/handshake.rst index e93296e453..0f8582b94b 100644 --- a/source/mongodb-handshake/handshake.rst +++ b/source/mongodb-handshake/handshake.rst @@ -674,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 From bcb5bbb4cef43586556637a01c008543d5690220 Mon Sep 17 00:00:00 2001 From: Abraham Egnor Date: Mon, 28 Aug 2023 08:51:13 -0400 Subject: [PATCH 4/5] Update source/mongodb-handshake/handshake.rst Co-authored-by: Andreas Braun --- source/mongodb-handshake/handshake.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/mongodb-handshake/handshake.rst b/source/mongodb-handshake/handshake.rst index 0f8582b94b..c7568b4fb2 100644 --- a/source/mongodb-handshake/handshake.rst +++ b/source/mongodb-handshake/handshake.rst @@ -379,7 +379,7 @@ Container runtime information is captured in ``client.env.container``. ``client.env.container.runtime`` SHOULD be set to ``"docker"`` if the file ``.dockerenv`` exists in the root directory. -``client.env.container.orchestrator`` SHOULD be set to ``"kubernetes"`` if the environment +``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 From c4831b426c7eab8749723d7f3cd6bb5c237bcbbe Mon Sep 17 00:00:00 2001 From: Abraham Egnor Date: Mon, 28 Aug 2023 08:51:25 -0400 Subject: [PATCH 5/5] Update source/mongodb-handshake/handshake.rst Co-authored-by: Andreas Braun --- source/mongodb-handshake/handshake.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/mongodb-handshake/handshake.rst b/source/mongodb-handshake/handshake.rst index c7568b4fb2..90e6156800 100644 --- a/source/mongodb-handshake/handshake.rst +++ b/source/mongodb-handshake/handshake.rst @@ -376,7 +376,7 @@ Container Container runtime information is captured in ``client.env.container``. -``client.env.container.runtime`` SHOULD be set to ``"docker"`` if the file ``.dockerenv`` +``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