Skip to content

Add ImageVolumeSource as a workspace binding type #10593

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bennyz wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add ImageVolumeSource as a workspace binding type #10593

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions config/300-crds/300-pipelinerun.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1669,6 +1669,27 @@ spec:
- type: integer
- type: string
x-kubernetes-int-or-string: true
image:
description: Image
type: object
properties:
pullPolicy:
description: |-
Policy for pulling OCI objects. Possible values are:
Always: the kubelet always attempts to pull the reference. Container creation will fail If the pull fails.
Never: the kubelet never pulls the reference and only uses a local image or artifact. Container creation will fail if the reference isn't present.
IfNotPresent: the kubelet pulls if the reference isn't already present on disk. Container creation will fail if the reference isn't present and the pull fails.
Defaults to Always if :latest tag is specified, or IfNotPresent otherwise.
type: string
reference:
description: |-
Required: Image or artifact reference to be used.
Behaves in the same way as pod.spec.containers[*].image.
Pull secrets will be assembled in the same way as for the container image by looking up node credentials, SA image pull secrets, and pod spec image pull secrets.
More info: https://kubernetes.io/docs/concepts/containers/images
This field is optional to allow higher level config management to default or override
container images in workload controllers like Deployments and StatefulSets.
type: string
name:
description: Name
type: string
Expand Down Expand Up @@ -2360,6 +2381,8 @@ spec:
type: boolean
enableConciseResolverSyntax:
type: boolean
enableImageWorkspace:
type: boolean
enableKeepPodOnCancel:
type: boolean
enableKubernetesSidecar:
Expand Down Expand Up @@ -2740,6 +2763,8 @@ spec:
type: boolean
enableConciseResolverSyntax:
type: boolean
enableImageWorkspace:
type: boolean
enableKeepPodOnCancel:
type: boolean
enableKubernetesSidecar:
Expand Down Expand Up @@ -3013,6 +3038,8 @@ spec:
type: boolean
enableConciseResolverSyntax:
type: boolean
enableImageWorkspace:
type: boolean
enableKeepPodOnCancel:
type: boolean
enableKubernetesSidecar:
Expand Down Expand Up @@ -4784,6 +4811,30 @@ spec:
- type: integer
- type: string
x-kubernetes-int-or-string: true
image:
description: |-
Image represents a volume populated from a container image's filesystem.
The image is pulled at pod startup. Contents are mounted read-only.
Requires Kubernetes 1.31+ with the ImageVolume feature gate enabled.
type: object
properties:
pullPolicy:
description: |-
Policy for pulling OCI objects. Possible values are:
Always: the kubelet always attempts to pull the reference. Container creation will fail If the pull fails.
Never: the kubelet never pulls the reference and only uses a local image or artifact. Container creation will fail if the reference isn't present.
IfNotPresent: the kubelet pulls if the reference isn't already present on disk. Container creation will fail if the reference isn't present and the pull fails.
Defaults to Always if :latest tag is specified, or IfNotPresent otherwise.
type: string
reference:
description: |-
Required: Image or artifact reference to be used.
Behaves in the same way as pod.spec.containers[*].image.
Pull secrets will be assembled in the same way as for the container image by looking up node credentials, SA image pull secrets, and pod spec image pull secrets.
More info: https://kubernetes.io/docs/concepts/containers/images
This field is optional to allow higher level config management to default or override
container images in workload controllers like Deployments and StatefulSets.
type: string
name:
description: Name is the name of the workspace populated by the volume.
type: string
Expand Down Expand Up @@ -5459,6 +5510,8 @@ spec:
type: boolean
enableConciseResolverSyntax:
type: boolean
enableImageWorkspace:
type: boolean
enableKeepPodOnCancel:
type: boolean
enableKubernetesSidecar:
Expand Down
53 changes: 53 additions & 0 deletions config/300-crds/300-taskrun.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1215,6 +1215,27 @@ spec:
- type: integer
- type: string
x-kubernetes-int-or-string: true
image:
description: Image
type: object
properties:
pullPolicy:
description: |-
Policy for pulling OCI objects. Possible values are:
Always: the kubelet always attempts to pull the reference. Container creation will fail If the pull fails.
Never: the kubelet never pulls the reference and only uses a local image or artifact. Container creation will fail if the reference isn't present.
IfNotPresent: the kubelet pulls if the reference isn't already present on disk. Container creation will fail if the reference isn't present and the pull fails.
Defaults to Always if :latest tag is specified, or IfNotPresent otherwise.
type: string
reference:
description: |-
Required: Image or artifact reference to be used.
Behaves in the same way as pod.spec.containers[*].image.
Pull secrets will be assembled in the same way as for the container image by looking up node credentials, SA image pull secrets, and pod spec image pull secrets.
More info: https://kubernetes.io/docs/concepts/containers/images
This field is optional to allow higher level config management to default or override
container images in workload controllers like Deployments and StatefulSets.
type: string
name:
description: Name
type: string
Expand Down Expand Up @@ -1875,6 +1896,8 @@ spec:
type: boolean
enableConciseResolverSyntax:
type: boolean
enableImageWorkspace:
type: boolean
enableKeepPodOnCancel:
type: boolean
enableKubernetesSidecar:
Expand Down Expand Up @@ -2148,6 +2171,8 @@ spec:
type: boolean
enableConciseResolverSyntax:
type: boolean
enableImageWorkspace:
type: boolean
enableKeepPodOnCancel:
type: boolean
enableKubernetesSidecar:
Expand Down Expand Up @@ -3351,6 +3376,30 @@ spec:
- type: integer
- type: string
x-kubernetes-int-or-string: true
image:
description: |-
Image represents a volume populated from a container image's filesystem.
The image is pulled at pod startup. Contents are mounted read-only.
Requires Kubernetes 1.31+ with the ImageVolume feature gate enabled.
type: object
properties:
pullPolicy:
description: |-
Policy for pulling OCI objects. Possible values are:
Always: the kubelet always attempts to pull the reference. Container creation will fail If the pull fails.
Never: the kubelet never pulls the reference and only uses a local image or artifact. Container creation will fail if the reference isn't present.
IfNotPresent: the kubelet pulls if the reference isn't already present on disk. Container creation will fail if the reference isn't present and the pull fails.
Defaults to Always if :latest tag is specified, or IfNotPresent otherwise.
type: string
reference:
description: |-
Required: Image or artifact reference to be used.
Behaves in the same way as pod.spec.containers[*].image.
Pull secrets will be assembled in the same way as for the container image by looking up node credentials, SA image pull secrets, and pod spec image pull secrets.
More info: https://kubernetes.io/docs/concepts/containers/images
This field is optional to allow higher level config management to default or override
container images in workload controllers like Deployments and StatefulSets.
type: string
name:
description: Name is the name of the workspace populated by the volume.
type: string
Expand Down Expand Up @@ -4029,6 +4078,8 @@ spec:
type: boolean
enableConciseResolverSyntax:
type: boolean
enableImageWorkspace:
type: boolean
enableKeepPodOnCancel:
type: boolean
enableKubernetesSidecar:
Expand Down Expand Up @@ -4294,6 +4345,8 @@ spec:
type: boolean
enableConciseResolverSyntax:
type: boolean
enableImageWorkspace:
type: boolean
enableKeepPodOnCancel:
type: boolean
enableKubernetesSidecar:
Expand Down
4 changes: 4 additions & 0 deletions config/config-feature-flags.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,3 +155,7 @@ data:
#
# See https://github.com/tektoncd/pipeline/issues/7691 for more info.
enable-informer-cache-transforms: "true"
# Setting this flag to "true" will enable image volume sources in workspace bindings.
# This allows using container images as read-only workspace content.
# Requires Kubernetes 1.31+ with the ImageVolume feature gate enabled (beta since Kubernetes 1.33).
enable-image-workspace: "false"
5 changes: 5 additions & 0 deletions docs/additional-configs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -441,6 +441,10 @@ Defaults to "ignore".
source from where a remote Task/Pipeline definition was fetched. By default, this is set to `true`.
To disable populating this field, set this flag to `"false"`.

