什么是strategy

本次分析将介绍storage的strategy。在创建,更新,删除资源时,我们常常需要有对资源进行预处理的需求。Kubernetes会对系统中的资源都定义一个strategy,用来表明在操作资源时该资源应有的处理方式。在Kubernetes中,主要有RESTCreateStrategy,RESTGracefulDeleteStrategy,RESTUpdateStrategy等。

RESTCreateStrategy

RESTCreateStrategy用来标识资源在创建时应有的处理方式,定义在/pkg/api/rest/create.go中:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// RESTCreateStrategy defines the minimum validation, accepted input, and
// name generation behavior to create an object that follows Kubernetes
// API conventions.
type RESTCreateStrategy interface {
runtime.ObjectTyper
// The name generate is used when the standard GenerateName field is set.
// The NameGenerator will be invoked prior to validation.
api.NameGenerator
// NamespaceScoped returns true if the object must be within a namespace.
NamespaceScoped() bool
// PrepareForCreate is invoked on create before validation to normalize
// the object. For example: remove fields that are not to be persisted,
// sort order-insensitive list fields, etc. This should not remove fields
// whose presence would be considered a validation error.
PrepareForCreate(ctx api.Context, obj runtime.Object)
// Validate is invoked after default fields in the object have been filled in before
// the object is persisted. This method should not mutate the object.
Validate(ctx api.Context, obj runtime.Object) field.ErrorList
// Canonicalize is invoked after validation has succeeded but before the
// object has been persisted. This method may mutate the object.
Canonicalize(obj runtime.Object)
}

RESTUpdateStrategy接口的各方法含义如下:

  1. NamespaceScoped(): 返回该资源是否在namespace scope下;
  2. PrepareForCreate(): 创建前处理资源;
  3. Validate():对资源进行创建前的验证,一般在PrepareForCreate()后执行;
  4. Canonicalize():规范化资源,一般在Validate()执行。

Kubernetes还提供了BeforeCreate()封装PrepareForCreate(), Validate()和Canonicalize():

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
// BeforeCreate ensures that common operations for all resources are performed on creation. It only returns
// errors that can be converted to api.Status. It invokes PrepareForCreate, then GenerateName, then Validate.
// It returns nil if the object should be created.
func BeforeCreate(strategy RESTCreateStrategy, ctx api.Context, obj runtime.Object) error {
objectMeta, kind, kerr := objectMetaAndKind(strategy, obj)
if kerr != nil {
return kerr
}
if strategy.NamespaceScoped() {
if !api.ValidNamespace(ctx, objectMeta) {
return errors.NewBadRequest("the namespace of the provided object does not match the namespace sent on the request")
}
} else {
objectMeta.Namespace = api.NamespaceNone
}
objectMeta.DeletionTimestamp = nil
objectMeta.DeletionGracePeriodSeconds = nil
//***调用PrepareForCreate()***//
strategy.PrepareForCreate(ctx, obj)
//***定义在/pkg/api/meta.go中***//
api.FillObjectMetaSystemFields(ctx, objectMeta)
api.GenerateName(strategy, objectMeta)
// ClusterName is ignored and should not be saved
objectMeta.ClusterName = ""
if errs := strategy.Validate(ctx, obj); len(errs) > 0 {
return errors.NewInvalid(kind.GroupKind(), objectMeta.Name, errs)
}
// Custom validation (including name validation) passed
// Now run common validation on object meta
// Do this *after* custom validation so that specific error messages are shown whenever possible
if errs := validation.ValidateObjectMeta(objectMeta, strategy.NamespaceScoped(), path.ValidatePathSegmentName, field.NewPath("metadata")); len(errs) > 0 {
return errors.NewInvalid(kind.GroupKind(), objectMeta.Name, errs)
}
strategy.Canonicalize(obj)
return nil
}

BeforeCreate()在/pkg/registry/generic/registry/store.go的Create()中会调用到。

RESTGracefulDeleteStrategy

RESTGracefulDeleteStrategy用来标识资源在更新时应有的处理方式,定义在/pkg/api/rest/delete.go中:

