From 19c9604630e81d66d7e6117841f8d43fdfdd3226 Mon Sep 17 00:00:00 2001 From: Casey Davenport Date: Thu, 23 Jul 2026 08:29:25 -0700 Subject: [PATCH 1/3] Add calicoctl datastore migrate-policy-names reference docs Documents the new command for the Next and v3.32 docs. OSS only for now, since the command has not merged to Calico Enterprise yet. --- .../datastore/migrate-policy-names.mdx | 74 ++++++++++++++++++ .../calicoctl/datastore/overview.mdx | 8 +- .../datastore/migrate-policy-names.mdx | 75 +++++++++++++++++++ .../calicoctl/datastore/overview.mdx | 8 +- .../version-3.32-sidebars.json | 3 +- sidebars-calico.js | 1 + 6 files changed, 162 insertions(+), 7 deletions(-) create mode 100644 calico/reference/calicoctl/datastore/migrate-policy-names.mdx create mode 100644 calico_versioned_docs/version-3.32/reference/calicoctl/datastore/migrate-policy-names.mdx diff --git a/calico/reference/calicoctl/datastore/migrate-policy-names.mdx b/calico/reference/calicoctl/datastore/migrate-policy-names.mdx new file mode 100644 index 0000000000..ea5569b6f9 --- /dev/null +++ b/calico/reference/calicoctl/datastore/migrate-policy-names.mdx @@ -0,0 +1,74 @@ +--- +description: Reference for the calicoctl datastore migrate-policy-names command in Calico Open Source, used to fix pre-v3.32 policy names on an upgraded etcdv3 datastore. +--- + +# calicoctl datastore migrate-policy-names + +This section describes the `calicoctl datastore migrate-policy-names` command. + +Read the [calicoctl Overview](../overview.mdx) +for a full list of calicoctl commands. + +:::note + +You only need this command on an etcdv3 datastore (for example, OpenStack) that +was created before v3.32 and upgraded in place. A Kubernetes datastore is +migrated automatically by kube-controllers, so no manual step is required there. + +::: + +## Display the help text for 'calicoctl datastore migrate-policy-names' command + +Run `calicoctl datastore migrate-policy-names --help` to display the following help menu for the +command. + +``` +Usage: + calicoctl datastore migrate-policy-names [--config=] [--allow-version-mismatch] + +Options: + -h --help Show this screen. + -c --config= Path to the file containing connection + configuration in YAML or JSON format. + [default: /etc/calico/calicoctl.cfg] + --allow-version-mismatch Allow client and cluster versions mismatch. + +Description: + Rewrite policy names in the datastore to drop the legacy "default." tier + prefix, aligning the stored name with the v3 resource name introduced in + v3.32. + + This is only needed for an etcdv3 datastore (for example OpenStack) that was + created before v3.32 and upgraded in place. A Kubernetes datastore is + migrated automatically by kube-controllers. The command is safe to re-run. +``` + +### Examples + +Rewrite any pre-v3.32 policy names in the datastore so they match their v3 names. + +```bash +calicoctl datastore migrate-policy-names +``` + +On completion, the command reports how many policies it rewrote. + +``` +Policy name migration complete, migrated 5 policies. +``` + +The command is idempotent. Running it again once every policy has already been +migrated reports `migrated 0 policies` and makes no changes. + +### General options + +``` +-c --config= Path to the file containing connection + configuration in YAML or JSON format. + [default: /etc/calico/calicoctl.cfg] +``` + +## See also + +- [Install calicoctl](../../../operations/calicoctl/install.mdx) +- [Upgrade Calico on OpenStack](../../../operations/upgrading/openstack-upgrade.mdx) for the full upgrade procedure that runs this command diff --git a/calico/reference/calicoctl/datastore/overview.mdx b/calico/reference/calicoctl/datastore/overview.mdx index 7490ae094f..8f24b6bda8 100644 --- a/calico/reference/calicoctl/datastore/overview.mdx +++ b/calico/reference/calicoctl/datastore/overview.mdx @@ -9,16 +9,17 @@ This section describes the `calicoctl datastore` commands. Read the [calicoctl Overview](../overview.mdx) for a full list of calicoctl commands. -## Display the help text for 'calicoctl datastore migrate' commands +## Display the help text for 'calicoctl datastore' commands -Run `calicoctl datastore migrate --help` to display the following help menu for the +Run `calicoctl datastore --help` to display the following help menu for the commands. ``` Usage: calicoctl datastore [...] - migrate Migrate the contents of an etcdv3 datastore to a Kubernetes datastore. + migrate Migrate the contents of an etcdv3 datastore to a Kubernetes datastore. + migrate-policy-names Rewrite pre-v3.32 policy names in an etcdv3 datastore to drop the tier prefix. Options: -h --help Show this screen. @@ -35,3 +36,4 @@ Details on the `calicoctl datastore` commands are described in the documents lin organized by sub command. - [calicoctl datastore migrate](migrate/overview.mdx) +- [calicoctl datastore migrate-policy-names](migrate-policy-names.mdx) diff --git a/calico_versioned_docs/version-3.32/reference/calicoctl/datastore/migrate-policy-names.mdx b/calico_versioned_docs/version-3.32/reference/calicoctl/datastore/migrate-policy-names.mdx new file mode 100644 index 0000000000..9eea2a112f --- /dev/null +++ b/calico_versioned_docs/version-3.32/reference/calicoctl/datastore/migrate-policy-names.mdx @@ -0,0 +1,75 @@ +--- +description: Reference for the calicoctl datastore migrate-policy-names command in Calico Open Source, used to fix pre-v3.32 policy names on an upgraded etcdv3 datastore. +--- + +# calicoctl datastore migrate-policy-names + +This section describes the `calicoctl datastore migrate-policy-names` command. + +Read the [calicoctl Overview](../overview.mdx) +for a full list of calicoctl commands. + +:::note + +This command is available in Calico v3.32.2 and later. You only need it on an +etcdv3 datastore (for example, OpenStack) that was created before v3.32 and +upgraded in place. A Kubernetes datastore is migrated automatically by +kube-controllers, so no manual step is required there. + +::: + +## Display the help text for 'calicoctl datastore migrate-policy-names' command + +Run `calicoctl datastore migrate-policy-names --help` to display the following help menu for the +command. + +``` +Usage: + calicoctl datastore migrate-policy-names [--config=] [--allow-version-mismatch] + +Options: + -h --help Show this screen. + -c --config= Path to the file containing connection + configuration in YAML or JSON format. + [default: /etc/calico/calicoctl.cfg] + --allow-version-mismatch Allow client and cluster versions mismatch. + +Description: + Rewrite policy names in the datastore to drop the legacy "default." tier + prefix, aligning the stored name with the v3 resource name introduced in + v3.32. + + This is only needed for an etcdv3 datastore (for example OpenStack) that was + created before v3.32 and upgraded in place. A Kubernetes datastore is + migrated automatically by kube-controllers. The command is safe to re-run. +``` + +### Examples + +Rewrite any pre-v3.32 policy names in the datastore so they match their v3 names. + +```bash +calicoctl datastore migrate-policy-names +``` + +On completion, the command reports how many policies it rewrote. + +``` +Policy name migration complete, migrated 5 policies. +``` + +The command is idempotent. Running it again once every policy has already been +migrated reports `migrated 0 policies` and makes no changes. + +### General options + +``` +-c --config= Path to the file containing connection + configuration in YAML or JSON format. + [default: /etc/calico/calicoctl.cfg] +``` + +## See also + +- [Install calicoctl](../../../operations/calicoctl/install.mdx) +- [Upgrade Calico on OpenStack](../../../operations/upgrading/openstack-upgrade.mdx) for the full upgrade procedure that runs this command diff --git a/calico_versioned_docs/version-3.32/reference/calicoctl/datastore/overview.mdx b/calico_versioned_docs/version-3.32/reference/calicoctl/datastore/overview.mdx index 7490ae094f..8f24b6bda8 100644 --- a/calico_versioned_docs/version-3.32/reference/calicoctl/datastore/overview.mdx +++ b/calico_versioned_docs/version-3.32/reference/calicoctl/datastore/overview.mdx @@ -9,16 +9,17 @@ This section describes the `calicoctl datastore` commands. Read the [calicoctl Overview](../overview.mdx) for a full list of calicoctl commands. -## Display the help text for 'calicoctl datastore migrate' commands +## Display the help text for 'calicoctl datastore' commands -Run `calicoctl datastore migrate --help` to display the following help menu for the +Run `calicoctl datastore --help` to display the following help menu for the commands. ``` Usage: calicoctl datastore [...] - migrate Migrate the contents of an etcdv3 datastore to a Kubernetes datastore. + migrate Migrate the contents of an etcdv3 datastore to a Kubernetes datastore. + migrate-policy-names Rewrite pre-v3.32 policy names in an etcdv3 datastore to drop the tier prefix. Options: -h --help Show this screen. @@ -35,3 +36,4 @@ Details on the `calicoctl datastore` commands are described in the documents lin organized by sub command. - [calicoctl datastore migrate](migrate/overview.mdx) +- [calicoctl datastore migrate-policy-names](migrate-policy-names.mdx) diff --git a/calico_versioned_sidebars/version-3.32-sidebars.json b/calico_versioned_sidebars/version-3.32-sidebars.json index 2f36ba2473..e3a1e03533 100644 --- a/calico_versioned_sidebars/version-3.32-sidebars.json +++ b/calico_versioned_sidebars/version-3.32-sidebars.json @@ -685,7 +685,8 @@ "reference/calicoctl/datastore/migrate/lock", "reference/calicoctl/datastore/migrate/unlock" ] - } + }, + "reference/calicoctl/datastore/migrate-policy-names" ] }, "reference/calicoctl/version" diff --git a/sidebars-calico.js b/sidebars-calico.js index 79c2dabcf7..a8d9b1abb6 100644 --- a/sidebars-calico.js +++ b/sidebars-calico.js @@ -692,6 +692,7 @@ module.exports = { 'reference/calicoctl/datastore/migrate/unlock', ], }, + 'reference/calicoctl/datastore/migrate-policy-names', ], }, 'reference/calicoctl/version', From 5ab131cc251837388d01fbd837567081ca88c8b9 Mon Sep 17 00:00:00 2001 From: Casey Davenport Date: Thu, 23 Jul 2026 08:49:22 -0700 Subject: [PATCH 2/3] Name the default tier in migrate-policy-names help text Matches the CLI wording clarification (calicoctl now says it drops the legacy "default." tier prefix). --- calico/reference/calicoctl/datastore/overview.mdx | 2 +- .../version-3.32/reference/calicoctl/datastore/overview.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/calico/reference/calicoctl/datastore/overview.mdx b/calico/reference/calicoctl/datastore/overview.mdx index 8f24b6bda8..e7532d44e3 100644 --- a/calico/reference/calicoctl/datastore/overview.mdx +++ b/calico/reference/calicoctl/datastore/overview.mdx @@ -19,7 +19,7 @@ Usage: calicoctl datastore [...] migrate Migrate the contents of an etcdv3 datastore to a Kubernetes datastore. - migrate-policy-names Rewrite pre-v3.32 policy names in an etcdv3 datastore to drop the tier prefix. + migrate-policy-names Rewrite pre-v3.32 policy names in an etcdv3 datastore to drop the legacy "default." tier prefix. Options: -h --help Show this screen. diff --git a/calico_versioned_docs/version-3.32/reference/calicoctl/datastore/overview.mdx b/calico_versioned_docs/version-3.32/reference/calicoctl/datastore/overview.mdx index 8f24b6bda8..e7532d44e3 100644 --- a/calico_versioned_docs/version-3.32/reference/calicoctl/datastore/overview.mdx +++ b/calico_versioned_docs/version-3.32/reference/calicoctl/datastore/overview.mdx @@ -19,7 +19,7 @@ Usage: calicoctl datastore [...] migrate Migrate the contents of an etcdv3 datastore to a Kubernetes datastore. - migrate-policy-names Rewrite pre-v3.32 policy names in an etcdv3 datastore to drop the tier prefix. + migrate-policy-names Rewrite pre-v3.32 policy names in an etcdv3 datastore to drop the legacy "default." tier prefix. Options: -h --help Show this screen. From ad3d4a17fb7f5c03ddb80ef943269204656da3e0 Mon Sep 17 00:00:00 2001 From: Casey Davenport Date: Fri, 24 Jul 2026 10:04:34 -0700 Subject: [PATCH 3/3] Scope this PR to the v3.32 migrate-policy-names docs The master (Next) reference page moves to the calicoctl cobra PR, which can merge now. This PR carries only the 3.32 page, gated on v3.32.2. --- .../datastore/migrate-policy-names.mdx | 74 ------------------- .../calicoctl/datastore/overview.mdx | 8 +- sidebars-calico.js | 1 - 3 files changed, 3 insertions(+), 80 deletions(-) delete mode 100644 calico/reference/calicoctl/datastore/migrate-policy-names.mdx diff --git a/calico/reference/calicoctl/datastore/migrate-policy-names.mdx b/calico/reference/calicoctl/datastore/migrate-policy-names.mdx deleted file mode 100644 index ea5569b6f9..0000000000 --- a/calico/reference/calicoctl/datastore/migrate-policy-names.mdx +++ /dev/null @@ -1,74 +0,0 @@ ---- -description: Reference for the calicoctl datastore migrate-policy-names command in Calico Open Source, used to fix pre-v3.32 policy names on an upgraded etcdv3 datastore. ---- - -# calicoctl datastore migrate-policy-names - -This section describes the `calicoctl datastore migrate-policy-names` command. - -Read the [calicoctl Overview](../overview.mdx) -for a full list of calicoctl commands. - -:::note - -You only need this command on an etcdv3 datastore (for example, OpenStack) that -was created before v3.32 and upgraded in place. A Kubernetes datastore is -migrated automatically by kube-controllers, so no manual step is required there. - -::: - -## Display the help text for 'calicoctl datastore migrate-policy-names' command - -Run `calicoctl datastore migrate-policy-names --help` to display the following help menu for the -command. - -``` -Usage: - calicoctl datastore migrate-policy-names [--config=] [--allow-version-mismatch] - -Options: - -h --help Show this screen. - -c --config= Path to the file containing connection - configuration in YAML or JSON format. - [default: /etc/calico/calicoctl.cfg] - --allow-version-mismatch Allow client and cluster versions mismatch. - -Description: - Rewrite policy names in the datastore to drop the legacy "default." tier - prefix, aligning the stored name with the v3 resource name introduced in - v3.32. - - This is only needed for an etcdv3 datastore (for example OpenStack) that was - created before v3.32 and upgraded in place. A Kubernetes datastore is - migrated automatically by kube-controllers. The command is safe to re-run. -``` - -### Examples - -Rewrite any pre-v3.32 policy names in the datastore so they match their v3 names. - -```bash -calicoctl datastore migrate-policy-names -``` - -On completion, the command reports how many policies it rewrote. - -``` -Policy name migration complete, migrated 5 policies. -``` - -The command is idempotent. Running it again once every policy has already been -migrated reports `migrated 0 policies` and makes no changes. - -### General options - -``` --c --config= Path to the file containing connection - configuration in YAML or JSON format. - [default: /etc/calico/calicoctl.cfg] -``` - -## See also - -- [Install calicoctl](../../../operations/calicoctl/install.mdx) -- [Upgrade Calico on OpenStack](../../../operations/upgrading/openstack-upgrade.mdx) for the full upgrade procedure that runs this command diff --git a/calico/reference/calicoctl/datastore/overview.mdx b/calico/reference/calicoctl/datastore/overview.mdx index e7532d44e3..7490ae094f 100644 --- a/calico/reference/calicoctl/datastore/overview.mdx +++ b/calico/reference/calicoctl/datastore/overview.mdx @@ -9,17 +9,16 @@ This section describes the `calicoctl datastore` commands. Read the [calicoctl Overview](../overview.mdx) for a full list of calicoctl commands. -## Display the help text for 'calicoctl datastore' commands +## Display the help text for 'calicoctl datastore migrate' commands -Run `calicoctl datastore --help` to display the following help menu for the +Run `calicoctl datastore migrate --help` to display the following help menu for the commands. ``` Usage: calicoctl datastore [...] - migrate Migrate the contents of an etcdv3 datastore to a Kubernetes datastore. - migrate-policy-names Rewrite pre-v3.32 policy names in an etcdv3 datastore to drop the legacy "default." tier prefix. + migrate Migrate the contents of an etcdv3 datastore to a Kubernetes datastore. Options: -h --help Show this screen. @@ -36,4 +35,3 @@ Details on the `calicoctl datastore` commands are described in the documents lin organized by sub command. - [calicoctl datastore migrate](migrate/overview.mdx) -- [calicoctl datastore migrate-policy-names](migrate-policy-names.mdx) diff --git a/sidebars-calico.js b/sidebars-calico.js index a8d9b1abb6..79c2dabcf7 100644 --- a/sidebars-calico.js +++ b/sidebars-calico.js @@ -692,7 +692,6 @@ module.exports = { 'reference/calicoctl/datastore/migrate/unlock', ], }, - 'reference/calicoctl/datastore/migrate-policy-names', ], }, 'reference/calicoctl/version',