1. Introduction
ZEDEDA Edge Virtualization platform allows you to optionally configure edge application instances through the cloud-init mechanism. This is applicable for Ubuntu and CentOS images, as well as application images based on these Linux distributions. The most powerful feature is that you can pass a script when you create an edge application instance using a field called user-data. This will be run during the initial boot process and is very flexible, allowing you to accomplish whatever you can script.
The most common type of script to pass in is called a cloud-config script. This is a YAML formatted file that provides simple, readable methods of setting up common configuration items by declaration. It also has the ability to run arbitrary commands for other tasks. You can refer to (https://cloudinit.readthedocs.io/en/latest/topics/examples.html) for more details.
2. Custom Configuration
You can specify the application configuration script as part of 'custom configuration' during
edge application creation. When you create an edge application instance from this edge application bundle, this custom configuration script is passed to the edge node as part of the edge application Instance configuration.
This allows instance-specific fields to be accepted by the user when they are created while allowing for the single and bulk of the configuration script—the common bits to be defined with the edge application.
You can further customize your edge application configuration script per instance but without manual intervention for each instance. You can define the common part of the configuration script as it is and pass instance-specific parameters using variables.
For example, if you want to set the hostname of your edge application instance to the name of the edge node it is running on, you can still use a single script for all your application instances but specify the hostname using a system variable and ZEDEDA will automatically replace the system variable with respective edge gateway name when it creates a configuration for the edge application instance.
ZEDEDA platform supports the following types of variables for custom configuration scripts:
Note: ZEDEDA supports cloud-init updates for purge/force updates, provided there are no edits/modifications done on the variable groups. After deploying the edge application instance:
- If the changes are made on the variable groups, the changes do not get reflected in the application instance (even after the purge/force update).
- The only way to update or make changes to cloud-init, in this case, is to delete and redeploy (with updated cloud-init) the application instance.
2.1. ZEDEDA Platform System Variables
ZEDEDA will automatically replace the system variables with values from the ZEDEDA platform. Supported variables are:
$zri.system.edge-node.id - System generated unique id for the edge node in Zedcontrol
$zri.system.edge-node.name - User defined name for the edge node in Zedcontrol
$zri.system.edge-node.arch - Hardware architecture of edge node. Values : AMD64, ARM64
$zri.system.edge-app.id - System generated unique id for the edge application instance in Zedcontrol
$zri.system.edge-app.name - User defined name for the edge application instance in Zedcontrol
$zri.system.edge-instance.ip – Edge Application Instance interface IP address in ZedControl
$zri.system.edge-instance.name – Edge Application Instance name in ZedControl
$zri.system.edge-node.serial – Edge Node serial number in ZedControl as configured during onboarding
2.2. ZEDEDA Webhook Variables
If your edge application is interacting with public IoT services like AWS, Azure, etc., you can define IoTHub or Device Provisioning common parameters as part of the webhook profile and ZEDEDA will automatically replace the variables with values from the configured webhook profile. The following are the supported variables:
$webhook.azure.dps.scope_id - Azure DPS group enrollment scope
$webhook.azure.dps.shared_key - Azure DPS group enrollment shared key
$webhook.azure.iothub.ca_cert - Azure IoTHub Intermediate certificate for transparent gateway
$webhook.azure.iothub.ca_key - Azure IoTHub Intermediate private key for transparent gateway
$webhook.azure.iothub.ca_password - Azure IoTHub Intermediate certificate password for transparent gateway
2.3. User Input Variables
Ask the user to provide values during edge application instance creation. Specify any variable name between specific delimiters
Example : ###my_user_variable### (here ### is the delimiter)
3. Custom Configuration Examples
Following are the cloud-config examples for:
3.1. AWS Greengrass Runtime
#cloud-config
# Add a user with ztest / zededaI0T credential and sudo permission
users:
- name: ztest
gecos: ZEDEDA Test User
shell: /bin/bash
sudo: ALL=(ALL) NOPASSWD:ALL
lock_passwd: False
passwd: $6$qAI9dWKMTMLUZBB$vpL6vHitSiCVTx8ZHjIkdnerwEsoiWJIffUi65cp6tC/ic1e5GlcbBo0RI90tEvvvolLaUErvIsKyVZkkeyuj1
write_files:
- path: /greengrass/certs/###greengrass_core_name###.cert.pem
permissions: '0644'
encoding: b64
content: ###cloud_cert_pem###
- path: /greengrass/certs/###greengrass_core_name###.key.pem
permissions: '0444'
encoding: b64
content: ###cloud_key_pem###
# Modify AWS Greengrass config file with greengrass core certificates
runcmd:
- sed -i.orig 's|file://certs/\[ROOT_CA_PEM_HERE\]|file:///greengrass/certs/root.ca.pem|' /greengrass/config/config.json
- sed -i.orig 's|file://certs/\[CLOUD_PEM_CRT_HERE\]|file:///greengrass/certs/###greengrass_core_name###.cert.pem|' /greengrass/config/config.json
- sed -i.orig 's|file://certs/\[CLOUD_PEM_KEY_HERE\]|file:///greengrass/certs/###greengrass_core_name###.key.pem|' /greengrass/config/config.json
- sed -i.orig 's|\[ROOT_CA_PEM_HERE\]|root.ca.pem|' /greengrass/config/config.json
- sed -i.orig 's|\[CLOUD_PEM_CRT_HERE\]|###greengrass_core_name###.cert.pem|' /greengrass/config/config.json
- sed -i.orig 's|\[CLOUD_PEM_KEY_HERE\]|###greengrass_core_name###.key.pem|' /greengrass/config/config.json
- sed -i.orig 's|\[yes\|no\]|yes|' /greengrass/config/config.json
- sed -i.orig 's|\[AWS_REGION_HERE\]|###greengrass_region###|' /greengrass/config/config.json
- sed -i.orig 's|\[HOST_PREFIX_HERE\]|###iotcore_name###|' /greengrass/config/config.json
- sed -i.orig 's|\[THING_ARN_HERE\]|arn:aws:iot:###greengrass_region###:###greengrass_account###:thing/###greengrass_core_name###|' /greengrass/config/config.json
- echo -e "Removing backup AWS Greengrass config file"; rm /greengrass/config/config.json.orig
- echo -e "Restarting AWS Greengrass service \n"; sleep 90; systemctl restart greengrass
- echo -e "Checking AWS Greengrass service status \n"; systemctl status greengrass
# - echo -e "Checking AWS Greengrass module status"; sudo iotedge list
final_message: "AWS Greengrass Core gateway is finally up, after $UPTIME seconds"
3.2. Azure IoTEdge Runtime
#cloud-config
# Add a user with ztest / zededaI0T credential and sudo permission
users:
- name: ztest
gecos: ZEDEDA Test User
shell: /bin/bash
sudo: ALL=(ALL) NOPASSWD:ALL
lock_passwd: False
passwd: $6$qAI9dWKMTMLUZBB$vpL6vHitSiCVTx8ZHjIkdnerwEsoiWJIffUi65cp6tC/ic1e5GlcbBo0RI90tEvvvolLaUErvIsKyVZkkeyuj1
write_files:
- path: /etc/iotedge/trusted_ca.cert.pem
permissions: '0644'
encoding: b64
content: $webhook.azure.iothub.ca_cert
- path: /etc/iotedge/trusted_ca.key.pem
permissions: '0644'
encoding: b64
content: $webhook.azure.iothub.ca_key
- path: /etc/iotedge/openssl_ca.cnf
permissions: '0644'
content: |
[ ca ]
default_ca = CA_default
[ CA_default ]
dir = /etc/iotedge
database = $dir/index.txt
serial = $dir/serial
policy = policy_loose
[ policy_loose ]
[ v3_intermediate_ca ]
# Extensions for a typical CA.
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer:always
basicConstraints = critical, CA:true
keyUsage = critical, digitalSignature, cRLSign, keyCertSign
# Modify Azure IoTEdge config file with DPS group enrollment settings
runcmd:
- group_key_bytes=$(echo $webhook.azure.dps.shared_key | base64 --decode | xxd -p -u -c 1000)
- symmetric_key=$(echo -n $zri.system.edge-node.name | openssl sha256 -mac HMAC -macopt hexkey:$group_key_bytes -binary | base64)
- symmetric_key_replacement="s|\"{symmetric_key}\"|\"$symmetric_key\"|"
- sed -i.orig '31,33 s/^/#/' /etc/iotedge/config.yaml
- sed -i.orig '45,52 s/^##* //' /etc/iotedge/config.yaml
- sed -i.orig '48s|"{scope_id}"|"$webhook.azure.dps.scope_id"|' /etc/iotedge/config.yaml
- sed -i.orig '51s|"{registration_id}"|"$zri.system.edge-node.name"|' /etc/iotedge/config.yaml
- sed -i.orig $symmetric_key_replacement /etc/iotedge/config.yaml
- echo -e "Installing IoTEdge gateway certificate chains"
- cd /etc/iotedge
- sudo mkdir -p newcerts
- sudo rm index.txt
- sudo touch index.txt
- sudo rm serial
- sudo bash -c 'echo 1000 > serial'
- openssl genrsa -out $zri.system.edge-node.name_ca.key.pem 4096
- chmod 444 $zri.system.edge-node.name_ca.key.pem
- openssl req -new -sha256 -key $zri.system.edge-node.name_ca.key.pem -subj "/CN=$zri.system.edge-node.name_ca" -out $zri.system.edge-node.name_ca.csr
- openssl ca -batch -config openssl_ca.cnf -extensions "v3_intermediate_ca" -days 365 -notext -md sha256 -in $zri.system.edge-node.name_ca.csr -cert trusted_ca.cert.pem -keyfile trusted_ca.key.pem -keyform PEM -passin pass:$webhook.azure.iothub.ca_password -out $zri.system.edge-node.name_ca.cert.pem -outdir newcerts
- chmod 444 $zri.system.edge-node.name_ca.cert.pem
- cat $zri.system.edge-node.name_ca.cert.pem trusted_ca.cert.pem > $zri.system.edge-node.name_ca-full-chain.cert.pem
- chmod 444 $zri.system.edge-node.name_ca-full-chain.cert.pem
- cd -
- sed -i.orig 's|# certificates:|certificates:|' /etc/iotedge/config.yaml
- sed -i.orig 's|# device_ca_cert:| device_ca_cert:|' /etc/iotedge/config.yaml
- sed -i.orig 's|"<ADD PATH TO DEVICE CA CERTIFICATE HERE>"|"/etc/iotedge/$zri.system.edge-node.name_ca-full-chain.cert.pem"|' /etc/iotedge/config.yaml
- sed -i.orig 's|# device_ca_pk:| device_ca_pk:|' /etc/iotedge/config.yaml
- sed -i.orig 's|"<ADD PATH TO DEVICE CA PRIVATE KEY HERE>"|"/etc/iotedge/$zri.system.edge-node.name_ca.key.pem"|' /etc/iotedge/config.yaml
- sed -i.orig 's|# trusted_ca_certs:| trusted_ca_certs:|' /etc/iotedge/config.yaml
- sed -i.orig 's|"<ADD PATH TO TRUSTED CA CERTIFICATES HERE>"|"/etc/iotedge/trusted_ca.cert.pem"|' /etc/iotedge/config.yaml
- echo -e "Removing backup IoTEdge config file"; rm /etc/iotedge/config.yaml.orig
- echo -e "Restarting IoTEdge service \n"; sleep 90; systemctl restart iotedge
- echo -e "Checking IoTEdge service status \n"; systemctl status iotedge
- echo -e "Checking IoTEdge module status"; sudo iotedge list
final_message: "Azure IoT Edge gateway is finally up, after $UPTIME seconds"
4. UI Screens
You can view the status and details of an edge app's custom configuration in the edge app's details page in the Configuration section.