Chef Declarative State Management (DSM) Manage API

The DSM Manage API provides administrative operations for DSM capabilities within Chef 360 Platform. This service includes two main functional areas:

Credential Management Service - Rotates critical system credentials
OpenSearch management - Manages OpenSearch index operations

Prerequisites

All API requests to the DSM Manage API require an install administrative token, which you can configure when installing Chef 360 Platform. To get the install admin token or check if it’s already set, see the Install Admin Token in the Admin Console.

Services

Credential Management Service

The Credential Management Service securely rotates PostgreSQL passwords and RSA key pairs used by DSM services. The service implements thread-safe operations with proper locking mechanisms to prevent concurrent rotation conflicts.

The request body has a field named targets, which is an array of credentials to rotate. Setting targets to all rotates all credentials.

Supported targets

erchef-postgres - DSM Erchef PostgreSQL database credentials
bifrost-postgres - DSM Bifrost PostgreSQL database credentials
pivotal-key - Pivotal RSA key pair
webui-key - WebUI RSA key pair
all - Rotates all supported targets

API endpoint

POST /internal/credentials/rotate

Authentication: Requires an install admin token.

Request Body:

{
  "targets": ["erchef-postgres", "pivotal-key"]
}

Response:

{
  "code": 202,
  "item": {
    "service": "dsm-manage-api",
    "operationId": "a2c8fb73-691d-4e4a-87cf-29aef78c4456",
    "message": "Credential rotation initiated for 2 target(s)"
  }
}

Example curl commands

Rotate specific targets:

curl -X POST \
  "http://example.com/courier/dsm-manage-api/v1/internal/credentials/rotate" \
  -H "Content-Type: application/json" \
  -H "API-Key: INSTALL-ADMIN-TOKEN" \
  -H "API-Secret: <INSTALL_ADMIN_TOKEN>" \
  -d '{
    "targets": ["erchef-postgres", "pivotal-key"]
  }'

Replace <INSTALL_ADMIN_TOKEN> with your configured install admin token.

Rotate all targets:

curl -X POST \
  "http://example.com/courier/dsm-manage-api/v1/internal/credentials/rotate" \
  -H "Content-Type: application/json" \
  -H "API-Key: INSTALL-ADMIN-TOKEN" \
  -H "API-Secret: <INSTALL_ADMIN_TOKEN>" \
  -d '{
    "targets": ["all"]
  }'

Replace <INSTALL_ADMIN_TOKEN> with your configured install admin token.

OpenSearch Management Service

The OpenSearch Management Service reindexes organizations within Chef tenants. This operation accepts two query parameters: a tenant name and an organizations list.

The tenant name is a mandatory parameter for all reindex operations, and the organizations list is optional.

If you provide a list of organizations, the OpenSearch Management Service reindexes only valid organization names present in the tenant. If you don’t provide an organizations list, the OpenSearch Management Service reindexes all organizations in the tenant.

Key features

Tenant-based organization validation
Selective organization reindexing
Asynchronous operation tracking

API endpoint

POST /internal/opensearch/reindex

Authentication: Requires an install admin token.

Query Parameters:

tenantName (required) - The tenant UUID to reindex
organizations (optional) - Array of organization names to reindex

Response:

{
  "kind": "object",
  "code": 202,
  "params": {
    "query": {
      "tenantName": "550e8400-e29b-41d4-a716-446655440000"
    },
    "path": {},
    "header": {}
  },
  "item": {
    "service": "dsm-manage-api",
    "operationId": "reindex-550e8400-e29b-41d4-a716-446655440000-1704067200",
    "message": "Reindex job created for 3 organizations. Job Name: dsm-erchef-reindex-abc12"
  }
}

Example curl commands

Reindex all organizations in a tenant:

curl -X POST \
  "http://example.com/courier/dsm-manage-api/v1/internal/opensearch/reindex?tenantName=550e8400-e29b-41d4-a716-446655440000" \
  -H "API-Key: INSTALL-ADMIN-TOKEN" \
  -H "API-Secret: <INSTALL_ADMIN_TOKEN>"

Replace <INSTALL_ADMIN_TOKEN> with your install admin token.

Reindex a specific organization:

curl -X POST \
  "http://example.com/courier/dsm-manage-api/v1/internal/opensearch/reindex?tenantName=550e8400-e29b-41d4-a716-446655440000&organizations=org1" \
  -H "API-Key: INSTALL-ADMIN-TOKEN" \
  -H "API-Secret: <INSTALL_ADMIN_TOKEN>"

Replace <INSTALL_ADMIN_TOKEN> with your install admin token.

Reindex specific organizations:

curl -X POST \
  "http://example.com/courier/dsm-manage-api/v1/internal/opensearch/reindex?tenantName=550e8400-e29b-41d4-a716-446655440000&organizations=org1&organizations=org2" \
  -H "API-Key: INSTALL-ADMIN-TOKEN" \
  -H "API-Secret: <INSTALL_ADMIN_TOKEN>"

Replace <INSTALL_ADMIN_TOKEN> with your install admin token.

Process flow

Parse tenant UUID from request parameters
Validate tenant and retrieve associated organizations
Filter organizations (if specific ones requested)
Create Kubernetes job with dsm-erchef image
Return operation tracking information immediately

Operation tracking

Both services provide operation IDs for tracking:

Credential rotations: uuid.New().String() format
Reindex operations: reindex-{tenantId}-{timestamp} format

These IDs can be used for:

Progress monitoring
Log correlation
Status checking
Troubleshooting operations

Get operation logs

Retrieve reindex logs

When you submit a reindex request, the response contains an operationId field that you can use to retrieve specific logs for that operation.

For example:

{
  "kind": "object",
  "code": 202,
  "item": {
    "service": "dsm-manage-api",
    "operationId": "reindex-b3800304-3c09-4be8-b745-f630ec4ba9ac-1770714283",
    "message": "Reindex job created for 3 organizations. Job Name: dsm-erchef-reindex-abc12"
  }
}

Retrieve service logs

With the operation ID, you can use the chef-platform-auth-cli to get logs for a specific operation:

chef-platform-auth-cli log-service general get-service-logs \
  --profile installAdminProfile \
  --services dsm-erchef-reindex \
  --filter '[{"operation_id": "<OPERATION_ID>"}]'

Example log retrieval workflow

To retrieve reindex logs, follow these steps:

Submit a reindex request and capture the operationId:

OPERATION_ID=$(curl -s -X POST \
  "https://your-host/courier/dsm-manage-api/v1/internal/opensearch/reindex?tenantName=550e8400-e29b-41d4-a716-446655440000" \
  -H "API-Key: INSTALL-ADMIN-TOKEN" \
  -H "API-Secret: <INSTALL_ADMIN_TOKEN>" \
  | jq -r '.item.operationId')

Use the operation ID to retrieve the logs:

chef-platform-auth-cli log-service general get-service-logs \
  --profile profile2 \
  --services dsm-erchef-reindex \
  --filter "[{\"operation_id\": \"$OPERATION_ID\"}]"

Monitor long-running reindex operations

You can use the log retrieval command (get-service-logs) to monitor long-running reindex operations. For example:

# Check logs every 30 seconds until operation completes
while true; do
  echo "=== $(date): Checking reindex logs ==="
  chef-platform-auth-cli log-service general get-service-logs \
    --profile profile2 \
    --services dsm-erchef-reindex \
    --filter '[{"operation_id": "'"$OPERATION_ID"'"}]' | \
    tail -n 20

  sleep 30
done