Create a Load Balancer

v1.0.0

Creates a Load Balancer.

Call specific error codes

Code	Description
`cloud_resource_ip_not_allowed`	The IP you are trying to add as a target belongs to a Hetzner Cloud resource
`ip_not_owned`	The IP is not owned by the owner of the project of the Load Balancer
`load_balancer_not_attached_to_network`	The Load Balancer is not attached to a network
`robot_unavailable`	Robot was not available. The caller may retry the operation after a short delay.
`server_not_attached_to_network`	The server you are trying to add as a target is not attached to the same network as the Load Balancer
`source_port_already_used`	The source port you are trying to add is already in use
`target_already_defined`	The Load Balancer target you are trying to define is already defined

Input

{
  "type": "object",
  "required": [
    "algorithm",
    "load_balancer_type",
    "name"
  ],
  "properties": {
    "algorithm": {
      "type": "object",
      "description": "Algorithm of the Load Balancer",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "Type of the algorithm",
          "enum": [
            "round_robin",
            "least_connections"
          ]
        }
      }
    },
    "labels": {
      "type": "object",
      "description": "User-defined labels (key-value pairs)",
      "properties": {
        "labelkey": {
          "type": "string",
          "description": "New label"
        }
      }
    },
    "load_balancer_type": {
      "type": "string",
      "description": "ID or name of the Load Balancer type this Load Balancer should be created with"
    },
    "location": {
      "type": "string",
      "description": "ID or name of Location to create Load Balancer in"
    },
    "name": {
      "type": "string",
      "description": "Name of the Load Balancer"
    },
    "network": {
      "type": "integer",
      "description": "ID of the network the Load Balancer should be attached to on creation"
    },
    "network_zone": {
      "type": "string",
      "description": "Name of network zone"
    },
    "public_interface": {
      "type": "boolean",
      "description": "Enable or disable the public interface of the Load Balancer"
    },
    "services": {
      "type": "array",
      "description": "Array of services",
      "items": {
        "type": "object",
        "required": [
          "protocol",
          "listen_port",
          "destination_port",
          "proxyprotocol",
          "health_check"
        ],
        "properties": {
          "destination_port": {
            "type": "integer",
            "description": "Port the Load Balancer will balance to"
          },
          "health_check": {
            "type": "object",
            "description": "Service health check",
            "required": [
              "protocol",
              "port",
              "interval",
              "timeout",
              "retries"
            ],
            "properties": {
              "http": {
                "type": "object",
                "description": "Additional configuration for protocol http",
                "required": [
                  "domain",
                  "path"
                ],
                "properties": {
                  "domain": {
                    "type": "string",
                    "description": "Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent."
                  },
                  "path": {
                    "type": "string",
                    "description": "HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead."
                  },
                  "response": {
                    "type": "string",
                    "description": "String that must be contained in HTTP response in order to pass the health check"
                  },
                  "status_codes": {
                    "type": "array",
                    "description": "List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. The default is to pass the health check for any status code between 2?? and 3??.",
                    "items": {
                      "type": "string"
                    }
                  },
                  "tls": {
                    "type": "boolean",
                    "description": "Use HTTPS for health check"
                  }
                },
                "additionalProperties": false
              },
              "interval": {
                "type": "integer",
                "description": "Time interval in seconds health checks are performed"
              },
              "port": {
                "type": "integer",
                "description": "Port the health check will be performed on"
              },
              "protocol": {
                "type": "string",
                "description": "Type of the health check",
                "enum": [
                  "tcp",
                  "http"
                ]
              },
              "retries": {
                "type": "integer",
                "description": "Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again"
              },
              "timeout": {
                "type": "integer",
                "description": "Time in seconds after an attempt is considered a timeout"
              }
            },
            "additionalProperties": false
          },
          "http": {
            "type": "object",
            "description": "Configuration option for protocols http and https",
            "properties": {
              "certificates": {
                "type": "array",
                "description": "IDs of the Certificates to use for TLS/SSL termination by the Load Balancer; empty for TLS/SSL passthrough or if `protocol` is \"http\"",
                "items": {
                  "type": "integer"
                }
              },
              "cookie_lifetime": {
                "type": "integer",
                "description": "Lifetime of the cookie used for sticky sessions"
              },
              "cookie_name": {
                "type": "string",
                "description": "Name of the cookie used for sticky sessions"
              },
              "redirect_http": {
                "type": "boolean",
                "description": "Redirect HTTP requests to HTTPS. Only available if protocol is \"https\". Default `false`"
              },
              "sticky_sessions": {
                "type": "boolean",
                "description": "Use sticky sessions. Only available if protocol is \"http\" or \"https\". Default `false`"
              }
            }
          },
          "listen_port": {
            "type": "integer",
            "description": "Port the Load Balancer listens on"
          },
          "protocol": {
            "type": "string",
            "description": "Protocol of the Load Balancer",
            "enum": [
              "tcp",
              "http",
              "https"
            ]
          },
          "proxyprotocol": {
            "type": "boolean",
            "description": "Is Proxyprotocol enabled or not"
          }
        }
      }
    },
    "targets": {
      "type": "array",
      "description": "Array of targets",
      "items": {
        "type": "object",
        "required": [
          "type"
        ],
        "properties": {
          "health_status": {
            "type": "array",
            "description": "List of health statuses of the services on this target",
            "items": {
              "type": "object",
              "properties": {
                "listen_port": {
                  "type": "integer"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "healthy",
                    "unhealthy",
                    "unknown"
                  ]
                }
              }
            }
          },
          "ip": {
            "type": "object",
            "description": "IP targets where the traffic should be routed through. It is only possible to use the (Public or vSwitch) IPs of Hetzner Online Root Servers belonging to the project owner. IPs belonging to other users are blocked. Additionally IPs belonging to services provided by Hetzner Cloud (Servers, Load Balancers, ...) are blocked as well.",
            "required": [
              "ip"
            ],
            "properties": {
              "ip": {
                "type": "string",
                "description": "IP of a server that belongs to the same customer (public IPv4/IPv6) or private IP in a Subnetwork type vswitch."
              }
            }
          },
          "label_selector": {
            "type": "object",
            "description": "Label selector and a list of selected targets",
            "required": [
              "selector"
            ],
            "properties": {
              "selector": {
                "type": "string",
                "description": "Label selector"
              }
            }
          },
          "server": {
            "type": "object",
            "description": "Server where the traffic should be routed through",
            "required": [
              "id"
            ],
            "properties": {
              "id": {
                "type": "integer",
                "description": "ID of the Server"
              }
            }
          },
          "targets": {
            "type": "array",
            "description": "List of selected targets",
            "items": {
              "type": "object",
              "properties": {
                "health_status": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "listen_port": {
                        "type": "integer"
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "healthy",
                          "unhealthy",
                          "unknown"
                        ]
                      }
                    }
                  }
                },
                "server": {
                  "type": "object",
                  "required": [
                    "id"
                  ],
                  "properties": {
                    "id": {
                      "type": "integer",
                      "description": "ID of the Server"
                    }
                  }
                },
                "type": {
                  "type": "string"
                },
                "use_private_ip": {
                  "type": "boolean"
                }
              }
            }
          },
          "type": {
            "type": "string",
            "description": "Type of the resource",
            "enum": [
              "server",
              "label_selector",
              "ip"
            ]
          },
          "use_private_ip": {
            "type": "boolean",
            "description": "Use the private network IP instead of the public IP. Default value is false."
          }
        }
      }
    }
  }
}

