Configuration Change Audit API

Overview

Cloudera Manager maintains configuration change history through its existing revision and audit infrastructure. Historically, administrators accessed this history through the Config History user interface (UI). External security, governance, and compliance systems lacked a supported Representational State Transfer (REST) API to query configuration differences programmatically.

GET /api/v58/audits/configChanges

Key Benefits

Understand the evolution of configuration change tracking in Cloudera Manager and how the dedicated Configuration Audit API simplifies integration with enterprise security and automation platforms.

Key Features and Functional Capabilities

Understand the core design objectives, query parameters, and security features supported by the Configuration Change Audit API.

API Query Parameters

Review the supported query parameters, their default values, and available filtering options.

Paginating Audit Results

Understand cursor-based navigation using beforeRevisionId to retrieve large audit trails safely without splitting change sets.

Request 1: GET .../configChanges?limit=100
           (Returns revisions 500 down to 401. Smallest revisionId = 401)
     ↓
Request 2: GET .../configChanges?limit=100&beforeRevisionId=401
           (Returns revisions 400 down to 301. Smallest revisionId = 301)
     ↓
Request 3: GET .../configChanges?limit=100&beforeRevisionId=301
           (Returns revisions 300 down to 201)

How to Paginate Through Results

To paginate through audit results:

1. Send an initial GET request without the beforeRevisionId parameter.

2. Identify the lowest revisionId value in the returned response list.

3. Pass that value as the beforeRevisionId query parameter in your subsequent request.

4. Repeat this process until the API returns an empty list.

Security Governance and Redaction

Review the authentication privileges, role requirements, and automated credential redaction policies enforced by the endpoint.

Role-Based Access Control (RBAC)

Cloudera Manager controls access to this endpoint through the dedicated AUTH_AUDITS permission authority.

Cloudera Manager User Role	Has AUTH_AUDITS Authority	Endpoint Access
ROLE_ADMIN	Yes	Allowed
ROLE_AUDITOR	Yes	Allowed
ROLE_USER and lower roles	No	Denied (HTTP 403 Forbidden)

If a user without the AUTH_AUDITS authority submits a request to the endpoint, Cloudera Manager rejects the request with an HTTP 403 Forbidden response.

Sensitive Data Redaction

To prevent credential leaks, the API enforces the same redaction rules as the Config History UI. Sensitive values such as passwords, private keys, Kerberos keytab contents, and confidential credentials, automatically appear as masked strings in both the oldValue and newValue fields.

Configuration Audit Scope

Identify the configuration objects included in the audit stream and the administrative settings excluded from this endpoint.

Supported Configuration Objects

The API audits configuration changes associated with the following resources:

• Service-level configurations: Global service properties, such as default HDFS replication settings and YARN cluster memory allocations.

• Role-level configurations: Process-specific parameters, such as NameNode Java Virtual Machine (JVM) heap limits.

• Role Config Groups (RCG): Specialized configuration group property overrides.

• Host-level configurations: Host-specific Cloudera Manager Agent parameters.

Excluded Configuration Objects

The following configuration resources fall outside the scope of this endpoint:

• Cloudera Manager server settings: Internal Cloudera Manager administrative configurations use a separate auditing path.

• External account configurations: External authentication and third-party credential associations fall outside cluster configuration auditing.

API Behavior and Validation Rules

Learn how the API evaluates query parameters, handles boundary conditions, parses parameter changes, and validates input requests.

Parameter Precedence (revisionId)

When you specify revisionId, Cloudera Manager treats it as the highest-priority filter. The API ignores all additional filtering parameters in the request (such as clusterName, serviceName, startTime, endTime, limit, beforeRevisionId, or query) without returning an error.

Handling Empty Query Parameters

The API treats empty parameter keys or empty assigned values as omitted parameters. The following requests produce identical results:

• GET /api/v58/audits/configChanges?clusterName

• GET /api/v58/audits/configChanges?clusterName=

• GET /api/v58/audits/configChanges

Half-Open Time Range Evaluation

The API calculates time boundaries using a standard half-open interval:

[startTime,endTime)

Cloudera Manager includes revisions where:

timestamp ≥ startTimeANDtimestamp < endTime

Deletion and Reset Semantics

When an administrator removes an explicit role-level or service-level configuration override, the audit record returns an oldValue without a corresponding newValue:

{
  "configParameter": "dfs.datanode.data.dir",
  "oldValue": "/data/dfs/dn"
}

This payload indicates that the administrator deleted an override at that specific configuration level, causing the parameter to inherit its default value from the parent level.

Addition and Override Semantics

When an administrator sets an explicit value for a parameter that previously had no custom value, the audit record returns a newValue without an oldValue:

{
  "configParameter": "dfs.replication",
  "newValue": "3"
}

This payload indicates that the administrator added a new, explicit configuration value at the audited hierarchy level.

Duplicate Parameter Validation

The API allows each supported query parameter to appear only once per request. Supplying the same query parameter multiple times causes Cloudera Manager to reject the call with an HTTP 400 Bad Request status:

GET /api/v58/audits/configChanges?clusterName=ClusterA&clusterName=ClusterB

HTTP/1.1 400 Bad Request