Merge pull request #1113 from fluxcd/create-image-update

Add repo path and push branch to image update cmd

cmd/flux/create_image_policy.go

@@ -32,7 +32,7 @@ import (
 )
 
 var createImagePolicyCmd = &cobra.Command{
-	Use:   "policy <name>",
+	Use:   "policy [name]",
 	Short: "Create or update an ImagePolicy object",
 	Long: `The create image policy command generates an ImagePolicy resource.
 An ImagePolicy object calculates a "latest image" given an image
@@ -40,6 +40,18 @@ repository and a policy, e.g., semver.
 
 The image that sorts highest according to the policy is recorded in
 the status of the object.`,
+	Example: `  # Create an ImagePolicy to select the latest stable release
+  flux create image policy podinfo \
+    --image-ref=podinfo \
+    --select-semver=">=1.0.0"
+
+  # Create an ImagePolicy to select the latest main branch build tagged as "${GIT_BRANCH}-${GIT_SHA:0:7}-$(date +%s)"
+  flux create image policy podinfo \
+    --image-ref=podinfo \
+    --select-numeric=asc \
+	--filter-regex='^main-[a-f0-9]+-(?P<ts>[0-9]+)' \
+	--filter-extract='$ts'
+`,
 	RunE: createImagePolicyRun}
 
 type imagePolicyFlags struct {

cmd/flux/create_image_repository.go

@@ -30,7 +30,7 @@ import (
 )
 
 var createImageRepositoryCmd = &cobra.Command{
-	Use:   "repository <name>",
+	Use:   "repository [name]",
 	Short: "Create or update an ImageRepository object",
 	Long: `The create image repository command generates an ImageRepository resource.
 An ImageRepository object specifies an image repository to scan.`,

cmd/flux/create_image_update.go

@@ -28,19 +28,38 @@ import (
 )
 
 var createImageUpdateCmd = &cobra.Command{
-	Use:   "update <name>",
+	Use:   "update [name]",
 	Short: "Create or update an ImageUpdateAutomation object",
 	Long: `The create image update command generates an ImageUpdateAutomation resource.
 An ImageUpdateAutomation object specifies an automated update to images
 mentioned in YAMLs in a git repository.`,
+	Example: `  # Configure image updates for the main repository created by flux bootstrap
+  flux create image update flux-system \
+    --git-repo-ref=flux-system \
+    --git-repo-path="./clusters/my-cluster" \
+    --checkout-branch=main \
+	--author-name=flux \
+	--author-email=flux@example.com \
+	--commit-template="{{range .Updated.Images}}{{println .}}{{end}}"
+
+  # Configure image updates to push changes to a different branch, if the branch doesn't exists it will be created
+  flux create image update flux-system \
+    --git-repo-ref=flux-system \
+    --git-repo-path="./clusters/my-cluster" \
+    --checkout-branch=main \
+    --push-branch=image-updates \
+	--author-name=flux \
+	--author-email=flux@example.com \
+	--commit-template="{{range .Updated.Images}}{{println .}}{{end}}"
+`,
 	RunE: createImageUpdateRun,
 }
 
 type imageUpdateFlags struct {
-	// git checkout spec
-	gitRepoRef string
-	branch     string
-	// commit spec
+	gitRepoRef     string
+	gitRepoPath    string
+	checkoutBranch string
+	pushBranch     string
 	commitTemplate string
 	authorName     string
 	authorEmail    string
@@ -50,8 +69,10 @@ var imageUpdateArgs = imageUpdateFlags{}
 
 func init() {
 	flags := createImageUpdateCmd.Flags()
-	flags.StringVar(&imageUpdateArgs.gitRepoRef, "git-repo-ref", "", "the name of a GitRepository resource with details of the upstream git repository")
-	flags.StringVar(&imageUpdateArgs.branch, "branch", "", "the branch to checkout and push commits to")
+	flags.StringVar(&imageUpdateArgs.gitRepoRef, "git-repo-ref", "", "the name of a GitRepository resource with details of the upstream Git repository")
+	flags.StringVar(&imageUpdateArgs.gitRepoPath, "git-repo-path", "", "path to the directory containing the manifests to be updated, defaults to the repository root")
+	flags.StringVar(&imageUpdateArgs.checkoutBranch, "checkout-branch", "", "the branch to checkout")
+	flags.StringVar(&imageUpdateArgs.pushBranch, "push-branch", "", "the branch to push commits to, defaults to the checkout branch if not specified")
 	flags.StringVar(&imageUpdateArgs.commitTemplate, "commit-template", "", "a template for commit messages")
 	flags.StringVar(&imageUpdateArgs.authorName, "author-name", "", "the name to use for commit author")
 	flags.StringVar(&imageUpdateArgs.authorEmail, "author-email", "", "the email to use for commit author")
@@ -69,8 +90,16 @@ func createImageUpdateRun(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("a reference to a GitRepository is required (--git-repo-ref)")
 	}
 
-	if imageUpdateArgs.branch == "" {
-		return fmt.Errorf("the Git repository branch is required (--branch)")
+	if imageUpdateArgs.checkoutBranch == "" {
+		return fmt.Errorf("the Git repository branch is required (--checkout-branch)")
+	}
+
+	if imageUpdateArgs.authorName == "" {
+		return fmt.Errorf("the author name is required (--author-name)")
+	}
+
+	if imageUpdateArgs.authorEmail == "" {
+		return fmt.Errorf("the author email is required (--author-email)")
 	}
 
 	labels, err := parseLabels()
@@ -89,9 +118,11 @@ func createImageUpdateRun(cmd *cobra.Command, args []string) error {
 				GitRepositoryRef: meta.LocalObjectReference{
 					Name: imageUpdateArgs.gitRepoRef,
 				},
-				Branch: imageUpdateArgs.branch,
+				Branch: imageUpdateArgs.checkoutBranch,
+			},
+			Interval: metav1.Duration{
+				Duration: createArgs.interval,
 			},
-			Interval: metav1.Duration{Duration: createArgs.interval},
 			Commit: autov1.CommitSpec{
 				AuthorName:      imageUpdateArgs.authorName,
 				AuthorEmail:     imageUpdateArgs.authorEmail,
@@ -100,6 +131,19 @@ func createImageUpdateRun(cmd *cobra.Command, args []string) error {
 		},
 	}
 
+	if imageUpdateArgs.pushBranch != "" {
+		update.Spec.Push = &autov1.PushSpec{
+			Branch: imageUpdateArgs.pushBranch,
+		}
+	}
+
+	if imageUpdateArgs.gitRepoPath != "" {
+		update.Spec.Update = &autov1.UpdateStrategy{
+			Path:     imageUpdateArgs.gitRepoPath,
+			Strategy: autov1.UpdateStrategySetters,
+		}
+	}
+
 	if createArgs.export {
 		return printExport(exportImageUpdate(&update))
 	}

cmd/flux/logs.go

@@ -21,38 +21,37 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
-	"github.com/fluxcd/flux2/internal/flags"
-	"github.com/fluxcd/flux2/internal/utils"
-	"github.com/spf13/cobra"
 	"html/template"
 	"io"
+	"os"
+	"strings"
+	"sync"
+
+	"github.com/spf13/cobra"
 	corev1 "k8s.io/api/core/v1"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 	"k8s.io/client-go/kubernetes"
 	"k8s.io/client-go/rest"
-	"os"
-	"strings"
-	"sync"
+
+	"github.com/fluxcd/flux2/internal/flags"
+	"github.com/fluxcd/flux2/internal/utils"
 )
 
 var logsCmd = &cobra.Command{
 	Use:   "logs",
-	Short: "Display formatted logs for toolkit components",
-	Long:  "The logs command displays formatted logs from various toolkit components.",
-	Example: `# Get logs from toolkit components
-	 flux logs
+	Short: "Display formatted logs for Flux components",
+	Long:  "The logs command displays formatted logs from various Flux components.",
+	Example: `  # Print the reconciliation logs of all Flux custom resources in your cluster
+	 flux logs --all-namespaces
 
-	# Stream logs from toolkit components
-	flux logs --follow
- 
-	# Get logs from toolkit components in a particular namespace
-	flux logs --flux-namespace my-namespace
+	# Stream logs for a particular log level
+	flux logs --follow --level=error --all-namespaces
 
-	# Get logs for a particular log level
-	flux logs --level=info
+	# Filter logs by kind, name and namespace
+	flux logs --kind=Kustomization --name=podinfo --namespace=default
 
-	# Filter logs by kind, name, or namespace
-	flux logs --kind=kustomization --name podinfo --namespace default
+	# Print logs when Flux is installed in a different namespace than flux-system
+	flux logs --flux-namespace=my-namespace
     `,
 	RunE: logsCmdRun,
 }
@@ -75,9 +74,9 @@ func init() {
 	logsCmd.Flags().Var(&logsArgs.logLevel, "level", logsArgs.logLevel.Description())
 	logsCmd.Flags().StringVarP(&logsArgs.kind, "kind", "", logsArgs.kind, "displays errors of a particular toolkit kind e.g GitRepository")
 	logsCmd.Flags().StringVarP(&logsArgs.name, "name", "", logsArgs.name, "specifies the name of the object logs to be displayed")
-	logsCmd.Flags().BoolVarP(&logsArgs.follow, "follow", "f", logsArgs.follow, "Specifies if the logs should be streamed")
+	logsCmd.Flags().BoolVarP(&logsArgs.follow, "follow", "f", logsArgs.follow, "specifies if the logs should be streamed")
 	logsCmd.Flags().Int64VarP(&logsArgs.tail, "tail", "", logsArgs.tail, "lines of recent log file to display")
-	logsCmd.Flags().StringVarP(&logsArgs.fluxNamespace, "flux-namespace", "", rootArgs.defaults.Namespace, "the namespace where the Flux components are running.")
+	logsCmd.Flags().StringVarP(&logsArgs.fluxNamespace, "flux-namespace", "", rootArgs.defaults.Namespace, "the namespace where the Flux components are running")
 	logsCmd.Flags().BoolVarP(&logsArgs.allNamespaces, "all-namespaces", "A", false, "displays logs for objects across all namespaces")
 	rootCmd.AddCommand(logsCmd)
 }

docs/cmd/flux.md

@@ -85,7 +85,7 @@ Command line utility for assembling Kubernetes CD pipelines the GitOps way.
 * [flux export](flux_export.md)	 - Export resources in YAML format
 * [flux get](flux_get.md)	 - Get sources and resources
 * [flux install](flux_install.md)	 - Install or upgrade Flux
-* [flux logs](flux_logs.md)	 - Display formatted logs for toolkit components
+* [flux logs](flux_logs.md)	 - Display formatted logs for Flux components
 * [flux reconcile](flux_reconcile.md)	 - Reconcile sources and resources
 * [flux resume](flux_resume.md)	 - Resume suspended resources
 * [flux suspend](flux_suspend.md)	 - Suspend resources

docs/cmd/flux_create_image_policy.md

@@ -12,7 +12,24 @@ The image that sorts highest according to the policy is recorded in
 the status of the object.
 
 ```
-flux create image policy <name> [flags]
+flux create image policy [name] [flags]
+```
+
+### Examples
+
+```
+  # Create an ImagePolicy to select the latest stable release
+  flux create image policy podinfo \
+    --image-ref=podinfo \
+    --select-semver=">=1.0.0"
+
+  # Create an ImagePolicy to select the latest main branch build tagged as "${GIT_BRANCH}-${GIT_SHA:0:7}-$(date +%s)"
+  flux create image policy podinfo \
+    --image-ref=podinfo \
+    --select-numeric=asc \
+	--filter-regex='^main-[a-f0-9]+-(?P<ts>[0-9]+)' \
+	--filter-extract='$ts'
+
 ```
 
 ### Options

docs/cmd/flux_create_image_repository.md

@@ -8,7 +8,7 @@ The create image repository command generates an ImageRepository resource.
 An ImageRepository object specifies an image repository to scan.
 
 ```
-flux create image repository <name> [flags]
+flux create image repository [name] [flags]
 ```
 
 ### Examples

docs/cmd/flux_create_image_update.md

@@ -9,7 +9,31 @@ An ImageUpdateAutomation object specifies an automated update to images
 mentioned in YAMLs in a git repository.
 
 ```
-flux create image update <name> [flags]
+flux create image update [name] [flags]
+```
+
+### Examples
+
+```
+  # Configure image updates for the main repository created by flux bootstrap
+  flux create image update flux-system \
+    --git-repo-ref=flux-system \
+    --git-repo-path="./clusters/my-cluster" \
+    --checkout-branch=main \
+	--author-name=flux \
+	--author-email=flux@example.com \
+	--commit-template="{{range .Updated.Images}}{{println .}}{{end}}"
+
+  # Configure image updates to push changes to a different branch, if the branch doesn't exists it will be created
+  flux create image update flux-system \
+    --git-repo-ref=flux-system \
+    --git-repo-path="./clusters/my-cluster" \
+    --checkout-branch=main \
+    --push-branch=image-updates \
+	--author-name=flux \
+	--author-email=flux@example.com \
+	--commit-template="{{range .Updated.Images}}{{println .}}{{end}}"
+
 ```
 
 ### Options
@@ -17,10 +41,12 @@ flux create image update <name> [flags]
 ```
       --author-email string      the email to use for commit author
       --author-name string       the name to use for commit author
-      --branch string            the branch to checkout and push commits to
+      --checkout-branch string   the branch to checkout
       --commit-template string   a template for commit messages
-      --git-repo-ref string      the name of a GitRepository resource with details of the upstream git repository
+      --git-repo-path string     path to the directory containing the manifests to be updated, defaults to the repository root
+      --git-repo-ref string      the name of a GitRepository resource with details of the upstream Git repository
   -h, --help                     help for update
+      --push-branch string       the branch to push commits to, defaults to the checkout branch if not specified
 ```
 
 ### Options inherited from parent commands

docs/cmd/flux_logs.md

@@ -1,10 +1,10 @@
 ## flux logs
 
-Display formatted logs for toolkit components
+Display formatted logs for Flux components
 
 ### Synopsis
 
-The logs command displays formatted logs from various toolkit components.
+The logs command displays formatted logs from various Flux components.
 
 ```
 flux logs [flags]
@@ -13,20 +13,17 @@ flux logs [flags]
 ### Examples
 
 ```
-# Get logs from toolkit components
-	 flux logs
+  # Print the reconciliation logs of all Flux custom resources in your cluster
+	 flux logs --all-namespaces
 
-	# Stream logs from toolkit components
-	flux logs --follow
- 
-	# Get logs from toolkit components in a particular namespace
-	flux logs --flux-namespace my-namespace
+	# Stream logs for a particular log level
+	flux logs --follow --level=error --all-namespaces
 
-	# Get logs for a particular log level
-	flux logs --level=info
+	# Filter logs by kind, name and namespace
+	flux logs --kind=Kustomization --name=podinfo --namespace=default
 
-	# Filter logs by kind, name, or namespace
-	flux logs --kind=kustomization --name podinfo --namespace default
+	# Print logs when Flux is installed in a different namespace than flux-system
+	flux logs --flux-namespace=my-namespace
     
 ```
 
@@ -34,8 +31,8 @@ flux logs [flags]
 
 ```
   -A, --all-namespaces          displays logs for objects across all namespaces
-      --flux-namespace string   the namespace where the Flux components are running. (default "flux-system")
-  -f, --follow                  Specifies if the logs should be streamed
+      --flux-namespace string   the namespace where the Flux components are running (default "flux-system")
+  -f, --follow                  specifies if the logs should be streamed
   -h, --help                    help for logs
       --kind string             displays errors of a particular toolkit kind e.g GitRepository
       --level logLevel          log level, available options are: (debug, info, error)