mirrors/kube-prometheus
1
0
Fork 0
mirror of https://github.com/prometheus-operator/kube-prometheus.git synced 2025-10-20 03:31:03 +02:00
Code Issues Projects Releases Wiki Activity

Setup mdox

Browse Source 
Signed-off-by: Saswata Mukherjee <saswataminsta@yahoo.com>
This commit is contained in:
Saswata Mukherjee 2021-10-21 18:58:21 +05:30
parent 0821adabf6
commit 13cfbe3b3d
14 changed files with 1035 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
.github/workflows/ci.yaml vendored
View File

@ -22,6 +22,17 @@ jobs:
with:
go-version: ${{ env.golang-version }}
- run: make --always-make generate validate && git diff --exit-code
check-docs:
runs-on: ubuntu-latest
name: Check Documentation formatting and links
steps:
- uses: actions/checkout@v2
with:
persist-credentials: false
- uses: actions/setup-go@v2
with:
go-version: ${{ env.golang-version }}
- run: make check-docs
lint:
runs-on: ubuntu-latest
name: Jsonnet linter

9
.mdox.validate.yaml Normal file
View File

@ -0,0 +1,9 @@
version: 1
validators:
# Ignore localhost links.
- regex: 'localhost'
type: "ignore"
# Ignore release links.
- regex: 'https:\/\/github\.com\/prometheus-operator\/kube-prometheus\/releases'
type: "ignore"

24
Makefile
View File

@ -2,29 +2,39 @@ SHELL=/bin/bash -o pipefail
BIN_DIR?=$(shell pwd)/tmp/bin
EMBEDMD_BIN=$(BIN_DIR)/embedmd
MDOX_BIN=$(BIN_DIR)/mdox
JB_BIN=$(BIN_DIR)/jb
GOJSONTOYAML_BIN=$(BIN_DIR)/gojsontoyaml
JSONNET_BIN=$(BIN_DIR)/jsonnet
JSONNETLINT_BIN=$(BIN_DIR)/jsonnet-lint
JSONNETFMT_BIN=$(BIN_DIR)/jsonnetfmt
KUBECONFORM_BIN=$(BIN_DIR)/kubeconform
TOOLING=$(EMBEDMD_BIN) $(JB_BIN) $(GOJSONTOYAML_BIN) $(JSONNET_BIN) $(JSONNETLINT_BIN) $(JSONNETFMT_BIN) $(KUBECONFORM_BIN)
TOOLING=$(JB_BIN) $(GOJSONTOYAML_BIN) $(JSONNET_BIN) $(JSONNETLINT_BIN) $(JSONNETFMT_BIN) $(KUBECONFORM_BIN) $(MDOX_BIN)
JSONNETFMT_ARGS=-n 2 --max-blank-lines 2 --string-style s --comment-style s
all: generate fmt test
MDOX_VALIDATE_CONFIG?=.mdox.validate.yaml
MD_FILES_TO_FORMAT=$(shell find docs developer-workspace examples experimental jsonnet manifests -name "*.md") $(shell ls *.md)
all: generate fmt test docs
.PHONY: clean
clean:
# Remove all files and directories ignored by git.
git clean -Xfd .
.PHONY: generate
generate: manifests **.md
.PHONY: docs
docs: $(MDOX_BIN) $(shell find examples) build.sh example.jsonnet
@echo ">> formatting and local/remote links"
$(MDOX_BIN) fmt --soft-wraps -l --links.localize.address-regex="https://prometheus-operator.dev/.*" --links.validate.config-file=$(MDOX_VALIDATE_CONFIG) $(MD_FILES_TO_FORMAT)
**.md: $(EMBEDMD_BIN) $(shell find examples) build.sh example.jsonnet
$(EMBEDMD_BIN) -w `find . -name "*.md" | grep -v vendor`
.PHONY: check-docs
check-docs: $(MDOX_BIN) $(shell find examples) build.sh example.jsonnet
@echo ">> checking formatting and local/remote links"
$(MDOX_BIN) fmt --soft-wraps --check -l --links.localize.address-regex="https://prometheus-operator.dev/.*" --links.validate.config-file=$(MDOX_VALIDATE_CONFIG) $(MD_FILES_TO_FORMAT)
.PHONY: generate
generate: manifests
manifests: examples/kustomize.jsonnet $(GOJSONTOYAML_BIN) vendor
./build.sh $<

