diff --git a/Documentation/installation.md b/Documentation/installation.md new file mode 100644 index 000000000..606ba2c62 --- /dev/null +++ b/Documentation/installation.md @@ -0,0 +1,99 @@ +--- +weight: 102 +toc: true +title: Installing Prometheus Operator +menu: + docs: + parent: getting-started +images: [] +draft: false +description: Installation guide listing all the installation methods of Prometheus Operator. +date: "2020-11-16T13:59:39+01:00" +--- + +There are different approaches to install Prometheus Operator in your Kubernetes cluster: + +- [Install using YAML files](#install-using-yaml-files) +- [Install using Kube-Prometheus](#install-using-kube-prometheus) +- [Install using Helm Chart](#install-using-helm-chart) + +### Pre-requisites + +For all the approaches listed on this page, you require access to a **Kubernetes cluster!** For this, you can check the official docs of Kubernetes available [here](https://kubernetes.io/docs/tasks/tools/). + +Version `>=0.39.0` of the Prometheus Operator requires a Kubernetes cluster of version `>=1.16.0`. If you are just starting out with the Prometheus Operator, it is **highly recommended** to use the latest version. If you have an older version of Kubernetes and the Prometheus Operator running, we recommend upgrading Kubernetes first and then the Prometheus Operator. + +> Check the appropriate versions of each of the components in the [Compatibility]({{<ref "compatibility">}}) page. + +### Install using YAML files + +The first step is to install the operator's Custom Resource Definitions (CRDs) as well as the operator itself with the required RBAC resources. + +Run the following commands to install the CRDs and deploy the operator in the `default` namespace: + +```bash +LATEST=$(curl -s https://api.github.com/repos/prometheus-operator/prometheus-operator/releases/latest | jq -cr .tag_name) +curl -sL https://github.com/prometheus-operator/prometheus-operator/releases/download/${LATEST}/bundle.yaml | kubectl create -f - +``` + +It can take a few minutes for the operator to be up and running. You can check for completion with the following command: + +```bash +kubectl wait --for=condition=Ready pods -l app.kubernetes.io/name=prometheus-operator -n default +``` + +### Install using Kube-Prometheus + +The easiest way of starting with the Prometheus Operator is by deploying it as part of kube-prometheus. kube-prometheus deploys the Prometheus Operator and already schedules a Prometheus called `prometheus-k8s` with alerts and rules by default. + +We are going to deploy a compiled version of the Kubernetes [manifests](https://github.com/prometheus-operator/kube-prometheus/tree/main/manifests). + +You can either clone the kube-prometheus from GitHub: + +```shell +git clone https://github.com/prometheus-operator/kube-prometheus.git +``` + +or download the current main branch as zip file and extract its contents: + +[github.com/prometheus-operator/kube-prometheus/archive/main.zip](https://github.com/prometheus-operator/kube-prometheus/archive/main.zip) + +Once you have the files on your machine change into the project's root directory and run the following commands: + +```shell +# Create the namespace and CRDs, and then wait for them to be available before creating the remaining resources +kubectl create -f manifests/setup + +# Wait until the "servicemonitors" CRD is created. The message "No resources found" means success in this context. +until kubectl get servicemonitors --all-namespaces ; do date; sleep 1; echo ""; done + +kubectl create -f manifests/ +``` + +We create the namespace and CustomResourceDefinitions first to avoid race conditions when deploying the monitoring components. Alternatively, the resources in both folders can be applied with a single command: + +``` +kubectl create -f manifests/setup -f manifests +``` + +But it may be necessary to run the command multiple times for all components to be created successfully. + +> Note: For versions before Kubernetes v1.20.z refer to the [Kubernetes compatibility matrix](https://github.com/prometheus-operator/kube-prometheus#kubernetes-compatibility-matrix) in order to choose a compatible branch. + +> Note: If you used Kube-Prometheus as the installation method, we would recommend you to follow this [page](http://prometheus-operator.dev/kube-prometheus/kube/access-ui/) to learn how to access the resources provided. + +### Remove Kube-Prometheus + +If you're done experimenting with kube-prometheus and the Prometheus Operator you can simply teardown the deployment by running: + +```shell +kubectl delete --ignore-not-found=true -f manifests/ -f manifests/setup +``` + +### Install Using Helm Chart + +Install the [Kube-Prometheus-Stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack) helm chart which provides a collection of Kubernetes manifests, [Grafana](https://grafana.com/) dashboards, and [Prometheus rules](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/) combined with documentation and scripts to provide easy to operate end-to-end Kubernetes cluster monitoring with [Prometheus](https://prometheus.io/) using the Prometheus Operator. + +To see more details, please check the [chart's README](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack#kube-prometheus-stack). + +> This helm chart is no longer part of Prometheus-Operator and is now maintained by [Prometheus Community Helm Charts](https://github.com/prometheus-community/helm-charts). diff --git a/Documentation/introduction.md b/Documentation/introduction.md new file mode 100644 index 000000000..dc5a09dc6 --- /dev/null +++ b/Documentation/introduction.md @@ -0,0 +1,80 @@ +--- +weight: 101 +toc: true +title: Introduction +menu: + docs: + parent: getting-started +lead: "" +lastmod: "2020-10-06T08:48:57+00:00" +images: [] +draft: false +description: The Prometheus Operator provides Kubernetes native deployment and management of Prometheus and related monitoring components +date: "2020-10-06T08:48:57+00:00" +--- + +Prometheus Operator is a [Kubernetes Operator](https://github.com/cncf/tag-app-delivery/blob/main/operator-wg/whitepaper/Operator-WhitePaper_v1-0.md#foundation) that provides Kubernetes native deployment and management of [Prometheus](https://prometheus.io/) and related monitoring components. + +The Prometheus operator includes, but is not limited to, the following features: + +- **Kubernetes Custom Resources**: Use Kubernetes custom resources to deploy and manage Prometheus, Alertmanager, and related components. + +- **Simplified Deployment Configuration**: Configure the fundamentals of Prometheus like versions, persistence, retention policies, and replicas from a native Kubernetes resource. + +- **Prometheus Target Configuration**: Automatically generate monitoring target configurations based on familiar Kubernetes label queries; no need to learn a Prometheus specific configuration language. + +Prometheus Operator provides a set of Custom Resource Definitions(CRDs) that allows you to configure your Prometheus and related instances. Currently, the CRDs provided by Prometheus Operator are: + +- Prometheus +- Alertmanager +- ThanosRuler +- ServiceMonitor +- PodMonitor +- Probe +- PrometheusRule +- AlertmanagerConfig +- PrometheusAgent +- ScrapeConfig + +> Check the [Design]({{<ref "design">}}) page for an overview of all the resources provided by Prometheus Operator. + +### Goals + +- To significantly reduce the effort required to configure, implement and manage all components of Prometheus based monitoring stack. + +- **Automation** - Automate the management of Prometheus monitoring targets, ultimately increasing efficiency. This automation is performed by the use of Kubernetes [Custom Resource Definition](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/). The Operator introduces custom resources like `Prometheus`, `Alertmanager`, `ThanosRuler`, and others, which help automate the deployment and configuration of these resources. + +- **Configuration Abstraction and Validation** - Instead of learning and manually writing Prometheus Relabeling rules (which can be time consuming), you can simply use Kubernetes [Label Selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors). `ServiceMonitor`, `PodMonitor` and `Probe` custom resources provide this abstraction. The Operator also removes the complexity of validating the configuration of `AlertmanagerConfig` and `PrometheusRule` objects. + +- **Scaling** - There are many scaling-related features provided by the Operator like [ThanosRuler](https://prometheus-operator.dev/docs/platform/thanos/#thanos-ruler) custom resource for rule evaluation, workload distribution across multiple Prometheus instances using scrape target sharding, and running [Thanos sidecar](https://thanos.io/v0.4/components/sidecar/) in Prometheus instance for long-term storage. + +### Next Steps + +By now, you have the basic idea about Prometheus Operator!! + +Take a look at these guides to get into action with Prometheus Operator. + +<!-- Getting-Started --> + +{{< +link-card title="Getting-Started" href="https://prometheus-operator.dev/docs/getting-started/introduction/" description="Get started with Prometheus-Operator.">}} + +<!-- API --> + +{{< +link-card title="API Reference" href="https://prometheus-operator.dev/docs/api-reference/api/" description="Reference for different fields of Custom Resources in Prometheus-Operator.">}} + +<!-- Platform Guide --> + +{{< +link-card title="Platform Guide" href="https://prometheus-operator.dev/docs/platform/webhook/" description="Set up, configure and manage instances of Prometheus-Operator, Prometheus, Alertmanager and ThanosRuler resources.">}} + +<!-- Developer Guide --> + +{{< +link-card title="Developer Guide" href="https://prometheus-operator.dev/docs/developer/getting-started/" description="Learn how to configure scraping, alerting, and recording rules for your applications.">}} + +<!-- Community --> + +{{< +link-card title="Community" href="https://prometheus-operator.dev/docs/community/contributing/" description="Join and interact with Prometheus-Operator community.">}}