BlockList

BlockList is a named, refreshable set of block or allow entries.


API version	`kudurru.io/v1alpha1`
Kind	`BlockList`
Scope	Namespaced
Resource	`blocklists.kudurru.io`
Short names	`blocklist`
Subresources	`status`

Columns of kubectl get blocklists:

Column	Type	Value
MODE	string	`.spec.mode`
ENTRIES	integer	`.status.entries`
LAST-FETCH	date	`.status.lastFetched`
READY	string	`.status.conditions[?(@.type=="Ready")].status`

Spec

BlockListSpec defines a set of sources compiled into one matcher chain.

Validation: response customIP requires the customIP block (!has(self.response) || self.response != 'customIP' || has(self.customIP))

Field	Type	Description
`spec.customIP`	`object`	CustomIP is the answer for BlockResponse customIP.
`spec.customIP.v4`	`string`
`spec.customIP.v6`	`string`
`spec.mode`	`string`	ListMode says whether entries block or allow. Default: `block` One of: `block`, `allow`
`spec.refreshInterval`	`string`	Default: `24h`
`spec.response`	`string`	BlockResponse is how a blocked query is answered: nxdomain, zeroIP (0.0.0.0 / ::), refused, customIP (the customIP addresses) or blockPage (the addresses of the block page listener, blockPage.ipv4/ipv6, so browsers show why the name is blocked). One of: `nxdomain`, `zeroIP`, `refused`, `customIP`, `blockPage`
`spec.sources`	`[]object`	Required. Items: 1 to 256
`spec.sources[].configMapRef`	`object`	ObjectRef points at another kudurru object. Namespace is omitted for cluster-scoped kinds and for same-namespace references.
`spec.sources[].configMapRef.name`	`string`	Required. Length: at least 1
`spec.sources[].configMapRef.namespace`	`string`
`spec.sources[].enabled`	`boolean`	Enabled false switches this one source off without removing it, like Pi-hole's per-adlist switch: it is not fetched and not compiled, its cached body and status digest are kept, and status.sources[] reports it with enabled: false. Omitted means true. The kudurru.io/enabled annotation switches the whole list off.
`spec.sources[].entries`	`[]object`	Entries are structured entries (value, type, switch, comment, provenance), as the dashboard's Allowlist and Denylist write them. They compile as adblock rules; format and subdomains do not apply. Items: at most 10000
`spec.sources[].entries[].comment`	`string`	Length: at most 500
`spec.sources[].entries[].created`	`string`	Format: `date-time`
`spec.sources[].entries[].createdBy`	`string`	CreatedBy is the actor that added the entry ("user:alice"). Length: at most 300
`spec.sources[].entries[].enabled`	`boolean`	Enabled false keeps the entry without applying it. Omitted means true.
`spec.sources[].entries[].modified`	`string`	Format: `date-time`
`spec.sources[].entries[].origin`	`string`	EntryOrigin records how a structured entry was added. One of: `manual`, `querylog`, `unblock`, `api`, `migrated`
`spec.sources[].entries[].request`	`string`	Request is the UnblockRequest ("namespace/name") whose approval added the entry. Length: at most 300
`spec.sources[].entries[].type`	`string`	EntryType is how a structured list entry matches. Default: `exact` One of: `exact`, `wildcard`, `regex`
`spec.sources[].entries[].value`	`string`	Required. Value is the canonical form for Type: "ads.example.com" (exact), "*.example.com" (wildcard) or the RE2 expression without slashes (regex). Length: 1 to 1024
`spec.sources[].exclude`	`[]string`	Exclude switches off single entries of this source without editing it, also for URL and ConfigMap sources: each value is a rule as the source's format normalises it ("ads.example.com" for a hosts line "0.0.0.0 ads.example.com", "\|\|ads.example.com^", "/regex/"), as GET /blocklists/{namespace}/{name}/sources/{source}/entries lists them. Excluded rules are not compiled; the exclusions survive refreshes, and values that match nothing in the current body are reported in status.sources[].staleExcludes. Items: at most 10000 List type: `set`
`spec.sources[].format`	`string`	ListFormat is the syntax of a blocklist source. Default: `auto` One of: `auto`, `hosts`, `domains`, `adblock`, `regex`
`spec.sources[].inline`	`[]string`
`spec.sources[].name`	`string`
`spec.sources[].subdomains`	`boolean`	Subdomains makes the hosts and plain-domain entries of this source match their subdomains too, for lists published as "domains with subdomains". Adblock and wildcard rules are not affected.
`spec.sources[].url`	`string`

Status

BlockListStatus is the observed state of a block list.

Field	Type	Description
`status.conditions`	`[]Condition`	List type: `map`, keyed by `type`
`status.entries`	`integer`
`status.invalid`	`integer`
`status.lastFetched`	`string`	Format: `date-time`
`status.observedGeneration`	`integer`	Format: `int64`
`status.ruleCount`	`integer`
`status.sources`	`[]object`
`status.sources[].digest`	`string`	Digest is the sha256 of the fetched body; replicas pull by digest from the leader (decision D15).
`status.sources[].enabled`	`boolean`	Enabled is false for a source switched off with spec.sources[].enabled and absent otherwise. A disabled source keeps the digest, etag, lastFetched and counts of its last fetch and reports no error; status.entries leaves it out.
`status.sources[].entries`	`integer`
`status.sources[].error`	`string`
`status.sources[].etag`	`string`
`status.sources[].excluded`	`integer`	Excluded counts the entries of this source that are switched off (spec.sources[].exclude hits, or entries with enabled: false); they are not in Entries.
`status.sources[].invalid`	`integer`
`status.sources[].lastFetched`	`string`	Format: `date-time`
`status.sources[].name`	`string`	Required.
`status.sources[].staleExcludes`	`[]string`	StaleExcludes are spec.sources[].exclude values that match no rule of the current body (at most 50): the list dropped the entry, or the value is not written the way the source's format normalises it.
`status.unsupported`	`integer`	Unsupported counts valid rules this version parses but does not apply: modifiers such as $important and $badfilter, mid-pattern wildcards, hosts rewrites.

Example

config/samples/kudurru.io_v1alpha1_blocklist.yaml:

apiVersion: kudurru.io/v1alpha1
kind: BlockList
metadata:
  name: default-ads
  namespace: dns
spec:
  mode: block
  sources:
    - url: https://big.oisd.nl/
      format: auto
  refreshInterval: 24h