phpIPAM Subnet Capacity Sentinel for Kestra

id: phpipam-subnet-capacity-sentinel
namespace: company.team
description: |
  On a schedule, read-only fetch a phpIPAM subnet's usage statistics
  (nothing is created, updated, or deleted) and classify its free address
  capacity as HEALTHY, WARNING, CRITICAL, or UNREACHABLE. Log clean runs
  and page Slack the moment a subnet is close to IP exhaustion.

inputs:
  - id: phpipam_base_url
    type: STRING
    defaults: "https://ipam.example.com"
    displayName: "phpIPAM Base URL"
    description: "Root URL of the phpIPAM instance, without a trailing slash."
  - id: phpipam_app_id
    type: STRING
    defaults: "kestra"
    displayName: "phpIPAM Application ID"
    description: "The API application identifier configured under Administration >
      API in phpIPAM; appears in the path /api/{appId}/."
  - id: subnet_id
    type: STRING
    defaults: "1"
    displayName: "Subnet ID"
    description: "Numeric ID of the phpIPAM subnet to check."
  - id: warning_free_percent
    type: INT
    defaults: 15
    displayName: "Warning Free Capacity Threshold (percent)"
    description: "At or below this percentage of free addresses, the subnet is
      classified WARNING."
  - id: critical_free_percent
    type: INT
    defaults: 5
    displayName: "Critical Free Capacity Threshold (percent)"
    description: "At or below this percentage of free addresses, the subnet is
      classified CRITICAL."

triggers:
  - id: subnet_capacity_schedule
    type: io.kestra.plugin.core.trigger.Schedule
    description: Check the subnet every 6 hours. Shipped disabled; enable it once
      phpipam_base_url/subnet_id point at a real phpIPAM instance and a manual
      run has been verified.
    cron: "0 */6 * * *"
    disabled: true
    inputs:
      warning_free_percent: 15
      critical_free_percent: 5

