Skip to main content

Prepare User Data

The Edge Installer supports using a custom configuration file in the format of a YAML file named user-data that you can use to customize the installation. You can provide the customized configuration to the Edge Installer as a user data file. For more information on how to provide the configuration to the Edge Installer, refer to Build Edge Installer ISO. Additionally, you can also provide the configuration during site deployment as site-specific configuration. This can replace, supplement, or override your installer configuration you provide to the installer ISO. For more information, refer to Apply Site User Data.

info

Review the Edge Install Configuration resource to learn more about all the supported configuration parameters you can use in the configuration user data.

You can also use the Operating System (OS) pack to apply additional customization using cloud-init stages. Both the Edge Installer configuration file and the OS pack support the usage of cloud-init stages. Refer to the Cloud-Init Stages to learn more.

User Data Samples

You may encounter the following scenarios when creating an Edge Installer configuration user data file. Use these examples as a starting point to help you create user data configurations that fit your needs.

#cloud-config
stylus:
site:
# The Palette API endpoint to use. The default value is api.spectrocloud.com.
paletteEndpoint: api.spectrocloud.com

# The edgeHostToken is an auto-registration token to register the Edge host with Palette upon bootup.
# This token can be generated by navigating to the Tenant Settings -> Registration Token.
# Specify a name and select the project id with which the Edge host should register itself.
edgeHostToken: aUAxxxxxxxxx0ChYCrO

# The Palette project ID the Edge host should pair with. This is an optional field if an edgeHostToken is used and the token was assigned to a project.
projectUid: 12345677788
# Tags which that will be assigned to the device as labels.
tags:
key1: value1
key2: value2
key3: value3

# The device's name, may also be referred to as the Edge ID or Edge host ID. If no Edge hostname is specified,
# a hostname will be generated from the device serial number. If the Edge Installer cannot identify the device serial number, then a random ID will
# be generated and used instead. In the case of hardware that does not have a serial number, we recommended specifying a
# random name, with minimal chances of being re-used by a different Edge host.
name: edge-appliance-1

# Optional
# If the Edge host requires a proxy to connect to Palette or to pull images, then specify the proxy information in this section
network:
# configures http_proxy
httpProxy: http://proxy.example.com
# configures https_proxy
httpsProxy: https://proxy.example.com
# configures no_proxy
noProxy: 10.10.128.10,10.0.0.0/8

# Optional: configures the global nameserver for the system.
nameserver: 1.1.1.1
# configure interface specific info. If omitted all interfaces will default to dhcp
interfaces:
enp0s3:
# type of network dhcp or static
type: static
# Ip address including the mask bits
ipAddress: 10.0.10.25/24
# Gateway for the static ip.
gateway: 10.0.10.1
# interface specific nameserver
nameserver: 10.10.128.8
enp0s4:
type: dhcp
caCerts:
- |
------BEGIN CERTIFICATE------
*****************************
*****************************
------END CERTIFICATE------
- |
------BEGIN CERTIFICATE------
*****************************
*****************************
------END CERTIFICATE------

# There is no password specified to the default kairos user. You must specify authorized keys or passwords to access the Edge host console.
stages:
initramfs:
- users:
kairos:
groups:
- sudo
passwd: kairos

Connected Sites - Multiple User Data Configuration

In this example, two configuration user user data files are used. The first one is used in the staging phase and is included with the Edge Installer image. Note how the first user data contains the registration information and creates a user group. A bootable USB stick applies the second user data at the physical site. The secondary user data includes network configurations specific to the edge location.

Staging - included with the Edge Installer.

#cloud-config
stylus:
site:
paletteEndpoint: api.spectrocloud.com
edgeHostToken: <yourRegistrationToken>
tags:
city: chicago
building: building-1

install:
poweroff: true

stages:
initramfs:
- users:
kairos:
groups:
- sudo
passwd: kairos

Site - supplied at the edge location through a bootable USB drive. If specified, the projectName value overrides project information specified in the edgeHostToken parameter. You can add optional tags to identify the city, building, and zip-code. If the edge site requires a proxy for an outbound connection, provide it in the network section of the site user data.

