Lightweight Worker Node Azure Deployment Troubleshooting

Overview

Troubleshoot failures when deploying a lightweight worker node in Azure from the OneTrust platform.

The deployment uses the main.bicep template, which is compiled to ARM for OneTrust platform deployment, and typically takes 20–30 minutes. It creates a VNet, a subnet, a NAT gateway, and a public IP address if a new VNet is created, an NSG, a network interface, a VM, and a CustomScript extension.

Prerequisites and IAM permissions

Required Azure permissions

You need one of the following options:

Option A – Built-in role (simplest)

Assign the Contributor role at the subscription or resource group scope. This role includes all the resource provider permissions required by the template.

Role

Scope

Covers

Contributor

Subscription or resource group

All resource types, including everything listed in the custom role.

Option B – Custom role (least privilege)

If you cannot use Contributor, create a custom role with the following resource provider permissions at the resource group scope.

Permission

Used for

Microsoft.Resources/deployments/*

ARM deployment operations

Microsoft.Network/*

VNet, subnet, NSG, network interface, NAT gateway, public IP, and security rules.

Microsoft.Compute/*

VM, managed disk, and CustomScript extension.
Note:

Do not assign both the Contributor and the custom role. Choose one. The Contributor role already includes all the resource provider permissions listed for the custom role.

Where to check permissions

Go to Azure Portal > Subscriptions > select the subscription > Access control (IAM) > View my access.

Verify that you have at least the Contributor role at the subscription or resource group level. If you use a custom role, verify the specific permissions listed above.

Azure subscription quotas

Resource

Default limit

Where to check

VMs per region

20000

Azure Portal > Subscriptions > Usage + quotas

vCPUs per region (D-series)

10–100 (varies)

Public IPs (Standard)

15

NAT gateways

16

NSGs

5000

VNet peering per VNet

500

ARM template parameters explained

Basic parameters (always shown)

Parameter

Default

Description

adminUsername

onetrust

Admin username for SSH access to the VM.

authenticationType

sshPublicKey

sshPublicKey or password.

adminPasswordOrKey

(user-provided)

SSH public key or password, depending on the authentication type.

onetrustToken

(auto-populated)

Base64-encoded OneTrust configuration data. Do not edit.

Advanced parameters (shown when Advanced Options = Yes)

Parameter

Default

Description

When to change

vmOperatingSystem

Ubuntu-2404

Operating system for the VM. Options: Ubuntu-2204, Ubuntu-2404, RHEL 8, and RHEL 9. These are the only tested and supported operating system versions. Other Linux distributions may work, but are untested and unsupported.

Select the required operating system.

vmSize

Standard_D16ads_v5

Azure VM size. Also available: Standard_D8ads_v5.

Use Standard_D8ads_v5 for testing and Standard_D16ads_v5 for production.

useExistingVnet

No

Use an existing VNet or create a new one.

Set to Yes for bring-your-own VNet deployments.

virtualNetworkName

(blank)

Name of the existing VNet when useExistingVnet is Yes.

Provide when using an existing VNet.

subnetName

(blank)

Name of the existing subnet when useExistingVnet is Yes.

Provide when using an existing VNet.

enterProxy

No

Configure an HTTP proxy.

Set to Yes if the VM needs a proxy for outbound internet access.

proxyIp

(blank)

Proxy server IP address.

Provide when enterProxy is Yes.

proxyPort

8080

Proxy server port.

Provide when enterProxy is Yes.

enableAIGov

No

Enable AI Guard. This opens inbound port 4443.

Set to Yes if using AI Guard.

Hidden parameters (not exposed in the UI)

Parameter

Value

Notes

securityType

Standard

Hidden in the UI form. TrustedLaunch is available but not exposed.

osDiskSize

From OneTrust token

Typically 512 GB.

osDiskType

From OneTrust token

Typically Standard LRS.

Deployment scenarios

useExistingVnet

What happens

No (default)

Creates a new VNet (<vmName>-vnet), a new subnet (<vmName>-subnet), and a NAT gateway with a public IP for outbound access.

Yes

Uses the existing VNet and subnet. No NAT gateway is created. The existing subnet must have outbound internet access.

Failure catalog

Deployment validation failures

Deployment failed – resource provider not registered

Portal error:

CODE 
Subscription is not registered for resource provider 'Microsoft.Network'.
Please register the provider and retry the deployment.

Where to check: Azure Portal > Subscriptions > select the subscription > Resource providers.

Root cause: The subscription does not have the required resource providers registered. This is rare. Microsoft.Compute and Microsoft.Network are automatically registered on most subscriptions, but they can be unregistered by policy or on recently created subscriptions.

Fix:

CODE 
az provider register --namespace Microsoft.Compute
az provider register --namespace Microsoft.Network

Registration takes a few minutes. Verify the status:

CODE 
az provider show --namespace Microsoft.Network --query registrationState

When both providers show Registered, retry the deployment from the OneTrust portal.

Validation error – SSH key format invalid

Portal error:

CODE 
Invalid SSH public key format.
Provide an RSA or Ed25519 public key in OpenSSH format
(starting with 'ssh-rsa' or 'ssh-ed25519') or an RSA key in multi-line PEM format.

Where to check: Azure Portal > Custom deployment > validation banner.

Root cause: The SSH public key is not in the correct format. The template requires OpenSSH format.

Fix: Generate a proper SSH key:

CODE 
ssh-keygen -t ed25519 -f ~/.ssh/onetrust_litenode

Copy the public key content:

CODE 
cat ~/.ssh/onetrust_litenode.pub

Paste the public key into the SSH public key field in the portal. Multi-line PEM format is not supported for Ed25519 keys; it is supported only for RSA keys.

Validation error – resource group region mismatch

Portal error:

PYTHON 
The location of the resource group is different from the location of the resources.

Root cause: The resource group is in a different region from the region where you are trying to deploy. The template uses resourceGroup().location for all resources.

Fix: Create a new resource group in the desired region: Azure Portal > Resource groups > Create. Select the new resource group in the deployment form. The VM region is automatically populated from the resource group location.

VM creation failures

VM creation failed – vCPU quota exceeded

Portal error:

CODE 
Operation could not be completed as it results in exceeding approved Total Regional Cores quota.
Current usage: XX, Additional required: 16, Total Regional Quota: YY.

Where to check: Azure Portal > Subscriptions > select the subscription > Usage + quotas > filter by region.

Root cause: The subscription does not have enough vCPU quota for Standard_D16ads_v5, which requires 16 vCPUs.

Fix: Request a quota increase: Azure Portal > Subscriptions > Usage + quotas > Request increase. Alternatively, use Standard_D8ads_v5, which requires 8 vCPUs but is below the recommended minimum, or free up vCPUs by stopping or deallocating unused VMs in the region.

VM creation failed – VM size not available in region

Portal error:

CODE 
The requested VM size Standard_D16ads_v5 is not available in the current region.

Where to check: Azure Portal > Virtual machines > Sizes > filter by region.

Root cause: Not all VM sizes are available in all Azure regions.

Fix: Check the available sizes in your region:

CODE 
az vm list-skus --location <region> --size Standard_D --output table

Use an available D-series size with at least 16 vCPUs and 64 GB of RAM. If no suitable size is available, try a different region.

VM creation failed – image reference not found

Portal error:

CODE 
The platform image referenced is not available in this region.
Publisher: Canonical, Offer: ubuntu-24_04-lts, SKU: pro-server

Where to check: Azure Portal > Virtual machines > Images > check marketplace availability.

Root cause: The operating system image, such as Ubuntu Pro or RHEL, is not available in the selected region, or the image reference in the OneTrust token is outdated.

Fix: Try a different operating system version, such as Ubuntu-2204 instead of Ubuntu-2404. Try a different region where the image is available. If you use RHEL, ensure that your subscription has RHEL access enabled in Azure Marketplace.

VM creation failed – disk size exceeds limits

Portal error:

CODE 
The specified disk size 512 GB is not supported for the storage account type Standard_LRS.

Root cause: The disk type and size combination is not supported.

Fix: This should not happen with the default settings. If it does, contact OneTrust Support because the disk configuration comes from the OneTrust token.

Network resource failures

VNet creation failed – address space conflict

Portal error:

CODE 
The virtual network address space '10.0.0.0/24' conflicts with an existing virtual network.

Where to check: Azure Portal > Virtual networks > check existing VNets in the resource group or region.

Root cause: The default VNet prefix 10.0.0.0/24 conflicts with an existing VNet in the subscription.

Fix: Use an existing VNet by setting useExistingVnet to Yes and providing the VNet and subnet names, or delete the conflicting VNet if it is unused. The template does not expose the VNet CIDR as a parameter. Contact OneTrust Support if you need a custom CIDR for a new VNet.

NSG creation failed – security rule conflict

Portal error:

CODE 
Security rule validation failed.
Priority XXXX is already in use.

Root cause: There is an NSG rule priority conflict. The template uses priorities 1000 for SSH, 1010 for proxy, 1020 for HTTPS, 1030 for HTTP, and 1040 for AI Guard.

Fix: This should not happen with a new NSG. If it does, delete the existing NSG and retry the deployment.

NAT gateway creation failed – public IP unavailable

Portal error:

CODE 
Cannot create public IP address.
Subscription is not registered for Microsoft.Network namespace.

Root cause: The resource provider is not registered, or the public IP quota has been exceeded.

Fix: Register the provider:

CODE 
az provider register --namespace Microsoft.Network

Check the public IP quota: Azure Portal > Subscriptions > Usage + quotas. Alternatively, use an existing VNet with outbound connectivity so that no NAT gateway is created.

CustomScript extension failures

Extension provisioning failed – installer download timeout

Portal error:

CODE 
VM extension 'SetWorkerNode' provisioning failed.
Error: Command execution finished with
  exit code: 1.
Output: curl: (28) Connection timed out after 300 seconds.

Where to check: Azure Portal > Virtual machines > select the VM > Extensions > SetWorkerNode > detailed status. You can also SSH to the VM and run cat /home/onetrust/installer.log.

Root cause: The CustomScript extension runs curl to download installer.sh from <tenant>.onetrust.com. If the VM cannot reach the tenant URL because of a firewall, NSG, or proxy, the download times out.

Fix: Verify that NSG outbound rules allow HTTPS on port 443 to *.onetrust.com. If you use a proxy, ensure that enterProxy is set to Yes and that the proxy IP and port are correct. SSH to the VM and test connectivity:

CODE 
curl -I https://<tenant>.onetrust.com

If access is blocked, update the NSG outbound rules or configure the proxy.

Extension provisioning failed – deploy.sh error

Portal error:

CODE 
VM extension 'SetWorkerNode' provisioning failed.
Error: Command execution finished with
  exit code: N.
Output: ...

Where to check: SSH to the VM and run cat /home/onetrust/installer.log.

Root causes:

  • K3s installation failed because of a network or dependency issue.

  • Helm deployment failed because of an image pull or pod startup issue.

  • There is insufficient disk space.

  • The proxy is not configured correctly in .guided-envs.

Fix: Read installer.log for the specific error. If K3s failed, run sudo systemctl status k3s. If Helm failed, run kubectl get pods -n onetrust. See Lightweight Worker Node Troubleshooting and Administration for pod-level troubleshooting. If the issue is proxy-related, verify that /etc/profile.d/proxy.sh exists and contains the correct values.

Extension timeout – deployment exceeded 90 minutes

Portal error:

CODE 
VM extension 'SetWorkerNode' provisioning timed out.

Root cause: The CustomScript extension has a default timeout. If the installer download, K3s setup, and Helm deployment take too long because of a slow network or large images, the extension times out.

Fix: SSH to the VM and check whether installation is still running:

CODE 
ps aux | grep deploy.sh

If installation is still running, wait. The extension may time out in Azure while the installation continues. Check the OneTrust portal because the node may still become healthy even if the extension shows as failed.

If the installation truly failed, re-run it manually:

CODE 
cd /home/onetrust/onetrust-dd-installer-*/data-discovery/litenode-deployment/
./deploy.sh install skip-prompt

