docs: API workspace agents and builds (#5538)

coderd/gitsshkey.go

@@ -100,6 +100,14 @@ func (api *API) gitSSHKey(rw http.ResponseWriter, r *http.Request) {
 	})
 }
 
+// @Summary Get workspace agent Git SSH key
+// @ID get-workspace-agent-git-ssh-key
+// @Security CoderSessionToken
+// @Accept json
+// @Produce json
+// @Tags Agents
+// @Success 200 {object} codersdk.AgentGitSSHKey
+// @Router /workspaceagents/me/gitsshkey [get]
 func (api *API) agentGitSSHKey(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	agent := httpmw.WorkspaceAgent(r)

coderd/workspaceagents.go

@@ -63,6 +63,14 @@ func (api *API) workspaceAgent(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, apiAgent)
 }
 
+// @Summary Get authorized workspace agent metadata
+// @ID get-authorized-workspace-agent-metadata
+// @Security CoderSessionToken
+// @Accept json
+// @Produce json
+// @Tags Agents
+// @Success 200 {object} codersdk.WorkspaceAgentMetadata
+// @Router /workspaceagents/me/metadata [get]
 func (api *API) workspaceAgentMetadata(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	workspaceAgent := httpmw.WorkspaceAgent(r)
@@ -138,6 +146,15 @@ func (api *API) workspaceAgentMetadata(rw http.ResponseWriter, r *http.Request)
 	})
 }
 
+// @Summary Submit workspace agent version
+// @ID submit-workspace-workspace-agent-version
+// @Security CoderSessionToken
+// @Produce application/json
+// @Tags Agents
+// @Param request body codersdk.PostWorkspaceAgentVersionRequest true "Version request"
+// @Success 200
+// @Router /workspaceagents/me/version [post]
+// @x-apidocgen {"skip": true}
 func (api *API) postWorkspaceAgentVersion(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	workspaceAgent := httpmw.WorkspaceAgent(r)
@@ -438,6 +455,15 @@ func (api *API) workspaceAgentConnection(rw http.ResponseWriter, r *http.Request
 	})
 }
 
+// @Summary Coordinate workspace agent via Tailnet
+// @Description It accepts a WebSocket connection to an agent that listens to
+// @Description incoming connections and publishes node updates.
+// @ID get-workspace-agent-git-ssh-key-via-tailnet
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Agents
+// @Success 101
+// @Router /workspaceagents/me/coordinate [get]
 func (api *API) workspaceAgentCoordinate(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 
@@ -757,6 +783,14 @@ func convertWorkspaceAgent(derpMap *tailcfg.DERPMap, coordinator tailnet.Coordin
 	return workspaceAgent, nil
 }
 
+// @Summary Submit workspace agent stats
+// @ID submit-workspace-workspace-agent-stats
+// @Security CoderSessionToken
+// @Produce application/json
+// @Tags Agents
+// @Param request body codersdk.AgentStats true "Stats request"
+// @Success 200 {object} codersdk.AgentStatsResponse
+// @Router /workspaceagents/me/report-stats [post]
 func (api *API) workspaceAgentReportStats(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 
@@ -826,6 +860,14 @@ func (api *API) workspaceAgentReportStats(rw http.ResponseWriter, r *http.Reques
 	})
 }
 
+// @Summary Submit workspace application health
+// @ID submit-workspace-workspace-agent-health
+// @Security CoderSessionToken
+// @Produce application/json
+// @Tags Agents
+// @Param request body codersdk.PostWorkspaceAppHealthsRequest true "Application health request"
+// @Success 200
+// @Router /workspaceagents/me/app-health [post]
 func (api *API) postWorkspaceAppHealth(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	workspaceAgent := httpmw.WorkspaceAgent(r)
@@ -941,8 +983,19 @@ func (api *API) postWorkspaceAppHealth(rw http.ResponseWriter, r *http.Request)
 	httpapi.Write(ctx, rw, http.StatusOK, nil)
 }
 
