New version of operator docs (#638)

controllers/factory/scrapes_test.go

@@ -27,6 +27,37 @@ func TestSelectServiceMonitors(t *testing.T) {
 		p *victoriametricsv1beta1.VMAgent
 		l logr.Logger
 	}
+
+	predefinedObjects := []runtime.Object{
+		&corev1.Namespace{ObjectMeta: metav1.ObjectMeta{Name: "default"}},
+		&victoriametricsv1beta1.VMServiceScrape{
+			ObjectMeta: metav1.ObjectMeta{Namespace: "default", Name: "ss1", Labels: map[string]string{"name": "ss1"}},
+			Spec:       victoriametricsv1beta1.VMServiceScrapeSpec{},
+		},
+		&victoriametricsv1beta1.VMServiceScrape{
+			ObjectMeta: metav1.ObjectMeta{Namespace: "default", Name: "ss2", Labels: map[string]string{"name": "ss2"}},
+			Spec:       victoriametricsv1beta1.VMServiceScrapeSpec{},
+		},
+		&corev1.Namespace{ObjectMeta: metav1.ObjectMeta{Name: "other1", Labels: map[string]string{"name": "other1"}}},
+		&victoriametricsv1beta1.VMServiceScrape{
+			ObjectMeta: metav1.ObjectMeta{Namespace: "other1", Name: "ss1", Labels: map[string]string{"name": "ss1"}},
+			Spec:       victoriametricsv1beta1.VMServiceScrapeSpec{},
+		},
+		&victoriametricsv1beta1.VMServiceScrape{
+			ObjectMeta: metav1.ObjectMeta{Namespace: "other1", Name: "ss2", Labels: map[string]string{"name": "ss2"}},
+			Spec:       victoriametricsv1beta1.VMServiceScrapeSpec{},
+		},
+		&corev1.Namespace{ObjectMeta: metav1.ObjectMeta{Name: "other2", Labels: map[string]string{"name": "other2"}}},
+		&victoriametricsv1beta1.VMServiceScrape{
+			ObjectMeta: metav1.ObjectMeta{Namespace: "other2", Name: "ss1", Labels: map[string]string{"name": "ss1"}},
+			Spec:       victoriametricsv1beta1.VMServiceScrapeSpec{},
+		},
+		&victoriametricsv1beta1.VMServiceScrape{
+			ObjectMeta: metav1.ObjectMeta{Namespace: "other2", Name: "ss2", Labels: map[string]string{"name": "ss2"}},
+			Spec:       victoriametricsv1beta1.VMServiceScrapeSpec{},
+		},
+	}
+
 	tests := []struct {
 		name              string
 		args              args
@@ -87,6 +118,166 @@ func TestSelectServiceMonitors(t *testing.T) {
 			want:    []string{"stg/default-monitor"},
 			wantErr: false,
 		},
+		{
+			name: "If NamespaceSelector and Selector both undefined, selectAllByDefault=false and empty watchNS",
+			args: args{
+				p: &victoriametricsv1beta1.VMAgent{
+					ObjectMeta: metav1.ObjectMeta{
+						Name:      "default-agent",
+						Namespace: "default",
+					},
+					Spec: victoriametricsv1beta1.VMAgentSpec{
+						ServiceScrapeNamespaceSelector: nil,
+						ServiceScrapeSelector:          nil,
+						SelectAllByDefault:             false,
+					},
+				},
+				l: logf.Log.WithName("unit-test"),
+			},
+			predefinedObjects: predefinedObjects,
+			want:              []string{},
+			wantErr:           false,
+		},
+		{
+			name: "If NamespaceSelector and Selector both undefined, selectAllByDefault=true and empty watchNS",
+			args: args{
+				p: &victoriametricsv1beta1.VMAgent{
+					ObjectMeta: metav1.ObjectMeta{
+						Name:      "default-agent",
+						Namespace: "default",
+					},
+					Spec: victoriametricsv1beta1.VMAgentSpec{
+						ServiceScrapeNamespaceSelector: nil,
+						ServiceScrapeSelector:          nil,
+						SelectAllByDefault:             true,
+					},
+				},
+				l: logf.Log.WithName("unit-test"),
+			},
+			predefinedObjects: predefinedObjects,
+			want:              []string{"default/ss1", "default/ss2", "other1/ss1", "other1/ss2", "other2/ss1", "other2/ss2"},
+			wantErr:           false,
+		},
+		{
+			name: "If NamespaceSelector defined, Selector undefined, selectAllByDefault=false and empty watchNS",
+			args: args{
+				p: &victoriametricsv1beta1.VMAgent{
+					ObjectMeta: metav1.ObjectMeta{
+						Name:      "default-agent",
+						Namespace: "default",
+					},
+					Spec: victoriametricsv1beta1.VMAgentSpec{
+						ServiceScrapeNamespaceSelector: &metav1.LabelSelector{MatchLabels: map[string]string{"name": "other1"}},
+						ServiceScrapeSelector:          nil,
+						SelectAllByDefault:             false,
+					},
+				},
+				l: logf.Log.WithName("unit-test"),
+			},
+			predefinedObjects: predefinedObjects,
+			want:              []string{"other1/ss1", "other1/ss2"},
+			wantErr:           false,
+		},
+		{
+			name: "If NamespaceSelector defined, Selector undefined, selectAllByDefault=true and empty watchNS",
+			args: args{
+				p: &victoriametricsv1beta1.VMAgent{
+					ObjectMeta: metav1.ObjectMeta{
+						Name:      "default-agent",
+						Namespace: "default",
+					},
+					Spec: victoriametricsv1beta1.VMAgentSpec{
+						ServiceScrapeNamespaceSelector: &metav1.LabelSelector{MatchLabels: map[string]string{"name": "other1"}},
+						ServiceScrapeSelector:          nil,
+						SelectAllByDefault:             true,
+					},
+				},
+				l: logf.Log.WithName("unit-test"),
+			},
+			predefinedObjects: predefinedObjects,
+			want:              []string{"other1/ss1", "other1/ss2"},
+			wantErr:           false,
+		},
+		{
+			name: "If NamespaceSelector undefined, Selector defined, selectAllByDefault=false and empty watchNS",
+			args: args{
+				p: &victoriametricsv1beta1.VMAgent{
+					ObjectMeta: metav1.ObjectMeta{
+						Name:      "default-agent",
+						Namespace: "default",
+					},
+					Spec: victoriametricsv1beta1.VMAgentSpec{
+						ServiceScrapeNamespaceSelector: nil,
+						ServiceScrapeSelector:          &metav1.LabelSelector{MatchLabels: map[string]string{"name": "ss1"}},
+						SelectAllByDefault:             false,
+					},
+				},
+				l: logf.Log.WithName("unit-test"),
+			},
+			predefinedObjects: predefinedObjects,
+			want:              []string{"default/ss1"},
+			wantErr:           false,
+		},
+		{
+			name: "If NamespaceSelector undefined, Selector defined, selectAllByDefault=true and empty watchNS",
+			args: args{
+				p: &victoriametricsv1beta1.VMAgent{
+					ObjectMeta: metav1.ObjectMeta{
+						Name:      "default-agent",
+						Namespace: "default",
+					},
+					Spec: victoriametricsv1beta1.VMAgentSpec{
+						ServiceScrapeNamespaceSelector: nil,
+						ServiceScrapeSelector:          &metav1.LabelSelector{MatchLabels: map[string]string{"name": "ss1"}},
+						SelectAllByDefault:             true,
+					},
+				},
+				l: logf.Log.WithName("unit-test"),
+			},
+			predefinedObjects: predefinedObjects,
+			want:              []string{"default/ss1"},
+			wantErr:           false,
+		},
+		{
+			name: "If NamespaceSelector and Selector both defined, selectAllByDefault=false and empty watchNS",
+			args: args{
+				p: &victoriametricsv1beta1.VMAgent{
+					ObjectMeta: metav1.ObjectMeta{
+						Name:      "default-agent",
+						Namespace: "default",
+					},
+					Spec: victoriametricsv1beta1.VMAgentSpec{
+						ServiceScrapeNamespaceSelector: &metav1.LabelSelector{MatchLabels: map[string]string{"name": "other1"}},
+						ServiceScrapeSelector:          &metav1.LabelSelector{MatchLabels: map[string]string{"name": "ss1"}},
+						SelectAllByDefault:             false,
+					},
+				},
+				l: logf.Log.WithName("unit-test"),
+			},
+			predefinedObjects: predefinedObjects,
+			want:              []string{"other1/ss1"},
+			wantErr:           false,
+		},
+		{
+			name: "If NamespaceSelector and Selector both defined, selectAllByDefault=true and empty watchNS",
+			args: args{
+				p: &victoriametricsv1beta1.VMAgent{
+					ObjectMeta: metav1.ObjectMeta{
+						Name:      "default-agent",
+						Namespace: "default",
+					},
+					Spec: victoriametricsv1beta1.VMAgentSpec{
+						ServiceScrapeNamespaceSelector: &metav1.LabelSelector{MatchLabels: map[string]string{"name": "other2"}},
+						ServiceScrapeSelector:          &metav1.LabelSelector{MatchLabels: map[string]string{"name": "ss2"}},
+						SelectAllByDefault:             true,
+					},
+				},
+				l: logf.Log.WithName("unit-test"),
+			},
+			predefinedObjects: predefinedObjects,
+			want:              []string{"other2/ss2"},
+			wantErr:           false,
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {

docs/CHANGELOG.MD

@@ -1,3 +1,9 @@
+---
+sort: 10
+weight: 10
+title: CHANGELOG
+---
+
 # CHANGELOG
 
 ## Next release

docs/README.md

@@ -0,0 +1,91 @@
+---
+sort: 0
+weight: 0
+title: VictoriaMetrics Operator
+---
+
+# VictoriaMetrics Operator
+
+Operator serves to make running VictoriaMetrics applications on top of Kubernetes as easy as possible while preserving Kubernetes-native configuration options.
+
+VictoriaMetrics Operator (`vmoperator`) is the classic kubernetes-operator for VictoriaMetrics with many [great features](#features).
+It allows you to manage Victoria Metrics components in Kubernetes or OpenShift clusters
+in a declarative style according to [GitOps](https://www.redhat.com/en/topics/devops/what-is-gitops)
+and [IaC](https://en.wikipedia.org/wiki/Infrastructure_as_code) concepts.
+
+VictoriaMetrics also provides [helm charts](https://github.com/VictoriaMetrics/helm-charts) without operator.
+Operator makes the same, simplifies it and provides [advanced features](https://docs.victorimetrics.com/operator/#features).
+
+Learn more about [key concepts](#key-concepts) of `vmoperator` and follow the **[quick start guide](https://docs.victoriametrics.com/operator/quickstart.html)** for a better experience.
+
+## Features of vmoperator
+
+- Deployment and management in a kubernetes clusters of any number of VictoriaMetrics applications (like vmsingle/vmcluster instances and another components like vmauth, vmagent, vmalert, etc...)
+- Seamless [migration from prometheus-operator](https://docs.victoriametrics.com/operator/migration.html) with auto-conversion of prometheus [custom resources](#custom-resources)
+- Simple VictoriaMetrics cluster installation, configuring, upgrading and managing with [crd-objects](https://docs.victoriametrics.com/operator/resources/).
+- Ability to delegate the configuration (parts of configuration) of applications monitoring to the end-users and managing access to different configurations or configuration sections.
+- Integration with VictoriaMetrics [vmbackupmanager](https://docs.victoriametrics.com/vmbackupmanager.html) - advanced tools for making backups. Check [backup docs](https://docs.victoriametrics.com/operator/backups.html)
+- Everything you need for monitoring out of the box in [k8s-stack helm chart](http://docs.victoriametrics.com/operator/deploy.html) with ready-made usecases and solutions.
+- Ability to template your own deployment scenarios.
+
+## Key Concepts
+
+### Kubernetes-operators
+
+[Kubernetes-operators](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) are software extensions
+for Kubernetes that make use of [custom resources](#custom-resources) to manage applications and their components.
+Operators follow Kubernetes principles, notably the control loop.
+It can be said that operators are custom controllers for Kubernetes that allow you to create business logic for custom resources.
+
+Design and implementation of `vmoperator` inspired by [prometheus-operator](https://github.com/prometheus-operator/prometheus-operator).
+
+Useful links:
+- [Custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
+- [Custom resource definitions](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)
+- [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)
+- [Operator best practices](https://sdk.operatorframework.io/docs/best-practices/)
+
+### Custom resources
+
+Kubernetes-Operators use [custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
+for interaction. Custom resources are a mechanism built into Kubernetes that allows you to create your own extensions for Kubernetes,
+working on the same principles as those built into Kubernetes APIs. Custom resources make Kubernetes so modular and extensible.
+
+In addition, thanks to CRD ([Custom Resource Definitions](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)),
+the mechanism of custom resources allows you to declare an API in the format of the OpenAPI specification and verify that the resources correspond to this API.
+
+### Reconciliation cycle
+
+The main task of the operator is to bring the state of the cluster in line with what is declared by the user in the custom resources.
+This process of constant monitoring and adjustment is called the "Reconciliation cycle" - it is the operator's workflow.
+
+The basic workflow of working with the operator can be simplified as the following diagram:
+
+<img src="README_operator-workflow.png" width="1200">
+
+- Operator declares and owns [resources of Victoria Metrics](http://docs.victoriametrics.com/operator/resources/).
+- Kubernetes validates of the resource according to the specification from CRD (see more in [custom resources](#custom-resources)).
+- Operator subscribed to change events (`create`, `update`, `delete`) for related resources.
+- When an event occurs, the operator reacts and updates the state of the objects in the cluster.
+- For some objects in the cluster the reconciliation cycle is performed at a given interval, even without the occurrence of change events (see `VM_FORCERESYNCINTERVAL`).
+
+### Next steps
+
+- [Quick Start Guide](https://docs.victoriametrics.com/operator/quickstart.html)
+- [Setup](https://docs.victoriametrics.com/operator/setup.html)
+- [Security](https://docs.victoriametrics.com/operator/security.html)
+- [Configuration](https://docs.victoriametrics.com/operator/configuration.html)
+- [Migration from Prometheus](https://docs.victoriametrics.com/operator/migration.html)
+- [Monitoring](https://docs.victoriametrics.com/operator/monitoring.html)
+- [Authorization and exposing components](https://docs.victoriametrics.com/operator/auth.html)
+- [High Availability](https://docs.victoriametrics.com/operator/high-availability.html)
+- [Enterprise](https://docs.victoriametrics.com/operator/enterprise.html)
+- [Custom resources](https://docs.victoriametrics.com/operator/resources/)
+
+If you have any questions, check out our [FAQ](https://docs.victoriametrics.com/operator/faq.html) 
+and feel free to can ask them:
+- [VictoriaMetrics Slack](https://victoriametrics.slack.com/)
+- [VictoriaMetrics Telegram](https://t.me/VictoriaMetrics_en)
+
+If you have any suggestions or find a bug, please create an issue
+on [GitHub](https://github.com/VictoriaMetrics/operator/issues/new).