Backport of Add guidelines for agent/server version compatibility int…

…o release/1.13.x (hashicorp#20319)

website/content/docs/agent/versions.mdx

@@ -0,0 +1,47 @@
+---
+layout: docs
+page_title: Vault Agent Version Compatibility
+description: |-
+  Guidelines for running different versions of Agent and Server
+---
+
+# Running different versions of Agent and Server
+
+There is no requirement to run identical versions of Vault Agent and Vault Server.
+It is safe to run different versions, however you may not be able to take advantage of all the newest features in Vault if you do not upgrade to the most recent versions of Agent and Server. We recognize that this isn’t always possible, so we do support version mismatch as best as possible.
+
+As of Vault Agent 1.13.0, Agent will write a note to its logs when it detects a mismatch between Agent and Server.  This is purely informative, intended to assist with debugging in case the mismatch is given rise to problems, e.g. because a newer Agent version is trying to make use of functionality that doesn't exist in the Server version it's talking to.  If Agent is behaving acceptably, the message may be ignored.
+
+This document describes the common cases.  There may be occasional exceptions, which if intentional will be called out in the CHANGELOG in a `CHANGES` section.  If unintentional/undocumented these should be treated as bugs and reported.
+
+## Older version of Agent than Server
+
+We do not anticipate any problems stemming from continuing to run an older Agent version after the server nodes are upgraded to a later version.  Existing deployments using Agent should not be impacted, as we don't generally make backwards-incompatible changes to Vault Server.
+
+Auto-auth:
+- new auth methods that have been introduced since Agent was built will be unavailable
+- existing auth methods should continue to function normally
+
+Proxy:
+- since Agent simply mirrors the incoming requests, even if an incoming request uses an endpoint that didn't exist when that version of Agent was compiled, that won't impede Agent's ability to proxy the request
+
+Templating:
+- the templating language features that interact with the Vault server use stable Vault APIs to retrieve and renew secrets
+- even if new secret engine types are introduced in newer Vault releases, these should not require an Agent upgrade to access via templates
+
+## Newer version of Agent than Server
+
+It is possible that an Agent could depend on features that don’t exist in older Server versions.
+
+Auto-auth:
+- Agent may claim to support newer auth methods that have been introduced since Server was built, but they won't work due to Server not supporting them
+- Agent may make use of new functionality for existing auth methods that isn't available in an older Server you're using
+  - Generally we will try to make such a change be opt-in, or to gracefully degrade when connecting to an older Server instance, unless there's a very good reason (such as a serious security flaw being patched)
+
+Proxy:
+- since Agent simply mirrors the incoming requests, it is unlikely that incompatibilities would surface in proxying, but new functionality may not be available
+- example: When client-controlled consistency support was added to Agent, it started looking for X-Vault-Index headers in responses, and started providing X-Vault-Index headers in proxied requests.  Older Vault Enterprise servers that don't make use of these headers would ignore the new request header and not emit them either.  Agent proxying behaviour continued unchanged, unable to take advantage of the new functionality, but also not impeded in its previously existing behavior.
+
+Templating:
+- we don't anticipate a scenario where changes to Agent's templating itself gives rise to an incompatibility with older Vault Servers, though of course with any Agent version it's possible to write templates that issue requests which make use of functionality not yet present in the upstream vault server, e.g. {{ with secret "secret/my-secret?some-new-option" }}
+- we would not deliberately make a change to templating that breaks existing deployments

website/data/docs-nav-data.json

@@ -994,6 +994,10 @@
       {
         "title": "Windows service",
         "path": "agent/winsvc"
+      },
+      {
+        "title": "Version compatibility",
+        "path": "agent/versions"
       }
     ]
   },