RHEL-specific failures

RHEL LVM resize failed

Symptom: The RHEL VM deploys, but disk space is not expanded correctly.

Where to check: SSH to the VM and run df -h. Check whether /var, /tmp, and /home are resized.

Root cause: The template includes an RHEL LVM resize script that runs before the installer. If growpart or lvextend fails, the disk partitions are not expanded.

Fix: SSH to the VM and run the resize commands manually:

CODE 
sudo pvresize /dev/sda3  # or the appropriate PV
sudo lvextend -l +100%FREE /dev/mapper/rootvg-varlv
sudo lvextend -l +100%FREE /dev/mapper/rootvg-tmplv
sudo lvextend -l +100%FREE /dev/mapper/rootvg-homelv

Re-run the installer.

AI Guard-specific failures

AI Guard inbound rule not created

Symptom: AI Guard is enabled, but port 4443 is unreachable.

Where to check: Azure Portal > Network Security Groups > find <vmName>-nsg > Inbound security rules.

Root cause: The AllowAIGuardInbound NSG rule with priority 1040 is created only when enableAIGov is set to Yes.

Fix: Verify that enableAIGov was set to Yes during deployment. If it was not, manually add an inbound rule: NSG > Inbound security rules > Add > port 4443, TCP, Allow. If the rule exists but the port is still unreachable, check that the source CIDR is correct. It defaults to sshAllowedIPs from the OneTrust token.

