pulumi-provider-devzero

The official Pulumi provider for DevZero, enabling you to manage DevZero infrastructure — Clusters, Workload Policies, and Node Policies — using your preferred programming language.

Resources

| Resource | Description | |---|---| | Cluster | Provision and manage a DevZero cluster | | WorkloadPolicy | Configure vertical/horizontal scaling policies for workloads | | WorkloadPolicyTarget | Apply a workload policy to one or more clusters with filters | | WorkloadRule | Pin explicit resource rules to a specific workload (MPA v3) | | NodePolicy | Configure node provisioning and pooling (AWS / Azure) | | NodePolicyTarget | Apply a node policy to one or more clusters |

Prerequisites

• Pulumi CLI v3+
• A DevZero account and API token
• The provider binary in bin/ (see Building from source)

Installation

TypeScript / JavaScript

npm install @devzero/pulumi-devzero

Python

pip install pulumi-devzero

Go

go get github.com/devzero-inc/pulumi-provider-devzero/sdk/go/devzero

Configuration

Set your DevZero API endpoint and credentials via Pulumi config or environment variables:

pulumi config set --secret devzero:token <YOUR_PAT_TOKEN>
pulumi config set devzero:teamId <TEAM_ID>
pulumi config set devzero:url https://dakr.devzero.io  # optional, this is the default

Quick Start

Pick your language below. Each example creates a Cluster, a WorkloadPolicy with CPU/memory vertical scaling, a WorkloadPolicyTarget, a NodePolicy, and a NodePolicyTarget.

TypeScript

Setup

mkdir my-devzero-ts && cd my-devzero-ts
pulumi new typescript
npm install @devzero/pulumi-devzero

index.ts

import * as pulumi from "@pulumi/pulumi";
import { resources } from "@devzero/pulumi-devzero";

// 1. Create a cluster
const cluster = new resources.Cluster("prod-cluster", {
    name: "prod-cluster",
});

// 2. Create a workload policy with CPU and memory vertical scaling
const policy = new resources.WorkloadPolicy("cpu-scaling-policy", {
    name: "cpu-scaling-policy",
    description: "Policy with CPU and memory vertical scaling enabled",
    actionTriggers: ["on_detection", "on_schedule"],  // apply on pod events AND on schedule
    cronSchedule: "0 2 * * *",                        // daily at 2 am UTC (required for on_schedule)
    detectionTriggers: ["pod_creation", "pod_reschedule"],
    cpuVerticalScaling: {
                enabled: true,
                targetPercentile: 0.75,        // P75 of observed usage
                minRequest: 25,                // millicores; hard floor
                maxScaleUpPercent: 1000,       // % per step
                maxScaleDownPercent: 1,        // % per step
                minDataPoints: 20,             // min CPU samples
                adjustReqEvenIfNotSet: true,   // set requests even if workload has none
                limitsRemovalEnabled: true,    // strip CPU limits (cycles compress safely)
            },
    memoryVerticalScaling: {
                enabled: true,
                targetPercentile: 1,           // P100 — guard against OOMKills
                minRequest: 134217728,         // 128 MiB in bytes; hard floor
                maxScaleUpPercent: 1000,       // % per step
                maxScaleDownPercent: 1,        // % per step
                overheadMultiplier: 0.3,       // extra headroom over the recommendation
                limitsAdjustmentEnabled: true, // adjust limits alongside requests
                limitMultiplier: 1,            // limits = request × this
                minDataPoints: 20,             // min memory samples
                adjustReqEvenIfNotSet: true,   // set requests even if workload has none
            },
            enablePmaxProtection: true,                        // guard against spike-induced OOMKills
            pmaxRatioThreshold: 3,                             // raise requests 3× on an OOM event
            minChangePercent: 0.2,                             // apply only if change > 20%
        });

// 3. Apply the workload policy to the cluster for all Deployments
const workloadTarget = new resources.WorkloadPolicyTarget("prod-cluster-deployments-target", {
    name: "prod-cluster-deployments-target",
    description: "Apply cpu-scaling-policy to all Deployments in prod-cluster",
    policyId: policy.id,
    clusterIds: [cluster.id],
    kindFilter: ["Deployment"],
    enabled: true,
});

// 4. Create a node policy for dzkarp-based node provisioning
const nodePolicy = new resources.NodePolicy("prod-node-policy", {
    name: "prod-node-policy",
    description: "Cost-efficient node provisioning for production workloads",

    // Higher weight wins when multiple policies match the same node request.
    weight: 10,

    // Instance categories: c (compute), m (general), r (memory), t (burstable).
    // Kept broad to maximise the instance pool and minimise cost.
    instanceCategories: {
        matchExpressions: [{
            operator: "In",
            values: ["c", "m", "r", "t"],
        }],
    },

    // Instance generation: prefer modern hardware (gen 3+) for better performance/cost ratio.
    instanceGenerations: {
        matchExpressions: [{
            operator: "In",
            values: ["3", "4", "5", "6"],
        }],
    },

    // CPU architecture: amd64 (x86_64) — derived from active nodes in the cluster.
    architectures: {
        matchExpressions: [{ operator: "In", values: ["amd64"] }],
    },

    // Capacity types: prefer spot for savings, fall back to on-demand for availability.
    capacityTypes: {
        matchExpressions: [{ operator: "In", values: ["spot", "on-demand"] }],
    },

    // Operating system: linux only.
    operatingSystems: {
        matchExpressions: [{ operator: "In", values: ["linux"] }],
    },

    // Disruption: how dzkarp consolidates and rotates nodes.
    disruption: {
        consolidationPolicy: "WhenEmptyOrUnderutilized", // reclaim empty and underused nodes
        consolidateAfter: "2h0m0s",                      // wait 2 h before consolidating
        expireAfter: "168h",                             // rotate nodes after 7 days
        budgets: [
            {
                // Disrupt up to 10% of nodes at once for these reasons.
                reasons: ["Empty", "Drifted", "Underutilized"],
                nodes: "10%",
            },
            {
                // Always protect at least 1 node from disruption at any time.
                nodes: "1",
            },
        ],
    },

    // Override the generated dzkarp CRD names (helps avoid collisions in shared clusters).
    nodePoolName: "prod-nodepool",   // name of the dzkarp NodePool CR
    nodeClassName: "prod-nodeclass", // name of the dzkarp NodeClass CR

    // AWS-specific EC2 configuration.
    aws: {
        // Subnets where nodes will launch — discovered via the cluster tag.
        subnetSelectorTerms: [{
            tags: { "karpenter.sh/discovery": "my-prod-cluster" },
        }],
        // Security groups for node instances — same discovery tag pattern.
        securityGroupSelectorTerms: [{
            tags: { "karpenter.sh/discovery": "my-prod-cluster" },
        }],
        // AMI: latest Amazon Linux 2023 managed alias (dzkarp keeps it up to date).
        amiSelectorTerms: [{ alias: "al2023@latest" }],
        // IAM role dzkarp uses to launch and manage nodes (must already exist in AWS).
        role: "KarpenterNodeRole-my-prod-cluster",
    },
});

// 5. Attach the node policy to the cluster
const nodePolicyTarget = new resources.NodePolicyTarget("prod-node-policy-target", {
    name: "prod-node-policy-target",
    description: "Apply prod-node-policy to prod-cluster",
    policyId: nodePolicy.id,
    clusterIds: [cluster.id],
    enabled: true,
});

export const clusterId    = cluster.id;
export const clusterToken = pulumi.secret(cluster.token);
export const policyId     = policy.id;
export const targetId     = workloadTarget.id;
export const nodePolicyId = nodePolicy.id;

Deploy

npm run build
pulumi up

Python

Setup

mkdir my-devzero-py && cd my-devzero-py
pulumi new python
pip install pulumi-devzero

__main__.py