1
2
3
4
5
6
7
// RESTGracefulDeleteStrategy must be implemented by the registry that supports
// graceful deletion.
type RESTGracefulDeleteStrategy interface {
// CheckGracefulDelete should return true if the object can be gracefully deleted and set
// any default values on the DeleteOptions.
CheckGracefulDelete(ctx api.Context, obj runtime.Object, options *api.DeleteOptions) bool
}

RESTGracefulDeleteStrategy接口的各方法含义如下:

  1. CheckGracefulDelete(): 返回该资源是否允许优雅地删除。

Kubernetes还提供了BeforeDelete():

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
// BeforeDelete tests whether the object can be gracefully deleted. If graceful is set the object
// should be gracefully deleted, if gracefulPending is set the object has already been gracefully deleted
// (and the provided grace period is longer than the time to deletion), and an error is returned if the
// condition cannot be checked or the gracePeriodSeconds is invalid. The options argument may be updated with
// default values if graceful is true. Second place where we set deletionTimestamp is pkg/registry/generic/registry/store.go
// this function is responsible for setting deletionTimestamp during gracefulDeletion, other one for cascading deletions.
func BeforeDelete(strategy RESTDeleteStrategy, ctx api.Context, obj runtime.Object, options *api.DeleteOptions) (graceful, gracefulPending bool, err error) {
objectMeta, gvk, kerr := objectMetaAndKind(strategy, obj)
if kerr != nil {
return false, false, kerr
}
// Checking the Preconditions here to fail early. They'll be enforced later on when we actually do the deletion, too.
if options.Preconditions != nil && options.Preconditions.UID != nil && *options.Preconditions.UID != objectMeta.UID {
return false, false, errors.NewConflict(unversioned.GroupResource{Group: gvk.Group, Resource: gvk.Kind}, objectMeta.Name, fmt.Errorf("the UID in the precondition (%s) does not match the UID in record (%s). The object might have been deleted and then recreated", *options.Preconditions.UID, objectMeta.UID))
}
gracefulStrategy, ok := strategy.(RESTGracefulDeleteStrategy)
if !ok {
// If we're not deleting gracefully there's no point in updating Generation, as we won't update
// the obcject before deleting it.
return false, false, nil
}
// if the object is already being deleted, no need to update generation.
if objectMeta.DeletionTimestamp != nil {
// if we are already being deleted, we may only shorten the deletion grace period
// this means the object was gracefully deleted previously but deletionGracePeriodSeconds was not set,
// so we force deletion immediately
// IMPORTANT:
// The deletion operation happens in two phases.
// 1. Update to set DeletionGracePeriodSeconds and DeletionTimestamp
// 2. Delete the object from storage.
// If the update succeeds, but the delete fails (network error, internal storage error, etc.),
// a resource was previously left in a state that was non-recoverable. We
// check if the existing stored resource has a grace period as 0 and if so
// attempt to delete immediately in order to recover from this scenario.
if objectMeta.DeletionGracePeriodSeconds == nil || *objectMeta.DeletionGracePeriodSeconds == 0 {
return false, false, nil
}
// only a shorter grace period may be provided by a user
if options.GracePeriodSeconds != nil {
period := int64(*options.GracePeriodSeconds)
if period >= *objectMeta.DeletionGracePeriodSeconds {
return false, true, nil
}
newDeletionTimestamp := unversioned.NewTime(
objectMeta.DeletionTimestamp.Add(-time.Second * time.Duration(*objectMeta.DeletionGracePeriodSeconds)).
Add(time.Second * time.Duration(*options.GracePeriodSeconds)))
objectMeta.DeletionTimestamp = &newDeletionTimestamp
objectMeta.DeletionGracePeriodSeconds = &period
return true, false, nil
}
// graceful deletion is pending, do nothing
options.GracePeriodSeconds = objectMeta.DeletionGracePeriodSeconds
return false, true, nil
}
if !gracefulStrategy.CheckGracefulDelete(ctx, obj, options) {
return false, false, nil
}
now := unversioned.NewTime(unversioned.Now().Add(time.Second * time.Duration(*options.GracePeriodSeconds)))
objectMeta.DeletionTimestamp = &now
objectMeta.DeletionGracePeriodSeconds = options.GracePeriodSeconds
// If it's the first graceful deletion we are going to set the DeletionTimestamp to non-nil.
// Controllers of the object that's being deleted shouldn't take any nontrivial actions, hence its behavior changes.
// Thus we need to bump object's Generation (if set). This handles generation bump during graceful deletion.
// The bump for objects that don't support graceful deletion is handled in pkg/registry/generic/registry/store.go.
if objectMeta.Generation > 0 {
objectMeta.Generation++
}
return true, false, nil
}

