migtools · Tamar-Dinavetsky · Sep 3, 2026 · Sep 2, 2026 · Sep 3, 2026 · aufi
diff --git a/docs/commands/apply.md b/docs/commands/apply.md
@@ -24,6 +24,7 @@ Kustomize is embedded directly in the Crane binary (via the krusty API), so no e
 | `--skip-cluster-scoped` | | `false` | Exclude cluster-scoped resources (ClusterRole, ClusterRoleBinding, CRD, etc.) from output. Useful for non-admin migration scenarios |
 | `--overwrite` | | `false` | Overwrite the output directory if it already exists |
 | `--ordered` | | `false` | Prefix resource filenames with a numeric order (e.g., `300_Role_`, `310_RoleBinding_`) so that `kubectl apply -f` processes dependencies before dependents. Useful when first apply fails due to missing referenced resources |
+| `--audit-log` | | `audit/.crane-audit.log` | Path to the audit log file |
 
 Stages are specified as positional arguments (e.g., `crane apply 10_KubernetesPlugin`). Stages can be specified by directory name or plugin name. If no stages are specified, all discovered stages are applied sequentially.
 
@@ -70,6 +71,12 @@ Without `--ordered` (default), filenames have no prefix and `kubectl apply -f` p
 crane apply
 ```
 
+### Apply with custom audit log path
+
+```bash
+crane apply --audit-log=/var/log/crane-audit.log
+```
+
 ### Apply with custom directories
 
 ```bash

diff --git a/docs/commands/export.md b/docs/commands/export.md
@@ -14,6 +14,12 @@ crane export [flags]
 
 Exported resources are written as individual YAML files under `export/resources/<namespace>/`. Cluster-scoped resources related to the namespace (ClusterRoleBindings, ClusterRoles, SCCs) are written to `export/resources/<namespace>/_cluster/`. Any errors encountered during listing are recorded in `export/failures/<namespace>/`.
 
+### Audit Logging
+
+Every `crane` invocation automatically writes a structured JSON Lines audit log to `audit/.crane-audit.log`. This log captures the full execution history and is persistent across runs (append-only). Support engineers can use these logs to replay or troubleshoot past runs.
+
+> **Note:** If you are using a git-based workflow, add the `audit/` directory to your `.gitignore` file.
+
 ### CRD Collection
 
 When custom resources are found in the namespace, Crane automatically collects their corresponding CustomResourceDefinitions. Operator-managed CRDs (identified via owner references) are skipped, since they should be installed by the operator on the target cluster rather than migrated directly. If the migration user lacks permission to read CRDs, Crane logs a warning and continues — the assumption is that the CRDs already exist on the target.
@@ -31,6 +37,7 @@ When custom resources are found in the namespace, Crane automatically collects t
 | `--qps` | `-q` | `100` | Query-per-second rate for API requests |
 | `--burst` | `-b` | `1000` | API burst rate |
 | `--overwrite` | | `false` | Overwrite the export directory if it already exists |
+| `--audit-log` | | `audit/.crane-audit.log` | Path to the audit log file |
 
 Standard kubeconfig flags (`--kubeconfig`, `--context`, `--cluster`, `--as`, `--as-group`, etc.) are also available.
 
@@ -90,6 +97,12 @@ crane export -n my-app --label-selector "app=frontend"
 crane export -n my-app --export-dir ./migration/export
 ```
 
+### Export with custom audit log path
+
+```bash
+crane export -n my-app --audit-log=/tmp/crane-audit.jsonl
+```
+
 ### Export with impersonation
 
 ```bash

diff --git a/docs/commands/transfer-pvc.md b/docs/commands/transfer-pvc.md
@@ -63,6 +63,7 @@ crane transfer-pvc --source-context=source --destination-context=destination \
 | `--rclone-config-file` | string | No | Path to local rclone.conf file for indirect transfer |
 | `--encrypt` | bool | No | Enable client-side encryption for indirect transfer |
 | `--keep-cloud-data` | bool | No | Reserved for cloud-data retention; currently has no effect because cleanup is not implemented |
+| `--audit-log` | string | No | Path to the audit log file (defaults to `audit/.crane-audit.log`) |
 
 ### PVC Options
 