import pulumi
from pulumi_devzero.resources import (
    Cluster, ClusterArgs,
    WorkloadPolicy, WorkloadPolicyArgs,
    WorkloadPolicyTarget, WorkloadPolicyTargetArgs,
    NodePolicy, NodePolicyArgs,
    NodePolicyTarget, NodePolicyTargetArgs,
)
from pulumi_devzero.resources.types import (
    VerticalScalingArgs,
    LabelSelectorArgs,
    MatchExpressionArgs,
    DisruptionPolicyArgs,
    DisruptionBudgetArgs,
    AWSNodeClassSpecArgs,
    AMISelectorTermArgs,
    SubnetSelectorTermArgs,
    SecurityGroupSelectorTermArgs,
)

# 1. Create a cluster
cluster = Cluster(
    "prod-cluster",
    args=ClusterArgs(name="prod-cluster"),
)

# 2. Create a workload policy with CPU and memory vertical scaling
policy = WorkloadPolicy(
    "cpu-scaling-policy",
    args=WorkloadPolicyArgs(
        name="cpu-scaling-policy",
        description="Policy with CPU and memory vertical scaling enabled",
        action_triggers=["on_detection", "on_schedule"],  # apply on pod events AND on schedule
        cron_schedule="0 2 * * *",                        # daily at 2 am UTC (required for on_schedule)
        detection_triggers=["pod_creation", "pod_reschedule"],
        cpu_vertical_scaling=VerticalScalingArgs(
            enabled=True,
            target_percentile=0.75,          # P75 of observed usage
            min_request=25,                  # millicores; hard floor
            max_scale_up_percent=1000,       # % per step
            max_scale_down_percent=1,        # % per step
            min_data_points=20,              # min CPU samples
            adjust_req_even_if_not_set=True, # set requests even if workload has none
            limits_removal_enabled=True,     # strip CPU limits (cycles compress safely)
        ),
        memory_vertical_scaling=VerticalScalingArgs(
            enabled=True,
            target_percentile=1,             # P100 — guard against OOMKills
            min_request=134217728,           # 128 MiB in bytes; hard floor
            max_scale_up_percent=1000,       # % per step
            max_scale_down_percent=1,        # % per step
            overhead_multiplier=0.3,         # extra headroom over the recommendation
            limits_adjustment_enabled=True,  # adjust limits alongside requests
            limit_multiplier=1,              # limits = request × this
            min_data_points=20,              # min memory samples
            adjust_req_even_if_not_set=True, # set requests even if workload has none
        ),
        enable_pmax_protection=True,         # guard against spike-induced OOMKills
        pmax_ratio_threshold=3,              # raise requests 3× on an OOM event
        min_change_percent=0.2,              # apply only if change > 20%
    ),
)

# 3. Apply the workload policy to the cluster for all Deployments
workload_target = WorkloadPolicyTarget(
    "prod-cluster-deployments-target",
    args=WorkloadPolicyTargetArgs(
        name="prod-cluster-deployments-target",
        policy_id=policy.id,
        cluster_ids=[cluster.id],
        kind_filter=["Deployment"],
        enabled=True,
    ),
)

# 4. Create a node policy for dzkarp-based node provisioning
node_policy = NodePolicy("prod-node-policy", args=NodePolicyArgs(
    name="prod-node-policy",
    description="Cost-efficient node provisioning for production workloads",

    # Higher weight wins when multiple policies match the same node request.
    weight=10,

    # Instance categories: c (compute), m (general), r (memory), t (burstable).
    # Kept broad to maximise the instance pool and minimise cost.
    instance_categories=LabelSelectorArgs(
        match_expressions=[MatchExpressionArgs(
            operator="In",
            values=["c", "m", "r", "t"],
        )],
    ),

    # Instance generation: prefer modern hardware (gen 3+) for better performance/cost ratio.
    instance_generations=LabelSelectorArgs(
        match_expressions=[MatchExpressionArgs(
            operator="In",
            values=["3", "4", "5", "6"],
        )],
    ),

    # CPU architecture: amd64 (x86_64) — derived from active nodes in the cluster.
    architectures=LabelSelectorArgs(
        match_expressions=[MatchExpressionArgs(operator="In", values=["amd64"])],
    ),

    # Capacity types: prefer spot for savings, fall back to on-demand for availability.
    capacity_types=LabelSelectorArgs(
        match_expressions=[MatchExpressionArgs(operator="In", values=["spot", "on-demand"])],
    ),

    # Operating system: linux only.
    operating_systems=LabelSelectorArgs(
        match_expressions=[MatchExpressionArgs(operator="In", values=["linux"])],
    ),

    # Disruption: how dzkarp consolidates and rotates nodes.
    disruption=DisruptionPolicyArgs(
        consolidation_policy="WhenEmptyOrUnderutilized", # reclaim empty and underused nodes
        consolidate_after="2h0m0s",                      # wait 2 h before consolidating
        expire_after="168h",                             # rotate nodes after 7 days
        budgets=[
            DisruptionBudgetArgs(
                # Disrupt up to 10% of nodes at once for these reasons.
                reasons=["Empty", "Drifted", "Underutilized"],
                nodes="10%",
            ),
            DisruptionBudgetArgs(nodes="1"),  # always protect at least 1 node
        ],
    ),

    # Override the generated dzkarp CRD names (helps avoid collisions in shared clusters).
    node_pool_name="prod-nodepool",   # name of the dzkarp NodePool CR
    node_class_name="prod-nodeclass", # name of the dzkarp NodeClass CR

    # AWS-specific EC2 configuration.
    aws=AWSNodeClassSpecArgs(
        # Subnets where nodes will launch — discovered via the cluster tag.
        subnet_selector_terms=[SubnetSelectorTermArgs(
            tags={"karpenter.sh/discovery": "my-prod-cluster"},
        )],
        # Security groups for node instances — same discovery tag pattern.
        security_group_selector_terms=[SecurityGroupSelectorTermArgs(
            tags={"karpenter.sh/discovery": "my-prod-cluster"},
        )],
        # AMI: latest Amazon Linux 2023 managed alias (dzkarp keeps it up to date).
        ami_selector_terms=[AMISelectorTermArgs(alias="al2023@latest")],
        # IAM role dzkarp uses to launch and manage nodes (must already exist in AWS).
        role="KarpenterNodeRole-my-prod-cluster",
    ),
))

# 5. Attach the node policy to the cluster
node_policy_target = NodePolicyTarget("prod-node-policy-target", args=NodePolicyTargetArgs(
    name="prod-node-policy-target",
    description="Apply prod-node-policy to prod-cluster",
    policy_id=node_policy.id,
    cluster_ids=[cluster.id],
    enabled=True,
))

pulumi.export("cluster_id",     cluster.id)
pulumi.export("cluster_token",  pulumi.Output.secret(cluster.token))
pulumi.export("policy_id",      policy.id)
pulumi.export("target_id",      workload_target.id)
pulumi.export("node_policy_id", node_policy.id)

Deploy

pulumi up

Go

Setup

mkdir my-devzero-go && cd my-devzero-go
pulumi new go
go get github.com/devzero-inc/pulumi-provider-devzero/sdk/go/devzero

main.go

package main

