[Durable Objects] Add documentation for gradual deployments for Durable Objects. by jp4a50 · Pull Request #13564 · cloudflare/cloudflare-docs

jp4a50 · 2024-03-21T21:19:31Z

No description provided.

content/workers/configuration/versions-and-deployments/gradual-deployments.md

vy-ton · 2024-03-21T21:41:33Z

content/workers/configuration/versions-and-deployments/gradual-deployments.md

+- For a given deployment, requests to each Durable Object will always use the same Worker version.
+- When you specify each version in the same order as the previous deployment and increase the percentage of a version, Durable Objects which were previously assigned that version will not be assigned a different version. In our example, Durable Object "foo" would never revert from version "B" to version "A".
+- The Durable Object will only be [reset](/durable-objects/reference/troubleshooting/#durable-object-reset-because-its-code-was-updated) when it is assigned a different version, so each Durable Object will only be reset once in our example.
+


Should we add a bullet for Websockets not being disconnected with gradual rollouts? I believe we can't remove https://github.com/cloudflare/cloudflare-docs/blob/production/content/durable-objects/reference/websockets.md?plain=1#L23 just yet

Websockets will still be disconnected whenever a specific Durable Object's code is updated. The difference is that a gradual deployment may only update the code for a subset of DOs now, so only websockets to those DOs will be disconnected.

I think ideally we should have a dedicated section on Durable Object resets which defines when they happen and their side effects (e.g. websockets being disconnected) and both the above documentation and the documentation in your link should reference that.

What d'you think?

Makes sense, I'll track the DO reset behavior docs.

content/workers/configuration/versions-and-deployments/gradual-deployments.md

JoshuaClaeys · 2024-03-27T00:07:15Z

content/workers/configuration/versions-and-deployments/gradual-deployments.md

 ```
 You should see 10 responses. Responses will reflect the content returned by the versions in your deployment. Responses will vary depending on the percentages configured in step #6. 

+## Gradual deployments for Durable Objects


I would love see a section that directly addresses forwards and backwards compatibility requirements between eyeball Worker and Durable Objects during a release (old eyeball talks to new DO and new eyeball talks to old DO).

If this is already mentioned elsewhere outside of gradual deployments page (if not, I think it should be), this could be as simple as a link and mentioning that this easily missed compatibility issue will be exacerbated with gradual deployments.

Good call. The requirement for forwards and backwards compatibility for durable objects and the worker that talks to them is briefly mentioned here so I will link to that for now and elaborate on how gradual deployments affects this problem.

I think we could generally do with a section explaining compatibility requirements more generally. I started drafting a new section in the "Versions & Deployments" page that was added in @tanushree-sharma 's PR but it's tricky to explain this in general terms without introducing new terminology and/or using diagrams/example code so I'll leave that for another time.

content/workers/configuration/versions-and-deployments/gradual-deployments.md

cloudflare-workers-and-pages · 2024-03-28T21:02:20Z

Deploying cloudflare-docs with Cloudflare Pages

Latest commit:	`be02af1`
Status:	✅ Deploy successful!
Preview URL:	https://610e40ea.cloudflare-docs-7ou.pages.dev
Branch Preview URL:	https://jphillips-do-gradual-deploym.cloudflare-docs-7ou.pages.dev

View logs

github-actions · 2024-03-28T21:10:55Z

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/workers/configuration/versions-and-deployments/gradual-deployments/	https://jphillips-do-gradual-deploym.cloudflare-docs-7ou.pages.dev/workers/configuration/versions-and-deployments/gradual-deployments/
https://developers.cloudflare.com/durable-objects/configuration/durable-object-gradual-deployments/	https://jphillips-do-gradual-deploym.cloudflare-docs-7ou.pages.dev/durable-objects/configuration/durable-object-gradual-deployments/
https://developers.cloudflare.com/durable-objects/platform/known-issues/	https://jphillips-do-gradual-deploym.cloudflare-docs-7ou.pages.dev/durable-objects/platform/known-issues/

irvinebroque

Merge conflicts then 🚀

content/workers/configuration/versions-and-deployments/gradual-deployments.md

irvinebroque · 2024-03-29T03:16:45Z

content/workers/configuration/versions-and-deployments/gradual-deployments.md

+
+Typically, your Durable Object Worker will define both your Durable Object class and the Worker that interacts with it. In this case, you cannot deploy changes to your Durable Object and its Worker independently.
+
+[You are advised](/durable-objects/platform/known-issues/#code-updates) to ensure that API changes between your Durable Object and its Worker are forwards and backwards compatible whether you are using gradual deployments or not. However, using gradual deployments will make it even more likely that different versions of your Durable Objects and its Worker will interact with each other.


Suggested change

[You are advised](/durable-objects/platform/known-issues/#code-updates) to ensure that API changes between your Durable Object and its Worker are forwards and backwards compatible whether you are using gradual deployments or not. However, using gradual deployments will make it even more likely that different versions of your Durable Objects and its Worker will interact with each other.

[You should](/durable-objects/platform/known-issues/#code-updates) ensure that API changes between your Durable Object and its Worker are forwards and backwards compatible, regardless of whether you are using gradual deployments or not. However, using gradual deployments will make it even more likely that different versions of your Durable Objects and its Worker will interact with each other.

content/workers/configuration/versions-and-deployments/gradual-deployments.md

deadlypants1973 · 2024-04-01T16:45:43Z

This PR seems to be carrying over content that was already edited, reviewed and pushed last week on #13429 and rewriting it to its pre-reviewed state.

Does this need a rebase? @jp4a50

jp4a50 · 2024-04-02T12:21:42Z

This PR seems to be carrying over content that was already edited, reviewed and pushed last week on #13429 and rewriting it to its pre-reviewed state.

Does this need a rebase? @jp4a50

Yep, it was because I originally targeted the branch used for #13429 which was squashed, merged and deleted. I've rebased now.

This PR is ready to merge now as far as I'm concerned.

irvinebroque · 2024-04-02T13:33:51Z

content/durable-objects/platform/known-issues.md

 ## Code updates

-Code changes for Workers and Durable Objects are released globally in an eventually consistent manner. Because each Durable Object is globally unique, the situation can arise that a request arrives to the latest version of your Worker (running in one part of the world), which then calls to a unique Durable Object running the previous version of your code for a short period of time (typically seconds to minutes).
+Code changes for Workers and Durable Objects are released globally in an eventually consistent manner. Because each Durable Object is globally unique, the situation can arise that a request arrives to the latest version of your Worker (running in one part of the world), which then calls to a unique Durable Object running the previous version of your code for a short period of time. If you create a [gradual deployment](/workers/configuration/versions-and-deployments/gradual-deployments/), this period of time is determined by however long your live deployment is configured to use more than one version.


Probably keep the "typiccally seconds to minutes" piece for the base case scenario

Maddy-Cloudflare · 2024-04-03T15:28:54Z

content/durable-objects/configuration/durable-object-gradual-deployments.md

@@ -0,0 +1,13 @@
+---
+pcx_content_type: navigation
+title: Gradual Deployments


Suggested change

title: Gradual Deployments

title: Gradual deployments

We usually capitalize Deployments elsewhere so leaving as-is.

content/durable-objects/platform/known-issues.md

content/workers/configuration/versions-and-deployments/gradual-deployments.md

Maddy-Cloudflare · 2024-04-03T15:32:06Z

content/workers/configuration/versions-and-deployments/gradual-deployments.md

+
+Imagine that you have previously created 3 Durable Objects, [deriving their IDs from the names](/durable-objects/configuration/access-durable-object-from-a-worker/#derive-ids-from-names) "foo", "bar" and "baz".
+
+Your Worker is currently on a version that we will call version "A" and you want to gradually deploy a new version "B" of your Worker.


Suggested change

Your Worker is currently on a version that we will call version "A" and you want to gradually deploy a new version "B" of your Worker.

Your Worker is currently on a version called version "A" and you want to gradually deploy a new version "B" of your Worker.

I'd like to leave this phrasing as-is to convey that this is just a made-up identifier, rather than the actual version ID.

content/workers/configuration/versions-and-deployments/gradual-deployments.md

Co-authored-by: Maddy <130055405+Maddy-Cloudflare@users.noreply.github.com>

irvinebroque · 2024-04-04T02:31:00Z

content/durable-objects/configuration/durable-object-gradual-deployments.md

+title: Gradual Deployments
+weight: 25
+
+external_link: /workers/configuration/versions-and-deployments/gradual-deployments/#gradual-deployments-for-durable-objects


adding this in DO docs was nice touch

…le Objects. (#13564) * Add documentation for gradual deployments for Durable Objects. * Address code review comments. * Make Durable Objects gradual deployments example more concise. * Fix broken links. * Minor code review. * add diagram and link * Apply suggestions from code review Co-authored-by: Maddy <130055405+Maddy-Cloudflare@users.noreply.github.com> --------- Co-authored-by: Tanushree Sharma <tanushree@cloudflare.com> Co-authored-by: Maddy <130055405+Maddy-Cloudflare@users.noreply.github.com>

jp4a50 requested review from irvinebroque and tanushree-sharma March 21, 2024 21:19

jp4a50 requested review from a team, GregBrimble and WalshyDev as code owners March 21, 2024 21:19

github-actions bot added size/s product:workers Related to Workers product labels Mar 21, 2024

github-actions bot assigned deadlypants1973 Mar 21, 2024

jp4a50 mentioned this pull request Mar 21, 2024

Add gradual deployments documentation the Cf-Worker-Version-Key header. #13554

Merged

jp4a50 commented Mar 21, 2024

View reviewed changes

content/workers/configuration/versions-and-deployments/gradual-deployments.md Outdated Show resolved Hide resolved

jp4a50 commented Mar 21, 2024

View reviewed changes

content/workers/configuration/versions-and-deployments/gradual-deployments.md Outdated Show resolved Hide resolved

vy-ton reviewed Mar 21, 2024

View reviewed changes

JoshuaClaeys reviewed Mar 26, 2024

View reviewed changes

content/workers/configuration/versions-and-deployments/gradual-deployments.md Outdated Show resolved Hide resolved

JoshuaClaeys reviewed Mar 27, 2024

View reviewed changes

content/workers/configuration/versions-and-deployments/gradual-deployments.md Outdated Show resolved Hide resolved

jp4a50 requested review from Maddy-Cloudflare, deadlypants1973, elithrar and joshthoward as code owners March 28, 2024 21:02

github-actions bot added the product:durable-objects Durable Objects: https://developers.cloudflare.com/workers/learning/using-durable-objects/ label Mar 28, 2024

irvinebroque approved these changes Mar 29, 2024

View reviewed changes

irvinebroque reviewed Mar 29, 2024

View reviewed changes

content/workers/configuration/versions-and-deployments/gradual-deployments.md Outdated Show resolved Hide resolved

irvinebroque reviewed Mar 29, 2024

View reviewed changes

Base automatically changed from gradual-deployments to production March 29, 2024 05:35

tanushree-sharma requested a review from jasnell as a code owner March 29, 2024 05:35

ndisidore reviewed Apr 1, 2024

View reviewed changes

content/workers/configuration/versions-and-deployments/gradual-deployments.md Outdated Show resolved Hide resolved

jp4a50 added 2 commits April 2, 2024 13:17

Add documentation for gradual deployments for Durable Objects.

de5b49b

Address code review comments.

795c5db

jp4a50 force-pushed the jphillips/do-gradual-deployments branch from c06d7d2 to 795c5db Compare April 2, 2024 12:19

jp4a50 added 2 commits April 2, 2024 13:59

Make Durable Objects gradual deployments example more concise.

5b73690

Fix broken links.

71b6cbf

irvinebroque approved these changes Apr 2, 2024

View reviewed changes

irvinebroque reviewed Apr 2, 2024

View reviewed changes

Minor code review.

45e3ee3

Maddy-Cloudflare changed the title ~~Add documentation for gradual deployments for Durable Objects.~~ [Durable Objects] Add documentation for gradual deployments for Durable Objects. Apr 2, 2024

add diagram and link

b04223e

tanushree-sharma approved these changes Apr 3, 2024

View reviewed changes

Maddy-Cloudflare approved these changes Apr 3, 2024

View reviewed changes

Apply suggestions from code review

be02af1

Co-authored-by: Maddy <130055405+Maddy-Cloudflare@users.noreply.github.com>

jp4a50 merged commit ebb1526 into production Apr 3, 2024

jp4a50 deleted the jphillips/do-gradual-deployments branch April 3, 2024 16:42

irvinebroque reviewed Apr 4, 2024

View reviewed changes


		Typically, your Durable Object Worker will define both your Durable Object class and the Worker that interacts with it. In this case, you cannot deploy changes to your Durable Object and its Worker independently.

		[You are advised](/durable-objects/platform/known-issues/#code-updates) to ensure that API changes between your Durable Object and its Worker are forwards and backwards compatible whether you are using gradual deployments or not. However, using gradual deployments will make it even more likely that different versions of your Durable Objects and its Worker will interact with each other.

	[You are advised](/durable-objects/platform/known-issues/#code-updates) to ensure that API changes between your Durable Object and its Worker are forwards and backwards compatible whether you are using gradual deployments or not. However, using gradual deployments will make it even more likely that different versions of your Durable Objects and its Worker will interact with each other.
	[You should](/durable-objects/platform/known-issues/#code-updates) ensure that API changes between your Durable Object and its Worker are forwards and backwards compatible, regardless of whether you are using gradual deployments or not. However, using gradual deployments will make it even more likely that different versions of your Durable Objects and its Worker will interact with each other.


		Imagine that you have previously created 3 Durable Objects, [deriving their IDs from the names](/durable-objects/configuration/access-durable-object-from-a-worker/#derive-ids-from-names) "foo", "bar" and "baz".

		Your Worker is currently on a version that we will call version "A" and you want to gradually deploy a new version "B" of your Worker.

	Your Worker is currently on a version that we will call version "A" and you want to gradually deploy a new version "B" of your Worker.
	Your Worker is currently on a version called version "A" and you want to gradually deploy a new version "B" of your Worker.

Conversation

jp4a50 commented Mar 21, 2024

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cloudflare-workers-and-pages bot commented Mar 28, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying cloudflare-docs with Cloudflare Pages

Uh oh!

github-actions bot commented Mar 28, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

irvinebroque left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

deadlypants1973 commented Apr 1, 2024

Uh oh!

jp4a50 commented Apr 2, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

irvinebroque Apr 4, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

cloudflare-workers-and-pages bot commented Mar 28, 2024 •

edited

Loading

github-actions bot commented Mar 28, 2024 •

edited

Loading

jp4a50 commented Apr 2, 2024 •

edited

Loading

irvinebroque Apr 4, 2024 •

edited

Loading