ka2a documentation
Configuration reference
Developer preview. Not yet production ready. This page is rendered from docs/configuration-reference.md of the ka2a repository at revision 96fb45e5e5f6693e779837998c3aa9581d6a37f2. It describes the behavior of that revision.
Contents
This reference lists every flag of the ka2a command and every field of ka2a.Config.
The test TestConfigurationReferenceMatchesTheFlagsAndConfig (internal/cli, make verify)
compares it with the code. It fails when a flag or a field is missing here, when a listed
flag or field does not exist, or when the commands or the default of a flag differ. For the
full text of a command, run ka2a help <command>.
Environment
| Variable | Meaning |
|---|---|
KA2A_STATE_DIR | Default of --state-dir. |
Command-line flags
The column "Default" shows the value when you do not give the flag. "none" is an empty value. "varies" means that the commands have different defaults.
| Flag | Commands | Default | Meaning |
|---|---|---|---|
--allow-plaintext | run, send, task get, tasks list, task cancel | false | Permit a broker connection without TLS. Only the development profile permits it; use it only for a local development broker. |
--allow-plaintext-credentials | doctor, topics verify, topics provision | false | Permit SASL/PLAIN without TLS. Use it only for a local test broker. |
--brokers | doctor, topics verify, topics provision, run, send, task get, tasks list, task cancel | none | Comma-separated Kafka bootstrap brokers (host:port). The node commands need it. doctor checks the broker only with it. |
--budget-bytes | doctor, observe, snapshot export, serve-ui | 0 | Retained-state budget of the owner, for the storage checks. The default is the store default (1 GiB). |
--catalog | doctor, topics verify, topics acl-plan, init, topics provision, run, send, task get, tasks list, task cancel | none | Trusted catalog file (ka2a.catalog.v1). run, the request commands and topics acl-plan need it. doctor, init and the other topic commands use it to check the catalog or to find the mailbox topic. |
--consumer-group | topics acl-plan | none | Consumer group of the node for the ACL plan. The default is ka2a.owner.<domain>.<endpoint>, the default of Config.Kafka.ConsumerGroup. |
--context-id | send, tasks list | none | send: the A2A context ID to continue. tasks list: list only the tasks of this context. |
--cursor | observe, snapshot export | 0 | Continue the list of --list after this cursor. |
--dispatch | held release, held abandon | 0 | Inbound sequence number of the held dispatch row (the IN column of 'ka2a observe --list dispatch'). |
--domain | doctor, topics verify, topics acl-plan, init, topics provision, run, send, task get, tasks list, task cancel | none | Trust domain of the local endpoint. |
--drain-timeout | run, send, task get, tasks list, task cancel | 30s | Time limit of the drain at the stop. Unfinished work stays durable. |
--endpoint | doctor, topics verify, topics acl-plan, init, topics provision, run, send, task get, tasks list, task cancel, keys generate, keys public | none | Endpoint ID of the local endpoint. keys generate and keys public: the endpoint that the key signs for, as DOMAIN/ENDPOINT (required). |
--expiry-days | catalog validate | 30 | Warn about catalog keys that end within this many days without a replacement (0..3650). |
--force | snapshot export | false | Replace an existing file. |
--from | restore | none | Backup file from 'ka2a backup'. |
--history-length | task get | -1 | Most recent history messages to return. -1 returns all. |
--key-id | keys generate | none | Key ID of the new key in the catalog ([A-Za-z0-9][A-Za-z0-9._:-]{0,127}). Required. |
--list | observe, snapshot export | none | Show only this list, to page through it: operations, outbox, dispatch, rejections, incidents, partitions. |
--listen | serve-ui | 127.0.0.1:0 | Loopback address to listen on. Port 0 selects a free port. |
--log-level | run, send, task get, tasks list, task cancel | warn | Node diagnostics on stderr: off, error, warn or info. They never hold bodies or raw identifiers. |
--max-value-bytes | doctor, topics verify, topics provision | 1048576 | Largest record value; it sets the required max.message.bytes. |
--message-id | send | none | A2A message ID. The default is the --operation-id key, so a repeated command sends the same request; without a key it is a new UUID. |
--metrics-listen | run | none | Serve the node metrics in the Prometheus text format at http://ADDRESS/metrics. ADDRESS must be a loopback address (127.0.0.1, ::1 or localhost). Port 0 selects a free port. The default serves no metrics. |
--not-after | keys generate, keys public | none | End of the key window in the printed catalog entry (RFC 3339). The default is no end. |
--not-before | keys generate, keys public | none | Start of the key window in the printed catalog entry (RFC 3339). The default is the current time, truncated to the second. |
--note | quarantine release | none | How the state was reconciled (required, 1..1024 bytes). |
--operation | held abandon | none | Operation ID of a sent request that waits for its response or is held. Give --dispatch or --operation. |
--operation-id | send, task get, tasks list, task cancel | none | Operation key (lowercase UUIDv4). The same key with the same request returns the original operation. |
--operator | quarantine release | none | Name of the person or tool that decided (required, 1..128 bytes). |
--out | snapshot export, backup, keys generate | none | backup: the backup file to write; it must not exist. snapshot export: the snapshot file to write. keys generate: the key file to write; it must not exist, and others must not be able to read its directory. |
--output | version, doctor, observe, snapshot export, operation show, topics verify, topics acl-plan, serve-ui, init, topics provision, backup, restore, quarantine release, held release, held abandon, run, send, task get, tasks list, task cancel, keys public, catalog validate, catalog digest, keys generate | text | Output format: text or json. |
--page-size | observe, snapshot export, serve-ui, tasks list | varies | Largest number of items in a page. tasks list: 1..100, default 50. The other commands give their own default in ka2a help <command>. |
--page-token | tasks list | none | Token of the page to read, from the previous page. |
--peer | send, task get, tasks list, task cancel | none | Peer endpoint as DOMAIN/ENDPOINT. The catalog must grant the operation. Required. |
--principal | topics acl-plan | none | Kafka principal of the node, for example User:ka2a-a or User:CN=ka2a-a,O=example. Required. |
--print-token | serve-ui | auto | Print the login token to stderr: auto, always or never. |
--profile | doctor, topics verify, topics provision, run, send, task get, tasks list, task cancel | qualified | Declared durability profile: qualified or development. The node and the topic commands check the mailbox topic against it. |
--raw-ids | observe, snapshot export, operation show, held release, held abandon, send, task get, tasks list, task cancel | false | Show raw identifiers and digests. The default shows pseudonyms. Bodies are never shown. |
--reason | held release, held abandon | none | Reason token of the decision, recorded with the row ([a-z][a-z0-9_]{0,63}, required). |
--retention | doctor, topics verify, topics provision | 192h0m0s | Smallest accepted retention of the mailbox topic. |
--sasl-mechanism | doctor, topics verify, topics provision, run, send, task get, tasks list, task cancel | none | SASL mechanism: PLAIN, SCRAM-SHA-256 or SCRAM-SHA-512. |
--sasl-password-file | doctor, topics verify, topics provision, run, send, task get, tasks list, task cancel | none | File with the SASL password (mode 0600). The password is never a flag value. |
--sasl-username | doctor, topics verify, topics provision, run, send, task get, tasks list, task cancel | none | SASL user name. |
--show-result | send, task get, tasks list, task cancel | false | Also print the A2A result document. It can hold business data. |
--signing-key | doctor, init, run, send, task get, tasks list, task cancel | none | Signing key file of the local endpoint (ka2a.signing-key.v1, mode 0600). run and the request commands need it. doctor and init check it. |
--snapshot | serve-ui | none | Show this ka2a.snapshot/1 file instead of a state directory. |
--start-timeout | run, send, task get, tasks list, task cancel | 2m0s | Time limit of the node start: restart recovery and the mailbox check. The start does not wait for a broker: without one, the mailbox check stays unverified and the node admits work locally. |
--state | observe, snapshot export, tasks list | none | List only the tasks in this state, for example working or TASK_STATE_WORKING. |
--state-dir | doctor, observe, snapshot export, operation show, topics verify, topics acl-plan, serve-ui, init, topics provision, backup, restore, quarantine release, held release, held abandon, run, send, task get, tasks list, task cancel | none | State directory of the endpoint. The default is $KA2A_STATE_DIR. |
--strict | doctor, topics verify, topics provision, catalog validate | false | Count unverified broker settings as problems. catalog validate: count warnings as problems. |
--task-id | send | none | A2A task ID to continue. |
--text | send | none | Text of the message. Required. |
--timeout | doctor, topics verify, topics provision | 30s | Time limit of the broker requests. |
--tls | doctor, topics verify, topics provision, run, send, task get, tasks list, task cancel | false | Connect to the brokers with TLS. |
--tls-ca | doctor, topics verify, topics provision, run, send, task get, tasks list, task cancel | none | PEM file of the CA certificates for TLS. The default is the system pool. |
--tls-crl | doctor, topics verify, topics provision, run, send, task get, tasks list, task cancel | none | PEM (or one DER) file of the certificate revocation lists (CRL) of the broker chain. Needs --tls-ca: a CA certificate of that file must sign each list, and each list must be current (after its this update, before its next update). Each handshake refuses a broker chain that a list revokes (tls_failed), also through a revoked intermediate CA of the bundle. Delta lists, indirect lists and lists with an unknown critical extension are refused. At most 64 lists and 8 MiB. |
--tls-cert | doctor, topics verify, topics provision, run, send, task get, tasks list, task cancel | none | PEM file of the client certificate for mutual TLS: the leaf first, then the intermediate CAs. Needs --tls-key. The certificate must allow client authentication. |
--tls-key | doctor, topics verify, topics provision, run, send, task get, tasks list, task cancel | none | PEM file of the unencrypted private key of --tls-cert (mode 0600). The key is never a flag value and never appears in an output. |
--tls-server-name | doctor, topics verify, topics provision, run, send, task get, tasks list, task cancel | none | Server name for TLS verification. |
--token-file | serve-ui | none | Token file. The default is ui.token in the state directory. A snapshot file needs this flag. |
--topic | doctor, topics verify, topics provision | none | Mailbox topic. The default comes from the catalog entry of the endpoint. |
--ui-listen | run | none | Serve the read-only operational UI of this node on this loopback address. The UI shows the live broker connectivity of the node. The default serves no UI. |
--ui-print-token | run | auto | Print the UI login token to stderr: auto, always or never. |
--ui-token-file | run | none | UI token file. The default is ui.token in the state directory. |
--wait | send, task get, tasks list, task cancel | 30s | How long to wait for the response. 0 waits only for the broker stage. |
Flag rules
- A password is never a flag value. Give it in a file with mode 0600
(
--sasl-password-file). --tls-ca,--tls-crl,--tls-server-name,--tls-certand--tls-keyturn on TLS, also without--tls.--tls-certand--tls-keygo together (mutual TLS). The key file must be a regular file of the effective user with mode 0600, and the pair must match. A command that contacts the broker refuses a client certificate that is expired or not yet valid.doctorreportsbroker.client_certificate: a problem outside the validity period and a warning in the last 30 days.- With
--tls-crl,doctorreportsbroker.revocation_listswith the earliest next update of the lists:ok, or a warning when it is less than 24 hours away. A stale list is refused before broker contact.ka2a runshows the earliest next update of the lists in use in the line of an accepted reload, the run UI andka2a_revocation_lists_next_update_timestamp_seconds. - With mutual TLS, SASL is optional. Without SASL, the client certificate identifies the principal
(the broker maps its subject with
ssl.principal.mapping.rules). --allow-plaintext(node commands) permits a connection without TLS. Only thedevelopmentprofile accepts it.--allow-plaintext-credentials(administrative commands) permits SASL/PLAIN without TLS. Use it only for a local test broker.--metrics-listen,--ui-listenand--listenaccept only loopback addresses.ka2a runreads--tls-ca,--tls-crl,--tls-server-name,--tls-cert,--tls-keyand--sasl-password-fileagain onSIGHUPand reloads the broker credentials of the running node. The node checks the new material, also with one broker request to each bootstrap broker of--brokers, before it uses it; a refusal of any broker keeps the previous material. Each refusal line on stderr names its class. The other flags, the catalog and the signing key stay until a restart (production guide).
ka2a.Config
pkg/ka2a reads this configuration at Open. Zero values take the defaults.
| Field | Default | Meaning |
|---|---|---|
Config.Endpoint | required | The local endpoint (Domain and Name). The catalog must list it. |
Config.StateDir | required | The state directory. One process owns it. Open creates it with mode 0700. |
Config.CatalogFile | required | The trusted catalog (ka2a.catalog.v1): peers, routes, keys and grants. |
Config.SigningKeyFile | required | The Ed25519 signing key (ka2a.signing-key.v1, mode 0600). |
Config.Kafka | The broker connection. | |
Config.Kafka.Brokers | required | Bootstrap brokers (host:port). |
Config.Kafka.TLS | nil | TLS configuration. The node uses a clone. The qualified profile requires it. For mutual TLS, set Certificates (or GetClientCertificate); the library does not check the validity period of the client certificate at Open. Node.ReloadCredentials replaces the TLS configuration and the SASL user name and password of a running node, and refuses an expired client certificate, a configuration that turns off the verification of the broker certificate (InsecureSkipVerify) and a lower MinVersion. For the revocation lists of --tls-crl, set VerifyConnection to the method of ka2a.ParseBrokerRevocationLists(caPEM, crl, now) (production guide); a reload cannot remove it. |
Config.Kafka.RevocationListsNextUpdate | zero | Earliest next update of the revocation lists that Config.Kafka.TLS.VerifyConnection checks (BrokerRevocationLists.NextUpdate()). Information only: the node shows it in Status.Credentials.RevocationListsNextUpdate and ka2a_revocation_lists_next_update_timestamp_seconds; the check is the function. BrokerCredentials.RevocationListsNextUpdate replaces it at an accepted reload. |
Config.Kafka.SASL | nil | SASL credentials. |
Config.Kafka.SASL.Mechanism | SCRAM-SHA-512, SCRAM-SHA-256 or PLAIN. PLAIN needs TLS. | |
Config.Kafka.SASL.Username | SASL user name. It must not hold control characters. | |
Config.Kafka.SASL.Password | SASL password. The node never writes it to an error or a log. | |
Config.Kafka.AllowPlaintext | false | Permit a connection without TLS. The qualified profile refuses it. |
Config.Kafka.ConsumerGroup | ka2a.owner.<domain>.<endpoint> | The group of the one durable owner. Observers must use other groups. |
Config.Kafka.ClientID | ka2a | Prefix of the Kafka client IDs. |
Config.Kafka.FetchMaxWait | Kafka layer default | Longest wait of a fetch. |
Config.Kafka.SessionTimeout | Kafka layer default | Consumer group session timeout. |
Config.Kafka.HeartbeatInterval | Kafka layer default | Consumer group heartbeat interval. |
Config.Kafka.RebalanceTimeout | Kafka layer default | Consumer group rebalance timeout. |
Config.Kafka.CommitTimeout | Kafka layer default | Time limit of an offset commit. |
Config.Kafka.RevokeSettleTimeout | Kafka layer default | Time that a revoked partition gets to settle its accounted progress. |
Config.Kafka.DeliveryTimeout | Kafka layer default | Time limit of one record delivery. |
Config.Kafka.RequestTimeout | Kafka layer default | Time limit of one broker request. |
Config.Durability | qualified | Declared broker profile: qualified or development. |
Config.Limits | Bounds of records, dispatch and retained state. | |
Config.Limits.MaxValueBytes | 1 MiB | Largest record value. |
Config.Limits.MaxHeaderBytes | 16 KiB | Largest total of the record headers. |
Config.Limits.RetainedBytes | 1 GiB | Retained-state budget. A new admission that would exceed it fails with storage_pressure. |
Config.Limits.MaxDispatch | 32 | Handler calls that run at the same time. |
Config.Horizons | Signed admission horizons, the clock skew and the retention periods. | |
Config.Horizons.ClockSkew | 5 minutes | Accepted wall-clock skew. |
Config.Horizons.RequestHorizon | 24 hours | Longest signed request lifetime. |
Config.Horizons.ResponseHorizon | 8 days | Longest signed response lifetime. |
Config.Horizons.RequestDedupRetention | 8 days | Retention of request deduplication. At least the request horizon plus the skew. |
Config.Horizons.ResponseDedupRetention | 9 days | Retention of response deduplication. At least the response horizon plus the skew. |
Config.Horizons.ResultRetention | 8 days | How long a completed result stays available. |
Config.Horizons.TombstoneRetention | 8 days | How long a purged identity stays blocked. |
Config.Horizons.RejectionRetention | 8 days | How long a rejection disposition stays. |
Config.MirrorSession | false | Write the A2A contextId to the header ce_ka2asession. |
Config.PropagateRun | false | Write a submitted run ID to the header ce_ka2arun. The default drops it. |
Config.DrainTimeout | 30 seconds | Time limit of the drain of Run after its context ends. |
Config.WaitForBroker | false | The start of Run waits until a broker answers the mailbox check. |
Config.Observer | nil | Receives events through a bounded, lossy queue. Messaging never waits for it. |
Config.ObserverQueue | 1024 | Size of the observer queue. |
Config.Logger | nil (discard) | Receives classified diagnostics. It never receives bodies, context IDs, run IDs or key material. |