import (
    "github.com/devzero-inc/pulumi-provider-devzero/sdk/go/devzero/resources"
    "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
    pulumi.Run(func(ctx *pulumi.Context) error {
        // 1. Create a cluster
        cluster, err := resources.NewCluster(ctx, "prod-cluster", &resources.ClusterArgs{
            Name: pulumi.String("prod-cluster"),
        })
        if err != nil {
            return err
        }

        // 2. Create a workload policy with CPU and memory vertical scaling
        policy, err := resources.NewWorkloadPolicy(ctx, "cpu-scaling-policy", &resources.WorkloadPolicyArgs{
            Name:              pulumi.String("cpu-scaling-policy"),
            Description:       pulumi.StringPtr("Policy with CPU and memory vertical scaling enabled"),
            ActionTriggers:    pulumi.StringArray{pulumi.String("on_detection"), pulumi.String("on_schedule")},
            CronSchedule:      pulumi.StringPtr("0 2 * * *"), // daily at 2 am UTC (required for on_schedule)
            DetectionTriggers: pulumi.StringArray{pulumi.String("pod_creation"), pulumi.String("pod_reschedule")},
            CpuVerticalScaling: resources.VerticalScalingArgsArgs{
                Enabled:               pulumi.BoolPtr(true),
                TargetPercentile:      pulumi.Float64Ptr(0.75),  // P75 of observed usage
                MinRequest:            pulumi.IntPtr(25),         // millicores; hard floor
                MaxScaleUpPercent:     pulumi.Float64Ptr(1000),  // % per step
                MaxScaleDownPercent:   pulumi.Float64Ptr(1),     // % per step
                MinDataPoints:         pulumi.IntPtr(20),         // min CPU samples
                AdjustReqEvenIfNotSet: pulumi.BoolPtr(true),     // set requests even if workload has none
                LimitsRemovalEnabled:  pulumi.BoolPtr(true),     // strip CPU limits (cycles compress safely)
            }.ToVerticalScalingArgsPtrOutput(),
            MemoryVerticalScaling: resources.VerticalScalingArgsArgs{
                Enabled:                 pulumi.BoolPtr(true),
                TargetPercentile:        pulumi.Float64Ptr(1.0),      // P100 — guard against OOMKills
                MinRequest:              pulumi.IntPtr(134217728),     // 128 MiB in bytes; hard floor
                MaxScaleUpPercent:       pulumi.Float64Ptr(1000),     // % per step
                MaxScaleDownPercent:     pulumi.Float64Ptr(1),        // % per step
                OverheadMultiplier:      pulumi.Float64Ptr(0.3),      // extra headroom over the recommendation
                LimitsAdjustmentEnabled: pulumi.BoolPtr(true),        // adjust limits alongside requests
                LimitMultiplier:         pulumi.Float64Ptr(1),        // limits = request × this
                MinDataPoints:           pulumi.IntPtr(20),            // min memory samples
                AdjustReqEvenIfNotSet:   pulumi.BoolPtr(true),        // set requests even if workload has none
            }.ToVerticalScalingArgsPtrOutput(),
            EnablePmaxProtection: pulumi.BoolPtr(true),       // guard against spike-induced OOMKills
            PmaxRatioThreshold:   pulumi.Float64Ptr(3),       // raise requests 3× on an OOM event
            MinChangePercent:     pulumi.Float64Ptr(0.2),     // apply only if change > 20%
        })
        if err != nil {
            return err
        }

        // 3. Apply the workload policy to the cluster for all Deployments
        workloadTarget, err := resources.NewWorkloadPolicyTarget(ctx, "prod-cluster-deployments-target", &resources.WorkloadPolicyTargetArgs{
            Name:       pulumi.String("prod-cluster-deployments-target"),
            PolicyId:   policy.ID(),
            ClusterIds: pulumi.StringArray{cluster.ID()},
            KindFilter: pulumi.StringArray{pulumi.String("Deployment")},
            Enabled:    pulumi.BoolPtr(true),
        })
        if err != nil {
            return err
        }

        // 4. Create a node policy for dzkarp-based node provisioning
        nodePolicy, err := resources.NewNodePolicy(ctx, "prod-node-policy", &resources.NodePolicyArgs{
            Name:        pulumi.String("prod-node-policy"),
            Description: pulumi.StringPtr("Cost-efficient node provisioning for production workloads"),
            // Higher weight wins when multiple policies match the same node request.
            Weight: pulumi.IntPtr(10),
            // Instance categories: c (compute), m (general), r (memory), t (burstable).
            // Kept broad to maximise the instance pool and minimise cost.
            InstanceCategories: &resources.LabelSelectorArgs{
                MatchExpressions: resources.MatchExpressionArray{
                    {Operator: pulumi.String("In"),
                        Values: pulumi.StringArray{pulumi.String("c"), pulumi.String("m"), pulumi.String("r"), pulumi.String("t")}},
                },
            },
            // Instance generation: prefer modern hardware (gen 3+) for better performance/cost ratio.
            InstanceGenerations: &resources.LabelSelectorArgs{
                MatchExpressions: resources.MatchExpressionArray{
                    {Operator: pulumi.String("In"),
                        Values: pulumi.StringArray{pulumi.String("3"), pulumi.String("4"), pulumi.String("5"), pulumi.String("6")}},
                },
            },
            // CPU architecture: amd64 (x86_64) — derived from active nodes in the cluster.
            Architectures: &resources.LabelSelectorArgs{
                MatchExpressions: resources.MatchExpressionArray{
                    {Operator: pulumi.String("In"), Values: pulumi.StringArray{pulumi.String("amd64")}},
                },
            },
            // Capacity types: prefer spot for savings, fall back to on-demand for availability.
            CapacityTypes: &resources.LabelSelectorArgs{
                MatchExpressions: resources.MatchExpressionArray{
                    {Operator: pulumi.String("In"), Values: pulumi.StringArray{pulumi.String("spot"), pulumi.String("on-demand")}},
                },
            },
            // Operating system: linux only.
            OperatingSystems: &resources.LabelSelectorArgs{
                MatchExpressions: resources.MatchExpressionArray{
                    {Operator: pulumi.String("In"), Values: pulumi.StringArray{pulumi.String("linux")}},
                },
            },
            // Disruption: how dzkarp consolidates and rotates nodes.
            Disruption: &resources.DisruptionPolicyArgs{
                ConsolidationPolicy: pulumi.StringPtr("WhenEmptyOrUnderutilized"), // reclaim empty and underused nodes
                ConsolidateAfter:    pulumi.StringPtr("2h0m0s"),                   // wait 2 h before consolidating
                ExpireAfter:         pulumi.StringPtr("168h"),                     // rotate nodes after 7 days
                Budgets: resources.DisruptionBudgetArray{
                    {
                        // Disrupt up to 10% of nodes at once for these reasons.
                        Reasons: pulumi.StringArray{pulumi.String("Empty"), pulumi.String("Drifted"), pulumi.String("Underutilized")},
                        Nodes:   pulumi.StringPtr("10%"),
                    },
                    {
                        Nodes: pulumi.StringPtr("1"), // always protect at least 1 node
                    },
                },
            },
            // Override the generated dzkarp CRD names (helps avoid collisions in shared clusters).
            NodePoolName:  pulumi.StringPtr("prod-nodepool"),   // name of the dzkarp NodePool CR
            NodeClassName: pulumi.StringPtr("prod-nodeclass"),  // name of the dzkarp NodeClass CR
            // AWS-specific EC2 configuration.
            Aws: &resources.AWSNodeClassSpecArgs{
                // Subnets where nodes will launch — discovered via the cluster tag.
                SubnetSelectorTerms: resources.SubnetSelectorTermArray{
                    {Tags: pulumi.StringMap{"karpenter.sh/discovery": pulumi.String("my-prod-cluster")}},
                },
                // Security groups for node instances — same discovery tag pattern.
                SecurityGroupSelectorTerms: resources.SecurityGroupSelectorTermArray{
                    {Tags: pulumi.StringMap{"karpenter.sh/discovery": pulumi.String("my-prod-cluster")}},
                },
                // AMI: latest Amazon Linux 2023 managed alias (dzkarp keeps it up to date).
                AmiSelectorTerms: resources.AMISelectorTermArray{
                    {Alias: pulumi.StringPtr("al2023@latest")},
                },
                // IAM role dzkarp uses to launch and manage nodes (must already exist in AWS).
                Role: pulumi.StringPtr("KarpenterNodeRole-my-prod-cluster"),
            },
        })
        if err != nil {
            return err
        }

        // 5. Attach the node policy to the cluster
        _, err = resources.NewNodePolicyTarget(ctx, "prod-node-policy-target", &resources.NodePolicyTargetArgs{
            Name:        pulumi.String("prod-node-policy-target"),
            Description: pulumi.StringPtr("Apply prod-node-policy to prod-cluster"),
            PolicyId:    nodePolicy.ID(),
            ClusterIds:  pulumi.StringArray{cluster.ID()},
            Enabled:     pulumi.BoolPtr(true),
        })
        if err != nil {
            return err
        }

        ctx.Export("clusterId",    cluster.ID())
        ctx.Export("clusterToken", cluster.Token)
        ctx.Export("policyId",     policy.ID())
        ctx.Export("targetId",     workloadTarget.ID())
        ctx.Export("nodePolicyId", nodePolicy.ID())

        return nil
    })
}

