Documentation
¶
Overview ¶
Package module implements the on-disk module package format: a parser that reads a module source tree into a validated Module model, shared by vela module publish, the registry fetch, and vela module deploy.
Index ¶
- Constants
- Variables
- func NewStore(cli client.Client) component.RegistryDataStore
- func NotFoundError(ctx context.Context, store component.RegistryDataStore, name string) error
- func ResolveRegistry(ctx context.Context, store component.RegistryDataStore, name string) (component.Registry, error)
- func SourceTypeName(reg component.Registry) string
- type Artifact
- type Line
- type Module
Constants ¶
const ( // AnnotationModule is the OCI annotation recording the published module's // name, so a registry listing identifies the module without pulling it. AnnotationModule = "modules.oam.dev/module" // AnnotationLines is the OCI annotation recording every API line in the // published artifact, comma-separated and sorted. AnnotationLines = "modules.oam.dev/lines" // AnnotationEnabledLines is the OCI annotation recording the subset of // lines their author left enabled, which is what the render service // installs. It is absent when no line is enabled. AnnotationEnabledLines = "modules.oam.dev/enabled-lines" )
const ( // ModuleRegistryConfigMap is the ConfigMap in vela-system holding module // registries. It is separate from the addon registry ConfigMap so modules // are configured, listed, and removed independently of addons. ModuleRegistryConfigMap = "vela-module-registry" // ModuleRegistrySecretPrefix prefixes the secret holding a module registry's // token. Each registry entry gets its own secret, named // ModuleRegistrySecretPrefix + the registry name. ModuleRegistrySecretPrefix = "module-registry-" // DefaultRegistryName is the registry seeded by the chart at install time. // It is the default when a caller does not name a registry and more than one // is configured. DefaultRegistryName = "catalog" )
Variables ¶
var ( // ErrRegistryNotFound marks an unknown module registry name. Resolution // wraps it (see notFoundError) so both fetch and the CLI report and detect // unknown names the same way. ErrRegistryNotFound = errors.New("module registry not found") // ErrModuleNotFound marks a module that is absent from an otherwise valid // registry. The fetch wraps it when the registry has no such module. ErrModuleNotFound = errors.New("module not found in registry") )
Distinct, typed errors for the module fetch/resolve path. Callers such as the type: module render service match these with errors.Is to set a meaningful Application condition (a mis-named registry is an operator config problem; a missing module is a publish/naming problem) instead of parsing message text.
Functions ¶
func NewStore ¶
func NewStore(cli client.Client) component.RegistryDataStore
NewStore returns the module registry store: the shared addon registry implementation pointed at the module ConfigMap and secret prefix.
func NotFoundError ¶
NotFoundError builds the same "not found" error ResolveRegistry returns for an unknown name. It is exported for commands such as delete, which look up a registry directly with store.GetRegistry rather than through ResolveRegistry -- so an entry ResolveRegistry would reject as unsupported can still be found and removed -- but should report an unknown name the same way.
func ResolveRegistry ¶
func ResolveRegistry(ctx context.Context, store component.RegistryDataStore, name string) (component.Registry, error)
ResolveRegistry returns the module registry to use for an operation. A non-empty name selects that registry; an empty name selects a default. The returned Registry is guaranteed to be an OCI source, with its token loaded from its secret.
Modules support no other kind of source. The module ConfigMap shares its format with the addon one, though, so an entry configured as git, helm, OSS, gitee, or gitlab can be present -- hand-edited, or written by `vela addon registry` if it is pointed at this ConfigMap. Such an entry is rejected here, naming the entry and its actual type, rather than handed to a consumer that assumes an oci:// reg.Helm is set. A Git-backed entry gets its own message, because it is the one kind an existing install may already be using.
With an empty name the rules apply in order: the sole configured registry wins; otherwise a registry named DefaultRegistryName wins; otherwise the choice is ambiguous and an error names the alternatives. Both rules are needed. The sole registry rule alone would start failing as soon as a user adds a second registry alongside the seeded one, and the DefaultRegistryName rule alone would fail for an operator who removed the seeded entry.
func SourceTypeName ¶
Types ¶
type Artifact ¶
type Artifact struct {
// Module is the parsed module the archive was built from.
Module *Module
// Tag is the version the artifact publishes under: the module's own
// version, or versionOverride when PackageModule was given one.
Tag string
// Annotations are the OCI annotations to stamp on the published artifact.
Annotations map[string]string
// Archive is the gzipped tar of the Helm chart carrying the module tree.
Archive []byte
}
Artifact is a module packaged for publication: the parsed module, the tag it publishes under, the OCI annotations to stamp, and the Helm chart archive carrying the module tree.
func PackageModule ¶
PackageModule parses the module tree at dir and packages it as a Helm chart archive named after the module and tagged from its version, or from versionOverride when that is set. The chart name must be the module's own name: the fetch strips a <moduleName>/ prefix from the files it pulls back, so an archive built under any other name reads as an empty module.
dir is read only. The generated Chart.yaml is written into a temporary copy of the tree, so publishing leaves the author's source directory untouched whether it succeeds or fails.
type Line ¶
type Line struct {
// APIVersion is the API line identifier, e.g. "v1", "v1beta1".
APIVersion string
// Enabled is the module author's install switch for this line, read from
// v<N>/_version.cue's top-level enabled field. Absent means true: a line
// ships installable unless its author opts out. The render service
// installs every enabled line and skips the rest.
Enabled bool
// Auxiliary holds the objects read from v<N>/auxiliary/, in filename order
// (and document order within a multi-document file).
// Empty for a line that ships no auxiliary/.
Auxiliary []map[string]interface{}
// Definitions are the rendered ComponentDefinitions (or other
// X-Definitions) under v<N>/definitions/, in sorted filename order.
Definitions []map[string]interface{}
}
Line is one API line of a module: its version identity, the auxiliary objects backing it, and its rendered ComponentDefinitions.
type Module ¶
type Module struct {
// Name is the module identity, read from _module.cue's top-level module
// field.
Name string
// Version is the module's own semver, read from _module.cue's top-level
// version field. It is the tag vela module publish uses for the artifact.
Version string
// Auxiliary holds the objects read from the module-level auxiliary/, in
// filename order (and document order within a multi-document file). Empty
// for infra-less module that ships no module-level auxiliary/.
Auxiliary []map[string]interface{}
// Lines are the module's API lines, keyed by APIVersion.
Lines map[string]Line
}
Module is a parsed module source tree: its identity, module-wide auxiliary objects, and its API lines keyed by apiVersion.
func ParseModule ¶
ParseModule reads the module source tree from fsys (rooted at the module directory) and returns its parsed Module. It reads fsys only; it dispatches nothing to a cluster and performs no identity or structural validation beyond what validate.go covers.
func ParseModuleDir ¶
ParseModuleDir reads a module from a local directory. It is the filesystem-backed convenience over ParseModule, preserving callers that have a directory path rather than an fs.FS.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package naming holds the module naming rules shared by the side that writes definition names and the side that reads them back: the render service derives {module}-{apiVersion}-{name} when installing a module, and type resolution derives the same string when an Application refers to a module capability.
|
Package naming holds the module naming rules shared by the side that writes definition names and the side that reads them back: the render service derives {module}-{apiVersion}-{name} when installing a module, and type resolution derives the same string when an Application refers to a module capability. |
|
Package service fetches a module from a registry and parses it into a module.Module, server-side, for the type: module render path.
|
Package service fetches a module from a registry and parses it into a module.Module, server-side, for the type: module render path. |
|
api
Package api holds the leaf types and injection seam shared between the module render service and the CueX module provider.
|
Package api holds the leaf types and injection seam shared between the module render service and the CueX module provider. |