diff --git a/README.md b/README.md index b7b8ca21..71a1e83f 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,6 @@ The summary of the documentation in the `examples` repository lists all availabl | [Custom serverless runtime image](custom-serverless-runtime-image/README.md) | Build custom runtime image. | Python | | [Kiali](kiali/README.md) | Deploy Kiali to Kyma. | Kiali, Istio, Prometheus | | [Prometheus](prometheus/README.md) | Deploy a Prometheus stack to monitor custom metrics. | Prometheus, Grafana | -| [Loki](loki/README.md) | Deploy Loki to store Pod logs. | Loki, Grafana | ## Installation diff --git a/jaeger/README.md b/jaeger/README.md index 237db94e..d26abad9 100644 --- a/jaeger/README.md +++ b/jaeger/README.md @@ -1,181 +1,3 @@ # Install custom Jaeger in Kyma -## Overview - -The following instructions outline how to use [`Jaeger`](https://github.com/jaegertracing/helm-charts/tree/main/charts/jaeger) as a tracing backend with Kyma's [TracePipeline](https://kyma-project.io/#/telemetry-manager/user/03-traces). - -## Prerequisites - -- Kyma version 2.10 or higher as the target deployment environment -- The [Telemetry module](https://kyma-project.io/#/telemetry-manager/user/README) is [installed](https://kyma-project.io/#/02-get-started/08-install-uninstall-upgrade-kyma-module?id=install-uninstall-and-upgrade-kyma-with-a-module) -- kubectl version 1.22.x or higher -- Helm 3.x - -## Installation - -### Preparation - -1. Export your Namespace as a variable. Replace the `{namespace}` placeholder in the following command and run it: - - ```bash - export K8S_NAMESPACE="{namespace}" - ``` - -1. Export the Helm release name that you want to use. The release name must be unique for the chosen Namespace. Be aware that all resources in the cluster will be prefixed with that name. Run the following command: - ```bash - export HELM_JAEGER_RELEASE="jaeger" - ``` - -1. Update your Helm installation with the required Helm repository: - - ```bash - helm repo add jaegertracing https://jaegertracing.github.io/helm-charts - helm repo update - ``` - -### Install Jaeger - -> **NOTE:** It is officially recommended to install Jaeger with the [Jaeger operator](https://github.com/jaegertracing/helm-charts/tree/main/charts/jaeger-operator). Because the operator requires a cert-manager to be installed, the following instructions use a plain Jaeger installation. However, the described installation is not meant to be used for production setups. - -Run the Helm upgrade command, which installs the chart if not present yet. -```bash -helm upgrade --install --create-namespace -n $K8S_NAMESPACE $HELM_JAEGER_RELEASE jaegertracing/jaeger -f https://raw.githubusercontent.com/kyma-project/examples/main/jaeger/values.yaml -``` - -You can either use the [`values.yaml`](./values.yaml) provided in this `jaeger` folder, which contains customized settings deviating from the default settings, or create your own `values.yaml` file. - -### Verify the installation - -Check if the `jaeger` Pod was successfully created in the Namespace and is in the `Running` state: -```bash -kubectl -n $K8S_NAMESPACE rollout status deploy $HELM_JAEGER_RELEASE -``` - -### Activate a TracePipeline - -To configure the Kyma trace collector with the deployed Jaeger instance as the backend. To create a new [TracePipeline](https://kyma-project.io/#/telemetry-manager/user/03-traces), -execute the following command: - ```bash - cat <**CAUTION**: The following approach exposes the Jaeger instance as it is without providing any ways of authentication. - -To expose Jaeger using Kyma API Gateway, create the following APIRule: -```bash -cat <**CAUTION:** This example uses the Grafana Loki version, which is distributed under AGPL-3.0 only and might not be free of charge for commercial usage. - -## Table of Content - -- [Prerequisites](#prerequisites) -- [Preparation](#preparation) -- [Loki installation](#loki-installation) -- [Log agent installation](#log-agent-installation) -- [Grafana installation](#grafana-installation) -- [Grafana Exposure](#grafana-exposure) - -## Prerequisites - -- Kyma as the target deployment environment -- The [Telemetry module](https://kyma-project.io/#/telemetry-manager/user/README) is [installed](https://kyma-project.io/#/02-get-started/08-install-uninstall-upgrade-kyma-module?id=install-uninstall-and-upgrade-kyma-with-a-module) -- Kubectl version 1.22.x or higher -- Helm 3.x - -## Preparation - -1. Export your Namespace as a variable. Replace the `{NAMESPACE}` placeholder in the following command and run it: - - ```bash - export K8S_NAMESPACE="{NAMESPACE}" - ``` - -2. Export the Helm release names that you want to use. It can be any name, but be aware that all resources in the cluster will be prefixed with that name. Run the following command: - - ```bash - export HELM_LOKI_RELEASE="loki" - ``` - -3. Update your Helm installation with the required Helm repository: - - ```bash - helm repo add grafana https://grafana.github.io/helm-charts - helm repo update - ``` - -## Loki installation - -Depending on your scalability needs and storage requirements, you can install Loki in different [Deployment modes](https://grafana.com/docs/loki/latest/fundamentals/architecture/deployment-modes/). The following instructions install Loki in a lightweight in-cluster solution that does not fulfil production-grade qualities. Consider using a scalable setup based on an object storage backend instead (see [Simple scalable deployment of Grafana Loki with Helm](https://grafana.com/docs/loki/latest/installation/helm/install-scalable/)). - -### Install Loki - -You install the Loki stack with a Helm upgrade command, which installs the chart if not present yet. - -```bash -helm upgrade --install --create-namespace -n ${K8S_NAMESPACE} ${HELM_LOKI_RELEASE} grafana/loki -f https://raw.githubusercontent.com/kyma-project/examples/main/loki/loki-values.yaml -``` - -In any case, you can either create your own `values.yaml` file, or use the [loki-values.yaml](./loki-values.yaml) provided in this `loki` folder, which contains customized settings deviating from the default settings: The provided `values.yaml` file activates the `singleBinary` mode and disables additional components that are usually used when running Loki as a central backend. - -### Verify Loki installation - -Check that the `loki` Pod has been created in the Namespace and is in the `Running` state: - -```bash -kubectl -n ${K8S_NAMESPACE} get pod -l app.kubernetes.io/name=loki -``` -## Log agent installation - -### Install the log agent - -To ingest the application logs from within your cluster to Loki, you can either choose an installation based on [Promtail](https://grafana.com/docs/loki/latest/clients/promtail/), which is the log collector recommended by Loki and provides a ready-to-use setup. Alternatively, you can use Kyma's LogPipeline feature based on Fluent Bit. - -
-
- - Install Promtail - - -To install Promtail pointing it to the previously installed Loki instance, run: - -```bash -helm upgrade --install --create-namespace -n ${K8S_NAMESPACE} promtail grafana/promtail -f https://raw.githubusercontent.com/kyma-project/examples/main/loki/promtail-values.yaml --set "config.clients[0].url=https://${HELM_LOKI_RELEASE}.${K8S_NAMESPACE}.svc.cluster.local:3100/loki/api/v1/push" -``` -
-
- - Install Fluent Bit with Kyma's LogPipeline - - ->**CAUTION:** This setup uses an unsupported output plugin for the LogPipline. - -Apply the LogPipeline: - - ```bash - cat <**NOTE:** The used output plugin configuration uses a static label map to assign labels of a Pod to Loki log streams. It's not recommended to activate the `auto_kubernetes_labels` feature for using all labels of a Pod because this lowers the performance. Follow [Loki's labelling best practices](https://grafana.com/docs/loki/latest/best-practices/) for a tailor-made setup that fits your workload configuration. - -
-
- -### Verify the setup by accessing logs using the Loki API - -1. To access the Loki API, use kubectl port forwarding. Run: - - ```bash - kubectl -n ${K8S_NAMESPACE} port-forward svc/$(kubectl get svc -n ${K8S_NAMESPACE} -l app.kubernetes.io/name=loki -ojsonpath='{.items[0].metadata.name}') 3100 - ``` - -1. Loki queries need a query parameter **time**, provided in nanoseconds. To get the current nanoseconds in Linux or macOS, run: - - ```bash - date +%s - ``` - -1. To get the latest logs from Loki, replace the `{NANOSECONDS}` placeholder with the result of the previous command, and run: - - ```bash - curl -G -s "http://localhost:3100/loki/api/v1/query" \ - --data-urlencode \ - 'query={job="fluentbit"}' \ - --data-urlencode \ - 'time={NANOSECONDS}' - ``` - -## Grafana installation - -Because Grafana provides a very good Loki integration, you might want to install it as well. - -### Install Grafana - -1. To deploy Grafana, run: - - ```bash - helm upgrade --install --create-namespace -n ${K8S_NAMESPACE} grafana grafana/grafana -f https://raw.githubusercontent.com/kyma-project/examples/main/loki/grafana-values.yaml - ``` - -1. To enable Loki as Grafana data source, run: - ```bash - cat <**CAUTION** The example shows an insecure way of exposing the trace endpoint. Do not use it in production. -```bash -export CLUSTER_DOMAIN={my-domain} - -cat <**CAUTION** This example is outdated and will be updated soon. Please have a look at the [trace-demo](./../trace-demo/) and [jaeger](./../jaeger/) instead. +>**CAUTION** This example is outdated and will be updated soon. ## Overview