Deploy

go build -o devzero-example .
pulumi up

Data Sources

getClusterIdByName

Look up an existing cluster by name and return its ID. Use this when a cluster was registered manually (not created by Pulumi) and you need its ID to attach policies, inject into values.yaml, or pass to a Kubernetes secret.

Note: If multiple clusters share the same name, the newest one (by created_at) is returned by default. Use the liveness field to prefer or require a cluster whose zxporter agent has reported a heartbeat within the last 60 minutes.

TypeScript

import { resources } from "@devzero/pulumi-devzero";

const existing = await resources.getClusterIdByName({
    name: "my-existing-cluster",
    // teamId: "my-team-id",      // optional — defaults to devzero:teamId from provider config
    // region: "us-east-1",       // optional: filter by region
    // cloudProvider: "AWS",      // optional: filter by cloud provider (AWS | GCP | AKS | OCI)
    // liveness: "PREFER_LIVE",   // optional: IGNORE | PREFER_LIVE | REQUIRE_LIVE
});

const target = new resources.WorkloadPolicyTarget("my-target", {
    name: "my-target",
    policyId: policy.id,
    clusterIds: [existing.clusterId],
    kindFilter: ["Deployment"],
    enabled: true,
});

export const existingClusterId = existing.clusterId;

Python

import pulumi
import pulumi_devzero as devzero

existing = devzero.resources.get_cluster_id_by_name(
    name="my-existing-cluster",
    # team_id="my-team-id",      # optional — defaults to devzero:teamId from provider config
    # region="us-east-1",        # optional: filter by region
    # cloud_provider="AWS",      # optional: filter by cloud provider (AWS | GCP | AKS | OCI)
    # liveness="PREFER_LIVE",    # optional: IGNORE | PREFER_LIVE | REQUIRE_LIVE
)

target = devzero.resources.WorkloadPolicyTarget("my-target",
    name="my-target",
    policy_id=policy.id,
    cluster_ids=[existing.cluster_id],
    kind_filter=["Deployment"],
    enabled=True,
)

pulumi.export("existing_cluster_id", existing.cluster_id)

Go

existing, err := resources.GetClusterIdByName(ctx, &resources.GetClusterIdByNameArgs{
    Name: "my-existing-cluster",
    // TeamId:        pulumi.StringRef("my-team-id"),    // optional — defaults to devzero:teamId from provider config
    // Region:        pulumi.StringRef("us-east-1"),     // optional: filter by region
    // CloudProvider: pulumi.StringRef("AWS"),           // optional: filter by cloud provider (AWS | GCP | AKS | OCI)
    // Liveness:      pulumi.StringRef("PREFER_LIVE"),   // optional: IGNORE | PREFER_LIVE | REQUIRE_LIVE
})
if err != nil {
    return err
}

_, err = resources.NewWorkloadPolicyTarget(ctx, "my-target", &resources.WorkloadPolicyTargetArgs{
    Name:       pulumi.String("my-target"),
    PolicyId:   policy.ID(),
    ClusterIds: pulumi.StringArray{pulumi.String(existing.ClusterId)},
    KindFilter: pulumi.StringArray{pulumi.String("Deployment")},
    Enabled:    pulumi.BoolPtr(true),
})
if err != nil {
    return err
}

ctx.Export("existingClusterId", pulumi.String(existing.ClusterId))

Inputs:

| Field | Type | Required | Description | |---|---|---|---| | name | string | yes | Cluster name to look up | | teamId | string | no | Team to search within. Defaults to devzero:teamId from provider config | | region | string | no | Filter by region name (e.g. us-east-1) | | cloudProvider | string | no | Filter by cloud provider: AWS, GCP, AKS, OCI | | liveness | string | no | Heartbeat filter: IGNORE (default), PREFER_LIVE, REQUIRE_LIVE |

Outputs:

| Field | Type | Description | |---|---|---| | clusterId | string | UUID of the matching cluster |

WorkloadPolicy — Key Fields

| Field | Type | Description | |---|---|---| | name | string | Unique policy name (per team) | | description | string | Human-readable description | | cpuVerticalScaling | VerticalScalingArgs | CPU vertical scaling configuration | | memoryVerticalScaling | VerticalScalingArgs | Memory vertical scaling configuration | | gpuVerticalScaling | VerticalScalingArgs | GPU core vertical scaling configuration (units: GPU millicores) | | gpuVramVerticalScaling | VerticalScalingArgs | GPU VRAM vertical scaling configuration (units: bytes) | | horizontalScaling | HorizontalScalingArgs | Horizontal (replica) scaling configuration | | actionTriggers | string[] | When to apply recommendations: on_detection | on_schedule. Both can be used together. | | cronSchedule | string | 5-field UTC cron expression for scheduled application. Required when actionTriggers includes on_schedule. Example: 0 2 * * * | | detectionTriggers | string[] | Events that trigger a recommendation: pod_creation | pod_update | pod_reschedule | | loopbackPeriodSeconds | int | Seconds of historical usage data to consider. Default: 86400 (24 h) | | startupPeriodSeconds | int | Seconds after workload start to exclude from usage data (avoids cold-start spikes). Example: 300 | | liveMigrationEnabled | bool | Allow live pod migration when applying recommendations without restart. Default: false | | schedulerPlugins | string[] | Kubernetes scheduler plugins to activate. Example: ["binpacking"] | | defragmentationSchedule | string | Cron expression for background node defragmentation. Example: 0 3 * * 0 | | enablePmaxProtection | bool | Raise requests to cover peak usage when max/recommendation ratio exceeds pmaxRatioThreshold. Default: false | | pmaxRatioThreshold | float | Peak-to-recommendation ratio that triggers pmax protection. Default: 3.0 | | minDataPoints | int | Global minimum data points required before a recommendation is emitted. Default: 15 | | minChangePercent | float | Global minimum relative change (0–1) required before applying a recommendation. Default: 0.2 (20%) | | stabilityCvMax | float | Maximum coefficient of variation (stddev/mean) for a workload to be considered stable enough for VPA. Example: 0.3 | | hysteresisVsTarget | float | Dead-band ratio around the HPA target to suppress VPA/HPA oscillation. Example: 0.1 | | driftDeltaPercent | float | Percentage change from baseline recommendation that triggers a VPA refresh. Example: 20.0 | | minVpaWindowDataPoints | int | Minimum data points in VPA analysis window. Default: 30 | | cooldownMinutes | int | Minutes to wait between applying recommendations. Default: 300 (5 h) |

Python uses snake_case for all fields (e.g. cpu_vertical_scaling, action_triggers, cron_schedule, detection_triggers, enable_pmax_protection, loopback_period_seconds, min_data_points, min_change_percent, cooldown_minutes). Go uses PascalCase equivalents.

VerticalScalingArgs

| Field | Type | Description | |---|---|---| | enabled | bool | Enable this scaling axis | | targetPercentile | float | Percentile of observed usage to target (e.g. 0.95) | | minRequest | int | Minimum resource request (millicores for CPU, bytes for memory) | | maxRequest | int | Maximum resource request | | maxScaleUpPercent | float | Maximum percentage to scale up in one step. Default: 1000 | | maxScaleDownPercent | float | Maximum percentage to scale down in one step. Default: 1.0 | | overheadMultiplier | float | Safety margin multiplier applied on top of the recommendation | | limitsAdjustmentEnabled | bool | Whether to also adjust resource limits alongside requests | | limitMultiplier | float | Limits = request × limitMultiplier | | minDataPoints | int | Minimum data points required before a recommendation is emitted. Default: 20 | | adjustReqEvenIfNotSet | bool | Recommend requests even when the workload has no existing requests set. Default: false | | limitsRemovalEnabled | bool | Actively remove limits from workloads (CPU axis only — memory limits removal is not supported). Takes precedence over limitsAdjustmentEnabled. Default: false |