tasks:
  - id: get_subnet
    type: io.kestra.plugin.phpipam.ipam.subnet.Get
    description: Retrieve the subnet's current usage statistics by its numeric ID.
      Does not create, update, or delete anything in phpIPAM.
    baseUrl: "{{ inputs.phpipam_base_url }}"
    appId: "{{ inputs.phpipam_app_id }}"
    auth:
      appToken: "{{ secret('PHPIPAM_APP_TOKEN') }}"
    subnetId: "{{ inputs.subnet_id }}"
    allowFailure: true

  - id: get_subnet_usage
    type: io.kestra.plugin.core.http.Request
    description: Read the subnet's usage counters from the dedicated usage endpoint.
      The subnet read above returns the subnet record only, with no usage block,
      so the percentages have to come from here.
    uri: "{{ inputs.phpipam_base_url }}/api/{{ inputs.phpipam_app_id }}/subnets/{{
      inputs.subnet_id }}/usage/"
    method: GET
    headers:
      token: "{{ secret('PHPIPAM_APP_TOKEN') }}"
    options:
      allowFailed: true
    allowFailure: true

  - id: classify_subnet_capacity
    type: io.kestra.plugin.core.debug.Return
    description: Classify the subnet's free-address percentage against the two
      configured thresholds, treating a missing output as a server or subnet
      lookup failure rather than a healthy subnet.
    format: "{{ (outputs.get_subnet_usage.body is not defined or
      (outputs.get_subnet_usage.body | jq('.data.freehosts_percent // empty') |
      first) is not defined) ? 'UNREACHABLE' : ((outputs.get_subnet_usage.body |
      jq('.data.freehosts_percent | tonumber') | first) <=
      inputs.critical_free_percent ? 'CRITICAL' :
      ((outputs.get_subnet_usage.body | jq('.data.freehosts_percent | tonumber')
      | first) <= inputs.warning_free_percent ? 'WARNING' : 'HEALTHY')) }}"

  - id: route_by_capacity
    type: io.kestra.plugin.core.flow.Switch
    description: Route to a quiet log on a subnet with plenty of free capacity, an
      informational Slack message when capacity is getting low, or a Slack page
      when the subnet is nearly exhausted or unreachable.
    value: "{{ outputs.classify_subnet_capacity.value }}"
    cases:
      "HEALTHY":
        - id: log_healthy
          type: io.kestra.plugin.core.log.Log
          message: "phpIPAM subnet {{ inputs.subnet_id }} ({{
            outputs.get_subnet.subnet.subnet }}/{{
            outputs.get_subnet.subnet.mask }}) is healthy: {{
            outputs.get_subnet_usage.body | jq('.data.freehosts_percent') |
            first }}% free, above the warning floor of {{
            inputs.warning_free_percent }}%."
      "WARNING":
        - id: alert_warning_capacity
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Post an informational Slack message when free capacity drops to or
            below the warning threshold but is not yet critical.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "phpIPAM capacity sentinel WARNING: subnet {{ inputs.subnet_id }} ({{ outputs.get_subnet.subnet.subnet }}/{{ outputs.get_subnet.subnet.mask }}) has only {{ outputs.get_subnet_usage.body | jq('.data.freehosts_percent') | first }}% free addresses ({{ outputs.get_subnet_usage.body | jq('.data.freehosts') | first }} of {{ outputs.get_subnet_usage.body | jq('.data.maxhosts') | first }} total), at or below the warning floor of {{ inputs.warning_free_percent }}%. Plan additional address space before it runs out. Execution {{ execution.id }}."
            }
      "CRITICAL":
        - id: alert_critical_capacity
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Page Slack when free capacity drops to or below the critical
            threshold, meaning the subnet is close to having no addresses left
            to assign.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "phpIPAM capacity sentinel CRITICAL: subnet {{ inputs.subnet_id }} ({{ outputs.get_subnet.subnet.subnet }}/{{ outputs.get_subnet.subnet.mask }}) has only {{ outputs.get_subnet_usage.body | jq('.data.freehosts_percent') | first }}% free addresses ({{ outputs.get_subnet_usage.body | jq('.data.freehosts') | first }} of {{ outputs.get_subnet_usage.body | jq('.data.maxhosts') | first }} total) left, at or below the critical floor of {{ inputs.critical_free_percent }}%. New devices or DHCP leases may soon fail to get an address. Execution {{ execution.id }}."
            }
      "UNREACHABLE":
        - id: alert_unreachable_subnet
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Page Slack when the subnet lookup could not return usage data at
            all, indicating the phpIPAM server is unreachable, the token is
            invalid, or the subnet ID does not exist.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "phpIPAM capacity sentinel UNREACHABLE: fetching subnet {{ inputs.subnet_id }} from {{ inputs.phpipam_base_url }} did not return usage data (server unreachable, token invalid, or subnet not found). Execution {{ execution.id }}."
            }
    defaults:
      - id: log_unclassified
        type: io.kestra.plugin.core.log.Log
        message: "phpIPAM capacity sentinel completed with an unexpected classification:
          {{ outputs.classify_subnet_capacity.value }}."

  - id: log_audit_result
    type: io.kestra.plugin.core.log.Log
    description: Record a single audit line for every run regardless of branch
      taken, so the check's own history stays queryable independent of Slack.
    message: "phpIPAM capacity sentinel audit: subnet_id={{ inputs.subnet_id }}
      status={{ outputs.classify_subnet_capacity.value }} free_percent={{
      outputs.get_subnet_usage.body is defined ? (outputs.get_subnet_usage.body
      | jq('.data.freehosts_percent') | first) : 'n/a' }} free_hosts={{
      outputs.get_subnet_usage.body is defined ? (outputs.get_subnet_usage.body
      | jq('.data.freehosts') | first) : 'n/a' }} max_hosts={{
      outputs.get_subnet_usage.body is defined ? (outputs.get_subnet_usage.body
      | jq('.data.maxhosts') | first) : 'n/a' }} execution={{ execution.id }}."

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Alert Slack when the sentinel flow itself fails outright, so a
      broken check is never mistaken for a subnet with healthy capacity.
    url: "{{ secret('SLACK_WEBHOOK') }}"
    payload: |
      {
        "text": "phpIPAM capacity sentinel flow {{ flow.id }} FAILED (execution {{ execution.id }}). Free capacity on subnet {{ inputs.subnet_id }} is now unknown; check the task logs and the phpIPAM server manually."
      }

