Documentation
¶
Overview ¶
Package client implements image factory HTTP API client.
Index ¶
- func IsHTTPErrorCode(err error, code int) bool
- func IsInvalidSchematicError(err error) bool
- func WithHeaders(headers map[string]string) requestOption
- func WithQueryParams(query url.Values) requestOption
- func WithRequestData(data []byte) requestOption
- type Actor
- type Client
- func (c *Client) BaseURL() string
- func (c *Client) BrokenVersions(ctx context.Context) ([]string, error)
- func (c *Client) DownloadToken(ctx context.Context, ttl time.Duration) (string, error)
- func (c *Client) ExtensionsVersions(ctx context.Context, talosVersion string) ([]ExtensionInfo, error)
- func (c *Client) OverlaysVersions(ctx context.Context, talosVersion string) ([]OverlayInfo, error)
- func (c *Client) SPDXBundle(ctx context.Context, schematicID, talosVersion, arch string) ([]byte, error)
- func (c *Client) ScanReport(ctx context.Context, schematicID, talosVersion, arch, filename string) ([]byte, error)
- func (c *Client) SchematicCreate(ctx context.Context, sc schematic.Schematic) (string, *schematic.Schematic, error)
- func (c *Client) SchematicGet(ctx context.Context, schematicID string) (*schematic.Schematic, error)
- func (c *Client) TalosctlList(ctx context.Context, talosVersion string) ([]string, error)
- func (c *Client) TokenCreate(ctx context.Context, opts TokenCreateOptions) (id, token string, err error)
- func (c *Client) TokenList(ctx context.Context) ([]TokenInfo, error)
- func (c *Client) TokenRevoke(ctx context.Context, id string) error
- func (c *Client) VEXDocument(ctx context.Context, talosVersion string) ([]byte, error)
- func (c *Client) Versions(ctx context.Context) ([]string, error)
- type ExtensionInfo
- type HTTPError
- type InvalidSchematicError
- type Option
- type Options
- type OverlayInfo
- type TokenCreateOptions
- type TokenInfo
- type TokenSource
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsHTTPErrorCode ¶ added in v0.2.1
IsHTTPErrorCode checks if the error is HTTP error with a specific doe.
func IsInvalidSchematicError ¶
IsInvalidSchematicError checks if the error is invalid schematic.
func WithHeaders ¶ added in v1.3.3
WithHeaders attaches request headers.
func WithQueryParams ¶ added in v1.3.3
WithQueryParams attaches URL query parameters.
func WithRequestData ¶ added in v1.3.3
func WithRequestData(data []byte) requestOption
WithRequestData attaches a request body.
Types ¶
type Actor ¶ added in v1.7.0
type Actor string
Actor is a server-defined credential profile. The server expands it into executable and issuable scopes; clients cannot override either scope set when selecting an actor.
const ( // ActorTalos can fetch generated images, PXE assets, and installer OCI artifacts. ActorTalos Actor = "talos" // ActorOnPrem can pull source images for mirroring into an on-premises installation. ActorOnPrem Actor = "onprem" // ActorAutomation can operate schematics and reports and issue bounded Talos or Automation credentials. ActorAutomation Actor = "automation" // ActorOperator can operate schematics and reports, fetch generated products, and pull source artifacts. ActorOperator Actor = "operator" // ActorAdmin can manage credentials and issue every actor profile. ActorAdmin Actor = "admin" )
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the Image Factory HTTP API client.
func (*Client) BrokenVersions ¶ added in v1.3.3
BrokenVersions gets the list of Talos versions marked as broken by the factory.
func (*Client) DownloadToken ¶ added in v1.5.0
DownloadToken requests a short-lived JWT token carrying image:read, scoped to the authenticated caller's identity. The token can be appended as ?token= to any image download URL, and to a PXE script URL, which forwards it into the asset URLs of the script; one token covers all schematics owned by the caller.
A positive ttl requests that lifetime, which the server accepts only within its configured bounds; zero or less takes the server default.
The token is not stored, so expiry is its only revocation mechanism and its lifetime is bounded by the server's authentication.tokens.ttl.ephemeral policy. Storage is independent of URL use; both stored and ephemeral tokens may travel in a URL when their scopes are URL-safe.
func (*Client) ExtensionsVersions ¶
func (c *Client) ExtensionsVersions(ctx context.Context, talosVersion string) ([]ExtensionInfo, error)
ExtensionsVersions gets the version of the extension for a Talos version.
func (*Client) OverlaysVersions ¶ added in v0.3.0
OverlaysVersions gets the version of the extension for a Talos version.
func (*Client) SPDXBundle ¶ added in v1.5.1
func (c *Client) SPDXBundle(ctx context.Context, schematicID, talosVersion, arch string) ([]byte, error)
SPDXBundle downloads the SPDX SBOM bundle for the given schematic, Talos version, and architecture, as "application/spdx+json".
func (*Client) ScanReport ¶ added in v1.3.3
func (c *Client) ScanReport(ctx context.Context, schematicID, talosVersion, arch, filename string) ([]byte, error)
ScanReport downloads a vulnerability scan report for the given schematic, Talos version, architecture, and report filename. The filename extension selects the report format: ".sarif" → SARIF, ".cdx" → CycloneDX, ".json" → JSON, ".table" → plain-text table.
func (*Client) SchematicCreate ¶
func (c *Client) SchematicCreate(ctx context.Context, sc schematic.Schematic) (string, *schematic.Schematic, error)
SchematicCreate generates new schematic from the configuration.
It returns the schematic ID and the normalized schematic as returned by the factory. The normalized schematic should be considered authoritative as it may differ from the input (for example, the factory may set the owner field for authenticated requests).
func (*Client) SchematicGet ¶ added in v0.9.0
func (*Client) TalosctlList ¶ added in v1.2.0
TalosctlList gets the list of talosctl download URLs for a Talos version.
func (*Client) TokenCreate ¶ added in v1.7.0
func (c *Client) TokenCreate(ctx context.Context, opts TokenCreateOptions) (id, token string, err error)
TokenCreate mints a credential, returning its ID and the credential itself. The credential is only returned at creation time and cannot be retrieved afterward.
A stored credential is recorded by the factory, so it can be listed and revoked, requires a name, and counts against the per-org cap. A non-stored credential is retired only by expiry. Actor cannot be combined with Scopes or IssuableScopes; the server expands actor profiles.
func (*Client) TokenList ¶ added in v1.7.0
TokenList returns the caller's currently active stored tokens.
func (*Client) TokenRevoke ¶ added in v1.7.0
TokenRevoke revokes the token with the given ID.
func (*Client) VEXDocument ¶ added in v1.5.1
VEXDocument downloads the VEX document for the given Talos version, as "application/json". VEX data is version-scoped, not schematic-scoped.
type ExtensionInfo ¶
type ExtensionInfo struct {
Name string `json:"name"`
Ref string `json:"ref"`
Digest string `json:"digest"`
Author string `json:"author"`
Description string `json:"description"`
}
ExtensionInfo defines extensions versions list response item.
type InvalidSchematicError ¶
type InvalidSchematicError struct {
// contains filtered or unexported fields
}
InvalidSchematicError is parsed from 400 response from the server.
func (*InvalidSchematicError) Error ¶
func (e *InvalidSchematicError) Error() string
Error implements error interface.
type Option ¶
type Option func(*Options)
Option defines a single client option setter.
func WithBasicAuth ¶ added in v1.2.0
WithBasicAuth adds basic authentication to each request. It can carry htpasswd credentials or a self-issued API token in the password position for Basic-only clients. For an API token, the signed subject determines the principal; the Basic username does not grant authority.
func WithBearerToken ¶ added in v1.5.1
WithBearerToken adds a static bearer token to each request. It may be a configured-provider bearer credential or a self-issued Image Factory API token; the server applies the corresponding identity and scope checks.
func WithClient ¶
WithClient overrides default client instance.
func WithTokenSource ¶ added in v1.6.0
func WithTokenSource(ts TokenSource) Option
WithTokenSource sets a token source that is consulted on every request for a bearer token.
Use this instead of WithBearerToken when the provider credential can rotate over the client's lifetime, for example when an Auth0 access token is refreshed in the background.
type Options ¶
type Options struct {
// ExtraHeaders represents extra headers to be added to each request.
ExtraHeaders http.Header
// TokenSource, when set, is called on every request to obtain a bearer token.
TokenSource TokenSource
// Client is the http client.
Client http.Client
}
Options defines client options.
type OverlayInfo ¶ added in v0.3.0
type OverlayInfo struct {
Name string `json:"name"`
Image string `json:"image"`
Ref string `json:"ref"`
Digest string `json:"digest"`
}
OverlayInfo defines overlay versions list response item.
type TokenCreateOptions ¶ added in v1.7.0
type TokenCreateOptions struct {
Name string
Subject string
Actor Actor
Scopes []string
IssuableScopes []string
TTL time.Duration
Ephemeral bool
}
TokenCreateOptions describes a credential to mint. Actor selects a fixed server-owned profile; otherwise Scopes and IssuableScopes define the executable and delegation capabilities directly. Subject is normally empty; only the CLI bootstrap credential may mint for another identity. Credentials are stored and revocable by default; Ephemeral explicitly opts out.
type TokenInfo ¶ added in v1.7.0
type TokenInfo struct {
CreatedAt time.Time `json:"created_at"`
ExpiresAt time.Time `json:"expires_at"`
ID string `json:"id"`
Name string `json:"name"`
Scopes []string `json:"scopes"`
IssuableScopes []string `json:"issuable_scopes,omitempty"`
}
TokenInfo defines an API token list response item.
type TokenSource ¶ added in v1.6.0
TokenSource returns the bearer token to use for the next request.
It is called on every request, so it can be backed by a value that rotates over time (for example, a token refreshed in the background). An empty token with a nil error leaves the request unauthenticated.