Python: target_percentile, min_request, max_request, max_scale_up_percent, max_scale_down_percent, overhead_multiplier, limits_adjustment_enabled, limit_multiplier, min_data_points, adjust_req_even_if_not_set, limits_removal_enabled. Go uses PascalCase equivalents.

HorizontalScalingArgs

| Field | Type | Description | |---|---|---| | enabled | bool | Enable horizontal (replica) scaling | | minReplicas | int | Minimum number of replicas to maintain | | maxReplicas | int | Maximum number of replicas to scale to | | targetUtilization | float | Target utilization ratio (0–1) for the primary metric. Example: 0.8 | | primaryMetric | string | Metric driving HPA: cpu | memory | gpu | network_ingress | network_egress. Example: "memory" | | minDataPoints | int | Minimum data points before a recommendation is emitted | | maxReplicaChangePercent | float | Maximum fraction of current replicas that can change per cycle (0–1). 0.25 = at most 25% added/removed at once. Example: 0.25 |

Python: min_replicas, max_replicas, target_utilization, primary_metric, min_data_points, max_replica_change_percent. Go uses PascalCase equivalents.

WorkloadPolicyTarget — Key Fields

| Field | Type | Description | |---|---|---| | name | string | Unique target name | | policyId | string | ID of the WorkloadPolicy to apply | | clusterIds | string[] | IDs of clusters to target | | description | string | Human-readable description (optional) | | priority | int | Evaluation priority; higher value wins when targets overlap | | kindFilter | string[] | Workload kinds: Pod | Deployment | StatefulSet | DaemonSet | Job | CronJob | ReplicaSet | ReplicationController | Rollout | | workloadNames | string[] | Explicit list of workload names to include | | nodeGroupNames | string[] | Restrict matching to specific node groups by name | | namePattern | NamePatternArgs | Regex pattern to match workload names | | namespaceSelector | LabelSelectorArgs | Select namespaces by labels (matchLabels / matchExpressions) | | workloadSelector | LabelSelectorArgs | Select workloads by labels | | enabled | bool | Activate the target. Default: true |

Python: policy_id, cluster_ids, kind_filter, workload_names, node_group_names, name_pattern, namespace_selector, workload_selector. Go uses PascalCase equivalents.

NodePolicy — Key Fields

NodePolicy configures dzkarp-based node provisioning rules. Ensure dzkarp is installed on your target clusters before attaching node policies.

| Field | Type | Description | |---|---|---| | name | string | Unique policy name | | description | string | Human-readable description | | weight | int | Priority when multiple policies match (higher = preferred) | | capacityTypes | LabelSelectorArgs | Capacity types: on-demand | spot | reserved | | instanceCategories | LabelSelectorArgs | Filter by instance category letter: e.g. m, c, r (AWS) or D, E (Azure) | | instanceFamilies | LabelSelectorArgs | Filter instance families (e.g. c5, m5) | | instanceCpus | LabelSelectorArgs | Filter by vCPU count | | instanceSizes | LabelSelectorArgs | Filter instance sizes (e.g. large, xlarge) | | instanceTypes | LabelSelectorArgs | Explicit instance types (e.g. m5.xlarge) | | instanceGenerations | LabelSelectorArgs | Filter by instance generation number (e.g. 2, 3) | | instanceHypervisors | LabelSelectorArgs | Filter by hypervisor type (e.g. nitro) | | zones | LabelSelectorArgs | Availability zones to provision into | | architectures | LabelSelectorArgs | CPU architectures (e.g. amd64, arm64) | | operatingSystems | LabelSelectorArgs | OS filter (e.g. linux, windows) | | labels | map[string]string | Labels applied to provisioned nodes | | taints | TaintArgs[] | Taints applied to provisioned nodes | | disruption | DisruptionPolicyArgs | Node disruption and consolidation settings | | limits | ResourceLimitsArgs | Max total CPU/memory this policy may provision | | nodePoolName | string | Override name for the generated dzkarp NodePool CR | | nodeClassName | string | Override name for the generated dzkarp NodeClass CR | | aws | AWSNodeClassSpecArgs | AWS-specific configuration (AMI, subnets, IAM role, EBS, etc.) | | azure | AzureNodeClassSpecArgs | Azure-specific configuration (subnet, image family, disk, etc.) | | raw | RawKarpenterSpecArgs[] | Raw Karpenter NodePool/NodeClass YAML (escape hatch) |

Python uses snake_case (e.g. capacity_types, instance_categories, instance_families, instance_cpus, instance_sizes, instance_types, operating_systems, node_pool_name, node_class_name). Go uses PascalCase equivalents.

DisruptionPolicyArgs

| Field | Type | Description | |---|---|---| | consolidationPolicy | string | WhenEmpty | WhenEmptyOrUnderutilized | | consolidateAfter | string | Wait time after a node is empty before consolidating (e.g. 30s) | | expireAfter | string | Force-replace nodes after this duration (e.g. 720h) | | ttlSecondsAfterEmpty | int | Seconds before an empty node is terminated. Deprecated — prefer consolidateAfter | | terminationGracePeriodSeconds | int | Grace period before forcefully terminating a draining node | | budgets | DisruptionBudgetArgs[] | Limits on how many nodes may be disrupted at once |

DisruptionBudgetArgs

| Field | Type | Description | |---|---|---| | nodes | string | Max nodes that can be disrupted at once. Absolute (e.g. "1") or percentage (e.g. "10%") | | reasons | string[] | Disruption reasons this budget applies to: Empty, Drifted, Underutilized. Omit to apply to all. | | schedule | string | Cron expression restricting when this budget is active | | duration | string | Duration the budget is active per schedule cycle (e.g. "1h") |

AWSNodeClassSpecArgs

| Field | Type | Description | |---|---|---| | amiFamily | string | AMI family: AL2, AL2023, Bottlerocket, Windows2019, Windows2022 | | role | string | IAM role name for nodes (dzkarp creates the instance profile) | | instanceProfile | string | IAM instance profile name (alternative to role) | | subnetSelectorTerms | SubnetSelectorTermArgs[] | Subnet selectors (by tag or ID) | | securityGroupSelectorTerms | SecurityGroupSelectorTermArgs[] | Security group selectors | | capacityReservationSelectorTerms | CapacityReservationSelectorTermArgs[] | EC2 capacity reservation selectors | | amiSelectorTerms | AMISelectorTermArgs[] | AMI selectors (by alias, tag, or ID) | | blockDeviceMappings | BlockDeviceMappingArgs[] | EBS volume configuration | | instanceStorePolicy | string | NVMe instance store policy. Value: INSTANCE_STORE_POLICY_RAID0 | | tags | map[string]string | AWS tags applied to all provisioned resources | | associatePublicIpAddress | bool | Assign a public IP to nodes | | detailedMonitoring | bool | Enable CloudWatch detailed monitoring | | metadataOptions | MetadataOptionsArgs | EC2 IMDS options (IMDSv2, hop limit, etc.) | | kubelet | KubeletConfigurationArgs | Kubelet overrides (maxPods, eviction thresholds, etc.) | | userData | string | Custom launch template user data | | context | string | Additional EC2 launch template context ARN for advanced customization |

Python: ami_family, instance_profile, subnet_selector_terms, security_group_selector_terms, capacity_reservation_selector_terms, ami_selector_terms, block_device_mappings, instance_store_policy, associate_public_ip_address, detailed_monitoring, metadata_options. Go uses PascalCase equivalents.

AzureNodeClassSpecArgs

