Allow pinning garm-agent version and UX improvements

This change allows operators to pin the garm-agent version to a known
good version that works with their setup. This should prevent situations
where we do an update to the GARM agent, the controller automatically
updates to latest and a potential requirement we added (ie: mandatory TLS)
breaks their setup, or if the latest version of the agent requires a newer
version of the agent.

This change also gives users the ability to see available versions, with
release notes directly in GARM, so they can decide whether or not they
want to update. This is surfaced by both the CLI and the Web UI.

Signed-off-by: Gabriel Adrian Samfira <gsamfira@cloudbasesolutions.com>

Author: gabriel-samfira

apiserver/controllers/metadata.go

@@ -155,6 +155,30 @@ func (a *APIController) AdminGARMToolsHandler(w http.ResponseWriter, r *http.Req
 	}
 }
 
+// swagger:route GET /tools/garm-agent/releases tools ListGARMAgentReleases
+//
+// List the garm-agent releases available at the controller's releases URL,
+// as recorded in the cached release index. The release the controller is
+// pinned to and the release "latest" resolves to are marked.
+//
+//	Responses:
+//	  200: GARMAgentReleases
+//	  400: APIErrorResponse
+func (a *APIController) ListGARMAgentReleasesHandler(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+
+	releases, err := a.r.ListGARMAgentReleases(ctx)
+	if err != nil {
+		handleError(ctx, w, err)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	if err := json.NewEncoder(w).Encode(releases); err != nil {
+		slog.With(slog.Any("error", err)).ErrorContext(ctx, "failed to encode response")
+	}
+}
+
 func (a *APIController) InstanceShowGARMToolHandler(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 

apiserver/routers/routers.go

@@ -267,6 +267,9 @@ func NewAPIRouter(han *controllers.APIController, authMiddleware, initMiddleware
 	///////////////////////////////////////////////////////
 	// Tools URLs (garm agent, cached gitea runner, etc) //
 	///////////////////////////////////////////////////////
+	// List garm-agent releases available upstream (from the cached release index)
+	apiRouter.Handle("/tools/garm-agent/releases/", http.HandlerFunc(han.ListGARMAgentReleasesHandler)).Methods("GET", "OPTIONS")
+	apiRouter.Handle("/tools/garm-agent/releases", http.HandlerFunc(han.ListGARMAgentReleasesHandler)).Methods("GET", "OPTIONS")
 	apiRouter.Handle("/tools/garm-agent/", http.HandlerFunc(han.AdminGARMToolsHandler)).Methods("GET", "OPTIONS")
 	apiRouter.Handle("/tools/garm-agent", http.HandlerFunc(han.AdminGARMToolsHandler)).Methods("GET", "OPTIONS")
 	// Upload garm agent tool

apiserver/swagger-models.yaml

@@ -442,6 +442,22 @@ definitions:
     type: object
     x-go-type:
         type: GARMAgentTool
+        import:
+            package: github.com/cloudbase/garm/params
+            alias: garm_params
+  GARMAgentReleases:
+    type: array
+    x-go-type:
+        type: GARMAgentReleases
+        import:
+            package: github.com/cloudbase/garm/params
+            alias: garm_params
+    items:
+        $ref: '#/definitions/GARMAgentRelease'
+  GARMAgentRelease:
+    type: object
+    x-go-type:
+        type: GARMAgentRelease
         import:
             package: github.com/cloudbase/garm/params
             alias: garm_params

apiserver/swagger.yaml

@@ -185,6 +185,22 @@ definitions:
                 alias: garm_params
                 package: github.com/cloudbase/garm/params
             type: ForgeInstances
+    GARMAgentRelease:
+        type: object
+        x-go-type:
+            import:
+                alias: garm_params
+                package: github.com/cloudbase/garm/params
+            type: GARMAgentRelease
+    GARMAgentReleases:
+        items:
+            $ref: '#/definitions/GARMAgentRelease'
+        type: array
+        x-go-type:
+            import:
+                alias: garm_params
+                package: github.com/cloudbase/garm/params
+            type: GARMAgentReleases
     GARMAgentTool:
         type: object
         x-go-type:
@@ -3030,6 +3046,24 @@ paths:
             summary: Upload a GARM agent tool binary.
             tags:
                 - tools
+    /tools/garm-agent/releases:
+        get:
+            description: |-
+                as recorded in the cached release index. The release the controller is
+                pinned to and the release "latest" resolves to are marked.
+            operationId: ListGARMAgentReleases
+            responses:
+                "200":
+                    description: GARMAgentReleases
+                    schema:
+                        $ref: '#/definitions/GARMAgentReleases'
+                "400":
+                    description: APIErrorResponse
+                    schema:
+                        $ref: '#/definitions/APIErrorResponse'
+            summary: List the garm-agent releases available at the controller's releases URL,
+            tags:
+                - tools
 produces:
     - application/json
 security: