Skip to content

Commit

Permalink
update runtime Client options and method signatures
Browse files Browse the repository at this point in the history
  • Loading branch information
@estroz
estroz committed Aug 27, 2019
1 parent 5a64d9b commit d9bc749
Show file tree
Hide file tree
Showing 2 changed files with 92 additions and 8 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
- The package `sigs.k8s.io/controller-runtime/pkg/runtime/scheme` is deprecated, and contains no code. Replace this import with `sigs.k8s.io/controller-runtime/pkg/scheme` where relevant.
- The package `sigs.k8s.io/controller-runtime/pkg/runtime/log` is deprecated. Replace this import with `sigs.k8s.io/controller-runtime/pkg/log` where relevant.
- The package `sigs.k8s.io/controller-runtime/pkg/runtime/signals` is deprecated. Replace this import with `sigs.k8s.io/controller-runtime/pkg/manager/signals` where relevant.
- All methods on [`sigs.k8s.io/controller-runtime/pkg/client.Client`](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.2.0/pkg/client/interfaces.go#L104) (except for `Get()`) have been updated. Instead of each using a `struct`-typed or variadic functional option parameter, or having no option parameter, each now uses a variadic interface option parameter typed for each method. See `List()` below for an example.
- [`sigs.k8s.io/controller-runtime/pkg/client.Client`](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.2.0/pkg/client/interfaces.go#L104)'s `List()` method signature has been updated: `List(ctx context.Context, opts *client.ListOptions, list runtime.Object) error` is now [`List(ctx context.Context, list runtime.Object, opts ...client.ListOption) error`](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.2.0/pkg/client/interfaces.go#L61). To migrate:
```go
import (
Expand Down
99 changes: 91 additions & 8 deletions doc/user/client.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ func (r *ReconcileApp) Reconcile(request reconcile.Request) (reconcile.Result, e
func (c Client) List(ctx context.Context, list runtime.Object, opts ...client.ListOption) error
```

A `client.ListOption` is an interface that sets [`client.ListOptions`](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.2.0/pkg/client/options.go#L257) fields. A `client.ListOption` is created by using one of the provided implementations: [`LableSelector`](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.2.0/pkg/client/options.go#L304), [`FieldSelector`](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.2.0/pkg/client/options.go#L326), [`Namespace`](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.2.0/pkg/client/options.go#L339).
A `client.ListOption` is an interface that sets [`client.ListOptions`][list-options] fields. A `client.ListOption` is created by using one of the provided implementations: [`MatchingLabels`][matchinglabels], [`MatchingFields`][matchingfields], [`InNamespace`][innamespace].

Example:

Expand Down Expand Up @@ -168,14 +168,23 @@ func (r *ReconcileApp) Reconcile(request reconcile.Request) (reconcile.Result, e
}
```

[list-options]:https://godoc.org/sigs.k8s.io/controller-runtime/pkg/client#ListOptions
[matchinglabels]:https://godoc.org/sigs.k8s.io/controller-runtime/pkg/client#MatchingLabels
[matchingfields]:https://godoc.org/sigs.k8s.io/controller-runtime/pkg/client#MatchingFields
[innamespace]:https://godoc.org/sigs.k8s.io/controller-runtime/pkg/client#InNamespace

#### Create

```Go
// Create saves the object obj in the Kubernetes cluster.
// Returns an error
func (c Client) Create(ctx context.Context, obj runtime.Object) error
func (c Client) Create(ctx context.Context, obj runtime.Object, opts ...client.CreateOption) error
```

A `client.CreateOption` is an interface that sets [`client.CreateOptions`][create-options] fields. A `client.CreateOption` is created by using one of the provided implementations: [`DryRunAll`][dryrunall], [`ForceOwnership`][forceownership]. Generally these options are not needed.

Example:

```Go
import (
"context"
Expand All @@ -196,16 +205,22 @@ func (r *ReconcileApp) Reconcile(request reconcile.Request) (reconcile.Result, e
}
```

[create-options]:https://godoc.org/sigs.k8s.io/controller-runtime/pkg/client#CreateOptions

#### Update

```Go
// Update updates the given obj in the Kubernetes cluster. obj must be a
// struct pointer so that obj can be updated with the content returned
// by the API server. Update does *not* update the resource's status
// subresource
func (c Client) Update(ctx context.Context, obj runtime.Object) error
func (c Client) Update(ctx context.Context, obj runtime.Object, opts ...client.UpdateOption) error
```

A `client.UpdateOption` is an interface that sets [`client.UpdateOptions`][update-options] fields. A `client.UpdateOption` is created by using one of the provided implementations: [`DryRunAll`][dryrunall], [`ForceOwnership`][forceownership]. Generally these options are not needed.

Example:

```Go
import (
"context"
Expand All @@ -229,10 +244,54 @@ func (r *ReconcileApp) Reconcile(request reconcile.Request) (reconcile.Result, e
}
```

[update-options]:https://godoc.org/sigs.k8s.io/controller-runtime/pkg/client#UpdateOptions

#### Patch

```Go
// Patch patches the given obj in the Kubernetes cluster. obj must be a
// struct pointer so that obj can be updated with the content returned by the Server.
func (c Client) Patch(ctx context.Context, obj runtime.Object, patch client.Patch, opts ...client.UpdateOption) error
```

A `client.PatchOption` is an interface that sets [`client.PatchOptions`][patch-options] fields. A `client.PatchOption` is created by using one of the provided implementations: [`DryRunAll`][dryrunall], [`ForceOwnership`][forceownership]. Generally these options are not needed.

Example:

```Go
import (
"context"
"k8s.io/api/apps/v1"
"sigs.k8s.io/controller-runtime/pkg/reconcile"
)

func (r *ReconcileApp) Reconcile(request reconcile.Request) (reconcile.Result, error) {
...

dep := &v1.Deployment{}
err := r.client.Get(context.TODO(), request.NamespacedName, dep)

...

ctx := context.TODO()
dep.Spec.Selector.MatchLabels["is_running"] = "true"
// A marge patch will preserve other fields modified at runtime.
patch := client.MergeFrom(dep)
err := r.client.Patch(ctx, dep, patch)

...
}
```

[patch-options]:https://godoc.org/sigs.k8s.io/controller-runtime/pkg/client#PatchOption
[dryrunall]:https://godoc.org/sigs.k8s.io/controller-runtime/pkg/client#DryRunAll
[forceownership]:https://godoc.org/sigs.k8s.io/controller-runtime/pkg/client#ForceOwnership

##### Updating Status Subresource

When updating the [status subresource][cr-status-subresource] from the client,
the StatusWriter must be used which can be gotten with `Status()`
When updating the [status subresource][cr-status-subresource] from the client, the [`StatusWriter`][statuswriter] must be used. The status subresource is retrieved with `Status()` and updated with `Update()` or patched with `Patch()`.

`Update()` takes variadic `client.UpdateOption`'s, and `Patch()` takes variadic `client.PatchOption`'s. See [`Client.Update()`](#update) and [`Client.Patch()`](#patch) for more details. Generally these options are not needed.

##### Status

Expand All @@ -253,19 +312,27 @@ import (
func (r *ReconcileApp) Reconcile(request reconcile.Request) (reconcile.Result, error) {
...

ctx := context.TODO()
mem := &cachev1alpha1.Memcached{}
err := r.client.Get(context.TODO(), request.NamespacedName, mem)
err := r.client.Get(ctx, request.NamespacedName, mem)

...

ctx := context.TODO()
// Update
mem.Status.Nodes = []string{"pod1", "pod2"}
err := r.client.Status().Update(ctx, mem)

...

// Patch
patch := client.MergeFrom(mem)
err := r.client.Status().Patch(ctx, mem, patch)

...
}
```

[statuswriter]:https://godoc.org/sigs.k8s.io/controller-runtime/pkg/client#StatusWriter

#### Delete

Expand All @@ -274,7 +341,7 @@ func (r *ReconcileApp) Reconcile(request reconcile.Request) (reconcile.Result, e
func (c Client) Delete(ctx context.Context, obj runtime.Object, opts ...client.DeleteOption) error
```

A `client.DeleteOption` is an interface that sets [`client.DeleteOptions`](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.2.0/pkg/client/options.go#L156) fields. A `client.DeleteOption` is created by using one of the provided implementations: [`GracePeriodSeconds`](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.2.0/pkg/client/options.go#L216), [`Preconditions`](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.2.0/pkg/client/options.go#L227), [`PropagationPolicy`](https://github.com/kubernetes-sigs/controller-runtime/blob/v0.2.0/pkg/client/options.go#L238).
A `client.DeleteOption` is an interface that sets [`client.DeleteOptions`][delete-opts] fields. A `client.DeleteOption` is created by using one of the provided implementations: [`GracePeriodSeconds`][graceperiodseconds], [`Preconditions`][preconditions], [`PropagationPolicy`][propagationpolicy].

Example:

Expand Down Expand Up @@ -305,6 +372,22 @@ func (r *ReconcileApp) Reconcile(request reconcile.Request) (reconcile.Result, e
}
```

[delete-opts]:https://godoc.org/sigs.k8s.io/controller-runtime/pkg/client#DeleteOptions
[graceperiodseconds]:https://godoc.org/sigs.k8s.io/controller-runtime/pkg/client#GracePeriodSeconds
[preconditions]:https://godoc.org/sigs.k8s.io/controller-runtime/pkg/client#Preconditions
[propagationpolicy]:https://godoc.org/sigs.k8s.io/controller-runtime/pkg/client#PropagationPolicy

#### Delete

```Go
// DeleteAllOf deletes all objects of the given type matching the given options.
func (c Client) Delete(ctx context.Context, obj runtime.Object, opts ...client.DeleteAllOfOption) error
```

A `client.DeleteAllOfOption` is an interface that sets [`client.DeleteAllOfOptions`][deleteallof-opts] fields. A `client.DeleteAllOfOption` wraps a [`client.ListOption`](#list) and [`client.DeleteOption`](#delete).

[deleteallof-opts]:https://godoc.org/sigs.k8s.io/controller-runtime/pkg/client#DeleteAllOfOptions

### Example usage

```Go
Expand Down

0 comments on commit d9bc749

Please sign in to comment.