BeforeDelete()在/pkg/registry/generic/registry/store.go的Delete()中会调用到。

RESTUpdateStrategy

RESTUpdateStrategy用来标识资源在更新时应有的处理方式,定义在/pkg/api/rest/update.go中:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// RESTUpdateStrategy defines the minimum validation, accepted input, and
// name generation behavior to update an object that follows Kubernetes
// API conventions. A resource may have many UpdateStrategies, depending on
// the call pattern in use.
type RESTUpdateStrategy interface {
runtime.ObjectTyper
// NamespaceScoped returns true if the object must be within a namespace.
NamespaceScoped() bool
// AllowCreateOnUpdate returns true if the object can be created by a PUT.
AllowCreateOnUpdate() bool
// PrepareForUpdate is invoked on update before validation to normalize
// the object. For example: remove fields that are not to be persisted,
// sort order-insensitive list fields, etc. This should not remove fields
// whose presence would be considered a validation error.
PrepareForUpdate(ctx api.Context, obj, old runtime.Object)
// ValidateUpdate is invoked after default fields in the object have been
// filled in before the object is persisted. This method should not mutate
// the object.
ValidateUpdate(ctx api.Context, obj, old runtime.Object) field.ErrorList
// Canonicalize is invoked after validation has succeeded but before the
// object has been persisted. This method may mutate the object.
Canonicalize(obj runtime.Object)
// AllowUnconditionalUpdate returns true if the object can be updated
// unconditionally (irrespective of the latest resource version), when
// there is no resource version specified in the object.
AllowUnconditionalUpdate() bool
}

RESTUpdateStrategy接口的各方法含义如下:

  1. NamespaceScoped(): 返回该资源是否在namespace scope下;
  2. AllowCreateOnUpdate():表明该资源在更新时,如果资源不存在,是否允许创建;
  3. PrepareForUpdate(): 更新前处理资源;
  4. ValidateUpdate():对资源进行更新前的验证,一般在PrepareForUpdate()执行;
  5. Canonicalize():规范化资源,一般在ValidateUpdate()执行;
  6. AllowUnconditionalUpdate():表明在未指定资源版本时,是否允许更新。

Kubernetes还提供了BeforeUpdate()封装PrepareForUpdate(), ValidateUpdate()和Canonicalize():

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
// BeforeUpdate ensures that common operations for all resources are performed on update. It only returns
// errors that can be converted to api.Status. It will invoke update validation with the provided existing
// and updated objects.
func BeforeUpdate(strategy RESTUpdateStrategy, ctx api.Context, obj, old runtime.Object) error {
objectMeta, kind, kerr := objectMetaAndKind(strategy, obj)
if kerr != nil {
return kerr
}
if strategy.NamespaceScoped() {
if !api.ValidNamespace(ctx, objectMeta) {
return errors.NewBadRequest("the namespace of the provided object does not match the namespace sent on the request")
}
} else {
objectMeta.Namespace = api.NamespaceNone
}
// Ensure requests cannot update generation
oldMeta, err := api.ObjectMetaFor(old)
if err != nil {
return err
}
objectMeta.Generation = oldMeta.Generation
strategy.PrepareForUpdate(ctx, obj, old)
// ClusterName is ignored and should not be saved
objectMeta.ClusterName = ""
// Ensure some common fields, like UID, are validated for all resources.
errs, err := validateCommonFields(obj, old)
if err != nil {
return errors.NewInternalError(err)
}
errs = append(errs, strategy.ValidateUpdate(ctx, obj, old)...)
if len(errs) > 0 {
return errors.NewInvalid(kind.GroupKind(), objectMeta.Name, errs)
}
strategy.Canonicalize(obj)
return nil
}

