diff --git a/docs/commands/apply.md b/docs/commands/apply.md index 9003ab6b..3f421c35 100644 --- 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 index 3ff01b12..f99cca9b 100644 --- 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//`. Cluster-scoped resources related to the namespace (ClusterRoleBindings, ClusterRoles, SCCs) are written to `export/resources//_cluster/`. Any errors encountered during listing are recorded in `export/failures//`. +### 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 index be5069aa..2cd07996 100644 --- 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 = 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 index 4a3dfa18..9f069915 100644 --- 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//`**: 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 index 31abf431..ddd6d2fa 100644 --- 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