Enroll an AIO-SX Subcloud On-Site

Use this procedure to enroll a factory-installed subcloud locally when the System Controller has no network path to the subcloud until the vCSR is configured.

Prerequisites

  • The System Controller and the subcloud run release r13 or later.

  • Physical access to the server is available to insert the seed ISO using a USB storage device or a local BMC connection.

  • The factory installation of the subcloud completed successfully.

  • The System Controller administrator credentials are available.

  • The System Controller’s OAM SSL CA certificate is available.

  • The site-specific configuration, including OAM IP address and vCSR configuration is available.

  • The following ports are accessible from the subcloud to the System Controller OAM IP address:

    Port

    Protocol

    Purpose

    5000

    TCP

    Keystone authentication. The enrollment script authenticates to the System Controller before triggering enrollment.

    8119

    TCP

    DC Manager API. The enrollment script calls this endpoint to trigger subcloud enrollment.

    For the complete list of Distributed Cloud port requirements, see Distributed Cloud Ports Reference.

At a high level, enrollment of an AIO-SX subcloud involves the following steps:

  1. Prepare a seed ISO with the site-specific network configuration, SSL CA certificate, bootstrap values, and vCSR script. See Prepare the Seed ISO for On-Site Enrollment.

  2. Insert the seed ISO into the subcloud server using a USB device or local Redfish virtual media. See Insert the Seed ISO for On-Site Enrollment.

  3. Cloud-init detects the seed ISO, configures the network, and establishes the IPsec tunnel through the vCSR.

  4. The enrollment script authenticates to the System Controller and triggers subcloud enrollment through the DC Manager API.

  5. Enrollment completes and the subcloud reaches deploy-complete status. To monitor progress, see Verify Subcloud Enrollment Status.

Prepare the Seed ISO for On-Site Enrollment

Procedure

  1. Verify that the factory installation completed successfully.

    $ ls /var/lib/factory-install/complete

    If the file does not exist, do not proceed. The seed ISO processing depends on this file to start the cloud-init-seed.service.

  2. Obtain the seed configuration template.

    Download and extract nocloud-factory-install.tar that contains seed ISO contents.

    Note

    For a full description of the directory structure and the scripts executed for each operation mode, see Seed ISO Directory Structure.

  3. Set the mode to on-site enrollment.

    Edit user-data and set the MODE variable to onsite-enrollment:

    runcmd:
  - |
    # MODE options: factory-install, onsite-enrollment, onsite-factory-restore, onsite-restore
    MODE=onsite-enrollment

  4. Update the instance ID.

    In meta-data, change the instance-id to a unique value different from the one used during factory install:

    instance-id: iid-onsite-enroll-01

    Note

    Cloud-init applies user-data once per instance-id. A new ID is required to trigger cloud-init processing.

  5. Configure the network.

    Edit network-config with the site’s OAM IP, VLAN, interface, and gateway information so that the subcloud can reach the System Controller after enrollment.

  6. Add the SSL CA certificate.

    Place the System Controller’s OAM SSL CA certificate file into the config/ directory.

  7. Prepare bootstrap and install values.

    Create config/bootstrap-values.yaml with:

    • ssl_ca_cert: filename of the CA cert from the previous step

    • Site-specific bootstrap parameters (same as standard enrollment)

    Place install values and deployment configurations in config/.

  8. Add the vCSR configuration script (if applicable).

    Replace cloud-init-config/scripts/20-vcsr-config with the actual vCSR configuration script and data files for the site.

  9. Generate the seed ISO.

    $ genisoimage -o seed.iso -volid 'CIDATA' \
    -untranslated-filenames -joliet -rock -iso-level 2 \
    nocloud-factory-install/

Seed ISO Directory Structure

The seed ISO for on-site operations extends the base nocloud-factory-install structure with new directories for each on-site operation:

nocloud-factory-install/
├── meta-data
├── user-data
├── network-config
├── nocloud_utils/                           # Shared utility scripts
├── config/
│   ├── bootstrap-values.yaml                # Enrollment/restore parameters
│   ├── install-values.yaml                  # BMC and OAM values
│   ├── deployment-config.yaml               # Deployment configuration
│   ├── restore-values.yaml                  # Restore parameters (restore only)
│   └── <ssl-ca-cert-file>                   # SC OAM SSL CA certificate
├── cloud-init-config/
│   └── scripts/
│       ├── 10-platform-reconfig             # Network reconfiguration
│       └── 20-vcsr-config                   # vCSR setup (site-specific)
├── onsite-enrollment/                   ◄── Used by on-site enrollment
│   └── scripts/
│       └── 90-enroll-subcloud               # Authenticates to SC, triggers enrollment
├── onsite-restore/                      ◄── Used by on-site restore (Scenarios 1 & 2)
│   └── scripts/
│       ├── 90-send-onsite-restore-request   # Send restore request to SC
│       └── 95-trigger-onsite-local-restore  # Triggers local restore
├── onsite-factory-restore/              ◄── Used by factory restore (Scenario 3)
│   └── scripts/
│       └── 10-trigger-reinstall             # Triggers reinstall from prestaged data
├── factory-install/                         # Original factory install services
│   ├── scripts/
│   ├── setup/
│   ├── systemd/
│   └── tests/
└── seed-config/
    ├── 99-seediso.rules                     # Udev rule for seed ISO detection
    ├── cloud-init-seed.service              # Systemd service triggered by udev
    ├── cloud.cfg
    └── run-cloud-init-from-seed.sh          # Main seed processing script

The user-data MODE variable selects which scripts are executed:

MODE value

Scripts executed

factory-install

Original factory install (uses factory-install/)

onsite-enrollment

cloud-init-config/scripts/ then onsite-enrollment/scripts/

onsite-restore

cloud-init-config/scripts/ then onsite-restore/scripts/

onsite-factory-restore

onsite-factory-restore/scripts/

Insert the Seed ISO for On-Site Enrollment

You must insert the seed ISO locally using one of the following methods.

Use a USB Storage Device

  1. Write the seed ISO to a USB storage device.

  2. Plug the USB device into the server.

  3. Power on the server if it is not already running. The system boots from the installed software and uses the seed ISO on the USB device as a data source.

    If the server is already running, wait until the system is stable and no active alarms are present before inserting the USB device. Cloud-init automatically detects the seed ISO and starts processing it.

Use Local Redfish Virtual Media

Use this method when you have local access to the BMC through Redfish, for example from a laptop connected to the BMC management port.

  1. Place the seed ISO in a location accessible by the BMC, such as a local HTTP server or a temporary HTTP server running on a laptop.

  2. Insert the seed ISO using the rvmc_install.py script, which is provided with the StarlingX system and uses the Redfish API to mount the ISO as virtual media on the server:

    $ sudo rvmc_install.py --config_file rvmc-config.yaml \
    --subcloud_name <name> --debug 1 \
    --excluded_operations "set_boot_override,poweroff_host"

    Example rvmc-config.yaml file:

    bmc_address: <bmc_ip>
bmc_username: <username>
bmc_password: <base64_encoded_password>
image: http://<server_ip>:<port>/seed.iso

  3. Power on the server if it is not already running. The seed ISO is used as a data source.

    If the server is already running, cloud-init automatically detects the virtual media and starts processing it.

Note

The boot order does not need to be changed. The server continues to boot from the installed software.

Results

After cloud-init detects the seed ISO, it automatically performs the following actions:

  1. The network configuration is applied, including the OAM IP address.

  2. The vCSR configuration script runs, establishing the IPsec tunnel.

  3. The enrollment script authenticates to the System Controller’s Keystone.

  4. The enrollment script invokes dcmanager subcloud add --enroll with the on_site=true option.

  5. The System Controller continues the enrollment process, skipping the enroll-init phase because the local setup was already completed on the subcloud.

  6. Enrollment completes and the subcloud reaches the deploy-complete status.

Note

The subcloud is not managed automatically after enrollment or restore. To manage the subcloud, run the following command from the System Controller:

~(keystone_admin)]$ dcmanager subcloud manage <subcloud-name>

Verify Subcloud Enrollment Status

To monitor enrollment progress from the subcloud:

$ tail -f /var/log/cloud-init.log

To view the enrollment status from the System Controller:

~(keystone_admin)]$ dcmanager subcloud show <subcloud-name>

Related Information