Merge branch 'master' into log-more-fields

applicationset/utils/template_functions.go

@@ -0,0 +1,71 @@
+package utils
+
+import (
+	"regexp"
+	"strings"
+
+	"sigs.k8s.io/yaml"
+)
+
+// SanitizeName sanitizes the name in accordance with the below rules
+// 1. contain no more than 253 characters
+// 2. contain only lowercase alphanumeric characters, '-' or '.'
+// 3. start and end with an alphanumeric character
+func SanitizeName(name string) string {
+	invalidDNSNameChars := regexp.MustCompile("[^-a-z0-9.]")
+	maxDNSNameLength := 253
+
+	name = strings.ToLower(name)
+	name = invalidDNSNameChars.ReplaceAllString(name, "-")
+	if len(name) > maxDNSNameLength {
+		name = name[:maxDNSNameLength]
+	}
+
+	return strings.Trim(name, "-.")
+}
+
+// This has been copied from helm and may be removed as soon as it is retrofited in sprig
+// toYAML takes an interface, marshals it to yaml, and returns a string. It will
+// always return a string, even on marshal error (empty string).
+//
+// This is designed to be called from a template.
+func toYAML(v interface{}) (string, error) {
+	data, err := yaml.Marshal(v)
+	if err != nil {
+		// Swallow errors inside of a template.
+		return "", err
+	}
+	return strings.TrimSuffix(string(data), "\n"), nil
+}
+
+// This has been copied from helm and may be removed as soon as it is retrofited in sprig
+// fromYAML converts a YAML document into a map[string]interface{}.
+//
+// This is not a general-purpose YAML parser, and will not parse all valid
+// YAML documents. Additionally, because its intended use is within templates
+// it tolerates errors. It will insert the returned error message string into
+// m["Error"] in the returned map.
+func fromYAML(str string) (map[string]interface{}, error) {
+	m := map[string]interface{}{}
+
+	if err := yaml.Unmarshal([]byte(str), &m); err != nil {
+		return nil, err
+	}
+	return m, nil
+}
+
+// This has been copied from helm and may be removed as soon as it is retrofited in sprig
+// fromYAMLArray converts a YAML array into a []interface{}.
+//
+// This is not a general-purpose YAML parser, and will not parse all valid
+// YAML documents. Additionally, because its intended use is within templates
+// it tolerates errors. It will insert the returned error message string as
+// the first and only item in the returned array.
+func fromYAMLArray(str string) ([]interface{}, error) {
+	a := []interface{}{}
+
+	if err := yaml.Unmarshal([]byte(str), &a); err != nil {
+		return nil, err
+	}
+	return a, nil
+}

applicationset/utils/utils.go

