Configure OpenBao file audit declaratively

docs/openbao.md

@@ -162,12 +162,9 @@ break-glass material with the same handling as unseal shares.
 
 ## Initial Configuration After Unseal
 
-Enable file audit:
-
-```bash
-kubectl exec -n openbao openbao-0 -- \
-  bao audit enable file file_path=/openbao/audit/openbao-audit.log
-```
+File audit is configured declaratively in `helm/openbao-values.yaml` with a
+server config `audit "file" "file"` stanza that writes to
+`/openbao/audit/openbao-audit.log` on the audit PVC.
 
 Enable the first KV v2 mount:
 
@@ -187,8 +184,8 @@ configuration:
 make openbao-configure-initial
 ```
 
-The target prompts for a token, enables file audit when API-managed audit is
-available, enables the `platform/` KV v2 mount, enables Kubernetes auth,
+The target prompts for a token, verifies the declarative file audit device is
+visible, enables the `platform/` KV v2 mount, enables Kubernetes auth,
 configures Kubernetes auth from the in-pod service account, and loads:
 
 - `openbao/policies/platform-admin.hcl`
@@ -198,11 +195,9 @@ It does not print or store the token. You may also set
 `OPENBAO_TOKEN_FILE=/path/to/token-file` for an operator-local, uncommitted
 token file.
 
-Current OpenBao releases may reject API-managed audit setup with a message that
-audit devices must be configured declaratively. In that case the helper exits
-successfully with a warning after applying the other bootstrap configuration.
-Treat declarative audit configuration in the OpenBao server config/Helm values
-as mandatory before production secrets move in.
+OpenBao audit is a production gate. If `bao audit list` does not show `file/`,
+fix the declarative audit stanza or Helm rollout before moving production
+secrets into OpenBao.
 
 The helper is idempotent. Re-running it should report existing `platform/` and
 `kubernetes/` paths as already enabled instead of failing the ceremony.
@@ -261,7 +256,7 @@ The template policy for workload KV reads is
 
 Before any live application secrets move into OpenBao:
 
-1. Enable file audit and confirm an audit file is written under
+1. Confirm file audit is enabled and an audit file is written under
    `/openbao/audit/openbao-audit.log`.
 2. Create an OpenBao Raft snapshot from the unsealed pod:
 

helm/openbao-values.yaml

@@ -101,6 +101,14 @@ server:
           path = "/openbao/data"
         }
 
+        audit "file" "file" {
+          description = "Default file audit device on the OpenBao audit PVC."
+
+          options {
+            file_path = "/openbao/audit/openbao-audit.log"
+          }
+        }
+
         service_registration "kubernetes" {}
 
         telemetry {

scripts/openbao-apply-initial-config.sh

@@ -14,7 +14,7 @@ usage() {
 Usage: scripts/openbao-apply-initial-config.sh [--dry-run]
 
 Applies the first post-unseal OpenBao configuration:
-  - file audit device when API-managed audit is available
+  - declarative file audit visibility check
   - platform KV v2 mount
   - Kubernetes auth mount and in-cluster config
   - platform-admin and platform-readonly policies
@@ -108,30 +108,27 @@ write_policy() {
     sh -c 'read -r BAO_TOKEN; export BAO_TOKEN; bao policy write "$1" -' sh "$name"
 }
 
-enable_file_audit() {
+verify_file_audit() {
   local token="$1"
   local output status
-  if output="$(remote_bao "$token" audit enable file file_path=/openbao/audit/openbao-audit.log 2>&1)"; then
+  if [ "$DRY_RUN" -eq 1 ]; then
+    printf 'DRY-RUN: verify declarative OpenBao file audit device is visible with bao audit list\n'
+    return 0
+  fi
+  if output="$(remote_bao "$token" audit list 2>&1)"; then
     printf '%s\n' "$output"
+    if printf '%s\n' "$output" | grep -Eq '(^|[[:space:]])file/'; then
+      printf 'OK: OpenBao file audit device is configured.\n'
+    else
+      warn "OpenBao audit list did not show file/. Check declarative audit configuration before production trust."
+    fi
     return 0
   fi
 
   status=$?
-  case "$output" in
-    *"cannot enable audit device via API"*)
-      warn "OpenBao rejected API-managed audit enable. Configure audit devices declaratively in the OpenBao server config/Helm values."
-      return 0
-      ;;
-    *"path is already in use"*)
-      printf 'OK: OpenBao file audit device already appears to be enabled.\n'
-      return 0
-      ;;
-    *)
-      printf '%s\n' "$output" >&2
-      warn "OpenBao audit enable failed with exit code $status."
-      return 0
-      ;;
-  esac
+  printf '%s\n' "$output" >&2
+  warn "OpenBao audit list failed with exit code $status. Check declarative audit configuration before production trust."
+  return 0
 }
 
 enable_optional() {
@@ -168,7 +165,7 @@ show_audit_list() {
 
   status=$?
   if printf '%s\n' "$output" | grep -qi "No audit devices are enabled"; then
-    warn "No API-visible audit devices are enabled. Treat declarative audit configuration as a follow-up before production secrets."
+    warn "No API-visible audit devices are enabled. Check declarative audit configuration before production secrets."
     return 0
   fi
 
@@ -185,7 +182,7 @@ fi
 
 remote_bao "$token" status
 
-enable_file_audit "$token"
+verify_file_audit "$token"
 enable_optional "$token" "platform/ KV secrets engine is already enabled." secrets enable -path=platform kv-v2
 enable_optional "$token" "kubernetes/ auth method is already enabled." auth enable kubernetes
 

scripts/openbao-verify.sh

@@ -106,13 +106,19 @@ if [ "$MODE" = "basic" ]; then
 fi
 
 step "Post-unseal unauthenticated checks"
-if run exec -n "$OPENBAO_NAMESPACE" "$pod" -- sh -c 'test -d /openbao/audit'; then
+if run exec -n "$OPENBAO_NAMESPACE" "$pod" -- sh -c 'test -d /openbao/audit' >/dev/null 2>&1; then
   ok "audit directory exists"
 else
   warn "audit directory missing or inaccessible"
 fi
 
-if run exec -n "$OPENBAO_NAMESPACE" "$pod" -- sh -c 'test -d /openbao/data'; then
+if run exec -n "$OPENBAO_NAMESPACE" "$pod" -- sh -c 'test -s /openbao/audit/openbao-audit.log' >/dev/null 2>&1; then
+  ok "audit log file exists and is non-empty"
+else
+  warn "audit log file missing or empty; declarative file audit is not verified"
+fi
+
+if run exec -n "$OPENBAO_NAMESPACE" "$pod" -- sh -c 'test -d /openbao/data' >/dev/null 2>&1; then
   ok "raft data directory exists"
 else
   warn "raft data directory missing or inaccessible"

workplans/RAIL-PL-WP-0002-openbao-platform-secrets-service.md

@@ -244,6 +244,17 @@ Authenticated checks for audit devices, auth methods, and mounts still require
 the OIDC-backed or temporary platform-admin path and remain part of the
 production-readiness closeout.
 
+**2026-06-01:** Added the source-side declarative file-audit configuration
+required by `NET-WP-0017-T02`: `helm/openbao-values.yaml` now includes an
+OpenBao `audit "file" "file"` stanza writing to
+`/openbao/audit/openbao-audit.log`, and
+`scripts/openbao-apply-initial-config.sh` now verifies audit visibility with
+`bao audit list` instead of attempting API-managed audit creation. The
+post-unseal verifier now warns when the audit log file is missing or empty.
+Live verification still reports the pod unsealed and healthy, but also reports
+the audit log file missing because this Helm change has not yet been rolled
+out. Roll out only in an attended window with unseal shares available.
+
 ### T07 - Cross-Repo Transition Tasks
 
 ```task