11# ExternalDNS - UNOFFICIAL Hetzner Webhook
22
3- > [ !WARNING]
4- > ** This software is experimental.**
3+ > [ !IMPORTANT]
4+ > Support for the legacy DNS is going to be discontinued by Hetzner in May 2026.
5+ > The legacy provider will be pulled from this provider in version ** v1.0.0** .
6+ > No new features will be added to the legacy DNS driver and only important
7+ > bugfixes will be backported.
58
69> [ !NOTE]
7- > The latest version is ** v0.10 .0** .
10+ > The latest version is ** v0.11 .0** .
811
912[ ExternalDNS] ( https://github.com/kubernetes-sigs/external-dns ) is a Kubernetes
1013add-on for automatically DNS records for Kubernetes services using different
@@ -16,7 +19,7 @@ you to manage your Hetzner domains inside your kubernetes cluster.
1619This webhook supports both the old DNS API and the new Cloud DNS interface.
1720
1821> [ !TIP]
19- > If you are upgrading to ** 0.8 .x** from previous versions read the
22+ > If you are upgrading to ** v0.11 .x** from previous versions read the
2023> [ Upgrading from previous versions] ( #upgrading-from-previous-versions ) section.
2124
2225
@@ -80,7 +83,7 @@ provider:
8083 webhook :
8184 image :
8285 repository : ghcr.io/mconfalonieri/external-dns-hetzner-webhook
83- tag : v0.10 .0
86+ tag : v0.11 .0
8487 env :
8588 - name : HETZNER_API_KEY
8689 valueFrom :
@@ -140,7 +143,7 @@ extraArgs:
140143
141144sidecars :
142145 - name : hetzner-webhook
143- image : ghcr.io/mconfalonieri/external-dns-hetzner-webhook:v0.10 .0
146+ image : ghcr.io/mconfalonieri/external-dns-hetzner-webhook:v0.11 .0
144147 ports :
145148 - containerPort : 8888
146149 name : webhook
@@ -215,8 +218,66 @@ requires an escape sequence for the slash part. By default this will be:
215218
216219This can be changed using the **SLASH_ESC_SEQ** environment variable.
217220
221+ # # Bulk mode
222+
223+ The Cloud API now supports a new way of updating the records for a zone called
224+ **bulk mode**. This mode is activated by setting the `BULK_MODE` environment
225+ variable to `true`. It works by exporting the zonefile, editing it and then
226+ uploading the modified version. It is meant to be used in environments with a
227+ high number of record changes per zone and a relatively long interval between
228+ the updates, a combination that could cause the exhaustion of the permitted API
229+ calls.
230+
231+ > [!WARNING]
232+ > Beware that this method of updating the records is potentially destructive
233+ > and subject to "race conditions" if manual edits are applied while the zone
234+ > is being updated. Theoretically, unsupported records won't be affected, but
235+ > this method is to be considered **HIGHLY EXPERIMENTAL**, and bugs are likely
236+ > to be found.
237+
238+ It comes with some limitations.
239+
240+ 1. [Hetzner labels](#hetzner-labels) are not supported, as there is no way to
241+ import them in the zonefile. Record comments are unsupported as well.
242+ 2. All the records must be **not protected** as they will all be overwritten
243+ during the import operation, **including the SOA**. This is why the bulk
244+ mode should be used with care.
245+ 3. The SOA serial number is updated on each import, but the logic of the
246+ serial number only accepts the standard 10-digits serial number and will
247+ refuse to update it if the serial of the day is 99. Most configurations
248+ will be OK with this limitation.
249+ 4. If the zones managed by this webhook are also manipuilated by other
250+ software the following situation, although unlikely, could happen :
251+
252+ 1. the webhook downloads the zonefile for a zone
253+ 2. the other software manipulates some record on the same zone
254+ 3. the webhook uploads the zonefile, missing the changes applied by the
255+ other software
256+ 4. since the upload rewrites the zonefile, those changes are now lost.
257+
258+ Please check the [Zone file import](https://docs.hetzner.cloud/reference/cloud#tag/zones/zone-file-import)
259+ section of the Hetzner documentation for more details.
260+
218261# # Upgrading from previous versions
219262
263+ # ## 0.10.x to 0.11.x
264+
265+ The configuration is compatible with previous versions; however the
266+ **DEFAULT_TTL** parameter was removed and this environment variable will
267+ therefore not affect the configuration. The default TTL will be the one defined
268+ in the zone.
269+
270+ A **BULK_MODE** parameter was added. When set to `true`, the webhook will
271+ export and manipulate the zonefiles instead of the single recordsets. This will
272+ reduce the API calls when updating zones with lots of changes and a relatively
273+ long interval.
274+
275+ > [!WARNING]
276+ > The bulk mode is experimental and comes with some limitations. Please read
277+ > the [Bulk mode](#bulk-mode) section before activating it.
278+ >
279+
280+
220281# ## 0.9.x to 0.10.x
221282
222283The configuration is fully compatible. There is a new configuration parameter
@@ -281,11 +342,11 @@ Hetzner DNS API.
281342| --------------- | -------------------------------------- | -------------------------- |
282343| HETZNER_API_KEY | Hetzner API token | Mandatory |
283344| BATCH_SIZE | Number of zones per call | Default : ` 100` , max: `100` |
284- | DEFAULT_TTL | Default record TTL | Default : ` 7200` |
285345| USE_CLOUD_API | Use the new cloud API | Default : ` false` |
286346| SLASH_ESC_SEQ | Escape sequence for label annotations | Default : ` --slash--` |
287347| MAX_FAIL_COUNT | Number of failed calls before shutdown | Default : ` -1` (disabled) |
288- | ZONE_CACHE_TTL | TTL for the zone cache in seconds | Default : ` 0` (disabled) |
348+ | ZONE_CACHE_TTL | TTL for the zone cache in seconds | Default : ` 0` (disabled) |
349+ | BULK_MODE | Enables bulk mode | Default : ` false` |
289350
290351> [!IMPORTANT]
291352> Please notice that when **USE_CLOUD_API** is set to `true`, the token stored
@@ -315,10 +376,11 @@ These variables control the sockets that this application listens to.
315376
316377Please notice that the following variables were **deprecated** :
317378
318- | Variable | Description |
319- | ----------- | -------------------------------- |
320- | HEALTH_HOST | Metrics hostname (deprecated) |
321- | HEALTH_PORT | Metrics port (deprecated) |
379+ | Variable | Description |
380+ | ----------- | -------------------------------------- |
381+ | HEALTH_HOST | Metrics hostname (deprecated) |
382+ | HEALTH_PORT | Metrics port (deprecated) |
383+ | DEFAULT_TTL | The default TTL is taken from the zone |
322384
323385
324386# ## Domain filtering
@@ -448,6 +510,13 @@ The actions supported by the Cloud API provider are:
448510- ` update_rrset` (this is the method used to update labels)
449511- ` delete_rrset`
450512
513+ In case `BULK_MODE` is set to true, the following actions will be used instead :
514+
515+ - ` get_zones`
516+ - ` get_rrsets`
517+ - ` import_zonefile`
518+ - ` export_zonefile`
519+
451520The label `zone` can assume one of the zone names as its value.
452521
453522# # Development
0 commit comments