Document best practices when upgrading Fastly#3188
Conversation
Preview of modified filesPreview of modified Markdown: |
|
|
|
||
| Before you move on to production, clone your production Fastly service to validate the infrastructure layer safely: | ||
|
|
||
| 1. Clone the service: In the Fastly UI, clone your active production service to create a temporary, test version. |
There was a problem hiding this comment.
Fastly UI is not available for Ibexa Cloud customers, that means 99% of our customers that uses Fastly. So not sure how applicable this is..
It should be possible to create a free account and fastly and use that, but cloning existing production is not an an option for most customers
AFAIK, all cloud customers that are entitled to Fastly, also have a staging environment where Fastly is/should be enabled. One of the ideas with this staging environment is to test for instance Fastly integration
|
|
||
| ## Update Fastly configuration safely | ||
|
|
||
| When you upgrade [[= product_name =]], do not reuse legacy VCL files. |
There was a problem hiding this comment.
I think we should mentioned explicitly in the upgrade docs if fastly .vcl files changes ( they don't change that often ). The burden on checking if they change should be on us, not every customer IMO
|
|
||
| To mitigate these issues, follow these recommendations and best practices: | ||
|
|
||
| #### Cookie and session handling |
There was a problem hiding this comment.
In this chapter you are very specific on a problem that occurs if you don't upgrade .vcl files when upgrading from 4.6 to 5.0. And I feel the recommendations given below avoids the heart of the problem. Client needs to upgrade .vcl files.. ( they have also changed names from 4.6 to 5.0).
AFAIK, we only mentioned that one one line, here : https://doc.ibexa.co/en/5.0/update_and_migration/from_4.6/update_to_5.0/#http-cache
And we don't say how to do it... I think this would be the place to start ?
| - Validate that session cookies correctly trigger cache bypass where needed. | ||
| - Review all cookie-based conditions in VCL and update outdated cookie references. | ||
| - Avoid relying on exact cookie names. Use pattern matching where possible to reduce the impact of cookie naming changes. | ||
| - Consider temporary support for both old and new cookie identifiers during transition. |
There was a problem hiding this comment.
I think I would remove all those recommendations and instead give user a way of comparing current deployed .vcls vs the one in vendor/fastly/fastly/
Unfortunately, there is no straight way for doing that, but this doc can help.
However, diffing the downloaded versions vs our dist vcl will never be exactly the same ( there are various snippets etc as well which will be included in the downloaded version ), but diffing the two would help a trained eye.
For an untrained-eye, I think user needs to create a new version in Fastly service, re-upload all the vcls and snippets to that version. Then download the active version and mentioned the newer version and then compare.
There was a problem hiding this comment.
Actually, I think you may download each individally vcl using:
fastly service vcl custom describe --service-id <SERVICE_ID> --version <VERSION_NUMBER> --name <VCL_NAME>
If there is something similar for snippets too, then it should be possible to compare our distributed .vcl files vs those installed. In this conntext, user should also check that the ibexa_main.vcl file is marked as main, ref: https://doc.ibexa.co/en/5.0/infrastructure_and_maintenance/cache/http_cache/fastly/#list-custom-vcl-files-for-specific-version
If ibexa_user_hash.vcl is marked as main, the configuration will not work
|
|
||
| !!! note "Fastly considerations" | ||
|
|
||
| Version updates may introduce changes (for example, to cookies or caching behavior) that could require modifications in Fastly/VCL configuration. |
There was a problem hiding this comment.
There is no "may introduce changes" here. We know for a fact that there are changes. User must update vcl configuration. Only reviewing them is not enough
3 participants
Document best practices when upgrading Fastly
Checklist