Merge pull request #1027 from raghavbhatnagar96/add/builrun_cleanup

Support automatic buildrun cleanup

deploy/crds/shipwright.io_buildruns.yaml

@@ -352,6 +352,30 @@ spec:
                       - name
                       type: object
                     type: array
+                  retention:
+                    description: Contains information about retention params
+                    properties:
+                      failedLimit:
+                        description: FailedLimit defines the maximum number of failed
+                          buildruns that should exist.
+                        minimum: 1
+                        type: integer
+                      succeededLimit:
+                        description: SucceededLimit defines the maximum number of
+                          succeeded buildruns that should exist.
+                        minimum: 1
+                        type: integer
+                      ttlAfterFailed:
+                        description: TTLAfterFailed defines the maximum duration of
+                          time the failed buildrun should exist.
+                        format: duration
+                        type: string
+                      ttlAfterSucceeded:
+                        description: TTLAfterSucceeded defines the maximum duration
+                          of time the succeeded buildrun should exist.
+                        format: duration
+                        type: string
+                    type: object
                   source:
                     description: Source refers to the Git repository containing the
                       source code to be built.
@@ -686,6 +710,20 @@ spec:
                   - name
                   type: object
                 type: array
+              retention:
+                description: Contains information about retention params
+                properties:
+                  ttlAfterFailed:
+                    description: TTLAfterFailed defines the maximum duration of time
+                      the failed buildrun should exist.
+                    format: duration
+                    type: string
+                  ttlAfterSucceeded:
+                    description: TTLAfterSucceeded defines the maximum duration of
+                      time the succeeded buildrun should exist.
+                    format: duration
+                    type: string
+                type: object
               serviceAccount:
                 description: ServiceAccount refers to the kubernetes serviceaccount
                   which is used for resource control. Default serviceaccount will
@@ -1020,6 +1058,30 @@ spec:
                       - name
                       type: object
                     type: array
+                  retention:
+                    description: Contains information about retention params
+                    properties:
+                      failedLimit:
+                        description: FailedLimit defines the maximum number of failed
+                          buildruns that should exist.
+                        minimum: 1
+                        type: integer
+                      succeededLimit:
+                        description: SucceededLimit defines the maximum number of
+                          succeeded buildruns that should exist.
+                        minimum: 1
+                        type: integer
+                      ttlAfterFailed:
+                        description: TTLAfterFailed defines the maximum duration of
+                          time the failed buildrun should exist.
+                        format: duration
+                        type: string
+                      ttlAfterSucceeded:
+                        description: TTLAfterSucceeded defines the maximum duration
+                          of time the succeeded buildrun should exist.
+                        format: duration
+                        type: string
+                    type: object
                   source:
                     description: Source refers to the Git repository containing the
                       source code to be built.

deploy/crds/shipwright.io_builds.yaml

@@ -331,6 +331,30 @@ spec:
                   - name
                   type: object
                 type: array
+              retention:
+                description: Contains information about retention params
+                properties:
+                  failedLimit:
+                    description: FailedLimit defines the maximum number of failed
+                      buildruns that should exist.
+                    minimum: 1
+                    type: integer
+                  succeededLimit:
+                    description: SucceededLimit defines the maximum number of succeeded
+                      buildruns that should exist.
+                    minimum: 1
+                    type: integer
+                  ttlAfterFailed:
+                    description: TTLAfterFailed defines the maximum duration of time
+                      the failed buildrun should exist.
+                    format: duration
+                    type: string
+                  ttlAfterSucceeded:
+                    description: TTLAfterSucceeded defines the maximum duration of
+                      time the succeeded buildrun should exist.
+                    format: duration
+                    type: string
+                type: object
               source:
                 description: Source refers to the Git repository containing the source
                   code to be built.

docs/build.md