outputs:
  - id: status
    type: STRING
    value: "{{ outputs.classify_subnet_capacity.value }}"

A subnet quietly fills up one DHCP lease and one static assignment at a time, and nothing in phpIPAM pages anyone until a new device fails to get an address. This blueprint turns a scheduled, read-only subnet lookup into a Day 2 resource-quota gate: io.kestra.plugin.phpipam.ipam.subnet.Get reports the subnet's current free-address percentage without creating, updating, or deleting anything, a single Pebble expression classifies that percentage against two thresholds, and the result routes to a quiet log, an informational Slack note, or a Slack page depending on severity.

How it works

get_subnet (io.kestra.plugin.phpipam.ipam.subnet.Get) retrieves subnet_id from the phpIPAM instance at phpipam_base_url under application ID phpipam_app_id. The response includes subnet.usage, with used, maxHosts, freeHosts, freeHostsPercent, and offlinePercent as reported by phpIPAM's own calculation for that subnet. allowFailure: true keeps a server or lookup failure from aborting the flow outright.
classify_subnet_capacity (io.kestra.plugin.core.debug.Return) first guards for a missing subnet/usage output (UNREACHABLE), then converts freeHostsPercent from phpIPAM's string representation to a number with a jq tonumber filter and classifies it: at or below critical_free_percent becomes CRITICAL, at or below warning_free_percent becomes WARNING, otherwise HEALTHY.
route_by_capacity (io.kestra.plugin.core.flow.Switch) branches on that classification: HEALTHY logs a quiet confirmation; WARNING posts an informational Slack note; CRITICAL and UNREACHABLE each page Slack with the free-address count and percentage; a defaults fallback logs the raw value for any classification outside the four known cases.
log_audit_result (io.kestra.plugin.core.log.Log) writes one audit line per run, independent of which Switch branch fired, carrying the free, used, and max host counts, so the check's own history stays queryable even if Slack delivery fails.
The flow-level errors block pages Slack separately if the flow fails outright, so a broken sentinel is never mistaken for a subnet with healthy capacity.
The subnet_capacity_schedule trigger checks every 6 hours and ships disabled: true, with explicit inputs: overrides for warning_free_percent and critical_free_percent so the scheduled run's thresholds are pinned regardless of this flow's own defaults.

What you get

A scheduled, read-only capacity check for any phpIPAM subnet with zero custom phpIPAM API scripting.
A single status output (HEALTHY / WARNING / CRITICAL / UNREACHABLE) other flows can gate on.
Three distinct Slack messages, one per severity, each carrying the exact free-host count and percentage.
An audit log line on every run, separate from Slack, so the check's own history survives a webhook outage.

Who it's for

Network engineering and infrastructure teams running phpIPAM as their IP address management system of record.
Platform teams who need to know a DHCP-serviced subnet is about to run out of addresses before a new device or VM fails to provision.
Teams standardizing Day 2 resource-quota governance across infrastructure systems inside Kestra instead of a cron job that emails a spreadsheet.

Why orchestrate this with Kestra

phpIPAM shows subnet utilization in its own dashboard, but nothing pages anyone when a subnet crosses a capacity threshold unless someone is actively looking. Kestra's scheduled, read-only Get check gives that page automatically: the schedule, the threshold classification, and the Slack call are all one auditable execution history, with the Switch branch ready to grow into real remediation (requesting a supernet split, opening a ticket) without rewriting the check itself.

Prerequisites

A phpIPAM instance reachable at phpipam_base_url, with API access enabled under Administration > API for application ID phpipam_app_id.
A phpIPAM API token (static app token auth) with read access to the target subnet.
A Slack incoming webhook for the WARNING, CRITICAL, UNREACHABLE, and flow-failure alerts.

Secrets

PHPIPAM_APP_TOKEN: phpIPAM static application API token used for authentication.
SLACK_WEBHOOK: Slack incoming webhook used for every alert branch and the flow-failure alert.

In Kestra OSS (no Enterprise secrets backend), secrets are supplied as environment variables prefixed SECRET_, base64-encoded, and read back in flows with {{ secret('NAME') }}, for example SECRET_SLACK_WEBHOOK=$(echo -n 'https://hooks.slack.com/services/<placeholder>' | base64). This keeps credentials out of the flow YAML but, per Kestra's own documentation, offers no encryption at rest or access control beyond the host environment; use the Enterprise secrets backend for stronger guarantees.

Quick start

Start a local phpIPAM instance with its bundled MariaDB, mapping its web port off host 8080 since Kestra's own UI already uses it: docker run -d --name phpipam-app -p 8880:80 -e TZ=UTC -e IPAM_DATABASE_HOST=phpipam-db -e IPAM_DATABASE_PASS=phpipam phpipam/phpipam-www:latest docker run -d --name phpipam-db -e MYSQL_ROOT_PASSWORD=phpipam phpipam/phpipam-db:latest
If Kestra is also running in Docker, check docker network ls for Kestra's network and attach the app container to it: docker network connect YOUR_KESTRA_NETWORK phpipam-app Then set phpipam_base_url to http://phpipam-app. From a host-based Kestra install, use http://localhost:8880 instead.
Complete the phpIPAM web setup wizard, create a section and a small test subnet, then enable the API under Administration > API and create a static-token application to get phpipam_app_id and the app token.
Add the PHPIPAM_APP_TOKEN and SLACK_WEBHOOK secrets, set subnet_id to the test subnet's numeric ID, and run the flow once manually to confirm status reads HEALTHY.
Enable subnet_capacity_schedule once pointed at a real instance and subnet.

How to extend

Loop this flow's subnet_id input over every subnet a team owns using io.kestra.plugin.core.flow.Loop, instead of checking one subnet per execution.
Use io.kestra.plugin.phpipam.ipam.subnet.Search or List to discover all subnets under a section automatically, instead of hardcoding one subnet_id.
Chain a CRITICAL branch into a ticketing system to request a supernet split before addresses actually run out.
Push status into a KV store and alert only on state transitions instead of every run.

Inputs

phpipam_base_url: root URL of the phpIPAM instance.
phpipam_app_id: phpIPAM API application ID.
subnet_id: numeric ID of the subnet to check.
warning_free_percent: free-address percentage floor at or below which the subnet is classified WARNING.
critical_free_percent: free-address percentage floor at or below which the subnet is classified CRITICAL.

Outputs

status: one of HEALTHY, WARNING, CRITICAL, UNREACHABLE.
Example path: {{ outputs.classify_subnet_capacity.value }}, also exposed as the flow output {{ outputs.status }}.

Pitfalls

phpIPAM reports usage fields (freeHostsPercent, freeHosts, maxHosts) as JSON strings, not numbers; this flow converts freeHostsPercent with a jq tonumber filter before comparing it to the integer thresholds. Confirm the field is still present before trusting the classification, since a renamed or missing field would otherwise be silently miscompared.
subnetId must be the subnet's internal numeric phpIPAM ID, not its CIDR notation; use List or Search to look up the ID if it is not already known.
This flow only ever calls subnet.Get; it never calls Create, Update, or Delete, so there is nothing destructive to default to dry-run for.
insecureTls exists on the connection for development instances with self-signed certificates; do not enable it against a production phpIPAM instance.