BeforeUpdate()在/pkg/registry/generic/registry/store.go的Update()中会调用到。

deploymentStrategy

在Kubernetes中,每种资源都有strategy,并实现有之前分析过的各strategy接口中的方法。我们以deploymentStrategy为例说明资源如何实现各strategy接口中的方法。
deploymentStrategy定义在/pkg/registry/extensions/deployment/strategy.go中:

1
2
3
4
5
// deploymentStrategy implements behavior for Deployments.
type deploymentStrategy struct {
runtime.ObjectTyper
api.NameGenerator
}

NamespaceScoped()方法实现如下:

1
2
3
4
// NamespaceScoped is true for deployment.
func (deploymentStrategy) NamespaceScoped() bool {
return true
}

NamespaceScoped()直接返回true表明deployment是属于namespace scope的。

PrepareForCreate()方法实现如下:

1
2
3
4
5
6
// PrepareForCreate clears fields that are not allowed to be set by end users on creation.
func (deploymentStrategy) PrepareForCreate(ctx api.Context, obj runtime.Object) {
deployment := obj.(*extensions.Deployment)
deployment.Status = extensions.DeploymentStatus{}
deployment.Generation = 1
}

PrepareForCreate()会去除deployment中的status,并设置Generation为1。

Validate()方法实现如下:

1
2
3
4
5
// Validate validates a new deployment.
func (deploymentStrategy) Validate(ctx api.Context, obj runtime.Object) field.ErrorList {
deployment := obj.(*extensions.Deployment)
return validation.ValidateDeployment(deployment)
}

Validate()调用了validation包中的ValidateDeployment()来确认deployment是否合法。

Canonicalize()方法实现如下:

1
2
3
// Canonicalize normalizes the object after validation.
func (deploymentStrategy) Canonicalize(obj runtime.Object) {
}

Canonicalize()方法为空。

AllowCreateOnUpdate()方法实现如下:

1
2
3
4
// AllowCreateOnUpdate is false for deployments.
func (deploymentStrategy) AllowCreateOnUpdate() bool {
return false
}

AllowCreateOnUpdate()方法返回false,表明不允许更新时创建。

PrepareForUpdate()方法实现如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// PrepareForUpdate clears fields that are not allowed to be set by end users on update.
func (deploymentStrategy) PrepareForUpdate(ctx api.Context, obj, old runtime.Object) {
newDeployment := obj.(*extensions.Deployment)
oldDeployment := old.(*extensions.Deployment)
newDeployment.Status = oldDeployment.Status
// Spec updates bump the generation so that we can distinguish between
// scaling events and template changes, annotation updates bump the generation
// because annotations are copied from deployments to their replica sets.
if !reflect.DeepEqual(newDeployment.Spec, oldDeployment.Spec) ||
!reflect.DeepEqual(newDeployment.Annotations, oldDeployment.Annotations) {
newDeployment.Generation = oldDeployment.Generation + 1
}
// Records timestamp on selector updates in annotation
if !reflect.DeepEqual(newDeployment.Spec.Selector, oldDeployment.Spec.Selector) {
if newDeployment.Annotations == nil {
newDeployment.Annotations = make(map[string]string)
}
now := unversioned.Now()
newDeployment.Annotations[util.SelectorUpdateAnnotation] = now.Format(time.RFC3339)
}
}

PrepareForUpdate()会对Generation和Annotations[util.SelectorUpdateAnnotation]进行更新。

ValidateUpdate()方法实现如下:

1
2
3
4
// ValidateUpdate is the default update validation for an end user.
func (deploymentStrategy) ValidateUpdate(ctx api.Context, obj, old runtime.Object) field.ErrorList {
return validation.ValidateDeploymentUpdate(obj.(*extensions.Deployment), old.(*extensions.Deployment))
}

ValidateDeploymentUpdate()调用validation包中的ValidateDeploymentUpdate()。

总结

Kubernetes的strategy机制提供了一种对具体资源进行具体处理的能力。资源的特殊操作都应该放在strategy的方法中。