@@ -15,6 +15,7 @@ SPDX-License-Identifier: Apache-2.0
   - [Defining ParamValues](#defining-paramvalues)
   - [Defining the Builder or Dockerfile](#defining-the-builder-or-dockerfile)
   - [Defining the Output](#defining-the-output)
+  - [Defining Retention Parameters](#defining-retention-parameters)
 - [BuildRun deletion](#BuildRun-deletion)
 
 ## Overview
@@ -29,6 +30,7 @@ A `Build` resource allows the user to define:
 - dockerfile
 - output
 - env
+- retention
 
 A `Build` is available within a namespace.
 
@@ -87,7 +89,11 @@ The `Build` definition supports the following fields:
   - `metadata.annotations[build.shipwright.io/build-run-deletion]` - Defines if delete all related BuildRuns when deleting the Build. The default is `false`.
   - `spec.output.annotations` - Refers to a list of `key/value` that could be used to [annotate](https://github.com/opencontainers/image-spec/blob/main/annotations.md) the output image.
   - `spec.output.labels` - Refers to a list of `key/value` that could be used to label the output image.
-  - `spec.env` - Specifies additional environment variables that should be passed to the build container. The available variables depend on the tool used by the chosen build strategy.
+  - `spec.env` - Specifies additional environment variables that should be passed to the build container. The available variables depend on the tool that is being used by the chosen build strategy.
+  - `spec.retention.ttlAfterFailed` - Specifies the duration for which a failed buildrun can exist.
+  - `spec.retention.ttlAfterSucceeded` - Specifies the duration for which a successful buildrun can exist.
+  - `spec.retention.failedLimit` - Specifies the number of failed buildrun that can exist.
+  - `spec.retention.succeededLimit` - Specifies the number of successful buildrun can exist.
 
 ### Defining the Source
 
@@ -530,6 +536,41 @@ You can verify which labels were added to the output image that is available on
   docker inspect us.icr.io/source-to-image-build/nodejs-ex | jq ".[].Config.Labels"
 ```
 
+### Defining Retention Parameters
+
+A `Build` resource can specify how long a completed BuildRun can exist and the number of buildruns that have failed or succeeded that should exist. Instead of manually cleaning up old BuildRuns, retention parameters provide an alternate method for cleaning up BuildRuns automatically.
+
+As part of the retention parameters, we have the following fields:
+
+- `retention.succeededLimit` - Defines number of succeeded BuildRuns for a Build that can exist.
+- `retention.failedLimit` - Defines number of failed BuildRuns for a Build that can exist.
+- `retention.ttlAfterFailed` - Specifies the duration for which a failed buildrun can exist.
+- `retention.ttlAfterSucceeded` - Specifies the duration for which a successful buildrun can exist.
+
+An example of a user using both TTL and Limit retention fields. In case of such a configuration, BuildRun will get deleted once the first criteria is met.
+
+```yaml
+  apiVersion: shipwright.io/v1alpha1
+  kind: Build
+  metadata:
+    name: build-retention-ttl
+  spec:
+    source:
+      url: "https://github.com/shipwright-io/sample-go"
+      contextDir: docker-build
+    strategy:
+      kind: ClusterBuildStrategy
+    output:
+    ...
+    retention:
+      ttlAfterFailed: 30m
+      ttlAfterSucceeded: 1h
+      failedLimit: 10
+      succeededLimit: 20
+```
+
+**NOTE**: When changes are made to `retention.failedLimit` and `retention.succeededLimit` values, they come into effect as soon as the build is applied, thereby enforcing the new limits. On the other hand, changing the `retention.ttlAfterFailed` and `retention.ttlAfterSucceeded` values will only affect new buildruns. Old buildruns will adhere to the old TTL retention values. In case TTL values are defined in buildrun specifications as well as build specifications, priority will be given to the values defined in the buildrun specifications.
+
 ### Sources
 
 Sources represent remote artifacts, as in external entities added to the build context before the actual Build starts. Therefore, you may employ `.spec.sources` to download artifacts from external repositories.

docs/buildrun.md

@@ -13,7 +13,9 @@ SPDX-License-Identifier: Apache-2.0
   - [Defining the BuildSpec](#defining-the-buildspec)
   - [Defining ParamValues](#defining-paramvalues)
   - [Defining the ServiceAccount](#defining-the-serviceaccount)
+  - [Defining Retention Parameters](#defining-retention-parameters)
 - [Canceling a `BuildRun`](#canceling-a-buildrun)
+- [Automatic `BuildRun` deletion](#automatic-buildrun-deletion)
 - [Specifying Environment Variables](#specifying-environment-variables)
 - [BuildRun Status](#buildrun-status)
   - [Understanding the state of a BuildRun](#understanding-the-state-of-a-buildrun)
@@ -166,6 +168,32 @@ You can also use set the `spec.serviceAccount.generate` path to `true`. This wil
 
 _**Note**_: When the service account is not defined, the `BuildRun` uses the `pipeline` service account if it exists in the namespace, and falls back to the `default` service account.
 
+### Defining Retention Parameters
+
+A `Buildrun` resource can specify how long a completed BuildRun can exist. Instead of manually cleaning up old BuildRuns, retention parameters provide an alternate method for cleaning up BuildRuns automatically.
+
+As part of the buildrun retention parameters, we have the following fields:
+
+- `retention.ttlAfterFailed` - Specifies the duration for which a failed buildrun can exist.
+- `retention.ttlAfterSucceeded` - Specifies the duration for which a successful buildrun can exist.
+
+An example of a user using buildrun TTL parameters.
+
+```yaml
+apiVersion: shipwright.io/v1alpha1
+kind: BuildRun
+metadata:
+  name: buidrun-retention-ttl
+spec:
+  buildRef:
+    name: build-retention-ttl
+  retention:
+    ttlAfterFailed: 10m
+    ttlAfterSucceeded: 10m
+```
+
+**NOTE** In case TTL values are defined in buildrun specifications as well as build specifications, priority will be given to the values defined in the buildrun specifications.
+
 ## Canceling a `BuildRun`
 
 To cancel a `BuildRun` that's currently executing, update its status to mark it as canceled.
@@ -184,6 +212,20 @@ spec:
   state: "BuildRunCanceled"
 ```
 
+## Automatic `BuildRun` deletion
+
+We have two controllers that ensure that buildruns can be deleted automatically if required. This is ensured by adding `retention` parameters in either the build specifications or the buildrun specifications.
+
+- Buildrun TTL parameters: These are used to make sure that buildruns exist for a fixed duration of time after completiion.
+  - `buildrun.spec.retention.ttlAfterFailed`: The buildrun is deleted if the mentioned duration of time has passed and the buildrun has failed.
+  - `buildrun.spec.retention.ttlAfterSucceeded`: The buildrun is deleted if the mentioned duration of time has passed and the buildrun has succeeded.
+- Build TTL parameters: These are used to make sure that related buildruns exist for a fixed duration of time after completiion.
+  - `build.spec.retention.ttlAfterFailed`: The buildrun is deleted if the mentioned duration of time has passed and the buildrun has failed.
+  - `build.spec.retention.ttlAfterSucceeded`: The buildrun is deleted if the mentioned duration of time has passed and the buildrun has succeeded.
+- Build Limit parameters: These are used to make sure that related buildruns exist for a fixed duration of time after completiion.
+  - `build.spec.retention.succeededLimit` - Defines number of succeeded BuildRuns for a Build that can exist.
+  - `build.spec.retention.failedLimit` - Defines number of failed BuildRuns for a Build that can exist.
+
 ## Specifying Environment Variables
 
 An example of a `BuildRun` that specifies environment variables:

pkg/apis/build/v1alpha1/build_types.go

@@ -138,6 +138,11 @@ type BuildSpec struct {
 	// Env contains additional environment variables that should be passed to the build container
 	// +optional
 	Env []corev1.EnvVar `json:"env,omitempty"`
+
+	// Contains information about retention params
+	//
+	// +optional
+	Retention *BuildRetention `json:"retention,omitempty"`
 }
 
 // StrategyName returns the name of the configured strategy, or 'undefined' in
@@ -215,6 +220,30 @@ type BuildList struct {
 	Items           []Build `json:"items"`
 }
 
+// BuildRetention struct for buildrun cleanup
+type BuildRetention struct {
+	// FailedLimit defines the maximum number of failed buildruns that should exist.
+	//
+	// +optional
+	// +kubebuilder:validation:Minimum=1
+	FailedLimit *uint `json:"failedLimit,omitempty"`
+	// SucceededLimit defines the maximum number of succeeded buildruns that should exist.
+	//
+	// +optional
+	// +kubebuilder:validation:Minimum=1
+	SucceededLimit *uint `json:"succeededLimit,omitempty"`
+	// TTLAfterFailed defines the maximum duration of time the failed buildrun should exist.
+	//
+	// +optional
+	// +kubebuilder:validation:Format=duration
+	TTLAfterFailed *metav1.Duration `json:"ttlAfterFailed,omitempty"`
+	// TTLAfterSucceeded defines the maximum duration of time the succeeded buildrun should exist.
+	//
+	// +optional
+	// +kubebuilder:validation:Format=duration
+	TTLAfterSucceeded *metav1.Duration `json:"ttlAfterSucceeded,omitempty"`
+}
+
 func init() {
 	SchemeBuilder.Register(&Build{}, &BuildList{})
 }

pkg/apis/build/v1alpha1/buildrun_types.go

@@ -72,6 +72,10 @@ type BuildRunSpec struct {
 	//
 	// +optional
 	Env []corev1.EnvVar `json:"env,omitempty"`
+
+	// Contains information about retention params
+	// +optional
+	Retention *BuildRunRetention `json:"retention,omitempty"`
 }
 
 // BuildRunRequestedState defines the buildrun state the user can provide to override whatever is the current state.
@@ -296,6 +300,20 @@ type Condition struct {
 	Message string `json:"message" description:"human-readable message indicating details about last transition"`
 }
 
+// BuildRunRetention struct for buildrun cleanup
+type BuildRunRetention struct {
+	// TTLAfterFailed defines the maximum duration of time the failed buildrun should exist.
+	//
+	// +optional
+	// +kubebuilder:validation:Format=duration
+	TTLAfterFailed *metav1.Duration `json:"ttlAfterFailed,omitempty"`
+	// TTLAfterSucceeded defines the maximum duration of time the succeeded buildrun should exist.
+	//
+	// +optional
+	// +kubebuilder:validation:Format=duration
+	TTLAfterSucceeded *metav1.Duration `json:"ttlAfterSucceeded,omitempty"`
+}
+
 func init() {
 	SchemeBuilder.Register(&BuildRun{}, &BuildRunList{})
 }