Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions docs/developer/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,29 @@ A deprecated entry stays in its catalog and keeps receiving releases until its
catalog removes it, so installs and upgrades keep working during the
deprecation period.

### What users see

`plugin install`, `plugin install` with no arguments (restore), and
`plugin upgrade` print a notice to stderr for a deprecated plugin.
`plugin upgrade` prints it whether the plugin was upgraded or was already up
to date. For the entry above, a user whose registry doesn't have the
replacement's catalog sees:

```text
warning: ipam is deprecated: ipam moved to the Milo catalog.
To switch to the replacement:
datumctl plugin index add milo-os milo-os/cli-plugins
datumctl plugin install milo-os/ipam
```

If the replacement's catalog is already registered, the notice shows only the
`plugin install` line. Installs and upgrades still proceed. Plugins installed
directly from GitHub have no catalog entry and get no notice.

To move, run `datumctl plugin install <catalog>/<name>`. The plugin is then
recorded as installed from the new catalog, so `plugin upgrade` uses that
catalog and the notice stops.

---

## plugins.json schema
Expand Down
223 changes: 223 additions & 0 deletions internal/cmd/plugin/deprecation_cmd_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,223 @@
package plugin

import (
"bytes"
"os"
"runtime"
"strings"
"testing"

metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"

"go.datum.net/datumctl/internal/pluginstore"
)

func deprecatedPlugin(name, version string) pluginstore.Plugin {
p := testPlugin(name, version, name)
p.Spec.Deprecated = &pluginstore.Deprecation{
Message: "use the new one",
Replacement: &pluginstore.PluginReplacement{
Catalog: "milo-os/cli-plugins",
Name: name,
},
}
return p
}

func TestUpgrade_deprecatedUpToDatePrintsNotice(t *testing.T) {
dir := t.TempDir()
seedManifest(t, dir, map[string]*pluginstore.InstalledPlugin{"ipam": installedEntry("datum", "v0.1.0")})
seedFreshCache(t, dir, pluginstore.OfficialCatalogName, deprecatedPlugin("ipam", "v0.1.0"))

out, err := execPluginCmd(t, dir, upgradeCmd(nil), "ipam")
if err != nil {
t.Fatalf("unexpected error: %v\n%s", err, out)
}
for _, want := range []string{"ipam is already up to date", "warning: ipam is deprecated: use the new one"} {
if !strings.Contains(out, want) {
t.Fatalf("want %q in output:\n%s", want, out)
}
}
}

func TestUpgrade_movedPluginNoNotice(t *testing.T) {
dir := t.TempDir()
if err := pluginstore.SaveRegistry(dir, &pluginstore.Registry{Catalogs: []pluginstore.Catalog{
{Name: "milo-os", Source: "milo-os/cli-plugins", Type: pluginstore.CatalogTypeCustom},
}}); err != nil {
t.Fatal(err)
}
seedManifest(t, dir, map[string]*pluginstore.InstalledPlugin{"ipam": installedEntry("milo-os", "v0.1.0")})
seedFreshCache(t, dir, "milo-os", testPlugin("ipam", "v0.1.0", "IPAM"))
seedFreshCache(t, dir, pluginstore.OfficialCatalogName, deprecatedPlugin("ipam", "v0.1.0"))

out, err := execPluginCmd(t, dir, upgradeCmd(nil), "ipam")
if err != nil {
t.Fatalf("unexpected error: %v\n%s", err, out)
}
if !strings.Contains(out, "ipam is already up to date") || strings.Contains(out, "deprecated") {
t.Fatalf("want up-to-date report and no notice, got:\n%s", out)
}
}

func TestUpgrade_nonDeprecatedNoNotice(t *testing.T) {
dir := t.TempDir()
seedManifest(t, dir, map[string]*pluginstore.InstalledPlugin{"dns": installedEntry("datum", "v1.0.0")})
seedFreshCache(t, dir, pluginstore.OfficialCatalogName, testPlugin("dns", "v1.0.0", "DNS"))

out, err := execPluginCmd(t, dir, upgradeCmd(nil), "dns")
if err != nil {
t.Fatalf("unexpected error: %v\n%s", err, out)
}
if strings.Contains(out, "deprecated") {
t.Fatalf("want no notice, got:\n%s", out)
}
}

