From 11c6f434512b5b1aecf903318792831e047d2a0f Mon Sep 17 00:00:00 2001 From: Tom Hayward Date: Tue, 30 Nov 2021 10:19:06 -0800 Subject: [PATCH] add upgrade guide (#276) * order guides alphabetically * add upgrade guide --- docs/guides/configure_memcached.markdown | 1 - .../configure_rules_via_configmap.markdown | 1 - .../configure_rules_via_sidecar.markdown | 1 - ...etting_started_with_block_storage.markdown | 1 - docs/guides/memberlist.markdown | 1 - docs/guides/upgrade-v1.markdown | 111 ++++++++++++++++++ 6 files changed, 111 insertions(+), 5 deletions(-) create mode 100644 docs/guides/upgrade-v1.markdown diff --git a/docs/guides/configure_memcached.markdown b/docs/guides/configure_memcached.markdown index fd0b9552..e835c6e0 100644 --- a/docs/guides/configure_memcached.markdown +++ b/docs/guides/configure_memcached.markdown @@ -4,7 +4,6 @@ title: Configure memcached parent: Guides has_children: true has_toc: false -nav_order: 5 --- # Configuring memcached as the caching store diff --git a/docs/guides/configure_rules_via_configmap.markdown b/docs/guides/configure_rules_via_configmap.markdown index 478cadca..348d456e 100644 --- a/docs/guides/configure_rules_via_configmap.markdown +++ b/docs/guides/configure_rules_via_configmap.markdown @@ -4,7 +4,6 @@ title: Configure rules via configmap parent: Guides has_children: true has_toc: false -nav_order: 3 --- # Configure rules via configmap diff --git a/docs/guides/configure_rules_via_sidecar.markdown b/docs/guides/configure_rules_via_sidecar.markdown index 960e5cdd..e248751a 100644 --- a/docs/guides/configure_rules_via_sidecar.markdown +++ b/docs/guides/configure_rules_via_sidecar.markdown @@ -4,7 +4,6 @@ title: Configure rules via sidecar parent: Guides has_children: true has_toc: false -nav_order: 4 --- # Rules and AlertManager configuration Cortex can be configured to use a sidecar container in the Ruler and AlertManager to dynamically discover rules and AlertManager config/templates that are declared as ConfigMaps to allow easy and extensible configuration that avoids having to store state in the Cortex system itself (via config service, etc). diff --git a/docs/guides/getting_started_with_block_storage.markdown b/docs/guides/getting_started_with_block_storage.markdown index 10e026cc..008d0e76 100644 --- a/docs/guides/getting_started_with_block_storage.markdown +++ b/docs/guides/getting_started_with_block_storage.markdown @@ -4,7 +4,6 @@ title: Getting started with block storage parent: Guides has_children: true has_toc: false -nav_order: 1 --- # Getting Started diff --git a/docs/guides/memberlist.markdown b/docs/guides/memberlist.markdown index adab5bc4..e998b046 100644 --- a/docs/guides/memberlist.markdown +++ b/docs/guides/memberlist.markdown @@ -4,7 +4,6 @@ title: Memberlist parent: Guides has_children: true has_toc: false -nav_order: 2 --- # Setup diff --git a/docs/guides/upgrade-v1.markdown b/docs/guides/upgrade-v1.markdown new file mode 100644 index 00000000..f6bc0831 --- /dev/null +++ b/docs/guides/upgrade-v1.markdown @@ -0,0 +1,111 @@ +--- +layout: page +title: Upgrading to chart version v1.0.0 +parent: Guides +has_children: false +has_toc: true +--- +# Upgrading to chart version v1.0.0 + +cortex-helm-chart v1.0.0 introduced a number of breaking changes in an attempt to provide better defaults for new users. Care should be taken when upgrading so that the new defaults are not inherited unexpectedly. Many of the new defaults are safe and simple to apply with an upgrade, but some require special procedures to migrate to, and some may not match your desired configuration. + +This guide covers a few topics, but is not exhaustive. Please review the [release notes](https://github.com/cortexproject/cortex-helm-chart/releases/tag/v1.0.0) and [diff](https://github.com/cortexproject/cortex-helm-chart/compare/v0.6.0...v1.0.0) before upgrading to ensure you haven't missed anything important to your installation. You may want to use a tool like [helm-diff](https://github.com/databus23/helm-diff) to see what changes will be applied. + +## Migrating to Memberlist + +The default kvstore changed from `consul` to `memberlist`. Migrating from one kvstore to another requires either downtime or a multi-stage process. + +### Downtime + +If you are okay with downtime, the simplest way to migrate kvstores is to scale down all cortex components, then `helm upgrade --reset-values` to cortex-helm-chart v1.x.x to apply the new default kvstore, `memberlist`. Keep in mind this will apply all the new defaults, so ensure any values you would like to preserve that are unrelated to the kvstore are overridden with `-f` and your custom values file or `--set`. + +### Multi KV + +Cortex provides a configuration called Multi KV to migrate from one kvstore to another without downtime. Please read the doc on Multi KV before continuing this guide: https://cortexmetrics.io/docs/configuration/arguments/#multi-kv + +Assuming you have an existing installation of cortex-helm-chart v0.6.0, here is an example of how to convert it to `memberlist`. +#### Stage 1 - mirror to both kvstores + +_Be sure to augment this command with any other options you used for the initial installation._ +``` +helm upgrade cortex cortex-helm/cortex --version 0.6.0 -f kvstore-mirror.yaml +``` + +kvstore-mirror.yaml: +```yaml +config: + alertmanager: + sharding_ring: + kvstore: &kvstore + store: multi + multi: + primary: consul + secondary: memberlist + mirror_enabled: true + compactor: + sharding_ring: + kvstore: *kvstore + distributor: + ring: + kvstore: *kvstore + ingester: + lifecycler: + ring: + kvstore: *kvstore + ring: + kvstore: *kvstore + store_gateway: + sharding_ring: + kvstore: *kvstore +``` + +#### Stage 2 - use runtime config to make memberlist the primary + +_Be sure to augment this command with any other options you used for the initial installation._ +``` +helm upgrade cortex cortex-helm/cortex --version 0.6.0 -f kvstore-mirror.yaml -f kvstore-runtime.yaml +``` + +kvstore-runtime.yaml: +```yaml +runtimeconfigmap: + runtime_config: + multi_kv_config: + mirror_enabled: false + primary: memberlist +``` + +#### Stage 3 - disable consul + +_Be sure to augment this command with any other options you used for the initial installation._ +``` +helm upgrade cortex cortex-helm/cortex --version 0.6.0 -f kvstore-memberlist.yaml +``` + +kvstore-memberlist.yaml: +```yaml +config: + alertmanager: + sharding_ring: + kvstore: &kvstore + store: memberlist + compactor: + sharding_ring: + kvstore: *kvstore + distributor: + ring: + kvstore: *kvstore + ingester: + lifecycler: + ring: + kvstore: *kvstore + ring: + kvstore: *kvstore + store_gateway: + sharding_ring: + kvstore: *kvstore +``` + +## Migrate from chucks to block storage + +https://cortexmetrics.io/docs/blocks-storage/migrate-cortex-cluster-from-chunks-to-blocks/