diff --git a/keps/NEXT_KEP_NUMBER b/keps/NEXT_KEP_NUMBER index a78736459024..8f92bfdd4976 100644 --- a/keps/NEXT_KEP_NUMBER +++ b/keps/NEXT_KEP_NUMBER @@ -1 +1 @@ -34 +35 diff --git a/keps/sig-storage/0035-20190116-ExecutionHook-apichange.md b/keps/sig-storage/0035-20190116-ExecutionHook-apichange.md new file mode 100644 index 000000000000..c6625305c0c6 --- /dev/null +++ b/keps/sig-storage/0035-20190116-ExecutionHook-apichange.md @@ -0,0 +1,140 @@ +--- +kep-number: 35 +title: ExecutionHook +authors: + - "@jingxu97" + - "@xing-yang" +owning-sig: sig-storage +participating-sigs: + - sig-storage + - sig-node + - sig-architecture +reviewers: + - "@saad-ali" + - "@thockin" +approvers: + - "@thockin" + - "@saad-ali" +editor: TBD +creation-date: 2019-1-16 +last-updated: 2019-1-16 +status: implementable +see-also: + - n/a +replaces: + - n/a +superseded-by: + - n/a +--- + +# Title + +ExecutionHook API change + +## Table of Contents + + * [Title](#title) + * [Table of Contents](#table-of-contents) + * [Summary](#summary) + * [Motivation](#motivation) + * [Goals](#goals) + * [Non-Goals](#non-goals) + * [Proposal](#proposal) + * [User Stories](#user-stories) + * [Workarounds](#workarounds) + * [Alternatives](#alternatives) + * [Risks and Mitigations](#risks-and-mitigations) + * [Graduation Criteria](#graduation-criteria) + * [Implementation History](#implementation-history) + +## Summary + +Volume snapshot support was introduced in Kubernetes v1.12 as an alpha feature. +In the alpha implementation of snapshots for Kubernetes, there is no snapshot consistency +guarantees beyond any guarantees provided by storage system (e.g. crash consistency). + +This proposal is aimed to address that limitation by providing an `ExecutionHook` +in the `Container` struct. The snapshot controller will look up this hook before +taking a snapshot and execute it accordingly. + +## Motivation + +The volume snapshot feature allows creating/deleting volume snapshots, and the +ability to create new volumes from a snapshot natively using the Kubernetes API. + +However, application consistency is not guaranteed. An user has to figure out how +to quiece an application before taking a snapshot and unquiece it after taking +the snapshot. + +### Goals + +`ExecutionHook` is introduced to define actions that can be taken on a container. +Specifically it can be used to perform a quiese operation before a volume snapshot +is taken and then perform an unquiesce operation after a volume snapshot is +taken to resume the application. + +## Non-Goals + +This proposal does not provide exact command included in the `ExecutionHook` +because every application has a different requirement. + +## Proposal + +An `ExecutionHook` is defined in the following. + +``` +// ExecutionHook defines a specific action that should be taken with retries and timeouts +type ExecutionHook struct { + // Command to execute for a particular trigger + Handler `json:",inline" protobuf:"bytes,1,opt,name=handler"` + // How long the controller should try/retry to execute the hook before giving up + RetryTimeOutSeconds int64 `json:"retryTimeOutSeconds,omitempty" protobuf:"varint,2,opt,name=retryTimeOutSeconds"` + // Number of retries + NumRetries int64 `json:"numRetries,omitempty" protobuf:"varint,3,opt,name=numRetries"` +} +``` + +A `QuiesceUnquiesceHook` struct contains a `Quiesce` and `Unquiesce` `ExecutionHook`. + +``` +// QuiesceUnquiesceHook includes a Quiesce action and an Unquiesce action +type QuiesceUnquiesceHook struct { + // The hook to quiesce the application + Quiesce *ExecutionHook `json:"quiesce,omitempty" protobuf:"bytes,1,opt,name=quiesce"` + // The hook to unquiesce the application + Unquiesce *ExecutionHook `json:"unquiesce,omitempty" protobuf:"bytes,2,opt,name=unquiesce"` +} +``` + +A `QuiesceUnquiesceHook` is added to the `Container` struct. + +``` +// A single application container that you want to run within a pod. +type Container struct { + ...... + // Defines the hook to quiesce and unquiesce an application + // +optional + QuiesceUnquiesceHook *QuiesceUnquiesceHook `json:"quiesceUnquiesceHook,omitempty" protobuf:"bytes,22,opt,name=quiesceUnquiesceHook"` +} +``` + +### User Stories + +## Workarounds + +## Alternatives + +The user can use Annotations to define the execution hook if it is not in the +container struct. + +### Risks and Mitigations + +## Graduation Criteria + +When the existing volume snapshot alpha feature goes beta, the `ExecutionHook` +feature will become beta as well. + +## Implementation History + +* Feature description: https://github.com/kubernetes/kubernetes/issues/177 +* VolumeSnapshotDataSource feature gate: https://github.com/kubernetes/kubernetes/pull/67087