Skip to main content

Operator Inputs: Environment File and OEM SBE

Runbook Azure Preview

DOCUMENT CATEGORY: Runbook SCOPE: Operator inputs for the azurelocal-ztp zero-touch automation PURPOSE: Fill in the environment file and download the OEM SBE MASTER REFERENCE: azurelocal-ztp repository

Status: Active

Overview​

The operator supplies two inputs. Everything else is automated, with a gate at each step.

  1. The environment file, a YAML file that describes the machines, the network, the Azure target and the ZTP settings.
  2. The OEM SBE folder, the Solution Builder Extension files that you download from the hardware vendor.

Invoke-ZtpEnvironment.ps1 validates the environment file, then generates the JSON inputs that the stage scripts need. Those generated files are specific to your environment. Don't copy them between environments or commit them.

The environment file​

The file is passed with -InfrastructureFile. The scripts read the keys below. The tables list only the keys the ZTP scripts use. Your environment file can carry more keys for other tools.

Validation before anything runs

If a tools\Validate-Infrastructure.ps1 script sits next to the environment file's folder, Invoke-ZtpEnvironment.ps1 runs it first and stops if it fails. If the script is absent, the run warns that the file wasn't checked. Check the file yourself in that case.

Example​

All values are placeholders. Addresses use the documentation ranges from RFC 5737.

infrastructure.yml (excerpt)
azure_identity:
  azure_tenant_id: "<tenant-id>"

azure_resources:
  location: eastus

site:
  name: "<site display name>"

hardware:
  vendor: Dell
  model: AX-760

cluster_nodes:
  - name: node-01
    service_tag: "<service-tag-1>"
    idrac_ip: 192.0.2.11
    ip_address: 192.0.2.21
    mac_address: "AA:BB:CC:DD:EE:01"
  - name: node-02
    service_tag: "<service-tag-2>"
    idrac_ip: 192.0.2.12
    ip_address: 192.0.2.22
    mac_address: "AA:BB:CC:DD:EE:02"

network_intents:
  management:
    subnet: 192.0.2.0/24
    gateway: 192.0.2.1
    dns_servers:
      - 192.0.2.53

onprem:
  ntp_servers:
    - 192.0.2.123

credentials:
  local_admin_username: "<deployment-admin-user>"
  local_admin_password_secret: "keyvault://<vault-name>/<secret-name>"

ztp:
  subscription_id: "<subscription-id>"
  resource_group: "<resource-group>"
  site_name: "<site-name>"
  time_zone: UTC
  provisioning_iso: latest
  os_version: "<solution-version-or-latest>"
  share_host_adapter: "<adapter-name-the-BMCs-reach>"
  share_name: ztp-virtual-usb
  azl_rp_object_id: "<azure-local-resource-provider-object-id>"
  tags:
    purpose: ztp
  admin_secret:
    subscription_id: "<vault-subscription-id>"
    vault: "<vault-name>"
    resource_group: "<vault-resource-group>"
    username: "<provisioning-admin-user>"
    name: "<secret-name>"
  bmc_secret:
    vault: "<vault-name>"
    username_name: "<secret-name-for-bmc-user>"
    password_name: "<secret-name-for-bmc-password>"
  node_preparation:
    sbe_bundle: 'D:\sbe\<oem>'

Machines and network​

KeyWhat it is
cluster_nodes[].nameThe node name. Also the name of its provisioned machine in Azure.
cluster_nodes[].service_tagThe machine serial or service tag. It must match the serial in the voucher.
cluster_nodes[].idrac_ipThe BMC address.
cluster_nodes[].ip_addressThe static management address that the Prepare stage sets.
cluster_nodes[].mac_addressThe MAC of the management adapter. The Prepare stage puts the static address on the adapter with this MAC and fails if no adapter has it.
network_intents.management.subnetManagement subnet in CIDR form. The prefix length is read from it.
network_intents.management.gatewayThe one default gateway.
network_intents.management.dns_serversDNS servers set on the node.
onprem.ntp_serversTime servers set on the node.
hardware.vendorThe OEM, such as Dell. It selects the OEM definition for SBE discovery and BMC log signals.
hardware.modelThe model, such as AX-760. The SBE selection uses it with the dash removed.

