NAME

Langertha::Holmgang::Sim::Linux::Kubernetes - Kubernetes cluster behind kubectl on a simulated Linux server — stored resources, derived status

VERSION

version 0.001

SYNOPSIS

# from the Linux simulator: kubectl on a device with kubernetes state
my ( $out, $ok ) = Langertha::Holmgang::Sim::Linux::Kubernetes::kubectl( $dev, \@argv, $ctx, $stdin );

DESCRIPTION

A Kubernetes cluster (v1.30) as state of a Linux device (the device is the admin host with kubectl, cai-platform docs/entwurf-evals.md §3.3.1). The state is under kubernetes:

kubernetes:
  context: prod
  registry: [ registry.example.com/shop/api:1.4.2, … ]   # images available
  nodes: { node1: { ready: true } }
  storageclasses: { local-path: { provisioner: rancher.io/local-path, default: true } }
  namespaces:
    shop:
      deployments:
        api:
          replicas: 2
          generation: 3                 # counts every change of the template (rollout)
          selector: { app: api }
          template:
            labels: { app: api }
            containers:
              - name: api
                image: registry.example.com/shop/api:1.4.2
                ports: [8080]
                listens: [8080]          # where the process really listens (simulation only)
                needs_env: [DB_PASSWORD] # without these variables it crashes (simulation only)
                env: [ { name: DB_PASSWORD, secret: api-db, key: password, optional: true } ]
                readiness: { port: 8080, path: /healthz }
                volumes: [ { claim: data } ]
                privileged: false
                logs: [ "…" ]            # what the process writes when it starts
                crash_log: [ "…" ]       # what it writes when its environment is missing
      services: { api: { selector: { app: api }, ports: [ { port: 80, target: 8080 } ] } }
      secrets: { api-db: { password: "…" } }       # key -> value
      configmaps: { … }
      pvcs: { data: { storage_class: fast, size: 10Gi } }
      networkpolicies:
        deny-all: { pod_selector: {}, ingress: [] }
        allow-web: { pod_selector: { app: api }, ingress: [ { from: [ { app: web } ], ports: [8080] } ] }

Derived, not stored: pods (name from the deployment and a hash of the template), their status (ImagePullBackOff when the image is not in registry; CreateContainerConfigError when a non-optional secret key is missing; CrashLoopBackOff when a needs_env variable is missing; Pending when a PVC is not bound; Running 0/1 when the readiness probe targets a port nothing listens on), PVC status (Bound when the StorageClass exists, or, without one given, a default class is there), endpoints of a service (ready pods whose labels match) and reachability (kubectl exec POD -- curl|wget URL checks service, endpoints, target port and NetworkPolicies). Only what kubectl changes is stored — the rules check the cause in the state.

Commands: get (kinds and short names, -n, -A, -l, -o wide|yaml|json|name, --show-labels), describe, logs [--previous], get events, apply -f file (YAML, several documents), create -f, create secret generic … --from-literal, create storageclass by file, set image, set env (-c|--containers NAME[,…], without: all containers; --from=secret/NAME [--keys=a,b] [--prefix=P] as secretKeyRef, name upper case with _; NAME- removes; --list only reads), patch … -p JSON [--type merge|strategic|json], scale, label, rollout restart|status|undo, delete, exec … -- curl|wget, config current-context, cluster-info, version. Anything interactive (edit, exec -it … sh, port-forward) and anything else is a gap of the simulation. A deployment's generation counts every change of the template; kubectl rollout restart counts as well.

Further kinds in API form (stored without apiVersion, kind, name, namespace and status; rules check the API's fields): ingresses, ingressclasses, serviceaccounts, roles, rolebindings, clusterroles, clusterrolebindings, certificates, issuers, clusterissuers; derived and read only: certificaterequests, orders, challenges. Also in the state: ingress: { controller, address } (the cluster's controller), dns: { host: ip } (public names), cert_manager: { namespace, acme_servers }.

Ingress: the controller serves only ingresses of an IngressClass with its spec.controller (class from ingressClassName, the deprecated annotation or the default class); paths Exact, Prefix (element-wise), ImplementationSpecific (character prefix); backend through the service port as number or name; TLS from the host's secret, otherwise a fake certificate; http with TLS redirects (308). kubectl exec … -- curl|wget to a public name goes through the ingress (-k, -L, -I, -f, -w, -H Host:). Containers with derive_logs: ingress-nginx|cert-manager have the controller's log from the state.

cert-manager: a Certificate is ready when its issuer is there and ready (CA secret in the issuer's namespace, or for a ClusterIssuer in cert_manager.namespace, a known ACME server, HTTP-01 through a served class and a name from dns, DNS-01 with an existing secret); then its secret exists (pseudo-PEM with names and issuer). Ingress annotations cert-manager.io/cluster-issuer|issuer create Certificates (ingress-shim).

RBAC: kubectl auth can-i (--as, --as-group, --list) over Roles, ClusterRoles (built in: cluster-admin, admin, edit, view) and bindings (ServiceAccount with namespace, without: the binding's; groups; resourceNames; subresources such as pods/log); kubectl create serviceaccount|role|clusterrole|rolebinding|clusterrolebinding|secret tls; roleRef is immutable. A container with needs_rbac crashes when its ServiceAccount lacks a permission; when the ServiceAccount is missing, there are no pods (event FailedCreate).

Pure functions on the state, neutral.

kubectl

my ( $out, $ok ) = kubectl( $dev, \@argv, $ctx, $stdin );

pod_tool

my ( $out, $ok ) = pod_tool( $k, $ns, $pod, [ 'curl', '-s', 'http://api' ] );

curl, wget or openssl s_client from a pod: service, endpoints, NetworkPolicies, ingress controller (for public names).

tls_probe

my ( $text, $ok ) = tls_probe( $k, $host, $servername );

What openssl s_client -connect host:443 -servername … sees from the cluster's ingress controller: certificate (pseudo-PEM), subject, issuer, verification result.

x509

my ( $text, $ok ) = x509( $pem, \@options );

openssl x509 -noout -subject|-issuer|-dates|-enddate|-ext subjectAltName|-text on a pseudo-PEM of the simulation.

jsonpath

my ( $text, $err ) = jsonpath( $data, '{range .items[*]}{.metadata.name}{"\n"}{end}' );

Subset of kubectl JSONPath: text and {expression}; expressions .a.b, .data.tls\.crt, ['a.b'], [n], [*], [?(@.f=="v")] (also !=), ..name (recursive), literals {"\n"}, {range …}…{end}. Several matches are joined with spaces; lists and objects as JSON.

SUPPORT

Issues

Please report bugs and feature requests at https://github.com/Getty/langertha-holmgang/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

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

AUTHOR

Torsten Raudssus <torsten@raudssus.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.