@@ -136,6 +137,17 @@ secret_access_key = <secret_key>
 region = us-east-1
 ```
 
+### Audit Logging
+
+`crane` maintains a persistent, structured JSON Lines audit log of all operations. This file is located at `audit/.crane-audit.log` by default.
+
+To save the audit log to a different location:
+```bash
+crane transfer-pvc --audit-log=/tmp/crane-transfer.log ...
+```
+
+> **Note:** The `audit/` directory is automatically created if it does not exist. It is recommended to add `audit/` to your `.gitignore` file to avoid tracking these logs in version control.
+
 ### Endpoint Options
 
 Endpoint enables a connection between the source and destination cluster for data transfer. It is created in the destination cluster. The destination cluster must support the kind of endpoint used.

diff --git a/docs/commands/transform.md b/docs/commands/transform.md
@@ -125,6 +125,9 @@ Each stage's `output/` becomes the next stage's `input/`, creating a sequential
 ```gitignore
 # Crane stage output directories (regenerated on each run)
 transform/*/output/
+
+# Audit logs
+audit/
 ```
 
 ### Running Multi-Stage Transforms
@@ -188,6 +191,21 @@ output/
 - **`resources/<namespace>/`**: Individual resource files organized by namespace for easier review and selective application
 - **`resources/_cluster/`**: Cluster-scoped resources (omitted when `--skip-cluster-scoped` is set)
 
+## Audit Logging
+
+Crane automatically records an audit trail of command executions. These logs are stored in the `audit/` directory.
+
+### Audit Configuration
+
+You can specify the location of the audit log file using the global `--audit-log` flag:
+
+```bash
+# Write audit logs to a custom location
+crane transform --audit-log=/var/log/crane-audit.log
+```
+
+**Note**: The audit log is created in the `audit/` directory by default. It is recommended to add `audit/` to your `.gitignore` file to prevent committing audit logs to version control.
+
 ## Automatic Stage Creation
 
 When no stages exist in the transform directory, `crane transform` automatically creates stages for **all available plugins** (not just KubernetesPlugin). Plugins are sorted alphabetically and assigned priorities starting at 10, incrementing by 5. Use `--skip-plugins` to exclude specific plugins from this default behavior.
@@ -466,6 +484,7 @@ kubectl apply -f output/output.yaml
 **Don't commit** (add to .gitignore):
 - `transform/*/output/` (materialized output, regenerated on each transform)
 - `output/` (generated by crane apply)
+- `audit/` (audit logs)
 
 Example `.gitignore`:
 
@@ -475,6 +494,9 @@ transform/*/output/
 
 # Final output directory
 output/
+
+# Audit logs
+audit/
 ```
 
 ### Reviewing Changes
@@ -536,9 +558,6 @@ ls -la transform/10_KubernetesPlugin/input/
 
 # Compare input vs output to see what was filtered
 diff -r transform/10_KubernetesPlugin/input/ transform/10_KubernetesPlugin/output/
-
-# Review plugin logs for whiteout/filtering
-crane transform --debug
 ```
 
 ## Advanced: Creating Custom Kustomizations

diff --git a/docs/commands/validate.md b/docs/commands/validate.md
@@ -16,6 +16,12 @@ This is the final step in the Crane migration pipeline: **export → transform
 
 Incompatible resources are written to a `failures/` directory under the validate-dir for auditability.
 
+### Audit Logging
+
+Every `crane` invocation creates a persistent, structured audit log in JSON Lines format. This allows for post-run analysis and troubleshooting.
+
+By default, the audit log is stored at `audit/.crane-audit.log`. You can customize this location using the `--audit-log` flag. Note that the `audit/` directory should be added to your `.gitignore` to prevent committing log files to version control.
+
 ### Offline Validation
 
 Use `--api-resources` to validate offline against a captured API surface JSON file when the target cluster is not directly reachable. This is mutually exclusive with `--context`, `--kubeconfig`, `--server`, `--token`, `--cluster`, and `--user`.
@@ -66,6 +72,7 @@ crane validate --api-resources api-surface.json
 | `--output` | `-o` | `json` | Report file format: `json` or `yaml` |
 | `--api-resources` | | | Path to API surface JSON file for offline validation (mutually exclusive with `--context`/`--kubeconfig`/`--server`/`--token`/`--cluster`/`--user`) |
 | `--overwrite` | | `false` | Overwrite the validate directory if it already exists |
+| `--audit-log` | | `audit/.crane-audit.log` | Path to the audit log file |
 
 Standard kubeconfig flags (`--kubeconfig`, `--context`, `--cluster`, etc.) are also available to specify the target cluster for live validation.
 
@@ -99,6 +106,12 @@ crane validate
 crane validate --context target-cluster
 ```
 
+### Validate with custom audit log path
+
+```bash
+crane validate --audit-log=/tmp/crane-audit.json
+```
+
 ### Validate with custom input directory
 
 ```bash