@@ -32,6 +32,9 @@ func init() {
 	delete(sprigFuncMap, "expandenv")
 	delete(sprigFuncMap, "getHostByName")
 	sprigFuncMap["normalize"] = SanitizeName
+	sprigFuncMap["toYaml"] = toYAML
+	sprigFuncMap["fromYaml"] = fromYAML
+	sprigFuncMap["fromYamlArray"] = fromYAMLArray
 }
 
 type Renderer interface {
@@ -431,23 +434,6 @@ func NormalizeBitbucketBasePath(basePath string) string {
 	return basePath
 }
 
-// SanitizeName sanitizes the name in accordance with the below rules
-// 1. contain no more than 253 characters
-// 2. contain only lowercase alphanumeric characters, '-' or '.'
-// 3. start and end with an alphanumeric character
-func SanitizeName(name string) string {
-	invalidDNSNameChars := regexp.MustCompile("[^-a-z0-9.]")
-	maxDNSNameLength := 253
-
-	name = strings.ToLower(name)
-	name = invalidDNSNameChars.ReplaceAllString(name, "-")
-	if len(name) > maxDNSNameLength {
-		name = name[:maxDNSNameLength]
-	}
-
-	return strings.Trim(name, "-.")
-}
-
 func getTlsConfigWithCACert(scmRootCAPath string) *tls.Config {
 
 	tlsConfig := &tls.Config{}

applicationset/utils/utils_test.go

@@ -555,6 +555,64 @@ func TestRenderTemplateParamsGoTemplate(t *testing.T) {
 			templateOptions: []string{"missingkey=error"},
 			errorMessage:    `failed to execute go template --> {{.doesnotexist}} <--: template: :1:6: executing "" at <.doesnotexist>: map has no entry for key "doesnotexist"`,
 		},
+		{
+			name:        "toYaml",
+			fieldVal:    `{{ toYaml . | indent 2 }}`,
+			expectedVal: "  foo:\n    bar:\n      bool: true\n      number: 2\n      str: Hello world",
+			params: map[string]interface{}{
+				"foo": map[string]interface{}{
+					"bar": map[string]interface{}{
+						"bool":   true,
+						"number": 2,
+						"str":    "Hello world",
+					},
+				},
+			},
+		},
+		{
+			name:         "toYaml Error",
+			fieldVal:     `{{ toYaml . | indent 2 }}`,
+			expectedVal:  "  foo:\n    bar:\n      bool: true\n      number: 2\n      str: Hello world",
+			errorMessage: "failed to execute go template {{ toYaml . | indent 2 }}: template: :1:3: executing \"\" at <toYaml .>: error calling toYaml: error marshaling into JSON: json: unsupported type: func(*string)",
+			params: map[string]interface{}{
+				"foo": func(test *string) {
+				},
+			},
+		},
+		{
+			name:        "fromYaml",
+			fieldVal:    `{{ get (fromYaml .value) "hello" }}`,
+			expectedVal: "world",
+			params: map[string]interface{}{
+				"value": "hello: world",
+			},
+		},
+		{
+			name:         "fromYaml error",
+			fieldVal:     `{{ get (fromYaml .value) "hello" }}`,
+			expectedVal:  "world",
+			errorMessage: "failed to execute go template {{ get (fromYaml .value) \"hello\" }}: template: :1:8: executing \"\" at <fromYaml .value>: error calling fromYaml: error unmarshaling JSON: while decoding JSON: json: cannot unmarshal string into Go value of type map[string]interface {}",
+			params: map[string]interface{}{
+				"value": "non\n compliant\n yaml",
+			},
+		},
+		{
+			name:        "fromYamlArray",
+			fieldVal:    `{{ fromYamlArray .value | last }}`,
+			expectedVal: "bonjour tout le monde",
+			params: map[string]interface{}{
+				"value": "- hello world\n- bonjour tout le monde",
+			},
+		},
+		{
+			name:         "fromYamlArray error",
+			fieldVal:     `{{ fromYamlArray .value | last }}`,
+			expectedVal:  "bonjour tout le monde",
+			errorMessage: "failed to execute go template {{ fromYamlArray .value | last }}: template: :1:3: executing \"\" at <fromYamlArray .value>: error calling fromYamlArray: error unmarshaling JSON: while decoding JSON: json: cannot unmarshal string into Go value of type []interface {}",
+			params: map[string]interface{}{
+				"value": "non\n compliant\n yaml",
+			},
+		},
 	}
 
 	for _, test := range tests {

cmd/argocd/commands/account.go

@@ -26,12 +26,26 @@ import (
 	"github.com/argoproj/argo-cd/v2/util/io"
 	"github.com/argoproj/argo-cd/v2/util/localconfig"
 	sessionutil "github.com/argoproj/argo-cd/v2/util/session"
+	"github.com/argoproj/argo-cd/v2/util/templates"
 )
 
 func NewAccountCommand(clientOpts *argocdclient.ClientOptions) *cobra.Command {
 	var command = &cobra.Command{
 		Use:   "account",
 		Short: "Manage account settings",
+		Example: templates.Examples(`
+			# List accounts
+			argocd account list
+
+			# Update the current user's password
+			argocd account update-password
+
+			# Can I sync any app?
+			argocd account can-i sync applications '*'
+
+			# Get User information
+			argocd account get-user-info
+		`),
 		Run: func(c *cobra.Command, args []string) {
 			c.HelpFunc()(c, args)
 			os.Exit(1)
@@ -143,6 +157,13 @@ func NewAccountGetUserInfoCommand(clientOpts *argocdclient.ClientOptions) *cobra
 	var command = &cobra.Command{
 		Use:   "get-user-info",
 		Short: "Get user info",
+		Example: templates.Examples(`
+			# Get User information for the currently logged-in user (see 'argocd login')
+			argocd account get-user-info
+
+			# Get User information in yaml format
+			argocd account get-user-info -o yaml
+		`),
 		Run: func(c *cobra.Command, args []string) {
 			ctx := c.Context()
 

cmd/argocd/commands/app_actions.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"github.com/argoproj/argo-cd/v2/util/templates"
 	"os"
 	"strconv"
 	"text/tabwriter"
@@ -33,11 +34,22 @@ type DisplayedAction struct {
 	Disabled bool
 }
 
+var (
+	appActionExample = templates.Examples(`
+	# List all the available actions for an application
+	argocd app actions list APPNAME
+
+	# Run an available action for an application
+	argocd app actions run APPNAME ACTION --kind KIND [--resource-name RESOURCE] [--namespace NAMESPACE] [--group GROUP]
+	`)
+)
+
 // NewApplicationResourceActionsCommand returns a new instance of an `argocd app actions` command
 func NewApplicationResourceActionsCommand(clientOpts *argocdclient.ClientOptions) *cobra.Command {
 	var command = &cobra.Command{
-		Use:   "actions",
-		Short: "Manage Resource actions",
+		Use:     "actions",
+		Short:   "Manage Resource actions",
+		Example: appActionExample,
 		Run: func(c *cobra.Command, args []string) {
 			c.HelpFunc()(c, args)
 			os.Exit(1)
@@ -58,6 +70,10 @@ func NewApplicationResourceActionsListCommand(clientOpts *argocdclient.ClientOpt
 	var command = &cobra.Command{
 		Use:   "list APPNAME",
 		Short: "Lists available actions on a resource",
+		Example: templates.Examples(`
+	# List all the available actions for an application
+	argocd app actions list APPNAME
+	`),
 	}
 	command.Run = func(c *cobra.Command, args []string) {
 		ctx := c.Context()
@@ -136,6 +152,10 @@ func NewApplicationResourceActionsRunCommand(clientOpts *argocdclient.ClientOpti
 	var command = &cobra.Command{
 		Use:   "run APPNAME ACTION",
 		Short: "Runs an available action on resource(s)",
+		Example: templates.Examples(`
+	# Run an available action for an application
+	argocd app actions run APPNAME ACTION --kind KIND [--resource-name RESOURCE] [--namespace NAMESPACE] [--group GROUP]
+	`),
 	}
 
 	command.Flags().StringVar(&resourceName, "resource-name", "", "Name of resource")

cmd/argocd/commands/completion.go

@@ -211,6 +211,13 @@ compdef _argocd argocd
 Optionally, also add the following, in case you are getting errors involving compdef & compinit such as command not found: compdef:
 autoload -Uz compinit
 compinit 
+`,
+		Example: `# For bash
+$ source <(argocd completion bash)
+
+# For zsh
+$ argocd completion zsh > _argocd
+$ source _argocd
 `,
 		Run: func(cmd *cobra.Command, args []string) {
 			if len(args) != 1 {

cmd/argocd/commands/context.go

@@ -22,6 +22,14 @@ func NewContextCommand(clientOpts *argocdclient.ClientOptions) *cobra.Command {
 		Use:     "context [CONTEXT]",
 		Aliases: []string{"ctx"},
 		Short:   "Switch between contexts",
+		Example: `# List Argo CD Contexts
+argocd context
+
+# Switch Argo CD context
+argocd context cd.argoproj.io
+
+# Delete Argo CD context
+argocd context cd.argoproj.io --delete`,
 		Run: func(c *cobra.Command, args []string) {
 
 			localCfg, err := localconfig.ReadLocalConfig(clientOpts.ConfigPath)

cmd/argocd/commands/logout.go

@@ -18,6 +18,10 @@ func NewLogoutCommand(globalClientOpts *argocdclient.ClientOptions) *cobra.Comma
 		Use:   "logout CONTEXT",
 		Short: "Log out from Argo CD",
 		Long:  "Log out from Argo CD",
+		Example: `# To log out of argocd
+$ argocd logout
+# This can be helpful for security reasons or when you want to switch between different Argo CD contexts or accounts.
+`,
 		Run: func(c *cobra.Command, args []string) {
 			if len(args) == 0 {
 				c.HelpFunc()(c, args)

cmd/argocd/commands/relogin.go

@@ -24,9 +24,10 @@ func NewReloginCommand(globalClientOpts *argocdclient.ClientOptions) *cobra.Comm
 		ssoPort  int
 	)
 	var command = &cobra.Command{
-		Use:   "relogin",
-		Short: "Refresh an expired authenticate token",
-		Long:  "Refresh an expired authenticate token",
+		Use:     "relogin",
+		Short:   "Refresh an expired authenticate token",
+		Long:    "Refresh an expired authenticate token",
+		Example: "argocd relogin --password YOUR_PASSWORD",
 		Run: func(c *cobra.Command, args []string) {
 			ctx := c.Context()
 

cmd/argocd/commands/repocreds.go

@@ -17,13 +17,24 @@ import (
 	"github.com/argoproj/argo-cd/v2/util/errors"
 	"github.com/argoproj/argo-cd/v2/util/git"
 	"github.com/argoproj/argo-cd/v2/util/io"
+	"github.com/argoproj/argo-cd/v2/util/templates"
 )
 
 // NewRepoCredsCommand returns a new instance of an `argocd repocreds` command
 func NewRepoCredsCommand(clientOpts *argocdclient.ClientOptions) *cobra.Command {
 	var command = &cobra.Command{
 		Use:   "repocreds",
 		Short: "Manage repository connection parameters",
+		Example: templates.Examples(`
+			# Add credentials with user/pass authentication to use for all repositories under the specified URL
+			argocd repocreds add URL --username USERNAME --password PASSWORD
+
+			# List all the configured repository credentials
+			argocd repocreds list
+
+			# Remove credentials for the repositories with speficied URL
+			argocd repocreds rm URL
+		`),
 		Run: func(c *cobra.Command, args []string) {
 			c.HelpFunc()(c, args)
 			os.Exit(1)
@@ -184,6 +195,10 @@ func NewRepoCredsRemoveCommand(clientOpts *argocdclient.ClientOptions) *cobra.Co
 	var command = &cobra.Command{
 		Use:   "rm CREDSURL",
 		Short: "Remove repository credentials",
+		Example: templates.Examples(`
+			# Remove credentials for the repositories with URL https://git.example.com/repos
+			argocd repocreds rm https://git.example.com/repos/
+		`),
 		Run: func(c *cobra.Command, args []string) {
 			ctx := c.Context()
 
@@ -231,6 +246,13 @@ func NewRepoCredsListCommand(clientOpts *argocdclient.ClientOptions) *cobra.Comm
 	var command = &cobra.Command{
 		Use:   "list",
 		Short: "List configured repository credentials",
+		Example: templates.Examples(`
+			# List all the configured repository credentials
+			argocd repocreds list
+
+			# List all the configured repository credentials in json format
+			argocd repocreds list -o json
+		`),
 		Run: func(c *cobra.Command, args []string) {
 			ctx := c.Context()
 

docs/operator-manual/applicationset/GoTemplate.md

@@ -174,6 +174,18 @@ It is also possible to use Sprig functions to construct the path variables manua
 | `{{path.filenameNormalized}}` | `{{.path.filenameNormalized}}` | `{{normalize .path.filename}}` |
 | `{{path[N]}}` | `-` | `{{index .path.segments N}}` |
 
+## Available template functions
+
+ApplicationSet controller provides:
+
+- all [sprig](http://masterminds.github.io/sprig/) Go templates function except `env`, `expandenv` and `getHostByName`
+- `normalize`: sanitizes the input so that it complies with the following rules:
+  1. contains no more than 253 characters
+  2. contains only lowercase alphanumeric characters, '-' or '.'
+  3. starts and ends with an alphanumeric character
+- `toYaml` / `fromYaml` / `fromYamlArray` helm like functions
+
+
 ## Examples
 
 ### Basic Go template usage