ap: refactor deployment apis to provider+id-based model by ilackarms · Pull Request #209 · agentregistry-dev/agentregistry

ilackarms · 2026-02-23T17:45:55Z

Description

The deployments API had mixed identity models (name/version vs ID), outdated update semantics, and duplicated client/server code paths. This refactor aligns deployments on a single provider-based, ID-first model and removes legacy flows.

Change Type

/kind breaking_change
/kind cleanup
/kind design

Changelog

refactor deployment apis to provider+id-based model

peterj · 2026-02-24T16:07:34Z

internal/client/client.go

-	if err != nil {
-		return nil, err
+// DeployServer deploys a server with configuration.
+func (c *Client) DeployServer(name, version string, config map[string]string, preferRemote bool, provider string) (*DeploymentResponse, error) {


while you're at it here, can we remove the prefereRemote?

later we should think about adding a similar arg that would tell us whether the user prefers OCI, Github source, npx/pypi, remote, etc. (basically different package types a server can have)

shashankram · 2026-02-24T16:29:06Z

internal/client/client.go

-func (c *Client) DeployAgent(name, version string, config map[string]string, runtimeTarget string) (*DeploymentResponse, error) {
+func (c *Client) DeployAgent(name, version string, config map[string]string, provider string) (*DeploymentResponse, error) {
+	if provider == "" {
+		provider = "docker"


could you define an enum for the providers

shashankram · 2026-02-24T16:42:22Z

internal/registry/api/handlers/v0/builtin_providers.go

+	DefaultKubernetesProviderID = "kubernetes-default"
+)
+
+var errBuiltinProviderReadOnly = errors.New("builtin providers are read-only")


What is the purpose of this? What does read-only refer to?

peterj · 2026-02-24T16:57:32Z

internal/registry/api/handlers/v0/deployments.go

-		if err != nil {
-			return nil, huma.Error400BadRequest("Invalid version encoding", err)
+		if adapter, ok := extensions.ResolveDeploymentAdapter(deployment.Provider); ok {
+			err = adapter.Undeploy(ctx, deployment)


can we rename this "Undeploy" to "Remove"?

peterj · 2026-02-24T16:59:25Z

internal/registry/api/handlers/v0/deployments.go

+			return &struct{}{}, nil
+		}
+
+		if deployment.Provider == "docker" || deployment.Provider == "kubernetes" {


could we do this check early on?

I mean before we resolve for deployment adapters

peterj · 2026-02-24T17:12:29Z

internal/registry/api/handlers/v0/providers.go

+		provider, err := adapter.CreateProvider(ctx, &input.Body)
+		if err != nil {
+			if errors.Is(err, errBuiltinProviderReadOnly) {
+				return nil, huma.Error400BadRequest("Provider is read-only")


what's the concept of "read-only"?

peterj · 2026-02-24T17:31:34Z

pkg/models/deployment.go

-	Runtime      string            `json:"runtime"`      // "local" or "kubernetes"
-	IsExternal   bool              `json:"isExternal"`   // true if not managed by registry
+	ID              string            `json:"id"`
+	ServerName      string            `json:"serverName"`   // resource name (legacy field name retained for compatibility)


can we remove the ServerName is we aren't using it anymore?

peterj · 2026-02-24T17:32:10Z

pkg/models/deployment.go

+	Version         string            `json:"version"`
+	Provider        string            `json:"provider"` // "docker", "kubernetes", "gcp", "aws"


Suggested change

Version string `json:"version"`

Provider string `json:"provider"` // "docker", "kubernetes", "gcp", "aws"

Provider string `json:"provider"` // "docker", "kubernetes"

peterj · 2026-02-24T17:32:44Z

pkg/models/deployment.go

 type DeploymentFilter struct {
-	Runtime      *string // "local" or "kubernetes"
-	ResourceType *string // "mcp" or "agent"
+	Provider      *string // docker, kubernetes, gcp, aws


Suggested change

Provider *string // docker, kubernetes, gcp, aws

Provider *string // docker, kubernetes

peterj · 2026-02-24T17:33:04Z

pkg/models/provider.go

+type Provider struct {
+	ID        string         `json:"id"`
+	Name      string         `json:"name"`
+	Platform  string         `json:"platform"` // local, kubernetes, gcp, aws


Suggested change

Platform string `json:"platform"` // local, kubernetes, gcp, aws

Platform string `json:"platform"` // local, kubernetes

peterj · 2026-02-24T17:37:43Z

internal/registry/service/registry_service.go


+func mapProviderToBackend(provider string) string {
+	if provider == "kubernetes" {
+		return "kubernetes"


is there a way we could ahe these as consts as we're referring to them in a lot of places

peterj

added some comments

peterj · 2026-02-25T23:47:59Z

internal/cli/agent/deploy.go

  arctl agent deploy my-agent --version latest
  arctl agent deploy my-agent --version 1.2.3
-  arctl agent deploy my-agent --version latest --runtime kubernetes`,
+  arctl agent deploy my-agent --version latest --provider-id kubernetes-default`,


can't this just be 'kubernetes' instead of 'kubernetes-default'?

peterj · 2026-02-25T23:48:30Z

internal/cli/agent/deploy.go

-	if runtime == "" {
-		runtime = "local"
+	if providerID == "" {
+		providerID = "local"


is local docker or is provider local and then platform is docker? (we'll need to make sure we document these terms)

peterj · 2026-02-25T23:50:26Z

pkg/models/deployment.go

-	Runtime      string            `json:"runtime"`      // "local" or "kubernetes"
-	IsExternal   bool              `json:"isExternal"`   // true if not managed by registry
+	ID              string            `json:"id"`
+	ServerName      string            `json:"serverName"` // resource name (legacy field name retained for compatibility)


can we remove this ServerName?

…y-dev#209)  # Description  The deployments API had mixed identity models (name/version vs ID), outdated update semantics, and duplicated client/server code paths. This refactor aligns deployments on a single provider-based, ID-first model and removes legacy flows. # Change Type  /kind breaking_change /kind cleanup /kind design # Changelog  ```release-note refactor deployment apis to provider+id-based model ```

github-actions bot added kind/cleanup release-note kind/breaking_change kind/design labels Feb 23, 2026

ilackarms force-pushed the api-refactor-6 branch 2 times, most recently from 894ea1c to c612482 Compare February 23, 2026 20:48

peterj reviewed Feb 24, 2026

View reviewed changes

shashankram reviewed Feb 24, 2026

View reviewed changes

peterj reviewed Feb 24, 2026

View reviewed changes

peterj requested changes Feb 24, 2026

View reviewed changes

refactor deployment + provider routes using extensions

c922bf9

ilackarms force-pushed the api-refactor-6 branch from 7cc723e to c922bf9 Compare February 24, 2026 23:33

ilackarms added 2 commits February 25, 2026 12:38

pr feedback

30d3e68

lint

536df41

peterj reviewed Feb 25, 2026

View reviewed changes

peterj approved these changes Feb 25, 2026

View reviewed changes

ilackarms added 2 commits February 25, 2026 20:58

clarify config vs env in deployment

f335283

fix config -> env field name

8e7a790

peterj merged commit 50741c8 into main Feb 26, 2026
5 checks passed

		Version string `json:"version"`
		Provider string `json:"provider"` // "docker", "kubernetes", "gcp", "aws"

	Provider *string // docker, kubernetes, gcp, aws
	Provider *string // docker, kubernetes

	Platform string `json:"platform"` // local, kubernetes, gcp, aws
	Platform string `json:"platform"` // local, kubernetes

Conversation

ilackarms commented Feb 23, 2026

Description

Change Type

Changelog

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

peterj Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

peterj left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

peterj Feb 24, 2026 •

edited

Loading