Skip to main content
Version: latest

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. 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.

This article guides you through several important configuration blocks in the user-data file. However, you can use many additional parameters to further customize your installation. Review the Edge Install Configuration resource to learn more about all the supported configuration parameters you can use in the configuration user data.

tip

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.

Prerequisites​

  • Git. You can ensure git installation by issuing the git --version command.

Prepare User Data​

  1. Clone the CanvOS repository.

     git clone https://github.com/spectrocloud/CanvOS.git

    From the CanvOS directory, copy the user-data.template file and name the copy user-data. This is a template that you can use as a starting point to build your own user data file.

Configure Installation Mode​

  1. Decide whether you want to deploy an Edge host that is connected to a Palette instance. The default configuration is a connected Edge host. If you want to deploy an Edge host that is not connected to a Palette instance, you need to change the installation mode to airgap. Add the installationMode parameter to under the stylus parameter.

    #cloud-init
    stylus:
      installationMode: airgap

    Edge hosts installed in airgap mode require you to provide assets needed to provision clusters. For more information about the deployment lifecycle of airgap Edge hosts, refer to Edge Deployment Lifecycle.

  2. If you want to deploy the Edge host in airgap mode, skip this step.

    If you want to deploy the Edge host in connected mode, you need to provide the Palette endpoint, in addition to either a registration token or QR code registration configuration. For more information about Edge host registration, refer to Edge Host Registration. For example, the following configuration provides the default Palette endpoint, a registration token, an a project name.

    #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

Configure Cloud Init Stages (Optional)​

  1. Cloud-init stages allow you to configure your Edge host declaratively. For more information about cloud-init stages, refer to Cloud-init Stages.

    To configure clout-init stages for your Edge host, use the stages block. For example, the following configuration installs Amazon Systems Manager agent on your Edge host during the after-install-chroot stage.

    #cloud-init
    stages:
      after-install-chroot:
        - name: "Install SSM"
          commands:
            - snap install amazon-ssm-agent --classic

Configure Users​

  1. If you would like to have SSH access to your Edge host, you must configure Operating System (OS) users on your Edge host. You can do this using the stages.initramfs.users block. Replace USERNAME with the name of your user and replace the value of the password with your password. You can also add the user to user groups, or add SSH keys to the list of authorized keys for that user.

    #cloud-init
    stages:
     initramfs:
       - users:
           USERNAME:
             passwd: ******
             groups:
             - sudo
             ssh_authorized_keys:
             - ssh-rsa AAAAB3N…

Configure Proxy Settings (Optional)​

  1. Optionally, you can configure HTTP/HTTPS proxy settings for your Edge host. This instructs the Edge host OS as well as the Palette agent to use the proxy server for outbound communications. Use the parameters from the table below to configure proxy settings for your Edge host.

    ParameterDescription
    siteNetwork.httpProxyThe URL of the HTTP proxy endpoint.
    siteNetwork.httpsProxyThe URL of the HTTPS proxy endpoint.
    siteNetwork.noProxyThe list of IP addresses or CIDR ranges to exclude routing through the network proxy.

Configure Post-Installation Behavior (Optional)​

  1. You can use some parameters of the install block to configure what you'd like the Edge host to do after installation is complete. The default behavior for the Edge host is to stay on the "Installation Complete" screen, but you can configure it to power off or restart automatically. For example, the following configuration instructs the Edge host to power off automatically post-installation.

    #cloud-init
    install:
      poweroff: true
    warning

    If your want your Edge host to restart automatically, ensure that you remove the installation disk after the installation is complete and before the restart happens. Otherwise, the Edge host might start the installation process again.

Validate​

You can use the +validate-user-data build target of EdgeForge to validate that your user data follows the expected schema. You need to perform this action on an AMD64 (also known as x86_64) machine.

From the CanvOS directory, issue the following command to validate your user data.

sudo ./earthly.sh +validate-user-data
+validate-user-data | time=*2024-07-25T20:19:172* level=info msg="Validation successful"

Full 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

Create Bind Mounts​

Palette Edge allows you to create bind mounts from your Edge host to your cluster through the installer configuration file named user-data, which allows your cluster to use directories or files from your Edge host directly within your Kubernetes cluster. This setup is useful for scenarios where your applications are active in the cluster and need direct access to files or directories on the Edge host.

Several packs require you set up bind mounts in order to function. For example, the Portwox pack requires several folders to be mounted on Edge deployments. You can use the install.bind_mounts parameter to specify folders to be mounted. For example, the following user data mounts three folders required by Portworx from the Edge host to the cluster.

#cloud-config
stylus:
  site:
    debug: true
    insecureSkipVerify: false
    paletteEndpoint: api.console.spectrocloud.com
    name: edge-appliance-1
    caCerts:
      - |
        -----BEGIN CERTIFICATE-----

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

install:
  bind_mounts:
    - /etc/pwx
    - /var/lib/osd
    - /var/cores

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.