From ef315aafb5d9c7dc2c695e30696b363e84761589 Mon Sep 17 00:00:00 2001 From: Rajkumar Rangaraj Date: Thu, 16 Nov 2023 10:09:23 -0800 Subject: [PATCH] [exporter/azuremonitor] Enhance AAD Documentation. (#29234) **Description:** * Update AAD documentation to use connection string instead of instrumentation key. Follow up to #28854 * Modified the ingestion version from 2.0 to 2.1 **Link to tracking Issue:** **Testing:** Existing tests. Output from manual run ``` json --------- Transmitting 30 items --------- {"kind": "exporter", "data_type": "logs", "name": "azuremonitor"} 2023-11-13T10:50:23.886-0800 debug azuremonitorexporter@v0.88.0/factory.go:139 Telemetry transmitted in 378.439395ms {"kind": "exporter", "data_type": "logs", "name": "azuremonitor"} 2023-11-13T10:50:23.886-0800 debug azuremonitorexporter@v0.88.0/factory.go:139 Response: 200 {"kind": "exporter", "data_type": "logs", "name": "azuremonitor"} 2023-11-13T10:50:23.886-0800 debug azuremonitorexporter@v0.88.0/factory.go:139 Items accepted/received: 30/30 {"kind": "exporter", "data_type": "logs", "name": "azuremonitor"} ``` **Documentation:** * Updated Authentication.md --- .../update-azuremonitor-service-version.yaml | 27 +++++++++++++++++++ .../azuremonitorexporter/AUTHENTICATION.md | 19 +++++++------ .../connection_string_parser.go | 2 +- .../connection_string_parser_test.go | 10 +++---- 4 files changed, 42 insertions(+), 16 deletions(-) create mode 100644 .chloggen/update-azuremonitor-service-version.yaml diff --git a/.chloggen/update-azuremonitor-service-version.yaml b/.chloggen/update-azuremonitor-service-version.yaml new file mode 100644 index 000000000000..a576169d5e6a --- /dev/null +++ b/.chloggen/update-azuremonitor-service-version.yaml @@ -0,0 +1,27 @@ +# Use this changelog template to create an entry for release notes. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver) +component: azuremonitorexporter + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Updated Azure Monitor Exporter service version from v2.0 to v2.1. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +issues: [29234] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: + +# If your change doesn't affect end users or the exported elements of any package, +# you should instead start your pull request title with [chore] or use the "Skip Changelog" label. +# Optional: The change log or logs in which this entry should be included. +# e.g. '[user]' or '[user, api]' +# Include 'user' if the change is relevant to end users. +# Include 'api' if there is a change to a library API. +# Default: '[user]' +change_logs: [user] diff --git a/exporter/azuremonitorexporter/AUTHENTICATION.md b/exporter/azuremonitorexporter/AUTHENTICATION.md index 8317edc1fc7f..c2c4b8dc8863 100644 --- a/exporter/azuremonitorexporter/AUTHENTICATION.md +++ b/exporter/azuremonitorexporter/AUTHENTICATION.md @@ -2,42 +2,41 @@ ## Local Authentication -The default authentication mechanism used by the Azure Monitor Exporter is "Local Authentication" - based solely on the Application Insights Instrumentation Key. An example of the exporters section of the configuration is +The default authentication mechanism used by the Azure Monitor Exporter is "Local Authentication", which relies exclusively on the `InstrumentationKey` obtained from the connection string of the Application Insights. Below is an illustrative example of the exporters section in a configuration file: ```yaml exporters: azuremonitor: - instrumentation_key: 00000000-0000-0000-0000-000000000000 + connection_string: "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://ingestion.azuremonitor.com/" ``` -Where the zero guid is replaced with the instrumentation key of your Application Insights instance. +Use the connection string from your Application Insights instance. The same can be achieved by using an environment variable to hold the key ```yaml exporters: azuremonitor: - instrumentation_key: ${env:APP_INSIGHTS_KEY} + connection_string: ${env:APPLICATIONINSIGHTS_CONNECTION_STRING} ``` ## AAD/Entra Authentication -Local Authentication can be disabled in [Application Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/app/azure-ad-authentication) and an AAD based identity can be used in conjunction with the instrumentation key. The instrumentation key is still required by the Exporter, but it is no long sufficient to just have this in order to import data. +Local Authentication can be disabled in [Application Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/app/azure-ad-authentication) and an AAD based identity can be used in conjunction with the instrumentation key. The Azure Monitor Exporter does not support this approach directly, but it can be used with the [AAD Authentication Proxy](https://github.com/Azure/aad-auth-proxy) from the Azure Monitor product group. The AAD Auth Proxy is a separate container/side-car that proxies calls to the Application Insights ingestion endpoint and attaches a bearer token to each call, asserting an AAD identity. This identity is managed by a certificate in the container that is registered with a Service Principal in AAD. -To use this, both Azure Monitor Exporter and the AAD Auth Proxy require specific configuration. In the Exporter's configuration, it is necessary to override the default endpoint used to send data to. In the following example, it is assumed the AAD Auth Proxy is listening on localhost:8081. +To integrate this setup, both the Azure Monitor Exporter and the AAD Auth Proxy must be configured appropriately. For the Exporter, replace the ingestion endpoint in the connection string with the proxy endpoint. For instance, if the AAD Auth Proxy listens on localhost:8081, configure as follows: ```yaml exporters: azuremonitor: - instrumentation_key: ${env:APP_INSIGHTS_KEY} - endpoint: http://localhost:8081/v2.1/track + connection_string: "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=http://localhost:8081" ``` -The key difference is this uses the `v2.1` endpoint, not the standard `v2` one. +The original `IngestionEndpoint` from the connection string needs to be set as the `TARGET_HOST` environment variable in the aad-auth-proxy configuration. In the docker compose file for AAD Auth Proxy, the following values need to be set: @@ -60,7 +59,7 @@ azuremonitor-ingestion-proxy: ``` - `AUDIENCE`: value is the generic Azure Monitor Scope. -- `TARGET_HOST`: the Application Insights IngestionEndpoint value from the Connection String, available in the Azure Portal. +- `TARGET_HOST`: the Application Insights `IngestionEndpoint` value from the Connection String, available in the Azure Portal. - `AAD_CLIENT_ID`: client id of the service principal representing the AAD identity to use. - `AAD_TENANT_ID`: id of the AAD Tenant the service principal exists in. - `AAD_CLIENT_CERTIFICATE_PATH`: path to the .pem certificate file containing the CERTIFICATE and PRIVATE KEY parts of the certificate registered with the service principal. diff --git a/exporter/azuremonitorexporter/connection_string_parser.go b/exporter/azuremonitorexporter/connection_string_parser.go index 15b4f57827fc..fd1a7d00e862 100644 --- a/exporter/azuremonitorexporter/connection_string_parser.go +++ b/exporter/azuremonitorexporter/connection_string_parser.go @@ -75,6 +75,6 @@ func getIngestionURL(ingestionEndpoint string) string { ingestionURL, _ = url.Parse(DefaultIngestionEndpoint) } - ingestionURL.Path = path.Join(ingestionURL.Path, "/v2/track") + ingestionURL.Path = path.Join(ingestionURL.Path, "/v2.1/track") return ingestionURL.String() } diff --git a/exporter/azuremonitorexporter/connection_string_parser_test.go b/exporter/azuremonitorexporter/connection_string_parser_test.go index ad8315f49159..cff893d4cd46 100644 --- a/exporter/azuremonitorexporter/connection_string_parser_test.go +++ b/exporter/azuremonitorexporter/connection_string_parser_test.go @@ -27,7 +27,7 @@ func TestParseConnectionString(t *testing.T) { }, want: &ConnectionVars{ InstrumentationKey: "00000000-0000-0000-0000-000000000000", - IngestionURL: "https://ingestion.azuremonitor.com/v2/track", + IngestionURL: "https://ingestion.azuremonitor.com/v2.1/track", }, wantError: false, }, @@ -38,7 +38,7 @@ func TestParseConnectionString(t *testing.T) { }, want: &ConnectionVars{ InstrumentationKey: "00000000-0000-0000-0000-000000000000", - IngestionURL: DefaultIngestionEndpoint + "v2/track", + IngestionURL: DefaultIngestionEndpoint + "v2.1/track", }, wantError: false, }, @@ -49,7 +49,7 @@ func TestParseConnectionString(t *testing.T) { }, want: &ConnectionVars{ InstrumentationKey: "00000000-0000-0000-0000-000000000000", - IngestionURL: "https://ingestion.azuremonitor.com/v2/track", + IngestionURL: "https://ingestion.azuremonitor.com/v2.1/track", }, wantError: false, }, @@ -93,7 +93,7 @@ func TestParseConnectionString(t *testing.T) { }, want: &ConnectionVars{ InstrumentationKey: "00000000-0000-0000-0000-000000000000", - IngestionURL: "https://ingestion.azuremonitor.com/v2/track", + IngestionURL: "https://ingestion.azuremonitor.com/v2.1/track", }, wantError: false, }, @@ -104,7 +104,7 @@ func TestParseConnectionString(t *testing.T) { }, want: &ConnectionVars{ InstrumentationKey: "00000000-0000-0000-0000-000000000000", - IngestionURL: "https://ingestion.azuremonitor.com/v2/track", + IngestionURL: "https://ingestion.azuremonitor.com/v2.1/track", }, wantError: false, },