logical/aws: help

builtin/logical/aws/backend.go

@@ -49,4 +49,8 @@ const backendHelp = `
 The AWS backend dynamically generates AWS access keys for a set of
 IAM policies. The AWS access keys have a configurable lease set and
 are automatically revoked at the end of the lease.
+
+After mounting this backend, credentials to generate IAM keys must
+be configured with the "root" path and policies must be written using
+the "policy/" endpoints before any access keys can be generated.
 `

builtin/logical/aws/path_policy.go

@@ -27,6 +27,9 @@ func pathPolicy() *framework.Path {
 		Callbacks: map[logical.Operation]framework.OperationFunc{
 			logical.WriteOperation: pathPolicyWrite,
 		},
+
+		HelpSynopsis:    pathPolicyHelpSyn,
+		HelpDescription: pathPolicyHelpDesc,
 	}
 }
 
@@ -49,3 +52,19 @@ func pathPolicyWrite(
 
 	return nil, nil
 }
+
+const pathPolicyHelpSyn = `
+Read and write IAM policies that access keys can be made for.
+`
+
+const pathPolicyHelpDesc = `
+This path allows you to read and write policies that are used to
+create access keys. These policies map directly to the route to read the
+access keys. For example, if the backend is mounted at "aws" and you
+wrote a policy to "aws/policy/deploy" then a user could request access
+credentials at "aws/deploy".
+
+The policies written are normal IAM policies. Vault will not attempt to
+parse these except to validate that they're basic JSON. To validate the
+keys, attempt to read an access key after writing the policy.
+`

builtin/logical/aws/path_root.go

@@ -28,6 +28,9 @@ func pathRoot() *framework.Path {
 		Callbacks: map[logical.Operation]framework.OperationFunc{
 			logical.WriteOperation: pathRootWrite,
 		},
+
+		HelpSynopsis:    pathRootHelpSyn,
+		HelpDescription: pathRootHelpDesc,
 	}
 }
 
@@ -54,3 +57,14 @@ type rootConfig struct {
 	SecretKey string `json:"secret_key"`
 	Region    string `json:"region"`
 }
+
+const pathRootHelpSyn = `
+Configure the root credentials that are used to manage IAM.
+`
+
+const pathRootHelpDesc = `
+Before doing anything, the AWS backend needs credentials that are able
+to manage IAM policies, users, access keys, etc. This endpoint is used
+to configure those credentials. They don't necessarilly need to be root
+keys as long as they have permission to manage IAM.
+`

builtin/logical/aws/path_user.go

@@ -23,6 +23,9 @@ func pathUser(b *backend) *framework.Path {
 		Callbacks: map[logical.Operation]framework.OperationFunc{
 			logical.ReadOperation: b.pathUserRead,
 		},
+
+		HelpSynopsis:    pathUserHelpSyn,
+		HelpDescription: pathUserHelpDesc,
 	}
 }
 
@@ -133,3 +136,17 @@ func pathUserRollback(req *logical.Request, _kind string, data interface{}) erro
 type walUser struct {
 	UserName string
 }
+
+const pathUserHelpSyn = `
+Generate an access key pair for a specific policy.
+`
+
+const pathUserHelpDesc = `
+This path will generate a new, never before used key pair for
+accessing AWS. The IAM policy used to back this key pair will be
+the "name" parameter. For example, if this backend is mounted at "aws",
+then "aws/deploy" would generate access keys for the "deploy" policy.
+
+The access keys will have a lease associated with them. The access keys
+can be revoked by using the Vault ID.
+`

logical/framework/backend.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"regexp"
 	"sort"
+	"strings"
 	"sync"
 	"time"
 
@@ -201,12 +202,12 @@ func (b *Backend) handleRootHelp() (*logical.Response, error) {
 		p := pathsMap[route]
 		pathData = append(pathData, rootHelpTemplatePath{
 			Path: route,
-			Help: p.HelpSynopsis,
+			Help: strings.TrimSpace(p.HelpSynopsis),
 		})
 	}
 
 	help, err := executeTemplate(rootHelpTemplate, &rootHelpTemplateData{
-		Help:  b.Help,
+		Help:  strings.TrimSpace(b.Help),
 		Paths: pathData,
 	})
 	if err != nil {

logical/framework/path.go

@@ -8,7 +8,6 @@ import (
 	"text/template"
 
 	"github.com/hashicorp/vault/logical"
-	"github.com/mitchellh/go-wordwrap"
 )
 
 // Path is a single path that the backend responds to.
@@ -59,8 +58,8 @@ func (p *Path) helpCallback(
 	var tplData pathTemplateData
 	tplData.Request = req.Path
 	tplData.RoutePattern = p.Pattern
-	tplData.Synopsis = wordwrap.WrapString(p.HelpSynopsis, 80)
+	tplData.Synopsis = strings.TrimSpace(p.HelpSynopsis)
-	tplData.Description = wordwrap.WrapString(p.HelpDescription, 80)
+	tplData.Description = strings.TrimSpace(p.HelpDescription)
 
 	// Alphabetize the fields
 	fieldKeys := make([]string, 0, len(p.Fields))
@@ -73,7 +72,7 @@ func (p *Path) helpCallback(
 	tplData.Fields = make([]pathTemplateFieldData, len(fieldKeys))
 	for i, k := range fieldKeys {
 		schema := p.Fields[k]
-		description := wordwrap.WrapString(schema.Description, 60)
+		description := strings.TrimSpace(schema.Description)
 		if description == "" {
 			description = "<no description>"
 		}