48
README.md
View File

@ -173,7 +173,7 @@ Then access via [http://localhost:9093](http://localhost:9093)
## Customizing Kube-Prometheus
This section:
* describes how to customize the kube-prometheus library via compiling the kube-prometheus manifests yourself (as an alternative to the [Quickstart section](#Quickstart)).
* describes how to customize the kube-prometheus library via compiling the kube-prometheus manifests yourself (as an alternative to the [Quickstart section](#quickstart)).
* still doesn't require you to make a copy of this entire repository, but rather only a copy of a few select files.
### Installing
@ -210,8 +210,7 @@ Here's [example.jsonnet](example.jsonnet):
> Note: some of the following components must be configured beforehand. See [configuration](#configuration) and [customization-examples](#customization-examples).
[embedmd]:# (example.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat example.jsonnet"
local kp =
(import 'kube-prometheus/main.libsonnet') +
// Uncomment the following imports to enable its patches
@ -250,8 +249,7 @@ local kp =
And here's the [build.sh](build.sh) script (which uses `vendor/` to render all manifests in a json structure of `{filename: manifest-content}`):
[embedmd]:# (build.sh)
```sh
```sh mdox-exec="cat build.sh"
#!/usr/bin/env bash
# This script uses arg $1 (name of *.jsonnet file to use) to generate the manifests/*.yaml files.
@ -373,8 +371,7 @@ A common example is that not all Kubernetes clusters are created exactly the sam
These mixins are selectable via the `platform` field of kubePrometheus:
[embedmd]:# (examples/jsonnet-snippets/platform.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/jsonnet-snippets/platform.jsonnet"
(import 'kube-prometheus/main.libsonnet') +
{
values+:: {
@ -406,8 +403,7 @@ The output of this command can be piped to a shell to be executed by appending `
Then to generate manifests with `internal-registry.com/organization`, use the `withImageRepository` mixin:
[embedmd]:# (examples/internal-registry.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/internal-registry.jsonnet"
local mixin = import 'kube-prometheus/addons/config-mixins.libsonnet';
local kp = (import 'kube-prometheus/main.libsonnet') + {
values+:: {
@ -430,8 +426,7 @@ local kp = (import 'kube-prometheus/main.libsonnet') + {
Another mixin that may be useful for exploring the stack is to expose the UIs of Prometheus, Alertmanager and Grafana on NodePorts:
[embedmd]:# (examples/jsonnet-snippets/node-ports.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/jsonnet-snippets/node-ports.jsonnet"
(import 'kube-prometheus/main.libsonnet') +
(import 'kube-prometheus/addons/node-ports.libsonnet')
```
@ -440,8 +435,7 @@ Another mixin that may be useful for exploring the stack is to expose the UIs of
To give another customization example, the name of the `Prometheus` object provided by this library can be overridden:
[embedmd]:# (examples/prometheus-name-override.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/prometheus-name-override.jsonnet"
((import 'kube-prometheus/main.libsonnet') + {
prometheus+: {
prometheus+: {
@ -457,8 +451,7 @@ To give another customization example, the name of the `Prometheus` object provi
Standard Kubernetes manifests are all written using [ksonnet-lib](https://github.com/ksonnet/ksonnet-lib/), so they can be modified with the mixins supplied by ksonnet-lib. For example to override the namespace of the node-exporter DaemonSet:
[embedmd]:# (examples/ksonnet-example.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/ksonnet-example.jsonnet"
((import 'kube-prometheus/main.libsonnet') + {
nodeExporter+: {
daemonset+: {
@ -474,8 +467,7 @@ Standard Kubernetes manifests are all written using [ksonnet-lib](https://github
The Alertmanager configuration is located in the `values.alertmanager.config` configuration field. In order to set a custom Alertmanager configuration simply set this field.
[embedmd]:# (examples/alertmanager-config.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/alertmanager-config.jsonnet"
((import 'kube-prometheus/main.libsonnet') + {
values+:: {
alertmanager+: {
@ -502,8 +494,7 @@ The Alertmanager configuration is located in the `values.alertmanager.config` co
In the above example the configuration has been inlined, but can just as well be an external file imported in jsonnet via the `importstr` function.
[embedmd]:# (examples/alertmanager-config-external.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/alertmanager-config-external.jsonnet"
((import 'kube-prometheus/main.libsonnet') + {
values+:: {
alertmanager+: {
@ -517,8 +508,7 @@ In the above example the configuration has been inlined, but can just as well be
In order to monitor additional namespaces, the Prometheus server requires the appropriate `Role` and `RoleBinding` to be able to discover targets from that namespace. By default the Prometheus server is limited to the three namespaces it requires: default, kube-system and the namespace you configure the stack to run in via `$.values.namespace`. This is specified in `$.values.prometheus.namespaces`, to add new namespaces to monitor, simply append the additional namespaces:
[embedmd]:# (examples/additional-namespaces.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/additional-namespaces.jsonnet"
local kp = (import 'kube-prometheus/main.libsonnet') + {
values+:: {
common+: {
@ -548,8 +538,7 @@ In order to Prometheus be able to discovery and scrape services inside the addit
You can define ServiceMonitor resources in your `jsonnet` spec. See the snippet bellow:
[embedmd]:# (examples/additional-namespaces-servicemonitor.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/additional-namespaces-servicemonitor.jsonnet"
local kp = (import 'kube-prometheus/main.libsonnet') + {
values+:: {
common+: {
@ -601,8 +590,7 @@ local kp = (import 'kube-prometheus/main.libsonnet') + {
In case you want to monitor all namespaces in a cluster, you can add the following mixin. Also, make sure to empty the namespaces defined in prometheus so that roleBindings are not created against them.
[embedmd]:# (examples/all-namespaces.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/all-namespaces.jsonnet"
local kp = (import 'kube-prometheus/main.libsonnet') +
(import 'kube-prometheus/addons/all-namespaces.libsonnet') + {
values+:: {
@ -630,7 +618,7 @@ Proceed with [creating ServiceMonitors for the services in the namespaces](#defi
### Static etcd configuration
In order to configure a static etcd cluster to scrape there is a simple [kube-prometheus-static-etcd.libsonnet](jsonnet/kube-prometheus/kube-prometheus-static-etcd.libsonnet) mixin prepared - see [etcd.jsonnet](examples/etcd.jsonnet) for an example of how to use that mixin, and [Monitoring external etcd](docs/monitoring-external-etcd.md) for more information.
In order to configure a static etcd cluster to scrape there is a simple [static-etcd.libsonnet](jsonnet/kube-prometheus/addons/static-etcd.libsonnet) mixin prepared - see [etcd.jsonnet](examples/etcd.jsonnet) for an example of how to use that mixin, and [Monitoring external etcd](docs/monitoring-external-etcd.md) for more information.
> Note that monitoring etcd in minikube is currently not possible because of how etcd is setup. (minikube's etcd binds to 127.0.0.1:2379 only, and within host networking namespace.)
@ -639,8 +627,7 @@ In order to configure a static etcd cluster to scrape there is a simple [kube-pr
To prevent `Prometheus` and `Alertmanager` instances from being deployed onto the same node when
possible, one can include the [kube-prometheus-anti-affinity.libsonnet](jsonnet/kube-prometheus/addons/anti-affinity.libsonnet) mixin:
[embedmd]:# (examples/anti-affinity.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/anti-affinity.jsonnet"
local kp = (import 'kube-prometheus/main.libsonnet') +
(import 'kube-prometheus/addons/anti-affinity.libsonnet') + {
values+:: {
@ -664,8 +651,7 @@ local kp = (import 'kube-prometheus/main.libsonnet') +
Sometimes in small clusters, the CPU/memory limits can get high enough for alerts to be fired continuously. To prevent this, one can strip off the predefined limits.
To do that, one can import the following mixin
[embedmd]:# (examples/strip-limits.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/strip-limits.jsonnet"
local kp = (import 'kube-prometheus/main.libsonnet') +
(import 'kube-prometheus/addons/strip-limits.libsonnet') + {
values+:: {
@ -759,7 +745,7 @@ resources. One driver for more resource needs, is a high number of
namespaces. There may be others.
kube-state-metrics resource allocation is managed by
[addon-resizer](https://github.com/kubernetes/autoscaler/tree/main/addon-resizer/nanny)
[addon-resizer](https://github.com/kubernetes/autoscaler/tree/master/addon-resizer/nanny)
You can control it's parameters by setting variables in the
config. They default to:

2
developer-workspace/README.md
View File

@ -26,7 +26,7 @@ If you are working on new features/bug fixes, you can regenerate kube-prometheus
Gitpod is already available to everyone to use for free. It can also run commands that we speficy in the `.gitpod.yml` file located in the root directory of the git repository, so even the cluster creation can be fully automated.
You can use the same workflow as mentioned in the [Codespaces](#Codespaces) section, however Gitpod doesn't have native support for any kubernetes distribution. The workaround is to create a full QEMU Virtual Machine and deploy [k3s](https://github.com/k3s-io/k3s) inside this VM. Don't worry, this whole process is already fully automated, but due to the workaround the whole workspace may be very slow.
You can use the same workflow as mentioned in the [Codespaces](#codespaces) section, however Gitpod doesn't have native support for any kubernetes distribution. The workaround is to create a full QEMU Virtual Machine and deploy [k3s](https://github.com/k3s-io/k3s) inside this VM. Don't worry, this whole process is already fully automated, but due to the workaround the whole workspace may be very slow.
To open up a workspace with Gitpod, you can install the [Google Chrome extension](https://www.gitpod.io/docs/browser-extension/) to add a new button to Github UI and use it on PRs or from the main page. Or by directly typing in the browser `http://gitpod.io/#https://github.com/prometheus-operator/kube-prometheus/pull/<Pull Request Number>` or just `http://gitpod.io/#https://github.com/prometheus-operator/kube-prometheus`

4
docs/EKS-cni-support.md
View File

@ -5,8 +5,8 @@ AWS EKS uses [CNI](https://github.com/aws/amazon-vpc-cni-k8s) networking plugin
One fatal issue that can occur is that you run out of IP addresses in your eks cluster. (Generally happens due to error configs where pods keep scheduling).
You can monitor the `awscni` using kube-promethus with :
[embedmd]:# (../examples/eks-cni-example.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/eks-cni-example.jsonnet"
local kp = (import 'kube-prometheus/main.libsonnet') + {
values+:: {
common+: {

25
docs/developing-prometheus-rules-and-grafana-dashboards.md
View File

@ -20,8 +20,7 @@ For both the Prometheus rules and the Grafana dashboards Kubernetes `ConfigMap`s
As a basis, all examples in this guide are based on the base example of the kube-prometheus [readme](../README.md):
[embedmd]:# (../example.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat example.jsonnet"
local kp =
(import 'kube-prometheus/main.libsonnet') +
// Uncomment the following imports to enable its patches
@ -68,8 +67,7 @@ The format is exactly the Prometheus format, so there should be no changes neces
> Note that alerts can just as well be included into this file, using the jsonnet `import` function. In this example it is just inlined in order to demonstrate their use in a single file.
[embedmd]:# (../examples/prometheus-additional-alert-rule-example.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/prometheus-additional-alert-rule-example.jsonnet"
local kp = (import 'kube-prometheus/main.libsonnet') + {
values+:: {
common+: {
@ -124,8 +122,7 @@ In order to add a recording rule, simply do the same with the `prometheusRules`
> Note that rules can just as well be included into this file, using the jsonnet `import` function. In this example it is just inlined in order to demonstrate their use in a single file.
[embedmd]:# (../examples/prometheus-additional-recording-rule-example.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/prometheus-additional-recording-rule-example.jsonnet"
local kp = (import 'kube-prometheus/main.libsonnet') + {
values+:: {
common+: {
@ -184,8 +181,7 @@ cat existingrule.yaml | gojsontoyaml -yamltojson > existingrule.json
Then import it in jsonnet:
[embedmd]:# (../examples/prometheus-additional-rendered-rule-example.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/prometheus-additional-rendered-rule-example.jsonnet"
local kp = (import 'kube-prometheus/main.libsonnet') + {
values+:: {
common+: {
@ -337,8 +333,7 @@ We recommend using the [grafonnet](https://github.com/grafana/grafonnet-lib/) li
> Note that dashboards can just as well be included into this file, using the jsonnet `import` function. In this example it is just inlined in order to demonstrate their use in a single file.
[embedmd]:# (../examples/grafana-additional-jsonnet-dashboard-example.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/grafana-additional-jsonnet-dashboard-example.jsonnet"
local grafana = import 'grafonnet/grafana.libsonnet';
local dashboard = grafana.dashboard;
local row = grafana.row;
@ -394,8 +389,7 @@ local kp = (import 'kube-prometheus/main.libsonnet') + {
As jsonnet is a superset of json, the jsonnet `import` function can be used to include Grafana dashboard json blobs. In this example we are importing a [provided example dashboard](../examples/example-grafana-dashboard.json).
[embedmd]:# (../examples/grafana-additional-rendered-dashboard-example.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/grafana-additional-rendered-dashboard-example.jsonnet"
local kp = (import 'kube-prometheus/main.libsonnet') + {
values+:: {
common+:: {
@ -419,8 +413,8 @@ local kp = (import 'kube-prometheus/main.libsonnet') + {
```
In case you have lots of json dashboard exported out from grafana UI the above approach is going to take lots of time to improve performance we can use `rawDashboards` field and provide it's value as json string by using `importstr`
[embedmd]:# (../examples/grafana-additional-rendered-dashboard-example-2.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/grafana-additional-rendered-dashboard-example-2.jsonnet"
local kp = (import 'kube-prometheus/main.libsonnet') + {
values+:: {
common+:: {
@ -523,8 +517,7 @@ values+:: {
Full example of including etcd mixin using method described above:
[embedmd]:# (../examples/mixin-inclusion.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/mixin-inclusion.jsonnet"
local addMixin = (import 'kube-prometheus/lib/mixin.libsonnet');
local etcdMixin = addMixin({
name: 'etcd',

2
docs/exposing-prometheus-alertmanager-grafana-ingress.md
View File

@ -104,7 +104,7 @@ k.core.v1.list.new([
In order to expose Alertmanager and Grafana, simply create additional fields containing an ingress object, but simply pointing at the `alertmanager` or `grafana` instead of the `prometheus-k8s` Service. Make sure to also use the correct port respectively, for Alertmanager it is also `web`, for Grafana it is `http`. Be sure to also specify the appropriate external URL. Note that the external URL for grafana is set in a different way than the external URL for Prometheus or Alertmanager. See [ingress.jsonnet](../examples/ingress.jsonnet) for how to set the Grafana external URL.
In order to render the ingress objects similar to the other objects use as demonstrated in the [main readme](../README.md#usage):
In order to render the ingress objects similar to the other objects use as demonstrated in the [main readme](../README.md):
```
{ ['00namespace-' + name]: kp.kubePrometheus[name] for name in std.objectFields(kp.kubePrometheus) } +

2
docs/monitoring-external-etcd.md
View File

@ -15,7 +15,7 @@ toc: true
When the etcd cluster is not hosted inside Kubernetes.
This is often the case with Kubernetes setups. This approach has been tested with kube-aws but the same principals apply to other tools.
Note that [etcd.jsonnet](../examples/etcd.jsonnet) & [kube-prometheus-static-etcd.libsonnet](../jsonnet/kube-prometheus/kube-prometheus-static-etcd.libsonnet) (which are described by a section of the [Readme](../README.md#static-etcd-configuration)) do the following:
Note that [etcd.jsonnet](../examples/etcd.jsonnet) & [static-etcd.libsonnet](../jsonnet/kube-prometheus/addons/static-etcd.libsonnet) (which are described by a section of the [Readme](../README.md#static-etcd-configuration)) do the following:
* Put the three etcd TLS client files (CA & cert & key) into a secret in the namespace, and have Prometheus Operator load the secret.
* Create the following (to expose etcd metrics - port 2379): a Service, Endpoint, & ServiceMonitor.

3
docs/weave-net-support.md
View File

@ -15,8 +15,7 @@ Using kube-prometheus and kubectl you will be able install the following for mon
## Instructions
- You can monitor Weave Net using an example like below. **Please note that some alert configurations are environment specific and may require modifications of alert thresholds**. For example: The FastDP flows have never gone below 15000 for us. But if this value is say 20000 for you then you can use an example like below to update the alert. The alerts which may require threshold modifications are `WeaveNetFastDPFlowsLow` and `WeaveNetIPAMUnreachable`.
[embedmd]:# (../examples/weave-net-example.jsonnet)
```jsonnet
```jsonnet mdox-exec="cat examples/weave-net-example.jsonnet"
local kp = (import 'kube-prometheus/main.libsonnet') +
(import 'kube-prometheus/addons/weave-net/weave-net.libsonnet') + {
values+:: {

2
jsonnet/kube-prometheus/platforms/README.md
View File

@ -1,3 +1,3 @@
# Adding a new platform specific configuration
Adding a new platform specific configuration requires to update the [README](../../../README.md#cluster-creation-tools) and the [platforms.jsonnet](./platform.jsonnet) file by adding the platform to the list of existing ones. This allow the new platform to be discoverable and easily configurable by the users.
Adding a new platform specific configuration requires to update the [README](../../../README.md#cluster-creation-tools) and the [platforms.libsonnet](./platforms.libsonnet) file by adding the platform to the list of existing ones. This allow the new platform to be discoverable and easily configurable by the users.

2
scripts/go.mod
View File

@ -4,7 +4,7 @@ go 1.15
require (
github.com/brancz/gojsontoyaml v0.0.0-20200602132005-3697ded27e8c
github.com/campoy/embedmd v1.0.0
github.com/bwplotka/mdox v0.9.0
github.com/google/go-jsonnet v0.17.1-0.20210909114553-2f2f6d664f06 // commit on SEP 9th 2021. Needed by jsonnet linter
github.com/jsonnet-bundler/jsonnet-bundler v0.4.0
github.com/yannh/kubeconform v0.4.7

968
scripts/go.sum
View File

File diff suppressed because it is too large Load Diff

4
scripts/tools.go
View File

@ -6,10 +6,10 @@ package tools
import (
_ "github.com/brancz/gojsontoyaml"
_ "github.com/campoy/embedmd"
_ "github.com/bwplotka/mdox"
_ "github.com/google/go-jsonnet/cmd/jsonnet"
_ "github.com/google/go-jsonnet/cmd/jsonnet-lint"
_ "github.com/google/go-jsonnet/cmd/jsonnetfmt"
_ "github.com/yannh/kubeconform/cmd/kubeconform"
_ "github.com/jsonnet-bundler/jsonnet-bundler/cmd/jb"
_ "github.com/yannh/kubeconform/cmd/kubeconform"
)