docs: Update variable formatting (#19610) (#19627)

Author: JStickler

docs/sources/alert/_index.md

@@ -304,16 +304,16 @@ The [Cortex rules action](https://github.com/grafana/cortex-rules-action) introd
   uses: grafana/cortex-rules-action@master
   env:
     ACTION: check
-    RULES_DIR: <source_dir_of_rules> # Example: logs/recording_rules/,logs/alerts/
+    RULES_DIR: <SOURCE_DIR_OF_RULES> # Example: logs/recording_rules/,logs/alerts/
     BACKEND: loki
 
 - name: Deploy rules to Loki staging
   uses: grafana/cortex-rules-action@master
   env:
-    CORTEX_ADDRESS: <loki_ingress_addr>
+    CORTEX_ADDRESS: <LOKI_INGRESS_ADDR>
     CORTEX_TENANT_ID: fake
     ACTION: sync
-    RULES_DIR: <source_dir_of_rules> # Example: logs/recording_rules/,logs/alerts/
+    RULES_DIR: <SOURCE_DIR_OF_RULES> # Example: logs/recording_rules/,logs/alerts/
     BACKEND: loki
 ```
 
@@ -327,7 +327,7 @@ A full sharding-enabled Ruler example is:
 
 ```yaml
 ruler:
-  alertmanager_url: <alertmanager_endpoint>
+  alertmanager_url: <ALERTMANAGER_ENDPOINT>
   enable_alertmanager_v2: true # true by default since Loki 3.2.0
   enable_api: true
   enable_sharding: true
@@ -339,7 +339,7 @@ ruler:
   rule_path: /tmp/rules
   storage:
     gcs:
-      bucket_name: <loki-rules-bucket>
+      bucket_name: <LOKI_RULES_BUCKET>
 ```
 
 ## Ruler storage

docs/sources/community/maintaining/release/patch-vulnerabilities.md

@@ -43,7 +43,7 @@ Before start patching vulnerabilities, know what are you patching. It can be one
 	1. Check if [dependabot already patched the dependency](https://github.com/grafana/loki/pulls?q=is%3Apr+label%3Adependencies+is%3Aclosed) or [have a PR opened to patch](https://github.com/grafana/loki/pulls?q=is%3Apr+is%3Aopen+label%3Adependencies) . If not, manually upgrade the package on the `main` branch as follows.
 
 		```shell
-		go get -u -v <package-path>@<patched-version>
+		go get -u -v <PACKAGE_PATH>@<PATCHED_VERSION>
 		go mod tidy
 		go mod vendor
 		```

docs/sources/reference/loki-http-api.md

@@ -275,7 +275,7 @@ For information on how to configure Loki, refer to the [OTel Collector topic](ht
 
 <!-- vale Google.Will = NO -->
 {{< admonition type="note" >}}
-When configuring the OpenTelemetry Collector, you must use `endpoint: http://<loki-addr>/otlp`, as the collector automatically completes the endpoint.  Entering the full endpoint will generate an error.
+When configuring the OpenTelemetry Collector, you must use `endpoint: http://<LOKI_ADDR>/otlp`, as the collector automatically completes the endpoint.  Entering the full endpoint will generate an error.
 {{< /admonition >}}
 <!-- vale Google.Will = YES -->
 
@@ -451,7 +451,7 @@ To query against your hosted log tenant in Grafana Cloud, use the **User** and *
 
 ```bash
 curl -u "User:$API_TOKEN" \
-  -G -s "<URL-PROVIDED-IN-LOKI-DATA-SOURCE-SETTINGS>/loki/api/v1/query" \
+  -G -s "<URL_PROVIDED_IN_LOKI_DATA_SOURCE_SETTINGS>/loki/api/v1/query" \
   --data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq
 ```
 
@@ -1440,16 +1440,16 @@ Example cURL command:
 
 ```bash
 curl -X GET \
-  <compactor_addr>/loki/api/v1/delete \
-  -H 'X-Scope-OrgID: <orgid>'
+  <COMPACTOR_ADDR>/loki/api/v1/delete \
+  -H 'X-Scope-OrgID: <ORG_ID>'
 ```
 
 The same example deletion request for Grafana Enterprise Logs uses Basic Authentication and specifies the tenant name as a user; `Tenant1` is the tenant name in this example. The password in this example is an access policy token that has been defined in the API_TOKEN environment variable. The token must be for an access policy with `logs:delete` scope for the tenant specified in the user field.
 
 ```bash
 curl -u "Tenant1:$API_TOKEN" \
   -X GET \
-  <compactor_addr>/loki/api/v1/delete
+  <COMPACTOR_ADDR>/loki/api/v1/delete
 ```
 
 ### Request cancellation of a delete request
@@ -1487,16 +1487,16 @@ Example cURL command:
 
 ```bash
 curl -X DELETE \
-  '<compactor_addr>/loki/api/v1/delete?request_id=<request_id>' \
-  -H 'X-Scope-OrgID: <tenant-id>'
+  '<COMPACTOR_ADDR>/loki/api/v1/delete?request_id=<REQUEST_ID>' \
+  -H 'X-Scope-OrgID: <TENANT_ID>'
 ```
 
 The same example deletion cancellation request for Grafana Enterprise Logs uses Basic Authentication and specifies the tenant name as a user; `Tenant1` is the tenant name in this example. The password in this example is an access policy token that has been defined in the API_TOKEN environment variable. The token must be for an access policy with `logs:delete` scope for the tenant specified in the user field.
 
 ```bash
 curl -u "Tenant1:$API_TOKEN" \
   -X DELETE \
-  '<compactor_addr>/loki/api/v1/delete?request_id=<request_id>'
+  '<COMPACTOR_ADDR>/loki/api/v1/delete?request_id=<REQUEST_ID>'
 ```
 
 ## Format a LogQL query

docs/sources/setup/install/helm/deployment-guides/aws.md

@@ -61,8 +61,8 @@ apiVersion: eksctl.io/v1alpha5
 kind: ClusterConfig
 
 metadata:
-  name: <INSERT-CLUSTER-NAME>
-  region: <INSERT-REGION-FOR-CLUSTER>
+  name: <INSERT_CLUSTER_NAME>
+  region: <INSERT_REGION_FOR_CLUSTER>
   version: "1.31"
 
 iam:

docs/sources/setup/install/helm/install-scalable/_index.md

@@ -148,15 +148,15 @@ loki:
       # s3 URL can be used to specify the endpoint, access key, secret key, and bucket name this works well for S3 compatible storages or if you are hosting Loki on-premises and want to use S3 as the storage backend. Either use the s3 URL or the individual fields below (AWS endpoint, region, secret).
       s3: s3://access_key:secret_access_key@custom_endpoint/bucket_name
       # AWS endpoint URL
-      endpoint: <your-endpoint>
+      endpoint: <YOUR_ENDPOINT>
       # AWS region where the S3 bucket is located
-      region: <your-region>
+      region: <YOUR_REGION>
       # AWS secret access key
-      secretAccessKey: <your-secret-access-key>
+      secretAccessKey: <YOUR_SECRET_ACCESS_KEY>
       # AWS access key ID
-      accessKeyId: <your-access-key-id>
+      accessKeyId: <YOUR_ACCESS_KEY_ID>
       # AWS signature version (e.g., v2 or v4)
-      signatureVersion: <your-signature-version>
+      signatureVersion: <YOUR_SIGNATURE_VERSION>
       # Forces the path style for S3 (true/false)
       s3ForcePathStyle: false
       # Allows insecure (HTTP) connections (true/false)
@@ -205,21 +205,21 @@ loki:
     type: azure
     azure:
       # Name of the Azure Blob Storage account
-      accountName: <your-account-name>
+      accountName: <YOUR_ACCOUNT_NAME>
       # Key associated with the Azure Blob Storage account
-      accountKey: <your-account-key>
+      accountKey: <YOUR_ACCOUNT_KEY>
       # Comprehensive connection string for Azure Blob Storage account (Can be used to replace endpoint, accountName, and accountKey)
-      connectionString: <your-connection-string>
+      connectionString: <YOUR_CONNECTION_STRING>
       # Flag indicating whether to use Azure Managed Identity for authentication
       useManagedIdentity: false
       # Flag indicating whether to use a federated token for authentication
       useFederatedToken: false
       # Client ID of the user-assigned managed identity (if applicable)
-      userAssignedId: <your-user-assigned-id>
+      userAssignedId: <YOUR_USER_ASSIGNED_ID>
       # Timeout duration for requests made to the Azure Blob Storage account (in seconds)
-      requestTimeout: <your-request-timeout>
+      requestTimeout: <YOUR_REQUEST_TIMEOUT>
       # Domain suffix of the Azure Blob Storage service endpoint (e.g., core.windows.net)
-      endpointSuffix: <your-endpoint-suffix>
+      endpointSuffix: <YOUR_ENDPOINT_SUFFIX>
     bucketNames:
       chunks: "chunks"
       ruler: "ruler"

docs/sources/setup/upgrade/upgrade-to-6x/index.md

@@ -84,6 +84,85 @@ resultsCache:
 
 With these caches disabled, Loki will return to defaults which enables an in-memory results and chunks cache, so you will still get some caching.
 
+#### BREAKING: Zone-aware ingester StatefulSet serviceName fix (6.34.0+)
+
+**Affected users**: Only deployments using zone-aware ingester replication (`ingester.zoneAwareReplication.enabled: true`)
+
+In Helm chart version 6.34.0, [PR #18558](https://github.com/grafana/loki/pull/18558) fixed the `serviceName` field in zone-aware ingester StatefulSets to correctly reference headless services. However, since `serviceName` is an immutable field in Kubernetes StatefulSets, upgrading to 6.34.0 requires manual intervention.
+
+**Required action before upgrading to 6.34.0**:
+
+1. **Check if you're affected**:
+
+   ```bash
+   helm get values <RELEASE_NAME> | grep -A5 zoneAwareReplication
+   ```
+
+   If `enabled: true` appears, you need to follow these steps.
+
+2. **Delete the StatefulSets** (data will be preserved):
+
+   ```bash
+   kubectl delete statefulset \
+     <RELEASE_NAME>-ingester-zone-a \
+     <RELEASE_NAME>-ingester-zone-b \
+     <RELEASE_NAME>-ingester-zone-c \
+     --cascade=orphan
+   ```
+
+3. **Proceed with the Helm upgrade**:
+
+   ```bash
+   helm upgrade <RELEASE_NAME> grafana/loki --version 6.34.0
+   ```
+
+**What happens**:
+
+- PersistentVolumeClaims and data are preserved
+- New StatefulSets will be created with correct service references
+- Pods will restart and reattach to existing storage
+
+**Why this change was necessary**:
+The previous configuration caused ingester scaling operations to fail because the rollout-operator couldn't find the correct headless services for the `/ingester/prepare-downscale` endpoint.
+
+#### BREAKING: Make access modes for persistence on all PVCs and StatefulSets editable (6.38.0+)
+
+Version 6.38.0 of the Helm charts introduced the ability to edit the access modes for persistence on all PVCs and StatefulSets. This is a breaking change because it requires users to manually orphan StatefulSets before upgrading.
+
+**Required action before upgrading to 6.38.0**:
+
+1. **Delete the StatefulSets** (delete only the ones that exist in your deployment):
+
+   ```bash
+   # Core components (SimpleScalable mode)
+   kubectl delete statefulset <RELEASE_NAME>-write --cascade=orphan
+   kubectl delete statefulset <RELEASE_NAME>-backend --cascade=orphan
+   
+   # Single binary mode
+   kubectl delete statefulset <RELEASE_NAME> --cascade=orphan
+   
+   # Distributed mode components
+   kubectl delete statefulset <RELEASE_NAME>-ingester --cascade=orphan
+
+   # Zone-aware ingester (if zoneAwareReplication.enabled is true)
+   kubectl delete statefulset <RELEASE_NAME>-ingester-zone-a --cascade=orphan
+   kubectl delete statefulset <RELEASE_NAME>-ingester-zone-b --cascade=orphan
+   kubectl delete statefulset <RELEASE_NAME>-ingester-zone-c --cascade=orphan
+
+   kubectl delete statefulset <RELEASE_NAME>-index-gateway --cascade=orphan
+   kubectl delete statefulset <RELEASE_NAME>-compactor --cascade=orphan
+   kubectl delete statefulset <RELEASE_NAME>-ruler --cascade=orphan
+   kubectl delete statefulset <RELEASE_NAME>-pattern-ingester --cascade=orphan
+   kubectl delete statefulset <RELEASE_NAME>-bloom-planner --cascade=orphan
+   kubectl delete statefulset <RELEASE_NAME>-bloom-gateway --cascade=orphan
+   ```
+
+2. **Proceed with the Helm upgrade**:
+
+   ```bash
+   helm upgrade <RELEASE_NAME> grafana/loki --version 6.38.0
+   ```
+
 #### Distributed mode
 
 This chart introduces the ability to run Loki in distributed, or [microservices mode](https://grafana.com/docs/loki/<LOKI_VERSION>/get-started/deployment-modes/#microservices-mode). Separate instructions on how to enable this as well as how to migrate from the existing community chart will be coming shortly.