hcidude's blog

When managing VMware Cloud Foundation (VCF) environments, administrators often face challenges in bringing existing infrastructure (brownfield) into the fold of a structured and automated VCF deployment. The VCF Brownfield Tool is designed to simplify this process, making it easier to onboard existing workloads, networks, and clusters into a VCF-managed state.

⚠️ Note: This guide is based on the VCF Brownfield Import Tool v5.2.1.1 which is production-ready. Version 9.0 is available but not yet recommended for production use.

What is the VCF Brownfield Tool?

The Brownfield Tool provides a framework for importing existing vSphere clusters into a VMware Cloud Foundation environment. This enables organizations to transition from non-VCF-managed infrastructure to a fully integrated SDDC without having to rebuild from scratch. It supports scenarios where workloads already exist, helping to reduce downtime and migration overhead.

Key Benefits

• Simplified Integration: Import existing vSphere clusters into VCF without redeployment.
• Consistency: Enforce VCF standards across newly imported infrastructure.
• Flexibility: Migrate at your own pace, aligning business requirements with infrastructure modernization.
• Reduced Risk: Keep existing workloads running while transitioning to VCF.

How it Works

The Brownfield Tool analyzes your current vSphere environment, validates compatibility, and then imports the cluster into VCF management via SDDC Manager. During this process, it checks for prerequisites such as vSphere versions, networking configurations, and storage compliance.

Important Caveat

There is a known issue administrators should be aware of: SDDC Manager automatically adds its own FQDN to /etc/hosts, pointing to 127.0.0.1. This can cause problems with the import tool, since the certificate check will fail — 127.0.0.1 is not part of the certificate’s Subject Alternative Names (SANs). To avoid this, ensure that the FQDN resolves correctly to the management IP via DNS rather than relying on the localhost entry.

Automating the Conversion Procedure

You can automate the conversion process using the following command:

cd vcf-import-package/vcf-brownfield-import-*/vcf-brownfield-toolset/ && python3 vcf_brownfield.py convert \
  --vcenter '$VCENTER-FQDN$' \
  --sso-user '$SSO-USERNAME$' \
  --sso-password '$PASSWORD$' \
  --vcenter-root-password '$PASSWORD$' \
  --local-admin-password '$PASSWORD$' \
  --backup-password '$PASSWORD$' \
  --accept-trust \
  --suppress-warnings \
  --domain-name '$VCF-DOMAIN-NAME$' \
  --nsx-deployment-spec-path '/nfs/vmware/vcf/nfs-mount/bundle/nsx.json' \
  --auto-proceed

Breakdown of Flags

Flag	Description
--vcenter	Specifies the FQDN of the vCenter Server being onboarded.
--sso-user	The SSO administrator username (usually administrator@vsphere.local).
--sso-password	Password for the SSO user.
--vcenter-root-password	Root password of the vCenter appliance.
--local-admin-password	Local admin password for the SDDC Manager integration.
--backup-password	Password used for backups during the process.
--accept-trust	Automatically accepts SSL/TLS certificates without prompting.
--suppress-warnings	Suppresses non-critical warnings during execution.
--domain-name	Specifies the VCF workload domain name.
--nsx-deployment-spec-path	Path to the JSON file that defines NSX deployment specs.
--auto-proceed	Runs the process end-to-end without requiring interactive confirmation.

Datastore Selection Limitation

Currently, the automation process does not provide a flag to preselect a datastore for NSX deployment. This leads to two scenarios:

• Single datastore: The Brownfield Tool will proceed automatically without asking questions.
• Multiple datastores: You will be prompted interactively to select one, for example:

Please select a primary datastore for cluster CLUSTER:
1) DATASTORE1
2) DATASTORE2
3) DATASTORE3
Choose a number:

This means that in fully automated scripts, the process can still pause if multiple datastores are available.

Best Practices

• Validate DNS resolution and ensure SDDC Manager’s FQDN resolves to the correct IP address.
• Remove or adjust the /etc/hosts entry if necessary.
• Run the precheck validations thoroughly before attempting import.
• Document existing workload dependencies to avoid disruption during transition.

Conclusion

The VCF Brownfield Tool bridges the gap between traditional vSphere deployments and modern, automated VCF-based environments. By enabling organizations to onboard existing infrastructure into VCF, it reduces friction and accelerates the journey to a fully integrated Software-Defined Data Center. Just be mindful of nuances such as certificate validation issues caused by /etc/hosts configurations, and limitations around datastore selection when automating imports.