From df0e6c043336aefa1ca157007f5771bedffacb0e Mon Sep 17 00:00:00 2001 From: shaik80 Date: Tue, 12 May 2026 17:02:17 +0530 Subject: [PATCH 1/2] docs(CHEF-28176): Update Automate audit-log retention docs - Document config fields from chef/automate-private#249 - Document retention behavior from chef/automate-private#243 - Refs: CHEF-28176, CHEF-28177 --- content/automate/audit_log_object_storage.md | 119 +++++++++++++++++++ 1 file changed, 119 insertions(+) diff --git a/content/automate/audit_log_object_storage.md b/content/automate/audit_log_object_storage.md index 0290c7c260..c850a497d7 100644 --- a/content/automate/audit_log_object_storage.md +++ b/content/automate/audit_log_object_storage.md @@ -223,6 +223,78 @@ If you don't set `[global.v1.audit.output]`, Chef Automate uses these defaults: sudo chef-automate config patch ``` +### Configure audit log retention + +Chef Automate can automatically delete old audit log objects from your S3 or MinIO bucket on a daily schedule. + +**Rotating audit log objects stored in S3** are deleted based on how old they are (in days). +**Requested-log export files** (generated when a user calls the audit request API) are deleted based on how long ago they were created (in hours or days). + +#### Configure daily cleanup of stored audit logs + +To enable daily deletion of audit log objects older than a set number of days, follow these steps: + +1. Create a TOML file with the following content: + + ```toml + [global.v1.audit] + + [global.v1.audit.retention] + days = 30 + schedule_hour = 2 + schedule_minute = 0 + ``` + + Replace the following: + + - `days` with the number of days to retain audit logs. Set to `0` to disable automatic cleanup (unlimited retention). + - `schedule_hour` with the hour (0-23) when cleanup runs. Default: `2` (2 AM). + - `schedule_minute` with the minute (0-59) when cleanup runs. Default: `0`. + + {{< note >}} + Retention is enabled when `days` is greater than `0`. + Setting `days = 0` disables automatic cleanup entirely. + {{< /note >}} + +1. Patch the Chef Automate configuration: + + ```bash + sudo chef-automate config patch + ``` + +#### Configure automatic deletion of requested log export files + +When a user requests audit logs through the API, Chef Automate generates a log export file and stores it in your configured bucket under the `requested-logs/` path prefix. +These files are automatically cleaned up on an hourly schedule. + +To configure how long requested-log files are retained before deletion, follow these steps: + +1. Create a TOML file with the following content: + + ```toml + [global.v1.audit] + + [global.v1.audit.async] + requested_logs_retention_duration = "1hr" + ``` + + Replace `"1hr"` with your retention duration. + Valid formats: + + - `"0"` disables automatic cleanup (files are retained indefinitely). + - `"1hr"`, `"24hr"` retain for the specified number of hours. + - `"7d"`, `"30d"` retain for the specified number of days. + + {{< note >}} + If the value is invalid, Chef Automate disables cleanup (fail-closed) and logs a warning. + {{< /note >}} + +1. Patch the Chef Automate configuration: + + ```bash + sudo chef-automate config patch + ``` + ## Troubleshooting - If uploads fail to MinIO with TLS enabled, verify the endpoint scheme (`http://` vs `https://`) matches the `ssl.enabled` setting. @@ -441,6 +513,47 @@ For a complete set of log storage settings, see the [reference examples](#audit- Units: minutes only (`m`). +`[global.v1.audit.retention]` + +: Configures automatic daily cleanup of audit log objects stored in S3 or MinIO: + + ```toml + [global.v1.audit.retention] + days = 30 + schedule_hour = 2 + schedule_minute = 0 + ``` + +: `days` + : Default value: `30` + + Number of days to retain audit logs. + A value of `0` disables automatic cleanup (unlimited retention). + A value greater than 0 enables cleanup and sets the retention period. + + Must be `>= 0`. + +: `schedule_hour` + : Default value: `2` + + Hour of day (0-23) when the daily cleanup job runs. + Default is `2` (2 AM). + +: `schedule_minute` + : Default value: `0` + + Minute (0-59) when the daily cleanup job runs. + +: `requested_logs_retention_duration` (under `[global.v1.audit.async]`) + : Default value: `"1hr"` + + Controls how long requested audit log export files (stored under `requested-logs/` in your bucket) are kept before automatic hourly cleanup. + Valid formats: `"0"` (disabled), `"1hr"`, `"24hr"`, `"7d"`, `"30d"`, and so on. + Must use `hr` for hours or `d` for days. + For example, `"24h"` is not valid. Use `"24hr"`. + + If set to an invalid value, cleanup is disabled and a warning is logged. + ### Audit log configuration file examples The following examples show all audit log settings in a single TOML file (logging, local rotation, S3 or MinIO storage, TLS settings, and upload behavior). @@ -471,6 +584,12 @@ The following TOML shows the default audit log settings: max_concurrent_workers = 4 queue_size = 100 multipart_chunk_size = "10M" + requested_logs_retention_duration = "1hr" + + [global.v1.audit.retention] + days = 0 + schedule_hour = 2 + schedule_minute = 0 [global.v1.audit.storage] storage_type = "s3" From b031e47232ae119127f376ad49c00d3e118238df Mon Sep 17 00:00:00 2001 From: Ian Maddaus Date: Fri, 29 May 2026 12:55:12 -0400 Subject: [PATCH 2/2] Editing Signed-off-by: Ian Maddaus --- content/automate/audit_log_object_storage.md | 90 +++++++++++--------- 1 file changed, 48 insertions(+), 42 deletions(-) diff --git a/content/automate/audit_log_object_storage.md b/content/automate/audit_log_object_storage.md index c850a497d7..39a21837e5 100644 --- a/content/automate/audit_log_object_storage.md +++ b/content/automate/audit_log_object_storage.md @@ -10,9 +10,6 @@ draft = false weight = 43 +++ - - - You can configure Chef Automate to use an object storage backend (AWS S3 or MinIO) for audit log storage. This is helpful when you want audit log data to live outside the local filesystem and to integrate with object-storage-based retention and access controls. @@ -106,7 +103,7 @@ To create the minimum configuration for uploading audit logs, follow these steps 1. Patch the Chef Automate configuration: - ```bash + ```shell sudo chef-automate config patch [flags] ``` @@ -119,7 +116,7 @@ To create the minimum configuration for uploading audit logs, follow these steps After you patch the configuration, Automate starts running the audit log collector and uploads audit log data to the configured bucket. -1. Optional: Once audit logs are uploaded, you can optionally configure the following: +1. Optional: Once audit logs are uploaded, you can configure the following: - a prefix inside the bucket to group objects - TLS options enable and verify a `root_cert` for private certificate authorities @@ -148,7 +145,7 @@ To verify audit log uploads, follow these steps: ### Configure local audit log rotation Chef Automate rotates the local audit log file written by the load balancer. -To change the rotation size threshold, patch your Automate configuration. +To change the rotation size threshold, patch your Automate configuration: 1. Create a TOML file with the following content: @@ -169,14 +166,14 @@ To change the rotation size threshold, patch your Automate configuration. Rotation behavior: - - Audit entries are written to `/hab/svc/automate-load-balancer/data/audit.log`. + - Chef Automate writes audit entries to `/hab/svc/automate-load-balancer/data/audit.log`. - When `audit.log` exceeds `max_file_size`, it's rotated to `audit.1.log`. - - Older rotated files are shifted up (`audit.1.log` -> `audit.2.log`, etc.). + - The load balancer shifts older rotated files up (`audit.1.log` -> `audit.2.log`, etc.). - Chef Automate keeps up to 10 rotated files (`audit.1.log` through `audit.10.log`). 1. Patch the Chef Automate configuration: - ```bash + ```shell sudo chef-automate config patch ``` @@ -219,7 +216,7 @@ If you don't set `[global.v1.audit.output]`, Chef Automate uses these defaults: 1. Patch the Chef Automate configuration: - ```bash + ```shell sudo chef-automate config patch ``` @@ -227,8 +224,8 @@ If you don't set `[global.v1.audit.output]`, Chef Automate uses these defaults: Chef Automate can automatically delete old audit log objects from your S3 or MinIO bucket on a daily schedule. -**Rotating audit log objects stored in S3** are deleted based on how old they are (in days). -**Requested-log export files** (generated when a user calls the audit request API) are deleted based on how long ago they were created (in hours or days). +**Rotating audit log objects stored in S3** are deleted based on their age in days. +**Requested-log export files** (generated when you call the audit request API) are deleted based on how long ago they were created (in hours or days). #### Configure daily cleanup of stored audit logs @@ -240,31 +237,30 @@ To enable daily deletion of audit log objects older than a set number of days, f [global.v1.audit] [global.v1.audit.retention] - days = 30 - schedule_hour = 2 - schedule_minute = 0 + days = + schedule_hour = + schedule_minute = ``` Replace the following: - - `days` with the number of days to retain audit logs. Set to `0` to disable automatic cleanup (unlimited retention). - - `schedule_hour` with the hour (0-23) when cleanup runs. Default: `2` (2 AM). - - `schedule_minute` with the minute (0-59) when cleanup runs. Default: `0`. + - `` with the number of days to retain audit logs. Default value: `30`. - {{< note >}} - Retention is enabled when `days` is greater than `0`. - Setting `days = 0` disables automatic cleanup entirely. - {{< /note >}} + Retention is enabled when `days` is greater than `0`. + Set to `0` to disable automatic cleanup (unlimited retention). + + - `` with the hour (0-23) when cleanup runs. Default: `2` (2 AM). + - `` with the minute (0-59) when cleanup runs. Default: `0`. 1. Patch the Chef Automate configuration: - ```bash + ```shell sudo chef-automate config patch ``` #### Configure automatic deletion of requested log export files -When a user requests audit logs through the API, Chef Automate generates a log export file and stores it in your configured bucket under the `requested-logs/` path prefix. +When you request audit logs through the API, Chef Automate generates a log export file and stores it in your configured bucket under the `requested-logs/` path prefix. These files are automatically cleaned up on an hourly schedule. To configure how long requested-log files are retained before deletion, follow these steps: @@ -291,7 +287,7 @@ To configure how long requested-log files are retained before deletion, follow t 1. Patch the Chef Automate configuration: - ```bash + ```shell sudo chef-automate config patch ``` @@ -303,6 +299,8 @@ To configure how long requested-log files are retained before deletion, follow t ## Audit log settings reference + + The following defines the default audit log storage settings. For a complete set of log storage settings, see the [reference examples](#audit-log-configuration-file-examples) below. @@ -335,6 +333,7 @@ For a complete set of log storage settings, see the [reference examples](#audit- max_concurrent_workers = 4 queue_size = 100 multipart_chunk_size = "10MB" + requested_logs_retention_duration = "1hr" ``` : `max_concurrent_workers` @@ -360,6 +359,16 @@ For a complete set of log storage settings, see the [reference examples](#audit- Format: `KB`, `MB`, or `GB` suffixes (use `"20MB"`, not `"20M"`). +: `requested_logs_retention_duration` + : Default value: `"1hr"` + + Controls how long requested audit log export files (stored under `requested-logs/` in your bucket) are kept before automatic hourly cleanup. + Valid formats: `"0"` (disabled), `"1hr"`, `"24hr"`, `"7d"`, `"30d"`, and so on. + Must use `hr` for hours or `d` for days. + For example, `"24h"` is not valid. Use `"24hr"`. + + If set to an invalid value, cleanup is disabled and a warning is logged. + `[global.v1.audit.input]` : The audit log input settings have the following defaults: @@ -514,7 +523,6 @@ For a complete set of log storage settings, see the [reference examples](#audit- Units: minutes only (`m`). `[global.v1.audit.retention]` - : Configures automatic daily cleanup of audit log objects stored in S3 or MinIO: ```toml @@ -531,12 +539,12 @@ For a complete set of log storage settings, see the [reference examples](#audit- A value of `0` disables automatic cleanup (unlimited retention). A value greater than 0 enables cleanup and sets the retention period. - Must be `>= 0`. + Must be greater than or equal to `0`. : `schedule_hour` : Default value: `2` - Hour of day (0-23) when the daily cleanup job runs. + Hour of day (0--23) when the daily cleanup job runs. Default is `2` (2 AM). : `schedule_minute` @@ -544,15 +552,7 @@ For a complete set of log storage settings, see the [reference examples](#audit- Minute (0-59) when the daily cleanup job runs. -: `requested_logs_retention_duration` (under `[global.v1.audit.async]`) - : Default value: `"1hr"` - - Controls how long requested audit log export files (stored under `requested-logs/` in your bucket) are kept before automatic hourly cleanup. - Valid formats: `"0"` (disabled), `"1hr"`, `"24hr"`, `"7d"`, `"30d"`, and so on. - Must use `hr` for hours or `d` for days. - For example, `"24h"` is not valid. Use `"24hr"`. - - If set to an invalid value, cleanup is disabled and a warning is logged. + ### Audit log configuration file examples @@ -587,7 +587,7 @@ The following TOML shows the default audit log settings: requested_logs_retention_duration = "1hr" [global.v1.audit.retention] - days = 0 + days = 30 schedule_hour = 2 schedule_minute = 0 @@ -629,6 +629,12 @@ The following example includes all available settings: max_concurrent_workers = 4 queue_size = 100 multipart_chunk_size = "10M" + requested_logs_retention_duration = "1hr" + + [global.v1.audit.retention] + days = 30 + schedule_hour = 2 + schedule_minute = 0 [global.v1.audit.storage] # Use "s3" for AWS S3 or "minio" for MinIO. @@ -669,7 +675,7 @@ All audit APIs require authentication. All endpoints accept a bearer token (JWT) in the `Authorization` header: -```bash +```shell curl -sS \ -H "Authorization: Bearer " \ "https:///api/v0/audit/..." @@ -686,7 +692,7 @@ The Self request API doesn't accept `api-token` authentication; use a bearer (JW Example using an API token header: -```bash +```shell curl -sS \ -H "api-token: $API_TOKEN" \ "https://$FQDN/api/v0/audit/admin/request" @@ -764,7 +770,7 @@ Response: - Access control: Self only (you can only view your own requested logs) - Query parameters: - `request_id` (optional): - - If omitted, returns the status of the latest request for the current user. + - If omitted, returns the status of your latest request. - If provided, returns the status for that specific request ID. Examples: @@ -816,7 +822,7 @@ Example (completed): - Access control: Self only (you can only download your own audit logs) - Query parameters: - `request_id` (optional): - - If omitted, returns the last requested audit log file for the current user. + - If omitted, returns your last requested audit log file. - If provided, returns the audit log file for that specific request ID. - Returns: The audit log file as a gzip-compressed download.