GuideNetworking

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:

src/K8S/Shop/Manifest/ApiService.phnsrc/K8S/Shop/Manifest/ApiService.php
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

src/K8S/Gateway/Manifest/PlatformGateway.phnsrc/K8S/Gateway/Manifest/PlatformGateway.php
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:

src/K8S/Gateway/Manifest/HttpsRedirectRoute.phnsrc/K8S/Gateway/Manifest/HttpsRedirectRoute.php
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

src/K8S/Shop/Manifest/ApiHTTPRoute.phnsrc/K8S/Shop/Manifest/ApiHTTPRoute.php
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:

src/K8S/Shop/Manifest/ApiHTTPRoute.phnsrc/K8S/Shop/Manifest/ApiHTTPRoute.php
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');
}
Renderedbin/console k8s:render:apps gateway shop
# 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:

src/K8S/Shop/Manifest/ApiIngress.phnsrc/K8S/Shop/Manifest/ApiIngress.php
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.

Next