(documentation) Vault Setup documentation (#2366)

* add vault documentation

* fix test

* fix typo

Co-authored-by: Oliver Nocon <33484802+OliverNocon@users.noreply.github.com>

documentation/docs/infrastructure/vault.md

@@ -0,0 +1,36 @@
+# Vault for Pipeline Secrets
+
+Project "Piper" also supports fetching your pipeline secrets directly from [Vault](https://www.hashicorp.com/products/vault).
+Currently Vault's key value engine is supported in version 1 and 2, although we recommend version 2 since it supports versioning of secrets
+
+Parameters that support being fetched from Vault are marked with the Vault Label in the Step Documentation.
+
+![Vault Label](../images/parameter-with-vault-support.png)
+
+
+## Vault Setup
+
+The first step to store your pipeline secrets in vault, is to enable a the [Key-Value Engine](https://www.vaultproject.io/docs/secrets/kv/kv-v2). And then create a policy which grants read access to the key value engine.
+For Piper to authenticate against Vault, [AppRole](https://www.vaultproject.io/docs/auth/approle) authentication must be enabled in your Vault instance.
+You have to [create an AppRole Role](https://www.vaultproject.io/api-docs/auth/approle#create-update-approle) for Piper and assign it the necessary policies.
+
+## Store Your Vault Credentials In Jenkins
+
+Take the role ID from your Vault AppRole and create a Jenkins `Secret Text` credential. Do the same for the Vault AppRole secret ID.
+
+![Create two jenkins secret text credentials](../images/jenkins-vault-credential.png)
+
+## Pipline Configuration
+
+For pipelines to actually use the secrets stored in Vault you need to adjust your `config.yml`
+
+```yml
+general:
+  ...
+  vaultAppRoleTokenCredentialsId: '<JENKINS_CREDENTIAL_ID_FOR_VAULT_APPROLE_ROLE_ID>'
+  vaultAppRoleSecretTokenCredentialsId: 'JENKINS_CREDENTIAL_ID_FOR_VAULT_APPROLE_SECRET_ID'
+  vaultPath: 'kv/my-pipeline' # the path under which your jenkins secrets are stored
+  vaultServerUrl: '<YOUR_VAULT_SERVER_URL>'
+  vaultNamespace: '<YOUR_NAMESPACE_NAME>' # if you are not using vault's namespace feature you can remove this line
+  ...
+```

documentation/mkdocs.yml

@@ -6,6 +6,7 @@ nav:
     - 'Infrastructure':
         - 'Overview': infrastructure/overview.md
         - 'Custom Jenkins Setup': infrastructure/customjenkins.md
+        - 'Vault For Pipline Secrets': infrastructure/vault.md
     - 'Pipelines':
         - 'ABAP Environment pipeline':
             - 'Introduction': pipelines/abapEnvironment/introduction.md

pkg/documentation/generator/parameters.go

@@ -66,6 +66,10 @@ func parameterFurtherInfo(paramName string, stepData *config.StepData) string {
 		if paramName == param.Name {
 			if param.Secret {
 				secretInfo := "[![Secret](https://img.shields.io/badge/-Secret-yellowgreen)](#) pass via ENV or Jenkins credentials"
+				if param.GetReference("vaultSecret") != nil {
+					secretInfo = " [![Vault](https://img.shields.io/badge/-Vault-lightgrey)](#) [![Secret](https://img.shields.io/badge/-Secret-yellowgreen)](/) pass via ENV, Vault or Jenkins credentials"
+
+				}
 				for _, res := range param.ResourceRef {
 					if res.Type == "secret" {
 						secretInfo += fmt.Sprintf(" ([`%v`](#%v))", res.Name, strings.ToLower(res.Name))
@@ -251,9 +255,18 @@ func resourceReferenceDetails(resourceRef []config.ResourceReference) string {
 				resourceDetails += fmt.Sprintf("&nbsp;&nbsp;- `%v`%v<br />", alias.Name, ifThenElse(alias.Deprecated, " (**Deprecated**)", ""))
 			}
 			resourceDetails += fmt.Sprintf("&nbsp;&nbsp;id: [`%v`](#%v)<br />", resource.Name, strings.ToLower(resource.Name))
-			resourceDetails += fmt.Sprintf("&nbsp;&nbsp;reference to: `%v`<br />", resource.Param)
+			resourceDetails += fmt.Sprintf("&nbsp;&nbsp;reference to: `%v`<br /><br />", resource.Param)
 			continue
 		}
+
+		if resource.Type == "vaultSecret" {
+			resourceDetails += "Vault paths: <br />"
+			resourceDetails += "<ul>"
+			for _, path := range resource.Paths[0:1] {
+				resourceDetails += fmt.Sprintf("<li>`%s`</li>", path)
+			}
+			resourceDetails += "</ul>"
+		}
 	}
 
 	return resourceDetails

pkg/documentation/generator/parameters_test.go

@@ -263,7 +263,7 @@ func TestResourceReferenceDetails(t *testing.T) {
 			resourceRef: []config.ResourceReference{
 				{Name: "testCredentialId", Aliases: []config.Alias{}, Type: "secret", Param: "password"},
 			},
-			expected: "Jenkins credential id:<br />&nbsp;&nbsp;id: [`testCredentialId`](#testcredentialid)<br />&nbsp;&nbsp;reference to: `password`<br />",
+			expected: "Jenkins credential id:<br />&nbsp;&nbsp;id: [`testCredentialId`](#testcredentialid)<br />&nbsp;&nbsp;reference to: `password`<br /><br />",
 		},
 		{
 			resourceRef: []config.ResourceReference{