@intentius/chant-lexicon-k3s 0.44.3

package/dist/okf/types/Registries.md

@@ -0,0 +1,14 @@
+---
+type: resource-type
+title: Registries
+description: k3s resource type K3s::Registries
+name: Registries
+lexicon: k3s
+resource_type: K3s::Registries
+---
+`K3s::Registries`, a resource type of the k3s lexicon.
+
+## Properties
+
+- `configs` (`Record<string, RegistryConfig>`, optional): Registry endpoint to auth/TLS configuration
+- `mirrors` (`Record<string, Mirror>`, optional): Registry name (or wildcard) to mirror configuration

package/dist/okf/types/Server.md

@@ -0,0 +1,122 @@
+---
+type: resource-type
+title: Server
+description: k3s resource type K3s::Server
+name: Server
+lexicon: k3s
+resource_type: K3s::Server
+---
+`K3s::Server`, a resource type of the k3s lexicon.
+
+## Properties
+
+- `advertise-address` (`string`, optional): (listener) IPv4/IPv6 address that apiserver uses to advertise to members of the cluster (default: node-external-ip/node-ip)
+- `advertise-port` (`number`, optional): (listener) Port that apiserver uses to advertise to members of the cluster (default: https-listen-port)
+- `agent-token-file` (`string`, optional): (cluster) File containing the agent secret
+- `alsologtostderr` (`boolean`, optional): (logging) Log to standard error as well as file (if set)
+- `bind-address` (`string`, optional): (listener) bind address (default: 0.0.0.0)
+- `cluster-cidr` (`string | string[]`, optional): (networking) IPv4/IPv6 network CIDRs to use for pod IPs (default: 10.42.0.0/16)
+- `cluster-dns` (`string | string[]`, optional): (networking) IPv4/IPv6 Cluster IP for coredns service. Should be in your service-cidr range (default: 10.43.0.10)
+- `cluster-domain` (`string`, optional): (networking) Cluster Domain (default: cluster.local)
+- `cluster-init` (`boolean`, optional): (cluster) Initialize a new cluster using embedded Etcd
+- `cluster-reset` (`boolean`, optional): (cluster) Forget all peers and become sole member of a new cluster
+- `cluster-reset-restore-path` (`string`, optional): (db) Path to snapshot file to be restored
+- `container-runtime-endpoint` (`string`, optional): (agent/runtime) Disable embedded containerd and use the CRI socket at the given path; when used with --docker this sets the docker socket path
+- `data-dir` (`string`, optional): (data) Folder to hold state default /var/lib/rancher/ or ${HOME}/.rancher/ if not root
+- `datastore-cafile` (`string`, optional): (db) TLS Certificate Authority file used to secure datastore backend communication
+- `datastore-certfile` (`string`, optional): (db) TLS certification file used to secure datastore backend communication
+- `datastore-endpoint` (`string`, optional): (db) Specify etcd, NATS, MySQL, Postgres, or SQLite (default) data source name
+- `datastore-keyfile` (`string`, optional): (db) TLS key file used to secure datastore backend communication
+- `debug` (`boolean`, optional): (logging) Turn on debug logs
+- `default-local-storage-path` (`string`, optional): (storage) Default local storage path for local provisioner storage class
+- `default-runtime` (`string`, optional): (agent/runtime) Set the default runtime in containerd
+- `disable` (`string | string[]`, optional): (components) Do not deploy packaged components and delete any deployed components (valid values: )
+- `disable-cloud-controller` (`boolean`, optional): (components) Disable default cloud controller manager
+- `disable-default-registry-endpoint` (`boolean`, optional): (agent/containerd) Disables containerd's fallback default registry endpoint when a mirror is configured for that registry
+- `disable-helm-controller` (`boolean`, optional): (components) Disable Helm controller
+- `disable-kube-proxy` (`boolean`, optional): (components) Disable running kube-proxy
+- `disable-network-policy` (`boolean`, optional): (components) Disable default network policy controller
+- `disable-scheduler` (`boolean`, optional): (components) Disable Kubernetes default scheduler
+- `docker` (`boolean`, optional): (agent/runtime) (experimental) Use cri-dockerd instead of containerd
+- `egress-selector-mode` (`string`, optional): (networking) One of 'agent', 'cluster', 'pod', 'disabled' (default: agent)
+- `embedded-registry` (`boolean`, optional): (components) Enable embedded distributed container registry; requires use of embedded containerd; when enabled agents will also listen on the supervisor port
+- `enable-pprof` (`boolean`, optional): (experimental) Enable pprof endpoint on supervisor port
+- `etcd-arg` (`string | string[]`, optional): (flags) Customized flag for etcd process
+- `etcd-disable-snapshots` (`boolean`, optional): (db) Disable automatic etcd snapshots
+- `etcd-expose-metrics` (`boolean`, optional): (db) Expose etcd metrics to client interface
+- `etcd-s3` (`boolean`, optional): (db) Enable backup to S3
+- `etcd-s3-access-key` (`string`, optional): (db) S3 access key
+- `etcd-s3-bucket` (`string`, optional): (db) S3 bucket name
+- `etcd-s3-bucket-lookup-type` (`string`, optional): (db) S3 bucket lookup type, one of 'auto', 'dns', 'path'; default is 'auto' if not set
+- `etcd-s3-config-secret` (`string`, optional): (db) Name of secret in the kube-system namespace used to configure S3, if etcd-s3 is enabled and no other etcd-s3 options are set
+- `etcd-s3-endpoint` (`string`, optional): (db) S3 endpoint url (default: s3.amazonaws.com)
+- `etcd-s3-endpoint-ca` (`string`, optional): (db) S3 custom CA cert to connect to S3 endpoint
+- `etcd-s3-folder` (`string`, optional): (db) S3 folder
+- `etcd-s3-insecure` (`boolean`, optional): (db) Disables S3 over HTTPS
+- `etcd-s3-proxy` (`string`, optional): (db) Proxy server to use when connecting to S3, overriding any proxy-releated environment variables
+- `etcd-s3-region` (`string`, optional): (db) S3 region / bucket location (optional) (default: us-east-1)
+- `etcd-s3-retention` (`number`, optional): (db) S3 retention limit
+- `etcd-s3-secret-key` (`string`, optional): (db) S3 secret key
+- `etcd-s3-session-token` (`string`, optional): (db) S3 session token
+- `etcd-s3-skip-ssl-verify` (`boolean`, optional): (db) Disables S3 SSL certificate validation
+- `etcd-s3-timeout` (`string`, optional): (db) S3 timeout
+- `etcd-snapshot-compress` (`boolean`, optional): (db) Compress etcd snapshot
+- `etcd-snapshot-dir` (`string`, optional): (db) Directory to save db snapshots. (default: ${data-dir}/server/db/snapshots)
+- `etcd-snapshot-name` (`string`, optional): (db) Set the base name of etcd snapshots, appended with UNIX timestamp (default: etcd-snapshot)
+- `etcd-snapshot-reconcile-interval` (`string`, optional): (db) Snapshot reconcile interval
+- `etcd-snapshot-retention` (`number`, optional): (db) Number of snapshots to retain
+- `etcd-snapshot-schedule-cron` (`string`, optional): (db) Snapshot interval time in cron spec. eg. every 5 hours '0 */5 * * *' (default: 0 */12 * * *)
+- `flannel-backend` (`string`, optional): (networking) Backend (valid values: 'none', 'vxlan', 'host-gw', 'wireguard-native' (default: vxlan)
+- `flannel-cni-conf` (`string`, optional): (agent/networking) Override default flannel cni config file
+- `flannel-conf` (`string`, optional): (agent/networking) Override default flannel config file
+- `flannel-external-ip` (`boolean`, optional): (networking) Use node external IP addresses for Flannel traffic
+- `flannel-iface` (`string`, optional): (agent/networking) Override default flannel interface
+- `flannel-ipv6-masq` (`boolean`, optional): (networking) Enable IPv6 masquerading for pod
+- `helm-controller-arg` (`string | string[]`, optional): (flags) Customized flag for helm-controller process
+- `https-listen-port` (`number`, optional): (listener) HTTPS listen port (default: 6443)
+- `image-credential-provider-bin-dir` (`string`, optional): (agent/node) The path to the directory where credential provider plugin binaries are located (default: /var/lib/rancher/credentialprovider/bin)
+- `image-credential-provider-config` (`string`, optional): (agent/node) The path to the credential provider plugin config file (default: /var/lib/rancher/credentialprovider/config.yaml)
+- `image-service-endpoint` (`string`, optional): (agent/runtime) Disable embedded containerd image service and use remote image service socket at the given path. If not specified, defaults to --container-runtime-endpoint.
+- `kube-apiserver-arg` (`string | string[]`, optional): (flags) Customized flag for kube-apiserver process
+- `kube-cloud-controller-manager-arg` (`string | string[]`, optional): (flags) Customized flag for kube-cloud-controller-manager process
+- `kube-controller-manager-arg` (`string | string[]`, optional): (flags) Customized flag for kube-controller-manager process
+- `kube-proxy-arg` (`string | string[]`, optional): (agent/flags) Customized flag for kube-proxy process
+- `kube-scheduler-arg` (`string | string[]`, optional): (flags) Customized flag for kube-scheduler process
+- `kubelet-arg` (`string | string[]`, optional): (agent/flags) Customized flag for kubelet process
+- `lb-server-port` (`number`, optional): (agent/node) Local port for supervisor client load-balancer. If the supervisor and apiserver are not colocated an additional port 1 less than this port will also be used for the apiserver client load-balancer. (default: 6444)
+- `log` (`string`, optional): (logging) Log to file
+- `node-external-dns` (`string | string[]`, optional): (agent/networking) external DNS addresses to advertise for node
+- `node-external-ip` (`string | string[]`, optional): (agent/networking) IPv4/IPv6 external IP addresses to advertise for node
+- `node-internal-dns` (`string | string[]`, optional): (agent/networking) internal DNS addresses to advertise for node
+- `node-ip` (`string | string[]`, optional): (agent/networking) IPv4/IPv6 addresses to advertise for node
+- `node-label` (`string | string[]`, optional): (agent/node) Registering and starting kubelet with set of labels
+- `node-name` (`string`, optional): (agent/node) Node name
+- `node-taint` (`string | string[]`, optional): (agent/node) Registering kubelet with set of taints
+- `nonroot-devices` (`boolean`, optional): (agent/containerd) Allows non-root pods to access devices by setting device_ownership_from_security_context=true in the containerd CRI config
+- `pause-image` (`string`, optional): (agent/runtime) Customized pause image for containerd or docker sandbox (default: rancher/mirrored-pause:3.10.2)
+- `prefer-bundled-bin` (`boolean`, optional): (experimental) Prefer bundled userspace binaries over host binaries
+- `private-registry` (`string`, optional): (agent/runtime) Private registry configuration file
+- `protect-kernel-defaults` (`boolean`, optional): (agent/node) Kernel tuning behavior. If set, error if kernel tunables are different than kubelet defaults.
+- `resolv-conf` (`string`, optional): (agent/networking) Kubelet resolv.conf file
+- `rootless` (`boolean`, optional): (experimental) Run rootless
+- `secrets-encryption` (`boolean`, optional): Enable secret encryption at rest
+- `secrets-encryption-provider` (`string`, optional): (experimental) Secret encryption provider (valid values: 'aescbc', 'secretbox') (default: aescbc)
+- `selinux` (`boolean`, optional): (agent/node) Enable SELinux in containerd
+- `server` (`string`, optional): (cluster) Server to connect to, used to join a cluster
+- `service-cidr` (`string | string[]`, optional): (networking) IPv4/IPv6 network CIDRs to use for service IPs (default: 10.43.0.0/16)
+- `service-node-port-range` (`string`, optional): (networking) Port range to reserve for services with NodePort visibility (default: 30000-32767)
+- `servicelb-namespace` (`string`, optional): (networking) Namespace of the pods for the servicelb component (default: kube-system)
+- `snapshotter` (`string`, optional): (agent/runtime) Override default containerd snapshotter
+- `supervisor-metrics` (`boolean`, optional): (experimental/components) Enable serving internal metrics on the supervisor port; when enabled agents will also listen on the supervisor port
+- `system-default-registry` (`string`, optional): (agent/runtime) Private registry to be used for all system images
+- `tls-san` (`string | string[]`, optional): (listener) Add additional hostnames or IPv4/IPv6 addresses as Subject Alternative Names on the server TLS cert
+- `tls-san-security` (`boolean`, optional): (listener) Protect the server TLS cert by refusing to add Subject Alternative Names not associated with the kubernetes apiserver service, server nodes, or values of the tls-san option (default: true) (default: true)
+- `token-file` (`string`, optional): (cluster) File containing the token
+- `v` (`number`, optional): (logging) Number for the log level verbosity
+- `vmodule` (`string`, optional): (logging) Comma-separated list of FILE_PATTERN=LOG_LEVEL settings for file-filtered logging
+- `vpn-auth` (`string`, optional): (agent/networking) (experimental) Credentials for the VPN provider. It must include the provider name and join key in the format name=<vpn-provider>,joinKey=<key>[,controlServerURL=<url>][,extraArgs=<args>]
+- `vpn-auth-file` (`string`, optional): (agent/networking) (experimental) File containing credentials for the VPN provider. It must include the provider name and join key in the format name=<vpn-provider>,joinKey=<key>[,controlServerURL=<url>][,extraArgs=<args>]
+- `with-node-id` (`boolean`, optional): (agent/node) Append id to node name
+- `write-kubeconfig` (`string`, optional): (client) Write kubeconfig for admin client to this file
+- `write-kubeconfig-group` (`string`, optional): (client) Write kubeconfig with this group
+- `write-kubeconfig-mode` (`string`, optional): (client) Write kubeconfig with this mode

package/dist/package-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env tsx
+export {};
+//# sourceMappingURL=package-cli.d.ts.map

package/dist/package-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-cli.d.ts","sourceRoot":"","sources":["../src/package-cli.ts"],"names":[],"mappings":""}

package/dist/plugin.d.ts

@@ -0,0 +1,8 @@
+import type { LexiconPlugin } from "@intentius/chant/lexicon";
+/**
+ * k3s lexicon plugin.
+ *
+ * Implements all required LexiconPlugin lifecycle methods.
+ */
+export declare const k3sPlugin: LexiconPlugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AAe7F;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,aA4GvB,CAAC"}

package/dist/serializer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * k3s config YAML serializer.
+ *
+ * Emits the files k3s consumes verbatim — the walk-away artifacts that
+ * justify a lexicon here at all (#1600):
+ *
+ *   K3s::Server / K3s::Agent → config.yaml   (`k3s server --config <file>`)
+ *   K3s::Registries          → registries.yaml
+ *
+ * One document per declared entity: the first config is the primary
+ * output, every further entity lands in files[] keyed `<name>.config.yaml`
+ * / `<name>.registries.yaml`. A config.yaml's keys are exactly the CLI
+ * flag names, so the emitted file diffs cleanly against any hand-written
+ * one and `k3s check-config` style tooling sees nothing unusual.
+ *
+ * ## Ownership rides node-label (#1603)
+ *
+ * config.yaml has no free-form metadata channel, but `node-label` is a
+ * first-class key on both server and agent and lands on the registered
+ * Node as ordinary Kubernetes labels. When a build carries ownership,
+ * the serializer appends the chant label pair to `node-label` — readable
+ * back through any kubectl against the cluster, and inert to k3s itself.
+ * An author's own label with the same key wins.
+ *
+ * ## What never appears
+ *
+ * `token` / `agent-token` literals are not part of the typed surface
+ * (#1601), and K3SC001 fails the build if one arrives through untyped
+ * props anyway. The file k3s reads secrets from is the file's business
+ * (`token-file`), not the artifact's.
+ */
+import type { Serializer } from "@intentius/chant/serializer";
+export declare const SERVER_TYPE = "K3s::Server";
+export declare const AGENT_TYPE = "K3s::Agent";
+export declare const REGISTRIES_TYPE = "K3s::Registries";
+export declare const k3sSerializer: Serializer;
+//# sourceMappingURL=serializer.d.ts.map

package/dist/serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AAMlG,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,UAAU,eAAe,CAAC;AACvC,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAkHjD,eAAO,MAAM,aAAa,EAAE,UAkC3B,CAAC"}

package/dist/skills/chant-k3s.md

@@ -0,0 +1,90 @@
+---
+skill: chant-k3s
+description: Declare k3s host configuration — server/agent config.yaml and registries.yaml — as typed chant source
+user-invocable: true
+---
+
+# k3s with chant
+
+The k3s lexicon declares the files k3s itself consumes: `config.yaml` for
+`k3s server` / `k3s agent`, and `registries.yaml` for the embedded
+containerd. The emitted files are exactly what the native tool accepts —
+drop them at `/etc/rancher/k3s/` (or pass `--config`) and chant is nowhere
+in sight.
+
+Config keys are the CLI flag names, verbatim. If `k3s server --help` shows
+`--write-kubeconfig-mode`, the declaration key is `"write-kubeconfig-mode"`.
+Quoted kebab-case keys are normal here.
+
+## Declaring a server
+
+```typescript
+import { Server } from "@intentius/chant-lexicon-k3s";
+
+export const controlPlane = new Server({
+  "cluster-init": true,                      // embedded etcd, first node
+  "tls-san": ["10.0.0.10", "cp.example.internal"],
+  "write-kubeconfig-mode": "0600",           // wider than 0644 trips K3S104
+  disable: ["traefik"],
+});
+```
+
+## Declaring an agent
+
+```typescript
+import { Agent } from "@intentius/chant-lexicon-k3s";
+
+export const worker = new Agent({
+  server: "https://cp.example.internal:6443", // required — K3S103 without it
+  "token-file": "/etc/rancher/k3s/agent-token",
+});
+```
+
+## The token boundary
+
+There is no `token` property, on purpose. The join secret reaches the node
+as a file (`token-file`, `agent-token-file`) or as `K3S_TOKEN` /
+`K3S_TOKEN_FILE` in the installer's environment — never as a value in
+source. A literal that arrives through raw props anyway fails K3S001 at
+lint and K3S101 at build. The same wall covers `etcd-s3-secret-key` and
+`etcd-s3-session-token`; use `etcd-s3-config-secret` (a Secret on the
+cluster) for snapshot-store credentials.
+
+## Private registries
+
+```typescript
+import { Mirror, Registries, RegistryConfig, RegistryTLS } from "@intentius/chant-lexicon-k3s";
+
+export const registries = new Registries({
+  mirrors: {
+    "docker.io": new Mirror({ endpoint: ["https://mirror.internal:5000"] }),
+  },
+  configs: {
+    "mirror.internal:5000": new RegistryConfig({
+      tls: new RegistryTLS({ ca_file: "/etc/ssl/certs/mirror-ca.pem" }),
+    }),
+  },
+});
+```
+
+Literal `auth.password` / `auth.token` fail K3S102; `insecure_skip_verify`
+warns via K3S105 — pin the CA instead.
+
+## Output shape
+
+One file per declared entity. The first Server/Agent config is the primary
+build output; further configs land beside it as `<name>.config.yaml`, and
+a Registries entity as `registries.yaml`. A build carrying an ownership
+marker stamps it into `node-label`, so the registered Node is attributable
+with any kubectl.
+
+## Rules
+
+| Rule | Severity | What it catches |
+|---|---|---|
+| K3S001 | error | literal `token` / `agent-token` in source |
+| K3S101 | error | a literal secret reaching the build (token, etcd S3 keys) |
+| K3S102 | error | literal registry credentials in registries.yaml |
+| K3S103 | error | an Agent with no `server` to join |
+| K3S104 | warning | kubeconfig written wider than 0644 |
+| K3S105 | warning | registry TLS verification disabled |

package/dist/spec/fetch.d.ts

@@ -0,0 +1,39 @@
+/**
+ * k3s CLI flag-definition fetching — downloads the pinned Go sources that
+ * define the server and agent flag surfaces, and caches them locally.
+ *
+ * k3s publishes no JSON Schema for config.yaml. The config file's keys ARE
+ * the CLI flag names ("Every flag can be a config key", docs.k3s.io), and
+ * the flags are defined as urfave/cli struct literals in pkg/cli/cmds/.
+ * Those literals carry name, usage, default and hidden-ness, so the tagged
+ * source tree is the machine-readable spec (#1599) — the same channel the
+ * k3s binary itself is built from, pinned the same way k3d pins its
+ * schema.json.
+ */
+/**
+ * Pinned upstream k3s release.
+ *
+ * Bump this constant (and re-generate) when adopting a newer k3s release.
+ * The acceptance test's rancher/k3s image tag derives from it (`+` → `-`).
+ */
+export declare const K3S_VERSION = "v1.36.3+k3s1";
+/** Docker image tag form of the pin: `+` is not legal in a tag. */
+export declare const K3S_IMAGE_TAG: string;
+/**
+ * Fetch all pinned spec files, keyed by filename.
+ */
+export declare function fetchSpecFiles(force?: boolean): Promise<Record<string, string>>;
+/**
+ * Fetch the spec as a Map<typeName, Buffer> compatible with the
+ * generatePipeline fetchSchemas callback.
+ *
+ * Single entry keyed "K3s::Config" whose buffer is a JSON envelope of the
+ * fetched files — the parse step needs them together to resolve flag-var
+ * references across files.
+ */
+export declare function fetchSchemas(force?: boolean): Promise<Map<string, Buffer>>;
+/**
+ * Clear the cached spec files.
+ */
+export declare function clearCache(): void;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/spec/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/spec/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH;;;;;GAKG;AACH,eAAO,MAAM,WAAW,iBAAiB,CAAC;AAE1C,mEAAmE;AACnE,eAAO,MAAM,aAAa,QAAgC,CAAC;AAqB3D;;GAEG;AACH,wBAAsB,cAAc,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAOrF;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAKhF;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC"}