#cloud-config
stylus:
site:
projectName: edge-sites
tags:
zip-code: 95135

Connected Sites - Single User Data

This example configuration is for a connected site. In this scenario, only a single Edge Installer configuration user data is used for the entire deployment process.


#cloud-config
stylus:
site:
paletteEndpoint: api.spectrocloud.com
edgeHostToken: <yourRegistrationToken>
projectName: edge-sites
tags:
city: chicago
building: building-1
zip-code: 95135

install:
poweroff: true

stages:
initramfs:
- users:
kairos:
groups:
- sudo
passwd: kairos

Apply Proxy & Certificate Settings

This example showcases how you can include network settings in a user data configuration.

#cloud-config
stylus:
site:
paletteEndpoint: api.spectrocloud.com
edgeHostToken: <yourRegistrationToken>
projectName: edge-sites
tags:
city: chicago
building: building-1
zip-code: 95135
network:
httpProxy: http://proxy.example.com
httpsProxy: https://proxy.example.com
noProxy: 10.10.128.10,10.0.0.0/8
nameserver: 1.1.1.1
# configure interface specific info. If omitted all interfaces will default to dhcp
interfaces:
enp0s3:
# type of network dhcp or static
type: static
# Ip address including the mask bits
ipAddress: 10.0.10.25/24
# Gateway for the static ip.
gateway: 10.0.10.1
# interface specific nameserver
nameserver: 10.10.128.8
enp0s4:
type: dhcp
caCerts:
- |
------BEGIN CERTIFICATE------
*****************************
*****************************
------END CERTIFICATE------
- |
------BEGIN CERTIFICATE------
*****************************
*****************************
------END CERTIFICATE------

install:
poweroff: true

stages:
initramfs:
- users:
kairos:
groups:
- sudo
passwd: kairos

Load Content From External Registry

In this example, content is downloaded from an external registry.

#cloud-config
stylus:
registryCredentials:
domain: 10.10.254.254:8000/spectro-images
username: ubuntu
password: <yourPassword>
insecure: true
site:
debug: true
insecureSkipVerify: false
paletteEndpoint: api.console.spectrocloud.com
name: edge-appliance-1
caCerts:
- |
-----BEGIN CERTIFICATE-----

-----END CERTIFICATE-----

install:
poweroff: false

stages:
initramfs:
- users:
kairos:
groups:
- sudo
passwd: kairos

Multiple User Data Use Case

If you don't need to apply any unique configurations on the device once it arrives at the physical site, then your site deployment flow would look like the following.

The flow of an install process not requiring additional customization

Should you need to apply different configurations once the device arrives at the physical site, you can use a secondary user data to support this use case.

Use the additional user data to override configurations from the previous user data that was flashed into the device or to inject new configuration settings. Using secondary user data at the physical site is a common pattern for organizations that need to change settings after powering on the Edge host at the physical location.

To use additional user data, create a bootable device, such as a USB stick, that contains the user data in the form of an ISO image. The Edge Installer will consume the additional user data during the installation process.

The flow of an install process with an additional customization occurring at the physical site. The additional customization is using a USB stick to upload the new user data.

When creating your Edge Installer, you can embed the user data into the installer image to eliminate providing it via a USB drive.

In the staging phase, you may identify user data parameter values that apply uniformly to all your edge sites. But you may also have some edge locations that require different configurations such as site network proxy, site certs, users and groups, etc. Site-specific configurations are typically not included in the Edge installer image. For the latter scenario, you can use a secondary user data configuration. Refer to the Apply Site User Data guide to learn more about applying secondary site-specific user data.

info

For your initial testing, your user data may include global settings and site-specific properties in a single user data. As you gain more experience, you should evaluate whether secondary site-specific user data is a better design for your use case.

Next Steps

After you have finalized your Installer configuration, you can build the configuration into the Edge Installer ISO, or turn the user-data file into an ISO file to use before site deployment.