/ 
IO-K8s-1.108
⭐ Starred 0 / IO::K8s::Role::MiddlewareBuilder

NAME

IO::K8s::Role::MiddlewareBuilder - Role for building Traefik middleware configuration

VERSION

version 1.108

SYNOPSIS

package My::TraefikMiddleware;
use IO::K8s::APIObject
    api_version     => 'traefik.io/v1alpha1',
    resource_plural => 'middlewares';
with 'IO::K8s::Role::MiddlewareBuilder';

package main;
my $k8s = IO::K8s->new(with => ['IO::K8s::Traefik']);
my $mw = $k8s->new_object('Middleware',
    metadata => { name => 'api-limits', namespace => 'default' },
);
$mw->rate_limit(average => 100, burst => 200)
   ->strip_prefix('/api')
   ->redirect_https;

DESCRIPTION

This role provides the fluent Traefik HTTP middleware builders documented in the README's Traefik section. Each method writes the corresponding block under the spec key Traefik's Middleware CRD expects, so the chain mirrors what a user would compose in YAML.

It applies to the HTTP Middleware kind only. Traefik's TCP middleware is a different, much smaller schema and honours none of these blocks, so it has a role of its own -- IO::K8s::Role::MiddlewareTCPBuilder, which IO::K8s::Traefik::V1alpha1::MiddlewareTCP composes.

Each setter either replaces or extends its target block:

  • rate_limit, basic_auth, strip_prefix, redirect_https overwrite the corresponding spec key each time.

  • add_request_header / add_response_header accumulate entries under the same headers parent block -- chained calls on the same parent append rather than replace.

Apply this role to any class whose spec field is the Traefik Middleware wire schema. The bundled Traefik CRD IO::K8s::Traefik::V1alpha1::Middleware is the obvious target, but the role composes on custom CRD classes too.

rate_limit

$mw->rate_limit(average => $n, burst => $n, period => $duration);

Configures the Traefik rateLimit middleware. average is the allowed average request rate and burst the maximum instantaneous queue depth; period is the averaging window and is optional. Only values Perl treats as true appear in the resulting spec.rateLimit hash, so an empty call or falsey values such as 0 and '' write {} rather than a populated block. Returns $self for chaining.

$mw->rate_limit(average => 100, burst => 200, period => '1s');

basic_auth

$mw->basic_auth(secret => $name, realm => $string);

Configures the Traefik basicAuth middleware. secret is the name of a Kubernetes Secret containing the htpasswd file; realm is the authentication realm shown to the user (optional). Returns $self for chaining.

$mw->basic_auth(secret => 'admins', realm => 'Admin Area');

strip_prefix

$mw->strip_prefix(@prefixes);

Configures the Traefik stripPrefix middleware to remove each prefix in @prefixes from incoming request paths. The prefixes are written as a single { prefixes => [...] } block, replacing any prior stripPrefix block. Pass an empty list to emit an empty stripPrefix.prefixes array. Returns $self for chaining.

$mw->strip_prefix('/api', '/v1');

redirect_https

$mw->redirect_https;

Configures the Traefik redirectScheme middleware to issue a permanent 301 redirect from the current listener to https. The wire block is { scheme => 'https', permanent => 1 }. Returns $self for chaining.

add_request_header

$mw->add_request_header($key, $value);

Adds a header that Traefik will inject into every request as it forwards to the upstream backend. Writes the spec.headers.customRequestHeaders.$key = $value shape. If the same $key is added twice the last value wins. Returns $self for chaining.

$mw->add_request_header('X-Forwarded-User', 'anonymous');

add_response_header

$mw->add_response_header($key, $value);

Adds a header that Traefik will inject into every response as it returns to the client. Writes the spec.headers.customResponseHeaders.$key = $value shape. If the same $key is added twice the last value wins. Returns $self for chaining.

$mw->add_response_header('X-Frame-Options', 'DENY');

SEE ALSO

IO::K8s::Traefik, IO::K8s::Role::MiddlewareTCPBuilder, IO::K8s::Role::SpecBuilder, IO::K8s::APIObject

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/pplu/io-k8s-p5/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHORS

  • Torsten Raudssus <getty@cpan.org>

  • Jose Luis Martinez Torres <jlmartin@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2018-2026 by Jose Luis Martinez Torres <jlmartin@cpan.org>.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004