Azure target and identity​

KeyWhat it is
azure_identity.azure_tenant_idTenant for sign-in and for the Azure context.
azure_resources.locationRegion. The preview supports East US only.
site.nameDisplay name of the site.
ztp.subscription_idSubscription of the site and the machines.
ztp.resource_groupResource group of the site and the machines. The run creates it if it doesn't exist.
ztp.site_nameName of the Azure Local site resource.
ztp.time_zoneSite time zone.
ztp.tagsTags for the resource group and for the resources the deployment creates.
ztp.azl_rp_object_idObject ID of the Azure Local resource provider in your tenant. If you leave it out, the script looks it up, which needs directory read rights that a managed identity doesn't have by default.

ZTP settings​

KeyWhat it is
ztp.provisioning_isoWhich maintenance ISO to resolve: latest, a train such as 2610, a build, or a Microsoft download URL.
ztp.os_versionThe Azure Local OS solution version to install: latest, latest-preview, or a validated solution recipe version. It also checks the SBE for compatibility.
ztp.share_host or ztp.share_host_adapterThe address of the management host as the BMCs reach it. Use share_host_adapter to name the network adapter and let the script read its IPv4 address, or share_host to give the address. One of them is required.
ztp.share_nameName of the SMB share for the images.
ztp.node_preparation.sbe_bundleThe OEM SBE folder. See below.

Secrets​

The environment file holds names and references only, never values.

KeyWhat it points to
ztp.admin_secret.*The Key Vault secret that holds the provisioning administrator password, and that administrator's user name. Provisioning sets this account on the installed OS, and the Prepare stage signs in to each node with it. The secret must exist before the run.
ztp.bmc_secret.*The vault and the names of the secrets that hold the BMC user name and the BMC password.
credentials.local_admin_password_secretThe deployment administrator's password, as keyvault://<vault>/<secret>.
Never commit secret values

Don't put a password, token or key in the environment file or in any file you commit. The run reads the values from Key Vault at run time.

The OEM SBE folder​

A Solution Builder Extension (SBE) is the hardware vendor's package for an Azure Local release. The automation needs it because the OEM requires its network drivers to be on the machine before Validate and Deploy. For Dell, the SBE can't install drivers or firmware during deployment. The Prepare stage installs the drivers.

What to download​

Download these from the OEM into one folder. Dell requires a support account for the download.

FilePurpose
SBE_<...>.zipThe SBE package. The folder must hold exactly one SBE_*.zip.
SBE_<...>.xmlThe package's metadata. It has the same name as the zip, with .xml.
SBE_Discovery_<oem>.xmlThe OEM's SBE discovery manifest.

Set the path​

Set ztp.node_preparation.sbe_bundle to the folder.

What the automation does with it​

  • Resolve stages the package you supplied. The package pins the SBE version. The automation checks its SHA-256 against the OEM's published manifest and checks it against the OS build in ztp.os_version.
  • Prepare verifies the zip again, unpacks the network driver folders once, chooses the drivers for each adapter by PCI hardware ID, checks their catalog signatures, and copies the three files to C:\SBE on each node.

The hash check in Resolve runs at the start, so a package that doesn't match the OEM manifest stops the run before it touches a machine. The Prepare stage is the one that needs all three files, and it runs last, after the OS is installed. Check that the folder holds all three before you start, so a missing file doesn't stop the run late.

Validation​

  • The environment file passes the validator, or you have checked it by hand
  • Every machine has name, service_tag, idrac_ip, ip_address and mac_address
  • ztp.share_host or ztp.share_host_adapter is set to the address the BMCs reach
  • The secrets named in the file exist in Key Vault, and the file holds no secret values
  • The SBE folder holds the zip, its XML and the discovery XML, and ztp.node_preparation.sbe_bundle points to it
← Prerequisites↑ Simplified ProvisioningRun from a management host →

References​

VersionDateAuthorChanges
1.02026-11-05Azure Local CloudInitial release