HTTP task type

The Site Controller can execute http(s) requests as part of a workflow or other types of extensions. This is done via the ExtensionTaskWebhook task type.

Warning

The HTTP request capability is required for this process to function on the site controller which is disabled by default. Follow this guide to enable it.

Creating an extension that executes an http request

  1. Create a file called http-request-extension.json with the following content:

{
    "kind": "ExtensionDefinition",
    "schemaVersion": "1.1",
    "name": "powerdns-automation",
    "label": "powerdnsautomation",
    "extensionType": "workflow",
    "vendor": "MetalSoft",
    "extensionVersion": "1.0.0",
    "description": "Manages DNS records via PowerDNS API during server lifecycle",
    "icon": "dns",
    "dependencies": {
        "controllerVersion": "string"
    },
    "inputs": [],
    "outputs": [],
    "assets": [
        {
            "label": "power-dns-configuration",
            "name": "power-dns-configuration",
            "assetType": "Bundle",
            "url": "https://repo.metalsoft.io/.extensions_ms/workflows/power_dns.zip"
        }
    ],
    "onAssetChange": [
        {
            "stage": "serverRegistered",
            "tasks": [
                {
                    "label": "testInitial",
                    "taskType": "ExtensionTaskWebhook",
                    "options": {
                        "endpoint": "www.google.com",
                        "method": "GET",
                        "requestTemplate": "{\"server_vendor\": {{ server.serverVendor }}, \"property2\": \"value2\"}\"",
                        "expectedResponseStatuses": [
                            200,
                            201
                        ],
                        "timeout": 120
                    }
                }
            ]
        }
    ]
}

  1. Create the extension make it public

metalcloud-cli -d extensions create test-http workflow "test-http" --format json --definition-source test3.json
metalcloud-cli -d extensions publish 1
metalcloud-cli -d extensions make-public 1

  1. You are now finished. Attempt a server register and watch for workflow related tasks in the registration graph.

Task object schema

{
"label": "testInitial",
"taskType": "ExtensionTaskWebhook",
"options": {
    "endpoint":"www.google.com",
    "method":"GET",
    "requestTemplate":"{\"server_vendor\": {{ server.serverVendor }}, \"property2\": \"value2\"}\""
    },
    "expectedResponseStatuses":[200,201],
    "timeout":120
}

