2 Copyright 2018 The Kubernetes Authors.
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
8 http://www.apache.org/licenses/LICENSE-2.0
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
22 "k8s.io/apimachinery/pkg/api/meta"
23 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
24 "k8s.io/apimachinery/pkg/fields"
25 "k8s.io/apimachinery/pkg/labels"
26 "k8s.io/apimachinery/pkg/runtime"
27 "k8s.io/apimachinery/pkg/types"
30 // ObjectKey identifies a Kubernetes Object.
31 type ObjectKey = types.NamespacedName
33 // ObjectKeyFromObject returns the ObjectKey given a runtime.Object
34 func ObjectKeyFromObject(obj runtime.Object) (ObjectKey, error) {
35 accessor, err := meta.Accessor(obj)
37 return ObjectKey{}, err
39 return ObjectKey{Namespace: accessor.GetNamespace(), Name: accessor.GetName()}, nil
42 // TODO(directxman12): is there a sane way to deal with get/delete options?
44 // Reader knows how to read and list Kubernetes objects.
45 type Reader interface {
46 // Get retrieves an obj for the given object key from the Kubernetes Cluster.
47 // obj must be a struct pointer so that obj can be updated with the response
48 // returned by the Server.
49 Get(ctx context.Context, key ObjectKey, obj runtime.Object) error
51 // List retrieves list of objects for a given namespace and list options. On a
52 // successful call, Items field in the list will be populated with the
53 // result returned from the server.
54 List(ctx context.Context, opts *ListOptions, list runtime.Object) error
57 // Writer knows how to create, delete, and update Kubernetes objects.
58 type Writer interface {
59 // Create saves the object obj in the Kubernetes cluster.
60 Create(ctx context.Context, obj runtime.Object) error
62 // Delete deletes the given obj from Kubernetes cluster.
63 Delete(ctx context.Context, obj runtime.Object, opts ...DeleteOptionFunc) error
65 // Update updates the given obj in the Kubernetes cluster. obj must be a
66 // struct pointer so that obj can be updated with the content returned by the Server.
67 Update(ctx context.Context, obj runtime.Object) error
70 // StatusClient knows how to create a client which can update status subresource
71 // for kubernetes objects.
72 type StatusClient interface {
76 // StatusWriter knows how to update status subresource of a Kubernetes object.
77 type StatusWriter interface {
78 // Update updates the fields corresponding to the status subresource for the
79 // given obj. obj must be a struct pointer so that obj can be updated
80 // with the content returned by the Server.
81 Update(ctx context.Context, obj runtime.Object) error
84 // Client knows how to perform CRUD operations on Kubernetes objects.
85 type Client interface {
91 // IndexerFunc knows how to take an object and turn it into a series
92 // of (non-namespaced) keys for that object.
93 type IndexerFunc func(runtime.Object) []string
95 // FieldIndexer knows how to index over a particular "field" such that it
96 // can later be used by a field selector.
97 type FieldIndexer interface {
98 // IndexFields adds an index with the given field name on the given object type
99 // by using the given function to extract the value for that field. If you want
100 // compatibility with the Kubernetes API server, only return one key, and only use
101 // fields that the API server supports. Otherwise, you can return multiple keys,
102 // and "equality" in the field selector means that at least one key matches the value.
103 IndexField(obj runtime.Object, field string, extractValue IndexerFunc) error
106 // DeleteOptions contains options for delete requests. It's generally a subset
107 // of metav1.DeleteOptions.
108 type DeleteOptions struct {
109 // GracePeriodSeconds is the duration in seconds before the object should be
110 // deleted. Value must be non-negative integer. The value zero indicates
111 // delete immediately. If this value is nil, the default grace period for the
112 // specified type will be used.
113 GracePeriodSeconds *int64
115 // Preconditions must be fulfilled before a deletion is carried out. If not
116 // possible, a 409 Conflict status will be returned.
117 Preconditions *metav1.Preconditions
119 // PropagationPolicy determined whether and how garbage collection will be
120 // performed. Either this field or OrphanDependents may be set, but not both.
121 // The default policy is decided by the existing finalizer set in the
122 // metadata.finalizers and the resource-specific default policy.
123 // Acceptable values are: 'Orphan' - orphan the dependents; 'Background' -
124 // allow the garbage collector to delete the dependents in the background;
125 // 'Foreground' - a cascading policy that deletes all dependents in the
127 PropagationPolicy *metav1.DeletionPropagation
129 // Raw represents raw DeleteOptions, as passed to the API server.
130 Raw *metav1.DeleteOptions
133 // AsDeleteOptions returns these options as a metav1.DeleteOptions.
134 // This may mutate the Raw field.
135 func (o *DeleteOptions) AsDeleteOptions() *metav1.DeleteOptions {
138 return &metav1.DeleteOptions{}
141 o.Raw = &metav1.DeleteOptions{}
144 o.Raw.GracePeriodSeconds = o.GracePeriodSeconds
145 o.Raw.Preconditions = o.Preconditions
146 o.Raw.PropagationPolicy = o.PropagationPolicy
150 // ApplyOptions executes the given DeleteOptionFuncs and returns the mutated
152 func (o *DeleteOptions) ApplyOptions(optFuncs []DeleteOptionFunc) *DeleteOptions {
153 for _, optFunc := range optFuncs {
159 // DeleteOptionFunc is a function that mutates a DeleteOptions struct. It implements
160 // the functional options pattern. See
161 // https://github.com/tmrts/go-patterns/blob/master/idiom/functional-options.md.
162 type DeleteOptionFunc func(*DeleteOptions)
164 // GracePeriodSeconds is a functional option that sets the GracePeriodSeconds
165 // field of a DeleteOptions struct.
166 func GracePeriodSeconds(gp int64) DeleteOptionFunc {
167 return func(opts *DeleteOptions) {
168 opts.GracePeriodSeconds = &gp
172 // Preconditions is a functional option that sets the Preconditions field of a
173 // DeleteOptions struct.
174 func Preconditions(p *metav1.Preconditions) DeleteOptionFunc {
175 return func(opts *DeleteOptions) {
176 opts.Preconditions = p
180 // PropagationPolicy is a functional option that sets the PropagationPolicy
181 // field of a DeleteOptions struct.
182 func PropagationPolicy(p metav1.DeletionPropagation) DeleteOptionFunc {
183 return func(opts *DeleteOptions) {
184 opts.PropagationPolicy = &p
188 // ListOptions contains options for limitting or filtering results.
189 // It's generally a subset of metav1.ListOptions, with support for
190 // pre-parsed selectors (since generally, selectors will be executed
191 // against the cache).
192 type ListOptions struct {
193 // LabelSelector filters results by label. Use SetLabelSelector to
194 // set from raw string form.
195 LabelSelector labels.Selector
196 // FieldSelector filters results by a particular field. In order
197 // to use this with cache-based implementations, restrict usage to
198 // a single field-value pair that's been added to the indexers.
199 FieldSelector fields.Selector
201 // Namespace represents the namespace to list for, or empty for
202 // non-namespaced objects, or to list across all namespaces.
205 // Raw represents raw ListOptions, as passed to the API server. Note
206 // that these may not be respected by all implementations of interface,
207 // and the LabelSelector and FieldSelector fields are ignored.
208 Raw *metav1.ListOptions
211 // SetLabelSelector sets this the label selector of these options
212 // from a string form of the selector.
213 func (o *ListOptions) SetLabelSelector(selRaw string) error {
214 sel, err := labels.Parse(selRaw)
218 o.LabelSelector = sel
222 // SetFieldSelector sets this the label selector of these options
223 // from a string form of the selector.
224 func (o *ListOptions) SetFieldSelector(selRaw string) error {
225 sel, err := fields.ParseSelector(selRaw)
229 o.FieldSelector = sel
233 // AsListOptions returns these options as a flattened metav1.ListOptions.
234 // This may mutate the Raw field.
235 func (o *ListOptions) AsListOptions() *metav1.ListOptions {
237 return &metav1.ListOptions{}
240 o.Raw = &metav1.ListOptions{}
242 if o.LabelSelector != nil {
243 o.Raw.LabelSelector = o.LabelSelector.String()
245 if o.FieldSelector != nil {
246 o.Raw.FieldSelector = o.FieldSelector.String()
251 // MatchingLabels is a convenience function that sets the label selector
252 // to match the given labels, and then returns the options.
253 // It mutates the list options.
254 func (o *ListOptions) MatchingLabels(lbls map[string]string) *ListOptions {
255 sel := labels.SelectorFromSet(lbls)
256 o.LabelSelector = sel
260 // MatchingField is a convenience function that sets the field selector
261 // to match the given field, and then returns the options.
262 // It mutates the list options.
263 func (o *ListOptions) MatchingField(name, val string) *ListOptions {
264 sel := fields.SelectorFromSet(fields.Set{name: val})
265 o.FieldSelector = sel
269 // InNamespace is a convenience function that sets the namespace,
270 // and then returns the options. It mutates the list options.
271 func (o *ListOptions) InNamespace(ns string) *ListOptions {
276 // MatchingLabels is a convenience function that constructs list options
277 // to match the given labels.
278 func MatchingLabels(lbls map[string]string) *ListOptions {
279 return (&ListOptions{}).MatchingLabels(lbls)
282 // MatchingField is a convenience function that constructs list options
283 // to match the given field.
284 func MatchingField(name, val string) *ListOptions {
285 return (&ListOptions{}).MatchingField(name, val)
288 // InNamespace is a convenience function that constructs list
289 // options to list in the given namespace.
290 func InNamespace(ns string) *ListOptions {
291 return (&ListOptions{}).InNamespace(ns)