Guide
Networking
Services, the Gateway API (a Gateway owned by the platform, routes owned by each service) and Ingress, with backends referenced by class.
Traffic reaches pods through Services, and from outside the cluster through the Gateway API or, on clusters without it, Ingress.
Services
A Service whose short name is a workload's selects that workload's pods (Manifests). The rest is the usual surface, typed:
namespace App\K8S\Shop\Manifest;
use Klass8s\Core\Service\AbstractService;
use Klass8s\Core\Service\Configurator\ServicePortsConfigurator;
use Klass8s\Core\Service\TrafficDistribution;
class ApiService extends AbstractService
{
const int PORT = 80;
static shortName(): string => 'api';
ports(ServicePortsConfigurator $ports): void => $ports->add(self::PORT, 'http')->setName('http');
trafficDistribution(): ?TrafficDistribution => TrafficDistribution::PreferSameZone;
}<?php
declare(strict_types=1);
namespace App\K8S\Shop\Manifest;
use Klass8s\Core\Service\AbstractService;
use Klass8s\Core\Service\Configurator\ServicePortsConfigurator;
use Klass8s\Core\Service\TrafficDistribution;
class ApiService extends AbstractService
{
public const int PORT = 80;
public static function shortName(): string
{
return 'api';
}
public function ports(ServicePortsConfigurator $ports): void
{
$ports->add(self::PORT, 'http')->setName('http');
}
public function trafficDistribution(): ?TrafficDistribution
{
return TrafficDistribution::PreferSameZone;
}
}ports() takes the Service port and the target, a number or a container port's name. type() receives a configurator with clusterIP() (the default), nodePort(), loadBalancer() and externalName(). trafficDistribution() defaults to PreferClose; return null to leave the field out. selector() replaces the derived selector when you need another.
The Gateway API
Klass8s has base classes for the Gateway API's resources (gateway.networking.k8s.io/v1): AbstractGatewayClass, AbstractGateway, AbstractHTTPRoute, AbstractGRPCRoute, AbstractBackendTLSPolicy and AbstractReferenceGrant. Their division of work matches the specification's: one App owns the Gateway, and every service owns its routes.
The Gateway
namespace App\K8S\Gateway\Manifest;
use Klass8s\GatewayApi\Enum\ProtocolType;
use Klass8s\GatewayApi\Gateway\AbstractGateway;
use Klass8s\GatewayApi\Gateway\Configurator\ListenersConfigurator;
use Klass8s\Manifest\MetadataConfigurator;
use Klass8s\Manifest\Reference\ManifestClassReference;
class PlatformGateway extends AbstractGateway
{
/** One HTTPS listener per public hostname; the list is a binding of config/services.yaml. */
__construct(private list<string> $publicHostnames) {}
static shortName(): string => 'platform';
gatewayClass(): string|ManifestClassReference => 'kgateway';
listeners(ListenersConfigurator $listeners): void {
$listeners->add('http')
->port(80)
->protocol(ProtocolType::HTTP)
->allowedRoutes()->fromAllNamespaces();
foreach ($this->publicHostnames as $hostname) {
$name = str_replace('.', '-', $hostname);
$listener = $listeners->add('https-'.$name)
->port(443)
->hostname($hostname)
->protocol(ProtocolType::HTTPS);
$listener->tls()->terminate()->certificateRef($name.'-tls'); // written by cert-manager
$listener->allowedRoutes()->fromAllNamespaces();
}
}
metadata(MetadataConfigurator $meta): void => $meta->annotations()->add('cert-manager.io/issuer', 'letsencrypt');
}<?php
declare(strict_types=1);
namespace App\K8S\Gateway\Manifest;
use Klass8s\GatewayApi\Enum\ProtocolType;
use Klass8s\GatewayApi\Gateway\AbstractGateway;
use Klass8s\GatewayApi\Gateway\Configurator\ListenersConfigurator;
use Klass8s\Manifest\MetadataConfigurator;
use Klass8s\Manifest\Reference\ManifestClassReference;
class PlatformGateway extends AbstractGateway
{
/**
* One HTTPS listener per public hostname; the list is a binding of config/services.yaml.
* @param list<string> $publicHostnames
*/
public function __construct(private array $publicHostnames) {}
public static function shortName(): string
{
return 'platform';
}
public function gatewayClass(): string|ManifestClassReference
{
return 'kgateway';
}
public function listeners(ListenersConfigurator $listeners): void
{
$listeners->add('http')
->port(80)
->protocol(ProtocolType::HTTP)
->allowedRoutes()->fromAllNamespaces();
foreach ($this->publicHostnames as $hostname) {
$name = str_replace('.', '-', $hostname);
$listener = $listeners->add('https-'.$name)
->port(443)
->hostname($hostname)
->protocol(ProtocolType::HTTPS);
$listener->tls()->terminate()->certificateRef($name.'-tls'); // written by cert-manager
$listener->allowedRoutes()->fromAllNamespaces();
}
}
public function metadata(MetadataConfigurator $meta): void
{
$meta->annotations()->add('cert-manager.io/issuer', 'letsencrypt');
}
}Each listener is a name, a port, a protocol and the routes it admits. TLS terminates with a certificate Secret named by certificateRef(), here one cert-manager writes, or by certificateRefFromClass() for a Secret that is a manifest of the build. allowedRoutes() narrows with fromSameNamespace(), fromSelector(), allowHTTPRoutes() and its siblings.
For an all-HTTPS setup, the plain-HTTP listener carries one route that redirects; Klass8s has it ready:
namespace App\K8S\Gateway\Manifest;
use Klass8s\GatewayApi\HTTPRoute\AbstractHttpsRedirectRoute;
// Every plain-HTTP request to the Gateway gets a redirect to https.
class HttpsRedirectRoute extends AbstractHttpsRedirectRoute
{
gatewayName(): string => 'gateway-'.PlatformGateway::shortName();
}<?php
declare(strict_types=1);
namespace App\K8S\Gateway\Manifest;
use Klass8s\GatewayApi\HTTPRoute\AbstractHttpsRedirectRoute;
// Every plain-HTTP request to the Gateway gets a redirect to https.
class HttpsRedirectRoute extends AbstractHttpsRedirectRoute
{
public function gatewayName(): string
{
return 'gateway-'.PlatformGateway::shortName();
}
}Routes
namespace App\K8S\Shop\Manifest;
use K8Schema\Collection\StringList;
use Klass8s\GatewayApi\Configurator\ParentRefsConfigurator;
use Klass8s\GatewayApi\Enum\HTTPMethod;
use Klass8s\GatewayApi\Enum\HTTPPathModifierType;
use Klass8s\GatewayApi\HTTPRoute\AbstractHTTPRoute;
use Klass8s\GatewayApi\HTTPRoute\Configurator\HTTPRouteRulesConfigurator;
class ApiHTTPRoute extends AbstractHTTPRoute
{
// bindings of config/services.yaml: the Gateway another App renders
__construct(private string $gatewayName, private string $gatewayNamespace) {}
static shortName(): string => 'api';
parentRefs(ParentRefsConfigurator $parentRefs): void
=> $parentRefs->add($this->gatewayName)->namespace($this->gatewayNamespace)->sectionName('https-shop-example-com');
hostnames(StringList $hostnames): void => $hostnames->add('shop.example.com');
}<?php
declare(strict_types=1);
namespace App\K8S\Shop\Manifest;
use K8Schema\Collection\StringList;
use Klass8s\GatewayApi\Configurator\ParentRefsConfigurator;
use Klass8s\GatewayApi\Enum\HTTPMethod;
use Klass8s\GatewayApi\Enum\HTTPPathModifierType;
use Klass8s\GatewayApi\HTTPRoute\AbstractHTTPRoute;
use Klass8s\GatewayApi\HTTPRoute\Configurator\HTTPRouteRulesConfigurator;
class ApiHTTPRoute extends AbstractHTTPRoute
{
// bindings of config/services.yaml: the Gateway another App renders
public function __construct(private string $gatewayName, private string $gatewayNamespace) {}
public static function shortName(): string
{
return 'api';
}
public function parentRefs(ParentRefsConfigurator $parentRefs): void
{
$parentRefs->add($this->gatewayName)->namespace($this->gatewayNamespace)->sectionName('https-shop-example-com');
}
public function hostnames(StringList $hostnames): void
{
$hostnames->add('shop.example.com');
}
}The rules cover what the Gateway API expresses: matches on paths, methods, headers and query parameters, weighted backends, timeouts, redirects, rewrites, header changes and mirroring:
rules(HTTPRouteRulesConfigurator $rules): void {
// 90 % of GET /api/v1 to the stable Service, 10 % to the canary
$api = $rules->add()->name('api-v1')->timeout('30s')->backendTimeout('10s');
$api->match()->pathPrefix('/api/v1')->method(HTTPMethod::GET);
$api->backendRef()->serviceClass(ApiService::class, ApiService::PORT)->weight(90);
$api->backendRef()->serviceClass(ApiCanaryService::class, ApiService::PORT)->weight(10);
// a retired prefix, redirected for good
$retired = $rules->add()->name('api-v0');
$retired->match()->pathPrefix('/api/v0');
$retired->filter()->requestRedirect(statusCode: 301, pathType: HTTPPathModifierType::ReplacePrefixMatch, pathValue: '/api/v1');
}public function rules(HTTPRouteRulesConfigurator $rules): void
{
// 90 % of GET /api/v1 to the stable Service, 10 % to the canary
$api = $rules->add()->name('api-v1')->timeout('30s')->backendTimeout('10s');
$api->match()->pathPrefix('/api/v1')->method(HTTPMethod::GET);
$api->backendRef()->serviceClass(ApiService::class, ApiService::PORT)->weight(90);
$api->backendRef()->serviceClass(ApiCanaryService::class, ApiService::PORT)->weight(10);
// a retired prefix, redirected for good
$retired = $rules->add()->name('api-v0');
$retired->match()->pathPrefix('/api/v0');
$retired->filter()->requestRedirect(statusCode: 301, pathType: HTTPPathModifierType::ReplacePrefixMatch, pathValue: '/api/v1');
}# File: /shop/api.h-t-t-p-route.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
annotations:
klass8s.dev/app: shop
klass8s.dev/deploy-priority: '0'
labels:
app.kubernetes.io/name: shop
app.kubernetes.io/component: api
name: shop-api
spec:
parentRefs:
-
name: gateway-platform
namespace: gateway
sectionName: https-shop-example-com
hostnames:
- shop.example.com
rules:
-
name: api-v1
timeouts:
request: 30s
backendRequest: 10s
matches:
-
path:
type: PathPrefix
value: /api/v1
method: GET
backendRefs:
-
name: shop-api
port: 80
weight: 90
-
name: shop-api-canary
port: 80
weight: 10
-
name: api-v0
matches:
-
path:
type: PathPrefix
value: /api/v0
filters:
-
type: RequestRedirect
requestRedirect:
statusCode: 301
path: { type: ReplacePrefixMatch, replacePrefixMatch: /api/v1 }serviceClass() names the Service by class, so a route cannot point at a Service that is not in the build; service('name', 8080) names one outside it. AbstractGRPCRoute has the same structure, matching on gRPC services and methods.
When routes and Gateways live in different namespaces, AbstractReferenceGrant allows references into a namespace, and AbstractBackendTLSPolicy configures TLS from the Gateway to a backend (reference).
Ingress
For clusters without the Gateway API:
namespace App\K8S\Shop\Manifest;
use Klass8s\Core\Ingress\AbstractIngress;
use Klass8s\Core\Ingress\Configurator\IngressRulesConfigurator;
use Klass8s\Core\Ingress\Http\PathType;
// For a cluster without the Gateway API.
class ApiIngress extends AbstractIngress
{
static shortName(): string => 'api';
ingressClassName(): ?string => 'nginx';
rules(IngressRulesConfigurator $rules): void {
$rules->addHttpRule('shop.example.com')
->addPath(PathType::Prefix, '/api')
->backend()->fromServiceClassAndPort(ApiService::class, ApiService::PORT);
}
}<?php
declare(strict_types=1);
namespace App\K8S\Shop\Manifest;
use Klass8s\Core\Ingress\AbstractIngress;
use Klass8s\Core\Ingress\Configurator\IngressRulesConfigurator;
use Klass8s\Core\Ingress\Http\PathType;
// For a cluster without the Gateway API.
class ApiIngress extends AbstractIngress
{
public static function shortName(): string
{
return 'api';
}
public function ingressClassName(): ?string
{
return 'nginx';
}
public function rules(IngressRulesConfigurator $rules): void
{
$rules->addHttpRule('shop.example.com')
->addPath(PathType::Prefix, '/api')
->backend()->fromServiceClassAndPort(ApiService::class, ApiService::PORT);
}
}The backend is a Service class again; fromServiceNameAndPort() names one outside the build, and withExternalApp() another App's.
If you are choosing, choose the Gateway API: its split between the platform's Gateway and each service's routes matches how Apps divide a project, and weighted backends or typed filters have no clean Ingress equivalent.