| Field | Type | Description | |---|---|---| | vnetSubnetId | string | Azure VNet subnet resource ID | | imageFamily | string | Image family: AzureLinux, Ubuntu2204, etc. | | osDiskSizeGb | int | OS disk size in GB | | fipsMode | string | Enabled | Disabled | | maxPods | int | Max pods per node | | tags | map[string]string | Azure tags on provisioned resources | | kubelet | AzureKubeletConfigurationArgs | Kubelet overrides for Azure nodes |

Python: vnet_subnet_id, image_family, os_disk_size_gb, fips_mode, max_pods. Go uses PascalCase equivalents.

RawKarpenterSpecArgs

Use this as an escape hatch when the structured fields don't cover your use case and you need full control over the Karpenter NodePool/NodeClass resources.

| Field | Type | Description | |---|---|---| | nodepoolYaml | string | Raw YAML for a complete dzkarp NodePool resource | | nodeclassYaml | string | Raw YAML for a complete dzkarp NodeClass resource |

Python: nodepool_yaml, nodeclass_yaml. Go: NodepoolYaml, NodeclassYaml.

WorkloadRule

A WorkloadRule pins explicit resource rules directly to a single workload (a specific kind/namespace/name on a cluster). Unlike WorkloadPolicy, which applies a shared policy to many workloads via a WorkloadPolicyTarget, a WorkloadRule targets one workload and lets you override CPU, memory, GPU, and HPA settings with precise values.

Set autoGenerate: true to have the engine automatically compute all rule fields from observed usage. Omit it (or set it to false) to provide your own values via cpuRule, memoryRule, hpaRule, etc.

TypeScript

import * as pulumi from "@pulumi/pulumi";
import { resources } from "@devzero/pulumi-devzero";

// Pin explicit CPU + memory rules to a single Deployment
const rule = new resources.WorkloadRule("my-app-rule", {
    clusterId: "cluster-abc123",
    namespace:  "production",
    kind:       "Deployment",
    name:       "my-api",

    cpuRule: {
        enabled:                 true,
        minRequest:              10,    // 10m CPU
        maxRequest:              4000,  // 4 cores
        targetPercentile:        0.95,
        limitsAdjustmentEnabled: true,
        limitMultiplier:         1.5,
    },
    memoryRule: {
        enabled:    true,
        minRequest: 67108864,    // 64 MiB
        maxRequest: 536870912,   // 512 MiB
    },
    emergencyResponse: {
        oomEnabled:             true,
        oomMemoryMultiplier:    1.5,
        oomMaxReactions:        3,
        oomCooldownSeconds:     60,
        cpuThrottlingEnabled:   true,
        cpuThrottlingThreshold: 0.1,
        cpuThrottlingMultiplier: 1.25,
    },
    actionTriggers: ["on_detection"],
    detectionTriggers: ["pod_creation", "pod_reschedule"],
    cooldownMinutes: 60,
});

export const ruleId = rule.id;

Auto-generate: Replace the rule body with autoGenerate: true to let the engine fill in all fields from observed usage data.

const rule = new resources.WorkloadRule("my-app-rule", {
    clusterId:    "cluster-abc123",
    namespace:    "production",
    kind:         "Deployment",
    name:         "my-api",
    autoGenerate: true,
});

Python

import pulumi
from pulumi_devzero.resources import (
    WorkloadRule, WorkloadRuleArgs,
    ResourceRuleConfigArgsArgs,
    EmergencyResponseConfigArgsArgs,
)

# Pin explicit CPU + memory rules to a single Deployment
rule = WorkloadRule(
    "my-app-rule",
    args=WorkloadRuleArgs(
        cluster_id="cluster-abc123",
        namespace="production",
        kind="Deployment",
        name="my-api",
        cpu_rule=ResourceRuleConfigArgsArgs(
            enabled=True,
            min_request=10,     # 10m CPU
            max_request=4000,   # 4 cores
            target_percentile=0.95,
            limits_adjustment_enabled=True,
            limit_multiplier=1.5,
        ),
        memory_rule=ResourceRuleConfigArgsArgs(
            enabled=True,
            min_request=67108864,    # 64 MiB
            max_request=536870912,   # 512 MiB
        ),
        emergency_response=EmergencyResponseConfigArgsArgs(
            oom_enabled=True,
            oom_memory_multiplier=1.5,
            oom_max_reactions=3,
            oom_cooldown_seconds=60,
            cpu_throttling_enabled=True,
            cpu_throttling_threshold=0.1,
            cpu_throttling_multiplier=1.25,
        ),
        action_triggers=["on_detection"],
        detection_triggers=["pod_creation", "pod_reschedule"],
        cooldown_minutes=60,
    ),
)

pulumi.export("rule_id", rule.id)

Auto-generate:

rule = WorkloadRule("my-app-rule", args=WorkloadRuleArgs(
    cluster_id="cluster-abc123", namespace="production",
    kind="Deployment", name="my-api", auto_generate=True,
))

Go

rule, err := resources.NewWorkloadRule(ctx, "my-app-rule", &resources.WorkloadRuleArgs{
    ClusterId: pulumi.String("cluster-abc123"),
    Namespace: pulumi.String("production"),
    Kind:      pulumi.String("Deployment"),
    Name:      pulumi.String("my-api"),

    CpuRule: resources.ResourceRuleConfigArgsArgs{
        Enabled:                 pulumi.BoolPtr(true),
        MinRequest:              pulumi.IntPtr(10),    // 10m CPU
        MaxRequest:              pulumi.IntPtr(4000),  // 4 cores
        TargetPercentile:        pulumi.Float64Ptr(0.95),
        LimitsAdjustmentEnabled: pulumi.BoolPtr(true),
        LimitMultiplier:         pulumi.Float64Ptr(1.5),
    }.ToResourceRuleConfigArgsPtrOutput(),
    MemoryRule: resources.ResourceRuleConfigArgsArgs{
        Enabled:    pulumi.BoolPtr(true),
        MinRequest: pulumi.IntPtr(67108864),  // 64 MiB
        MaxRequest: pulumi.IntPtr(536870912), // 512 MiB
    }.ToResourceRuleConfigArgsPtrOutput(),
    EmergencyResponse: resources.EmergencyResponseConfigArgsArgs{
        OomEnabled:              pulumi.BoolPtr(true),
        OomMemoryMultiplier:     pulumi.Float64Ptr(1.5),
        OomMaxReactions:         pulumi.IntPtr(3),
        OomCooldownSeconds:      pulumi.IntPtr(60),
        CpuThrottlingEnabled:    pulumi.BoolPtr(true),
        CpuThrottlingThreshold:  pulumi.Float64Ptr(0.1),
        CpuThrottlingMultiplier: pulumi.Float64Ptr(1.25),
    }.ToEmergencyResponseConfigArgsPtrOutput(),
    ActionTriggers:    pulumi.StringArray{pulumi.String("on_detection")},
    DetectionTriggers: pulumi.StringArray{pulumi.String("pod_creation"), pulumi.String("pod_reschedule")},
    CooldownMinutes:   pulumi.IntPtr(60),
})
if err != nil {
    return err
}

ctx.Export("ruleId", rule.ID())

Auto-generate:

rule, err := resources.NewWorkloadRule(ctx, "my-app-rule", &resources.WorkloadRuleArgs{
    ClusterId:    pulumi.String("cluster-abc123"),
    Namespace:    pulumi.String("production"),
    Kind:         pulumi.String("Deployment"),
    Name:         pulumi.String("my-api"),
    AutoGenerate: pulumi.BoolPtr(true),
})

WorkloadRule — Key Fields

