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
29 changes: 28 additions & 1 deletion datumctl/plugins/publishing-catalogs.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,7 @@
| `spec.description` | Optional | Longer text shown when inspecting the plugin. |
| `spec.homepage` | Optional | The plugin's homepage. |
| `spec.platforms` | Yes | One entry per supported OS/arch. |
| `spec.deprecated` | Optional | Marks the plugin as deprecated and names its replacement. See [Deprecating a plugin](#deprecating-a-plugin). |

**Each entry under `spec.platforms`:**

Expand All @@ -93,7 +94,7 @@

## Validating before you publish

Lint a manifest before you ship it. The validator reports missing plugin names or versions, missing or non-HTTPS download URIs, missing checksums, and invalid platform selectors:
Lint a manifest before you ship it. The validator reports missing plugin names or versions, missing or non-HTTPS download URIs, missing checksums, invalid platform selectors, and `deprecated` blocks that have no `message` or no `replacement.catalog`:

Check warning on line 97 in datumctl/plugins/publishing-catalogs.mdx

View check run for this annotation

Mintlify / Mintlify Validation (datum-4926dda5) - vale-spellcheck

datumctl/plugins/publishing-catalogs.mdx#L97

Did you really mean 'validator'?

```bash
# Validate a local manifest
Expand Down Expand Up @@ -132,6 +133,32 @@

See [Adding catalogs](/datumctl/plugins/adding-catalogs#enterprise-guardrails) for how allow-list entries are matched.

## Deprecating a plugin

When a plugin moves to another catalog, removing its entry right away breaks `datumctl plugin upgrade` for everyone who installed it from your catalog. Instead, keep the entry and mark it deprecated with a message and the plugin that replaces it:

```yaml
spec:
# ...version, platforms, and other fields as before
deprecated:
message: deploy moved to the ACME Platform catalog.
replacement:
catalog: acme-platform/datumctl-plugins # a catalog source, as `plugin index add` takes
name: deploy # optional; defaults to this plugin's name
```

| Field | Required | Purpose |
|-------|----------|---------|
| `deprecated.message` | Yes | Explains why the plugin is deprecated or where it went. |
| `deprecated.replacement.catalog` | Yes | The catalog source of the replacement plugin. |
| `deprecated.replacement.name` | Optional | The replacement plugin's name. Defaults to the deprecated plugin's name. |

`replacement.catalog` is a catalog source, not a catalog name, because each user picks their own name when they add a catalog. datumctl recognizes the replacement's catalog by comparing sources. For GitHub sources, it matches by owner and repository regardless of case or branch, so `acme-platform/datumctl-plugins`, `github.com/acme-platform/datumctl-plugins`, and `https://raw.githubusercontent.com/acme-platform/datumctl-plugins/main/index.yaml` all name the same catalog.

Users who install, restore, or upgrade a deprecated plugin see a warning that names the replacement and the commands to switch to it. See [Deprecated plugins](/datumctl/plugins/using-plugins#deprecated-plugins).

A deprecated entry stays installable and upgradable until you remove it from your catalog. Keep publishing releases to it during the deprecation period. datumctl releases without deprecation support ignore the `deprecated` block and keep installing and upgrading the plugin as usual.

## Versioning guidance

`spec.version` is the version datumctl installs when a user runs `datumctl plugin install <name>` without pinning. Users can pin a specific version with `datumctl plugin install <name>@<version>`.
Expand Down
27 changes: 26 additions & 1 deletion datumctl/plugins/using-plugins.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@
Without a version, datumctl installs the release GitHub marks as latest. If the repository has published only pre-releases, datumctl installs the highest pre-release instead, and `datumctl plugin upgrade` follows newer pre-releases the same way.

<Info>
If a bare name exists in more than one catalog, datumctl lists the matches instead of guessing. Qualify the name with its catalog (for example `acme/deploy`) to choose.
If a bare name exists in more than one catalog, datumctl lists the matches instead of guessing. Qualify the name with its catalog (for example `acme/deploy`) to choose. A deprecated plugin and its same-named replacement don't count as a collision; see [Deprecated plugins](#deprecated-plugins).
</Info>

### Pinning a version
Expand Down Expand Up @@ -154,9 +154,34 @@

`plugin upgrade` runs the same verified install flow as a fresh install.

### Deprecated plugins

When a catalog marks a plugin as deprecated, usually because it moved to another catalog, datumctl prints a warning when you install, restore, or upgrade that plugin. `plugin upgrade` prints it whether or not a newer version was installed. The install or upgrade still completes. The warning names the replacement and the commands to switch to it:

```text
warning: deploy is deprecated: deploy moved to the ACME Platform catalog.
To switch to the replacement:
datumctl plugin index add acme-platform acme-platform/datumctl-plugins
datumctl plugin install acme-platform/deploy
```

If you already added the replacement's catalog, the warning shows only the `datumctl plugin install` line, using the name you gave that catalog. If your organization's policy disables that catalog, the warning says so instead of suggesting commands.

Run the suggested commands to switch. After `datumctl plugin install <catalog>/<name>`, datumctl records the plugin as installed from the new catalog, so `plugin upgrade` uses that catalog and the warning stops. Plugins installed directly from a GitHub release never show this warning.

After you add the replacement's catalog, a bare-name install such as `datumctl plugin install ipam` installs the replacement when it has the same name. datumctl doesn't report that the name exists in multiple catalogs. It first prints this note to stderr, once for each deprecated match it skips:

```text
note: <name> in <catalog> is deprecated; installing its replacement from <catalog>
```

If other catalogs also have a plugin with that name, the collision error lists only those catalogs and the replacement. A replacement with a different name isn't picked this way. Install it with `datumctl plugin install <catalog>/<new-name>`.

`datumctl plugin install --all-available` skips a deprecated plugin you haven't installed and prints `Skipped <name>: deprecated`. A deprecated plugin you already have is still upgraded, or reported as up to date, and datumctl prints its deprecation warning.

## How plugins stay trustworthy

datumctl treats a plugin as untrusted code and protects you in a few ways:

Check warning on line 184 in datumctl/plugins/using-plugins.mdx

View check run for this annotation

Mintlify / Mintlify Validation (datum-4926dda5) - vale-spellcheck

datumctl/plugins/using-plugins.mdx#L184

Did you really mean 'untrusted'?

- **HTTPS-only downloads.** Plugin archives and catalog manifests are fetched over HTTPS only. Downloads to private, loopback, or link-local addresses are refused, and redirects are re-checked on every hop.
- **Checksum verification on every run.** datumctl records a SHA256 fingerprint of each plugin binary at install time and verifies it *every time the plugin runs*. If a managed plugin binary is modified after installation, datumctl refuses to run it.
Expand Down
Loading