From b52ac08b18bc10d66d7509c2cb79a269245a2c04 Mon Sep 17 00:00:00 2001
From: Michael Schurter <mschurter@hashicorp.com>
Date: Mon, 10 Jul 2023 11:53:07 -0700
Subject: [PATCH] docs: v1.6.0 requires ipc_lock cap for mlock (#17881)

Fixes #17780
---
 .../content/docs/upgrade/upgrade-specific.mdx | 82 +++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/website/content/docs/upgrade/upgrade-specific.mdx b/website/content/docs/upgrade/upgrade-specific.mdx
index 2d88d98fd007..bf99c8bed51c 100644
--- a/website/content/docs/upgrade/upgrade-specific.mdx
+++ b/website/content/docs/upgrade/upgrade-specific.mdx
@@ -13,6 +13,88 @@ upgrade. However, specific versions of Nomad may have more details provided for
 their upgrades as a result of new features or changed behavior. This page is
 used to document those details separately from the standard upgrade flow.
 
+## Nomad 1.6.0
+
+#### Enterprise License Validation with BuildDate
+
+Nomad Enterprise 1.6.0 now compares license `ExpirationTime` with the Nomad binary's `BuildDate`,
+rather than comparing the sometimes more lenient license `TerminationTime` with `time.Now()`.
+See the [licensing FAQ](/nomad/docs/v1.6.x/enterprise/license/faq) for more info,
+but most relevant here is that you should run the new
+[`nomad license inspect`](/nomad/docs/commands/license/inspect) command
+before trying to upgrade your Enterprise servers to v1.6.0 or higher.
+
+#### Job Evaluate API Endpoint Requires `submit-job` Instead of `read-job`
+
+Nomad 1.6.0 updated the ACL capability requirement for the job evaluate
+endpoint from `read-job` to `submit-job` to better reflect that this operation
+writes state to Nomad. This endpoint is used by the `nomad job eval` CLI
+command and so the ACL requirements changed for the command as well. Users that
+called this endpoint or used this command using tokens with just the `read-job`
+capability or the `read` policy must update their tokens to use the
+`submit-job` capability or the `write` policy.
+
+#### Exec Driver Requires New Capability for mlock
+
+Nomad 1.6.0 updated the `exec` task driver to maintain the max memory locked
+limit set by the host system. In earlier versions of Nomad this limit was
+*unset* unintentionally.
+
+In practice this means that `exec` tasks such as Vault which use the `mlock`
+system call will now need to explicitly add the `ipc_lock` capability.
+
+First [allow the `ipc_lock` capability in the Client
+configuration][allow_caps_exec]:
+
+```hcl
+plugin "exec" {
+  config {
+    allow_caps = ["audit_write", "chown", "dac_override", "fowner", "fsetid",
+      "kill", "mknod", "net_bind_service", "setfcap", "setgid", "setpcap",
+      "setuid", "sys_chroot", "ipc_lock"]
+  }
+}
+```
+
+Then [add the `ipc_lock` capability to the exec task][cap_add_exec] that uses
+`mlock`:
+
+```hcl
+task "vault" {
+  driver = "exec"
+
+  config {
+    cap_add = ["ipc_lock"]
+
+    # ... other task configuration
+  }
+
+# ... rest of jobspec
+```
+
+These additions are backward compatible with Nomad v1.5, so Clients and Jobs
+should be updated prior to upgrading to Nomad v1.6.
+
+See [#17780](https://github.com/hashicorp/nomad/issues/17780) for details.
+
+#### Command `nomad tls cert create` flag `-cluster-region` deprecated
+
+Nomad 1.6.0 will deprecate the command `nomad tls cert create` flag `-cluster-region`
+in favour of using the standard flag `-region`. The `-cluster-region` flag
+will be removed in Nomad 1.7.0
+
+#### 32-bit Intel Builds Deprecated
+
+Starting with Nomad 1.6.0, HashiCorp will no longer release 32-bit Intel builds
+of Nomad and Nomad Enterprise (the builds named `windows_386` and
+`linux_386`). Bug fixes will continue to be backported to the 1.5.x and 1.4.x
+versions so long as those major versions are still supported.
+
+The 32-bit ARM build (`linux_arm` for the armhf architecture) is deprecated and
+may be removed in a future major version of Nomad. The 32-bit ARM build is not
+tested and may include bugs around platform-specific integer sizes. Using 64-bit
+builds for small form-factor hosts such as the RaspberryPi is strongly
+recommended.
 
 ## Nomad 1.5.5