func TestUpgradeAll_failedUpgradeNoNotice(t *testing.T) {
dir := t.TempDir()
seedManifest(t, dir, map[string]*pluginstore.InstalledPlugin{
"ipam": installedEntry("datum", "v0.1.0"),
"dns": installedEntry("datum", "v1.0.0"),
})
// ipam is deprecated and has a newer version with no platforms, so its
// upgrade fails.
seedFreshCache(t, dir, pluginstore.OfficialCatalogName,
deprecatedPlugin("ipam", "v0.2.0"), deprecatedPlugin("dns", "v1.0.0"))

out, err := execPluginCmd(t, dir, upgradeCmd(nil), "--all")
if err == nil {
t.Fatalf("want error for failed ipam upgrade, got none:\n%s", out)
}
if strings.Contains(out, "warning: ipam is deprecated") {
t.Fatalf("failed upgrade must not print a notice:\n%s", out)
}
if !strings.Contains(out, "warning: dns is deprecated") {
t.Fatalf("successful plugin should print its notice:\n%s", out)
}
}

func TestInstallFromCatalog_deprecatedPrintsNotice(t *testing.T) {
if runtime.GOOS == "windows" {
t.Skip("test builds a unix binary helper; skip on windows")
}
pluginBin := buildHelperBinary(t, `
package main

import (
"fmt"
"os"
)

func main() {
for _, a := range os.Args[1:] {
if a == "--plugin-manifest" {
fmt.Println(`+"`"+`{"name":"alpha","version":"v0.2.0","description":"Alpha","api_version":1}`+"`"+`)
return
}
}
}
`)
binData, err := os.ReadFile(pluginBin)
if err != nil {
t.Fatal(err)
}
archiveBytes := makeTarGz(t, "alpha", binData)
url := serveArchive(t, archiveBytes)

alpha := pluginstore.Plugin{
ObjectMeta: metav1.ObjectMeta{Name: "alpha"},
Spec: pluginstore.PluginSpec{
ShortDescription: "Alpha",
Version: "v0.2.0",
Platforms: []pluginstore.Platform{{URI: url + "/alpha.tar.gz", SHA256: sha256HexOf(archiveBytes)}},
Deprecated: &pluginstore.Deprecation{Message: "use beta"},
},
}
dir := t.TempDir()
seedFreshCache(t, dir, pluginstore.OfficialCatalogName, alpha)

t.Setenv("DATUMCTL_PLUGINS_DIR", dir)
var stdout, stderr bytes.Buffer
cmd := installCmd(nil)
cmd.SetOut(&stdout)
cmd.SetErr(&stderr)
cmd.SetIn(strings.NewReader(""))
cmd.SetArgs([]string{"datum/alpha"})
if err := cmd.Execute(); err != nil {
t.Fatalf("unexpected error: %v\n%s%s", err, stdout.String(), stderr.String())
}
if !strings.Contains(stdout.String(), "Installed alpha") {
t.Fatalf("want install report on stdout:\n%s", stdout.String())
}
const notice = "warning: alpha is deprecated: use beta"
if !strings.Contains(stderr.String(), notice) || strings.Contains(stdout.String(), "deprecated") {
t.Fatalf("notice must be on stderr only; stdout:\n%s\nstderr:\n%s", stdout.String(), stderr.String())
}
m, err := pluginstore.Load(dir)
if err != nil || m.Plugins["alpha"] == nil {
t.Fatalf("record not saved: %v", err)
}
}

func TestInstallRestore_deprecatedPrintsNotice(t *testing.T) {
if runtime.GOOS == "windows" {
t.Skip("test builds a unix binary helper; skip on windows")
}
build := func(name string) pluginstore.Plugin {
bin := buildHelperBinary(t, `
package main

import (
"fmt"
"os"
)

func main() {
for _, a := range os.Args[1:] {
if a == "--plugin-manifest" {
fmt.Println(`+"`"+`{"name":"`+name+`","version":"v0.2.0","description":"x","api_version":1}`+"`"+`)
return
}
}
}
`)
data, err := os.ReadFile(bin)
if err != nil {
t.Fatal(err)
}
archive := makeTarGz(t, name, data)
url := serveArchive(t, archive)
return pluginstore.Plugin{
ObjectMeta: metav1.ObjectMeta{Name: name},
Spec: pluginstore.PluginSpec{
ShortDescription: name,
Version: "v0.2.0",
Platforms: []pluginstore.Platform{{URI: url + "/" + name + ".tar.gz", SHA256: sha256HexOf(archive)}},
},
}
}
alpha := build("alpha")
alpha.Spec.Deprecated = &pluginstore.Deprecation{Message: "use gamma"}
beta := build("beta")

dir := t.TempDir()
seedManifest(t, dir, map[string]*pluginstore.InstalledPlugin{
"alpha": installedEntry("datum", "v0.2.0"),
"beta": installedEntry("datum", "v0.2.0"),
})
seedFreshCache(t, dir, pluginstore.OfficialCatalogName, alpha, beta)

out, err := execPluginCmd(t, dir, installCmd(nil))
if err != nil {
t.Fatalf("unexpected error: %v\n%s", err, out)
}
for _, want := range []string{"Installed alpha", "Installed beta", "warning: alpha is deprecated: use gamma"} {
if !strings.Contains(out, want) {
t.Fatalf("want %q in output:\n%s", want, out)
}
}
if strings.Contains(out, "beta is deprecated") {
t.Fatalf("beta must get no notice:\n%s", out)
}
}
11 changes: 10 additions & 1 deletion internal/cmd/plugin/install.go
Original file line number Diff line number Diff line change
Expand Up @@ -238,7 +238,13 @@ func installFromCatalog(cmd *cobra.Command, pluginsDir string, reg *pluginstore.
// Record the catalog's canonical name (cat.Name), so "default/<plugin>"
// is stored as "datum".
idxEntry.Catalog = cat.Name
return saveAndReport(cmd, pluginsDir, name, idxEntry, binaryPath)
if err := saveAndReport(cmd, pluginsDir, name, idxEntry, binaryPath); err != nil {
return err
}
if p := pluginstore.FindInIndex(idx, name); p != nil {
writeDeprecationNotice(cmd.ErrOrStderr(), reg, name, p.Spec.Deprecated)
}
return nil
}

