diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 87f8998527e1..c0f7f5368263 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -11,5 +11,5 @@ Fixes # - [ ] Tests updated - [ ] `CHANGELOG.md` updated - [ ] If the change is worth mentioning in the release notes, add `add-to-release-notes` label -- [ ] Changes that require user attention or interaction to upgrade are documented in `docs/sources/upgrading/_index.md` +- [ ] Changes that require user attention or interaction to upgrade are documented in `docs/sources/setup/upgrade/_index.md` - [ ] For Helm chart changes bump the Helm chart version in `production/helm/loki/Chart.yaml` and update `production/helm/loki/CHANGELOG.md` and `production/helm/loki/README.md`. [Example PR](https://github.com/grafana/loki/commit/d10549e3ece02120974929894ee333d07755d213) diff --git a/CHANGELOG.md b/CHANGELOG.md index af9c5787b023..32e91173b8cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1371,7 +1371,7 @@ There are many other noteworthy additions and fixes, too many to list, but we sh Thanks to everyone for another exciting Loki release!! -Please read the [Upgrade Guide](https://github.com/grafana/loki/blob/master/docs/sources/upgrading/_index.md#220) before upgrading for a smooth experience. +Please read the [Upgrade Guide](https://github.com/grafana/loki/blob/master/docs/sources/setup/upgrade/_index.md#220) before upgrading for a smooth experience. TL;DR Loki 2.2 changes the internal chunk format which limits what versions you can downgrade to, a bug in how many queries were allowed to be scheduled per tenant was fixed which might affect your `max_query_parallelism` and `max_outstanding_per_tenant` settings, and we fixed a mistake related `scrape_configs` which do not have a `pipeline_stages` defined. If you have any Promtail `scrape_configs` which do not specify `pipeline_stages` you should go read the upgrade notes! @@ -1831,11 +1831,11 @@ Thanks again for the many incredible contributions and improvements from the won **Please Note** There are several changes in this release which require your attention! -* Anyone using a docker image please go read the [upgrade guide](https://github.com/grafana/loki/blob/master/docs/sources/upgrading/_index.md#200)!! There is one important consideration around a potentially breaking schema change depending on your configuration. -* MAJOR changes have been made to the boltdb-shipper index, breaking changes are not expected but extra precautions are highly recommended, more details in the [upgrade guide](https://github.com/grafana/loki/blob/master/docs/sources/upgrading/_index.md#200). +* Anyone using a docker image please go read the [upgrade guide](https://github.com/grafana/loki/blob/master/docs/sources/setup/upgrade/_index.md#200)!! There is one important consideration around a potentially breaking schema change depending on your configuration. +* MAJOR changes have been made to the boltdb-shipper index, breaking changes are not expected but extra precautions are highly recommended, more details in the [upgrade guide](https://github.com/grafana/loki/blob/master/docs/sources/setup/upgrade/_index.md#200). * The long deprecated `entry_parser` config in Promtail has been removed, use [pipeline_stages](https://grafana.com/docs/loki/latest/clients/promtail/configuration/#pipeline_stages) instead. -Check the [upgrade guide](https://github.com/grafana/loki/blob/master/docs/sources/upgrading/_index.md#200) for detailed information on all these changes. +Check the [upgrade guide](https://github.com/grafana/loki/blob/master/docs/sources/setup/upgrade/_index.md#200) for detailed information on all these changes. ### 2.0!!!! diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ad48caa0c0c6..22d997036530 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,7 +26,7 @@ LIDs must be created as a pull request using [this template](docs/sources/commun * It fixes an issue present in a previous release * It causes a change in operation that would be useful for an operator of Loki to know * You can skip this step for documentation changes, build related changes and simple bug fixes or enhancements. Rationale being we are attempting to curate the CHANGELOG entries with the most relevant and important changes that end users of Loki care about. -1. Your PR documents upgrading steps under `docs/sources/upgrading/_index.md` if it changes: +1. Your PR documents upgrading steps under `docs/sources/setup/upgrade/_index.md` if it changes: * Default configuration values * Metric names or label names * Changes existing log lines that may be used in dashboard or alerts. e.g: logs lines in any `metrics.go` files might be used in building dashboards or alerts. @@ -135,7 +135,7 @@ import ( We're glad you're here to help make our technical documentation even better for Loki users. -The Grafana docs team has created a [Writer's Toolkit](https://grafana.com/docs/writers-toolkit/writing-guide/contribute-documentation/) that includes information about how we write docs, a [Style Guide](https://grafana.com/docs/writers-toolkit/style-guide/), and templates to help you contribute to the Loki documentation. +The Grafana docs team has created a [Writer's Toolkit](https://grafana.com/docs/writers-toolkit/) that includes information about how we write docs, a [Style Guide](https://grafana.com/docs/writers-toolkit/write/style-guide/), and templates to help you contribute to the Loki documentation. The Loki documentation is written using the CommonMark flavor of markdown, including some extended features. For more information about markdown, you can see the [CommonMark specification](https://spec.commonmark.org/), and a [quick reference guide](https://commonmark.org/help/) for CommonMark. diff --git a/Makefile b/Makefile index e1f13017f5e4..8ee96bd0f493 100644 --- a/Makefile +++ b/Makefile @@ -631,8 +631,8 @@ loki-operator-push: loki-operator-image-cross documentation-helm-reference-check: @echo "Checking diff" - $(MAKE) -BC docs sources/installation/helm/reference.md - @git diff --exit-code -- docs/sources/installation/helm/reference.md || (echo "Please generate Helm Chart reference by running 'make -C docs sources/installation/helm/reference.md'" && false) + $(MAKE) -BC docs sources/setup/install/helm/reference.md + @git diff --exit-code -- docs/sources/setup/install/helm/reference.md || (echo "Please generate Helm Chart reference by running 'make -C docs sources/setup/install/helm/reference.md'" && false) ######## # Misc # diff --git a/README.md b/README.md index 6efa9532ae4a..5486d9e93834 100644 --- a/README.md +++ b/README.md @@ -29,13 +29,13 @@ Loki differs from Prometheus by focusing on logs instead of metrics, and deliver ## Getting started -* [Installing Loki](https://grafana.com/docs/loki/latest/installation/) +* [Installing Loki](https://grafana.com/docs/loki/latest/setup/install/) * [Installing Promtail](https://grafana.com/docs/loki/latest/clients/promtail/installation/) * [Getting Started](https://grafana.com/docs/loki/latest/getting-started/) ## Upgrading -* [Upgrading Loki](https://grafana.com/docs/loki/latest/upgrading/) +* [Upgrading Loki](https://grafana.com/docs/loki/latest/setup/upgrade/) ## Documentation @@ -44,16 +44,16 @@ Loki differs from Prometheus by focusing on logs instead of metrics, and deliver Commonly used sections: -- [API documentation](https://grafana.com/docs/loki/latest/api/) for getting logs into Loki. -- [Labels](https://grafana.com/docs/loki/latest/getting-started/labels/) +- [API documentation](https://grafana.com/docs/loki/latest/reference/api/) for getting logs into Loki. +- [Labels](https://grafana.com/docs/loki/latest/get-started/labels/) - [Operations](https://grafana.com/docs/loki/latest/operations/) - [Promtail](https://grafana.com/docs/loki/latest/clients/promtail/) is an agent which tails log files and pushes them to Loki. - [Pipelines](https://grafana.com/docs/loki/latest/clients/promtail/pipelines/) details the log processing pipeline. - [Docker Driver Client](https://grafana.com/docs/loki/latest/clients/docker-driver/) is a Docker plugin to send logs directly to Loki from Docker containers. - [LogCLI](https://grafana.com/docs/loki/latest/query/logcli/) provides a command-line interface for querying logs. - [Loki Canary](https://grafana.com/docs/loki/latest/operations/loki-canary/) monitors your Loki installation for missing logs. -- [Troubleshooting](https://grafana.com/docs/loki/latest/getting-started/troubleshooting/) presents help dealing with error messages. -- [Loki in Grafana](https://grafana.com/docs/loki/latest/getting-started/grafana/) describes how to set up a Loki datasource in Grafana. +- [Troubleshooting](https://grafana.com/docs/loki/latest/operations/troubleshooting/) presents help dealing with error messages. +- [Loki in Grafana](https://grafana.com/docs/loki/latest/visualize/grafana/) describes how to set up a Loki datasource in Grafana. ## Getting Help diff --git a/docs/sources/operations/storage/wal.md b/docs/sources/operations/storage/wal.md index d475d5153712..a504ed4d2948 100644 --- a/docs/sources/operations/storage/wal.md +++ b/docs/sources/operations/storage/wal.md @@ -91,7 +91,7 @@ After hitting the endpoint for `ingester-2 ingester-3`, scale down the ingesters ### Kubernetes hacking -Statefulsets are significantly more cumbersome to work with/upgrade/etc. Much of this stems from immutable fields on the specification. For example, if one wants to start using the WAL with single store Loki and wants separate volume mounts for the WAL and the boltdb-shipper, you may see immutability errors when attempting updates the Kubernetes statefulsets. +Statefulsets are significantly more cumbersome to work with, upgrade, and so on. Much of this stems from immutable fields on the specification. For example, if one wants to start using the WAL with single store Loki and wants separate volume mounts for the WAL and the boltdb-shipper, you may see immutability errors when attempting updates the Kubernetes statefulsets. In this case, try `kubectl -n delete sts ingester --cascade=false`. This will leave the pods alive but delete the statefulset. Then you may recreate the (updated) statefulset and one-by-one start deleting the `ingester-0` through `ingester-n` pods _in that order_, allowing the statefulset to spin up new pods to replace them. diff --git a/docs/sources/release-notes/next.md b/docs/sources/release-notes/next.md index b0988c0d6ec2..91e430b3e806 100644 --- a/docs/sources/release-notes/next.md +++ b/docs/sources/release-notes/next.md @@ -2,6 +2,7 @@ title: V?.? description: Version ?.? release notes weight: 100000 +draft: true --- # V?.? diff --git a/docs/sources/release-notes/v2-3.md b/docs/sources/release-notes/v2-3.md index 4ec227480a6f..6167bf343bee 100644 --- a/docs/sources/release-notes/v2-3.md +++ b/docs/sources/release-notes/v2-3.md @@ -42,7 +42,7 @@ Lastly several useful additions to the LogQL query language have been included: ## Upgrade considerations -The path from 2.2.1 to 2.3.0 should be smooth, as always, read the [Upgrade Guide](https://github.com/grafana/loki/blob/master/docs/sources/upgrading/_index.md#230) for important upgrade guidance. +The path from 2.2.1 to 2.3.0 should be smooth, as always, read the [Upgrade Guide]({{< relref "../setup/upgrade#230" >}}) for important upgrade guidance. One change we consider noteworthy however is: diff --git a/docs/sources/release-notes/v2-4.md b/docs/sources/release-notes/v2-4.md index 018948f3b696..871bffb8b8b9 100644 --- a/docs/sources/release-notes/v2-4.md +++ b/docs/sources/release-notes/v2-4.md @@ -27,7 +27,7 @@ For a full list of all changes, look at the [CHANGELOG](https://github.com/grafa ## Upgrade Considerations -Please read the [upgrade guide]({{< relref "../upgrading#240" >}}) before updating Loki. +Please read the [upgrade guide]({{< relref "../setup/upgrade#240" >}}) before updating Loki. We made a lot of changes to Loki’s configuration as part of this release. We have tried our best to make sure changes are compatible with existing configurations, however some changes to default limits may impact users who didn't have values explicitly set for these limits in their configuration files. diff --git a/docs/sources/release-notes/v2-5.md b/docs/sources/release-notes/v2-5.md index 1dd9775b6628..918c6fad3342 100644 --- a/docs/sources/release-notes/v2-5.md +++ b/docs/sources/release-notes/v2-5.md @@ -25,7 +25,7 @@ For a full list of all changes, look at the [CHANGELOG](https://github.com/grafa ## Upgrade Considerations -As always, please read the [upgrade guide]({{< relref "../upgrading#250" >}}) before upgrading Loki. +As always, please read the [upgrade guide]({{< relref "../setup/upgrade#250" >}}) before upgrading Loki. ### Changes to the config `split_queries_by_interval` The most likely impact many people will see is Loki failing to start because of a change in the YAML configuration for `split_queries_by_interval`. It was previously possible to define this value in two places. diff --git a/docs/sources/release-notes/v2-6.md b/docs/sources/release-notes/v2-6.md index 19a1de53a750..aeac78937f70 100644 --- a/docs/sources/release-notes/v2-6.md +++ b/docs/sources/release-notes/v2-6.md @@ -19,7 +19,7 @@ For a full list of all changes, look at the [CHANGELOG](https://github.com/grafa ## Upgrade Considerations -As always, please read the [upgrade guide]({{< relref "../upgrading#260" >}}) before upgrading Loki. +As always, please read the [upgrade guide]({{< relref "../setup/upgrade#260" >}}) before upgrading Loki. ## Bug fixes diff --git a/docs/sources/release-notes/v2-7.md b/docs/sources/release-notes/v2-7.md index c30911ad6e45..416ee8e03e7c 100644 --- a/docs/sources/release-notes/v2-7.md +++ b/docs/sources/release-notes/v2-7.md @@ -14,7 +14,7 @@ Grafana Labs is excited to announce the release of Loki 2.7. Here's a summary of - **Better Support for Azure Blob Storage** thanks to the ability to use Azure's Service Principal Credentials. - **Logs can now be pushed from the Loki canary** so you don't have to rely on a scraping service to use the canary. - **Additional `label_format` fields** `__timestamp__` and `__line__`. -- **`fifocache` has been renamed** The in-memory `fifocache` has been renamed to `embedded-cache`. Check [upgrade guide]({{< relref "../upgrading#270" >}}) for more details +- **`fifocache` has been renamed** The in-memory `fifocache` has been renamed to `embedded-cache`. Check [upgrade guide]({{< relref "../setup/upgrade#270" >}}) for more details - **New HTTP endpoint for Ingester shutdown** that will also delete the ring token. - **Faster label queries** thanks to new parallization. - **Introducing Stream Sharding** an experimental new feature to help deal with very large streams. @@ -30,7 +30,7 @@ For a full list of all, look at the [CHANGELOG](https://github.com/grafana/loki/ ## Upgrade Considerations -As always, please read the [upgrade guide]({{< relref "../upgrading#270" >}}) before upgrading Loki. +As always, please read the [upgrade guide]({{< relref "../setup/upgrade#270" >}}) before upgrading Loki. ## Bug fixes diff --git a/docs/sources/release-notes/v2-8.md b/docs/sources/release-notes/v2-8.md index 04f2fd4af669..9affaa134a7a 100644 --- a/docs/sources/release-notes/v2-8.md +++ b/docs/sources/release-notes/v2-8.md @@ -18,7 +18,7 @@ For a full list of all changes, look at the [CHANGELOG](https://github.com/grafa ## Upgrade Considerations -As always, please read the [upgrade guide]({{< relref "../upgrading#270" >}}) before upgrading Loki. +As always, please read the [upgrade guide]({{< relref "../setup/upgrade#270" >}}) before upgrading Loki. ## Bug fixes diff --git a/docs/sources/setup/_index.md b/docs/sources/setup/_index.md new file mode 100644 index 000000000000..31c1cd885be1 --- /dev/null +++ b/docs/sources/setup/_index.md @@ -0,0 +1,13 @@ +--- +title: Setup Loki +menuTitle: Setup +description: How to install and upgrade Loki, and how to migrate configurations. +weight: 300 +--- + +# Setup Loki + +- Estimate the initial [size]({{< relref "./size" >}}) for your Loki cluster. +- [Install]({{< relref "./install" >}}) Loki. +- [Migrate]({{< relref "./migrate" >}}) from one Loki implementation to another. +- [Upgrade]({{< relref "./upgrade" >}}) from one Loki version to a newer version. diff --git a/docs/sources/installation/_index.md b/docs/sources/setup/install/_index.md similarity index 72% rename from docs/sources/installation/_index.md rename to docs/sources/setup/install/_index.md index 9fbdd8852026..f2c922381851 100644 --- a/docs/sources/installation/_index.md +++ b/docs/sources/setup/install/_index.md @@ -1,6 +1,9 @@ --- title: Installation -description: Installation +menuTitle: Install +description: Describes how to install Loki. +aliases: + - ../installation/ weight: 200 --- @@ -10,11 +13,11 @@ There are several methods of installing Loki and Promtail: - [Install using Helm (recommended)]({{< relref "./helm" >}}) - [Install using Tanka]({{< relref "./tanka" >}}) -- [Install through Docker or Docker Compose]({{< relref "./docker" >}}) +- [Install using Docker or Docker Compose]({{< relref "./docker" >}}) - [Install and run locally]({{< relref "./local" >}}) - [Install from source]({{< relref "./install-from-source" >}}) -The [Sizing Tool]({{< relref "./sizing" >}}) can be used to determine the proper cluster sizing +The [Sizing Tool]({{< relref "../size" >}}) can be used to determine the proper cluster sizing given an expected ingestion rate and query performance. It targets the Helm installation on Kubernetes. diff --git a/docs/sources/installation/docker.md b/docs/sources/setup/install/docker.md similarity index 88% rename from docs/sources/installation/docker.md rename to docs/sources/setup/install/docker.md index d037288ee3fa..ef72645dfb93 100644 --- a/docs/sources/installation/docker.md +++ b/docs/sources/setup/install/docker.md @@ -1,11 +1,14 @@ --- -title: Install Grafana Loki with Docker or Docker Compose -description: Docker -weight: 30 +title: Install Loki with Docker or Docker Compose +menuTitle: Install using Docker +description: Describes how to install Loki using Docker or Docker Compose +aliases: + - ../../installation/docker/ +weight: 400 --- -# Install Grafana Loki with Docker or Docker Compose +# Install Loki with Docker or Docker Compose -You can install Grafana Loki and Promtail with Docker or Docker Compose if you are evaluating, testing, or developing Loki. +You can install Loki and Promtail with Docker or Docker Compose if you are evaluating, testing, or developing Loki. For production, we recommend installing with Tanka or Helm. The configuration acquired with these installation instructions run Loki as a single binary. diff --git a/docs/sources/installation/helm/_index.md b/docs/sources/setup/install/helm/_index.md similarity index 93% rename from docs/sources/installation/helm/_index.md rename to docs/sources/setup/install/helm/_index.md index 34b9d5ab6e9e..d920dace8f2b 100644 --- a/docs/sources/installation/helm/_index.md +++ b/docs/sources/setup/install/helm/_index.md @@ -3,8 +3,8 @@ title: Install Grafana Loki with Helm menuTitle: Install using Helm description: Learn how to install Grafana Loki on Kubernetes with Helm. aliases: - - /docs/installation/helm -weight: 100 + - ../../installation/helm/ +weight: 200 keywords: - helm - scalable diff --git a/docs/sources/installation/helm/concepts.md b/docs/sources/setup/install/helm/concepts.md similarity index 85% rename from docs/sources/installation/helm/concepts.md rename to docs/sources/setup/install/helm/concepts.md index 72c91c80bf4f..fd8f81ebe474 100644 --- a/docs/sources/installation/helm/concepts.md +++ b/docs/sources/setup/install/helm/concepts.md @@ -3,7 +3,7 @@ title: Helm chart components menuTitle: Helm chart components description: A short introduction to the components installed with the Loki Helm Chart. aliases: - - /docs/installation/helm/concepts + - ../../../installation/helm/concepts/ weight: 100 keywords: - dashboards @@ -25,7 +25,7 @@ This chart includes dashboards for monitoring Loki. These require the scrape con ## Canary -This chart installs the [canary]({{< relref "../../operations/loki-canary" >}}) and its alerts by default. This is another tool to verify the Loki deployment is in a healthy state. It can be disabled with `monitoring.lokiCanary.enabled=false`. +This chart installs the [canary]({{< relref "../../../operations/loki-canary" >}}) and its alerts by default. This is another tool to verify the Loki deployment is in a healthy state. It can be disabled with `monitoring.lokiCanary.enabled=false`. ## Gateway diff --git a/docs/sources/installation/helm/configure-storage/index.md b/docs/sources/setup/install/helm/configure-storage/_index.md similarity index 91% rename from docs/sources/installation/helm/configure-storage/index.md rename to docs/sources/setup/install/helm/configure-storage/_index.md index a2e649d78629..105a3fd5397d 100644 --- a/docs/sources/installation/helm/configure-storage/index.md +++ b/docs/sources/setup/install/helm/configure-storage/_index.md @@ -3,7 +3,8 @@ title: Configure storage menuTitle: Configure storage description: Configure Loki storage aliases: - - /docs/installation/helm/storage + - ../../../installation/helm/configure-storage/ + - ../../../installation/helm/storage weight: 500 keywords: - object store @@ -37,7 +38,7 @@ This guide assumes Loki will be installed in one of the modes above and that a ` **To grant access to S3 via an IAM role without providing credentials:** -1. Provision an IAM role, policy and S3 bucket as described in [Storage]({{< relref "../../../storage#aws-deployment-s3-single-store" >}}). +1. Provision an IAM role, policy and S3 bucket as described in [Storage]({{< relref "../../../../storage#aws-deployment-s3-single-store" >}}). - If the Terraform module was used note the annotation emitted by `terraform output -raw annotation`. 2. Add the IAM role annotation to the service account in `values.yaml`: diff --git a/docs/sources/installation/helm/install-monolithic/index.md b/docs/sources/setup/install/helm/install-monolithic/_index.md similarity index 88% rename from docs/sources/installation/helm/install-monolithic/index.md rename to docs/sources/setup/install/helm/install-monolithic/_index.md index 5fda2a7531e8..c74b0c4cecfb 100644 --- a/docs/sources/installation/helm/install-monolithic/index.md +++ b/docs/sources/setup/install/helm/install-monolithic/_index.md @@ -3,16 +3,16 @@ title: Install the monolithic Helm chart menuTitle: Install monolithic Loki description: Install Loki in monolithic, single binary mode. aliases: - - /docs/installation/helm/monolithic -weight: 300 -keywords: + - ../../../installation/helm/monolithic + - ../../../installation/helm/install-monolithic/ +weight: 100 --- # Install the monolithic Helm chart This Helm Chart installation runs the Grafana Loki *single binary* within a Kubernetes cluster. -If you set the `singleBinary.replicas` value to 1, this chart configures Loki to run the `all` target in a [monolithic mode]({{< relref "../../../get-started/deployment-modes#monolithic-mode" >}}), designed to work with a filesystem storage. It will also configure meta-monitoring of metrics and logs. +If you set the `singleBinary.replicas` value to 1, this chart configures Loki to run the `all` target in a [monolithic mode]({{< relref "../../../../get-started/deployment-modes#monolithic-mode" >}}), designed to work with a filesystem storage. It will also configure meta-monitoring of metrics and logs. If you set the `singleBinary.replicas` value to 2 or more, this chart configures Loki to run a *single binary* in a replicated, highly available mode. When running replicas of a single binary, you must configure object storage. **Before you begin: Software Requirements** diff --git a/docs/sources/installation/helm/install-scalable/index.md b/docs/sources/setup/install/helm/install-scalable/_index.md similarity index 83% rename from docs/sources/installation/helm/install-scalable/index.md rename to docs/sources/setup/install/helm/install-scalable/_index.md index 910147b42ce5..63a1d871747c 100644 --- a/docs/sources/installation/helm/install-scalable/index.md +++ b/docs/sources/setup/install/helm/install-scalable/_index.md @@ -3,8 +3,9 @@ title: Install the scalable monolithic Helm chart menuTitle: Install scalable Loki description: Install Loki in scalable mode. aliases: - - /docs/installation/helm/scalable -weight: 400 + - ../../../installation/helm/scalable/ + - ../../../installation/helm/install-scalable/ +weight: 300 keywords: --- @@ -14,7 +15,7 @@ keywords: This Helm Chart installation runs the Grafana Loki cluster within a Kubernetes cluster. -If object storge is configured, this chart configures Loki to run `read` and `write` targets in a [scalable mode]({{< relref "../../../get-started/deployment-modes#simple-scalable-deployment-mode" >}}), highly available architecture (3 replicas of each) designed to work with AWS S3 object storage. It will also configure meta-monitoring of metrics and logs. +If object storge is configured, this chart configures Loki to run `read` and `write` targets in a [scalable mode]({{< relref "../../../../get-started/deployment-modes#simple-scalable-deployment-mode" >}}), highly available architecture (3 replicas of each) designed to work with AWS S3 object storage. It will also configure meta-monitoring of metrics and logs. It is not possible to run the scalable mode with the `filesystem` storage. @@ -23,7 +24,7 @@ It is not possible to run the scalable mode with the `filesystem` storage. - Helm 3 or above. See [Installing Helm](https://helm.sh/docs/intro/install/). - A running Kubernetes cluster. - A Prometheus operator installation in case meta-monitoring should be used. -- Optionally a Memcached deployment for better performance. Consult the [caching section]({{< relref "../../../operations/caching" >}}) on how to configure Memcached. +- Optionally a Memcached deployment for better performance. Consult the [caching section]({{< relref "../../../../operations/caching" >}}) on how to configure Memcached. **To deploy Loki in scalable mode:** diff --git a/docs/sources/installation/helm/monitor-and-alert/_index.md b/docs/sources/setup/install/helm/monitor-and-alert/_index.md similarity index 84% rename from docs/sources/installation/helm/monitor-and-alert/_index.md rename to docs/sources/setup/install/helm/monitor-and-alert/_index.md index 75f281e6f052..db9b2d24e5e4 100644 --- a/docs/sources/installation/helm/monitor-and-alert/_index.md +++ b/docs/sources/setup/install/helm/monitor-and-alert/_index.md @@ -1,9 +1,9 @@ --- title: Monitoring description: monitoring -weight: 900 +weight: 500 aliases: - - /docs/installation/helm/monitor-and-alert + - ../../../installation/helm/monitor-and-alert/ keywords: - helm - scalable diff --git a/docs/sources/installation/helm/monitor-and-alert/with-grafana-cloud.md b/docs/sources/setup/install/helm/monitor-and-alert/with-grafana-cloud.md similarity index 98% rename from docs/sources/installation/helm/monitor-and-alert/with-grafana-cloud.md rename to docs/sources/setup/install/helm/monitor-and-alert/with-grafana-cloud.md index 68e4604acecd..1f46c1046ab2 100644 --- a/docs/sources/installation/helm/monitor-and-alert/with-grafana-cloud.md +++ b/docs/sources/setup/install/helm/monitor-and-alert/with-grafana-cloud.md @@ -3,7 +3,7 @@ title: Configure monitoring and alerting of Loki using Grafana Cloud menuTitle: Monitor Loki with Grafana Cloud description: setup monitoring and alerts for Loki using Grafana Cloud aliases: - - /docs/installation/helm/monitoring/with-grafana-cloud + - ../../../../installation/helm/monitor-and-alert/with-grafana-cloud weight: 200 keywords: - monitoring diff --git a/docs/sources/installation/helm/monitor-and-alert/with-local-monitoring.md b/docs/sources/setup/install/helm/monitor-and-alert/with-local-monitoring.md similarity index 99% rename from docs/sources/installation/helm/monitor-and-alert/with-local-monitoring.md rename to docs/sources/setup/install/helm/monitor-and-alert/with-local-monitoring.md index ff19218f3202..eadd153ccfa4 100644 --- a/docs/sources/installation/helm/monitor-and-alert/with-local-monitoring.md +++ b/docs/sources/setup/install/helm/monitor-and-alert/with-local-monitoring.md @@ -3,7 +3,7 @@ title: Configure monitoring and alerting menuTitle: Configure monitoring and alerting description: setup monitoring and alerts for the Helm chart aliases: - - /docs/installation/helm/monitoring/with-local-monitoring + - ../../../../installation/helm/monitor-and-alert/with-local-monitoring/ weight: 100 keywords: - monitoring diff --git a/docs/sources/installation/helm/reference.md b/docs/sources/setup/install/helm/reference.md similarity index 99% rename from docs/sources/installation/helm/reference.md rename to docs/sources/setup/install/helm/reference.md index a5fab6deed78..eb202548efe3 100644 --- a/docs/sources/installation/helm/reference.md +++ b/docs/sources/setup/install/helm/reference.md @@ -2,7 +2,9 @@ title: Helm Chart Values menuTitle: Helm chart values description: Reference for Helm Chart values. -weight: 200 +weight: 500 +aliases: + - ../../../installation/helm/reference/ keywords: [] --- diff --git a/docs/sources/installation/install-from-source.md b/docs/sources/setup/install/install-from-source.md similarity index 80% rename from docs/sources/installation/install-from-source.md rename to docs/sources/setup/install/install-from-source.md index 429c02ab4039..d7f8350262a3 100644 --- a/docs/sources/installation/install-from-source.md +++ b/docs/sources/setup/install/install-from-source.md @@ -1,7 +1,10 @@ --- title: Build from source -description: Build from source -weight: 50 +menuTitle: Install from source +description: Describes how to install Loki from the source code. +aliases: + - ../../installation/install-from-source/ +weight: 700 --- # Build from source diff --git a/docs/sources/installation/istio.md b/docs/sources/setup/install/istio.md similarity index 96% rename from docs/sources/installation/istio.md rename to docs/sources/setup/install/istio.md index 2e7ac69d62d4..8e3b18ab3046 100644 --- a/docs/sources/installation/istio.md +++ b/docs/sources/setup/install/istio.md @@ -1,9 +1,13 @@ --- -title: Installing on Istio -description: Installation instructions for Istio -weight: 50 +title: Install on Istio +menuTitle: +description: Installation instructions for Istio service mesh +aliases: + - ../../installation/istio/ +weight: 600 +keywords: --- -# Installing on Istio +# Install on Istio When installing Loki on Istio service mesh you must complete some additional steps. Without these steps, the ingester, querier, etc. might start, but you will see logs like the following: diff --git a/docs/sources/installation/local.md b/docs/sources/setup/install/local.md similarity index 92% rename from docs/sources/installation/local.md rename to docs/sources/setup/install/local.md index 002bee8a57f5..961b910a9032 100644 --- a/docs/sources/installation/local.md +++ b/docs/sources/setup/install/local.md @@ -1,7 +1,10 @@ --- title: Local -description: Install and run Grafana Loki locally -weight: 40 +menuTitle: Install locally +description: Install and run Grafana Loki locally +aliases: + - ../../installation/local/ +weight: 500 --- # Local @@ -31,7 +34,7 @@ The configuration specifies running Loki as a single binary. 1. Navigate to the [release page](https://github.com/grafana/loki/releases/). 2. Scroll down to the Assets section under the version that you want to install. 3. Download the Loki and Promtail .zip files that correspond to your system. - **Note:** Do not download LogCLI or Loki Canary at this time. `LogCLI` allows you to run Loki queries in a command line interface. [Loki Canary]({{< relref "../operations/loki-canary" >}}) is a tool to audit Loki performance. + **Note:** Do not download LogCLI or Loki Canary at this time. `LogCLI` allows you to run Loki queries in a command line interface. [Loki Canary]({{< relref "../../operations/loki-canary" >}}) is a tool to audit Loki performance. 4. Unzip the package contents into the same directory. This is where the two programs will run. 5. In the command line, change directory (`cd` on most systems) to the directory with Loki and Promtail. Copy and paste the commands below into your command line to download generic configuration files. **Note:** Use the corresponding Git refs that match your downloaded Loki version to get the correct configuration file. For example, if you are using Loki version 2.6.1, you need to use the `https://raw.githubusercontent.com/grafana/loki/v2.6.1/cmd/loki/loki-local-config.yaml` URL to download the configuration file that corresponds to the Loki version you aim to run. @@ -56,7 +59,7 @@ The configuration specifies running Loki as a single binary. Loki runs and displays Loki logs in your command line and on http://localhost:3100/metrics. The next step will be running an agent to send logs to Loki. -To do so with Promtail, refer to the [Promtail configuration]({{< relref "../clients/promtail" >}}). +To do so with Promtail, refer to the [Promtail configuration]({{< relref "../../clients/promtail" >}}). ## Release binaries - openSUSE Linux only diff --git a/docs/sources/installation/tanka.md b/docs/sources/setup/install/tanka.md similarity index 97% rename from docs/sources/installation/tanka.md rename to docs/sources/setup/install/tanka.md index 0106c967fdeb..14deffd828e7 100644 --- a/docs/sources/installation/tanka.md +++ b/docs/sources/setup/install/tanka.md @@ -1,7 +1,10 @@ --- -title: Tanka -description: Install Grafana Loki with Tanka -weight: 10 +title: Tanka +menuTitle: Install using Tanka +description: Install Loki using Tanka +aliases: + - ../../installation/tanka/ +weight: 300 --- # Tanka diff --git a/docs/sources/setup/migrate/_index.md b/docs/sources/setup/migrate/_index.md new file mode 100644 index 000000000000..f8158b199f04 --- /dev/null +++ b/docs/sources/setup/migrate/_index.md @@ -0,0 +1,13 @@ +--- +title: Migrate +menuTitle: Migrate +description: Instructions for migrating from one Loki implementation to another +weight: 300 +--- + +# Migrate + +This section contains instructions for migrating from one Loki implementation to another. + +- [Migrate]({{< relref "./migrate-from-distributed" >}}) from the `Loki-distributed` Helm chart to the `loki` Helm chart. +- [Migrate]({{< relref "./migrate-to-three-scalable-targets" >}}) from the two target Helm chart to the three target scalable configuration Helm chart. diff --git a/docs/sources/installation/helm/migrate-from-distributed/index.md b/docs/sources/setup/migrate/migrate-from-distributed/index.md similarity index 99% rename from docs/sources/installation/helm/migrate-from-distributed/index.md rename to docs/sources/setup/migrate/migrate-from-distributed/index.md index 01d1f40fa3b5..51c1476c58f2 100644 --- a/docs/sources/installation/helm/migrate-from-distributed/index.md +++ b/docs/sources/setup/migrate/migrate-from-distributed/index.md @@ -3,7 +3,7 @@ title: Migrate from `loki-distributed` Helm chart menuTitle: Migrate from `loki-distributed` description: Migration guide for moving from `loki-distributed` to `loki` aliases: - - /docs/installation/helm/migrate-from-distributed + - ../../installation/helm/migrate-from-distributed weight: 600 keywords: - migrate diff --git a/docs/sources/installation/helm/migrate-to-three-scalable-targets/index.md b/docs/sources/setup/migrate/migrate-to-three-scalable-targets/index.md similarity index 96% rename from docs/sources/installation/helm/migrate-to-three-scalable-targets/index.md rename to docs/sources/setup/migrate/migrate-to-three-scalable-targets/index.md index 70ce390009be..071bf6335ae3 100644 --- a/docs/sources/installation/helm/migrate-to-three-scalable-targets/index.md +++ b/docs/sources/setup/migrate/migrate-to-three-scalable-targets/index.md @@ -3,7 +3,7 @@ title: Migrate to three scalable targets menuTitle: Migrate to three targets description: Migration guide for moving from two scalable to three scalable targets aliases: - - /docs/installation/helm/migrate-from-distributed + - ../../installation/helm/migrate-to-three-scalable-targets/ weight: 700 keywords: - migrate diff --git a/docs/sources/installation/sizing/index.md b/docs/sources/setup/size/_index.md similarity index 97% rename from docs/sources/installation/sizing/index.md rename to docs/sources/setup/size/_index.md index 35dfa0d411d9..ec308602a7fb 100644 --- a/docs/sources/installation/sizing/index.md +++ b/docs/sources/setup/size/_index.md @@ -1,9 +1,10 @@ --- title: Size the cluster menuTitle: Size the cluster -description: This tool generates a Helm Chart values.yaml file based on expected ingestion, retention rate, and node type, to help size your Grafana deployment. +description: Tool that generates a Helm Chart values.yaml file based on expected ingestion, retention rate, and node type, to help size your Grafana deployment. aliases: - - /docs/installation/helm/generate + - ../installation/sizing/ + - ../installation/helm/generate weight: 100 keywords: [] --- diff --git a/docs/sources/upgrading/_index.md b/docs/sources/setup/upgrade/_index.md similarity index 99% rename from docs/sources/upgrading/_index.md rename to docs/sources/setup/upgrade/_index.md index e8e66cff1daf..1d749e8d5854 100644 --- a/docs/sources/upgrading/_index.md +++ b/docs/sources/setup/upgrade/_index.md @@ -1,10 +1,13 @@ --- -title: Upgrading +title: Upgrade Loki +menuTitle: Upgrade description: Upgrading Grafana Loki -weight: 250 +aliases: + - ../upgrading/ +weight: 400 --- -# Upgrading +# Upgrade Loki Every attempt is made to keep Grafana Loki backwards compatible, such that upgrades should be low risk and low friction. @@ -462,7 +465,7 @@ limits_config: retention_period: [30d] ``` -See the [retention docs]({{< relref "../operations/storage/retention" >}}) for more info. +See the [retention docs]({{< relref "../../operations/storage/retention" >}}) for more info. #### Log messages on startup: proto: duplicate proto type registered: @@ -924,7 +927,7 @@ If you happen to have `results_cache.max_freshness` set, use `limits_config.max_ ### Promtail config removed -The long deprecated `entry_parser` config in Promtail has been removed, use [pipeline_stages]({{< relref "../clients/promtail/configuration#pipeline_stages" >}}) instead. +The long deprecated `entry_parser` config in Promtail has been removed, use [pipeline_stages]({{< relref "../../clients/promtail/configuration#pipeline_stages" >}}) instead. ### Upgrading schema to use boltdb-shipper and/or v11 schema @@ -958,7 +961,7 @@ schema_config: ④ Make sure this matches your existing config (e.g. maybe you were using gcs for your object_store) ⑤ 24h is required for boltdb-shipper -There are more examples on the [Storage description page]({{< relref "../storage/_index.md#examples" >}}) including the information you need to setup the `storage` section for boltdb-shipper. +There are more examples on the [Storage description page]({{< relref "../../storage/_index.md#examples" >}}) including the information you need to setup the `storage` section for boltdb-shipper. ## 1.6.0 @@ -1248,7 +1251,7 @@ max_retries: Loki 1.4.0 vendors Cortex v0.7.0-rc.0 which contains [several breaking config changes](https://github.com/cortexproject/cortex/blob/v0.7.0-rc.0/CHANGELOG). -In the [cache_config]({{< relref "../configure#cache_config" >}}), `defaul_validity` has changed to `default_validity`. +In the [cache_config]({{< relref "../../configure#cache_config" >}}), `defaul_validity` has changed to `default_validity`. If you configured your schema via arguments and not a config file, this is no longer supported. This is not something we had ever provided as an option via docs and is unlikely anyone is doing, but worth mentioning. diff --git a/docs/sources/installation/helm/upgrade-from-2.x/index.md b/docs/sources/setup/upgrade/upgrade-from-2x/index.md similarity index 97% rename from docs/sources/installation/helm/upgrade-from-2.x/index.md rename to docs/sources/setup/upgrade/upgrade-from-2x/index.md index a762f595c83c..7979c5018afe 100644 --- a/docs/sources/installation/helm/upgrade-from-2.x/index.md +++ b/docs/sources/setup/upgrade/upgrade-from-2x/index.md @@ -3,7 +3,8 @@ title: Upgrade the Helm chart to 3.0 menuTitle: Upgrade the Helm chart to 3.0 description: Upgrade the Helm chart from 2.x to 3.0. aliases: - - /docs/installation/helm/upgrade + - ../installation/helm/upgrade + - ../../installation/helm/upgrade-from-2.x/ weight: 800 keywords: - upgrade diff --git a/production/helm/loki/reference.md.gotmpl b/production/helm/loki/reference.md.gotmpl index 467956ffc3e4..0efc492767c2 100644 --- a/production/helm/loki/reference.md.gotmpl +++ b/production/helm/loki/reference.md.gotmpl @@ -2,7 +2,9 @@ title: Helm Chart Values menuTitle: Helm chart values description: Reference for Helm Chart values. -weight: 200 +aliases: + - ../../../installation/helm/reference/ +weight: 500 keywords: [] ---