- `enable-image-workspace`: Set this flag to `"true"` to enable image volume sources in workspace bindings.
This allows using container images as read-only workspace content. Requires Kubernetes 1.31+ with the
`ImageVolume` feature gate enabled (beta since Kubernetes 1.33). Defaults to `"false"`.

- `enable-termination-message-compression`: Set this flag to `"true"` to enable zlib compression of
termination messages written by the entrypoint. This increases the effective capacity for results
from ~33 to ~187 in typical scenarios (5.7x improvement). Has no effect when `results-from` is
Expand Down Expand Up @@ -480,6 +484,7 @@ Features currently in "alpha" are:
| [CEL in WhenExpression](./pipelines.md#use-cel-expression-in-whenexpression) | [TEP-0145](https://github.com/tektoncd/community/blob/main/teps/0145-cel-in-whenexpression.md) | [v0.53.0](https://github.com/tektoncd/pipeline/releases/tag/v0.53.0) | `enable-cel-in-whenexpression` |
| [Param Enum](./taskruns.md#parameter-enums) | [TEP-0144](https://github.com/tektoncd/community/blob/main/teps/0144-param-enum.md) | [v0.54.0](https://github.com/tektoncd/pipeline/releases/tag/v0.54.0) | `enable-param-enum` |
| Termination Message Compression | N/A | N/A | `enable-termination-message-compression` |
| [Image Workspace](./workspaces.md#image) | N/A | N/A | `enable-image-workspace` |

### Beta Features

Expand Down
18 changes: 18 additions & 0 deletions docs/workspaces.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -591,6 +591,24 @@ policies=internal-app \
ttl=20m
```

##### `image`

The `image` field references an [`image` volume](https://kubernetes.io/docs/concepts/storage/volumes/#image).
Using an `image` volume has the following limitations:

- This feature is gated behind the `enable-image-workspace` feature flag. Set `enable-image-workspace: "true"` in the `feature-flags` ConfigMap to enable it.
- Requires Kubernetes 1.31+ with the `ImageVolume` feature gate enabled (beta since Kubernetes 1.33).
- `image` volume sources are always mounted read-only by the kubelet. Workspaces using `image` should be declared with `readOnly: true`.
- `subPath` is not supported with `image` volumes on Kubernetes 1.31 and 1.32. Support for `subPath` begins in Kubernetes 1.33.

```yaml
workspaces:
- name: my-tools
image:
reference: quay.io/example/my-tools:latest
pullPolicy: IfNotPresent
```

If you need support for a `VolumeSource` type not listed above, [open an issue](https://github.com/tektoncd/pipeline/issues) or
a [pull request](https://github.com/tektoncd/pipeline/blob/main/CONTRIBUTING.md).

Expand Down
16 changes: 16 additions & 0 deletions pkg/apis/config/feature_flags.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,11 @@ const (
// DefaultEnableTerminationMessageCompression is the default value for EnableTerminationMessageCompression
DefaultEnableTerminationMessageCompression = false

// EnableImageWorkspace is the flag to enable image volume sources in workspace bindings
EnableImageWorkspace = "enable-image-workspace"
// DefaultEnableImageWorkspace is the default value for EnableImageWorkspace
DefaultEnableImageWorkspace = false

// EnableStepActions is the flag to enable step actions (no-op since it's stable)
EnableStepActions = "enable-step-actions"

Expand Down Expand Up @@ -193,6 +198,13 @@ var (
Enabled: DefaultAlphaFeatureEnabled,
}

// DefaultEnableImageWorkspaceFlag is the default PerFeatureFlag value for "enable-image-workspace"
DefaultEnableImageWorkspaceFlag = PerFeatureFlag{
Name: EnableImageWorkspace,
Stability: AlphaAPIFields,
Enabled: DefaultAlphaFeatureEnabled,
}
Comment thread
bennyz marked this conversation as resolved.

DefaultEnableTektonOCIBundles = PerFeatureFlag{
Name: EnableTektonOCIBundles,
Stability: AlphaAPIFields,
Expand Down Expand Up @@ -235,6 +247,7 @@ type FeatureFlags struct {
EnableKubernetesSidecar bool `json:"enableKubernetesSidecar,omitempty"`
EnableWaitExponentialBackoff bool `json:"enableWaitExponentialBackoff,omitempty"`
EnableTerminationMessageCompression bool `json:"enableTerminationMessageCompression,omitempty"`
EnableImageWorkspace bool `json:"enableImageWorkspace,omitempty"`
// DeprecatedEnableTektonOCIBundles is maintained for backward compatibility
// to allow deletion of PipelineRuns created before v0.62.x.
// This field is not used and can be removed in a future release
Expand Down Expand Up @@ -351,6 +364,9 @@ func NewFeatureFlagsFromMap(cfgMap map[string]string) (*FeatureFlags, error) {
if err := setPerFeatureFlag(EnableTerminationMessageCompression, DefaultEnableTerminationMessageCompressionFlag, &tc.EnableTerminationMessageCompression); err != nil {
return nil, err
}
if err := setPerFeatureFlag(EnableImageWorkspace, DefaultEnableImageWorkspaceFlag, &tc.EnableImageWorkspace); err != nil {
return nil, err
}

return &tc, nil
}
Expand Down
1 change: 1 addition & 0 deletions pkg/apis/config/feature_flags_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,7 @@ func TestNewFeatureFlagsFromConfigMap(t *testing.T) {
EnableConciseResolverSyntax: true,
EnableKubernetesSidecar: true,
EnableTerminationMessageCompression: true,
EnableImageWorkspace: true,
},
fileName: "feature-flags-all-flags-set",
},
Expand Down
1 change: 1 addition & 0 deletions pkg/apis/config/testdata/feature-flags-all-flags-set.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,3 +39,4 @@ data:
enable-concise-resolver-syntax: "true"
enable-kubernetes-sidecar: "true"
enable-termination-message-compression: "true"
enable-image-workspace: "true"
8 changes: 7 additions & 1 deletion pkg/apis/pipeline/v1/openapi_generated.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading