1
0
Fork 0
mirror of https://github.com/prometheus-operator/prometheus-operator.git synced 2025-04-16 09:16:38 +00:00

Setup mdox

Signed-off-by: Saswata Mukherjee <saswataminsta@yahoo.com>
This commit is contained in:
Saswata Mukherjee 2021-07-31 20:48:30 +05:30
parent 2a802a189b
commit d3043017b9
16 changed files with 405 additions and 104 deletions

View file

@ -1,13 +0,0 @@
{
"ignorePatterns": [
{
"pattern": "^http://127.0.0.1"
},
{
"pattern": "^http://localhost"
},
{
"pattern": "^http://proxyserver"
}
]
}

View file

@ -25,16 +25,15 @@ jobs:
with:
go-version: ${{ env.golang-version }}
- run: make --always-make format generate && git diff --exit-code
check-links:
check-docs:
runs-on: ubuntu-latest
name: Check markdown links
name: Check Documentation formatting and links
steps:
- uses: actions/checkout@v2
- uses: gaurav-nelson/github-action-markdown-link-check@v1
- uses: actions/setup-go@v2
with:
use-quiet-mode: 'yes'
config-file: '.github/workflows/.mlc_config.json'
continue-on-error: true
go-version: ${{ env.golang-version }}
- run: make check-docs
check-golang:
runs-on: ubuntu-latest
name: Golang linter

15
.mdox.validate.yaml Normal file
View file

@ -0,0 +1,15 @@
version: 1
validators:
# Cloudflare protection, so returns 503 if not in browser. Cannot curl as well.
- regex: 'wise\.com'
type: "ignore"
# Adopters example link.
- regex: "our-link"
type: "ignore"
# 301 errors even when curl-ed.
- regex: "envoyproxy"
type: "ignore"
# Ignore release links.
- regex: 'https:\/\/github\.com\/prometheus-operator\/prometheus-operator\/releases'
type: "ignore"

View file

@ -51,8 +51,7 @@ networkpolicy "prometheus" configured
* Allow inbound tcp dst port 9093 from any source to alertmanager
* Allow inbound tcp & udp dst port 9094 from only alertmanager to alertmanager
[embedmd]:# (../example/networkpolicies/alertmanager.yaml)
```yaml
```yaml mdox-exec="cat example/networkpolicies/alertmanager.yaml"
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
@ -101,8 +100,7 @@ spec:
* Allow inbound tcp dst port 3000 from any source to grafana
[embedmd]:# (../example/networkpolicies/grafana.yaml)
```yaml
```yaml mdox-exec="cat example/networkpolicies/grafana.yaml"
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
@ -121,8 +119,7 @@ spec:
* Allow inbound tcp dst port 9090 from any source to prometheus
[embedmd]:# (../example/networkpolicies/prometheus.yaml)
```yaml
```yaml mdox-exec="cat example/networkpolicies/prometheus.yaml"
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
@ -142,8 +139,7 @@ spec:
* Allow inbound tcp dst port 9100 from only prometheus to node-exporter
[embedmd]:# (../example/networkpolicies/node-exporter.yaml)
```yaml
```yaml mdox-exec="cat example/networkpolicies/node-exporter.yaml"
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
@ -173,8 +169,7 @@ spec:
* Allow inbound tcp dst port 8080 from only prometheus to kube-state-metrics
[embedmd]:# (../example/networkpolicies/kube-state-metrics.yaml)
```yaml
```yaml mdox-exec="cat example/networkpolicies/kube-state-metrics.yaml"
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:

View file

@ -28,8 +28,7 @@ This grants:
- Users with `view` role permissions to view the Prometheus Operator CRDs within their namespaces,
- Users with `edit` and `admin` roles permissions to create, edit and delete Prometheus Operator CRDs within their namespaces.
[embedmd]:# (../example/rbac/prometheus-operator-crd/prometheus-operator-crd-cluster-roles.yaml)
```yaml
```yaml mdox-exec="cat example/rbac/prometheus-operator-crd/prometheus-operator-crd-cluster-roles.yaml"
kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:

View file

@ -20,8 +20,7 @@ In order for the Prometheus Operator to work in an RBAC based authorization envi
Here is a ready to use manifest of a `ClusterRole` that can be used to start the Prometheus Operator:
[embedmd]:# (../example/rbac/prometheus-operator/prometheus-operator-cluster-role.yaml)
```yaml
```yaml mdox-exec="cat example/rbac/prometheus-operator/prometheus-operator-cluster-role.yaml"
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
@ -133,8 +132,7 @@ As Prometheus does not modify any Objects in the Kubernetes API, but just reads
In addition to the resources Prometheus itself needs to access, the Prometheus side-car needs to be able to `get` configmaps to be able to pull in rule files from configmap objects.
[embedmd]:# (../example/rbac/prometheus/prometheus-cluster-role.yaml)
```yaml
```yaml mdox-exec="cat example/rbac/prometheus/prometheus-cluster-role.yaml"
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
@ -169,8 +167,7 @@ To demonstrate how to use a `ClusterRole` with a `ClusterRoleBinding` and a `Ser
Say the Prometheus Operator shall be deployed in the `default` namespace. First a `ServiceAccount` needs to be setup.
[embedmd]:# (../example/rbac/prometheus-operator/prometheus-operator-service-account.yaml)
```yaml
```yaml mdox-exec="cat example/rbac/prometheus-operator/prometheus-operator-service-account.yaml"
apiVersion: v1
kind: ServiceAccount
metadata:
@ -186,8 +183,7 @@ Note that the `ServiceAccountName` also has to actually be used in the `PodTempl
And then a `ClusterRoleBinding`:
[embedmd]:# (../example/rbac/prometheus-operator/prometheus-operator-cluster-role-binding.yaml)
```yaml
```yaml mdox-exec="cat example/rbac/prometheus-operator/prometheus-operator-cluster-role-binding.yaml"
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
@ -210,8 +206,7 @@ Because the `Pod` that the Prometheus Operator is running in uses the `ServiceAc
When creating `Prometheus` objects the procedure is similar. It starts with a `ServiceAccount`.
[embedmd]:# (../example/rbac/prometheus/prometheus-service-account.yaml)
```yaml
```yaml mdox-exec="cat example/rbac/prometheus/prometheus-service-account.yaml"
apiVersion: v1
kind: ServiceAccount
metadata:
@ -220,8 +215,7 @@ metadata:
And then because the `ClusterRole` named `prometheus`, as described above, is likely to be used multiple times, a `ClusterRoleBinding` instead of a `RoleBinding` is used.
[embedmd]:# (../example/rbac/prometheus/prometheus-cluster-role-binding.yaml)
```yaml
```yaml mdox-exec="cat example/rbac/prometheus/prometheus-cluster-role-binding.yaml"
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:

View file

@ -21,8 +21,7 @@ The Prometheus Operator also introduces an AlertmanagerConfig resource, which al
First, create an example Alertmanager cluster, with three instances.
[embedmd]:# (../../example/user-guides/alerting/alertmanager-example.yaml)
```yaml
```yaml mdox-exec="cat example/user-guides/alerting/alertmanager-example.yaml"
apiVersion: monitoring.coreos.com/v1
kind: Alertmanager
metadata:
@ -39,8 +38,7 @@ For more information on configuring Alertmanager, see the Prometheus [Alerting C
The following example configuration creates an AlertmanagerConfig resource that sends notifications to a non-existent `wechat` receiver:
[embedmd]:# (../../example/user-guides/alerting/alertmanager-config-example.yaml)
```yaml
```yaml mdox-exec="cat example/user-guides/alerting/alertmanager-config-example.yaml"
apiVersion: monitoring.coreos.com/v1alpha1
kind: AlertmanagerConfig
metadata:
@ -81,8 +79,7 @@ $ kubectl create -f alertmanager-config.yaml
The `alertmanagerConfigSelector` field in the Alertmanager resource Spec needs to be specified so that the operator can select such AlertmanagerConfig resources. In the previous example, the label `alertmanagerConfig: example` is added, so the Alertmanager instance should be updated, adding the `alertmanagerConfigSelector`:
[embedmd]:# (../../example/user-guides/alerting/alertmanager-selector-example.yaml)
```yaml
```yaml mdox-exec="cat example/user-guides/alerting/alertmanager-selector-example.yaml"
apiVersion: monitoring.coreos.com/v1
kind: Alertmanager
metadata:
@ -98,8 +95,7 @@ spec:
The following example configuration sends notifications against to a `webhook`:
[embedmd]:# (../../example/user-guides/alerting/alertmanager.yaml)
```yaml
```yaml mdox-exec="cat example/user-guides/alerting/alertmanager.yaml"
global:
resolve_timeout: 5m
route:
@ -150,8 +146,7 @@ Once the operator merges the optional manually specified Secret with any selecte
To be able to view the web UI, expose it through a Service. A simple way to do this is to use a Service of type `NodePort`.
[embedmd]:# (../../example/user-guides/alerting/alertmanager-example-service.yaml)
```yaml
```yaml mdox-exec="cat example/user-guides/alerting/alertmanager-example-service.yaml"
apiVersion: v1
kind: Service
metadata:
@ -174,8 +169,7 @@ Once created it allows the web UI to be accessible via a Node's IP and the port
This Alertmanager cluster is now fully functional and highly available, but no alerts are fired against it. Create Prometheus instances to fire alerts to the Alertmanagers.
[embedmd]:# (../../example/user-guides/alerting/prometheus-example.yaml)
```yaml
```yaml mdox-exec="cat example/user-guides/alerting/prometheus-example.yaml"
apiVersion: monitoring.coreos.com/v1
kind: Prometheus
metadata:
@ -202,8 +196,7 @@ Prometheus rule files are held in `PrometheusRule` custom resources. Use the lab
The best practice is to label the `PrometheusRule`s containing rule files with `role: alert-rules` as well as the name of the Prometheus object, `prometheus: example` in this case.
[embedmd]:# (../../example/user-guides/alerting/prometheus-example-rules.yaml)
```yaml
```yaml mdox-exec="cat example/user-guides/alerting/prometheus-example-rules.yaml"
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:

View file

@ -32,8 +32,7 @@ The Prometheus resource includes a field called `serviceMonitorSelector`, which
First, deploy three instances of a simple example application, which listens and exposes metrics on port `8080`.
[embedmd]:# (../../example/user-guides/getting-started/example-app-deployment.yaml)
```yaml
```yaml mdox-exec="cat example/user-guides/getting-started/example-app-deployment.yaml"
apiVersion: apps/v1
kind: Deployment
metadata:
@ -58,8 +57,7 @@ spec:
The ServiceMonitor has a label selector to select Services and their underlying Endpoint objects. The Service object for the example application selects the Pods by the `app` label having the `example-app` value. The Service object also specifies the port on which the metrics are exposed.
[embedmd]:# (../../example/user-guides/getting-started/example-app-service.yaml)
```yaml
```yaml mdox-exec="cat example/user-guides/getting-started/example-app-service.yaml"
kind: Service
apiVersion: v1
metadata:
@ -76,8 +74,7 @@ spec:
This Service object is discovered by a ServiceMonitor, which selects in the same way. The `app` label must have the value `example-app`.
[embedmd]:# (../../example/user-guides/getting-started/example-app-service-monitor.yaml)
```yaml
```yaml mdox-exec="cat example/user-guides/getting-started/example-app-service-monitor.yaml"
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
@ -98,16 +95,14 @@ If [RBAC][rbac-auth] authorization is activated, you must create RBAC rules for
Create a ClusterRole and ClusterRoleBinding for the Prometheus Pods:
[embedmd]:# (../../example/rbac/prometheus/prometheus-service-account.yaml)
```yaml
```yaml mdox-exec="cat example/rbac/prometheus/prometheus-service-account.yaml"
apiVersion: v1
kind: ServiceAccount
metadata:
name: prometheus
```
[embedmd]:# (../../example/rbac/prometheus/prometheus-cluster-role.yaml)
```yaml
```yaml mdox-exec="cat example/rbac/prometheus/prometheus-cluster-role.yaml"
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
@ -134,8 +129,7 @@ rules:
verbs: ["get"]
```
[embedmd]:# (../../example/rbac/prometheus/prometheus-cluster-role-binding.yaml)
```yaml
```yaml mdox-exec="cat example/rbac/prometheus/prometheus-cluster-role-binding.yaml"
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
@ -156,8 +150,7 @@ For more information, see the [Prometheus Operator RBAC guide][prom-rbac].
A Prometheus object defines the `serviceMonitorSelector` to specify which ServiceMonitors should be included. Above the label `team: frontend` was specified, so that's what the Prometheus object selects by.
[embedmd]:# (../../example/user-guides/getting-started/prometheus-service-monitor.yaml)
```yaml
```yaml mdox-exec="cat example/user-guides/getting-started/prometheus-service-monitor.yaml"
apiVersion: monitoring.coreos.com/v1
kind: Prometheus
metadata:
@ -181,8 +174,7 @@ This enables the frontend team to create new ServiceMonitors and Services which
Finally, a Prometheus object defines the `podMonitorSelector` to specify which PodMonitors should be included. Above the label `team: frontend` was specified, so that's what the Prometheus object selects by.
[embedmd]:# (../../example/user-guides/getting-started/prometheus-pod-monitor.yaml)
```yaml
```yaml mdox-exec="cat example/user-guides/getting-started/prometheus-pod-monitor.yaml"
apiVersion: monitoring.coreos.com/v1
kind: Prometheus
metadata:
@ -206,8 +198,7 @@ This enables the frontend team to create new PodMonitors which allow Prometheus
To access the Prometheus instance it must be exposed to the outside. This example exposes the instance using a Service of type `NodePort`.
[embedmd]:# (../../example/user-guides/getting-started/prometheus-service.yaml)
```yaml
```yaml mdox-exec="cat example/user-guides/getting-started/prometheus-service.yaml"
apiVersion: v1
kind: Service
metadata:
@ -238,8 +229,7 @@ This API access is disabled by default and can be toggled using this boolean fla
> user is advised to add additional authentication authorization via a proxy to
> ensure only clients authorized to perform these actions can do so.
[embedmd]:# (../../example/user-guides/getting-started/prometheus-admin-api.yaml)
```yaml
```yaml mdox-exec="cat example/user-guides/getting-started/prometheus-admin-api.yaml"
apiVersion: monitoring.coreos.com/v1
kind: Prometheus
metadata:

View file

@ -190,8 +190,8 @@ Envoy's metrics data model is remarkably similar to that of Prometheus and uses
| Metric Category | Notable Metrics | Description |
| --------------- | --------------- | ----------- |
| envoy_http_downstream_rq | envoy_http_downstream_rq_http1_total <br></br> envoy_http_downstream_rq_http1_total <br></br> envoy_http_downstream_rq_total <br></br> envoy_http_downstream_rq_xx | Statistics regarding traffic from the internet, to each Ambassador instance. Tracking this will give you insight into how each pod is performing for various requests. |
| envoy_cluster_upstream_rq | envoy_cluster_upstream_rq <br></br> envoy_cluster_upstream_rq_xx <br></br> envoy_cluster_upstream_rq_total <br></br> envoy_cluster_upstream_rq_retry | Statistics regarding traffic from Envoy to each upstream service. Tracking this will give you insight to how the request is performing after reaching Ambassador. It will help you pinpoint whether failures are happening in Ambassador or the upstream service. |
| envoy_http_downstream_rq | envoy_http_downstream_rq_http1_total, envoy_http_downstream_rq_http1_total, envoy_http_downstream_rq_total, envoy_http_downstream_rq_xx | Statistics regarding traffic from the internet, to each Ambassador instance. Tracking this will give you insight into how each pod is performing for various requests. |
| envoy_cluster_upstream_rq | envoy_cluster_upstream_rq, envoy_cluster_upstream_rq_xx, envoy_cluster_upstream_rq_total, envoy_cluster_upstream_rq_retry | Statistics regarding traffic from Envoy to each upstream service. Tracking this will give you insight to how the request is performing after reaching Ambassador. It will help you pinpoint whether failures are happening in Ambassador or the upstream service. |
Envoy collects many more statistics including some regarding rate limiting, circuit breaking, and distributed tracing. See the [Envoy's documentation](https://envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/stats) for more information on the metrics envoy collects.

View file

@ -15,8 +15,7 @@ This document assumes a basic understanding of PersistentVolumes, PersistentVolu
Automatic provisioning of storage requires a `StorageClass`.
[embedmd]:# (../../example/storage/storageclass.yaml)
```yaml
```yaml mdox-exec="cat example/storage/storageclass.yaml"
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
@ -32,8 +31,7 @@ For best results, use volumes that have high I/O throughput. These examples use
The `StorageClass` that was created can be specified in the `storage` section in the `Prometheus` resource (note that if you're using [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus), then instead of making the following change to your `Prometheus` resource, see the [prometheus-pvc.jsonnet](https://github.com/prometheus-operator/kube-prometheus/blob/master/examples/prometheus-pvc.jsonnet) example).
[embedmd]:# (../../example/storage/persisted-prometheus.yaml)
```yaml
```yaml mdox-exec="cat example/storage/persisted-prometheus.yaml"
apiVersion: monitoring.coreos.com/v1
kind: Prometheus
metadata:

View file

@ -24,7 +24,6 @@ export PATH := $(TOOLS_BIN_DIR):$(PATH)
PO_DOCGEN_BINARY:=$(TOOLS_BIN_DIR)/po-docgen
CONTROLLER_GEN_BINARY := $(TOOLS_BIN_DIR)/controller-gen
EMBEDMD_BINARY=$(TOOLS_BIN_DIR)/embedmd
JB_BINARY=$(TOOLS_BIN_DIR)/jb
GOJSONTOYAML_BINARY=$(TOOLS_BIN_DIR)/gojsontoyaml
JSONNET_BINARY=$(TOOLS_BIN_DIR)/jsonnet
@ -32,7 +31,8 @@ JSONNETFMT_BINARY=$(TOOLS_BIN_DIR)/jsonnetfmt
SHELLCHECK_BINARY=$(TOOLS_BIN_DIR)/shellcheck
PROMLINTER_BINARY=$(TOOLS_BIN_DIR)/promlinter
GOLANGCILINTER_BINARY=$(TOOLS_BIN_DIR)/golangci-lint
TOOLING=$(PO_DOCGEN_BINARY) $(CONTROLLER_GEN_BINARY) $(EMBEDMD_BINARY) $(GOBINDATA_BINARY) $(JB_BINARY) $(GOJSONTOYAML_BINARY) $(JSONNET_BINARY) $(JSONNETFMT_BINARY) $(SHELLCHECK_BINARY) $(PROMLINTER_BINARY) $(GOLANGCILINTER_BINARY)
MDOX_BINARY=$(TOOLS_BIN_DIR)/mdox
TOOLING=$(PO_DOCGEN_BINARY) $(CONTROLLER_GEN_BINARY) $(GOBINDATA_BINARY) $(JB_BINARY) $(GOJSONTOYAML_BINARY) $(JSONNET_BINARY) $(JSONNETFMT_BINARY) $(SHELLCHECK_BINARY) $(PROMLINTER_BINARY) $(GOLANGCILINTER_BINARY) $(MDOX_BINARY)
K8S_GEN_VERSION:=release-1.14
K8S_GEN_BINARIES:=informer-gen lister-gen client-gen
@ -224,10 +224,6 @@ Documentation/api.md: $(PO_DOCGEN_BINARY) $(TYPES_V1_TARGET) $(TYPES_V1ALPHA1_TA
Documentation/compatibility.md: $(PO_DOCGEN_BINARY) pkg/prometheus/statefulset.go
$(PO_DOCGEN_BINARY) compatibility > $@
$(TO_BE_EXTENDED_DOCS): $(EMBEDMD_BINARY) $(shell find example) bundle.yaml
$(EMBEDMD_BINARY) -w `find Documentation -name "*.md"`
##############
# Formatting #
##############
@ -260,6 +256,19 @@ check-metrics: $(PROMLINTER_BINARY)
check-golang: $(GOLANGCILINTER_BINARY)
$(GOLANGCILINTER_BINARY) run
MDOX_VALIDATE_CONFIG?=.mdox.validate.yaml
MD_FILES_TO_FORMAT=$(filter-out $(FULLY_GENERATED_DOCS), $(shell find Documentation -name "*.md")) $(shell ls *.md)
.PHONY: docs
docs: $(MDOX_BINARY)
@echo ">> formatting and local/remote links"
$(MDOX_BINARY) fmt -l --links.localize.address-regex="https://prometheus-operator.dev/.*" --links.validate.config-file=$(MDOX_VALIDATE_CONFIG) $(MD_FILES_TO_FORMAT)
.PHONY: check-docs
check-docs: $(MDOX_BINARY)
@echo ">> checking formatting and local/remote links"
$(MDOX_BINARY) fmt --check -l --links.localize.address-regex="https://prometheus-operator.dev/.*" --links.validate.config-file=$(MDOX_VALIDATE_CONFIG) $(MD_FILES_TO_FORMAT)
###########
# Testing #
###########

View file

@ -20,4 +20,4 @@ spec:
protocol: TCP
podSelector:
matchLabels:
app: kube-state-metrics
app: kube-state-metrics

View file

@ -20,4 +20,4 @@ spec:
protocol: TCP
podSelector:
matchLabels:
app: node-exporter
app: node-exporter

View file

@ -3,9 +3,8 @@ module github.com/prometheus-operator/prometheus-operator/tooling
go 1.15
require (
github.com/alecthomas/units v0.0.0-20190924025748-f65c72e2690d // indirect
github.com/brancz/gojsontoyaml v0.0.0-20191212081931-bf2969bbd742
github.com/campoy/embedmd v1.0.0
github.com/bwplotka/mdox v0.2.2-0.20210731105602-946757ef5f98
github.com/golangci/golangci-lint v1.40.1
github.com/google/go-jsonnet v0.17.0
github.com/jsonnet-bundler/jsonnet-bundler v0.3.1

File diff suppressed because it is too large Load diff

View file

@ -20,7 +20,7 @@ package tools
import (
_ "github.com/brancz/gojsontoyaml"
_ "github.com/campoy/embedmd"
_ "github.com/bwplotka/mdox"
_ "github.com/golangci/golangci-lint/cmd/golangci-lint"
_ "github.com/google/go-jsonnet/cmd/jsonnet"
_ "github.com/google/go-jsonnet/cmd/jsonnetfmt"