// installBareName resolves a bare plugin name across all catalogs (default
Expand Down Expand Up @@ -350,6 +356,9 @@ func installAllFromManifest(cmd *cobra.Command, pluginsDir, currentVersion strin
newEntry.Catalog = catalogName
manifest.Plugins[name] = newEntry
fmt.Fprintf(cmd.OutOrStdout(), "Installed %s %s from %s\n", name, newEntry.Version, catalogName)
if p := pluginstore.FindInIndex(idx, name); p != nil {
writeDeprecationNotice(cmd.ErrOrStderr(), reg, name, p.Spec.Deprecated)
}
}

if saveErr := pluginstore.Save(pluginsDir, manifest); saveErr != nil {
Expand Down
25 changes: 25 additions & 0 deletions internal/cmd/plugin/upgrade.go
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,7 @@ func upgradeOne(cmd *cobra.Command, pluginsDir string, manifest *pluginstore.Man
return customerrors.NewUserError(fmt.Sprintf("upgrade plugin %s: %v", name, err))
}
reportUpgrade(cmd, name, from, to, upgraded)
u.writeNotice(name, entry)
return nil
}

Expand Down Expand Up @@ -127,6 +128,7 @@ func upgradeAll(cmd *cobra.Command, pluginsDir string, manifest *pluginstore.Man
continue
}
reportUpgrade(cmd, name, from, to, upgraded)
u.writeNotice(name, entry)
}

if len(errs) > 0 {
Expand All @@ -152,6 +154,7 @@ type upgrader struct {
cmd *cobra.Command
pluginsDir string
manifest *pluginstore.Manifest
reg *pluginstore.Registry
currentVersion string
getIndex func(catalogName string) (*pluginstore.CachedIndex, error)
}
Expand All @@ -166,11 +169,33 @@ func newUpgrader(cmd *cobra.Command, pluginsDir string, manifest *pluginstore.Ma
cmd: cmd,
pluginsDir: pluginsDir,
manifest: manifest,
reg: reg,
currentVersion: currentVersion,
getIndex: catalogIndexLoader(cmd, pluginsDir, reg),
}, nil
}

// writeNotice prints the deprecation notice, if any, for a plugin that was
// just processed without error. Direct GitHub installs have no catalog entry
// and get none. The catalog is the one the plugin is recorded as installed
// from, so a plugin that moved to another catalog stops getting a notice.
func (u *upgrader) writeNotice(name string, entry *pluginstore.InstalledPlugin) {
if entry.Catalog == "" && strings.Contains(entry.Source, "/") {
return
}
catalogName := pluginstore.CanonicalCatalogName(entry.Catalog)
if catalogName == "" {
catalogName = pluginstore.OfficialCatalogName
}
idx, err := u.getIndex(catalogName)
if err != nil {
return
}
if p := pluginstore.FindInIndex(idx, name); p != nil {
writeDeprecationNotice(u.cmd.ErrOrStderr(), u.reg, name, p.Spec.Deprecated)
}
}

// upgrade brings one installed plugin to the latest version offered by the
// source it was installed from and records the result in plugins.json. It
// returns the latest version and whether a new version was installed; when the
Expand Down
Loading