| Field | Type | Description | |---|---|---| | clusterId | string | ID of the cluster the workload lives in | | namespace | string | Kubernetes namespace of the workload | | kind | string | Workload kind: Deployment | StatefulSet | DaemonSet | CronJob | Job | | name | string | Name of the Kubernetes workload | | autoGenerate | bool | When true, the engine fills all rule fields from observed usage; manual fields are ignored | | cpuRule | ResourceRuleConfigArgs | CPU vertical scaling rule | | memoryRule | ResourceRuleConfigArgs | Memory vertical scaling rule | | gpuRule | ResourceRuleConfigArgs | GPU vertical scaling rule (units: GPU millicores) | | hpaRule | HPARuleConfigArgs | Horizontal (replica) scaling rule | | emergencyResponse | EmergencyResponseConfigArgs | OOM and CPU-throttle emergency reactions | | actionTriggers | string[] | When to apply: on_detection | on_schedule | | cronSchedule | string | Cron expression for scheduled application (5-field UTC). Required when actionTriggers includes on_schedule | | detectionTriggers | string[] | Events that trigger a recommendation: pod_creation | pod_update | pod_reschedule | | startupPeriodSeconds | int | Seconds after workload start to exclude from usage data | | cooldownMinutes | int | Minimum minutes between consecutive recommendation applications | | schedulerPlugins | string[] | Kubernetes scheduler plugins to activate. Example: ["binpacking"] | | defragmentationSchedule | string | Cron expression for node defragmentation | | liveMigrationEnabled | bool | Allow live pod migration when applying recommendations without restart | | useInPlaceVerticalScaling | bool | Use in-place pod vertical scaling instead of pod restarts | | containers | ContainerResourceRuleConfigArgs[] | Per-container resource overrides. When empty, workload-level rules apply to all containers |

ResourceRuleConfigArgs

Used for cpuRule, memoryRule, and gpuRule at both the workload and per-container level.

Note: maxScaleUpPercent and maxScaleDownPercent are not supported on per-container rules — set them on the workload-level fields instead.

| Field | Type | Description | |---|---|---| | enabled | bool | Enable this resource axis rule | | minRequest | int | Minimum resource request (millicores for CPU, bytes for memory/GPU) | | maxRequest | int | Maximum resource request | | targetPercentile | float | Percentile of observed usage to target (0–1). Example: 0.95 | | maxScaleUpPercent | float | Maximum percentage to scale up in one step (workload-level only) | | maxScaleDownPercent | float | Maximum percentage to scale down in one step (workload-level only) | | limitsAdjustmentEnabled | bool | Whether to also adjust resource limits | | limitMultiplier | float | Limits = request × limitMultiplier | | limitsRemovalEnabled | bool | Actively remove limits from workloads (CPU only) |

HPARuleConfigArgs

| Field | Type | Description | |---|---|---| | enabled | bool | Enable horizontal (replica) scaling | | minReplicas | int | Minimum number of replicas | | maxReplicas | int | Maximum number of replicas | | targetUtilization | float | Target CPU utilization ratio (0–1). Example: 0.8 | | targetMemoryUtilization | float | Target memory utilization ratio (0–1), tuned independently of CPU. Example: 0.65 | | primaryMetric | string | Primary metric driving HPA (used when metrics is empty): cpu | memory | gpu | network_ingress | network_egress. Example: "memory" | | maxReplicaChangePercent | float | Maximum fraction of current replicas that can change in one scale event (0–1). 0.25 means at most 25% added or removed at once. Example: 0.25 | | scaleDownCooldownSeconds | int | Seconds to wait between scale-down events. Example: 300 | | metrics | HPAMetricTriggerArgs[] | Additional metric triggers (e.g. Prometheus). CPU/Memory/Network are auto-generated by the engine from primaryMetric — do not redeclare them here | | compositeFormula | string | Expression combining multiple metric ratios into one scaling signal. Example: "0.6*cpu + 0.4*memory" | | behavior | HPABehaviorArgs | Fine-grained scale-up and scale-down behavior policies | | fallback | HPAFallbackArgs | Replica fallback when metrics become unavailable |

Python uses snake_case (e.g. target_memory_utilization, scale_down_cooldown_seconds, composite_formula). Go uses PascalCase equivalents.

HPAMetricTriggerArgs

Note: CPU, Memory, and Network triggers are auto-generated by the engine from primaryMetric + targetUtilization. Only add entries here for external metrics (e.g. Prometheus). Redeclaring built-in metrics here will result in duplicate triggers.

| Field | Type | Description | |---|---|---| | type | string | Metric source type. Built-in: CPU, Memory, NetworkIngress, NetworkEgress. External: prometheus | | targetUtilization | string | Target utilization as a decimal string (resource metrics). Example: "0.70" | | targetValue | string | Absolute target value as a string (external/object metrics). Example: "50000000" | | weight | string | Weight for composite formula scaling (decimal string). Example: "0.5" | | metadata | map[string]string | Free-form key-value pairs passed to the external scaler | | serverAddress | string | Prometheus server URL — packed into metadata by the service layer. Example: "http://prometheus:9090" | | query | string | PromQL query string — packed into metadata by the service layer. Example: "sum(rate(http_requests_total[2m]))" |

Python: target_utilization, target_value, server_address. Go uses PascalCase equivalents.

Prometheus-driven HPA example

// TypeScript
const rule = new resources.WorkloadRule("my-app-rule", {
    clusterId: "cluster-abc123",
    namespace: "production",
    kind: "Deployment",
    name: "my-api",
    hpaRule: {
        enabled: true,
        minReplicas: 1,
        maxReplicas: 8,
        primaryMetric: "memory",       // primary scaling signal
        targetUtilization: 0.8,        // CPU target — 80%
        targetMemoryUtilization: 0.65, // Memory target — 65%
        maxReplicaChangePercent: 0.25, // at most 25% of replicas changed per event
        scaleDownCooldownSeconds: 300, // 5 min between scale-downs
        // Only add external metrics here — CPU/Memory are auto-generated above
        metrics: [
            {
                type: "prometheus",
                targetValue: "100",
                serverAddress: "http://prometheus.monitoring:9090",
                query: "sum(rate(http_requests_total{app='my-api'}[2m]))",
            },
        ],
        compositeFormula: "0.6*cpu + 0.4*prometheus",
        fallback: {
            replicas: 1,
            behavior: "currentReplicas", // keep whatever is running when metrics fail
            failureThreshold: 3,
        },
        behavior: {
            scaleDown: {
                stabilizationWindowSeconds: 300, // wait 5 min before scaling down
                selectPolicy: "Min",
                policies: [
                    { type: "Pods", value: 1, periodSeconds: 60 }, // remove at most 1 pod/min
                ],
            },
            scaleUp: {
                stabilizationWindowSeconds: 0,   // scale up immediately
                selectPolicy: "Max",
                policies: [
                    { type: "Percent", value: 100, periodSeconds: 60 }, // double replicas/min
                    { type: "Pods", value: 4, periodSeconds: 60 },      // or add 4 pods/min
                ],
            },
        },
    },
});

# Python
from pulumi_devzero.resources import (
    WorkloadRule, WorkloadRuleArgs,
    HPARuleConfigArgsArgs,
    HPAMetricTriggerArgsArgs,
    HPAFallbackArgsArgs,
    HPABehaviorArgsArgs,
    HPAScalingRulesArgsArgs,
    HPAScalingPolicyArgsArgs,
)

rule = WorkloadRule("my-app-rule", args=WorkloadRuleArgs(
    cluster_id="cluster-abc123",
    namespace="production",
    kind="Deployment",
    name="my-api",
    hpa_rule=HPARuleConfigArgsArgs(
        enabled=True,
        min_replicas=1,
        max_replicas=8,
        primary_metric="memory",          # primary scaling signal
        target_utilization=0.8,           # CPU target — 80%
        target_memory_utilization=0.65,   # Memory target — 65%
        max_replica_change_percent=0.25,  # at most 25% of replicas changed per event
        scale_down_cooldown_seconds=300,  # 5 min between scale-downs
        # Only add external metrics here — CPU/Memory are auto-generated above
        metrics=[HPAMetricTriggerArgsArgs(
            type="prometheus",
            target_value="100",
            server_address="http://prometheus.monitoring:9090",
            query="sum(rate(http_requests_total{app='my-api'}[2m]))",
        )],
        composite_formula="0.6*cpu + 0.4*prometheus",
        fallback=HPAFallbackArgsArgs(
            replicas=1,
            behavior="currentReplicas",  # keep whatever is running when metrics fail
            failure_threshold=3,
        ),
        behavior=HPABehaviorArgsArgs(
            scale_down=HPAScalingRulesArgsArgs(
                stabilization_window_seconds=300,  # wait 5 min before scaling down
                select_policy="Min",
                policies=[HPAScalingPolicyArgsArgs(type="Pods", value=1, period_seconds=60)],  # remove at most 1 pod/min
            ),
            scale_up=HPAScalingRulesArgsArgs(
                stabilization_window_seconds=0,    # scale up immediately
                select_policy="Max",
                policies=[
                    HPAScalingPolicyArgsArgs(type="Percent", value=100, period_seconds=60),  # double replicas/min
                    HPAScalingPolicyArgsArgs(type="Pods", value=4, period_seconds=60),       # or add 4 pods/min
                ],
            ),
        ),
    ),
))

