feat(resource-detector-azure): Add AKS Resource Detector (open-telemetry#3371)

Author: JacksonWeber

packages/resource-detector-azure/README.md

@@ -71,6 +71,43 @@ This package implements Semantic Convention [Version 1.37.0](https://github.com/
 | cloud.resource_id  | The Azure Resource Manager URI uniquely identifying the Azure Virtual Machine. It typically follows this format: /subscriptions/{subscriptionId}/resourceGroups/{groupName}/providers/Microsoft.Compute/virtualMachines/{vmName}. Value from resourceId key on /metadata/instance/compute request. |
 | process.pid        | The process ID collected from the running process.                                                                                                                                                                                                                                                 |
 
+### Azure Kubernetes Service (AKS) Resource Detector
+
+The AKS detector reads cluster metadata from the native `aks-cluster-metadata` ConfigMap in the `kube-public` namespace, which is automatically created by AKS. The ConfigMap contains a `clusterResourceId` key with the full ARM resource ID of the cluster.
+
+| Resource Attribute | Description                                                                                                                                                                                                  |
+|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| cloud.platform     | The cloud platform. Here, it's always "azure.aks".                                                                                                                                                           |
+| cloud.provider     | The cloud service provider. In this context, it's always "azure".                                                                                                                                            |
+| cloud.resource_id  | The Azure Resource Manager URI uniquely identifying the AKS cluster. Value from `clusterResourceId` key in the `aks-cluster-metadata` ConfigMap.                                                             |
+| k8s.cluster.name   | The name of the AKS cluster, extracted from the ARM resource ID.                                                                                                                                             |
+
+#### Usage
+
+To use the AKS detector, configure your pod to read from the native `aks-cluster-metadata` ConfigMap in the `kube-public` namespace:
+
+```yaml
+env:
+  - name: CLUSTER_RESOURCE_ID
+    valueFrom:
+      configMapKeyRef:
+        name: aks-cluster-metadata
+        key: clusterResourceId
+```
+
+Alternatively, you can mount the ConfigMap as a file at `/etc/kubernetes/aks-cluster-metadata`.
+
+```typescript
+import { detectResources } from '@opentelemetry/resources';
+import { azureAksDetector } from '@opentelemetry/resource-detector-azure';
+
+const resource = detectResources({
+    detectors: [azureAksDetector],
+});
+
+const tracerProvider = new NodeTracerProvider({ resource });
+```
+
 ## Useful links
 
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>

packages/resource-detector-azure/src/detectors/AzureAksDetector.ts

@@ -0,0 +1,133 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as fs from 'fs';
+
+import { diag } from '@opentelemetry/api';
+import { ResourceDetector, DetectedResource } from '@opentelemetry/resources';
+import {
+  ATTR_CLOUD_PLATFORM,
+  ATTR_CLOUD_PROVIDER,
+  ATTR_K8S_CLUSTER_NAME,
+  CLOUD_PLATFORM_VALUE_AZURE_AKS,
+  CLOUD_PROVIDER_VALUE_AZURE,
+} from '../semconv';
+import {
+  AKS_CLUSTER_RESOURCE_ID,
+  AKS_METADATA_FILE_PATH,
+  AksClusterMetadata,
+  CLOUD_RESOURCE_ID_RESOURCE_ATTRIBUTE,
+  extractClusterNameFromResourceId,
+} from '../types';
+
+/**
+ * The AzureAksDetector can be used to detect if a process is running in an Azure Kubernetes Service (AKS) cluster.
+ * It reads cluster metadata from environment variables populated from the aks-cluster-metadata ConfigMap
+ * in the kube-public namespace, or from the ConfigMap file if mounted.
+ *
+ * The ConfigMap contains a single key 'clusterResourceId' with the full ARM resource ID.
+ * The cluster name is extracted from this resource ID.
+ *
+ * @returns a {@link Resource} populated with data about the AKS environment or an empty Resource if detection fails.
+ */
+class AzureAksDetector implements ResourceDetector {
+  public detect(): DetectedResource {
+    let attributes = {};
+
+    const metadata = this.getAksMetadata();
+    if (metadata && (metadata.name || metadata.resourceId)) {
+      attributes = {
+        [ATTR_CLOUD_PROVIDER]: CLOUD_PROVIDER_VALUE_AZURE,
+        [ATTR_CLOUD_PLATFORM]: CLOUD_PLATFORM_VALUE_AZURE_AKS,
+      };
+
+      if (metadata.name) {
+        attributes = {
+          ...attributes,
+          [ATTR_K8S_CLUSTER_NAME]: metadata.name,
+        };
+      }
+
+      if (metadata.resourceId) {
+        attributes = {
+          ...attributes,
+          [CLOUD_RESOURCE_ID_RESOURCE_ATTRIBUTE]: metadata.resourceId,
+        };
+      }
+
+      diag.debug('AzureAksDetector: detected AKS cluster:', metadata);
+    }
+
+    return { attributes };
+  }
+
+  private getAksMetadata(): AksClusterMetadata | undefined {
+    // Try environment variable first (populated from aks-cluster-metadata ConfigMap)
+    const clusterResourceId = process.env[AKS_CLUSTER_RESOURCE_ID];
+
+    if (clusterResourceId) {
+      return {
+        name: extractClusterNameFromResourceId(clusterResourceId),
+        resourceId: clusterResourceId,
+      };
+    }
+
+    // Fall back to reading from mounted ConfigMap file
+    return this.getAksMetadataFromFile();
+  }
+
+  private getAksMetadataFromFile(): AksClusterMetadata | undefined {
+    try {
+      if (!fs.existsSync(AKS_METADATA_FILE_PATH)) {
+        return undefined;
+      }
+
+      const content = fs.readFileSync(AKS_METADATA_FILE_PATH, 'utf8');
+      const metadata: AksClusterMetadata = {};
+
+      // Parse the ConfigMap file content (key=value format)
+      // The native aks-cluster-metadata ConfigMap has a single key: clusterResourceId
+      const lines = content.split('\n');
+      for (const line of lines) {
+        const trimmedLine = line.trim();
+        if (!trimmedLine || trimmedLine.startsWith('#')) {
+          continue;
+        }
+
+        const [key, ...valueParts] = trimmedLine.split('=');
+        const value = valueParts.join('=').trim();
+
+        if (key === 'clusterResourceId' && value) {
+          metadata.resourceId = value;
+          metadata.name = extractClusterNameFromResourceId(value);
+        }
+      }
+
+      if (metadata.resourceId) {
+        return metadata;
+      }
+    } catch (err: any) {
+      diag.debug(
+        'AzureAksDetector: failed to read AKS metadata file:',
+        err.message
+      );
+    }
+
+    return undefined;
+  }
+}
+
+export const azureAksDetector = new AzureAksDetector();

packages/resource-detector-azure/src/detectors/index.ts

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+export { azureAksDetector } from './AzureAksDetector';
 export { azureAppServiceDetector } from './AzureAppServiceDetector';
 export { azureFunctionsDetector } from './AzureFunctionsDetector';
 export { azureVmDetector } from './AzureVmDetector';

packages/resource-detector-azure/src/index.ts

@@ -15,6 +15,7 @@
  */
 
 export {
+  azureAksDetector,
   azureAppServiceDetector,
   azureFunctionsDetector,
   azureVmDetector,

packages/resource-detector-azure/src/semconv.ts

@@ -67,6 +67,15 @@ export const ATTR_CLOUD_REGION = 'cloud.region' as const;
 export const ATTR_DEPLOYMENT_ENVIRONMENT_NAME =
   'deployment.environment.name' as const;
 
+/**
+ * The name of the cluster.
+ *
+ * @example opentelemetry-cluster
+ *
+ * @experimental This attribute is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
+ */
+export const ATTR_K8S_CLUSTER_NAME = 'k8s.cluster.name' as const;
+
 /**
  * The execution environment ID as a string, that will be potentially reused for other invocations to the same function/function version.
  *
@@ -199,6 +208,15 @@ export const CLOUD_PLATFORM_VALUE_AZURE_FUNCTIONS = 'azure.functions' as const;
  */
 export const CLOUD_PLATFORM_VALUE_AZURE_VM = 'azure.vm' as const;
 
+/**
+ * Enum value "azure.aks" for attribute {@link ATTR_CLOUD_PLATFORM}.
+ *
+ * Azure Kubernetes Service
+ *
+ * @experimental This enum value is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
+ */
+export const CLOUD_PLATFORM_VALUE_AZURE_AKS = 'azure.aks' as const;
+
 /**
  * Enum value "azure" for attribute {@link ATTR_CLOUD_PROVIDER}.
  *

packages/resource-detector-azure/src/types.ts

@@ -36,6 +36,44 @@ export const AZURE_VM_METADATA_PATH =
 export const AZURE_VM_SCALE_SET_NAME_ATTRIBUTE = 'azure.vm.scaleset.name';
 export const AZURE_VM_SKU_ATTRIBUTE = 'azure.vm.sku';
 
+// AKS ConfigMap environment variables
+// The native AKS ConfigMap is 'aks-cluster-metadata' in 'kube-public' namespace
+// with a single key 'clusterResourceId'
+export const AKS_CLUSTER_RESOURCE_ID = 'CLUSTER_RESOURCE_ID';
+
+// AKS ConfigMap file path (mounted from aks-cluster-metadata ConfigMap in kube-public)
+export const AKS_METADATA_FILE_PATH = '/etc/kubernetes/aks-cluster-metadata';
+
+export interface AksClusterMetadata {
+  name?: string;
+  resourceId?: string;
+}
+
+/**
+ * Extracts the cluster name from an AKS ARM resource ID.
+ * @param resourceId The full ARM resource ID, e.g.:
+ *   /subscriptions/.../resourceGroups/.../providers/Microsoft.ContainerService/managedClusters/my-cluster
+ * @returns The cluster name (last segment), or undefined if not found
+ */
+export function extractClusterNameFromResourceId(
+  resourceId: string
+): string | undefined {
+  if (!resourceId) return undefined;
+  const segments = resourceId.split('/');
+  // The cluster name is the last segment after 'managedClusters'
+  const managedClustersIndex = segments.findIndex(
+    s => s.toLowerCase() === 'managedclusters'
+  );
+  if (
+    managedClustersIndex !== -1 &&
+    managedClustersIndex < segments.length - 1
+  ) {
+    return segments[managedClustersIndex + 1];
+  }
+  // Fallback: just return the last segment
+  return segments[segments.length - 1] || undefined;
+}
+
 export interface AzureVmMetadata {
   azEnvironment?: string;
   additionalCapabilities?: {

packages/resource-detector-azure/test/detectors/AzureAksDetector.test.ts

@@ -0,0 +1,90 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as assert from 'assert';
+import { azureAksDetector } from '../../src/detectors/AzureAksDetector';
+import {
+  ATTR_CLOUD_PLATFORM,
+  ATTR_CLOUD_PROVIDER,
+  ATTR_K8S_CLUSTER_NAME,
+} from '../../src/semconv';
+import { CLOUD_RESOURCE_ID_RESOURCE_ATTRIBUTE } from '../../src/types';
+import { detectResources } from '@opentelemetry/resources';
+
+describe('AzureAksDetector', () => {
+  let originalEnv: NodeJS.ProcessEnv;
+
+  beforeEach(() => {
+    originalEnv = process.env;
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  it('should detect AKS environment from CLUSTER_RESOURCE_ID environment variable', () => {
+    process.env.CLUSTER_RESOURCE_ID =
+      '/subscriptions/test-sub/resourceGroups/test-rg/providers/Microsoft.ContainerService/managedClusters/test-aks-cluster';
+
+    const resource = detectResources({
+      detectors: [azureAksDetector],
+    });
+
+    assert.ok(resource);
+    const attributes = resource.attributes;
+    assert.strictEqual(attributes[ATTR_CLOUD_PROVIDER], 'azure');
+    assert.strictEqual(attributes[ATTR_CLOUD_PLATFORM], 'azure.aks');
+    assert.strictEqual(attributes[ATTR_K8S_CLUSTER_NAME], 'test-aks-cluster');
+    assert.strictEqual(
+      attributes[CLOUD_RESOURCE_ID_RESOURCE_ATTRIBUTE],
+      '/subscriptions/test-sub/resourceGroups/test-rg/providers/Microsoft.ContainerService/managedClusters/test-aks-cluster'
+    );
+  });
+
+  it('should extract cluster name from resource ID with different casing', () => {
+    process.env.CLUSTER_RESOURCE_ID =
+      '/subscriptions/test-sub/resourceGroups/test-rg/providers/Microsoft.ContainerService/ManagedClusters/my-cluster-name';
+
+    const resource = detectResources({
+      detectors: [azureAksDetector],
+    });
+
+    assert.ok(resource);
+    const attributes = resource.attributes;
+    assert.strictEqual(attributes[ATTR_CLOUD_PROVIDER], 'azure');
+    assert.strictEqual(attributes[ATTR_CLOUD_PLATFORM], 'azure.aks');
+    assert.strictEqual(attributes[ATTR_K8S_CLUSTER_NAME], 'my-cluster-name');
+  });
+
+  it('should return empty resource when not in AKS environment', () => {
+    delete process.env.CLUSTER_RESOURCE_ID;
+
+    const resource = detectResources({
+      detectors: [azureAksDetector],
+    });
+
+    assert.ok(resource);
+    const attributes = resource.attributes;
+    assert.strictEqual(attributes[ATTR_CLOUD_PROVIDER], undefined);
+    assert.strictEqual(attributes[ATTR_CLOUD_PLATFORM], undefined);
+    assert.strictEqual(attributes[ATTR_K8S_CLUSTER_NAME], undefined);
+    assert.strictEqual(
+      attributes[CLOUD_RESOURCE_ID_RESOURCE_ATTRIBUTE],
+      undefined
+    );
+  });
+});