Options

  • endpoint - The endpoint to call. Must be a valid URL.

  • method - The method to use, one of GET, POST, PATCH, DELETE

  • headers - An array of headers to send such as: headers: {"Content-type": "application/json", "header2": "value2"}

  • expectedResponseStatuses - This is an array of codes such as [200,201]

  • timeout - Timeout in seconds. Defaults to 30 seconds.

  • insecureSkipVerify - If set to true it will ignore TLS certificate authentication failures. Defaults to false.

  • requestTemplate - This is the payload of the request. It can be a Nunjucks (a subset of Jinja2) template. The available objects that can be referenced in the requestTemplate object

    • For serverInstanceRecordSet the following will be received:

        {
        "serverInstanceRecordSet": {
            "deployStatus": "ongoing",
            "deployType": "create",
            "deploymentId": 5388,
            "instanceIpv4IpRanges": [],
            "instanceIpv4Ips": [
                {
                    "cidr": "10.0.0.4/24",
                    "gateway": "10.0.0.1",
                    "ip": "10.0.0.4",
                    "logicalNetworkId": 1214,
                    "maskBits": 24,
                    "netmask": "255.255.255.0",
                    "networkAddress": "10.0.0.0",
                    "status": "allocated"
                }
            ],
            "instanceIpv6IpRanges": [],
            "instanceIpv6Ips": [],
            "logicalNetworks": [
                {
                    "interfaces": [
                        {
                            "macAddress": "8c:84:74:0e:6c:34",
                            "redundancyIndex": null,
                            "serverInterfaceId": 688,
                            "tagged": false
                        }
                    ],
                    "ipv4Subnets": [
                        {
                            "gateway": "10.0.0.1",
                            "gatewayPlacement": "default",
                            "id": 237,
                            "networkAddress": "10.0.0.0",
                            "prefixLength": 24,
                            "scope": {
                                "kind": "fabric",
                                "resourceId": 1931
                            },
                            "status": "allocated"
                        }
                    ],
                    "logicalNetworkId": 1214,
                    "logicalNetworkLabel": "alex-private-net",
                    "logicalNetworkName": "alex-private-net",
                    "vlans": [
                        {
                            "id": 314,
                            "scope": {
                                "kind": "fabric",
                                "resourceId": 1931
                            },
                            "status": "allocated",
                            "vlanId": 826
                        }
                    ]
                }
            ],
            "serverId": 204,
            "serverInstanceId": 4434,
            "serviceStatus": "ordered",
            "siteLabel": "dc-eveng-qa02"
        }
    }

    • For serverRegistered, serverDecommissioned The server object is available to the jinja2 template:

        "server": {
    "administrationState": "managed",
    "bdkDebug": 0,
    "biosInfo": {
    "vendor": "Dell Inc.",
    "version": "1.17.2"
    },
    "bmcMacAddress": "08:92:04:a4:d9:98",
    "bootLastUpdateTimestamp": "0000-00-00T00:00:00Z",
    "bootingCustomIsoInProgress": 0,
    "chassisRackId": null,
    "customInfo": null,
    "datacenterName": "sonic-qts",
    "diskCount": 4,
    "disks": [],
    "extensionInfo": null,
    "gpuCount": 0,
    "gpuInfo": [],
    "instanceCustomInfo": null,
    "interfaces": [],
    "inventoryId": null,
    "ipmiCredentialsNeedUpdate": 0,
    "ipmiVersion": "2",
    "isBasicCampusEndpoint": 0,
    "jobInfo": {
    "jobGroupId": null,
    "jobId": null
    },
    "links": [],
    "managementAddress": "172.18.33.189",
    "mgmtSnmpPasswordEncrypted": "sonic-qts_r1|aes-cbc|GsO+10B80u+bZZ9ppepYrV/tA16siQw4Arb6FYI3feJT5TQTkzXqlmbCGGuY6sAZ",
    "mgmtSnmpPort": 161,
    "model": "PowerEdge R450",
    "passwordEncrypted": "....",
    "powerStatus": "off",
    "powerStatusLastUpdateTimestamp": "2025-09-16T18:48:50Z",
    "processorCoreCount": 12,
    "processorCoreMhz": 4000,
    "processorCount": 1,
    "processorCpuMark": null,
    "processorName": "Intel(R) Xeon(R) Silver 4310 CPU @ 2.10GHz",
    "processorThreads": 24,
    "rackName": null,
    "rackPositionLowerUnit": null,
    "rackPositionUpperUnit": null,
    "ramGbytes": 32,
    "registeredTimestamp": "2025-09-16T18:48:50Z",
    "requiresManualCleaning": 0,
    "requiresReRegister": 0,
    "resourcePoolId": null,
    "revision": 16,
    "serialNumber": "6SBT0R3",
    "serverAllocationTimestamp": null,
    "serverCapacityMbps": 20000,
    "serverClass": "bigdata",
    "serverCleanupPolicyId": null,
    "serverComments": null,
    "serverCreatedTimestamp": "2025-09-16T18:13:26Z",
    "serverDhcpStatus": "deny_requests",
    "serverDiskCount": 4,
    "serverDiskWipe": 1,
    "serverId": 27,
    "serverIsProduction": 0,
    "serverMetricsMetadata": {
    "fans": [],
    "temperatures": [
        {
        "Label": "temperature.cpu.1",
        "Name": "CPU1 Temp",
        "Number": 1,
        "Oem": null,
        "PhysicalContext": "CPU",
        "Units": "Celsius",
        "UpperThresholdCritical": null,
        "UpperThresholdFatal": null
        },
        {
        "Label": "temperature.systemboard.5",
        "Name": "System Board Inlet Temp",
        "Number": 5,
        "Oem": null,
        "PhysicalContext": "SystemBoard",
        "Units": "Celsius",
        "UpperThresholdCritical": 47,
        "UpperThresholdFatal": null
        },
        {
        "Label": "temperature.systemboard.6",
        "Name": "System Board Exhaust Temp",
        "Number": 6,
        "Oem": null,
        "PhysicalContext": "SystemBoard",
        "Units": "Celsius",
        "UpperThresholdCritical": null,
        "UpperThresholdFatal": null
        }
    ]
    },
    "serverStatus": "deleting",
    "serverSupportsOobProvisioning": 1,
    "serverSupportsSol": 1,
    "serverSupportsVirtualMedia": 1,
    "serverTypeId": 9,
    "serverUUID": "44454c4c-5300-1042-8054-b6c04f305233",
    "siteId": 1,
    "storageControllers": [
    {
        "description": "Embedded AHCI 1",
        "id": 114,
        "label": "C620 Series Chipset Family SSATA Controller [AHCI mode]",
        "mode": "HBA",
        "name": "AHCI.Embedded.1-1",
        "options": {
        "controllerModesSupported": [],
        "raidTypesSupported": []
        },
        "serverId": 27
    },
    {
        "description": "Embedded AHCI 2",
        "id": 115,
        "label": "C620 Series Chipset Family SATA Controller [AHCI mode]",
        "mode": "HBA",
        "name": "AHCI.Embedded.2-1",
        "options": {
        "controllerModesSupported": [],
        "raidTypesSupported": []
        },
        "serverId": 27
    },
    {
        "description": "AHCI controller in slot 1",
        "id": 113,
        "label": "BOSS-S1",
        "mode": "RAID",
        "name": "AHCI.Slot.1-1",
        "options": {
        "controllerModesSupported": [
            "RAID"
        ],
        "raidTypesSupported": [
            "RAID1"
        ]
        },
        "serverId": 27
    },
    {
        "description": "RAID Controller in SL 3",
        "id": 112,
        "label": "PERC H745 Front",
        "mode": "RAID",
        "name": "RAID.SL.3-1",
        "options": {
        "controllerModesSupported": [
            "RAID",
            "HBA"
        ],
        "raidTypesSupported": [
            "RAID0",
            "RAID1",
            "RAID5",
            "RAID6",
            "RAID10",
            "RAID50",
            "RAID60"
        ]
        },
        "serverId": 27
    }
    ],
    "submodel": null,
    "supportsFcProvisioning": 0,
    "tags": null,
    "username": "root",
    "vendor": "Dell",
    "vendorInfo": {
    "management": "iDRAC",
    "version": "iDRAC9"
    },
    "vendorSkuId": "PowerEdge R450",
    "vncPasswordEncrypted": "rqi|aes-cbc|1so23myI+2ymfZzcacFnk1EN7Yx726lGH0/jTI5pLc/nFhAJZYPSfRiiEO0PY6ak",
    "vncPort": 5901
}

    • For switchRegistered, switchDecomissioned: The network equipment object is available:

        "networkDevice":{
        "id": "ND-001",
        "revision": 2,
        "status": "active",
        "siteId": 101,
        "identifierString": "switch-01",
        "description": "Core switch in datacenter rack 5",
        "chassisIdentifier": "CHS-12345",
        "country": "USA",
        "city": "San Francisco",
        "datacenterMeta": "DC-West",
        "datacenterRoom": "Room A",
        "datacenterRack": "Rack 5",
        "rackPositionUpperUnit": 42,
        "rackPositionLowerUnit": 37,
        "managementAddress": "192.168.1.10",
        "managementAddressPrefixLength": 24,
        "managementAddressGateway": "192.168.1.1",
        "managementPort": 22,
        "syslogEnabled": 1,
        "username": "admin",
        "managementPassword": "password",
        "managementMacAddress": "00:1A:2B:3C:4D:5E",
        "serialNumber": "SN-987654321",
        "driver": {
        "name": "sonic_enterprise"
        },
        "position": {
        "role": "leaf"
        },
        "orderIndex": 1,
        "tags": ["production", "core", "leaf"],
        "readyForInitialConfiguration": 1,
        "bootstrapReadinessCheckInProgress": 0,
        "subnetOobId": 2001,
        "subnetOobIndex": 1,
        "requiresOsInstall": true,
        "bootstrapSkipInitialConfiguration": 0,
        "bootstrapExpectedPartnerHostname": "switch-02",
        "loopbackAddressIpv4": "10.0.0.1",
        "loopbackAddressIpv6": "fe80::1",
        "asn": 65001,
        "vtepAddressIpv4": "10.1.1.1",
        "vtepAddressIpv6": "fe80::2",
        "mlagSystemMac": "00:1A:2B:3C:4D:5F",
        "mlagDomainId": 10,
        "quarantineVlan": 999,
        "variablesMaterializedForOSAssets": {
        "osVersion": "1.2.3"
        },
        "secretsMaterializedForOSAssets": {
        "apiKey": "secret-key"
        },
        "bootstrapReadinessCheckResult": {
        "status": "ready"
        },
        "isGateway": false,
        "extensionInfo": {
        "lastRun": "2025-09-17T12:00:00Z"
        },
        "links": [
        {
            "rel": "self",
            "href": "/networkdevices/ND-001"
        }
        ]
    }

    • For serverInstanceGroupCreateDNS, serverInstanceGroupUpdateDNS, serverInstanceGroupDeleteDN,serverInstanceUpdateDNS, serverInstanceDeleteDNS refer to the RecordSet object: A server DNS record set object similar to this:

    "serverInstanceGroupDNSRecordSet": {
    "zone": {
    "zoneName": "eveng-qa02.metalcloud.io",
    "soaEmail": "admin.eveng-qa02.metalcloud.io",
    "nameServers": [
        "ns1.evenq-qa02.metalcloud.io"
    ],
    "ttl": 3600,
    "isDefault": true
    },
    "infrastructureId": 3870,
    "serverInstanceGroup": {
    "label": "instance-array-3386"
    },
    "hostname": "lambda",
    "fqdn": "lambda.eveng-qa02.metalcloud.io",
    "ips": [
    {
        "status": "allocated",
        "ip": "10.20.50.36"
    }
    ]
}

    • For serverCreateDNS, serverDeleteDNS an object similar to is provided:

    "serverDNSRecordSet": {
    "zone": {
        "zoneName": "us08.metalsoft.io",
        "soaEmail": "admin.us08.metalsoft.io",
        "nameServers": ["n1.metalsoft.io"],
        "ttl": 3600,
        "isDefault": true
    },
    "serverId": 10,
    "serialNumber": "serial-number",
    "managementAddress": "192.168.100.100",
    "hostname": "server-10",
    "fqdn": "server-10.us08.metalsoft.io",
    "ip": {
        "status": "allocated",
        "ip": "192.168.100.100"
    },
    "operation": "create"
}

    • For switchCreateDNS, switchDeleteDNS the following payload is provided:

    "switchDNSRecordSet": {
    "zone": {
        "zoneName": "us08.metalsoft.io",
        "soaEmail": "admin.us08.metalsoft.io",
        "nameServers": ["n1.metalsoft.io"],
        "ttl": 3600,
        "isDefault": true
    },
    "switchId": 10,
    "managementAddress": "192.168.100.100",
    "hostname": "switch-10",
    "fqdn": "switch-10.us08.metalsoft.io",
    "ip": {
        "status": "allocated",
        "ip": "192.168.100.100"
    },
    "operation": "create"
}