kubernetes-sigs / kubernetes-sigs/controller-runtime
Enable a user-friendly means of the controller-manager self-identifying with a distinct ID with HTTP calls
- Dominant language
- Go
- Stars
- 3k
- Forks
- 1.3k
- Avg merge
- 2d 5h
- Merged PRs (30d)
- 14
Description
# Summary
This story tracks enabling a user-friendly option for telling controller-runtime to self-identify with a distinct ID when making HTTP calls to the Kubernetes API server.
# Context
The actor that causes a raw Kubernetes event to occur is identified by a field named `manager`, for example:
```json
{
"type": "MODIFIED",
"object": {
"apiVersion": "vmoperator.vmware.com/v1alpha1",
"kind": "VirtualMachine",
"metadata": {
"annotations": {
"vsphere-cluster-module-group": "tkg7-cluster7-workers-0",
"vsphere-tag": "WorkerVmVmAATag"
},
"creationTimestamp": "2020-10-08T11:41:50Z",
"finalizers": [
"virtualmachine.vmoperator.vmware.com"
],
"generation": 19,
"labels": {
"capw.vmware.com/cluster.name": "tkg7-cluster7",
"capw.vmware.com/cluster.role": "node"
},
"managedFields": [
{
"apiVersion": "vmoperator.vmware.com/v1alpha1",
"fieldsType": "FieldsV1",
"fieldsV1": { ... }
"manager": "manager",
"operation": "Update",
"time": "2020-10-08T14:11:49Z"
}
],
"name": "tkg7-cluster7-workers-whph9-6ff8cdb6fb-fq2b6",
"namespace": "tkg7",
...
},
...
}
```
These raw, Kubernetes events are useful for root cause analysis (RCA). The field `object.metadata.managedFields[0].manager` has a value of simply `manager`. This is the identifier for the actor that caused this `MODIFIED` event to occur, but `manager` is not exactly helpful in identifying the component in question.
The reason, if the reader will permit this author to make a broad guess, is that the majority of projects based on controller-runtime and [client-go](https://github.com/kubernetes/client-go) have adopted the pattern of naming the manager binary simply manager for a few reasons:
* It simplifies Makefiles
* It simplifies CI
* It enables a standard pattern for managing/working on these projects
So, good reasons. Unfortunately it has the side effect that all the components send the same user agent to the API server when updating/patching resources. This happens because:
* When controller-runtime creates a `*rest.Config`, it creates a [user-agent string](https://github.com/kubernetes-sigs/controller-runtime/blob/053454753c02b59084a1061011e58a85f9656b22/pkg/client/apiutil/apimachinery.go#L94) for HTTP calls
* This user-agent string is based on a call to client-go's [`DefaultKubernetesUserAgent() string`](https://github.com/kubernetes/client-go/blob/5682372f35384ad502addfa244930da534af433b/rest/config.go#L459-L466), which builds part of the string from `os.Args[0]`; in other words, the name of the controller manager binary.
# Suggestions
Therefore, instead of updating the name of the manager binary for all projects based on controller-runtime, this issue tracks a way to easily provide a unique way to identify the manager. Some suggested ideas are:
* Standardizing on some environment variable (ex. `MANAGER_NAME`), flag (ex. `--manager-name`), or manager option used to override the name given to the user agent
* Update [`sig.k8s.io/controller-runtime/pkg/manager.Options`](https://github.com/kubernetes-sigs/controller-runtime/blob/c000ea850121b53dd769f624f3bfa74a4fcf100f/pkg/manager/manager.go#L121-L266) with a field like so:
```go
// Options are the arguments for creating a new Manager
type Options struct {
//
// ...
//
// Name is an optional identifier to assign to the Manager.
// This value is part of the User-Agent string used with HTTP calls to the API server,
// and can help identify this controller-manager as the actor responsible for lifecycle
// changes in resources, ex. ADDED, MODIFIED, DELETED.
// Defaults to the name of the controller manager binary, ex. os.Args[0].
Name string
//
// ...
//
}
```
Thoughts, concerns?
Contributor guide
Research direction
Start with pkg/client/apiutil/apimachinery.go to understand how the user-agent string is created, then inspect pkg/manager/manager.go and its Options type. Resolve how a manager identifier should be supplied and applied to HTTP calls, with completion shown by a distinct identifier in Kubernetes managed fields and events.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- api, backend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100