diff --git a/Makefile b/Makefile index b7af47e439..2ef80687e7 100644 --- a/Makefile +++ b/Makefile @@ -786,33 +786,34 @@ check-doc: doc ################### # Example Configs # ################### -CONFIG_DOC_PATH := $(DOC_SOURCES_PATH)/configure -CONFIG_EXAMPLES_PATH := $(CONFIG_DOC_PATH)/examples -CONFIG_EXAMPLES_SKIP_VALIDATION_FLAG := "doc-example:skip-validation=true" +EXAMPLES_DOC_PATH := $(DOC_SOURCES_PATH)/configure/examples +EXAMPLES_DOC_OUTPUT_PATH := $(EXAMPLES_DOC_PATH)/configuration-examples.md +EXAMPLES_YAML_PATH := $(EXAMPLES_DOC_PATH)/yaml +EXAMPLES_SKIP_VALIDATION_FLAG := "doc-example:skip-validation=true" # Validate the example configurations that we provide in ./docs/sources/configure/examples # We run the validation only for complete examples, not snippets. # Complete examples should contain "Example" in their file name. validate-example-configs: loki - for f in $$(grep -rL $(CONFIG_EXAMPLES_SKIP_VALIDATION_FLAG) $(CONFIG_EXAMPLES_PATH)/*.yaml); do echo "Validating provided example config: $$f" && ./cmd/loki/loki -config.file=$$f -verify-config || exit 1; done + for f in $$(grep -rL $(EXAMPLES_SKIP_VALIDATION_FLAG) $(EXAMPLES_YAML_PATH)/*.yaml); do echo "Validating provided example config: $$f" && ./cmd/loki/loki -config.file=$$f -verify-config || exit 1; done # Dynamically generate ./docs/sources/configure/examples.md using the example configs that we provide. # This target should be run if any of our example configs change. generate-example-config-doc: - echo "Removing existing doc at $(CONFIG_DOC_PATH)/examples.md and re-generating. . ." + echo "Removing existing doc at $(EXAMPLES_DOC_OUTPUT_PATH) and re-generating. . ." # Title and Heading - echo -e "---\ntitle: Examples\ndescription: Loki Configuration Examples\n---\n # Examples" > $(CONFIG_DOC_PATH)/examples.md + echo -e "---\ntitle: Configuration\ndescription: Loki Configuration Examples and Snippets\nweight: 100\n---\n# Configuration" > $(EXAMPLES_DOC_OUTPUT_PATH) # Append each configuration and its file name to examples.md - for f in $$(find $(CONFIG_EXAMPLES_PATH)/*.yaml -printf "%f\n" | sort -k1n); do \ - echo -e "\n## $$f\n\n\`\`\`yaml\n" >> $(CONFIG_DOC_PATH)/examples.md; \ - grep -v $(CONFIG_EXAMPLES_SKIP_VALIDATION_FLAG) $(CONFIG_EXAMPLES_PATH)/$$f >> $(CONFIG_DOC_PATH)/examples.md; \ - echo -e "\n\`\`\`\n" >> $(CONFIG_DOC_PATH)/examples.md; \ + for f in $$(find $(EXAMPLES_YAML_PATH)/*.yaml -printf "%f\n" | sort -k1n); do \ + echo -e "\n## $$f\n\n\`\`\`yaml\n" >> $(EXAMPLES_DOC_OUTPUT_PATH); \ + grep -v $(EXAMPLES_SKIP_VALIDATION_FLAG) $(EXAMPLES_YAML_PATH)/$$f >> $(EXAMPLES_DOC_OUTPUT_PATH); \ + echo -e "\n\`\`\`\n" >> $(EXAMPLES_DOC_OUTPUT_PATH); \ done # Fail our CI build if changes are made to example configurations but our doc is not updated check-example-config-doc: generate-example-config-doc - @if ! (git diff --exit-code ./docs/sources/configure/examples.md); then \ + @if ! (git diff --exit-code $(EXAMPLES_DOC_OUTPUT_PATH)); then \ echo -e "\nChanges found in generated example configuration doc"; \ echo "Run 'make generate-example-config-doc' and commit the changes to fix this error."; \ echo "If you are actively developing these files you can ignore this error"; \ diff --git a/docs/sources/configure/_index.md b/docs/sources/configure/_index.md index 9868a58e38..58fc91867c 100644 --- a/docs/sources/configure/_index.md +++ b/docs/sources/configure/_index.md @@ -15,7 +15,7 @@ Grafana Loki is configured in a YAML file (usually referred to as `loki.yaml` ) which contains information on the Loki server and its individual components, depending on which mode Loki is launched in. -Configuration examples can be found in the [Configuration Examples]({{< relref "./examples" >}}) document. +Configuration examples can be found in the [Configuration Examples]({{< relref "./examples/configuration-examples" >}}) document. ## Printing Loki config at runtime diff --git a/docs/sources/configure/examples/_index.md b/docs/sources/configure/examples/_index.md new file mode 100644 index 0000000000..96a00ec3d0 --- /dev/null +++ b/docs/sources/configure/examples/_index.md @@ -0,0 +1,13 @@ +--- +title: Examples +menuTitle: Examples +description: Examples to help you run Grafana Loki. +weight: 800 +--- + +# Examples + +The following pages contain examples of how to configure Grafana Loki. + +- [Configuration snippets and ready-to-use configuration examples]({{< relref "./configuration-examples" >}}). +- [Deploy a query frontend on a existing cluster]({{< relref "./query-frontend" >}}). \ No newline at end of file diff --git a/docs/sources/configure/examples.md b/docs/sources/configure/examples/configuration-examples.md similarity index 98% rename from docs/sources/configure/examples.md rename to docs/sources/configure/examples/configuration-examples.md index d26469b938..c449e1e519 100644 --- a/docs/sources/configure/examples.md +++ b/docs/sources/configure/examples/configuration-examples.md @@ -1,8 +1,9 @@ --- -title: Examples -description: Loki Configuration Examples +title: Configuration +description: Loki Configuration Examples and Snippets +weight: 100 --- - # Examples +# Configuration ## 1-Local-Configuration-Example.yaml diff --git a/docs/sources/configure/query-frontend.md b/docs/sources/configure/examples/query-frontend.md similarity index 97% rename from docs/sources/configure/query-frontend.md rename to docs/sources/configure/examples/query-frontend.md index a10454aed2..af81104898 100644 --- a/docs/sources/configure/query-frontend.md +++ b/docs/sources/configure/examples/query-frontend.md @@ -1,10 +1,7 @@ --- title: Query frontend example menuTitle: -description: Kubernetes query frontent example. -aliases: - - ../configuration/query-frontend/ - - ../configure/query-frontend/ +description: Kubernetes query frontend example. weight: 200 --- # Query frontend example diff --git a/docs/sources/configure/examples/1-Local-Configuration-Example.yaml b/docs/sources/configure/examples/yaml/1-Local-Configuration-Example.yaml similarity index 100% rename from docs/sources/configure/examples/1-Local-Configuration-Example.yaml rename to docs/sources/configure/examples/yaml/1-Local-Configuration-Example.yaml diff --git a/docs/sources/configure/examples/10-Expanded-S3-Snippet.yaml b/docs/sources/configure/examples/yaml/10-Expanded-S3-Snippet.yaml similarity index 100% rename from docs/sources/configure/examples/10-Expanded-S3-Snippet.yaml rename to docs/sources/configure/examples/yaml/10-Expanded-S3-Snippet.yaml diff --git a/docs/sources/configure/examples/11-COS-HMAC-Example.yaml b/docs/sources/configure/examples/yaml/11-COS-HMAC-Example.yaml similarity index 100% rename from docs/sources/configure/examples/11-COS-HMAC-Example.yaml rename to docs/sources/configure/examples/yaml/11-COS-HMAC-Example.yaml diff --git a/docs/sources/configure/examples/12-COS-APIKey-Example.yaml b/docs/sources/configure/examples/yaml/12-COS-APIKey-Example.yaml similarity index 100% rename from docs/sources/configure/examples/12-COS-APIKey-Example.yaml rename to docs/sources/configure/examples/yaml/12-COS-APIKey-Example.yaml diff --git a/docs/sources/configure/examples/13-COS-Trusted-Profile-Example.yaml b/docs/sources/configure/examples/yaml/13-COS-Trusted-Profile-Example.yaml similarity index 100% rename from docs/sources/configure/examples/13-COS-Trusted-Profile-Example.yaml rename to docs/sources/configure/examples/yaml/13-COS-Trusted-Profile-Example.yaml diff --git a/docs/sources/configure/examples/15-Memberlist-Ring-Snippet.yaml b/docs/sources/configure/examples/yaml/15-Memberlist-Ring-Snippet.yaml similarity index 100% rename from docs/sources/configure/examples/15-Memberlist-Ring-Snippet.yaml rename to docs/sources/configure/examples/yaml/15-Memberlist-Ring-Snippet.yaml diff --git a/docs/sources/configure/examples/16-(Deprecated)-Cassandra-Snippet.yaml b/docs/sources/configure/examples/yaml/16-(Deprecated)-Cassandra-Snippet.yaml similarity index 100% rename from docs/sources/configure/examples/16-(Deprecated)-Cassandra-Snippet.yaml rename to docs/sources/configure/examples/yaml/16-(Deprecated)-Cassandra-Snippet.yaml diff --git a/docs/sources/configure/examples/17-(Deprecated)-S3-And-DynamoDB-Snippet.yaml b/docs/sources/configure/examples/yaml/17-(Deprecated)-S3-And-DynamoDB-Snippet.yaml similarity index 100% rename from docs/sources/configure/examples/17-(Deprecated)-S3-And-DynamoDB-Snippet.yaml rename to docs/sources/configure/examples/yaml/17-(Deprecated)-S3-And-DynamoDB-Snippet.yaml diff --git a/docs/sources/configure/examples/2-S3-Cluster-Example.yaml b/docs/sources/configure/examples/yaml/2-S3-Cluster-Example.yaml similarity index 100% rename from docs/sources/configure/examples/2-S3-Cluster-Example.yaml rename to docs/sources/configure/examples/yaml/2-S3-Cluster-Example.yaml diff --git a/docs/sources/configure/examples/3-S3-Without-Credentials-Snippet.yaml b/docs/sources/configure/examples/yaml/3-S3-Without-Credentials-Snippet.yaml similarity index 100% rename from docs/sources/configure/examples/3-S3-Without-Credentials-Snippet.yaml rename to docs/sources/configure/examples/yaml/3-S3-Without-Credentials-Snippet.yaml diff --git a/docs/sources/configure/examples/4-GCS-Example.yaml b/docs/sources/configure/examples/yaml/4-GCS-Example.yaml similarity index 100% rename from docs/sources/configure/examples/4-GCS-Example.yaml rename to docs/sources/configure/examples/yaml/4-GCS-Example.yaml diff --git a/docs/sources/configure/examples/5-BOS-Example.yaml b/docs/sources/configure/examples/yaml/5-BOS-Example.yaml similarity index 100% rename from docs/sources/configure/examples/5-BOS-Example.yaml rename to docs/sources/configure/examples/yaml/5-BOS-Example.yaml diff --git a/docs/sources/configure/examples/6-Compactor-Snippet.yaml b/docs/sources/configure/examples/yaml/6-Compactor-Snippet.yaml similarity index 100% rename from docs/sources/configure/examples/6-Compactor-Snippet.yaml rename to docs/sources/configure/examples/yaml/6-Compactor-Snippet.yaml diff --git a/docs/sources/configure/examples/7-Schema-Migration-Snippet.yaml b/docs/sources/configure/examples/yaml/7-Schema-Migration-Snippet.yaml similarity index 100% rename from docs/sources/configure/examples/7-Schema-Migration-Snippet.yaml rename to docs/sources/configure/examples/yaml/7-Schema-Migration-Snippet.yaml diff --git a/docs/sources/configure/examples/8-alibaba-cloud-storage-Snippet.yaml b/docs/sources/configure/examples/yaml/8-alibaba-cloud-storage-Snippet.yaml similarity index 100% rename from docs/sources/configure/examples/8-alibaba-cloud-storage-Snippet.yaml rename to docs/sources/configure/examples/yaml/8-alibaba-cloud-storage-Snippet.yaml diff --git a/docs/sources/configure/examples/9-S3-With-SSE-KMS-Snippet.yaml b/docs/sources/configure/examples/yaml/9-S3-With-SSE-KMS-Snippet.yaml similarity index 100% rename from docs/sources/configure/examples/9-S3-With-SSE-KMS-Snippet.yaml rename to docs/sources/configure/examples/yaml/9-S3-With-SSE-KMS-Snippet.yaml diff --git a/docs/sources/configure/examples/README.txt b/docs/sources/configure/examples/yaml/README.txt similarity index 100% rename from docs/sources/configure/examples/README.txt rename to docs/sources/configure/examples/yaml/README.txt diff --git a/docs/sources/configure/index.template b/docs/sources/configure/index.template index e46dbaec49..91bd7ab699 100644 --- a/docs/sources/configure/index.template +++ b/docs/sources/configure/index.template @@ -15,7 +15,7 @@ Grafana Loki is configured in a YAML file (usually referred to as `loki.yaml` ) which contains information on the Loki server and its individual components, depending on which mode Loki is launched in. -Configuration examples can be found in the [Configuration Examples]({{ `{{< relref "./examples" >}}` }}) document. +Configuration examples can be found in the [Configuration Examples]({{ `{{< relref "./examples/configuration-examples" >}}` }}) document. ## Printing Loki config at runtime