Output

{
  "type": "object",
  "required": [
    "action",
    "load_balancer"
  ],
  "properties": {
    "action": {
      "type": "object",
      "required": [
        "command",
        "error",
        "finished",
        "id",
        "progress",
        "resources",
        "started",
        "status"
      ],
      "properties": {
        "command": {
          "type": "string",
          "description": "Command executed in the Action"
        },
        "error": {
          "type": "object",
          "description": "Error message for the Action if error occurred, otherwise null",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message"
            }
          }
        },
        "finished": {
          "type": "string",
          "description": "Point in time when the Action was finished (in ISO-8601 format). Only set if the Action is finished otherwise null."
        },
        "id": {
          "type": "integer",
          "description": "ID of the Resource"
        },
        "progress": {
          "type": "number",
          "description": "Progress of Action in percent"
        },
        "resources": {
          "type": "array",
          "description": "Resources the Action relates to",
          "items": {
            "type": "object",
            "required": [
              "id",
              "type"
            ],
            "properties": {
              "id": {
                "type": "integer",
                "description": "ID of the Resource"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            }
          }
        },
        "started": {
          "type": "string",
          "description": "Point in time when the Action was started (in ISO-8601 format)"
        },
        "status": {
          "type": "string",
          "description": "Status of the Action",
          "enum": [
            "success",
            "running",
            "error"
          ]
        }
      }
    },
    "load_balancer": {
      "type": "object",
      "required": [
        "algorithm",
        "created",
        "id",
        "included_traffic",
        "ingoing_traffic",
        "labels",
        "load_balancer_type",
        "location",
        "name",
        "outgoing_traffic",
        "private_net",
        "protection",
        "public_net",
        "services",
        "targets"
      ],
      "properties": {
        "algorithm": {
          "type": "object",
          "description": "Algorithm of the Load Balancer",
          "required": [
            "type"
          ],
          "properties": {
            "type": {
              "type": "string",
              "description": "Type of the algorithm",
              "enum": [
                "round_robin",
                "least_connections"
              ]
            }
          }
        },
        "created": {
          "type": "string",
          "description": "Point in time when the Resource was created (in ISO-8601 format)"
        },
        "id": {
          "type": "integer",
          "description": "ID of the Resource"
        },
        "included_traffic": {
          "type": "integer",
          "description": "Free Traffic for the current billing period in bytes"
        },
        "ingoing_traffic": {
          "type": "integer",
          "description": "Inbound Traffic for the current billing period in bytes"
        },
        "labels": {
          "type": "object",
          "description": "User-defined labels (key-value pairs)"
        },
        "load_balancer_type": {
          "type": "object",
          "required": [
            "deprecated",
            "description",
            "id",
            "max_assigned_certificates",
            "max_connections",
            "max_services",
            "max_targets",
            "name",
            "prices"
          ],
          "properties": {
            "deprecated": {
              "type": "string",
              "description": "Point in time when the Load Balancer type is deprecated (in ISO-8601 format)"
            },
            "description": {
              "type": "string",
              "description": "Description of the Load Balancer type"
            },
            "id": {
              "type": "number",
              "description": "ID of the Load Balancer type"
            },
            "max_assigned_certificates": {
              "type": "number",
              "description": "Number of SSL Certificates that can be assigned to a single Load Balancer"
            },
            "max_connections": {
              "type": "number",
              "description": "Number of maximum simultaneous open connections"
            },
            "max_services": {
              "type": "number",
              "description": "Number of services a Load Balancer of this type can have"
            },
            "max_targets": {
              "type": "number",
              "description": "Number of targets a single Load Balancer can have"
            },
            "name": {
              "type": "string",
              "description": "Unique identifier of the Load Balancer type"
            },
            "prices": {
              "type": "array",
              "description": "Prices in different network zones",
              "items": {
                "type": "object",
                "required": [
                  "location",
                  "price_hourly",
                  "price_monthly"
                ],
                "properties": {
                  "location": {
                    "type": "string",
                    "description": "Name of the Location the price is for"
                  },
                  "price_hourly": {
                    "type": "object",
                    "description": "Hourly costs for a Resource in this Location",
                    "required": [
                      "net",
                      "gross"
                    ],
                    "properties": {
                      "gross": {
                        "type": "string",
                        "description": "Price with VAT added"
                      },
                      "net": {
                        "type": "string",
                        "description": "Price without VAT"
                      }
                    }
                  },
                  "price_monthly": {
                    "type": "object",
                    "description": "Monthly costs for a Resource in this Location",
                    "required": [
                      "net",
                      "gross"
                    ],
                    "properties": {
                      "gross": {
                        "type": "string",
                        "description": "Price with VAT added"
                      },
                      "net": {
                        "type": "string",
                        "description": "Price without VAT"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "location": {
          "type": "object",
          "required": [
            "city",
            "country",
            "description",
            "id",
            "latitude",
            "longitude",
            "name",
            "network_zone"
          ],
          "properties": {
            "city": {
              "type": "string",
              "description": "City the Location is closest to"
            },
            "country": {
              "type": "string",
              "description": "ISO 3166-1 alpha-2 code of the country the Location resides in"
            },
            "description": {
              "type": "string",
              "description": "Description of the Location"
            },
            "id": {
              "type": "number",
              "description": "ID of the Location"
            },
            "latitude": {
              "type": "number",
              "description": "Latitude of the city closest to the Location"
            },
            "longitude": {
              "type": "number",
              "description": "Longitude of the city closest to the Location"
            },
            "name": {
              "type": "string",
              "description": "Unique identifier of the Location"
            },
            "network_zone": {
              "type": "string",
              "description": "Name of network zone this Location resides in"
            }
          }
        },
        "name": {
          "type": "string",
          "description": "Name of the Resource. Must be unique per Project."
        },
        "outgoing_traffic": {
          "type": "integer",
          "description": "Outbound Traffic for the current billing period in bytes"
        },
        "private_net": {
          "type": "array",
          "description": "Private networks information",
          "items": {
            "type": "object",
            "properties": {
              "ip": {
                "type": "string"
              },
              "network": {
                "type": "integer"
              }
            }
          }
        },
        "protection": {
          "type": "object",
          "description": "Protection configuration for the Resource",
          "required": [
            "delete"
          ],
          "properties": {
            "delete": {
              "type": "boolean",
              "description": "If true, prevents the Resource from being deleted"
            }
          }
        },
        "public_net": {
          "type": "object",
          "description": "Public network information",
          "required": [
            "enabled",
            "ipv4",
            "ipv6"
          ],
          "properties": {
            "enabled": {
              "type": "boolean",
              "description": "Public Interface enabled or not"
            },
            "ipv4": {
              "type": "object",
              "description": "IP address (v4)",
              "properties": {
                "dns_ptr": {
                  "type": "string",
                  "description": "Reverse DNS PTR entry for the IPv4 address of this Load Balancer"
                },
                "ip": {
                  "type": "string",
                  "description": "IP address (v4) of this Load Balancer"
                }
              }
            },
            "ipv6": {
              "type": "object",
              "description": "IP address (v6)",
              "properties": {
                "dns_ptr": {
                  "type": "string",
                  "description": "Reverse DNS PTR entry for the IPv6 address of this Load Balancer"
                },
                "ip": {
                  "type": "string",
                  "description": "IP address (v6) of this Load Balancer"
                }
              }
            }
          }
        },
        "services": {
          "type": "array",
          "description": "List of services that belong to this Load Balancer",
          "items": {
            "type": "object",
            "required": [
              "protocol",
              "listen_port",
              "destination_port",
              "proxyprotocol",
              "health_check"
            ],
            "properties": {
              "destination_port": {
                "type": "integer",
                "description": "Port the Load Balancer will balance to"
              },
              "health_check": {
                "type": "object",
                "description": "Service health check",
                "required": [
                  "protocol",
                  "port",
                  "interval",
                  "timeout",
                  "retries"
                ],
                "properties": {
                  "http": {
                    "type": "object",
                    "description": "Additional configuration for protocol http",
                    "required": [
                      "domain",
                      "path"
                    ],
                    "properties": {
                      "domain": {
                        "type": "string",
                        "description": "Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent."
                      },
                      "path": {
                        "type": "string",
                        "description": "HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead."
                      },
                      "response": {
                        "type": "string",
                        "description": "String that must be contained in HTTP response in order to pass the health check"
                      },
                      "status_codes": {
                        "type": "array",
                        "description": "List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. The default is to pass the health check for any status code between 2?? and 3??.",
                        "items": {
                          "type": "string"
                        }
                      },
                      "tls": {
                        "type": "boolean",
                        "description": "Use HTTPS for health check"
                      }
                    },
                    "additionalProperties": false
                  },
                  "interval": {
                    "type": "integer",
                    "description": "Time interval in seconds health checks are performed"
                  },
                  "port": {
                    "type": "integer",
                    "description": "Port the health check will be performed on"
                  },
                  "protocol": {
                    "type": "string",
                    "description": "Type of the health check",
                    "enum": [
                      "tcp",
                      "http"
                    ]
                  },
                  "retries": {
                    "type": "integer",
                    "description": "Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again"
                  },
                  "timeout": {
                    "type": "integer",
                    "description": "Time in seconds after an attempt is considered a timeout"
                  }
                },
                "additionalProperties": false
              },
              "http": {
                "type": "object",
                "description": "Configuration option for protocols http and https",
                "properties": {
                  "certificates": {
                    "type": "array",
                    "description": "IDs of the Certificates to use for TLS/SSL termination by the Load Balancer; empty for TLS/SSL passthrough or if `protocol` is \"http\"",
                    "items": {
                      "type": "integer"
                    }
                  },
                  "cookie_lifetime": {
                    "type": "integer",
                    "description": "Lifetime of the cookie used for sticky sessions"
                  },
                  "cookie_name": {
                    "type": "string",
                    "description": "Name of the cookie used for sticky sessions"
                  },
                  "redirect_http": {
                    "type": "boolean",
                    "description": "Redirect HTTP requests to HTTPS. Only available if protocol is \"https\". Default `false`"
                  },
                  "sticky_sessions": {
                    "type": "boolean",
                    "description": "Use sticky sessions. Only available if protocol is \"http\" or \"https\". Default `false`"
                  }
                }
              },
              "listen_port": {
                "type": "integer",
                "description": "Port the Load Balancer listens on"
              },
              "protocol": {
                "type": "string",
                "description": "Protocol of the Load Balancer",
                "enum": [
                  "tcp",
                  "http",
                  "https"
                ]
              },
              "proxyprotocol": {
                "type": "boolean",
                "description": "Is Proxyprotocol enabled or not"
              }
            }
          }
        },
        "targets": {
          "type": "array",
          "description": "List of targets that belong to this Load Balancer",
          "items": {
            "type": "object",
            "required": [
              "type"
            ],
            "properties": {
              "health_status": {
                "type": "array",
                "description": "List of health statuses of the services on this target",
                "items": {
                  "type": "object",
                  "properties": {
                    "listen_port": {
                      "type": "integer"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "healthy",
                        "unhealthy",
                        "unknown"
                      ]
                    }
                  }
                }
              },
              "ip": {
                "type": "object",
                "description": "IP targets where the traffic should be routed through. It is only possible to use the (Public or vSwitch) IPs of Hetzner Online Root Servers belonging to the project owner. IPs belonging to other users are blocked. Additionally IPs belonging to services provided by Hetzner Cloud (Servers, Load Balancers, ...) are blocked as well.",
                "required": [
                  "ip"
                ],
                "properties": {
                  "ip": {
                    "type": "string",
                    "description": "IP of a server that belongs to the same customer (public IPv4/IPv6) or private IP in a Subnetwork type vswitch."
                  }
                }
              },
              "label_selector": {
                "type": "object",
                "description": "Label selector and a list of selected targets",
                "required": [
                  "selector"
                ],
                "properties": {
                  "selector": {
                    "type": "string",
                    "description": "Label selector"
                  }
                }
              },
              "server": {
                "type": "object",
                "description": "Server where the traffic should be routed through",
                "required": [
                  "id"
                ],
                "properties": {
                  "id": {
                    "type": "integer",
                    "description": "ID of the Server"
                  }
                }
              },
              "targets": {
                "type": "array",
                "description": "List of selected targets",
                "items": {
                  "type": "object",
                  "properties": {
                    "health_status": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "listen_port": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "status": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      }
                    },
                    "server": {
                      "type": "object",
                      "required": [
                        "id"
                      ],
                      "properties": {
                        "id": {
                          "type": "integer",
                          "description": "ID of the Server"
                        }
                      }
                    },
                    "type": {
                      "type": "string"
                    },
                    "use_private_ip": {
                      "type": "boolean"
                    }
                  }
                }
              },
              "type": {
                "type": "string",
                "description": "Type of the resource",
                "enum": [
                  "server",
                  "label_selector",
                  "ip"
                ]
              },
              "use_private_ip": {
                "type": "boolean",
                "description": "Use the private network IP instead of the public IP. Default value is false."
              }
            }
          }
        }
      }
    }
  }
}