-// postWorkspaceAgentsGitAuth returns a username and password for use
+// workspaceAgentsGitAuth returns a username and password for use
 // with GIT_ASKPASS.
+//
+// @Summary Get workspace agent Git auth
+// @ID get-workspace-agent-git-auth
+// @Security CoderSessionToken
+// @Accept json
+// @Produce json
+// @Tags Agents
+// @Param url query string true "Git URL" format(uri)
+// @Param listen query bool false "Wait for a new token to be issued"
+// @Success 200 {object} codersdk.WorkspaceAgentGitAuthResponse
+// @Router /workspaceagents/me/gitauth [get]
 func (api *API) workspaceAgentsGitAuth(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	gitURL := r.URL.Query().Get("url")

coderd/workspacebuilds.go

@@ -23,6 +23,14 @@ import (
 	"github.com/coder/coder/codersdk"
 )
 
+// @Summary Get workspace build
+// @ID get-workspace-build
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Builds
+// @Param workspacebuild path string true "Workspace build ID"
+// @Success 200 {object} codersdk.WorkspaceBuild
+// @Router /workspacebuilds/{workspacebuild} [get]
 func (api *API) workspaceBuild(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	workspaceBuild := httpmw.WorkspaceBuildParam(r)
@@ -64,6 +72,18 @@ func (api *API) workspaceBuild(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, apiBuild)
 }
 
+// @Summary Get workspace builds by workspace ID
+// @ID get-workspace-builds-by-workspace-id
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Builds
+// @Param id path string true "Workspace ID" format(uuid)
+// @Param after_id query string false "After ID" format(uuid)
+// @Param limit query int false "Page limit"
+// @Param offset query int false "Page offset"
+// @Param since query string false "Since timestamp" format(date-time)
+// @Success 200 {array} codersdk.WorkspaceBuild
+// @Router /workspaces/{id}/builds [get]
 func (api *API) workspaceBuilds(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	workspace := httpmw.WorkspaceParam(r)
@@ -254,6 +274,19 @@ func (api *API) workspaceBuildByBuildNumber(rw http.ResponseWriter, r *http.Requ
 	httpapi.Write(ctx, rw, http.StatusOK, apiBuild)
 }
 
+// Azure supports instance identity verification:
+// https://docs.microsoft.com/en-us/azure/virtual-machines/windows/instance-metadata-service?tabs=linux#tabgroup_14
+//
+// @Summary Create workspace build
+// @ID create-workspace-build
+// @Security CoderSessionToken
+// @Accepts json
+// @Produce json
+// @Tags Builds
+// @Param id path string true "Workspace ID" format(uuid)
+// @Param request body codersdk.CreateWorkspaceBuildRequest true "Create workspace build request"
+// @Success 200 {object} codersdk.WorkspaceBuild
+// @Router /workspaces/{id}/builds [post]
 func (api *API) postWorkspaceBuilds(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	apiKey := httpmw.APIKey(r)
@@ -535,6 +568,14 @@ func (api *API) postWorkspaceBuilds(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusCreated, apiBuild)
 }
 
+// @Summary Cancel workspace build
+// @ID cancel-workspace-build
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Builds
+// @Param workspacebuild path string true "Workspace build ID"
+// @Success 200 {object} codersdk.Response
+// @Router /workspacebuilds/{workspacebuild}/cancel [patch]
 func (api *API) patchCancelWorkspaceBuild(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	workspaceBuild := httpmw.WorkspaceBuildParam(r)
@@ -630,6 +671,14 @@ func (api *API) verifyUserCanCancelWorkspaceBuilds(ctx context.Context, userID u
 	return slices.Contains(user.RBACRoles, rbac.RoleOwner()), nil // only user with "owner" role can cancel workspace builds
 }
 
+// @Summary Get workspace resources for workspace build
+// @ID get-workspace-resources-for-workspace-build
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Builds
+// @Param workspacebuild path string true "Workspace build ID"
+// @Success 200 {array} codersdk.WorkspaceResource
+// @Router /workspacebuilds/{workspacebuild}/resources [get]
 func (api *API) workspaceBuildResources(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	workspaceBuild := httpmw.WorkspaceBuildParam(r)
@@ -657,6 +706,17 @@ func (api *API) workspaceBuildResources(rw http.ResponseWriter, r *http.Request)
 	api.provisionerJobResources(rw, r, job)
 }
 
+// @Summary Get workspace build logs
+// @ID get-workspace-build-logs
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Builds
+// @Param workspacebuild path string true "Workspace build ID"
+// @Param before query int false "Before Unix timestamp"
+// @Param after query int false "After Unix timestamp"
+// @Param follow query bool false "Follow log stream"
+// @Success 200 {array} codersdk.ProvisionerJobLog
+// @Router /workspacebuilds/{workspacebuild}/logs [get]
 func (api *API) workspaceBuildLogs(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	workspaceBuild := httpmw.WorkspaceBuildParam(r)
@@ -684,6 +744,14 @@ func (api *API) workspaceBuildLogs(rw http.ResponseWriter, r *http.Request) {
 	api.provisionerJobLogs(rw, r, job)
 }
 
+// @Summary Get provisioner state for workspace build
+// @ID get-provisioner-state-for-workspace-build
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Builds
+// @Param workspacebuild path string true "Workspace build ID"
+// @Success 200 {object} codersdk.WorkspaceBuild
+// @Router /workspacebuilds/{workspacebuild}/state [get]
 func (api *API) workspaceBuildState(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	workspaceBuild := httpmw.WorkspaceBuildParam(r)

coderd/workspaceresourceauth.go

@@ -19,6 +19,15 @@ import (
 
 // Azure supports instance identity verification:
 // https://docs.microsoft.com/en-us/azure/virtual-machines/windows/instance-metadata-service?tabs=linux#tabgroup_14
+//
+// @Summary Authenticate agent on Azure instance
+// @ID authenticate-agent-on-azure-instance
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Agents
+// @Param request body codersdk.AzureInstanceIdentityToken true "Instance identity token"
+// @Success 200 {object} codersdk.WorkspaceAgentAuthenticateResponse
+// @Router /workspaceagents/azure-instance-identity [post]
 func (api *API) postWorkspaceAuthAzureInstanceIdentity(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	var req codersdk.AzureInstanceIdentityToken
@@ -36,6 +45,15 @@ func (api *API) postWorkspaceAuthAzureInstanceIdentity(rw http.ResponseWriter, r
 	api.handleAuthInstanceID(rw, r, instanceID)
 }
 
+// @Summary Authenticate agent on AWS instance
+// @ID authenticate-agent-on-aws-instance
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Agents
+// @Param request body codersdk.AWSInstanceIdentityToken true "Instance identity token"
+// @Success 200 {object} codersdk.WorkspaceAgentAuthenticateResponse
+// @Router /workspaceagents/aws-instance-identity [post]
+//
 // AWS supports instance identity verification:
 // https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html
 // Using this, we can exchange a signed instance payload for an agent token.
@@ -56,6 +74,15 @@ func (api *API) postWorkspaceAuthAWSInstanceIdentity(rw http.ResponseWriter, r *
 	api.handleAuthInstanceID(rw, r, identity.InstanceID)
 }
 
+// @Summary Authenticate agent on Google Cloud instance
+// @ID authenticate-agent-on-google-cloud-instance
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Agents
+// @Param request body codersdk.GoogleInstanceIdentityToken true "Instance identity token"
+// @Success 200 {object} codersdk.WorkspaceAgentAuthenticateResponse
+// @Router /workspaceagents/google-instance-identity [post]
+//
 // Google Compute Engine supports instance identity verification:
 // https://cloud.google.com/compute/docs/instances/verifying-instance-identity
 // Using this, we can exchange a signed instance payload for an agent token.