Hadoop Migration CLI Reference (Bifrost)
The Bifrost CLI (bifrost) is the single entry point for every migration operation. Every command translates to a consistent, auditable sequence of automation steps under the hood; the user-facing surface is a command tree organized by migration path.
In a delivered bundle, commands are run through ./bifrost.sh in the bundle directory, which sets the Ansible configuration and the Python path, or as bifrost after activating the bundle's .venv. The examples on this page use bifrost.
Global Options
Usage: bifrost <path> [group options] <command> [command options]
Paths:
classic Path 1: CDP to Open-Source Hadoop
modernize Path 2: Hadoop to Ilum on Kubernetes
direct Path 3: CDP directly to Ilum on Kubernetes
Group options (after the path, before the command):
--dry-run Rehearse the run under Ansible check mode
--strict Promote WARN verdicts to non-zero exit (useful in CI)
--verbose Enable debug output
--log-file <path> Also write the log to this file (a new or empty file)
--no-notify Suppress notifications for this invocation
--env <name> Target Kubernetes environment (dev / staging / production)
Classic group options:
--node-state-dir <p> Node-side root for the phase-3 capture
--break-state-lock Proceed past a state-directory lock whose holder
cannot be proven alive
--break-cluster-lock Take over a cluster-side lock held by a run that is
no longer active
Command options:
--cluster <name> Source cluster name (Classic paths, and the
decommission command under any path; matches
inventory directory)
--source-cluster <n> Source cluster name (Modernize and Direct paths,
except decommission)
--execute Perform the change (without it, the command plans)
Group options are placed between the path and the command, for example bifrost classic --verbose discover --cluster prod01. Every command accepts --help for inline usage.
Classic commands that change the cluster only plan by default and act when --execute is given. --dry-run rehearses a run under Ansible check mode: no migration phase is intended to change the cluster, but read-only probes still reach it, Bifrost still writes its state directory, and the canary harness still submits real workloads.
Log output is written to standard error. --log-file adds a copy in a file and --verbose raises the level to debug. Every gate also writes its report to the state directory (see Exit Codes and Notifications).
Environment Variables
| Variable | Purpose |
|---|---|
BIFROST_STATE_DIR | State directory root (default /var/lib/bifrost/state). Holds the run record, gate reports, baselines, and rollback manifests of each cluster. |
BIFROST_NODE_STATE_DIR | Node-side capture root, equivalent to --node-state-dir. |
BIFROST_VAULT_PASS_FILE | Ansible Vault password file (default inventories/<cluster>/.vault_pass). |
CM_PASSWORD | Cloudera Manager API password for discover, instead of --cm-pass. |
BIFROST_AMBARI_PASSWORD | Ambari admin password for every command that calls the Ambari API. |
BIFROST_KMS_PASSWORD | Source KMS password when discovery reads keys with basic authentication. |
BIFROST_SMOKE_PASSWORD | Password of the smoke-test identity for smoke-keytab. |
BIFROST_ACK_SKIPPED_CHECKS | Comma-separated check IDs whose skipped CRITICAL check is acknowledged under --strict. |
BIFROST_FINALIZE_VALIDATE_POST_MAX_AGE_SECONDS | Maximum age of the validate-post result that finalize accepts (default seven days). It cannot be disabled. |
BIFROST_ESTATE_VALUES | Values file or estate name for bifrost classic estate and the console. |
Classic (Path 1) Commands
Commands are listed in the order a Classic migration uses them. For the end-to-end sequence, see Classic migration: phase pipeline.
| Stage | Commands |
|---|---|
| Assessment | discover, extract, scan-class-coverage, scan-metastore-schema, validate-plan, validate-pre, validate-ambari |
| Preparation | smoke-keytab, canary, stage-nodes, stage-bigtop, stage-ambari |
| Cutover | migrate, ambari-takeover, validate-post, replication-activate |
| Rollback and finalize | rollback, recertify-capture, finalize |
| Day-2 | patch, mirror-lock, renew-certificates, configuration plane, day2-drill, other day-2 commands, node lifecycle and keytabs |
| Operator workflow | estate, console |
bifrost classic discover
Non-destructive discovery of a Cloudera CDP cluster. Reads the Cloudera Manager API and, by default, connects to the cluster hosts over SSH to capture the deployed configuration files, the HDFS encryption zones, and their key versions. Produces the YAML inventory and the discovery files under inventories/<cluster>/. Returns PROCEED or WARN.
export CM_PASSWORD='...'
bifrost classic discover \
--cluster prod01 \
--cm-host cm.example.internal \
--cm-port 7183 \
--cm-user bifrost-readonly \
--cm-ca-bundle /etc/pki/bifrost/cm-ca.pem
Key flags:
| Flag | Purpose |
|---|---|
--cluster | Inventory directory name. Use the same name for every later command. |
--cm-host, --cm-port, --cm-user, --cm-pass | Cloudera Manager API credentials. A read-only account is sufficient; --cm-pass falls back to CM_PASSWORD. |
--cm-cluster | Cloudera Manager cluster name, when one Cloudera Manager manages several clusters. |
--cm-ca-bundle | PEM bundle that verifies the Cloudera Manager certificate. |
--no-tls | Turns certificate verification off, for lab environments. On port 7183 the request still uses HTTPS. |
--cm-timeout | Increase API timeout for clusters with >100 services (default 30 seconds). |
--no-capture-deployed | Reads the Cloudera Manager API only, without the SSH capture (useful as a first pass). |
--ez-kinit-keytab, --ez-kinit-principal | HDFS superuser identity used to list encryption zones on a Kerberized source. |
--kms-fetch-on, --kms-kinit-keytab, --kms-kinit-principal | Host and key administrator identity used to read encryption-zone key versions. |
--seed-cm-credential | Stores the Cloudera Manager password in the inventory vault for later phases. |
--output | Destination directory for discovery output (default inventories/<cluster>/). Leave it unset so that later commands find the inventory. |
Output tree: see Getting started: first discovery run.
bifrost classic extract
Transforms the discovered Cloudera Manager configuration into standalone Hadoop XML templates. Filters Cloudera-internal properties, expands safety valves, and produces a manual-review report for unmapped entries.
bifrost classic extract --cluster prod01
Extraction runs in three stages (raw extraction, property translation, and template generation) and always closes with a canonicalization diff against rendered source XML. Any remaining differences are captured for manual approval. Extraction also produces the adoption blueprint for the management plane and routes secrets to the inventory vault. The verdict is WARN while unexplained differences remain.
bifrost classic scan-class-coverage
Offline comparison of the Java classes referenced by the source configuration with the classes shipped in the target packages. A class the configuration references but the target packages lack is reported as a backport task and is never stripped from the configuration. The report is an input of the management plane takeover.
bifrost classic scan-class-coverage --cluster prod01 --build-output /srv/bifrost/bigtop-bundle
| Flag | Purpose |
|---|---|
--build-output | Directory, package, or JAR set of the target distribution to index. |
--class-index | Newline-separated list of class names to use instead of --build-output. |
--capture-jars | After the report, copies customer JARs referenced by the configuration from the source hosts, so that they are carried to the target. |
The report is written to extract/class_coverage.json and extract/class_coverage.md in the inventory.
bifrost classic scan-metastore-schema
Offline comparison of the source Hive Metastore schema with the schema of the target Hive version. Differences that can block metastore operations after the cutover are classified, so that they are resolved before the migration window.
bifrost classic scan-metastore-schema \
--cdp source-metastore-schema.sql \
--baseline target-hive-schema.sql \
--output metastore-schema-gaps.json
| Flag | Purpose |
|---|---|
--cdp | Schema-only dump of the source metastore database. |
--live | Reads the schema from the live metastore instead of a dump (Oracle metastores; requires --cluster). |
--baseline | Schema of the target Hive Metastore (required). |
--strict | Exit code 3 when a blocking schema difference is found. |
bifrost classic validate-plan
Validates the migration plan against the discovered estate: offline, read-only, no cluster access required. After discover and extract it answers the two questions that matter before anything destructive runs: did discovery miss anything the migration needs (completeness), and what will actually differ after the migration (drift, endpoints, service coverage). Returns PROCEED, WARN, or ABORT and writes a classified report to extract/plan_validation.md (plus a machine-readable .json and a per-key drill-down with secret values masked).
bifrost classic validate-plan --cluster prod01
Key flags:
| Flag | Purpose |
|---|---|
--ambari-source | Path to the Ambari stack definitions; arms target stack defaults, service-definition presence checks, and the offline stack advisor. |
--target-defaults | Directory of Apache *-default.xml source trees, extracted jars, or target RPMs (repeatable); deepens the drift verdicts with real target defaults. |
--bundle | Adopt bundle root; arms the adoption-chain checks (repository sanity, stack overlays). |
--live | Re-probe the running daemons' effective configuration now and diff against the captured tier, which proves the plan was not computed against a stale capture. Needs SSH to the cluster; without it the check reports a named skip. |
--waivers | Scoped waiver file; every waiver must name the check, the key or service, and a reason. |
--gate-mode | soft / hard / report: caps the exit code for chained runs; the report always carries the true findings. A standalone run reports the true verdict. |
Findings are classified by check family: drift against the estate's effective configuration, discovery completeness (every deployed key must have a recorded disposition), endpoint parity (a moved port or a dropped TLS endpoint is named before the cutover, not after), adoption-chain preflight, and stack-advisor deltas. Skips are always named, never silent. Re-run it after every re-extract; it is idempotent. For check families and the waiver file format, see Plan validation.
bifrost classic validate-pre
Runs the full pre-flight checklist. Returns PROCEED, WARN, or ABORT. Non-destructive.
bifrost classic validate-pre --cluster prod01
Checks include fsimage parseability against the target Hadoop version, edit log parseability, NameNode and DataNode layout versions, HBase HFile integrity, Hive Metastore schema validity, keytab validity, TLS certificate expiry, encryption zone documentation, reachable service ports, free disk space, presence of rollback assets, and a fsimage compatibility test on isolated test infrastructure. A detailed breakdown is in Classic migration: phase pipeline.
| Flag | Purpose |
|---|---|
--strict | Promotes a WARN verdict to a non-zero exit. |
--build-output, --class-index | Resolves the class references of the adoption plan already at this gate. |
--accept-missing-class | Comma-separated class names assessed and accepted as known gaps. |
--exclude-services | Services the later takeover will leave out. |
The report is written to validate-pre/report.md in the cluster's state directory.
bifrost classic validate-ambari
Checks the migration against the management plane without changing the cluster. An offline parity check always runs: every Cloudera Manager role must map to a component of the target stack, and items that need manual review are listed. With --ambari-host, the generated blueprint is also validated by Ambari and deleted afterwards; no cluster is created and no running service is touched.
bifrost classic validate-ambari --cluster prod01 --ambari-host ambari.example.internal
| Flag | Purpose |
|---|---|
--ambari-host | Ambari server host. Omit it for the offline parity check only. |
--ambari-port | Ambari port (default 8085; 8443 when Ambari serves HTTPS). |
--ambari-tls, --ambari-ca-bundle | HTTPS connection to Ambari and the CA bundle that verifies it. |
--stack-advisor | Also runs the stack advisor validations. |
--strict | Promotes a WARN verdict to a non-zero exit. |
The report is written to extract/parity.json and extract/parity.md in the inventory.
bifrost classic smoke-keytab
Places the keytab of the smoke-test identity on every node. The keytab is derived from the identity's password, read from BIFROST_SMOKE_PASSWORD or from standard input. Without --execute, the command verifies that every node already holds the keytab.
bifrost classic smoke-keytab --cluster prod01 --execute
| Flag | Purpose |
|---|---|
--password-stdin | Reads the password from one line of standard input. |
--group, --mode | Group and mode of the keytab file (defaults hadoop and 0440). |
--execute | Derives and places the keytab. |
bifrost classic canary
Before-and-after comparison of cluster state and behaviour. Signatures are recorded before the migration and after the management plane takeover, and the two snapshots are compared. See Before-and-after canary.
bifrost classic canary seed --cluster prod01 --execute
bifrost classic canary capture --cluster prod01 --snapshot cdp-before
# After the management plane takeover:
bifrost classic canary capture --cluster prod01 --snapshot post-takeover
bifrost classic canary verify --cluster prod01 --from cdp-before --to post-takeover --gate-mode hard
| Subcommand | Purpose |
|---|---|
prereqs | Provisions the canary identity and trust material on a secured cluster. Re-run after every cluster rebuild. |
seed | Writes a small deterministic dataset to the live source under the canary namespace. Plans only without --execute. |
capture | Records the signatures of every enabled service at a snapshot (--snapshot cdp-before, post-bigtop, or post-takeover). Read-only by default; --workload adds jobs that write to HDFS scratch space. |
verify | Compares two snapshots (--from, --to), writes the report, and returns a verdict. --gate-mode sets how a mismatch is treated: soft, hard, or report. |
report | Renders the before-and-after report without changing the exit code. |
cleanup | Removes the canary objects. Reports only without --execute. |
bifrost classic stage-nodes
Installs only the prerequisites that the cluster nodes lack, such as the JDK for the management plane or a database driver, and reuses what is already present. --builder names a proxy host for package installation when the nodes have no repository access.
bifrost classic stage-nodes --cluster prod01
bifrost classic stage-bigtop
Stages a local mirror of the Ilum Bigtop distribution on every node, so that the cutover installs without network access. The command refuses before any transfer when a node lacks the disk space for the mirror.
bifrost classic stage-bigtop --cluster prod01 --from /srv/bifrost/bigtop-bundle
| Flag | Purpose |
|---|---|
--from | Pre-seeded package repository on the controller (air-gapped installations). |
--component-java-home | The JDK the takeover will use for the adopted components, so that staged packages resolve against it. |
bifrost classic stage-ambari
Installs and sets up the Apache Ambari (Ilum build) server from a delivered bundle, on PostgreSQL or Oracle. After the migration, the same command upgrades or downgrades Ambari with --roll-packages.
bifrost classic stage-ambari --cluster prod01 --from /srv/bifrost/ambari-bundle
| Flag | Purpose |
|---|---|
--from | Ambari bundle directory on the controller. |
--ambari-tls, --ambari-port, --ambari-ca-bundle | How Bifrost reaches the Ambari API (default port 8085; 8443 with HTTPS). |
--bootstrap-admin | Sets the first admin password from BIFROST_AMBARI_PASSWORD. Requires --execute. |
--roll-packages | Upgrades or downgrades the Ambari agents one host at a time and then the server. Requires --from and --reapply-service-defs. |
--ambari-db-backup-ref | Reference to the database team's backup of the Ambari schema, required with --roll-packages when Bifrost does not dump the database itself (Oracle or a remote database). |
--exclude-services | Services the later takeover will leave out. |
--execute | Required to restart an Ambari server that is already running. |
bifrost classic migrate
Executes the cutover: the in-window preflight and security steps, then phases 3 to 7 (backup, stop services, swap packages, deploy configurations, start services). Two strategies are available; pick based on cluster size. On the default version-aligned target, services are started by the management plane takeover, which is followed by validate-post.
# Stop-and-swap (for clusters with fewer than 30 nodes)
# Without --execute, the command plans only:
bifrost classic migrate \
--cluster prod01 \
--strategy stop-and-swap
bifrost classic migrate \
--cluster prod01 \
--strategy stop-and-swap \
--execute
# Shrink-and-grow (for larger production clusters)
bifrost classic migrate \
--cluster prod02 \
--strategy shrink-and-grow \
--batch-size 10 \
--execute
Flag details:
| Flag | Purpose |
|---|---|
--strategy | stop-and-swap or shrink-and-grow. |
--batch-size | Number of DataNodes processed per wave in shrink-and-grow. |
--execute | Required to run the destructive phases (without it, the command only plans). |
--from-phase | Resumes an interrupted cutover from backup, stop-services, swap-packages, deploy-configs, or start-services. |
--no-auto-rollback | Leaves the cluster mid-cutover after an ABORT for diagnosis in place. Automatic rollback is on by default. |
--mode | Canary preset for the embedded before-and-after gate: light, full, or report. |
--skip-canary | Skips the embedded canary gate for this run. Validation still runs. |
bifrost classic ambari-takeover
Phase 9. Adopts the migrated cluster into Apache Ambari (Ilum build), operated directly or through Ilum Cluster Ops. The takeover places keytabs and TLS material, carries Ranger plugins and Atlas hooks, imports replication schedules in a paused state, starts every service, and enables automatic restart. Without --execute, the adoption blueprint is checked and nothing is created. See Management plane.
export BIFROST_AMBARI_PASSWORD='...'
bifrost classic ambari-takeover --cluster prod01 \
--ambari-host ambari.example.internal \
--from /srv/bifrost/ambari-bundle
bifrost classic ambari-takeover --cluster prod01 \
--ambari-host ambari.example.internal \
--from /srv/bifrost/ambari-bundle \
--execute
| Flag | Purpose |
|---|---|
--ambari-host | Ambari server host (required). |
--ambari-port, --ambari-tls, --ambari-ca-bundle | How Bifrost reaches the Ambari API (default port 8085; 8443 with HTTPS). |
--from | Ambari bundle used by stage-ambari. The Ambari agent installs from it on every node. |
--component-java-home | JDK for all adopted components. Unset, the source JDK 11 is used, or a JDK 11 present on every host. |
--exclude-services | Services to leave out of the adoption. |
--resume-from | Resumes at a named step after an interrupted run. Earlier steps are verified before they are skipped. |
--accept-missing-class | Comma-separated class names assessed and accepted as known gaps. |
--un-adopt | Removes the Ambari cluster again (with --execute). The full inverse is rollback --from-adopted. |
--execute | Required to adopt (without it, the command only plans). |
bifrost classic validate-post
Comprehensive post-migration validation against the pre-migration baseline. On the default path, it runs after the management plane takeover.
bifrost classic validate-post \
--cluster prod01 \
--ambari-host ambari.example.internal
Validates HDFS write-read cycle, HDFS fsck cleanliness, block count parity, HBase meta scan, Hive table count parity, Kafka consumer offsets, Kerberos authentication, policy enforcement, encryption zone accessibility, and performance benchmarks (TeraSort, TestDFSIO). Warns on regressions greater than 20 %. The performance benchmarks belong to the functional tier, which is enabled with --workload.
| Flag | Purpose |
|---|---|
--baseline | Pre-migration baseline directory (default: the baseline recorded for the cluster in the state directory). |
--ambari-host, --ambari-ca-bundle | Ambari endpoint for the management plane checks. |
--workload | Runs the functional tier, which submits real jobs to the cluster. |
--only, --skip | Runs a subset of sections for diagnosis. A partial run cannot return PROCEED. |
--rollback-on-abort | Rolls back automatically on ABORT. Off by default. |
bifrost classic replication-activate
Runs a dry run of each Cloudera Manager replication schedule imported during the takeover and activates the schedules whose dry run reads their source. One-time schedules and schedules that were paused in Cloudera Manager stay paused.
bifrost classic replication-activate --cluster prod01 --ambari-host ambari.example.internal --execute
| Flag | Purpose |
|---|---|
--schedule | Limits the run to the named schedules (comma-separated). |
--wait | Seconds to wait for each dry run (default 1800). |
--execute | Runs the dry runs and activates the schedules. |
bifrost classic rollback
Available at any point before bifrost classic finalize. Without --execute, the command shows a preview.
# Rollback to a specific phase
bifrost classic rollback --cluster prod01 --to-phase backup --execute
# Rollback after the management plane takeover
bifrost classic rollback --cluster prod01 --from-adopted \
--ambari-host ambari.example.internal --execute
# Check the pre-write fences before a migration window
bifrost classic rollback --cluster prod01 --preflight
Without --execute, Classic commands print the plan only:
# Rollback a specific node (shrink-and-grow scenarios)
bifrost classic rollback --cluster prod01 --node dn-042.example.internal
| Flag | Purpose |
|---|---|
--to-phase | backup, after-swap, or after-services-started. Unset, the target is derived from the recorded progress. |
--from-adopted | Removes the management plane adoption first (un-adopt, restore of the pre-adoption configuration, removal of Ambari), then runs the ordinary rollback. Requires --ambari-host. |
--preflight | Runs only the pre-write checks and writes nothing. |
--verify | Runs only the post-rollback checks. |
--resume, --from-the-start | Finishes or repeats a rollback that stopped after Cloudera Manager came up. |
--external-db-backup-ack, --parity-db-divergence-ack, --accept-orphaned-ez | Acknowledgements for this run only, required in specific situations. |
--execute | Required to perform the rollback. |
A rollback that does not complete exits with code 5. See Validation and rollback for the complete rollback model.
bifrost classic recertify-capture
Re-records the checksums of the phase-3 credential capture in the existing rollback manifest after an integrity refusal. Plans only without --execute.
bifrost classic recertify-capture --cluster prod01 --execute
bifrost classic finalize
Irreversible. Removes the distribution package cache, snapshots, and all rollback assets.
bifrost classic finalize --cluster prod01 --confirm-irreversible --execute
--confirm-irreversible is required, and without --execute the command plans only. Finalize refuses unless every HDFS encryption-zone key is proven decryptable on the target and a fresh validate-post returned PROCEED. Bifrost recommends a 5-business-day soak of clean operation before finalize. Re-run validate-post at the end of the soak: finalize accepts only a PROCEED at most seven days old by default (BIFROST_FINALIZE_VALIDATE_POST_MAX_AGE_SECONDS).
bifrost classic patch
Rolls a package set through Ambari one host at a time, with a health gate between hosts, and then restarts every daemon that still runs a replaced file. Lock the package mirror on the target release with mirror-lock first. See Day-2 operations: patching.
bifrost classic patch --cluster prod01 \
--package '<package-glob>' \
--component KAFKA_BROKER \
--strategy rolling \
--ambari-host ambari.example.internal \
--execute
| Flag | Purpose |
|---|---|
--package | Package glob to upgrade from the mirror (required, repeatable). |
--component | Ambari component to stop and start on each host (required, repeatable). |
--hosts | Host order: a canary host first, standby before active. |
--strategy | rolling (one host at a time) or coordinated (stop all selected components, patch all hosts, start them together). |
--rollback-to | Installs an exact earlier version and release, including downgrades. |
--execute | Applies the change. Without it, the command records a baseline and plans. |
bifrost classic mirror-lock
Locks the local package mirror on every node on one release of a module. Checksums are verified, and superseded releases are kept for a later downgrade.
bifrost classic mirror-lock --cluster prod01 \
--prefix '<package-prefix>' \
--release '<version>-<release>' \
--from /srv/bifrost/rpms/<module> \
--execute
| Flag | Purpose |
|---|---|
--prefix | Package name prefix the lock applies to (required). |
--release | Version and release to keep (required). |
--from | Directory that holds the packages of that release (required). |
--promote-to, --module | Promotes the packages to a release share first. |
--execute | Applies the lock. Without it, the command plans only. |
bifrost classic renew-certificates
Renews the TLS material of the adopted cluster from the customer's PKI files and rolls the affected services one host at a time. See Day-2 operations: certificate renewal.
# Verify the upload and plan
bifrost classic renew-certificates --cluster prod01 --from /srv/pki/renewal
# Stage, roll, and verify
bifrost classic renew-certificates --cluster prod01 --from /srv/pki/renewal --execute
| Flag | Purpose |
|---|---|
--from | Upload directory with ca/, hosts/<fqdn>/, and hosts/_shared/. |
--hosts | Host order (default: every host running a TLS-enabled component). |
--accept-anchor-change | Allows the set of trusted CA certificates to change. |
--rollback-to | Restores the material an earlier run replaced, using that run's manifest.json. |
--execute | Stages and rolls the new material. Without it, the upload is verified and nothing is written. |
Configuration Plane Commands
The takeover certifies the configuration it adopted. These commands detect and reverse later changes made outside Bifrost. All three plan only without --execute.
| Command | Purpose |
|---|---|
certify-config-plane | Records the configuration Ambari holds as the certified baseline. --declare-adopted-types asks the Ambari stack advisor to keep the carried values. |
restore-config-plane | Restores every service whose configuration moved away from the certified version, through Ambari configuration versions. Restarts no daemon; --refresh-clients re-renders client configurations. |
refresh-clients | Re-renders client configuration files that Ambari reports as stale. No daemon is restarted. |
bifrost classic day2-drill
Runs the day-2 acceptance drill of the management plane. Every block is bracketed by canary captures, and every restart is proven by a new process. --execute requires bifrost_day2_drill_allowed: true in the inventory. See Day-2 acceptance drill.
bifrost classic day2-drill --cluster prod01 --ambari-host ambari.example.internal --execute
| Flag | Purpose |
|---|---|
--blocks | Comma-separated block IDs to run (default: every block, in order). |
--resume | Resumes the named run at its next step. |
--restart-block, --rerun-block | With --resume: starts an interrupted block over, or repeats a block that passed. |
--canary-mode | light (default) or full. |
--keep-going | Continues with the next block after a failed one. |
--execute | Runs the blocks. Without it, the plan is printed. |
Other Day-2 Commands
All of the following plan only without --execute.
| Command | Purpose |
|---|---|
restart-kms | Restarts Ranger KMS one host at a time through Ambari. --hsm-ack is required for HSM-backed key stores. |
atlas-upgrade | Upgrades the Atlas server package to --target-version, with HBase snapshots and a search index rebuild. |
daemon-limits | Carries the source per-daemon process and open-file limits to the adopted cluster and restarts daemons that run below them. |
impala-ha | enable or disable adds or removes the second Impala statestore and catalog service on --host. |
ranger-plugin-trust | Gives a Ranger plugin trust in an HTTPS Ranger Admin and restarts it one host at a time. |
kafka-jaas-parity | Restores the Kafka broker JAAS entry needed for SCRAM authentication; --roll-brokers restarts brokers one at a time. |
displace-cm-residue | Moves leftover Cloudera Manager directories under the adopted tree aside. Nothing is deleted. |
retract-group-grants | Removes supplementary group memberships the adoption added and no longer needs. |
Classic day-2 operations
Day-2 operations run through Apache Ambari (Ilum build), operated directly or through Ilum Cluster Ops, together with the commands above. The following commands are also part of the Classic command tree. Without --execute, Classic commands print the plan only.
# Decommission a node
bifrost classic decommission --cluster prod01 --host worker-042.example.internal
# Add a node to the cluster
bifrost classic add-node --cluster prod01 --host worker-120.example.internal --role datanode
# Rotate Kerberos keytabs
bifrost classic rotate-keytabs --cluster prod01
The Modernize and Direct paths also expose a source-side Kerberos keytab refresh for long-running migrations against a Kerberized source HDFS:
bifrost modernize rotate-keytabs --source-cluster PROD01
bifrost direct rotate-keytabs --source-cluster PROD01
This refreshes the controller-side keytab cache and re-authenticates in-flight DistCp runs. It does not modify the source cluster.
bifrost classic estate
Runs the Classic phase chain from one values file per cluster. The values are rendered into the inventory, and every phase runs the corresponding command. A flag given on the command line always overrides the values file. The values file is selected with --values or BIFROST_ESTATE_VALUES.
bifrost classic estate plan --values prod01
bifrost classic estate run discover --values prod01 --execute
bifrost classic estate next --values prod01
| Subcommand | Purpose |
|---|---|
check | Readiness list for the values file and its inputs. |
render | Renders the values into the inventory (--write applies them). |
plan | Prints the phase chain as the commands estate run would start. |
preflight | Runs a phase's named checks before its window. |
run | Runs one phase, synchronously or detached with --bg. The cutover and the takeover ask for a typed confirmation word. |
status | Shows a running or finished phase, its progress, and the end of its log. |
report | One row per phase for the migration report. --scrub replaces host names and identities with aliases. |
record | Records a phase run performed outside the runner. |
next | Shows the next command to run. |
operator-change | Applies declared configuration changes through Ambari, then refreshes clients and certifies the configuration. |
bifrost console
Opens the Heimdall terminal console on the controller (see Operator console for a step-by-step guide). It shows the phase chain with state and estimated time, the log of the running phase, and the command line behind every action, and it starts, stops, and resumes phases through the same commands as the CLI. The console is also available as bifrost heimdall, and as ./heimdall in a delivered bundle.
./bifrost.sh console
| Flag | Purpose |
|---|---|
--values | Values file or estate name to open. |
--demo | Opens a generated example workspace, without a cluster. |
Modernize (Path 2) Commands
bifrost modernize discover
Inventories the source Hadoop estate and produces a scored migration plan.
bifrost modernize discover --source-cluster PROD01
Output tree: see Getting started: first discovery run.
bifrost modernize plan
Generates or updates the phased migration plan.
# Generate an initial plan
bifrost modernize plan \
--source-cluster PROD01 \
--target-env production \
--waves 8 \
--max-parallel 8
# View the current plan
bifrost modernize plan --show
# Move a specific table between waves
bifrost modernize plan \
--move-table production_db.customers \
--to-wave 1
bifrost modernize land
Deploys the complete Kubernetes target platform via Helm.
# Deploy with the production profile
bifrost modernize land \
--env production \
--profile production \
--values modernize/helm/values-production.yaml
# Deploy a minimal dev environment
bifrost modernize land --env dev --profile dev
# Check platform health after deployment
bifrost modernize land --status
The platform components that are provisioned are listed in Target platform architecture.
bifrost modernize validate-pre
Non-destructive pre-flight check for the target platform. Runs before any wave execution and verifies that the platform is healthy enough to accept migration traffic.
bifrost modernize validate-pre --env production
Checks performed, grouped by the phase they gate:
Gates Phase 2 (bridge) and Phase 3 (table migration), always blocking:
- Object storage cluster in
HEALTH_OKand below the configured utilization threshold. - Catalog service reachable and accepting OAuth2 client_credentials.
- Trino interactive and ETL clusters responding to health probes.
- OIDC flow to Keycloak succeeds (tested via authorization-code server flow with a pre-seeded test user, and via client_credentials for service accounts; no interactive browser flow is exercised).
- OPA sidecar reachable; a Bifrost-supplied test-policy bundle is loaded and returns
allow=truefor the synthetic test principal. - Connectivity from Kubernetes pods to legacy HDFS (for DistCp).
- Container registry reachable for Spark, Trino, Airflow images.
Informational; gates Phase 4 (workflow conversion) only:
- Airflow scheduler heartbeat current; a test DAG can be parsed.
Returns PROCEED, WARN, or ABORT with the same semantics as the Classic pre-flight. See Validation and rollback: Decision Engine Gates.
bifrost modernize bridge
Configures the dual-read strangler facade.
# Enable the bridge
bifrost modernize bridge \
--source-cluster PROD01 \
--target-env production \
--sync-interval 1h
# Check bridge status
bifrost modernize bridge --status
# Disable the bridge (rolls back redirection rules via Helm upgrade + Trino reload)
bifrost modernize bridge --disable
bridge configures Trino with both legacy and modern catalogs, enables table redirection for migrated tables, starts a periodic DistCp warm-sync, and prepares Spark (via Ilum) to read from both the legacy and modern storage paths.
Key flags:
| Flag | Purpose |
|---|---|
--source-cluster | Source cluster inventory name. |
--target-env | Target Kubernetes environment (dev / staging / production). |
--sync-interval | Interval for the DistCp warm-sync loop. Accepts Go-duration strings (30m, 1h, 6h). Default 1h. |
--status | Report the bridge's current state and warm-sync lag without changing anything. |
--disable | Remove redirection rules via a Helm upgrade of the Trino catalog config, followed by a coordinator reload. Does not delete migrated tables. |
bifrost modernize migrate-table
Migrates a single table from Hive on HDFS to Iceberg on object storage.
# Safe, reversible, no data copy
bifrost modernize migrate-table \
--table production_db.customers \
--strategy snapshot
# Destructive in-place conversion, faster for large stable tables
bifrost modernize migrate-table \
--table production_db.transactions \
--strategy migrate
# Additive import with re-partitioning
bifrost modernize migrate-table \
--table production_db.events \
--strategy add_files \
--partition-spec "year(event_date)"
Strategy guidance: see Modernize migration: table migration strategies.
bifrost modernize migrate-catalog
Bulk catalog migration without copying data. Moves table references between catalogs.
bifrost modernize migrate-catalog \
--source-type HIVE \
--target-type REST \
--target-uri https://polaris.example.internal/api/catalog \
--identifier-file tables_wave3.txt \
--dry-run
bifrost modernize migrate-wave
Migrates every table in a wave concurrently.
# Migrate wave 3 with up to 8 tables in parallel
bifrost modernize migrate-wave --wave 3 --parallel 8
# Check wave status
bifrost modernize migrate-wave --wave 3 --status
bifrost modernize migrate-storage
Bulk data movement from HDFS to object storage.
# DistCp (default, for historical data)
bifrost modernize migrate-storage \
--source hdfs:///data/warehouse \
--target s3a://lakehouse/warehouse \
--method distcp \
--mappers 20 \
--bandwidth 500
# Continuous replication
bifrost modernize migrate-storage \
--source hdfs:///data/warehouse \
--target s3a://lakehouse/warehouse \
--method continuous
# Incremental sync
bifrost modernize migrate-storage \
--source hdfs:///data/warehouse \
--target s3a://lakehouse/warehouse \
--method distcp \
--update \
--delete
Accepted --method values:
| Value | Mechanism | Use case |
|---|---|---|
distcp | Hadoop DistCp with the magic committer | Bulk historical data |
continuous | Paxos-coordinated live-data replication (partner integration) | Continuous replication of live, changing data |
juicefs | JuiceFS bridge exposing object storage through the HDFS SDK | Applications that require native HDFS SDK compatibility |
ozone | Two-step migration via Apache Ozone (ofs:// scheme, then object-storage) | Legacy estates already running Ozone |
--mappers, --bandwidth, --update, --delete apply to the distcp method. --kerberos-principal and --kerberos-keytab apply to any method when the source HDFS is Kerberized.
The Bifrost CLI uses double-dash flags (--mappers, --bandwidth, --update, --delete) and translates them to the native DistCp form internally (-m, -bandwidth, -update, -delete). When tuning DistCp directly outside Bifrost, use the single-dash native form.
--bandwidth expresses the per-mapper throughput cap in MB/s and accepts a floating-point value (for example, --bandwidth 0.5). The cap is approximate. Fewer mappers at higher bandwidth per mapper usually outperforms many mappers against the same object storage endpoint.
bifrost modernize convert-workflow
Converts Oozie workflows to Airflow 3 DAGs and extracts Hive SQL into dbt models.
# Convert a single workflow
bifrost modernize convert-workflow \
--oozie-path /user/oozie/workflows/etl-daily-revenue \
--output-dir airflow/dags/
# Convert every workflow in a directory tree
bifrost modernize convert-workflow \
--oozie-path /user/oozie/workflows/ \
--output-dir airflow/dags/ \
--recursive
# Extract SQL into dbt models during conversion
bifrost modernize convert-workflow \
--oozie-path /user/oozie/workflows/etl-daily-revenue \
--output-dir airflow/dags/ \
--extract-dbt \
--dbt-project-dir dbt/lakehouse/
Action-type coverage: see Component migrations: workflows.
bifrost modernize hue-import
Migrates HUE saved queries and dashboards to Superset.
bifrost modernize hue-import \
--hue-db-host hue.example.internal \
--hue-db-name hue \
--hue-db-user hue \
--hue-db-pass "$HUE_DB_PASSWORD" \
--target-superset https://superset.example.internal \
--superset-admin-user admin \
--superset-admin-pass "$SUPERSET_PASSWORD" \
--user-mapping-file user_mapping.csv
Items that must be rebuilt manually are listed in Component migrations: user interface.
bifrost modernize validate
Runs validation for migrated tables.
# Validate a single table
bifrost modernize validate \
--table production_db.customers \
--type data-diff
# Validate every table in a wave
bifrost modernize validate \
--wave 3 \
--type data-diff \
--sample-rate 0.01
# Query parity test (compare legacy vs. modern results)
bifrost modernize validate \
--type query-parity \
--query-file benchmark_queries.sql \
--source-engine hive \
--target-engine trino
bifrost modernize rollback
Reverts one or more migrated tables to their pre-migration state. Invoked automatically by Bifrost when validation fails; the command is also available for operator-initiated reverts.
# Revert a single table
bifrost modernize rollback --table production_db.customers
# Revert every table in a wave (only after the wave is COMPLETE or FAILED)
bifrost modernize rollback --wave 3
--table and --wave are mutually exclusive. The revert mechanism depends on the migration strategy used for the table:
migratestrategy: the Iceberg table is dropped and the original Hive table is renamed back from<name>_BACKUP_to<name>. Metadata operation; microseconds.snapshotstrategy: the Iceberg table is dropped and table redirection is disabled. The source Hive table was never modified, so nothing is renamed back.add_filesstrategy: the imported files are removed from the Iceberg table's metadata; source files remain untouched.
Use --wave only after migrate-wave has finished (either COMPLETE or FAILED). While a wave is actively running, use --table per-table to avoid racing against in-flight migrations. Pause the wave with bifrost modernize migrate-wave --wave <n> --pause first if a bulk revert is required mid-wave.
bifrost modernize decommission
Decommissions a legacy service after a confirmed silence period.
# Decommission HDFS after 30 days of silence
bifrost modernize decommission \
--service hdfs \
--cluster PROD01 \
--after-silence 30d
# Dry-run decommission readiness check
bifrost modernize decommission \
--service yarn \
--cluster PROD01 \
--after-silence 30d \
--dry-run
Required flags by --service value:
| Service value | Required flags | Optional flags |
|---|---|---|
hdfs, yarn, hive, hbase, kafka, oozie, ranger, atlas, hue, solr | --cluster, --after-silence | --dry-run |
cloudera-manager (Direct only) | --cm-host, --confirm-irreversible | --dry-run |
--after-silence does not apply to the Cloudera Manager shutdown because there is no legacy data access to monitor after every cluster under it has already been decommissioned.
Note on cluster flags. The decommission command is service-scoped rather than path-scoped; it accepts --cluster under every path (Classic, Modernize, Direct), which is the single exception to the Global Options rule that Modernize and Direct use --source-cluster.
bifrost modernize status
Shows migration progress across storage, tables, workloads, and services.
bifrost modernize status
Example output:
Bifrost Modernize Status: PROD01 -> production
==================================================
Storage Migration: ################.... 78% (179 TB / 230 TB)
Table Migration: ##############...... 68% (2,847 / 4,187 tables)
Workload Conversion: ########............ 42% (156 / 371 workflows)
Service Replacement: ##################.. 88% (7 / 8 services)
Current Wave: 5 of 8
Tables in Progress: 23
Tables Blocked: 2 (manual review required)
Active Issues:
WARN production_db.risk_scores: 22 % slower on Trino (within tolerance)
TODO etl-risk-model coordinator: manual Airflow Dataset definition needed
BLOCK production_db.hbase_audit: HBase schema review pending (coprocessor detected)
Dashboard: https://superset.example.internal/bifrost-migration
Direct (Path 3) Commands
Direct combines Classic discovery and extraction with Modernize execution. The CLI namespace is bifrost direct, and every Modernize command is also aliased under Direct.
bifrost direct discover
Combines Cloudera Manager extraction with modernization estate scoring in a single pass.
bifrost direct discover \
--cm-host cm.example.internal \
--cm-port 7183 \
--cm-user admin \
--cm-pass "$CM_PASSWORD" \
--source-cluster PROD01 \
--output plans/prod01/
Key flags:
| Flag | Purpose |
|---|---|
--source-cluster | Name of the source CDP cluster; becomes the plan directory. |
--cm-host, --cm-port, --cm-user, --cm-pass | Cloudera Manager API credentials. Same semantics as classic discover. |
--no-tls | For lab environments where Cloudera Manager is not TLS-protected. |
--cm-timeout | Increase API timeout for clusters with more than 100 services (default 30 seconds). |
--output | Destination directory for discovery output. |
bifrost direct plan
Produces a migration plan that goes directly from CDP to the Kubernetes lakehouse. Includes a CDP dependency analysis step that identifies Cloudera-specific integrations and maps them to open alternatives or flags them for manual handling.
bifrost direct plan \
--source-cluster PROD01 \
--target-env production \
--waves 8 \
--max-parallel 8
bifrost direct land
Identical to bifrost modernize land. Deploys the Kubernetes target platform.
bifrost direct land --env production --profile production
bifrost direct migrate-wave
Executes the combined migration for every table in a wave. For each wave, Bifrost extracts the relevant table or service configuration from the source, translates it directly into Kubernetes-native equivalents (skipping an intermediate Hadoop XML representation), migrates data from source HDFS to object storage, converts Hive tables to Iceberg, and validates via data-diff.
# Migrate a specific wave
bifrost direct migrate-wave --wave 3 --parallel 8
# Migrate storage directly from CDP HDFS to object storage
bifrost direct migrate-storage \
--source hdfs:///data/warehouse \
--target s3a://lakehouse/warehouse \
--method distcp \
--kerberos-principal [email protected] \
--kerberos-keytab /var/lib/bifrost/keytabs/bifrost.keytab
Kerberos flags are required when migrating directly from a Kerberized CDP HDFS. Bifrost captures the keytab during discovery and manages kinit automatically. The same Kerberos flags are accepted by bifrost modernize migrate-storage when the legacy HDFS source is Kerberized.
Other Direct commands
Every Modernize command is available under Direct with identical syntax. For each, consult the Modernize documentation for flags and examples; only the command prefix changes from bifrost modernize to bifrost direct:
bifrost direct bridge --source-cluster PROD01 --target-env production --sync-interval 1h
bifrost direct migrate-table --table production_db.customers --strategy snapshot
bifrost direct convert-workflow --oozie-path /user/oozie/workflows/ --output-dir airflow/dags/ --recursive
bifrost direct hue-import --hue-db-host hue.example.internal --target-superset https://superset.example.internal
bifrost direct validate --wave 3 --type data-diff
bifrost direct decommission --service hdfs --cluster PROD01 --after-silence 30d
bifrost direct status
The only behavioural difference is that bifrost direct decommission can additionally shut down Cloudera Manager as the last step of the program:
bifrost direct decommission \
--service cloudera-manager \
--cm-host cm.example.internal \
--confirm-irreversible
Exit Codes and Notifications
Every gate ends in a verdict: PROCEED, WARN, or ABORT. Bifrost maps verdicts and failures to exit codes:
| Exit code | Meaning |
|---|---|
0 | PROCEED, or WARN without --strict. |
1 | Unexpected error or invalid usage. |
2 | ABORT verdict from the decision engine, or a refusal at an irreversible step. |
3 | WARN under --strict. |
4 | The source cluster could not be reached. |
5 | A rollback ran but did not complete. |
64 | The command is not available in this release. |
Each check carries a status (PASS, FAIL, WARN, or SKIPPED) and a severity (INFO, WARNING, or CRITICAL). A failed CRITICAL check returns ABORT. A failed WARNING check, a warning, or a skipped CRITICAL check returns WARN. Skipped checks are classified as NOT_APPLICABLE (the feature is absent), NOT_ASKED (an optional probe was off), NOT_MEASURABLE (the source could not be read), or UNCLASSIFIED. A skipped CRITICAL check that is not NOT_APPLICABLE caps the verdict at WARN, so a gate never returns PROCEED over an unanswered question. Under --strict, an unacknowledged skipped CRITICAL check in a pre-flight gate returns ABORT; reviewed skips are acknowledged with BIFROST_ACK_SKIPPED_CHECKS.
Each gate writes report.md and report.json under $BIFROST_STATE_DIR/<cluster>/, in a directory named after the gate (for example validate-pre/ or validate-post/). The canary writes a self-contained HTML report next to them. Plan validation and Ambari parity reports are written to the inventory's extract/ directory.
Notifications are configured per cluster in inventories/<cluster>/notification_config.yml. A missing file disables notifications, and a failing channel never stops a command. Bifrost supports three channels:
channels:
slack:
webhook: "https://hooks.slack.com/services/T0000/B0000/XXXXXXXX"
channel: "#hadoop-migration"
events:
- phase_start
- phase_complete
- phase_failed
- gate_decision
- rollback_triggered
- table_migrated # Modernize / Direct only
- wave_complete # Modernize / Direct only
itsm:
type: bmc_helix # bmc_helix | servicenow | jira
api_url: "https://helix.example.internal/api/arsys/v1"
auth: jwt
events:
- migration_start
- migration_complete
- rollback_triggered
- incident_created
email:
smtp: "smtp.example.internal"
recipients: ["[email protected]"]
events:
- gate_decision
- rollback_triggered
Give the Slack webhook as a literal URL: a templated value, such as an unresolved vault reference, is treated as not configured. Omitting events subscribes a channel to every event.
--no-notify suppresses all channels for a single invocation, which is useful for dry runs and local testing. For Modernize and Direct paths, Bifrost also exposes Prometheus metrics and ships a Superset dashboard that visualizes live migration KPIs in real time. See Operations: monitoring and alerting.