Skip to content

Commit 68b2609

Browse files
bhavin192bhavin192
authored
docs: version upgrade guide: add more details for 0.11, 0.14, 0.16 (#3307)
**Motivation for the change:** Closes #3213
1 parent 4fa12a4 commit 68b2609

File tree

1 file changed

+168
-0
lines changed

1 file changed

+168
-0
lines changed

‎website/content/en/docs/migration/version-upgrade-guide.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -450,6 +450,8 @@ Upon updating the project to `v0.8.2` the following breaking changes apply:
450450
- `./pkg/controller/<kind>/<kind>_controller.go`
451451
- Replace import `sigs.k8s.io/controller-runtime/pkg/runtime/signals` with `sigs.k8s.io/controller-runtime/pkg/manager/signals` in:
452452
- `cmd/manager/main.go`
453+
- Remove import `sigs.k8s.io/controller-tools/pkg/crd/generator` from:
454+
- `tools.go`
453455

454456
**controller-runtime API updates**
455457

@@ -679,6 +681,109 @@ replace github.com/docker/docker => github.com/moby/moby v0.7.3-0.20190826074503
679681
- Run the command `operator-sdk generate k8s` to ensure that your resources will be updated
680682
- Run the command `operator-sdk generate crds` to regenerate CRDs
681683
684+
**(Optional) Skip metrics logs when the operator is running locally**
685+
686+
There are changes to the default implementation of the metrics export. These changes require `cmd/manager/main.go` to be updated as follows.
687+
688+
Update imports:
689+
690+
```go
691+
import (
692+
...
693+
"errors"
694+
...
695+
)
696+
```
697+
698+
Replace:
699+
700+
```go
701+
func main() {
702+
...
703+
if err = serveCRMetrics(cfg); err != nil {
704+
log.Info("Could not generate and serve custom resource metrics", "error", err.Error())
705+
}
706+
707+
// Add to the below struct any other metrics ports you want to expose.
708+
servicePorts := []v1.ServicePort{
709+
{Port: metricsPort, Name: metrics.OperatorPortName, Protocol: v1.ProtocolTCP, TargetPort: intstr.IntOrString{Type: intstr.Int, IntVal: metricsPort}},
710+
{Port: operatorMetricsPort, Name: metrics.CRPortName, Protocol: v1.ProtocolTCP, TargetPort: intstr.IntOrString{Type: intstr.Int, IntVal: operatorMetricsPort}},
711+
}
712+
// Create Service object to expose the metrics port(s).
713+
service, err := metrics.CreateMetricsService(ctx, cfg, servicePorts)
714+
if err != nil {
715+
log.Info("Could not create metrics Service", "error", err.Error())
716+
}
717+
718+
// CreateServiceMonitors will automatically create the prometheus-operator ServiceMonitor resources
719+
// necessary to configure Prometheus to scrape metrics from this operator.
720+
services := []*v1.Service{service}
721+
_, err = metrics.CreateServiceMonitors(cfg, namespace, services)
722+
if err != nil {
723+
log.Info("Could not create ServiceMonitor object", "error", err.Error())
724+
// If this operator is deployed to a cluster without the prometheus-operator running, it will return
725+
// ErrServiceMonitorNotPresent, which can be used to safely skip ServiceMonitor creation.
726+
if err == metrics.ErrServiceMonitorNotPresent {
727+
log.Info("Install prometheus-operator in your cluster to create ServiceMonitor objects", "error", err.Error())
728+
}
729+
}
730+
```
731+
732+
With:
733+
734+
```go
735+
func main() {
736+
...
737+
// Add the Metrics Service
738+
addMetrics(ctx, cfg, namespace)
739+
```
740+
741+
And then, add implementation for `addMetrics`:
742+
743+
```go
744+
// addMetrics will create the Services and Service Monitors to allow the operator export the metrics by using
745+
// the Prometheus operator
746+
func addMetrics(ctx context.Context, cfg *rest.Config, namespace string) {
747+
if err := serveCRMetrics(cfg); err != nil {
748+
if errors.Is(err, k8sutil.ErrRunLocal) {
749+
log.Info("Skipping CR metrics server creation; not running in a cluster.")
750+
return
751+
}
752+
log.Info("Could not generate and serve custom resource metrics", "error", err.Error())
753+
}
754+
755+
// Add to the below struct any other metrics ports you want to expose.
756+
servicePorts := []v1.ServicePort{
757+
{Port: metricsPort, Name: metrics.OperatorPortName, Protocol: v1.ProtocolTCP, TargetPort: intstr.IntOrString{Type: intstr.Int, IntVal: metricsPort}},
758+
{Port: operatorMetricsPort, Name: metrics.CRPortName, Protocol: v1.ProtocolTCP, TargetPort: intstr.IntOrString{Type: intstr.Int, IntVal: operatorMetricsPort}},
759+
}
760+
761+
// Create Service object to expose the metrics port(s).
762+
service, err := metrics.CreateMetricsService(ctx, cfg, servicePorts)
763+
if err != nil {
764+
log.Info("Could not create metrics Service", "error", err.Error())
765+
}
766+
767+
// CreateServiceMonitors will automatically create the prometheus-operator ServiceMonitor resources
768+
// necessary to configure Prometheus to scrape metrics from this operator.
769+
services := []*v1.Service{service}
770+
_, err = metrics.CreateServiceMonitors(cfg, namespace, services)
771+
if err != nil {
772+
log.Info("Could not create ServiceMonitor object", "error", err.Error())
773+
// If this operator is deployed to a cluster without the prometheus-operator running, it will return
774+
// ErrServiceMonitorNotPresent, which can be used to safely skip ServiceMonitor creation.
775+
if err == metrics.ErrServiceMonitorNotPresent {
776+
log.Info("Install prometheus-operator in your cluster to create ServiceMonitor objects", "error", err.Error())
777+
}
778+
}
779+
}
780+
781+
// serveCRMetrics gets the Operator/CustomResource GVKs and generates metrics based on those types.
782+
...
783+
```
784+
785+
**NOTE**: For more information check the PR which is responsible for the above changes [#2190](https://github.com/operator-framework/operator-sdk/pull/2190).
786+
682787
**Deprecations**
683788
684789
The `github.com/operator-framework/operator-sdk/pkg/restmapper` package was deprecated in favor of the `DynamicRESTMapper` implementation in [controller-runtime](https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/client/apiutil#NewDiscoveryRESTMapper). Users should migrate to controller-runtime's implementation, which is a drop-in replacement.
@@ -985,6 +1090,69 @@ func serveCRMetrics(cfg *rest.Config, operatorNs string) error {
9851090
9861091
**NOTE**: For more information check the PRs which are responsible for the above changes [#2606](https://github.com/operator-framework/operator-sdk/pull/2606),[#2603](https://github.com/operator-framework/operator-sdk/pull/2603) and [#2601](https://github.com/operator-framework/operator-sdk/pull/2601).
9871092
1093+
**(Optional) Support for watching multiple namespaces**
1094+
1095+
There are changes to add support for watching multiple namespaces. These changes require `cmd/manager/main.go` to be updated as follows.
1096+
1097+
Update imports:
1098+
1099+
```go
1100+
import (
1101+
...
1102+
"strings"
1103+
1104+
...
1105+
"sigs.k8s.io/controller-runtime/pkg/cache"
1106+
...
1107+
)
1108+
```
1109+
1110+
Replace:
1111+
1112+
```go
1113+
func main() {
1114+
...
1115+
// Create a new Cmd to provide shared dependencies and start components
1116+
mgr, err := manager.New(cfg, manager.Options{
1117+
Namespace: namespace,
1118+
MetricsBindAddress: fmt.Sprintf("%s:%d", metricsHost, metricsPort),
1119+
})
1120+
if err != nil {
1121+
log.Error(err, "")
1122+
os.Exit(1)
1123+
}
1124+
```
1125+
1126+
With:
1127+
1128+
```go
1129+
func main() {
1130+
...
1131+
// Set default manager options
1132+
options := manager.Options{
1133+
Namespace: namespace,
1134+
MetricsBindAddress: fmt.Sprintf("%s:%d", metricsHost, metricsPort),
1135+
}
1136+
1137+
// Add support for MultiNamespace set in WATCH_NAMESPACE (e.g ns1,ns2)
1138+
// Note that this is not intended to be used for excluding namespaces, this is better done via a Predicate
1139+
// Also note that you may face performance issues when using this with a high number of namespaces.
1140+
// More Info: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/cache#MultiNamespacedCacheBuilder
1141+
if strings.Contains(namespace, ",") {
1142+
options.Namespace = ""
1143+
options.NewCache = cache.MultiNamespacedCacheBuilder(strings.Split(namespace, ","))
1144+
}
1145+
1146+
// Create a new manager to provide shared dependencies and start components
1147+
mgr, err := manager.New(cfg, options)
1148+
if err != nil {
1149+
log.Error(err, "")
1150+
os.Exit(1)
1151+
}
1152+
```
1153+
1154+
**NOTE**: For more information check the PR which is responsible for the above changes [#2522](https://github.com/operator-framework/operator-sdk/pull/2522).
1155+
9881156
**Breaking changes**
9891157
9901158
**`TestCtx` in `pkg/test` has been deprecated**

0 commit comments

Comments
 (0)