// Go
rule, err := resources.NewWorkloadRule(ctx, "my-app-rule", &resources.WorkloadRuleArgs{
    ClusterId: pulumi.String("cluster-abc123"),
    Namespace: pulumi.String("production"),
    Kind:      pulumi.String("Deployment"),
    Name:      pulumi.String("my-api"),
    HpaRule: resources.HPARuleConfigArgsArgs{
        Enabled:                    pulumi.BoolPtr(true),
        MinReplicas:                pulumi.IntPtr(1),
        MaxReplicas:                pulumi.IntPtr(8),
        PrimaryMetric:              pulumi.StringPtr("memory"),  // primary scaling signal
        TargetUtilization:          pulumi.Float64Ptr(0.8),      // CPU target — 80%
        TargetMemoryUtilization:    pulumi.Float64Ptr(0.65),     // Memory target — 65%
        MaxReplicaChangePercent:    pulumi.Float64Ptr(0.25),     // at most 25% of replicas changed per event
        ScaleDownCooldownSeconds:   pulumi.IntPtr(300),          // 5 min between scale-downs
        CompositeFormula:           pulumi.StringPtr("0.6*cpu + 0.4*prometheus"),
        // Only add external metrics here — CPU/Memory are auto-generated above
        Metrics: resources.HPAMetricTriggerArgsArray{
            resources.HPAMetricTriggerArgsArgs{
                Type:          pulumi.String("prometheus"),
                TargetValue:   pulumi.StringPtr("100"),
                ServerAddress: pulumi.StringPtr("http://prometheus.monitoring:9090"),
                Query:         pulumi.StringPtr("sum(rate(http_requests_total{app='my-api'}[2m]))"),
            },
        },
        Fallback: resources.HPAFallbackArgsArgs{
            Replicas:         pulumi.Int(1),
            Behavior:         pulumi.String("currentReplicas"), // keep whatever is running when metrics fail
            FailureThreshold: pulumi.Int(3),
        }.ToHPAFallbackArgsPtrOutput(),
        Behavior: resources.HPABehaviorArgsArgs{
            ScaleDown: resources.HPAScalingRulesArgsArgs{
                StabilizationWindowSeconds: pulumi.Int(300), // wait 5 min before scaling down
                SelectPolicy:               pulumi.String("Min"),
                Policies: resources.HPAScalingPolicyArgsArray{
                    // remove at most 1 pod per minute
                    resources.HPAScalingPolicyArgsArgs{Type: pulumi.String("Pods"), Value: pulumi.Int(1), PeriodSeconds: pulumi.Int(60)},
                },
            }.ToHPAScalingRulesArgsPtrOutput(),
            ScaleUp: resources.HPAScalingRulesArgsArgs{
                StabilizationWindowSeconds: pulumi.Int(0), // scale up immediately
                SelectPolicy:               pulumi.String("Max"),
                Policies: resources.HPAScalingPolicyArgsArray{
                    // double replicas per minute
                    resources.HPAScalingPolicyArgsArgs{Type: pulumi.String("Percent"), Value: pulumi.Int(100), PeriodSeconds: pulumi.Int(60)},
                    // or add up to 4 pods per minute
                    resources.HPAScalingPolicyArgsArgs{Type: pulumi.String("Pods"), Value: pulumi.Int(4), PeriodSeconds: pulumi.Int(60)},
                },
            }.ToHPAScalingRulesArgsPtrOutput(),
        }.ToHPABehaviorArgsPtrOutput(),
    }.ToHPARuleConfigArgsPtrOutput(),
})

HPAFallbackArgs

| Field | Type | Description | |---|---|---| | replicas | int | Replica count to use when metrics are unavailable. Example: 1 | | behavior | string | How to apply fallback replicas. One of: static (always use replicas), currentReplicas (keep whatever is running), currentReplicasIfHigher (use current only if higher), currentReplicasIfLower (use current only if lower). Example: "currentReplicas" | | failureThreshold | int | Consecutive metric failures before fallback activates. Example: 3 |

HPABehaviorArgs

| Field | Type | Description | |---|---|---| | scaleUp | HPAScalingRulesArgs | Scale-up rate limiting and stabilization | | scaleDown | HPAScalingRulesArgs | Scale-down rate limiting and stabilization |

HPAScalingRulesArgs

| Field | Type | Description | |---|---|---| | stabilizationWindowSeconds | int | Seconds to look back when selecting replica count to avoid flapping. Default: 0 for scale-up, 300 for scale-down | | selectPolicy | string | Which policy wins when multiple match: Max | Min | Disabled. Example: "Max" | | policies | HPAScalingPolicyArgs[] | List of rate-limiting step policies |

HPAScalingPolicyArgs

| Field | Type | Description | |---|---|---| | type | string | Policy type: Pods (absolute count) | Percent (% of current replicas). Example: "Percent" | | value | int | Maximum change allowed per period. Example: 100 | | periodSeconds | int | Time window for this policy in seconds. Example: 60 |

Python: stabilization_window_seconds, select_policy, period_seconds. Go uses PascalCase equivalents.

EmergencyResponseConfigArgs

| Field | Type | Description | |---|---|---| | oomEnabled | bool | React to OOM kills by increasing memory requests | | oomMemoryMultiplier | float | Multiplier applied to memory on OOM. Example: 1.5 | | oomMaxReactions | int | Maximum OOM reactions before giving up | | oomCooldownSeconds | int | Seconds to wait between OOM reactions | | cpuThrottlingEnabled | bool | React to CPU throttling by increasing CPU requests | | cpuThrottlingThreshold | float | Throttle ratio (0–1) that triggers a reaction. Example: 0.1 | | cpuThrottlingMultiplier | float | Multiplier applied to CPU request on throttle reaction. Example: 1.25 |

ContainerResourceRuleConfigArgs

| Field | Type | Description | |---|---|---| | containerName | string | Name of the container this config applies to | | cpuRule | ResourceRuleConfigArgs | CPU rule for this container | | memoryRule | ResourceRuleConfigArgs | Memory rule for this container | | gpuRule | ResourceRuleConfigArgs | GPU rule for this container |

NodePolicyTarget — Key Fields

| Field | Type | Description | |---|---|---| | name | string | Unique target name | | policyId | string | ID of the NodePolicy to apply | | clusterIds | string[] | Cluster IDs to target. At most 1 entry — the backend rejects more than one. | | description | string | Human-readable description (optional) | | enabled | bool | Activate the target. Default: true |

Python: policy_id, cluster_ids. Go: PolicyId, ClusterIds.

Note: pulumi destroy removes this resource from Pulumi state but does not delete it on the DevZero backend. You must remove it manually via the dashboard or API if needed.

Destroying Resources

To tear down all resources managed by your stack:

pulumi destroy

To also remove the stack itself:

pulumi stack rm <stack-name>

Building from Source

# Build the provider binary
make build

# Run tests
make test

# Regenerate schema and all SDKs (requires Pulumi CLI)
make sdk

# Install binary to $GOPATH/bin
make install

See CONTRIBUTING.md for full development instructions.

Examples

Ready-to-run examples live in examples/:

| Language | Path | |---|---| | TypeScript | [`e