Post-deployment verification

Azure Portal

Go to Azure Portal > Resource groups and find the resource group. Verify that the following resources exist:

  • Virtual machine with a Running status.

  • Network security group.

  • Network interface.

  • Virtual network, if a new VNet was created.

  • NAT gateway and public IP, if a new VNet is created.

  • Under VM > Extensions, SetWorkerNode shows Provisioning succeeded.

SSH verification

CODE 
ssh -i ~/.ssh/your-key onetrust@<vm-public-ip>
CODE 
# Check K3s
sudo systemctl status k3s
CODE 
# Check pods
kubectl get pods -n onetrust
# Expected: 18 pods Running (17 without AI Guard)
CODE 
# Check installer log
cat ~/installer.log | tail -20

OneTrust portal

To check the status of the lightweight worker node, go to Data Discovery > Worker nodes. The status should transition to Healthy within 20–30 minutes. If it is still Awaiting activation after 30 minutes, SSH to the VM and check installer.log.

Cleanup and rollback

Delete a failed deployment

Go to Azure Portal > Resource groups and find the resource group. If a dedicated resource group was created, delete the resource group to delete all resources.

If an existing resource group was used, delete the individual resources:

  • Virtual machine > Delete.

  • Network interface > Delete.

  • Network security group > Delete.

  • VNet, if created > Delete.

  • NAT gateway and public IP (if created) > delete each.

  • Managed disk > Delete, if it was not automatically deleted with the VM.

