UserTasks: add title per issue type (#52479)

This PR changes the API to return the issue type title.

lib/usertasks/descriptions.go

@@ -21,37 +21,52 @@ package usertasks
 import (
 	"embed"
 	"fmt"
+	"strings"
 )
 
 //go:embed descriptions/*.md
 var descriptionsFS embed.FS
 
-func loadIssueDescription(issueType string) string {
+func loadIssueTitleDescription(issueType string) (string, string) {
 	filename := fmt.Sprintf("descriptions/%s.md", issueType)
 	bs, err := descriptionsFS.ReadFile(filename)
 	if err != nil {
-		return ""
+		return "", ""
 	}
-	return string(bs)
+
+	documentParts := strings.SplitN(string(bs), "\n", 2)
+	if len(documentParts) != 2 {
+		return "", ""
+	}
+
+	title := documentParts[0]
+	if !strings.HasPrefix(title, "# ") {
+		return "", ""
+	}
+	title = title[2:]
+
+	description := strings.TrimSpace(documentParts[1])
+
+	return title, description
 }
 
 // DescriptionForDiscoverEC2Issue returns the description of the issue and fixing steps.
 // The returned string contains a markdown document.
 // If issue type is not recognized or doesn't have a specific description, them an empty string is returned.
-func DescriptionForDiscoverEC2Issue(issueType string) string {
-	return loadIssueDescription(issueType)
+func DescriptionForDiscoverEC2Issue(issueType string) (string, string) {
+	return loadIssueTitleDescription(issueType)
 }
 
 // DescriptionForDiscoverEKSIssue returns the description of the issue and fixing steps.
 // The returned string contains a markdown document.
 // If issue type is not recognized or doesn't have a specific description, them an empty string is returned.
-func DescriptionForDiscoverEKSIssue(issueType string) string {
-	return loadIssueDescription(issueType)
+func DescriptionForDiscoverEKSIssue(issueType string) (string, string) {
+	return loadIssueTitleDescription(issueType)
 }
 
 // DescriptionForDiscoverRDSIssue returns the description of the issue and fixing steps.
 // The returned string contains a markdown document.
 // If issue type is not recognized or doesn't have a specific description, them an empty string is returned.
-func DescriptionForDiscoverRDSIssue(issueType string) string {
-	return loadIssueDescription(issueType)
+func DescriptionForDiscoverRDSIssue(issueType string) (string, string) {
+	return loadIssueTitleDescription(issueType)
 }

lib/usertasks/descriptions/ec2-ssm-agent-connection-lost.md

@@ -1,3 +1,4 @@
+# SSM Agent lost connection
 Auto enrolling EC2 instances requires the SSM Agent to be installed and running on them.
 Some instances appear to have lost connection to Amazon Systems Manager.
 

lib/usertasks/descriptions/ec2-ssm-agent-not-registered.md

@@ -1,3 +1,4 @@
+# SSM Agent not registered
 Auto enrolling EC2 instances requires the SSM Agent to be installed and running on them.
 Some instances failed to connect to Amazon Systems Manager.
 

lib/usertasks/descriptions/ec2-ssm-invocation-failure.md

@@ -1,3 +1,4 @@
+# SSM Invocation failed
 Teleport failed to access the SSM Agent to auto enroll the instance.
 Some instances failed to communicate with the AWS Systems Manager service to execute the install script.
 

lib/usertasks/descriptions/ec2-ssm-script-failure.md

@@ -1,3 +1,4 @@
+# SSM Script failure
 Teleport was able to reach the SSM Agent inside the EC2 instance, however the install script returned an error.
 
 You can click below in the Invocation URL and get further details on why the script failed.

lib/usertasks/descriptions/ec2-ssm-unsupported-os.md

@@ -1,3 +1,4 @@
+# Unsupported Operating System
 Auto enrolling EC2 instances requires a compatible Operating System.
 
 Teleport only supports Linux instances when auto-enrolling them into the cluster.

lib/usertasks/descriptions/eks-agent-not-connecting.md

@@ -1,3 +1,4 @@
+# Teleport Agent not connecting
 The process of automatically enrolling EKS Clusters into Teleport, starts by installing the [`teleport-kube-agent`](https://goteleport.com/docs/reference/helm-reference/teleport-kube-agent/) to the cluster.
 
 If the installation is successful, the EKS Cluster will appear in your Resources list.

lib/usertasks/descriptions/eks-authentication-mode-unsupported.md

@@ -1,3 +1,4 @@
+# Cluster authentication mode unsupported
 Teleport uses the Amazon EKS API to install the Teleport Kubernetes Agent.
 
 Please enable API (or API and Config Map) authentication mode in the following EKS Clusters so that they can be automatically enrolled.

lib/usertasks/descriptions/eks-cluster-unreachable.md

@@ -1,3 +1,4 @@
+# Unreachable cluster
 The EKS Cluster must be accessible from the Teleport Auth Service in order for Teleport to deploy the Teleport Kubernetes Agent.
 
 The following EKS Clusters couldn't be accessed.

lib/usertasks/descriptions/eks-missing-endpoint-public-access.md

@@ -1,3 +1,4 @@
+# Missing endpoint public access
 The EKS Cluster must be publicly accessible in order for Teleport to deploy the Teleport Kubernetes Agent.
 
 You can enable the public endpoint by accessing the Manage Endpoint Access.

lib/usertasks/descriptions/eks-status-not-active.md

@@ -1,3 +1,4 @@
+# Cluster status
 Only EKS Clusters whose status is active can be automatically enrolled into teleport.
 
 The following are not active.

lib/usertasks/descriptions/rds-iam-auth-disabled.md

@@ -1,3 +1,4 @@
+# IAM Auth disabled
 The Teleport Database Service uses [IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html) to communicate with RDS.
 
 The following RDS databases do not have IAM authentication enabled.

lib/usertasks/descriptions_test.go

@@ -27,13 +27,15 @@ import (
 )
 
 func TestAllDescriptions(t *testing.T) {
-	for _, issueType := range usertasksapi.DiscoverEC2IssueTypes {
-		require.NotEmpty(t, DescriptionForDiscoverEC2Issue(issueType), "issue type %q is missing descriptions/%s.md file", issueType, issueType)
-	}
-	for _, issueType := range usertasksapi.DiscoverEKSIssueTypes {
-		require.NotEmpty(t, DescriptionForDiscoverEKSIssue(issueType), "issue type %q is missing descriptions/%s.md file", issueType, issueType)
-	}
-	for _, issueType := range usertasksapi.DiscoverRDSIssueTypes {
-		require.NotEmpty(t, DescriptionForDiscoverRDSIssue(issueType), "issue type %q is missing descriptions/%s.md file", issueType, issueType)
+	for _, issueGroup := range [][]string{
+		usertasksapi.DiscoverEC2IssueTypes,
+		usertasksapi.DiscoverEKSIssueTypes,
+		usertasksapi.DiscoverRDSIssueTypes,
+	} {
+		for _, issueType := range issueGroup {
+			title, description := DescriptionForDiscoverEC2Issue(issueType)
+			require.NotEmpty(t, title, "issue type %q is missing title in descriptions/%s.md file", issueType, issueType)
+			require.NotEmpty(t, description, "issue type %q is missing description in descriptions/%s.md file", issueType, issueType)
+		}
 	}
 }

lib/web/ui/usertask.go

@@ -49,6 +49,8 @@ type UserTask struct {
 type UserTaskDetail struct {
 	// UserTask has the basic fields that all tasks include.
 	UserTask
+	// Title is the issue title.
+	Title string `json:"title,omitempty"`
 	// Description is a markdown document that explains the issue and how to fix it.
 	Description string `json:"description,omitempty"`
 	// DiscoverEC2 contains the task details for the DiscoverEC2 tasks.
@@ -97,6 +99,7 @@ func MakeUserTasks(uts []*usertasksv1.UserTask) []UserTask {
 
 // MakeDetailedUserTask creates a UI UserTask representation containing all the details.
 func MakeDetailedUserTask(ut *usertasksv1.UserTask) UserTaskDetail {
+	var title string
 	var description string
 
 	var discoverEC2 *usertasks.UserTaskDiscoverEC2WithURLs
@@ -105,20 +108,21 @@ func MakeDetailedUserTask(ut *usertasksv1.UserTask) UserTaskDetail {
 
 	switch ut.GetSpec().GetTaskType() {
 	case apiusertasks.TaskTypeDiscoverEC2:
-		description = usertasks.DescriptionForDiscoverEC2Issue(ut.GetSpec().GetIssueType())
+		title, description = usertasks.DescriptionForDiscoverEC2Issue(ut.GetSpec().GetIssueType())
 		discoverEC2 = usertasks.EC2InstancesWithURLs(ut)
 
 	case apiusertasks.TaskTypeDiscoverEKS:
-		description = usertasks.DescriptionForDiscoverEKSIssue(ut.GetSpec().GetIssueType())
+		title, description = usertasks.DescriptionForDiscoverEKSIssue(ut.GetSpec().GetIssueType())
 		discoverEKS = usertasks.EKSClustersWithURLs(ut)
 
 	case apiusertasks.TaskTypeDiscoverRDS:
-		description = usertasks.DescriptionForDiscoverRDSIssue(ut.GetSpec().GetIssueType())
+		title, description = usertasks.DescriptionForDiscoverRDSIssue(ut.GetSpec().GetIssueType())
 		discoverRDS = usertasks.RDSDatabasesWithURLs(ut)
 	}
 
 	return UserTaskDetail{
 		UserTask:    MakeUserTask(ut),
+		Title:       title,
 		Description: description,
 		DiscoverEC2: discoverEC2,
 		DiscoverEKS: discoverEKS,

lib/web/usertasks_test.go

@@ -141,6 +141,8 @@ func TestUserTask(t *testing.T) {
 		err = json.Unmarshal(resp.Bytes(), &userTaskDetailResp)
 		require.NoError(t, err)
 		require.Equal(t, "OPEN", userTaskDetailResp.State)
+		require.NotEmpty(t, userTaskDetailResp.Description)
+		require.NotEmpty(t, userTaskDetailResp.Title)
 		require.NotEmpty(t, userTaskDetailResp.DiscoverEC2)
 		lastStateChangeT0 := userTaskDetailResp.LastStateChange