Skip to content

Commit 0a13165

Browse files
rothgarrothgar
committed
feat: add llms.txt for better LLM usage
Adds the file to the root path for automatic discovery and helping LLMs discover endpoints and usage. Signed-off-by: Justin Garrison <justin.garrison@siderolabs.com>
1 parent 915ef76 commit 0a13165

1 file changed

Lines changed: 186 additions & 0 deletions

File tree

‎llms.txt‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Talos Linux Image Factory
2+
3+
The Image Factory builds and serves customized Talos Linux boot artifacts. Artifacts are parameterized by a **schematic** (a hash-identified YAML document describing customizations) and a **Talos Linux version**. The official instance is at `https://factory.talos.dev` (HTTP/OCI) and `https://pxe.talos.dev` (PXE).
4+
5+
## Core Concepts
6+
7+
**Schematic**: A YAML document that describes image customizations. Submitting one returns a stable SHA-256 ID. The same customizations always produce the same ID. The well-known default schematic (no customizations) has ID `376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba`.
8+
9+
**Version**: A Talos Linux release version string, e.g. `v1.5.0`. Use `GET /versions` to list available versions.
10+
11+
**Model**: The combination of a schematic ID and a Talos version. From a model you can derive any artifact type.
12+
13+
## Typical Workflow
14+
15+
1. POST a schematic → get back an ID
16+
2. GET `/versions` to find a version to target
17+
3. GET `/image/:schematic/:version/:path` to download an artifact
18+
19+
## HTTP API (`https://factory.talos.dev`)
20+
21+
**Authentication**: The official public instance (`factory.talos.dev`) does not require authentication. Self-hosted deployments may enable an auth provider, in which case all schematic and image endpoints require credentials (HTTP Basic Auth via htpasswd). If you receive a `401 Unauthorized`, check the deployment's authentication configuration. The `/versions`, `/version/:version/extensions/official`, `/version/:version/overlays/official`, `/secureboot/signing-cert.pem`, and `/oci/cosign/signing-key.pub` endpoints are typically public even when auth is enabled.
22+
23+
### POST /schematics
24+
25+
Create a schematic. Request body is YAML (or JSON). Returns `{"id": "<sha256>", "schematic": "<canonical-yaml>"}`.
26+
27+
```yaml
28+
customization:
29+
extraKernelArgs: # optional
30+
- vga=791
31+
meta: # optional, initial Talos META
32+
- key: 0xa
33+
value: "{}"
34+
systemExtensions:
35+
officialExtensions: # optional
36+
- siderolabs/gvisor
37+
- siderolabs/amd-ucode
38+
secureboot: # optional, SecureBoot images only
39+
includeWellKnownCertificates: true
40+
enrollKeys: force # off | manual | if-safe | force
41+
bootloader: sd-boot # optional: auto | sd-boot | dual-boot | grub
42+
embeddedMachineConfiguration: | # optional, YAML machine config docs
43+
apiVersion: v1alpha1
44+
kind: HostnameConfig
45+
hostname: my-host
46+
diskImage: # optional, disk images only
47+
sectorSize: 4096
48+
overlay: # optional, for SBC/overlay targets
49+
image: ghcr.io/siderolabs/sbc-raspberry-pi
50+
name: rpi_generic
51+
options:
52+
data: "mydata"
53+
```
54+
55+
### GET /schematics/:schematic
56+
57+
Retrieve schematic YAML by ID. Returns 404 if not found.
58+
59+
### GET /versions
60+
61+
List available Talos Linux versions. Returns a JSON array of version strings.
62+
63+
```json
64+
["v1.5.0","v1.5.1","v1.5.2"]
65+
```
66+
67+
### GET /version/:version/extensions/official
68+
69+
List official system extensions for a version. Returns array of `{name, ref, digest}`.
70+
71+
### GET /version/:version/overlays/official
72+
73+
List official overlays (e.g. SBC support) for a version. Returns array of `{name, image, ref, digest}`.
74+
75+
### GET /image/:schematic/:version/:path
76+
77+
Download a boot artifact. `:path` values:
78+
79+
| Path pattern | Description |
80+
|---|---|
81+
| `kernel-<arch>` | Raw kernel (e.g. `kernel-amd64`) |
82+
| `cmdline-<platform>-<arch>[-secureboot]` | Kernel command line |
83+
| `initramfs-<arch>.xz` | Initramfs (with extensions) |
84+
| `<platform>-<arch>[-secureboot].iso` | ISO image |
85+
| `<platform>-<arch>[-secureboot]-uki.efi` | UEFI UKI image |
86+
| `installer-<arch>[-secureboot].tar` | Metal installer OCI tar |
87+
| `<platform>-installer-<arch>[-secureboot].tar` | Platform-specific installer |
88+
| `metal-<arch>[-secureboot].raw.xz` | Raw disk image (metal) |
89+
| `aws-<arch>.raw.xz` | Raw disk image for AWS AMI import |
90+
| `gcp-<arch>.raw.tar.gz` | Raw disk image for GCE import |
91+
92+
`<arch>` is `amd64` or `arm64`. `<platform>` examples: `metal`, `aws`, `gcp`, `azure`, `vmware`.
93+
94+
Append `.sha256` or `.sha512` to any path to get a checksum file (Enterprise only).
95+
96+
### GET /talosctl/:version
97+
98+
List `talosctl` binary download URLs for a version (available from v1.11.0+).
99+
100+
### GET /talosctl/:version/:path
101+
102+
Download a `talosctl` binary. `:path` example: `talosctl-linux-amd64`.
103+
104+
### GET /secureboot/signing-cert.pem
105+
106+
Returns the PEM-encoded SecureBoot signing certificate for manual UEFI enrollment.
107+
108+
## PXE API (`https://pxe.talos.dev`)
109+
110+
### GET /pxe/:schematic/:version/:path
111+
112+
Returns an iPXE script that boots Talos Linux. `:path` is `<platform>-<arch>[-secureboot]`, e.g. `metal-amd64`.
113+
114+
Example iPXE chain URL to embed in firmware:
115+
```
116+
chain --replace --autofree https://pxe.talos.dev/pxe/376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba/v1.5.0/metal-${buildarch}
117+
```
118+
119+
## OCI Registry API (`factory.talos.dev`)
120+
121+
Pull installer images directly with `docker`/`crane`/`skopeo`:
122+
123+
```
124+
# Legacy form
125+
docker pull factory.talos.dev/installer/<schematic>:<version>
126+
docker pull factory.talos.dev/installer-secureboot/<schematic>:<version>
127+
128+
# Current form (preferred)
129+
docker pull factory.talos.dev/metal-installer/<schematic>:<version>
130+
docker pull factory.talos.dev/aws-installer/<schematic>:<version>
131+
132+
# latest tag resolves to latest stable (non-prerelease) version
133+
docker pull factory.talos.dev/metal-installer/<schematic>:latest
134+
```
135+
136+
### GET /oci/cosign/signing-key.pub
137+
138+
Returns the PEM-encoded public key used to sign installer images. Verify with:
139+
140+
```shell
141+
cosign verify --offline --insecure-ignore-tlog --insecure-ignore-sct \
142+
--key signing-key.pub factory.talos.dev/metal-installer/<schematic>:<version>
143+
```
144+
145+
## Enterprise-Only APIs
146+
147+
Requires Talos Enterprise Image Factory. Available from Talos v1.11.0+.
148+
149+
### GET /spdx/:schematic/:version/:arch
150+
151+
Returns an SPDX 2.3 JSON SBOM for the given schematic and version.
152+
153+
### GET /vex/:version/vex.json
154+
155+
Returns a VEX JSON document for vulnerability suppression.
156+
157+
### GET /scans/:schematic/:version/:arch/:report
158+
159+
Returns a vulnerability scan report. `:report` suffix: `.json`, `.table`, `.sarif`, `.cdx`.
160+
161+
## Examples
162+
163+
Download a default metal AMD64 ISO for Talos v1.7.0:
164+
```shell
165+
curl -LO https://factory.talos.dev/image/376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba/v1.7.0/metal-amd64.iso
166+
```
167+
168+
Create a schematic with an extension and download its installer image:
169+
```shell
170+
# 1. Create schematic
171+
curl -s -X POST https://factory.talos.dev/schematics \
172+
-H 'Content-Type: application/yaml' \
173+
--data-binary 'customization:
174+
systemExtensions:
175+
officialExtensions:
176+
- siderolabs/gvisor'
177+
# Returns: {"id":"<id>","schematic":"..."}
178+
179+
# 2. Pull installer
180+
docker pull factory.talos.dev/metal-installer/<id>:v1.7.0
181+
```
182+
183+
List extensions available for a version:
184+
```shell
185+
curl https://factory.talos.dev/version/v1.7.0/extensions/official
186+
```

0 commit comments

Comments
 (0)