OneTrust portal cleanup

To delete a lightweight worker node, see Managing Worker Node Details: To delete worker nodes.

The delete action removes the OneTrust resource but does not delete Azure cloud resources. You must manually clean up Azure resources.

Soft recovery without deleting the VM

If the VM is operating correctly but K3s or Helm is not working, SSH to the VM and uninstall K3s:

CODE 
sudo /usr/local/bin/k3s-uninstall.sh

Re-download and install the lightweight worker node:

CODE 
curl -L -o ~/installer.sh -H "Authorization: Bearer <TOKEN>" \
  "https://<tenant>.onetrust.com/api/discovery-scan-config/v1/installer-config/<WN_ID>/download"
chmod +x ~/installer.sh
echo "1111" | ~/installer.sh extract-zip
cd ~/onetrust-dd-installer-*/data-discovery/litenode-deployment/
./deploy.sh install skip-prompt

Quick reference

Symptom

Likely cause

Where to look

Validation error

SSH key format

Azure portal validation banner

Deployment failed

vCPU quota

Subscriptions > Usage + quotas

Deployment failed

Image not available in the region

VM > Images > check availability

Extension failed

Network blocking installer

SSH > installer.log

Extension timeout

Slow download

SSH > check whether deploy.sh is still running

Node in Awaiting activation status

Bootstrap failure

SSH > installer.log

VNet conflict

CIDR overlap

Azure Portal > Virtual networks

Node in Unhealthy status

NATS blocked

See Lightweight Worker Node Troubleshooting and Administration: Post-deployment troubleshooting.