From caa18c03454d3d805ae448c2f45fcf0ed9f625f5 Mon Sep 17 00:00:00 2001 From: Patrik Date: Fri, 8 Oct 2021 17:23:17 +0200 Subject: [PATCH] docs: adjust details missed for v0.7 (#762) --- docs/docs/concepts/namespaces.mdx | 9 -------- docs/docs/guides/v0.7-migration.mdx | 23 +++++++++++++++---- .../version-v0.7/concepts/namespaces.mdx | 9 -------- .../version-v0.7/guides/v0.7-migration.mdx | 23 +++++++++++++++---- 4 files changed, 36 insertions(+), 28 deletions(-) diff --git a/docs/docs/concepts/namespaces.mdx b/docs/docs/concepts/namespaces.mdx index 3f9635de5..8e903f147 100644 --- a/docs/docs/concepts/namespaces.mdx +++ b/docs/docs/concepts/namespaces.mdx @@ -40,15 +40,6 @@ will evaluate to false (a.k.a. rejected). Vice versa, all relation tuples containing an object have to be in the same namespace to reference the same object. -## Migrations - -Because namespaces each come with an individual configuration that can even -modify some storage specific options, it is required to manually review and run -migrations on namespace configuration updates. Please refer to the -[namespace migration CLI reference](../cli/keto-namespace-migrate.md) and -[running in production guide](../guides/production.md) to learn more about that -process. - ## Naming Conventions Namespaces should be named after the plural of the type of objects they describe diff --git a/docs/docs/guides/v0.7-migration.mdx b/docs/docs/guides/v0.7-migration.mdx index 837482185..827db4023 100644 --- a/docs/docs/guides/v0.7-migration.mdx +++ b/docs/docs/guides/v0.7-migration.mdx @@ -46,12 +46,25 @@ not be available during migration. 3. Change the privileges of `keto` to be read-only on all tables. 4. Still route all traffic to the old Keto. Write API requests will fail from now on, but the Read API will be zero-downtime. -5. Run `keto namespace migrate legacy --yes` considering the points raised in - [preparations](#preparations). -6. In case of failure, re-run the command until it succeeds. -7. In case of log statements stating +5. Run `keto migrate up --yes` considering the points raised in + [preparations](#preparations). This command will apply SQL schema changes, + but not yet migrate data. +6. Run `keto namespace migrate legacy --yes` considering the points raised in + [preparations](#preparations). This command will migrate **all** namespaces + **and** delete the old tables on success. +7. In case of failure, re-run the command until it succeeds. +8. In case of log statements stating `Skipping relation tuple, it seems to be in a broken state. Please recreate it manually.` note down the logged data somewhere and recreate the relation tuples in question once the migration is done using the API. -8. After the migration is successfully done, route all traffic to Keto v0.7 and +9. After the migration is successfully done, route all traffic to Keto v0.7 and shut down Keto v0.6. At this point the API is fully operational again. + +## Options for Adjusting the Migration Process + +The `keto namespace migrate legacy` command supports multiple options: + +- interactive mode with manual approval by not specifying `--yes` +- migrate single namespace by specifying its name as an argument +- only delete old tables by specifying `--down-only`; useful if you did not + approve the down migration previously diff --git a/docs/versioned_docs/version-v0.7/concepts/namespaces.mdx b/docs/versioned_docs/version-v0.7/concepts/namespaces.mdx index 3f9635de5..8e903f147 100644 --- a/docs/versioned_docs/version-v0.7/concepts/namespaces.mdx +++ b/docs/versioned_docs/version-v0.7/concepts/namespaces.mdx @@ -40,15 +40,6 @@ will evaluate to false (a.k.a. rejected). Vice versa, all relation tuples containing an object have to be in the same namespace to reference the same object. -## Migrations - -Because namespaces each come with an individual configuration that can even -modify some storage specific options, it is required to manually review and run -migrations on namespace configuration updates. Please refer to the -[namespace migration CLI reference](../cli/keto-namespace-migrate.md) and -[running in production guide](../guides/production.md) to learn more about that -process. - ## Naming Conventions Namespaces should be named after the plural of the type of objects they describe diff --git a/docs/versioned_docs/version-v0.7/guides/v0.7-migration.mdx b/docs/versioned_docs/version-v0.7/guides/v0.7-migration.mdx index 837482185..827db4023 100644 --- a/docs/versioned_docs/version-v0.7/guides/v0.7-migration.mdx +++ b/docs/versioned_docs/version-v0.7/guides/v0.7-migration.mdx @@ -46,12 +46,25 @@ not be available during migration. 3. Change the privileges of `keto` to be read-only on all tables. 4. Still route all traffic to the old Keto. Write API requests will fail from now on, but the Read API will be zero-downtime. -5. Run `keto namespace migrate legacy --yes` considering the points raised in - [preparations](#preparations). -6. In case of failure, re-run the command until it succeeds. -7. In case of log statements stating +5. Run `keto migrate up --yes` considering the points raised in + [preparations](#preparations). This command will apply SQL schema changes, + but not yet migrate data. +6. Run `keto namespace migrate legacy --yes` considering the points raised in + [preparations](#preparations). This command will migrate **all** namespaces + **and** delete the old tables on success. +7. In case of failure, re-run the command until it succeeds. +8. In case of log statements stating `Skipping relation tuple, it seems to be in a broken state. Please recreate it manually.` note down the logged data somewhere and recreate the relation tuples in question once the migration is done using the API. -8. After the migration is successfully done, route all traffic to Keto v0.7 and +9. After the migration is successfully done, route all traffic to Keto v0.7 and shut down Keto v0.6. At this point the API is fully operational again. + +## Options for Adjusting the Migration Process + +The `keto namespace migrate legacy` command supports multiple options: + +- interactive mode with manual approval by not specifying `--yes` +- migrate single namespace by specifying its name as an argument +- only delete old tables by specifying `--down-only`; useful if you did not + approve the down migration previously