From d11d939e83fa1e01e63d0ee775a1d3f7684d5b55 Mon Sep 17 00:00:00 2001 From: vinckr Date: Mon, 10 Jan 2022 18:34:08 +0100 Subject: [PATCH 01/11] fix: upgrade guide 0.5->0.8 --- UPGRADE.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/UPGRADE.md b/UPGRADE.md index b93195e6be0..af7587c56bd 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -10,9 +10,27 @@ before finalizing the upgrade process. These changes have not yet been released and this area's purpose is to keep track of future changes. -## v0.4.4-alpha.1 +## v0.8.0-alpha.1 -Please head over to the [CHANGELOG](https://github.com/ory/kratos/blob/master/CHANGELOG.md#040-alpha1-2020-07-08) +This version includes a lot of new features, but includes few breaking changes, mostly around the SDKs. +For a full list of breaking changes please visit the [CHANGELOG](https://github.com/ory/kratos/blob/master/CHANGELOG.md#080-alpha1-2021-10-27). + +## v0.7.0-alpha.1 + +A new SDK has been introduced in this version, please visit the [CHANGELOG](https://github.com/ory/kratos/blob/master/CHANGELOG.md#070-alpha1-2021-07-13) to get a full overview of the SDK and other breaking changes. + +## v0.6.0-alpha.1 + +BCrypt is now the default hashing algorithm. You must apply SQL migrations for this upgrade, this will invalidate all ongoing self-service flows and purge existing self-service forms. If you wish to keep these records, make a back up of your database prior! +For a full list of breaking changes please visit the [CHANGELOG](https://github.com/ory/kratos/blob/master/CHANGELOG.md#060-alpha1-2021-05-05). + +## v0.5.0-alpha.1 + +For a full list of breaking changes please visit the [CHANGELOG](https://github.com/ory/kratos/blob/master/CHANGELOG.md#050-alpha1-2020-10-15). + +## v0.4.0-alpha.1 + +Please visit the [CHANGELOG](https://github.com/ory/kratos/blob/master/CHANGELOG.md#040-alpha1-2020-07-08). ## v0.3.0-alpha.1 From 0f4df7a3652eabaeb6ffc27e7ee2495fca716047 Mon Sep 17 00:00:00 2001 From: vinckr Date: Mon, 10 Jan 2022 19:10:40 +0100 Subject: [PATCH 02/11] docs: add upgrade guide --- docs/docs/debug/upgrade.md | 324 +++++++++++++++++++++++++++++++++++++ docs/sidebar.json | 3 +- 2 files changed, 326 insertions(+), 1 deletion(-) create mode 100644 docs/docs/debug/upgrade.md diff --git a/docs/docs/debug/upgrade.md b/docs/docs/debug/upgrade.md new file mode 100644 index 00000000000..d5d36e3193b --- /dev/null +++ b/docs/docs/debug/upgrade.md @@ -0,0 +1,324 @@ +--- +id: upgrade +title: Ory Kratos Upgrade Guide +--- + +This guide covers essentials to consider when upgrading Ory Kratos, please also +refer to [UPGRADE.md](https://github.com/ory/kratos/blob/master/UPGRADE.md). + +Generally after upgrading just run `kratos migrate`. + +Please note the following breaking changes when upgrading from Ory Kratos 0.5 to +0.8: + +## Ory Kratos v0.6 Breaking changes + +Full list of changes: +https://github.com/ory/kratos/blob/v0.6.0-alpha.1/CHANGELOG.md#breaking-changes + +1. **hashing:** BCrypt is now the default hashing algorithm. If you wish to + continue using Argon2id please set `hashers.algorithm` to `argon2`. + +1. To upgrade to v0.6 you must apply SQL migrations. These migrations will drop + the flow method table implying that all self-service flows that are ongoing + will become invalid. We recommend purging the flow table manually as well + after this migration has been applied, if you have users doing at least one + self-service flow per minute. This implies a significant breaking change in + the self-service flows payload. Please consult the new ui documentation. In + essence, the login flow's `methods` key was replaced with a generic `ui` key + which provides information for the UI that needs to be rendered. + +1. This change introduces a new feature: UI Nodes. Previously, all self-service + flows (login, registration, ...) included form fields (e.g. + `methods.password.config.fields`). However, these form fields lacked support + for other types of UI elements such as links (for e.g. "Sign in with + Google"), images (e.g. QR codes), javascript (e.g. WebAuthn), or text (e.g. + recovery codes). With v0.6, these new features have been introduced. Please + be aware that this introduces significant breaking changes which you will + need to adopt to in your UI. Please refer to the most recent documentation to + see what has changed. Conceptionally, most things stayed the same - you do + however need to update how you access and render the form fields. + +1. Please be also aware that v0.6 includes SQL migrations which **purge existing + self-service forms** from the database. This means that users will need to + re-start the login/registration/... flow after the SQL migrations have been + applied! If you wish to keep these records, make a back up of your database + prior! + +1. The configuration value for `hashers.argon2.memory` is now a string + representation of the memory amount including the unit of measurement. To + convert the value divide your current setting (KB) by 1024 to get a result in + MB or 1048576 to get a result in GB. Example: `131072` would now become + `128MB`. + +1. The following configuration keys were updated: + + ```diff + selfservice.methods.password.config.max_breaches + ``` + + - `password.max_breaches` -> + `selfservice.methods.password.config.max_breaches` + - `password.ignore_network_errors` -> + `selfservice.methods.password.config.ignore_network_errors` + +1. After battling with [spf13/viper](https://github.com/spf13/viper) for several + years we finally found a viable alternative with + [knadh/koanf](https://github.com/knadh/koanf). The complete internal + configuration infrastructure has changed, with several highlights: + + 1. Configuration sourcing works from all sources (file, env, cli flags) with + validation against the configuration schema, greatly improving developer + experience when changing or updating configuration. + 2. Configuration reloading has improved significantly and works flawlessly on + Kubernetes. + 3. Performance increased dramatically, completely removing the need for a + cache layer between the configuration system and ORY Hydra. + 4. It is now possible to load several config files using the `--config` flag. + 5. Configuration values are now sent to the tracer (e.g. Jaeger) if tracing + is enabled. + +Please be aware that Ory Kratos might complain about an invalid configuration, +because the validation process has improved significantly. + +## Ory Kratos v0.7 Breaking changes + +Full list of changes: +https://github.com/ory/kratos/blob/v0.7.0-alpha.1/CHANGELOG.md#breaking-changes + +1. Prior to this change it was not possible to specify the + verification/recovery link lifetime. Instead, it was bound to the flow + expiry. This patch changes that and adds the ability to configure the + lifespan of the link individually: + + ```diff + selfservice: + methods: + link: + enabled: true + config: + + # Defines how long a recovery link is valid for (default 1h) + + lifespan: 15m + ``` + + This is a breaking change because the link strategy no longer respects the + recovery / verification flow expiry time and, unless set, will default to + one hour. + +1. This change introduces a better SDK. As part of this change, several + breaking changes with regards to the SDK have been introduced. We recommend + reading this section carefully to understand the changes and how they might + affect you. Before, the SDK was structured into tags `public` and `admin`. + This stems from the fact that we have two ports in Ory Kratos - one + administrative and one public port. While serves as a good overview when + working with Ory Kratos, it does not express: + + - What module the API belongs to (e.g. self-service, identity, ...) + - What maturity the API has (e.g. experimental, alpha, beta, ...) + - What version the API has (e.g. v0alpha0, v1beta0, ...) + + This patch replaces the current `admin` and `public` tags with a versioned approach indicating the maturity of the API used. For example, `initializeSelfServiceSettingsForBrowsers` would no longer be under the `public` tag but instead under the `v0alpha1` tag: + + ```diff + import { + Configuration, + - PublicApi + + V0Alpha1 + } from '@ory/kratos-client'; + + - const kratos = new PublicApi(new Configuration({ basePath: config.kratos.public })); + + const kratos = new V0Alpha1(new Configuration({ basePath: config.kratos.public })); + ``` + + To avoid confusion when setting up the SDK, and potentially using the wrong endpoints in your codebase and ending up with strange 404 errors, Ory Kratos now redirects you to the correct port, given that `serve.(public|admin).base_url` are configured correctly. + +1. Further, all administrative functions require authorization using e.g. an + Ory Personal Access Token in Ory Cloud. For self-hosted deployments of Ory + Kratos, we do not know what developers use to protect their APIs. As such, + we believe that it is ok to have admin and public functions under one common + API and differentiate with an `admin` prefix. Therefore, the following + patches should be made in your codebase: + + ```diff + import { + - AdminApi, + + V0Alpha1, + Configuration + } from '@ory/kratos-client'; + + -const kratos = new AdminApi(new Configuration({ basePath: config.kratos.admin })); + +const kratos = new V0Alpha1(new Configuration({ basePath: config.kratos.admin })); + + -kratos.createIdentity({ + +kratos.adminCreateIdentity({ + schema_id: 'default', + traits: { /* ... */ } + }) + ``` + +1. We streamlined how credentials are used. We now differentiate between: + + - Per-request credentials such as the Ory Session Token / Cookie + ```diff + - public getSelfServiceRegistrationFlow(id: string, cookie?: string, options?: any) {} + + public getSelfServiceSettingsFlow(id: string, xSessionToken?: string, cookie?: string, options?: any) {} + ``` + - Global credentials such as the Ory Cloud PAT. + + ```typescript + const kratos = new V0Alpha0( + new Configuration({ + basePath: config.kratos.admin, + accessToken: 'some-token' + }) + ) + + kratosAdmin.adminCreateIdentity({ + schema_id: 'default', + traits: { + /* ... */ + } + }) + ``` + +1. This patch introduces CSRF countermeasures for fetching all self-service + flows. This ensures that users can not accidentally leak sensitive + information when copy/pasting e.g. login URLs (see #1282). If a self-service + flow for browsers is requested, the CSRF cookie must be included in the + call, regardless if it is a client-side browser app or a server-side browser + app calling. This **does not apply** for API-based flows. + + As part of this change, the following endpoints have been removed: + + - `GET /self-service/login/flows`; + - `GET /self-service/registration/flows`; + - `GET /self-service/verification/flows`; + - `GET /self-service/recovery/flows`; + - `GET /self-service/settings/flows`. + + Please ensure that your server-side applications use the public port (e.g. + `GET /self-service/login/flows`) for fetching + self-service flows going forward. + + If you use the SDKs, upgrading is easy by adding the `cookie` header when + fetching the flows. This is only required when **using browser flows on the + server side**. + + The following example illustrates a ExpressJS (NodeJS) server-side + application fetching the self-service flows. + + ```diff + app.get('some-route', (req: Request, res: Response) => { + - kratos.getSelfServiceLoginFlow(flow).then((flow) => /* ... */ ) + + kratos.getSelfServiceLoginFlow(flow, req.header('cookie')).then((flow) => /* ... */ ) + + - kratos.getSelfServiceRecoveryFlow(flow).then((flow) => /* ... */ ) + + kratos.getSelfServiceRecoveryFlow(flow, req.header('cookie')).then((flow) => /* ... */ ) + + - kratos.getSelfServiceRegistrationFlow(flow).then((flow) => /* ... */ ) + + kratos.getSelfServiceRegistrationFlow(flow, req.header('cookie')).then((flow) => /* ... */ ) + + - kratos.getSelfServiceVerificationFlow(flow).then((flow) => /* ... */ ) + + kratos.getSelfServiceVerificationFlow(flow, req.header('cookie')).then((flow) => /* ... */ ) + + - kratos.getSelfServiceSettingsFlow(flow).then((flow) => /* ... */ ) + + kratos.getSelfServiceSettingsFlow(flow, undefined, req.header('cookie')).then((flow) => /* ... */ ) + }) + ``` + + For concrete details, check out + [the changes in the NodeJS app](https://github.com/ory/kratos-selfservice-ui-node/commit/e7fa292968111e06401fcfc9b1dd0e8e285a4d87). + +1. This patch refactors the logout functionality for browsers and APIs. It adds + increased security and DoS-defenses to the logout flow. Previously, calling + `GET /self-service/browser/flows/logout` would remove the session cookie and + redirect the user to the logout endpoint. Now you have to make a call to + `GET /self-service/logout/browser` which returns a JSON response including a + `logout_url` URL to be used for logout. The call to + `/self-service/logout/browser` must be made using AJAX with cookies enabled + or by including the Ory Session Cookie in the `X-Session-Cookie` HTTP + Header. You may also use the SDK method + `createSelfServiceLogoutUrlForBrowsers` to do that. + + Additionally, the endpoint `DELETE /sessions` has been moved to + `DELETE /self-service/logout/api`. Payloads and responses stay equal. The + SDK method `revokeSession` has been renamed to + `submitSelfServiceLogoutFlowWithoutBrowser`. + +1. Several SDK methods have been renamed: + + - `initializeSelfServiceRecoveryForNativeApps` to + `initializeSelfServiceRecoveryWithoutBrowser`. + - `initializeSelfServiceVerificationForNativeApps` to + `initializeSelfServiceVerificationWithoutBrowser` + - `initializeSelfServiceSettingsForNativeApps` to + `initializeSelfServiceSettingsWithoutBrowser`. + - `initializeSelfServiceregistrationForNativeApps` to + `initializeSelfServiceregistrationWithoutBrowser`. + - `initializeSelfServiceLoginForNativeApps` to + `initializeSelfServiceLoginWithoutBrowser`. + + As in the previous release you may still use the old SDK if you do not want + to deal with the SDK breaking changes for now. + +## Ory Kratos v0.8 Breaking changes + +Full list of changes: +https://github.com/ory/kratos/blob/v0.8.0-alpha.1/CHANGELOG.md#breaking-changes + +1. The location of the homebrew tap has changed from `ory/ory/kratos` to + `ory/tap/kratos`. + +1. The self-service login flow's `forced` key has been renamed to `refresh`. + +1. The SDKs are now generated with tag v0alpha2 to reflect that some signatures + have changed in a breaking fashion. Please update your imports from + `v0alpha1` to `v0alpha2`. + +1. To support 2FA on non-browser (e.g. native mobile) apps we have added the Ory + Session Token as a possible parameter to both + `initializeSelfServiceLoginFlowWithoutBrowser` and + `submitSelfServiceLoginFlow`. Depending on the SDK generator, the order of + the arguments may have changed. In JavaScript: + + ```diff + - .submitSelfServiceLoginFlow(flow.id, payload) + + .submitSelfServiceLoginFlow(flow.id, sessionToken, payload) + // or if the user has no session yet: + + .submitSelfServiceLoginFlow(flow.id, undefined, payload) + ``` + +1. To improve the overall API design we have changed the result of + `POST /self-service/settings`. Instead of having flow be a key, the flow is + now the response. The updated identity payload stays the same! + + ```diff + { + - "flow": { + - "id": "flow-id-..." + - ... + - }, + + "id": "flow-id-..." + + ... + "identity": { + "id": "identity-id-..." + } + } + ``` + +1. The SMTPS scheme used in courier config url with cleartext/StartTLS/TLS SMTP + connection types is now only supporting implicit TLS. For StartTLS and + cleartext SMTP, please use the smtp scheme instead. + + Example: + + - SMTP Cleartext: `smtp://foo:bar@my-mailserver:1234/?disable_starttls=true` + - SMTP with StartTLS: `smtps://foo:bar@my-mailserver:1234/` -> + `smtp://foo:bar@my-mailserver:1234/` + - SMTP with implicit TLS: + `smtps://foo:bar@my-mailserver:1234/?legacy_ssl=true` -> + `smtps://foo:bar@my-mailserver:1234/` + +1. This patch changes the naming and number of prometheus metrics (see: + https://github.com/ory/x/pull/379). In short: all metrics will have now + `http_` prefix to conform to Prometheus best practices. diff --git a/docs/sidebar.json b/docs/sidebar.json index 8bca6dfa929..0703e3e99a6 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -119,7 +119,8 @@ "debug/troubleshooting", "debug/csrf", "debug/performance-out-of-memory-password-hashing-argon2", - "debug/debug-docker-delve-ory-kratos" + "debug/debug-docker-delve-ory-kratos", + "debug/upgrade" ] }, { From a7e708bebe1c568c130e3305441ec89093d1fe5a Mon Sep 17 00:00:00 2001 From: vinckr Date: Tue, 11 Jan 2022 12:35:05 +0100 Subject: [PATCH 03/11] fix: remove unreleased section from UPGRADE.md --- UPGRADE.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/UPGRADE.md b/UPGRADE.md index af7587c56bd..b13c7375288 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -5,11 +5,6 @@ possible. Please note that not all breaking changes might be included here. Please check the [CHANGELOG.md](./CHANGELOG.md) for a full list of changes before finalizing the upgrade process. -## unreleased - -These changes have not yet been released and this area's purpose is to keep -track of future changes. - ## v0.8.0-alpha.1 This version includes a lot of new features, but includes few breaking changes, mostly around the SDKs. From 4b1bf9d1134e224df356c6de2d5c7bccc5e93fb7 Mon Sep 17 00:00:00 2001 From: vinckr Date: Tue, 11 Jan 2022 13:50:35 +0100 Subject: [PATCH 04/11] docs: fix up upgrade guide --- docs/docs/debug/upgrade.md | 324 ------------------------------------ docs/docs/guides/upgrade.md | 63 +++++++ docs/sidebar.json | 7 +- 3 files changed, 66 insertions(+), 328 deletions(-) delete mode 100644 docs/docs/debug/upgrade.md create mode 100644 docs/docs/guides/upgrade.md diff --git a/docs/docs/debug/upgrade.md b/docs/docs/debug/upgrade.md deleted file mode 100644 index d5d36e3193b..00000000000 --- a/docs/docs/debug/upgrade.md +++ /dev/null @@ -1,324 +0,0 @@ ---- -id: upgrade -title: Ory Kratos Upgrade Guide ---- - -This guide covers essentials to consider when upgrading Ory Kratos, please also -refer to [UPGRADE.md](https://github.com/ory/kratos/blob/master/UPGRADE.md). - -Generally after upgrading just run `kratos migrate`. - -Please note the following breaking changes when upgrading from Ory Kratos 0.5 to -0.8: - -## Ory Kratos v0.6 Breaking changes - -Full list of changes: -https://github.com/ory/kratos/blob/v0.6.0-alpha.1/CHANGELOG.md#breaking-changes - -1. **hashing:** BCrypt is now the default hashing algorithm. If you wish to - continue using Argon2id please set `hashers.algorithm` to `argon2`. - -1. To upgrade to v0.6 you must apply SQL migrations. These migrations will drop - the flow method table implying that all self-service flows that are ongoing - will become invalid. We recommend purging the flow table manually as well - after this migration has been applied, if you have users doing at least one - self-service flow per minute. This implies a significant breaking change in - the self-service flows payload. Please consult the new ui documentation. In - essence, the login flow's `methods` key was replaced with a generic `ui` key - which provides information for the UI that needs to be rendered. - -1. This change introduces a new feature: UI Nodes. Previously, all self-service - flows (login, registration, ...) included form fields (e.g. - `methods.password.config.fields`). However, these form fields lacked support - for other types of UI elements such as links (for e.g. "Sign in with - Google"), images (e.g. QR codes), javascript (e.g. WebAuthn), or text (e.g. - recovery codes). With v0.6, these new features have been introduced. Please - be aware that this introduces significant breaking changes which you will - need to adopt to in your UI. Please refer to the most recent documentation to - see what has changed. Conceptionally, most things stayed the same - you do - however need to update how you access and render the form fields. - -1. Please be also aware that v0.6 includes SQL migrations which **purge existing - self-service forms** from the database. This means that users will need to - re-start the login/registration/... flow after the SQL migrations have been - applied! If you wish to keep these records, make a back up of your database - prior! - -1. The configuration value for `hashers.argon2.memory` is now a string - representation of the memory amount including the unit of measurement. To - convert the value divide your current setting (KB) by 1024 to get a result in - MB or 1048576 to get a result in GB. Example: `131072` would now become - `128MB`. - -1. The following configuration keys were updated: - - ```diff - selfservice.methods.password.config.max_breaches - ``` - - - `password.max_breaches` -> - `selfservice.methods.password.config.max_breaches` - - `password.ignore_network_errors` -> - `selfservice.methods.password.config.ignore_network_errors` - -1. After battling with [spf13/viper](https://github.com/spf13/viper) for several - years we finally found a viable alternative with - [knadh/koanf](https://github.com/knadh/koanf). The complete internal - configuration infrastructure has changed, with several highlights: - - 1. Configuration sourcing works from all sources (file, env, cli flags) with - validation against the configuration schema, greatly improving developer - experience when changing or updating configuration. - 2. Configuration reloading has improved significantly and works flawlessly on - Kubernetes. - 3. Performance increased dramatically, completely removing the need for a - cache layer between the configuration system and ORY Hydra. - 4. It is now possible to load several config files using the `--config` flag. - 5. Configuration values are now sent to the tracer (e.g. Jaeger) if tracing - is enabled. - -Please be aware that Ory Kratos might complain about an invalid configuration, -because the validation process has improved significantly. - -## Ory Kratos v0.7 Breaking changes - -Full list of changes: -https://github.com/ory/kratos/blob/v0.7.0-alpha.1/CHANGELOG.md#breaking-changes - -1. Prior to this change it was not possible to specify the - verification/recovery link lifetime. Instead, it was bound to the flow - expiry. This patch changes that and adds the ability to configure the - lifespan of the link individually: - - ```diff - selfservice: - methods: - link: - enabled: true - config: - + # Defines how long a recovery link is valid for (default 1h) - + lifespan: 15m - ``` - - This is a breaking change because the link strategy no longer respects the - recovery / verification flow expiry time and, unless set, will default to - one hour. - -1. This change introduces a better SDK. As part of this change, several - breaking changes with regards to the SDK have been introduced. We recommend - reading this section carefully to understand the changes and how they might - affect you. Before, the SDK was structured into tags `public` and `admin`. - This stems from the fact that we have two ports in Ory Kratos - one - administrative and one public port. While serves as a good overview when - working with Ory Kratos, it does not express: - - - What module the API belongs to (e.g. self-service, identity, ...) - - What maturity the API has (e.g. experimental, alpha, beta, ...) - - What version the API has (e.g. v0alpha0, v1beta0, ...) - - This patch replaces the current `admin` and `public` tags with a versioned approach indicating the maturity of the API used. For example, `initializeSelfServiceSettingsForBrowsers` would no longer be under the `public` tag but instead under the `v0alpha1` tag: - - ```diff - import { - Configuration, - - PublicApi - + V0Alpha1 - } from '@ory/kratos-client'; - - - const kratos = new PublicApi(new Configuration({ basePath: config.kratos.public })); - + const kratos = new V0Alpha1(new Configuration({ basePath: config.kratos.public })); - ``` - - To avoid confusion when setting up the SDK, and potentially using the wrong endpoints in your codebase and ending up with strange 404 errors, Ory Kratos now redirects you to the correct port, given that `serve.(public|admin).base_url` are configured correctly. - -1. Further, all administrative functions require authorization using e.g. an - Ory Personal Access Token in Ory Cloud. For self-hosted deployments of Ory - Kratos, we do not know what developers use to protect their APIs. As such, - we believe that it is ok to have admin and public functions under one common - API and differentiate with an `admin` prefix. Therefore, the following - patches should be made in your codebase: - - ```diff - import { - - AdminApi, - + V0Alpha1, - Configuration - } from '@ory/kratos-client'; - - -const kratos = new AdminApi(new Configuration({ basePath: config.kratos.admin })); - +const kratos = new V0Alpha1(new Configuration({ basePath: config.kratos.admin })); - - -kratos.createIdentity({ - +kratos.adminCreateIdentity({ - schema_id: 'default', - traits: { /* ... */ } - }) - ``` - -1. We streamlined how credentials are used. We now differentiate between: - - - Per-request credentials such as the Ory Session Token / Cookie - ```diff - - public getSelfServiceRegistrationFlow(id: string, cookie?: string, options?: any) {} - + public getSelfServiceSettingsFlow(id: string, xSessionToken?: string, cookie?: string, options?: any) {} - ``` - - Global credentials such as the Ory Cloud PAT. - - ```typescript - const kratos = new V0Alpha0( - new Configuration({ - basePath: config.kratos.admin, - accessToken: 'some-token' - }) - ) - - kratosAdmin.adminCreateIdentity({ - schema_id: 'default', - traits: { - /* ... */ - } - }) - ``` - -1. This patch introduces CSRF countermeasures for fetching all self-service - flows. This ensures that users can not accidentally leak sensitive - information when copy/pasting e.g. login URLs (see #1282). If a self-service - flow for browsers is requested, the CSRF cookie must be included in the - call, regardless if it is a client-side browser app or a server-side browser - app calling. This **does not apply** for API-based flows. - - As part of this change, the following endpoints have been removed: - - - `GET /self-service/login/flows`; - - `GET /self-service/registration/flows`; - - `GET /self-service/verification/flows`; - - `GET /self-service/recovery/flows`; - - `GET /self-service/settings/flows`. - - Please ensure that your server-side applications use the public port (e.g. - `GET /self-service/login/flows`) for fetching - self-service flows going forward. - - If you use the SDKs, upgrading is easy by adding the `cookie` header when - fetching the flows. This is only required when **using browser flows on the - server side**. - - The following example illustrates a ExpressJS (NodeJS) server-side - application fetching the self-service flows. - - ```diff - app.get('some-route', (req: Request, res: Response) => { - - kratos.getSelfServiceLoginFlow(flow).then((flow) => /* ... */ ) - + kratos.getSelfServiceLoginFlow(flow, req.header('cookie')).then((flow) => /* ... */ ) - - - kratos.getSelfServiceRecoveryFlow(flow).then((flow) => /* ... */ ) - + kratos.getSelfServiceRecoveryFlow(flow, req.header('cookie')).then((flow) => /* ... */ ) - - - kratos.getSelfServiceRegistrationFlow(flow).then((flow) => /* ... */ ) - + kratos.getSelfServiceRegistrationFlow(flow, req.header('cookie')).then((flow) => /* ... */ ) - - - kratos.getSelfServiceVerificationFlow(flow).then((flow) => /* ... */ ) - + kratos.getSelfServiceVerificationFlow(flow, req.header('cookie')).then((flow) => /* ... */ ) - - - kratos.getSelfServiceSettingsFlow(flow).then((flow) => /* ... */ ) - + kratos.getSelfServiceSettingsFlow(flow, undefined, req.header('cookie')).then((flow) => /* ... */ ) - }) - ``` - - For concrete details, check out - [the changes in the NodeJS app](https://github.com/ory/kratos-selfservice-ui-node/commit/e7fa292968111e06401fcfc9b1dd0e8e285a4d87). - -1. This patch refactors the logout functionality for browsers and APIs. It adds - increased security and DoS-defenses to the logout flow. Previously, calling - `GET /self-service/browser/flows/logout` would remove the session cookie and - redirect the user to the logout endpoint. Now you have to make a call to - `GET /self-service/logout/browser` which returns a JSON response including a - `logout_url` URL to be used for logout. The call to - `/self-service/logout/browser` must be made using AJAX with cookies enabled - or by including the Ory Session Cookie in the `X-Session-Cookie` HTTP - Header. You may also use the SDK method - `createSelfServiceLogoutUrlForBrowsers` to do that. - - Additionally, the endpoint `DELETE /sessions` has been moved to - `DELETE /self-service/logout/api`. Payloads and responses stay equal. The - SDK method `revokeSession` has been renamed to - `submitSelfServiceLogoutFlowWithoutBrowser`. - -1. Several SDK methods have been renamed: - - - `initializeSelfServiceRecoveryForNativeApps` to - `initializeSelfServiceRecoveryWithoutBrowser`. - - `initializeSelfServiceVerificationForNativeApps` to - `initializeSelfServiceVerificationWithoutBrowser` - - `initializeSelfServiceSettingsForNativeApps` to - `initializeSelfServiceSettingsWithoutBrowser`. - - `initializeSelfServiceregistrationForNativeApps` to - `initializeSelfServiceregistrationWithoutBrowser`. - - `initializeSelfServiceLoginForNativeApps` to - `initializeSelfServiceLoginWithoutBrowser`. - - As in the previous release you may still use the old SDK if you do not want - to deal with the SDK breaking changes for now. - -## Ory Kratos v0.8 Breaking changes - -Full list of changes: -https://github.com/ory/kratos/blob/v0.8.0-alpha.1/CHANGELOG.md#breaking-changes - -1. The location of the homebrew tap has changed from `ory/ory/kratos` to - `ory/tap/kratos`. - -1. The self-service login flow's `forced` key has been renamed to `refresh`. - -1. The SDKs are now generated with tag v0alpha2 to reflect that some signatures - have changed in a breaking fashion. Please update your imports from - `v0alpha1` to `v0alpha2`. - -1. To support 2FA on non-browser (e.g. native mobile) apps we have added the Ory - Session Token as a possible parameter to both - `initializeSelfServiceLoginFlowWithoutBrowser` and - `submitSelfServiceLoginFlow`. Depending on the SDK generator, the order of - the arguments may have changed. In JavaScript: - - ```diff - - .submitSelfServiceLoginFlow(flow.id, payload) - + .submitSelfServiceLoginFlow(flow.id, sessionToken, payload) - // or if the user has no session yet: - + .submitSelfServiceLoginFlow(flow.id, undefined, payload) - ``` - -1. To improve the overall API design we have changed the result of - `POST /self-service/settings`. Instead of having flow be a key, the flow is - now the response. The updated identity payload stays the same! - - ```diff - { - - "flow": { - - "id": "flow-id-..." - - ... - - }, - + "id": "flow-id-..." - + ... - "identity": { - "id": "identity-id-..." - } - } - ``` - -1. The SMTPS scheme used in courier config url with cleartext/StartTLS/TLS SMTP - connection types is now only supporting implicit TLS. For StartTLS and - cleartext SMTP, please use the smtp scheme instead. - - Example: - - - SMTP Cleartext: `smtp://foo:bar@my-mailserver:1234/?disable_starttls=true` - - SMTP with StartTLS: `smtps://foo:bar@my-mailserver:1234/` -> - `smtp://foo:bar@my-mailserver:1234/` - - SMTP with implicit TLS: - `smtps://foo:bar@my-mailserver:1234/?legacy_ssl=true` -> - `smtps://foo:bar@my-mailserver:1234/` - -1. This patch changes the naming and number of prometheus metrics (see: - https://github.com/ory/x/pull/379). In short: all metrics will have now - `http_` prefix to conform to Prometheus best practices. diff --git a/docs/docs/guides/upgrade.md b/docs/docs/guides/upgrade.md new file mode 100644 index 00000000000..982dc1223ce --- /dev/null +++ b/docs/docs/guides/upgrade.md @@ -0,0 +1,63 @@ +--- +id: upgrade +title: Applying Upgrades +--- + +This guide covers basics to consider when upgrading Ory Kratos, please also +visit [UPGRADE.md](https://github.com/ory/kratos/blob/master/UPGRADE.md) for more technical details. + + +Generally upgrading Ory Kratos can be split into three main steps: + +- Make a backup. +- [Install](/install.md) the new version (depending on how you run Ory Kratos). +- Run [`kratos migrate sql`](../cli/kratos-migrate-sql.md) to run the appropriate SQL queries. + +Ory Kratos will run the `migrate sql` command for all versions. For example when upgrading from v0.6 to v0.8, the migrations will be run for v0.6 to v0.7 and then for v0.7 to v0.8. As such upgrading from any version to the latest version directly is possible. Should you run into problems with a direct upgrade, consider a stepped upgrade and please visit the community [chat](https://slack.ory.sh/) or [discussions](https://github.com/ory/kratos/discussions). + +:::warning + +Back up your data! +Applying upgrades can lead to data loss if handled incorrectly. + +::: + +### Upgrading Tips + +We recommend taking the following steps to ensure that no data is lost: + +>Please note: These are recommendations and should be used in accordance with other Ops best practices. The steps required for a smooth and secure upgrade process may vary with different setups, tech stacks, and environments. + +1. Write down a high-level upgrade plan +- Who will perform the upgrade? +- How will the upgrade be performed? +- What components are affected? +2. Devise roll-out plan +- When will the upgrade be performed? +- Will there be an outage? +- How long will it be? +- What is your rollback plan? +3. Back up everything! +4. Run a trial upgrade on a local environment. +5. Run an upgrade on a staging environment. +6. Perform tests on staging & prepare production environment. +7. Run the upgrade on production. + +### Breaking changes overview + +- __[Ory Kratos v0.8 Breaking changes](https://github.com/ory/kratos/blob/v0.8.0-alpha.1/CHANGELOG.md#breaking-changes)__ + +- __[Ory Kratos v0.7 Breaking changes](https://github.com/ory/kratos/blob/v0.7.0-alpha.1/CHANGELOG.md#breaking-changes)__ + +- __[Ory Kratos v0.6 Breaking changes](https://github.com/ory/kratos/blob/v0.6.0-alpha.1/CHANGELOG.md#breaking-changes)__ + +- __[Ory Kratos v0.5 Breaking changes](https://github.com/ory/kratos/blob/v0.5.0-alpha.1/CHANGELOG.md#breaking-changes)__ + +For older Ory Kratos versions, visit [UPGRADE.md](https://github.com/ory/kratos/blob/master/UPGRADE.md) + +:::note + +Skip the hassle of applying upgrades to Ory Kratos? +Take a look at [Ory Cloud](https://www.ory.sh/docs/#ory-cloud). + +::: \ No newline at end of file diff --git a/docs/sidebar.json b/docs/sidebar.json index 0703e3e99a6..145e38eebb6 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -74,7 +74,8 @@ "guides/https-tls", "guides/setting-up-password-hashing-parameters", "guides/integration-with-other-systems-using-web-hooks", - "guides/tracing" + "guides/tracing", + "guides/upgrade" ] }, "reference/api", @@ -119,9 +120,7 @@ "debug/troubleshooting", "debug/csrf", "debug/performance-out-of-memory-password-hashing-argon2", - "debug/debug-docker-delve-ory-kratos", - "debug/upgrade" - ] + "debug/debug-docker-delve-ory-kratos" ] }, { "SDKs": ["sdk"] From e97ebe19bd893618916f1cc424e3839f7570e122 Mon Sep 17 00:00:00 2001 From: vinckr Date: Tue, 11 Jan 2022 13:52:00 +0100 Subject: [PATCH 05/11] chore: format --- docs/docs/guides/upgrade.md | 62 +++++++++++++++++++++++-------------- docs/sidebar.json | 3 +- 2 files changed, 40 insertions(+), 25 deletions(-) diff --git a/docs/docs/guides/upgrade.md b/docs/docs/guides/upgrade.md index 982dc1223ce..ae61605411e 100644 --- a/docs/docs/guides/upgrade.md +++ b/docs/docs/guides/upgrade.md @@ -4,60 +4,74 @@ title: Applying Upgrades --- This guide covers basics to consider when upgrading Ory Kratos, please also -visit [UPGRADE.md](https://github.com/ory/kratos/blob/master/UPGRADE.md) for more technical details. +visit [UPGRADE.md](https://github.com/ory/kratos/blob/master/UPGRADE.md) for +more technical details. - -Generally upgrading Ory Kratos can be split into three main steps: +Generally upgrading Ory Kratos can be split into three main steps: - Make a backup. - [Install](/install.md) the new version (depending on how you run Ory Kratos). -- Run [`kratos migrate sql`](../cli/kratos-migrate-sql.md) to run the appropriate SQL queries. +- Run [`kratos migrate sql`](../cli/kratos-migrate-sql.md) to run the + appropriate SQL queries. -Ory Kratos will run the `migrate sql` command for all versions. For example when upgrading from v0.6 to v0.8, the migrations will be run for v0.6 to v0.7 and then for v0.7 to v0.8. As such upgrading from any version to the latest version directly is possible. Should you run into problems with a direct upgrade, consider a stepped upgrade and please visit the community [chat](https://slack.ory.sh/) or [discussions](https://github.com/ory/kratos/discussions). +Ory Kratos will run the `migrate sql` command for all versions. For example when +upgrading from v0.6 to v0.8, the migrations will be run for v0.6 to v0.7 and +then for v0.7 to v0.8. As such upgrading from any version to the latest version +directly is possible. Should you run into problems with a direct upgrade, +consider a stepped upgrade and please visit the community +[chat](https://slack.ory.sh/) or +[discussions](https://github.com/ory/kratos/discussions). -:::warning +:::warning -Back up your data! -Applying upgrades can lead to data loss if handled incorrectly. +Back up your data! Applying upgrades can lead to data loss if handled +incorrectly. ::: -### Upgrading Tips +### Upgrading Tips We recommend taking the following steps to ensure that no data is lost: ->Please note: These are recommendations and should be used in accordance with other Ops best practices. The steps required for a smooth and secure upgrade process may vary with different setups, tech stacks, and environments. +> Please note: These are recommendations and should be used in accordance with +> other Ops best practices. The steps required for a smooth and secure upgrade +> process may vary with different setups, tech stacks, and environments. 1. Write down a high-level upgrade plan + - Who will perform the upgrade? - How will the upgrade be performed? -- What components are affected? +- What components are affected? + 2. Devise roll-out plan -- When will the upgrade be performed? -- Will there be an outage? -- How long will it be? + +- When will the upgrade be performed? +- Will there be an outage? +- How long will it be? - What is your rollback plan? + 3. Back up everything! 4. Run a trial upgrade on a local environment. 5. Run an upgrade on a staging environment. -6. Perform tests on staging & prepare production environment. +6. Perform tests on staging & prepare production environment. 7. Run the upgrade on production. ### Breaking changes overview -- __[Ory Kratos v0.8 Breaking changes](https://github.com/ory/kratos/blob/v0.8.0-alpha.1/CHANGELOG.md#breaking-changes)__ +- **[Ory Kratos v0.8 Breaking changes](https://github.com/ory/kratos/blob/v0.8.0-alpha.1/CHANGELOG.md#breaking-changes)** -- __[Ory Kratos v0.7 Breaking changes](https://github.com/ory/kratos/blob/v0.7.0-alpha.1/CHANGELOG.md#breaking-changes)__ +- **[Ory Kratos v0.7 Breaking changes](https://github.com/ory/kratos/blob/v0.7.0-alpha.1/CHANGELOG.md#breaking-changes)** -- __[Ory Kratos v0.6 Breaking changes](https://github.com/ory/kratos/blob/v0.6.0-alpha.1/CHANGELOG.md#breaking-changes)__ +- **[Ory Kratos v0.6 Breaking changes](https://github.com/ory/kratos/blob/v0.6.0-alpha.1/CHANGELOG.md#breaking-changes)** -- __[Ory Kratos v0.5 Breaking changes](https://github.com/ory/kratos/blob/v0.5.0-alpha.1/CHANGELOG.md#breaking-changes)__ +- **[Ory Kratos v0.5 Breaking changes](https://github.com/ory/kratos/blob/v0.5.0-alpha.1/CHANGELOG.md#breaking-changes)** -For older Ory Kratos versions, visit [UPGRADE.md](https://github.com/ory/kratos/blob/master/UPGRADE.md) +For older Ory Kratos versions, visit +[UPGRADE.md](https://github.com/ory/kratos/blob/master/UPGRADE.md) -:::note +:::note -Skip the hassle of applying upgrades to Ory Kratos? -Take a look at [Ory Cloud](https://www.ory.sh/docs/#ory-cloud). +Skip the hassle of applying upgrades to Ory Kratos? Take a look at +[Ory Cloud](https://www.ory.sh/docs/#ory-cloud). -::: \ No newline at end of file +::: diff --git a/docs/sidebar.json b/docs/sidebar.json index 145e38eebb6..96162ac1d66 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -120,7 +120,8 @@ "debug/troubleshooting", "debug/csrf", "debug/performance-out-of-memory-password-hashing-argon2", - "debug/debug-docker-delve-ory-kratos" ] + "debug/debug-docker-delve-ory-kratos" + ] }, { "SDKs": ["sdk"] From c2515af6f0c37077d75a842b56e169495c5071dd Mon Sep 17 00:00:00 2001 From: vinckr Date: Tue, 11 Jan 2022 14:12:01 +0100 Subject: [PATCH 06/11] fix: delete UPGRADE.md --- UPGRADE.md | 125 ----------------------------------------------------- 1 file changed, 125 deletions(-) delete mode 100644 UPGRADE.md diff --git a/UPGRADE.md b/UPGRADE.md deleted file mode 100644 index b13c7375288..00000000000 --- a/UPGRADE.md +++ /dev/null @@ -1,125 +0,0 @@ -# Upgrading - -The intent of this document is to make migration of breaking changes as easy as -possible. Please note that not all breaking changes might be included here. -Please check the [CHANGELOG.md](./CHANGELOG.md) for a full list of changes -before finalizing the upgrade process. - -## v0.8.0-alpha.1 - -This version includes a lot of new features, but includes few breaking changes, mostly around the SDKs. -For a full list of breaking changes please visit the [CHANGELOG](https://github.com/ory/kratos/blob/master/CHANGELOG.md#080-alpha1-2021-10-27). - -## v0.7.0-alpha.1 - -A new SDK has been introduced in this version, please visit the [CHANGELOG](https://github.com/ory/kratos/blob/master/CHANGELOG.md#070-alpha1-2021-07-13) to get a full overview of the SDK and other breaking changes. - -## v0.6.0-alpha.1 - -BCrypt is now the default hashing algorithm. You must apply SQL migrations for this upgrade, this will invalidate all ongoing self-service flows and purge existing self-service forms. If you wish to keep these records, make a back up of your database prior! -For a full list of breaking changes please visit the [CHANGELOG](https://github.com/ory/kratos/blob/master/CHANGELOG.md#060-alpha1-2021-05-05). - -## v0.5.0-alpha.1 - -For a full list of breaking changes please visit the [CHANGELOG](https://github.com/ory/kratos/blob/master/CHANGELOG.md#050-alpha1-2020-10-15). - -## v0.4.0-alpha.1 - -Please visit the [CHANGELOG](https://github.com/ory/kratos/blob/master/CHANGELOG.md#040-alpha1-2020-07-08). - -## v0.3.0-alpha.1 - -This release finalizes the OpenID Connect and OAuth2 login, registration, and settings strategy with JsonNet data transformation! From now on, "Sign in with Google, Github, ..." is officially supported! It's also possible to link and unlink these connections using the Self-Service Settings Flow! The documentation has been updated to reflect those changes and includes guides to setting up "Sign in with GitHub" in under 5 Minutes! Please be aware that existing OpenID Connect connections will stop working. Check out the "Breaking Changes" section for more info! Want to learn more? Check [out the docs](https://www.ory.sh/kratos/docs/concepts/credentials/openid-connect-oidc-oauth2)! - -We changed the config validation output, making it easier than ever to find bugs in your config: - -``` -% kratos --config invalid-config.yml serve -INFO[0001] Config file loaded successfully. path=invalid-config.yml -ERRO[0001] The provided configuration is invalid and could not be loaded. Check the output below to understand why. config_file=invalid-config.yml - -dsn: - ^-- one or more required properties are missing - -urls.whitelisted_return_to_urls: https://selfservice.office.example.com - ^-- expected array, but got string - -FATA[0001] The services failed to start because the configuration is invalid. Check the output above for more details. -``` - -This release concludes over 50 commits and 16.000 lines of code changed. - -## v0.2.0-alpha.2 - -This is a heavy release with over hundreds of commits and files changed! Let's -take a look at some of the highlights! - -### Ory Oathkeeper now optional - -Using Ory Oathkeeper to protect your API is now optional. The basic quickstart -now uses a much simpler set up. Go -[check it out](https://www.ory.sh/kratos/docs/quickstart) now! - -### PostgreSQL, MySQL, CockroachDB support now tested and official! - -All three databases now pass acceptance tests and are thus officially supported! - -### Self-Service Profile Flow - -The self-service profile flow has been refactored into a more generic flow -allowing users to make modifications to their traits and credentials. Check out -the [docs to learn -more]([here](https://www.ory.sh/kratos/docs/self-service/flows/user-settings-profile-management) -about the flow and it's features. - -Please keep in mind that the flow's APIs have changed. We recommend re-reading -the docs! - -### Managing Privileged Profile Fields - -Flows such as changing ones profile or primary email address should not be -possible unless the login session is fresh. This prevents your colleague or evil -friend to take over your account while you make yourself a coffee. - -Ory Kratos now supports this by redirecting the user to the login screen if -changes to sensitive fields are made. The changes will only be applied after -successful reauthentication. - -### Changes to Hooks - -This patch focuses on refactoring how self-service flows terminate and changes -how hooks behave and when they are executed. - -Before this patch, it was not clear whether hooks run before or after an -identity is persisted. This caused problems with multiple writes on the HTTP -ResponseWriter and other bugs. - -This patch removes certain hooks from after login, registration, and profile -flows. Per default, these flows now respond with an appropriate payload ( -redirect for browsers, JSON for API clients) and deprecate the `redirect` hook. -This patch includes documentation which explains how these hooks work now. - -Additionally, the documentation was updated. Especially the sections about hooks -have been refactored. The login and user registration docs have been updated to -reflect the latest changes as well. - -BREAKING CHANGE: Please remove the `redirect` hook from both login, -registration, and settings after configuration. Please remove the `session` hook -from your login after configuration. Hooks have moved down a level and are now -configured at `selfservice...hooks` -instead of `selfservice..`. -Hooks are now identified by `hook:` instead of `job:`. Please rename those -sections accordingly. - -We recommend re-reading the -[Hooks Documentation](https://www.ory.sh/kratos/docs/self-service/hooks/index). - -### Changing Passwords - -It's now possible to change your password using the Self-Service Settings Flow! -Lean more about this flow -[here](https://www.ory.sh/kratos/docs/self-service/flows/user-settings-profile-management) - -### End-To-End Tests - -We added tons of end-to-end and integration tests to find and fix pesky bugs. From 8fdfac4af9121c51932b7b09f4254275b2f5930b Mon Sep 17 00:00:00 2001 From: vinckr Date: Tue, 11 Jan 2022 14:12:32 +0100 Subject: [PATCH 07/11] fix: correct formatting+links --- docs/docs/guides/upgrade.md | 23 ++++++++--------------- 1 file changed, 8 insertions(+), 15 deletions(-) diff --git a/docs/docs/guides/upgrade.md b/docs/docs/guides/upgrade.md index ae61605411e..797a69d3fce 100644 --- a/docs/docs/guides/upgrade.md +++ b/docs/docs/guides/upgrade.md @@ -38,18 +38,14 @@ We recommend taking the following steps to ensure that no data is lost: > process may vary with different setups, tech stacks, and environments. 1. Write down a high-level upgrade plan - -- Who will perform the upgrade? -- How will the upgrade be performed? -- What components are affected? - + - Who will perform the upgrade? + - How will the upgrade be performed? + - What components are affected? 2. Devise roll-out plan - -- When will the upgrade be performed? -- Will there be an outage? -- How long will it be? -- What is your rollback plan? - + - When will the upgrade be performed? + - Will there be an outage? + - How long will it be? + - What is your rollback plan? 3. Back up everything! 4. Run a trial upgrade on a local environment. 5. Run an upgrade on a staging environment. @@ -59,11 +55,8 @@ We recommend taking the following steps to ensure that no data is lost: ### Breaking changes overview - **[Ory Kratos v0.8 Breaking changes](https://github.com/ory/kratos/blob/v0.8.0-alpha.1/CHANGELOG.md#breaking-changes)** - - **[Ory Kratos v0.7 Breaking changes](https://github.com/ory/kratos/blob/v0.7.0-alpha.1/CHANGELOG.md#breaking-changes)** - - **[Ory Kratos v0.6 Breaking changes](https://github.com/ory/kratos/blob/v0.6.0-alpha.1/CHANGELOG.md#breaking-changes)** - - **[Ory Kratos v0.5 Breaking changes](https://github.com/ory/kratos/blob/v0.5.0-alpha.1/CHANGELOG.md#breaking-changes)** For older Ory Kratos versions, visit @@ -72,6 +65,6 @@ For older Ory Kratos versions, visit :::note Skip the hassle of applying upgrades to Ory Kratos? Take a look at -[Ory Cloud](https://www.ory.sh/docs/#ory-cloud). +[Ory Cloud](https://www.ory.sh/docs). ::: From 93becae15cbdd767ebdcb10330b096918100d938 Mon Sep 17 00:00:00 2001 From: vinckr Date: Tue, 11 Jan 2022 14:14:45 +0100 Subject: [PATCH 08/11] chore : format2 --- docs/docs/guides/upgrade.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/docs/guides/upgrade.md b/docs/docs/guides/upgrade.md index 797a69d3fce..918428feebe 100644 --- a/docs/docs/guides/upgrade.md +++ b/docs/docs/guides/upgrade.md @@ -38,14 +38,18 @@ We recommend taking the following steps to ensure that no data is lost: > process may vary with different setups, tech stacks, and environments. 1. Write down a high-level upgrade plan - - Who will perform the upgrade? - - How will the upgrade be performed? - - What components are affected? + + - Who will perform the upgrade? + - How will the upgrade be performed? + - What components are affected? + 2. Devise roll-out plan - - When will the upgrade be performed? - - Will there be an outage? - - How long will it be? - - What is your rollback plan? + + - When will the upgrade be performed? + - Will there be an outage? + - How long will it be? + - What is your rollback plan? + 3. Back up everything! 4. Run a trial upgrade on a local environment. 5. Run an upgrade on a staging environment. From c5d612956e4af5c16e99fdfb130cc29e123d58c2 Mon Sep 17 00:00:00 2001 From: vinckr Date: Tue, 11 Jan 2022 14:15:40 +0100 Subject: [PATCH 09/11] chore: list format --- docs/docs/guides/upgrade.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/docs/guides/upgrade.md b/docs/docs/guides/upgrade.md index 918428feebe..6d2698bec5e 100644 --- a/docs/docs/guides/upgrade.md +++ b/docs/docs/guides/upgrade.md @@ -38,18 +38,14 @@ We recommend taking the following steps to ensure that no data is lost: > process may vary with different setups, tech stacks, and environments. 1. Write down a high-level upgrade plan - - Who will perform the upgrade? - How will the upgrade be performed? - What components are affected? - 2. Devise roll-out plan - - When will the upgrade be performed? - Will there be an outage? - How long will it be? - What is your rollback plan? - 3. Back up everything! 4. Run a trial upgrade on a local environment. 5. Run an upgrade on a staging environment. From 76c2eaddb61a870275a8276edc524a1cd67c0d48 Mon Sep 17 00:00:00 2001 From: vinckr Date: Tue, 11 Jan 2022 14:22:22 +0100 Subject: [PATCH 10/11] chore: remove UPGRADE.md links --- docs/docs/guides/upgrade.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/docs/guides/upgrade.md b/docs/docs/guides/upgrade.md index 6d2698bec5e..549c3cf6cd2 100644 --- a/docs/docs/guides/upgrade.md +++ b/docs/docs/guides/upgrade.md @@ -4,7 +4,7 @@ title: Applying Upgrades --- This guide covers basics to consider when upgrading Ory Kratos, please also -visit [UPGRADE.md](https://github.com/ory/kratos/blob/master/UPGRADE.md) for +visit [CHANGELOG.md](https://github.com/ory/kratos/blob/master/CHANGELOG.md) for more technical details. Generally upgrading Ory Kratos can be split into three main steps: @@ -59,9 +59,6 @@ We recommend taking the following steps to ensure that no data is lost: - **[Ory Kratos v0.6 Breaking changes](https://github.com/ory/kratos/blob/v0.6.0-alpha.1/CHANGELOG.md#breaking-changes)** - **[Ory Kratos v0.5 Breaking changes](https://github.com/ory/kratos/blob/v0.5.0-alpha.1/CHANGELOG.md#breaking-changes)** -For older Ory Kratos versions, visit -[UPGRADE.md](https://github.com/ory/kratos/blob/master/UPGRADE.md) - :::note Skip the hassle of applying upgrades to Ory Kratos? Take a look at From 366e67174773d07eb4dddfc0bc09e86fbec6c386 Mon Sep 17 00:00:00 2001 From: vinckr Date: Tue, 11 Jan 2022 14:27:26 +0100 Subject: [PATCH 11/11] chore: remove UPGRADE.md link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2061d2430e3..844a4e568ff 100644 --- a/README.md +++ b/README.md @@ -385,7 +385,7 @@ The HTTP API is documented [here](https://www.ory.sh/kratos/docs/sdk/api). ### Upgrading and Changelog New releases might introduce breaking changes. To help you identify and incorporate those changes, we document these -changes in [UPGRADE.md](./UPGRADE.md) and [CHANGELOG.md](./CHANGELOG.md). +changes in the [CHANGELOG.md](./CHANGELOG.md). For upgrading, please visit the [upgrade guide](https://www.ory.sh/kratos/docs/guides/upgrade). ### Command line documentation