fix: rename ambiguous --skip-build to --require-built-images (#5619)

- hide skip-build flag, print warning when --skip-build is used

Signed-off-by: Ivan Mikheykin <ivan.mikheykin@flant.com>
Co-authored-by: Aleksei Igrychev <alexey.igrychev@flant.com>

cmd/werf/bundle/export/export.go

@@ -139,6 +139,7 @@ func NewCmd(ctx context.Context) *cobra.Command {
 	common.SetupParallelOptions(&commonCmdData, cmd, common.DefaultBuildParallelTasksLimit)
 
 	common.SetupSkipBuild(&commonCmdData, cmd)
+	common.SetupRequireBuiltImages(&commonCmdData, cmd)
 	commonCmdData.SetupPlatform(cmd)
 
 	common.SetupDisableAutoHostCleanup(&commonCmdData, cmd)
@@ -296,7 +297,7 @@ func runExport(ctx context.Context, imagesToProcess build.ImagesToProcess) error
 		defer conveyorWithRetry.Terminate()
 
 		if err := conveyorWithRetry.WithRetryBlock(ctx, func(c *build.Conveyor) error {
-			if *commonCmdData.SkipBuild {
+			if common.GetRequireBuiltImages(ctx, &commonCmdData) {
 				shouldBeBuiltOptions, err := common.GetShouldBeBuiltOptions(&commonCmdData, giterminismManager, werfConfig)
 				if err != nil {
 					return err

cmd/werf/bundle/publish/publish.go

@@ -137,6 +137,7 @@ func NewCmd(ctx context.Context) *cobra.Command {
 	common.SetupDockerServerStoragePath(&commonCmdData, cmd)
 
 	common.SetupSkipBuild(&commonCmdData, cmd)
+	common.SetupRequireBuiltImages(&commonCmdData, cmd)
 	commonCmdData.SetupPlatform(cmd)
 
 	commonCmdData.SetupHelmCompatibleChart(cmd, false)
@@ -302,7 +303,7 @@ func runPublish(ctx context.Context, imagesToProcess build.ImagesToProcess) erro
 		defer conveyorWithRetry.Terminate()
 
 		if err := conveyorWithRetry.WithRetryBlock(ctx, func(c *build.Conveyor) error {
-			if *commonCmdData.SkipBuild {
+			if common.GetRequireBuiltImages(ctx, &commonCmdData) {
 				shouldBeBuiltOptions, err := common.GetShouldBeBuiltOptions(&commonCmdData, giterminismManager, werfConfig)
 				if err != nil {
 					return err

cmd/werf/common/cmd_data.go

@@ -54,8 +54,9 @@ type CmdData struct {
 	SecondaryStagesStorage *[]string
 	CacheStagesStorage     *[]string
 
-	SkipBuild *bool
-	StubTags  *bool
+	SkipBuild          *bool
+	RequireBuiltImages *bool
+	StubTags           *bool
 
 	AddCustomTag *[]string
 	UseCustomTag *string

cmd/werf/common/common.go

@@ -800,9 +800,19 @@ IMAGE_NAME is the name of an image or artifact described in werf.yaml, the namel
 STAGE_NAME should be one of the following: `+strings.Join(allStagesNames(), ", "))
 }
 
+// SetupSkipBuild
+// Deprecated. See [SetupRequireBuiltImages].
 func SetupSkipBuild(cmdData *CmdData, cmd *cobra.Command) {
 	cmdData.SkipBuild = new(bool)
-	cmd.Flags().BoolVarP(cmdData.SkipBuild, "skip-build", "Z", util.GetBoolEnvironmentDefaultFalse("WERF_SKIP_BUILD"), "Disable building of docker images, cached images in the repo should exist in the repo if werf.yaml contains at least one image description (default $WERF_SKIP_BUILD)")
+	cmd.Flags().BoolVarP(cmdData.SkipBuild, "skip-build", "", util.GetBoolEnvironmentDefaultFalse("WERF_SKIP_BUILD"), "DEPRECATED: use --require-built-images.")
+	_ = cmd.Flags().MarkHidden("skip-build")
+}
+
+// SetupRequireBuiltImages adds --require-built-images flag.
+// See also [quireBuiltImages].
+func SetupRequireBuiltImages(cmdData *CmdData, cmd *cobra.Command) {
+	cmdData.RequireBuiltImages = new(bool)
+	cmd.Flags().BoolVarP(cmdData.RequireBuiltImages, "require-built-images", "Z", util.GetBoolEnvironmentDefaultFalse("WERF_REQUIRE_BUILT_IMAGES"), "Requires all used images to be previously built and exist in repo. Exits with error if needed images are not cached and so require to run build instructions (default $WERF_REQUIRE_BUILT_IMAGES)")
 }
 
 func SetupStubTags(cmdData *CmdData, cmd *cobra.Command) {
@@ -1166,6 +1176,20 @@ func GetOptionalRelease(cmdData *CmdData) string {
 	return *cmdData.Release
 }
 
+// GetRequireBuiltImages returns true if --require-built-images is set or --skip-build is set.
+// There is no way to determine if both options are used, so no warning.
+func GetRequireBuiltImages(ctx context.Context, cmdData *CmdData) bool {
+	if cmdData.RequireBuiltImages != nil && *cmdData.RequireBuiltImages {
+		return true
+	}
+	// Support for deprecated option.
+	if cmdData.SkipBuild != nil && *cmdData.SkipBuild {
+		logboek.Context(ctx).Warn().LogF("DEPRECATED: use --require-built-images ($WERF_REQUIRE_BUILT_IMAGES) instead of --skip-build\n")
+		return true
+	}
+	return false
+}
+
 func GetIntrospectOptions(cmdData *CmdData, werfConfig *config.WerfConfig) (build.IntrospectOptions, error) {
 	isStageExist := func(sName string) bool {
 		for _, stageName := range allStagesNames() {

cmd/werf/compose/main.go

@@ -193,6 +193,7 @@ func newCmd(ctx context.Context, composeCmdName string, options *newCmdOptions)
 	common.SetupFinalRepo(&commonCmdData, cmd)
 
 	common.SetupSkipBuild(&commonCmdData, cmd)
+	common.SetupRequireBuiltImages(&commonCmdData, cmd)
 
 	if options.FollowSupport {
 		common.SetupFollow(&commonCmdData, cmd)
@@ -408,7 +409,7 @@ func run(ctx context.Context, containerBackend container_backend.ContainerBacken
 			defer conveyorWithRetry.Terminate()
 
 			if err := conveyorWithRetry.WithRetryBlock(ctx, func(c *build.Conveyor) error {
-				if *commonCmdData.SkipBuild {
+				if common.GetRequireBuiltImages(ctx, &commonCmdData) {
 					if err := c.ShouldBeBuilt(ctx, build.ShouldBeBuiltOptions{}); err != nil {
 						return err
 					}

cmd/werf/converge/converge.go

@@ -173,6 +173,7 @@ werf converge --repo registry.mydomain.com/web --env production`,
 
 	common.SetupParallelOptions(&commonCmdData, cmd, common.DefaultBuildParallelTasksLimit)
 	common.SetupSkipBuild(&commonCmdData, cmd)
+	common.SetupRequireBuiltImages(&commonCmdData, cmd)
 	commonCmdData.SetupPlatform(cmd)
 	common.SetupFollow(&commonCmdData, cmd)
 
@@ -344,7 +345,7 @@ func run(ctx context.Context, containerBackend container_backend.ContainerBacken
 		defer conveyorWithRetry.Terminate()
 
 		if err := conveyorWithRetry.WithRetryBlock(ctx, func(c *build.Conveyor) error {
-			if *commonCmdData.SkipBuild {
+			if common.GetRequireBuiltImages(ctx, &commonCmdData) {
 				shouldBeBuiltOptions, err := common.GetShouldBeBuiltOptions(&commonCmdData, giterminismManager, werfConfig)
 				if err != nil {
 					return err

cmd/werf/export/export.go

@@ -104,6 +104,7 @@ func NewExportCmd(ctx context.Context) *cobra.Command {
 	common.SetupFinalRepo(&commonCmdData, cmd)
 
 	common.SetupSkipBuild(&commonCmdData, cmd)
+	common.SetupRequireBuiltImages(&commonCmdData, cmd)
 
 	common.SetupDockerConfig(&commonCmdData, cmd, "Command needs granted permissions to read and pull images from the specified repo")
 	common.SetupInsecureRegistry(&commonCmdData, cmd)
@@ -265,7 +266,7 @@ func run(ctx context.Context, imagesToProcess build.ImagesToProcess, tagTemplate
 		return c.Export(ctx, build.ExportOptions{
 			BuildPhaseOptions: build.BuildPhaseOptions{
 				BuildOptions:      build.BuildOptions{SkipImageMetadataPublication: *commonCmdData.Dev},
-				ShouldBeBuiltMode: *commonCmdData.SkipBuild,
+				ShouldBeBuiltMode: common.GetRequireBuiltImages(ctx, &commonCmdData),
 			},
 			ExportPhaseOptions: build.ExportPhaseOptions{
 				ExportImageNameList: imageNameList,

cmd/werf/kube_run/kube_run.go

@@ -171,6 +171,7 @@ func NewCmd(ctx context.Context) *cobra.Command {
 	common.SetupFinalRepo(&commonCmdData, cmd)
 
 	common.SetupSkipBuild(&commonCmdData, cmd)
+	common.SetupRequireBuiltImages(&commonCmdData, cmd)
 
 	common.SetupFollow(&commonCmdData, cmd)
 
@@ -406,7 +407,7 @@ func run(ctx context.Context, pod, secret, namespace string, werfConfig *config.
 
 	var image string
 	if err := conveyorWithRetry.WithRetryBlock(ctx, func(c *build.Conveyor) error {
-		if *commonCmdData.SkipBuild {
+		if common.GetRequireBuiltImages(ctx, &commonCmdData) {
 			if err := c.ShouldBeBuilt(ctx, build.ShouldBeBuiltOptions{}); err != nil {
 				return err
 			}

cmd/werf/render/render.go

@@ -148,6 +148,7 @@ func NewCmd(ctx context.Context) *cobra.Command {
 	common.SetupParallelOptions(&commonCmdData, cmd, common.DefaultBuildParallelTasksLimit)
 
 	common.SetupSkipBuild(&commonCmdData, cmd)
+	common.SetupRequireBuiltImages(&commonCmdData, cmd)
 	commonCmdData.SetupPlatform(cmd)
 
 	cmd.Flags().BoolVarP(&cmdData.Validate, "validate", "", util.GetBoolEnvironmentDefaultFalse("WERF_VALIDATE"), "Validate your manifests against the Kubernetes cluster you are currently pointing at (default $WERF_VALIDATE)")
@@ -321,7 +322,7 @@ func runRender(ctx context.Context, imagesToProcess build.ImagesToProcess) error
 
 			if err := conveyorWithRetry.WithRetryBlock(ctx, func(c *build.Conveyor) error {
 				buildFunc := func(ctx context.Context) error {
-					if *commonCmdData.SkipBuild {
+					if common.GetRequireBuiltImages(ctx, &commonCmdData) {
 						shouldBeBuiltOptions, err := common.GetShouldBeBuiltOptions(&commonCmdData, giterminismManager, werfConfig)
 						if err != nil {
 							return err

cmd/werf/run/run.go

@@ -132,6 +132,7 @@ func NewCmd(ctx context.Context) *cobra.Command {
 	common.SetupFinalRepo(&commonCmdData, cmd)
 
 	common.SetupSkipBuild(&commonCmdData, cmd)
+	common.SetupRequireBuiltImages(&commonCmdData, cmd)
 
 	common.SetupFollow(&commonCmdData, cmd)
 
@@ -392,7 +393,7 @@ func run(ctx context.Context, containerBackend container_backend.ContainerBacken
 
 	var dockerImageName string
 	if err := conveyorWithRetry.WithRetryBlock(ctx, func(c *build.Conveyor) error {
-		if *commonCmdData.SkipBuild {
+		if common.GetRequireBuiltImages(ctx, &commonCmdData) {
 			if err := c.ShouldBeBuilt(ctx, build.ShouldBeBuiltOptions{}); err != nil {
 				return err
 			}

docs/_includes/reference/cli/werf_bundle_export.md

@@ -251,6 +251,10 @@ werf bundle export [IMAGE_NAME...] [options]
       --report-path=''
             DEPRECATED: use --save-build-report with optional --build-report-path.
             Report save path ($WERF_REPORT_PATH by default)
+  -Z, --require-built-images=false
+            Requires all used images to be previously built and exist in repo. Exits with error if  
+            needed images are not cached and so require to run build instructions (default          
+            $WERF_REQUIRE_BUILT_IMAGES)
       --save-build-report=false
             Save build report (by default $WERF_SAVE_BUILD_REPORT or false). Its path and format    
             configured with --build-report-path
@@ -274,9 +278,6 @@ werf bundle export [IMAGE_NAME...] [options]
             with commas: key1=val1,key2=val2).
             Also, can be defined with $WERF_SET_STRING_* (e.g. $WERF_SET_STRING_1=key1=val1,        
             $WERF_SET_STRING_2=key2=val2)
-  -Z, --skip-build=false
-            Disable building of docker images, cached images in the repo should exist in the repo   
-            if werf.yaml contains at least one image description (default $WERF_SKIP_BUILD)
   -L, --skip-dependencies-repo-refresh=false
             Do not refresh helm chart repositories locally cached index
       --skip-tls-verify-registry=false

docs/_includes/reference/cli/werf_bundle_publish.md

@@ -278,6 +278,10 @@ werf bundle publish [IMAGE_NAME...] [options]
       --report-path=''
             DEPRECATED: use --save-build-report with optional --build-report-path.
             Report save path ($WERF_REPORT_PATH by default)
+  -Z, --require-built-images=false
+            Requires all used images to be previously built and exist in repo. Exits with error if  
+            needed images are not cached and so require to run build instructions (default          
+            $WERF_REQUIRE_BUILT_IMAGES)
       --save-build-report=false
             Save build report (by default $WERF_SAVE_BUILD_REPORT or false). Its path and format    
             configured with --build-report-path
@@ -306,9 +310,6 @@ werf bundle publish [IMAGE_NAME...] [options]
             with commas: key1=val1,key2=val2).
             Also, can be defined with $WERF_SET_STRING_* (e.g. $WERF_SET_STRING_1=key1=val1,        
             $WERF_SET_STRING_2=key2=val2)
-  -Z, --skip-build=false
-            Disable building of docker images, cached images in the repo should exist in the repo   
-            if werf.yaml contains at least one image description (default $WERF_SKIP_BUILD)
   -L, --skip-dependencies-repo-refresh=false
             Do not refresh helm chart repositories locally cached index
       --skip-tls-verify-registry=false

docs/_includes/reference/cli/werf_compose_config.md

@@ -243,14 +243,15 @@ werf compose config [IMAGE_NAME...] [options] [--docker-compose-options="OPTIONS
             repo Selectel VPC (default $WERF_REPO_SELECTEL_VPC)
       --repo-selectel-vpc-id=''
             repo Selectel VPC ID (default $WERF_REPO_SELECTEL_VPC_ID)
+  -Z, --require-built-images=false
+            Requires all used images to be previously built and exist in repo. Exits with error if  
+            needed images are not cached and so require to run build instructions (default          
+            $WERF_REQUIRE_BUILT_IMAGES)
       --secondary-repo=[]
             Specify one or multiple secondary read-only repos with images that will be used as a    
             cache.
             Also, can be specified with $WERF_SECONDARY_REPO_* (e.g. $WERF_SECONDARY_REPO_1=...,    
             $WERF_SECONDARY_REPO_2=...)
-  -Z, --skip-build=false
-            Disable building of docker images, cached images in the repo should exist in the repo   
-            if werf.yaml contains at least one image description (default $WERF_SKIP_BUILD)
       --skip-tls-verify-registry=false
             Skip TLS certificate validation when accessing a registry (default                      
             $WERF_SKIP_TLS_VERIFY_REGISTRY)

docs/_includes/reference/cli/werf_compose_down.md

@@ -236,14 +236,15 @@ werf compose down [IMAGE_NAME...] [options] [--docker-compose-options="OPTIONS"]
             repo Selectel VPC (default $WERF_REPO_SELECTEL_VPC)
       --repo-selectel-vpc-id=''
             repo Selectel VPC ID (default $WERF_REPO_SELECTEL_VPC_ID)
+  -Z, --require-built-images=false
+            Requires all used images to be previously built and exist in repo. Exits with error if  
+            needed images are not cached and so require to run build instructions (default          
+            $WERF_REQUIRE_BUILT_IMAGES)
       --secondary-repo=[]
             Specify one or multiple secondary read-only repos with images that will be used as a    
             cache.
             Also, can be specified with $WERF_SECONDARY_REPO_* (e.g. $WERF_SECONDARY_REPO_1=...,    
             $WERF_SECONDARY_REPO_2=...)
-  -Z, --skip-build=false
-            Disable building of docker images, cached images in the repo should exist in the repo   
-            if werf.yaml contains at least one image description (default $WERF_SKIP_BUILD)
       --skip-tls-verify-registry=false
             Skip TLS certificate validation when accessing a registry (default                      
             $WERF_SKIP_TLS_VERIFY_REGISTRY)

docs/_includes/reference/cli/werf_compose_run.md

@@ -233,14 +233,15 @@ werf compose run [IMAGE_NAME...] [options] [--docker-compose-options="OPTIONS"]
             repo Selectel VPC (default $WERF_REPO_SELECTEL_VPC)
       --repo-selectel-vpc-id=''
             repo Selectel VPC ID (default $WERF_REPO_SELECTEL_VPC_ID)
+  -Z, --require-built-images=false
+            Requires all used images to be previously built and exist in repo. Exits with error if  
+            needed images are not cached and so require to run build instructions (default          
+            $WERF_REQUIRE_BUILT_IMAGES)
       --secondary-repo=[]
             Specify one or multiple secondary read-only repos with images that will be used as a    
             cache.
             Also, can be specified with $WERF_SECONDARY_REPO_* (e.g. $WERF_SECONDARY_REPO_1=...,    
             $WERF_SECONDARY_REPO_2=...)
-  -Z, --skip-build=false
-            Disable building of docker images, cached images in the repo should exist in the repo   
-            if werf.yaml contains at least one image description (default $WERF_SKIP_BUILD)
       --skip-tls-verify-registry=false
             Skip TLS certificate validation when accessing a registry (default                      
             $WERF_SKIP_TLS_VERIFY_REGISTRY)

docs/_includes/reference/cli/werf_compose_up.md

@@ -244,14 +244,15 @@ werf compose up [IMAGE_NAME...] [options] [--docker-compose-options="OPTIONS"] [
             repo Selectel VPC (default $WERF_REPO_SELECTEL_VPC)
       --repo-selectel-vpc-id=''
             repo Selectel VPC ID (default $WERF_REPO_SELECTEL_VPC_ID)
+  -Z, --require-built-images=false
+            Requires all used images to be previously built and exist in repo. Exits with error if  
+            needed images are not cached and so require to run build instructions (default          
+            $WERF_REQUIRE_BUILT_IMAGES)
       --secondary-repo=[]
             Specify one or multiple secondary read-only repos with images that will be used as a    
             cache.
             Also, can be specified with $WERF_SECONDARY_REPO_* (e.g. $WERF_SECONDARY_REPO_1=...,    
             $WERF_SECONDARY_REPO_2=...)
-  -Z, --skip-build=false
-            Disable building of docker images, cached images in the repo should exist in the repo   
-            if werf.yaml contains at least one image description (default $WERF_SKIP_BUILD)
       --skip-tls-verify-registry=false
             Skip TLS certificate validation when accessing a registry (default                      
             $WERF_SKIP_TLS_VERIFY_REGISTRY)

docs/_includes/reference/cli/werf_converge.md

@@ -318,6 +318,10 @@ werf converge --repo registry.mydomain.com/web --env production
       --report-path=''
             DEPRECATED: use --save-build-report with optional --build-report-path.
             Report save path ($WERF_REPORT_PATH by default)
+  -Z, --require-built-images=false
+            Requires all used images to be previously built and exist in repo. Exits with error if  
+            needed images are not cached and so require to run build instructions (default          
+            $WERF_REQUIRE_BUILT_IMAGES)
       --save-build-report=false
             Save build report (by default $WERF_SAVE_BUILD_REPORT or false). Its path and format    
             configured with --build-report-path
@@ -351,9 +355,6 @@ werf converge --repo registry.mydomain.com/web --env production
             with commas: key1=val1,key2=val2).
             Also, can be defined with $WERF_SET_STRING_* (e.g. $WERF_SET_STRING_1=key1=val1,        
             $WERF_SET_STRING_2=key2=val2)
-  -Z, --skip-build=false
-            Disable building of docker images, cached images in the repo should exist in the repo   
-            if werf.yaml contains at least one image description (default $WERF_SKIP_BUILD)
   -L, --skip-dependencies-repo-refresh=false
             Do not refresh helm chart repositories locally cached index
       --skip-tls-verify-registry=false

docs/_includes/reference/cli/werf_export.md

@@ -185,14 +185,15 @@ werf export [IMAGE_NAME...] [options]
             repo Selectel VPC (default $WERF_REPO_SELECTEL_VPC)
       --repo-selectel-vpc-id=''
             repo Selectel VPC ID (default $WERF_REPO_SELECTEL_VPC_ID)
+  -Z, --require-built-images=false
+            Requires all used images to be previously built and exist in repo. Exits with error if  
+            needed images are not cached and so require to run build instructions (default          
+            $WERF_REQUIRE_BUILT_IMAGES)
       --secondary-repo=[]
             Specify one or multiple secondary read-only repos with images that will be used as a    
             cache.
             Also, can be specified with $WERF_SECONDARY_REPO_* (e.g. $WERF_SECONDARY_REPO_1=...,    
             $WERF_SECONDARY_REPO_2=...)
-  -Z, --skip-build=false
-            Disable building of docker images, cached images in the repo should exist in the repo   
-            if werf.yaml contains at least one image description (default $WERF_SKIP_BUILD)
       --skip-tls-verify-registry=false
             Skip TLS certificate validation when accessing a registry (default                      
             $WERF_SKIP_TLS_VERIFY_REGISTRY)