From 21c6ee5ed2693074b8290b97327821d05e036cc9 Mon Sep 17 00:00:00 2001 From: Martin Hirschvogel Date: Thu, 7 Sep 2023 13:37:53 +0200 Subject: [PATCH] Readmes updated to direct to single source of truth: docs.checkmk.com Change-Id: Ie8d10cdfe559a3be69bd795588a232686f6d83fe --- README.rst | 26 +++-- deploy/charts/checkmk/README.md | 180 ------------------------------- deploy/charts/checkmk/README.rst | 26 +++++ deploy/kubernetes/README.rst | 137 ++--------------------- 4 files changed, 49 insertions(+), 320 deletions(-) delete mode 100644 deploy/charts/checkmk/README.md create mode 100644 deploy/charts/checkmk/README.rst diff --git a/README.rst b/README.rst index 13f2fb2..5ca64ca 100644 --- a/README.rst +++ b/README.rst @@ -9,6 +9,20 @@ Checkmk cluster and node collectors to monitor Kubernetes clusters. * Free software: GNU General Public License v2 +Installation +-------- + +You can use our `helm repository`_ to install the collectors from our latest release. +Detailed instructions can be found in our `official docs`_. + + +Support policy +-------- + +Please read our `official docs`_ for information regarding supported Kubernetes versions +and supported Kubernetes distros. + + Features -------- @@ -29,16 +43,6 @@ Features * can be configured to run the API in *http* or *https* mode * Supports PodSecurityPolicy (up to Kubernetes 1.24) and NetworkPolicy -Installation ------------- -Please use the Helm charts provided in ``deploy/charts/checkmk`` or the manifests in ``deploy/kubernetes``. You will find detailed installation instructions there. - -You can also use our `helm repository`_ to install the collectors from our latest release. - -Feedback --------- -If you've got any feedback you'd like to share or are experiencing any issues, please let us know via feedback@checkmk.com or by creating a support ticket. - - .. _cAdvisor: https://github.com/google/cadvisor .. _helm repository: https://checkmk.github.io/checkmk_kube_agent/ +.. _official docs: https://docs.checkmk.com/latest/en/monitoring_kubernetes.html \ No newline at end of file diff --git a/deploy/charts/checkmk/README.md b/deploy/charts/checkmk/README.md deleted file mode 100644 index a2f864f..0000000 --- a/deploy/charts/checkmk/README.md +++ /dev/null @@ -1,180 +0,0 @@ -# checkmk - -Installs the checkmk Kubernetes agent. - -_Note: This chart is relatively young. Please use with care, read the documentation carefully, and file Pull Requests if required._ - -## Prerequisites - -- Kubernetes 1.21+ -- Helm 3+ - -## Tutorials -Watch our tutorials to help you get started with our Kubernetes monitoring! -* [How to set up Checkmk monitoring for Kubernetes clusters](https://www.youtube.com/watch?v=H9AlO98afUE) -* [How to detect issues on Kubernetes clusters](https://www.youtube.com/watch?v=2H-cLhyfYbc) - -## Add repository -```console -helm repo add [REPO] https://checkmk.github.io/checkmk_kube_agent -helm repo update -``` -Use any name for `REPO`, e.g. checkmk. -_See [helm repo](https://helm.sh/docs/helm/helm_repo/) for command documentation._ - -## Install or upgrade chart - -```console -helm upgrade --install --create-namespace -n [RELEASE_NAMESPACE] [RELEASE_NAME] [REPO]/checkmk [-f values.yaml] -``` - -The flag `--create-namespace` will create the specified namespace `RELEASE_NAMESPACE` if it does not yet exists. - -Freely set `RELEASE_NAME`. Using the name of the chart, in this case *checkmk*, will result in short names of your Kubernetes objects. - -Use the same name for `REPO` as in the previous step. - -Optionally, you can pass `-f values.yaml` to overwrite default values of the chart specified in your custom `values.yaml` file. - -_See [configuration](#configuration) below._ - -_See [helm install](https://helm.sh/docs/helm/helm_install/) for command documentation._ - -## Uninstall chart - -```console -helm uninstall -n [RELEASE_NAMESPACE] [RELEASE_NAME] -``` - -This removes all the Kubernetes components associated with the chart and deletes the release. - -_See [helm uninstall](https://helm.sh/docs/helm/helm_uninstall/) for command documentation._ - -## Preview Helm changes - -The [helm-diff](https://github.com/databus23/helm-diff) plugin gives us the possibility to preview what a `helm upgrade` would change. - -Install it via `helm plugin install https://github.com/databus23/helm-diff`, then you can run the following prior to an install or upgrade command: - -```console -# Helm (requires helm-diff plugin) -helm diff upgrade --install -n [RELEASE_NAMESPACE] [RELEASE_NAME] [-f values.yaml] [REPO]/checkmk -``` - -## Render Helm templates - -To render plain Kubernetes manifests from the Helm chart, run: - -```console -helm template -n [RELEASE_NAMESPACE] [RELEASE_NAME] [REPO]/checkmk -``` - -## Configuration - -See [Customizing the Chart Before Installing](https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing). To see all configurable options with detailed comments: - -```console -helm show values [REPO]/checkmk -``` - -To configure the installation, you can specify additional helm value files via `-f [MY_CUSTOM_VALUES_FILE]`. - -We recommend using the `values.yaml` provided in this repository. - -### Configure the Checkmk Kubernetes Collectors -By default, the *Checkmk Cluster Collector service* is not exposed and communicates using HTTP. Depending on your requirements, either expose the *Checkmk Cluster Collector service* via NodePort or Ingress. - -For communication via NodePort: -- Set *clusterCollector.service.type: NodePort* -- Uncomment *clusterCollector.service.nodePort* - -For communication via Ingress: Adapt the configuration in *clusterCollector.ingress* as needed. - -#### Image tags -You can find possible tags here: https://hub.docker.com/r/checkmk/kubernetes-collector/tags - -#### Secure commmunication - -Secure communications to and between the *Checkmk Kubernetes Collectors* can be achieved in various ways. -You can use Kubernetes native methods, e.g. a properly configured Ingress for external communication and a -ServiceMesh for internal communication. This has to be done by you / your cluster administrator. - -Alternatively, you can use the mechanisms provided by *Checkmk Kubernetes Collectors* to secure both the communication from outside -to the *Cluster Collector* API as well as the communication between the *Node Collectors* and the *Cluster Collector*. - -1. Set *tlsCommunication.enabled: true* and *tlsCommunication.verifySsl: true* -2. Add certificates in *tlsCommunication* - - For *clusterCollectorKey* and *clusterCollectorCert*: Add certificates with the service (`[cluster-collector-service].[collector-namespace]`) as FQDN following and the hostname/ingress as AltName - - Add the respective CA certificate to *checkmkCaCert* and add that in Checkmk as well (Trusted certificate authorities for SSL) - -### Multiple releases - -The same chart can be used to run multiple checkmk instances in the same cluster (or even the same namespace) if required. To achieve this, just rename the `RELEASE_NAME` when installing. - -### Configure Checkmk - -#### Prerequisites - -* The URL of the Kubernetes API server -* The token of Checkmk service account. Use the command provided by helm after succesful deployment. Alternatively adapt this one. - ```console - kubectl get secret $(kubectl get serviceaccount [SERVICEACCOUNT] -o=jsonpath='{.secrets[*].name}' -n [NAMESPACE]) -n [NAMESPACE] -o=jsonpath='{.data.token}' | base64 --decode - ``` -* The certificate of the Checkmk service account. Use the command provided by helm after succesful deployment. Alternatively adapt this one. - ```console - kubectl get secret $(kubectl get serviceaccount [SERVICEACCOUNT] -o=jsonpath='{.secrets[*].name}' -n [NAMESPACE]) -n [NAMESPACE] -o=jsonpath='{.data.ca\.crt}' | base64 --decode - ``` -* The *Checkmk Kubernetes Collectors* deployed and the URL under which the *Cluster Collector* is reachable -* Recommended: Secure communication to the *Cluster Collector* (see details in *Additional topics*) - -#### Preparing your Checkmk - -1. Create a piggyback source host with *IP address family* set to *No IP* (this host will contain cluster-level services and metrics) -2. Create a folder, which will later contain all Kubernetes objects -3. Configure the dynamic host management: *Setup → Hosts (Dynamic host management) → Add connection* -4. Enter *Title* and click *show more* for *Connection Properties* - - *Connection Properties → Piggyback creation options → Add new element* - - In *Create hosts in*: select the folder you just created - - Select *Automatically delete hosts without piggyback data* - - Under *Restrict source hosts*: enter the name of your piggyback source host(s) - - Tick *Service discovery → Discover services during creation* -5. Optional: add the certificate of the Checkmk service account (depends on your cluster / set-up) - - *Setup → Global Settings → Trusted certificate authorities for SSL → Add new CA certificate or chain* -6. Optional: add the token of the Checkmk service account to the password store - - *Setup → General → Passwords → Add pasword* - -#### Setting up the connection - -1. Set up the Kubernetes 2.0 ruleset: *Setup → Agents (VM, Cloud, Container) → Kubernetes → Add rule* -2. Name your cluster (will be included in the object names) -3. Add the token of the Checkmk service account to be able to retrieve data. We recommend using the password store for this. -4. Configure the *API server connection endpoint*: enter the URL (and port), where your API server is located - - You can set *SSL certficate verification* to *Verify the certificate*, if you added the certificate as mentioned in the previous section -5. Configure the *Collector NodePort / Ingress endpoint* - - NodePort: URL of a node + port (default: 30035) - - If you set-up communication via HTTPS for the cluster collector (see section below), you can set *SSL certficate verification* to *Verify the certificate* -6. You can exclude namespaces or limit your monitoring to a few namespaces. Cluster-wide components, e.g. nodes, will still be retrieved though -7. Under *Explicit host* in *Conditions* add the name of piggyback source host. -8. Activate changes. You are done. - -## Debug - -To debug in-cluster, you can launch a debug pod with network tools via - -```console -kubectl -n [RELEASE_NAMESPACE] run -it debug --rm --image wbitt/network-multitool --restart=Never -- sh -``` - -and, with the token of the service account names `[RELEASE_NAME]-checkmk`, issue queries against the `cluster-collector`: - -```console -# non-TLS -curl -H "Authorization: Bearer " -cluster-collector..svc:8080/metadata | jq - -# TLS -curl -k -H "Authorization: Bearer " https://-cluster-collector..svc:8080/metadata | jq -``` - -As endpoints, instead of `/metadata`, feel free to also test `/container_metrics`, `/machine_sections`, etc. - -Note that this will only work when disabling or adjusting the NetworkPolicies accordingly, as the `debug` pod won't be allowed to communicate with the cluster-collector having NetworkPolicies enabled in this chart. diff --git a/deploy/charts/checkmk/README.rst b/deploy/charts/checkmk/README.rst new file mode 100644 index 0000000..7b1740f --- /dev/null +++ b/deploy/charts/checkmk/README.rst @@ -0,0 +1,26 @@ +Checkmk Kubernetes Cluster and Node Collectors +============================================== + +Installs the collectors required for Kubernetes monitoring with Checkmk. + +Installation +-------- + +You can use our `helm repository`_ to install the collectors from our latest release. +Detailed instructions can be found in our `official docs`_. + +Watch our tutorials to help you get started with our Kubernetes monitoring! + +- `How to set up Checkmk monitoring for Kubernetes clusters`_ +- `How to detect issues on Kubernetes clusters`_ + +Support policy +-------- + +Please read our `official docs`_ for information regarding supported Kubernetes versions +and supported Kubernetes distros. + +.. _helm repository: https://checkmk.github.io/checkmk_kube_agent/ +.. _official docs: https://docs.checkmk.com/latest/en/monitoring_kubernetes.html +.. _How to set up Checkmk monitoring for Kubernetes clusters: https://www.youtube.com/watch?v=H9AlO98afUE +.. _How to detect issues on Kubernetes clusters: https://www.youtube.com/watch?v=2H-cLhyfYbc \ No newline at end of file diff --git a/deploy/kubernetes/README.rst b/deploy/kubernetes/README.rst index 3416966..32fc04a 100644 --- a/deploy/kubernetes/README.rst +++ b/deploy/kubernetes/README.rst @@ -5,137 +5,16 @@ Checkmk Kubernetes Cluster and Node Collectors You can deploy the Checkmk Kubernetes Cluster and Node Collectors using the manifests here. Note: We recommend using Helm charts as they are less error-prone. We do not provide support for installation via manifests. -Short installation guide ------------------------- +Installation +-------- -#. Download ``00_namespace.yaml``, ``checkmk-serviceaccount.yaml``, ``cluster-collector.yaml``, ``node-collector.yaml``, ``service.yaml`` +Detailed instructions can be found in our `official docs`_. -#. Optional: Download ``network-policy.yaml`` and ``pod-security-policy.yaml``, if this is required in your cluster. -#. Replace the image tags *main_* in ``cluster-collector.yaml``, ``node-collector.yaml`` - You can find possible tags here: https://hub.docker.com/r/checkmk/kubernetes-collector/tags +Support policy +-------- -#. Define communication method for Cluster Collector +Please read our `official docs`_ for information regarding supported Kubernetes versions +and supported Kubernetes distros. - #. NodePort: Enabled by default with NodePort 30035, no change needed. - - #. Ingress: As this depends highly on your Kubernetes set-up, this needs to be entirely configured by you in the *service.yaml* and *ingress.yaml*. Example instructions will follow. - -#. Deploy to your cluster - - .. code-block:: - - kubectl apply -f . - - - -Validation: - -* If everything was successful, you should have one pod called ``cluster-collector`` and on each node pods called ``node-collector-container-metrics`` and ``node-collector-machine-sections`` - - .. code-block:: - - kubectl get pods -n checkmk-monitoring - -* You should have the internal service ``cluster-collector`` and either a NodePort (default 30035) or the service you configured running - - .. code-block:: - - kubectl get svc -n checkmk-monitoring - -Checkmk set-up guide --------------------- - -Prerequisites: - -* The URL of the Kubernetes API server - -* The token of Checkmk service account. - - .. code-block:: - - kubectl get secret $(kubectl get serviceaccount checkmk -o=jsonpath='{.secrets[*].name}' -n checkmk-monitoring) -n checkmk-monitoring -o=jsonpath='{.data.token}' | base64 --decode - -* The certificate of the Checkmk service account. - - .. code-block:: - - kubectl get secret $(kubectl get serviceaccount checkmk -o=jsonpath='{.secrets[*].name}' -n checkmk-monitoring) -n checkmk-monitoring -o=jsonpath='{.data.ca\.crt}' | base64 --decode - -* The *Checkmk Kubernetes Collectors* deployed and the URL under which the *Cluster Collector* is reachable - -* Recommended: Secure communication to the *Cluster Collector* (see details in *Additional topics*) - -#. **Preparing your Checkmk** - - #. Create a piggyback source host with *IP address family* set to *No IP* (this host will contain cluster-level services and metrics) - - #. Create a folder, which will later contain all Kubernetes objects - - #. Configure the dynamic host management: *Setup → Hosts (Dynamic host management) → Add connection* - - * Enter *Title* and click *show more* for *Connection Properties* - - * *Connection Properties → Piggyback creation options → Add new element* - - * In *Create hosts in*: select the folder you just created - - * Select *Automatically delete hosts without piggyback data* - - * Under *Restrict source hosts*: enter the name of your piggyback source host(s) - - * Tick *Service discovery → Discover services during creation* - - #. Optional: add the certificate of the Checkmk service account (depends on your cluster / set-up) - - * *Setup → Global Settings → Trusted certificate authorities for SSL → Add new CA certificate or chain* - - #. Optional: add the token of the Checkmk service account to the password store - - * *Setup → General → Passwords → Add pasword* - -#. **Setting up the connection** - - #. Set up the Kubernetes 2.0 ruleset: *Setup → Agents (VM, Cloud, Container) → Kubernetes → Add rule* - - #. Name your cluster (will be included in the object names) - - #. Add the token of the Checkmk service account to be able to retrieve data. We recommend using the password store for this. - - #. Configure the *API server connection endpoint*: enter the URL (and port), where your API server is located - - * You can set *SSL certficate verification* to *Verify the certificate*, if you added the certificate as mentioned in the previous section - - #. Configure the *Collector NodePort / Ingress endpoint* - - * NodePort: URL of a node + port (default: 30035) - - * If you set-up communication via HTTPS for the cluster collector (see section below), you can set *SSL certficate verification* to *Verify the certificate* - - #. You can exclude namespaces or limit your monitoring to a few namespaces. Cluster-wide components, e.g. nodes, will still be retrieved though - - #. Under *Explicit host* in *Conditions* add the name of piggyback source host. - - #. Activate changes. You are done. - -Additional topics ------------------ - -**Secure commmunication** - -Secure communications to and between the *Checkmk Kubernetes Collectors* can be achieved in various ways. -You can use Kubernetes native methods, e.g. a properly configured Ingress for external communication and a -ServiceMesh for internal communication. This has to be done by you / your cluster administrator. - -Alternatively, you can use the mechanisms provided by *Checkmk Kubernetes Collectors* to secure both the communication from outside -to the *Cluster Collector* API as well as the communication between the *Node Collectors* and the *Cluster Collector*. - -#. Search for the HTTPS comment in ``node-collector.yaml`` and ``cluster-collector.yaml`` and follow the instructions there - -#. Download the ``secret.yaml`` and add certificates - - #. For *cluster-collector-key* and *cluster-collector-cert*: Add certificates with the service: [cluster-collector-service].[collector-namespace] as FQDN following and the hostname/ingress as AltName - - #. Add the respective CA certificate to *checkmkCaCert* and add that in Checkmk as well (Trusted certificate authorities for SSL) - -.. _cAdvisor: "https://github.com/google/cadvisor" +.. _official docs: https://docs.checkmk.com/latest/en/monitoring_kubernetes.html \ No newline at end of file