Add page for updated PCR upgrade info #20729
Conversation
Added new page on the upgrade process with pcr enabled, including more detailed and accurate info than we had previously
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
Files changed:
|
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
Fixed summary to be the right length
|
Changes to 25.4 aren't in this PR yet, but will be added as identical to 25.3 once the changes are finalized- easier to make adjustments in just the one version |
A few small adjustments based on tech review
Removed cloud only components and adjusting steps to match source of truth doc
| DROP VIRTUAL CLUSTER <readervc-name> | ||
| ~~~ | ||
|
|
||
| 1. Back on the standby cluster, if the version is as expected, re-create the ReaderVC: |
There was a problem hiding this comment.
What does 'as expected mean?' and what version will the ReaderVC be on once this sql statement is added? will it be the same version as the standby?
| When [**physical cluster replication (PCR)**]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}) is enabled, you must use the process on this page to upgrade your clusters. This process ensures that the standby cluster upgrades before the primary cluster. | ||
|
|
||
| {{site.data.alerts.callout_info}} | ||
| The entire standby cluster must be on the same version as the primary cluster or a version the primary cluster can directly upgrade to. Within the primary and standby CockroachDB clusters, the _system virtual cluster (SystemVC)_ must be at a cluster version greater than or equal to the _app virtual cluster (AppVC)_. |
There was a problem hiding this comment.
nit: perhaps link to a page that talks about version skipping etc.
| docs_area: manage | ||
| --- | ||
|
|
||
| When [**physical cluster replication (PCR)**]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}) is enabled, you must use the process on this page to upgrade your clusters. This process ensures that the standby cluster upgrades before the primary cluster. |
There was a problem hiding this comment.
Should we say 'That standby cluster safely upgrades before the primary cluster, preventing any version incompatibility'
| When [**physical cluster replication (PCR)**]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}) is enabled, you must use the process on this page to upgrade your clusters. This process ensures that the standby cluster upgrades before the primary cluster. | ||
|
|
||
| {{site.data.alerts.callout_info}} | ||
| The entire standby cluster must be on the same version as the primary cluster or a version the primary cluster can directly upgrade to. Within the primary and standby CockroachDB clusters, the _system virtual cluster (SystemVC)_ must be at a cluster version greater than or equal to the _app virtual cluster (AppVC)_. |
There was a problem hiding this comment.
Can we specify **major ** version?
Also, when you say 'version the primary cluster can directly upgrade to,' i assume you're implying that innovation releases can be skipped? i.e. PCR set up could be going from 25.4 (primary) --> 26.2 (standby), skipping 26.1 which is the primary release? I think we should be explicit, or link to a section of the docs that are explicit about it . Ideally we could just link to docs that are more explicit on it
There was a problem hiding this comment.
https://www.cockroachlabs.com/docs/stable/upgrade-cockroach-version ok found them, we shojld link to these docs
| 1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary cluster's SystemVC. | ||
|
|
||
| {{site.data.alerts.callout_info}} | ||
| If you need to [roll back]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#roll-back-a-major-version-upgrade) an upgrade, you must do so before the upgrade has been finalized. Rolling back the upgrade on the primary cluster does not also roll back the standby cluster. |
There was a problem hiding this comment.
for readability should we say "primary cluster does not roll backup" instead of "does not also"
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ sql | ||
| ALTER VIRTUAL CLUSTER <readervc-name> STOP SERVICE |
There was a problem hiding this comment.
nit: these are SQL statements and should have semicolons at the end, users will often copy and paste
so ALTER VIRTUAL CLUSTER STOP SERVICE; is what it should be
There was a problem hiding this comment.
^imho the sql command should still contain <readervc-name>
There was a problem hiding this comment.
oh yeah sorry, that was a copy and paste issue. my main point was we need to add a semicolon at the end of every sql statement code example.
| If you need to [roll back]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#roll-back-a-major-version-upgrade) an upgrade, you must do so before the upgrade has been finalized. | ||
| {{site.data.alerts.end}} | ||
|
|
||
| After you have finalized the upgrade on the standby cluster's SystemVC, the clusters can remain in this state for an indefinite amount of time. You can wait to upgrade the primary cluster as long as is needed. |
There was a problem hiding this comment.
hm, I'm not super clear what the use case for this is. I'm fine removing this line. I don't know why someone would be in this state
|
|
||
| ## Upgrade ReaderVC | ||
|
|
||
| If you have a [_reader virtual cluster (ReaderVC)_]({% link {{ page.version.version }}/read-from-standby.md %}), use the following steps to upgrade it by dropping and re-creating it: |
There was a problem hiding this comment.
I think we should be more explicit and add somewhere that 'the reader vc must be handled independently' from the upgrade process or something. And then also add a link to this section from the Reader VC page.
There was a problem hiding this comment.
^good point. the reader vc should be handled after the main upgrade process.
| DROP VIRTUAL CLUSTER <readervc-name> | ||
| ~~~ | ||
|
|
||
| 1. Back on the standby cluster, if the version is as expected, re-create the ReaderVC: |
There was a problem hiding this comment.
What does 'as expected mean?' and what version will the ReaderVC be on once this sql statement is added? will it be the same version as the standby?
|
|
||
| ## Failover and fast failback during upgrade | ||
|
|
||
| If you need to perform a [failover]({% link {{ page.version.version }}/failover-replication.md %}) while upgrading your clusters, you can do that using the normal process. |
There was a problem hiding this comment.
Wait what is this normal process referring to? The normal upgrade process?
|
|
||
| If you need to perform a [failover]({% link {{ page.version.version }}/failover-replication.md %}) while upgrading your clusters, you can do that using the normal process. | ||
|
|
||
| However, after performing a failover you cannot perform a [fast failback]({% link {{ page.version.version }}/failover-replication.md %}#failback) to the original primary cluster during the upgrade process. This is because at times during the upgrade the standby cluster is ahead of the primary cluster. |
There was a problem hiding this comment.
I think instead of this, we should say that you cannot perform fast failback under conditions that the standby cluster may be a version ahead of the primary cluster, making it incompatible because we would be replicating data from a cluster that is a version ahead back into a cluster that is a version behind (didn't phrase that very well but the core tenent of version compatibility is that we can't replicate data from a new version into an old version, bc the old versions doesn't know the new version exists)
Then we can list out the conditions:
- Upgrade process
- Process where the standby cluster version is higher than the primary
Not super opinionated on the layout, but i think we should be explicit on the version incompatibility issue with fast failback
3 participants
Addresses: DOC-15034 and DOC-14967
Added new page on the upgrade process with pcr enabled, including more detailed and accurate info than we had previously.