Mirrors/flux2
1
0
Fork 0
mirror of synced 2026-05-03 02:03:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

Make plugin types public

Browse Source 
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
This commit is contained in:
Stefan Prodan
2026-04-14 00:02:13 +03:00
parent c0938d351f
commit 5256361d8c
6 changed files with 192 additions and 153 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
internal/plugin/catalog.go
View File

@@ -24,122 +24,16 @@ import (
"github.com/hashicorp/go-retryablehttp"
"sigs.k8s.io/yaml"
plugintypes "github.com/fluxcd/flux2/v2/pkg/plugin"
)
const (
// defaultCatalogBase points at the latest GitHub release of fluxcd/plugins.
defaultCatalogBase = "https://github.com/fluxcd/plugins/releases/latest/download/"
envCatalogBase = "FLUXCD_PLUGIN_CATALOG"
pluginAPIVersion = "cli.fluxcd.io/v1beta1"
pluginKind = "Plugin"
catalogKind = "PluginCatalog"
)
// PluginManifest represents a single plugin's manifest from the catalog.
type PluginManifest struct {
// APIVersion is the manifest schema version (e.g. "cli.fluxcd.io/v1beta1").
APIVersion string `json:"apiVersion"`
// Kind is the manifest type, must be "Plugin".
Kind string `json:"kind"`
// Name is the plugin name used in "flux <name>" invocations.
Name string `json:"name"`
// Description is a short human-readable summary of the plugin.
Description string `json:"description"`
// Homepage is the URL to the plugin's documentation site.
Homepage string `json:"homepage,omitempty"`
// Source is the URL to the plugin's source repository.
Source string `json:"source,omitempty"`
// Bin is the binary name inside archives and the installed filename
// (e.g. "flux-operator"). On Windows ".exe" is appended automatically.
Bin string `json:"bin"`
// Versions lists available versions, newest first.
Versions []PluginVersion `json:"versions"`
}
// PluginVersion represents a version entry in a plugin manifest.
type PluginVersion struct {
// Version is the semantic version string (e.g. "0.45.0").
Version string `json:"version"`
// Platforms lists the platform-specific binaries for this version.
Platforms []PluginPlatform `json:"platforms"`
}
// PluginPlatform represents a platform-specific binary entry.
type PluginPlatform struct {
// OS is the target operating system (e.g. "darwin", "linux", "windows").
OS string `json:"os"`
// Arch is the target architecture (e.g. "amd64", "arm64").
Arch string `json:"arch"`
// URL is the download URL for the archive or binary.
URL string `json:"url"`
// Checksum is the expected digest in "<algorithm>:<hex>" format
// (e.g. "sha256:cd85d5d84d264...").
Checksum string `json:"checksum"`
// ExtractPath overrides the default binary lookup name inside archives.
// When set, it is matched as an exact path within the archive (e.g.
// "bin/flux-operator"). When empty, the archive is searched by the
// base name derived from the manifest's Bin field.
ExtractPath string `json:"extractPath,omitempty"`
}
// PluginCatalog represents the generated catalog.yaml file.
type PluginCatalog struct {
// APIVersion is the catalog schema version (e.g. "cli.fluxcd.io/v1beta1").
APIVersion string `json:"apiVersion"`
// Kind is the catalog type, must be "PluginCatalog".
Kind string `json:"kind"`
// Plugins lists all available plugins in the catalog.
Plugins []CatalogEntry `json:"plugins"`
}
// CatalogEntry is a single entry in the plugin catalog.
type CatalogEntry struct {
// Name is the plugin name.
Name string `json:"name"`
// Description is a short human-readable summary of the plugin.
Description string `json:"description"`
// Homepage is the URL to the plugin's documentation site.
Homepage string `json:"homepage,omitempty"`
// Source is the URL to the plugin's source repository.
Source string `json:"source,omitempty"`
// License is the SPDX license identifier (e.g. "Apache-2.0").
License string `json:"license,omitempty"`
}
// Receipt records what was installed for a plugin.
type Receipt struct {
// Name is the plugin name (e.g. "operator").
Name string `json:"name"`
// Version is the installed semantic version.
Version string `json:"version"`
// InstalledAt is the RFC 3339 timestamp of the installation.
InstalledAt string `json:"installedAt"`
// Platform records the platform-specific details used for installation.
Platform PluginPlatform `json:"platform"`
}
// CatalogClient fetches plugin manifests and catalogs from a remote URL.
type CatalogClient struct {
// BaseURL is the catalog base URL for fetching manifests.
@@ -170,46 +64,46 @@ func (c *CatalogClient) baseURL() string {
}
// FetchManifest fetches a single plugin manifest from the catalog.
func (c *CatalogClient) FetchManifest(name string) (*PluginManifest, error) {
func (c *CatalogClient) FetchManifest(name string) (*plugintypes.Manifest, error) {
url := c.baseURL() + name + ".yaml"
body, err := c.fetch(url)
if err != nil {
return nil, fmt.Errorf("plugin %q not found in catalog", name)
}
var manifest PluginManifest
var manifest plugintypes.Manifest
if err := yaml.Unmarshal(body, &manifest); err != nil {
return nil, fmt.Errorf("failed to parse plugin manifest for %q: %w", name, err)
}
if manifest.APIVersion != pluginAPIVersion {
return nil, fmt.Errorf("plugin %q has unsupported apiVersion %q (expected %q)", name, manifest.APIVersion, pluginAPIVersion)
if manifest.APIVersion != plugintypes.APIVersion {
return nil, fmt.Errorf("plugin %q has unsupported apiVersion %q (expected %q)", name, manifest.APIVersion, plugintypes.APIVersion)
}
if manifest.Kind != pluginKind {
return nil, fmt.Errorf("plugin %q has unexpected kind %q (expected %q)", name, manifest.Kind, pluginKind)
if manifest.Kind != plugintypes.PluginKind {
return nil, fmt.Errorf("plugin %q has unexpected kind %q (expected %q)", name, manifest.Kind, plugintypes.PluginKind)
}
return &manifest, nil
}
// FetchCatalog fetches the generated catalog.yaml.
func (c *CatalogClient) FetchCatalog() (*PluginCatalog, error) {
func (c *CatalogClient) FetchCatalog() (*plugintypes.Catalog, error) {
url := c.baseURL() + "catalog.yaml"
body, err := c.fetch(url)
if err != nil {
return nil, fmt.Errorf("failed to fetch plugin catalog: %w", err)
}
var catalog PluginCatalog
var catalog plugintypes.Catalog
if err := yaml.Unmarshal(body, &catalog); err != nil {
return nil, fmt.Errorf("failed to parse plugin catalog: %w", err)
}
if catalog.APIVersion != pluginAPIVersion {
return nil, fmt.Errorf("plugin catalog has unsupported apiVersion %q (expected %q)", catalog.APIVersion, pluginAPIVersion)
if catalog.APIVersion != plugintypes.APIVersion {
return nil, fmt.Errorf("plugin catalog has unsupported apiVersion %q (expected %q)", catalog.APIVersion, plugintypes.APIVersion)
}
if catalog.Kind != catalogKind {
return nil, fmt.Errorf("plugin catalog has unexpected kind %q (expected %q)", catalog.Kind, catalogKind)
if catalog.Kind != plugintypes.CatalogKind {
return nil, fmt.Errorf("plugin catalog has unexpected kind %q (expected %q)", catalog.Kind, plugintypes.CatalogKind)
}
return &catalog, nil
@@ -243,7 +137,7 @@ func newHTTPClient(timeout time.Duration) *http.Client {
// ResolveVersion finds the requested version in the manifest.
// If version is empty, returns the first (latest) version.
func ResolveVersion(manifest *PluginManifest, version string) (*PluginVersion, error) {
func ResolveVersion(manifest *plugintypes.Manifest, version string) (*plugintypes.Version, error) {
if len(manifest.Versions) == 0 {
return nil, fmt.Errorf("plugin %q has no versions", manifest.Name)
}
@@ -262,7 +156,7 @@ func ResolveVersion(manifest *PluginManifest, version string) (*PluginVersion, e
}
// ResolvePlatform finds the platform entry matching the given OS and arch.
func ResolvePlatform(pv *PluginVersion, goos, goarch string) (*PluginPlatform, error) {
func ResolvePlatform(pv *plugintypes.Version, goos, goarch string) (*plugintypes.Platform, error) {
for i := range pv.Platforms {
if pv.Platforms[i].OS == goos && pv.Platforms[i].Arch == goarch {
return &pv.Platforms[i], nil

12
internal/plugin/catalog_test.go
View File

@@ -20,6 +20,8 @@ import (
"net/http"
"net/http/httptest"
"testing"
plugintypes "github.com/fluxcd/flux2/v2/pkg/plugin"
)
func TestFetchManifest(t *testing.T) {
@@ -168,9 +170,9 @@ plugins: []
}
func TestResolveVersion(t *testing.T) {
manifest := &PluginManifest{
manifest := &plugintypes.Manifest{
Name: "operator",
Versions: []PluginVersion{
Versions: []plugintypes.Version{
{Version: "0.45.0"},
{Version: "0.44.0"},
},
@@ -204,7 +206,7 @@ func TestResolveVersion(t *testing.T) {
})
t.Run("no versions", func(t *testing.T) {
_, err := ResolveVersion(&PluginManifest{Name: "empty"}, "")
_, err := ResolveVersion(&plugintypes.Manifest{Name: "empty"}, "")
if err == nil {
t.Fatal("expected error, got nil")
}
@@ -212,9 +214,9 @@ func TestResolveVersion(t *testing.T) {
}
func TestResolvePlatform(t *testing.T) {
pv := &PluginVersion{
pv := &plugintypes.Version{
Version: "0.45.0",
Platforms: []PluginPlatform{
Platforms: []plugintypes.Platform{
{OS: "darwin", Arch: "arm64", URL: "https://example.com/darwin_arm64.tar.gz"},
{OS: "linux", Arch: "amd64", URL: "https://example.com/linux_amd64.tar.gz"},
},

12
internal/plugin/install.go
View File

@@ -31,6 +31,8 @@ import (
"time"
"sigs.k8s.io/yaml"
plugintypes "github.com/fluxcd/flux2/v2/pkg/plugin"
)
// Installer handles downloading, verifying, and installing plugins.
@@ -48,7 +50,7 @@ func NewInstaller() *Installer {
// Install downloads, verifies, extracts, and installs a plugin binary
// to the given plugin directory.
func (inst *Installer) Install(pluginDir string, manifest *PluginManifest, pv *PluginVersion, plat *PluginPlatform) error {
func (inst *Installer) Install(pluginDir string, manifest *plugintypes.Manifest, pv *plugintypes.Version, plat *plugintypes.Platform) error {
tmpFile, err := os.CreateTemp("", "flux-plugin-*")
if err != nil {
return fmt.Errorf("failed to create temp file: %w", err)
@@ -118,7 +120,7 @@ func (inst *Installer) Install(pluginDir string, manifest *PluginManifest, pv *P
return err
}
receipt := Receipt{
receipt := plugintypes.Receipt{
Name: manifest.Name,
Version: pv.Version,
InstalledAt: time.Now().UTC().Format(time.RFC3339),
@@ -156,13 +158,13 @@ func Uninstall(pluginDir, name string) error {
// ReadReceipt reads the install receipt for a plugin.
// Returns nil if no receipt exists.
func ReadReceipt(pluginDir, name string) *Receipt {
func ReadReceipt(pluginDir, name string) *plugintypes.Receipt {
data, err := os.ReadFile(receiptPath(pluginDir, name))
if err != nil {
return nil
}
var receipt Receipt
var receipt plugintypes.Receipt
if err := yaml.Unmarshal(data, &receipt); err != nil {
return nil
}
@@ -174,7 +176,7 @@ func receiptPath(pluginDir, name string) string {
return filepath.Join(pluginDir, pluginPrefix+name+".yaml")
}
func writeReceipt(pluginDir, name string, receipt *Receipt) error {
func writeReceipt(pluginDir, name string, receipt *plugintypes.Receipt) error {
data, err := yaml.Marshal(receipt)
if err != nil {
return fmt.Errorf("failed to marshal receipt: %w", err)

38
internal/plugin/install_test.go
View File

@@ -31,6 +31,8 @@ import (
"runtime"
"strings"
"testing"
plugintypes "github.com/fluxcd/flux2/v2/pkg/plugin"
)
// createTestTarGz creates a tar.gz archive containing a single file.
@@ -164,12 +166,12 @@ func TestInstall(t *testing.T) {
pluginDir := t.TempDir()
manifest := &PluginManifest{
manifest := &plugintypes.Manifest{
Name: "operator",
Bin: "flux-operator",
}
pv := &PluginVersion{Version: "0.45.0"}
plat := &PluginPlatform{
pv := &plugintypes.Version{Version: "0.45.0"}
plat := &plugintypes.Platform{
OS: "linux",
Arch: "amd64",
URL: server.URL + "/flux-operator_0.45.0_linux_amd64.tar.gz",
@@ -218,9 +220,9 @@ func TestInstallChecksumMismatch(t *testing.T) {
pluginDir := t.TempDir()
manifest := &PluginManifest{Name: "operator", Bin: "flux-operator"}
pv := &PluginVersion{Version: "0.45.0"}
plat := &PluginPlatform{
manifest := &plugintypes.Manifest{Name: "operator", Bin: "flux-operator"}
pv := &plugintypes.Version{Version: "0.45.0"}
plat := &plugintypes.Platform{
OS: "linux",
Arch: "amd64",
URL: server.URL + "/archive.tar.gz",
@@ -253,9 +255,9 @@ func TestInstallBinaryNotInArchive(t *testing.T) {
pluginDir := t.TempDir()
manifest := &PluginManifest{Name: "operator", Bin: "flux-operator"}
pv := &PluginVersion{Version: "0.45.0"}
plat := &PluginPlatform{
manifest := &plugintypes.Manifest{Name: "operator", Bin: "flux-operator"}
pv := &plugintypes.Version{Version: "0.45.0"}
plat := &plugintypes.Platform{
OS: "linux",
Arch: "amd64",
URL: server.URL + "/archive.tar.gz",
@@ -396,12 +398,12 @@ func TestInstallRawBinary(t *testing.T) {
pluginDir := t.TempDir()
manifest := &PluginManifest{
manifest := &plugintypes.Manifest{
Name: "validate",
Bin: "flux-validate",
}
pv := &PluginVersion{Version: "1.2.3"}
plat := &PluginPlatform{
pv := &plugintypes.Version{Version: "1.2.3"}
plat := &plugintypes.Platform{
OS: runtime.GOOS,
Arch: runtime.GOARCH,
// URL filename deliberately differs from manifest.Bin — mimics a
@@ -701,9 +703,9 @@ func TestInstallExtractPath(t *testing.T) {
pluginDir := t.TempDir()
manifest := &PluginManifest{Name: "operator", Bin: "flux-operator"}
pv := &PluginVersion{Version: "0.45.0"}
plat := &PluginPlatform{
manifest := &plugintypes.Manifest{Name: "operator", Bin: "flux-operator"}
pv := &plugintypes.Version{Version: "0.45.0"}
plat := &plugintypes.Platform{
OS: "linux",
Arch: "amd64",
URL: server.URL + "/archive.tar.gz",
@@ -746,9 +748,9 @@ func TestInstallExtractPathZip(t *testing.T) {
pluginDir := t.TempDir()
manifest := &PluginManifest{Name: "operator", Bin: "flux-operator"}
pv := &PluginVersion{Version: "0.45.0"}
plat := &PluginPlatform{
manifest := &plugintypes.Manifest{Name: "operator", Bin: "flux-operator"}
pv := &plugintypes.Version{Version: "0.45.0"}
plat := &plugintypes.Platform{
OS: "linux",
Arch: "amd64",
URL: server.URL + "/archive.zip",

10
internal/plugin/update.go
View File

@@ -16,6 +16,10 @@ limitations under the License.
package plugin
import (
plugintypes "github.com/fluxcd/flux2/v2/pkg/plugin"
)
const (
SkipReasonManual = "manually installed"
SkipReasonUpToDate = "already up to date"
@@ -41,13 +45,13 @@ type UpdateResult struct {
SkipReason string
// Manifest is the resolved plugin manifest for the update.
Manifest *PluginManifest
Manifest *plugintypes.Manifest
// Version is the resolved target version for the update.
Version *PluginVersion
Version *plugintypes.Version
// Platform is the resolved platform entry for the update.
Platform *PluginPlatform
Platform *plugintypes.Platform
// Err is set when the update check itself failed.
Err error