Skip to content

when available, ykey is preferred over xkey #498

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dbu merged 1 commit into from
Jun 18, 2021
Merged

when available, ykey is preferred over xkey #498

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 14 additions & 8 deletions doc/varnish-configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,14 @@ Tag Invalidation Using xkey
Since Varnish 4.1, you can use the official `xkey Varnish module`_ for better
performance with cache tags.

.. tip::

If you are using the payed "Varnish Plus" offering, you should use the
improved ykey feature instead of xkey. The `ykey documentation`_ explains
how to use the xkey headers to set up the ykey information. Instead of
including the ``fos_tags_xkey.vcl`` you would need to write your own VCL to
handle ykey tagging and invalidation requests.

As explained in the `Cache Invalidation chapter of the Varnish documentation`_::
> (..), ``hashtwo``/``xkey`` is much more efficient than bans because of two reasons:
> 1) looking up hash keys is much more efficient than traversing ban-lists, and
Expand All @@ -192,13 +200,10 @@ As explained in the `Cache Invalidation chapter of the Varnish documentation`_::
With xkey, you can also soft purge tagged responses to allow for a grace period
where invalidated (stale) content is still delivered to the client.

Minimum version of `varnish-modules` is v0.10.2*. It's part of Ubuntu 17.10
("Artful") and higher, otherwise see their documentation for
`installing xkey on other platforms`_. You can technically use earlier versions
of the varnish modules down to 0.9.x releases. However, v0.10.2 is the first
version introducing support for purging several tags at once. If you use an
older version, you need to invalidate only one tag at a time, and can't use
soft purge.
Install the varnish modules with your distribution if available, or refer to the
Varnish documentation for `installing xkey`_. Version 0.10.2 is the first version
to support purging more than one tag at once. With older versions you can only
invalidate one tag at a time, and soft purge is not available.

To use ``xkey``, :ref:`configure the Varnish Client for xkey <varnish_custom_tags_header>`
and :ref:`the response tagger to use the xkey header <response_tagger_optional_parameters>`,
Expand Down Expand Up @@ -462,7 +467,8 @@ To enable this feature, add the following to ``your_varnish.vcl``:
.. _explained in the Varnish documentation: https://www.varnish-cache.org/trac/wiki/VCLExampleRemovingSomeCookies#RemovingallBUTsomecookies
.. _curl Varnish plugin: https://github.com/varnish/libvmod-curl
.. _xkey Varnish module: https://github.com/varnish/varnish-modules/blob/master/docs/vmod_xkey.rst
.. _ykey documentation: https://docs.varnish-software.com/varnish-cache-plus/vmods/ykey/
.. _Cache Invalidation chapter of the Varnish documentation: http://book.varnish-software.com/4.0/chapters/Cache_Invalidation.html#hashtwo-xkey-varnish-software-implementation-of-surrogate-keys
.. _installing xkey on other platforms: https://github.com/varnish/varnish-modules#installation
.. _installing xkey: https://github.com/varnish/varnish-modules#installation
.. _`builtin VCL`: https://github.com/varnishcache/varnish-cache/blob/5.0/bin/varnishd/builtin.vcl
.. _`default VCL`: https://github.com/varnishcache/varnish-cache/blob/3.0/bin/varnishd/default.vcl