Consul Content Updates (#1233)

* Consul Content Updates

Add additional consul content changed since #1228

* Fix quoting in jsonc files

Author: rmainwork

content/consul/v1.21.x/content/commands/debug.mdx

@@ -40,6 +40,11 @@ flag to not retrieve it initially.
 Additionally, we recommend securely transmitting this archive via encryption
 or otherwise.
 
+## Port connectivity checks
+
+The `consul debug` command includes a built-in port connectivity check that runs on the host that executes the command. This check is similar to the one performed by the `consul troubleshoot ports` command, but it is integrated directly into the debug command's data capture process. Therefore, when you run `consul debug`, the resulting archive contains information about the status of the default Consul ports. This information can make it easier to diagnose network issues.
+There is no separate `-capture` flag  because the port connectivity check always runs as a core part of the debug command. If you need to check port connectivity without collecting other debugging information, use the [`consul troubleshoot ports` command](/consul/commands/troubleshoot/ports).
+
 ## Usage
 
 `Usage: consul debug [options]`

content/consul/v1.21.x/content/docs/automate/kv/store.mdx

@@ -86,4 +86,8 @@ The following example deletes all the keys with the `redis` prefix using the `-r
 ```shell-session
 $ consul kv delete -recurse redis
 Success! Deleted keys with prefix: redis
-```
+```
+
+<Warning title="Security warning">
+To mitigate vulnerability [CVE-2025-11392], Consul does not allow path escapes, directory escapes, leading spaces, or trailing spaces in keys, beginning with Consul v1.22.0. If you have any existing keys in this format and want to continue using the same keys, set the `disable_kv_key_validation` parameter to `true` in the Consul agent configuration. We strongly recommend using validated keys unless you have a specific reason to disable it for legacy compatibility.
+</Warning>

content/consul/v1.21.x/content/docs/connect/proxy/transparent-proxy/k8s.mdx

@@ -98,6 +98,25 @@ spec:
       serviceAccountName: static-server
 ```
 
+### Transparent proxy and multi-port services
+
+Transparent proxy mode assumes that services have only one port. If you want multi-port services to be reachable from the service mesh, you must use explicit upstreams as well. 
+
+In the following example, the `source-service` has one port, and it is part of the service mesh. Its annotations include two upstream targets towards the multi-port `target-service` on ports `15000` and `20000`. Without explicitly declaring the ports as service upstreams, the multi-port service `target-service` is unreachable from within the service mesh. For more information regarding the `connect-service-upstreams` annotation, refer to [Dial services across Kubernetes cluster](#dial-services-across-kubernetes-cluster).
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: source-service
+spec:
+  template:
+    metadata:
+      annotations:
+        consul.hashicorp.com/connect-inject: "true"
+        consul.hashicorp.com/connect-service-upstreams: "target-service.svc:15000,target-service.svc:20000"
+```
+
 ## Enable the Consul CNI plugin
 
 By default, Consul generates a `connect-inject init` container as part of the Kubernetes Pod startup process. The container configures traffic redirection in the service mesh through the sidecar proxy. To configure redirection, the container requires elevated CAP_NET_ADMIN privileges, which may not be compatible with security policies in your organization.
@@ -253,4 +272,4 @@ Note that when dialing individual instances, Consul ignores the HTTP routing rul
 
 - Deployment configurations with federation across or a single datacenter spanning multiple clusters must explicitly dial a service in another datacenter or cluster using annotations.
 
-- When dialing headless services, the request is proxied using a plain TCP proxy. Consul does not take into consideration the upstream's protocol.
+- When dialing headless services, the request is proxied using a plain TCP proxy. Consul does not take into consideration the upstream's protocol.

content/consul/v1.21.x/content/docs/discover/vm.mdx

@@ -7,7 +7,7 @@ description: >-
 
 # Discover services on virtual machines (VMs)
 
-This page provides an overview of Consul service discovery operations on virtual machines. After you register services with Consul, you can address them using Consul DNS to perform application load balancing and static service lookups. You can also create prepared queries for dynamic service lookups and service failover.
+This page provides an overview of Consul service discovery operations on virtual machines. After you register services with Consul, you can use Consul DNS to perform application load balancing and static service lookups. You can also create prepared queries for dynamic service lookups and service failover.
 
 ## Introduction
 

content/consul/v1.21.x/content/docs/error-messages/consul.mdx

@@ -107,7 +107,7 @@ Error getting server health from "XXX": context deadline exceeded
 
 </CodeBlockConfig>
 
-Make sure you are monitoring Consul telemetry and system metrics according to our [monitoring guide][monitoring]. Increase the CPU or memory allocation to the server if needed. Check the performance of the network between Consul nodes.
+Make sure you are monitoring Consul telemetry and system metrics according to our [telemetry documentation][monitoring]. Increase the CPU or memory allocation to the server if needed. Check the performance of the network between Consul nodes.
 
 ## Too many open files
 
@@ -131,14 +131,46 @@ Get http://localhost:8500/: dial tcp 127.0.0.1:31643: socket: too many open file
 
 You need to increase the limit for the Consul user and maybe the system-wide limit. Refer to [this guide][files] for instructions to do so on Linux. Alternatively, if you are starting Consul from `systemd`, you could add `LimitNOFILE=65536` to the unit file for Consul. Refer to the [sample systemd file][systemd].
 
-## Snapshot close error
+## Backup and restore errors
+
+### Snapshot close error
 
 Our RPC protocol requires support for a TCP half-close in order to signal the other side that they are done reading the stream, since we don't know the size in advance. This saves us from having to buffer just to calculate the size.
 
-If a host does not properly implement half-close, you may see an error message `[ERR] consul: Failed to close snapshot: write tcp <source>-><destination>: write: broken pipe` when saving snapshots. This should not affect saving and restoring snapshots.
+If a host does not properly implement half-close, you may receive an error message when saving snapshots.
+
+<CodeBlockConfig hideClipboard>
+
+```log
+[ERR] consul: Failed to close snapshot: write tcp <source>-><destination>: write: broken pipe
+```
+
+</CodeBlockConfig>
+
+This error should not affect saving and restoring snapshots.
 
 This has been a [known issue](https://github.com/docker/libnetwork/issues/1204) in Docker, but may manifest in other environments as well.
 
+### Snapshot restore error
+
+When restoring a Consul datacenter with a snapshot on new infrastructure, Consul throws the following errors when there is a conflict between the `node_name` used in the new datacenter and the `node_id` value for those nodes. 
+
+<CodeBlockConfig hideClipboard>
+
+```log
+[WARN] agent.fsm: EnsureRegistration failed: error="failed inserting node: Error while renaming Node ID: "<NEW_UUID>": Node name <NAME> is reserved by node <OLD_UUID> with name <NAME> (<IP>)"
+```
+
+</CodeBlockConfig>
+
+This error means that in the new datacenter there is at least one node with the same `node_name` as a node in the snapshot's datacenter, but with a different `node_id`. This represents a consistency issue.
+
+There are two possible workarounds:
+
+1. Save the UUID from the previous node’s data directory. Then re-use that same UUID when you first start the agent on the new node. You can configure node IDs for your Consul agent nodes with the [`node_id` configuration parameter](/consul/docs/reference/agent/configuration-file/node#_node_id).
+
+1. Always use unique node names for your Consul datacenters so that there is no risk of conflicts. You can configure node names for your Consul agent nodes using the [`node_name`](/consul/docs/reference/agent/configuration-file/node#_node) configuration parameter.
+
 ## ACL not found
 
 If Consul returns the following error, this indicates that you have ACL enabled in your cluster but you aren't passing a valid token.
@@ -251,7 +283,8 @@ To resolve this error, you must manually issue the `consul reload` command or se
 [releases]: https://releases.hashicorp.com/consul/
 [files]: https://easyengine.io/tutorials/linux/increase-open-files-limit
 [certificates]: /consul/docs/secure/encryption/tls/enable/new/builtin
-[systemd]: /consul/tutorials/production-deploy/deployment-guide#configure-systemd
-[monitoring]: /consul/tutorials/day-2-operations/monitor-datacenter-health
+[systemd]: /consul/tutorials/production-vms/deployment-guide#configure-systemd
+[monitoring]: /consul/docs/monitor/telemetry/agent
 [bind]: /consul/commands/agent#_bind
 [jq]: https://stedolan.github.io/jq/
+[go-sockaddr]: https://pkg.go.dev/github.com/hashicorp/go-sockaddr

content/consul/v1.21.x/content/docs/error-messages/k8s.mdx

@@ -111,4 +111,56 @@ spec:
       serviceAccountName: does-not-match
 ```
 
-</CodeBlockConfig>
+</CodeBlockConfig>
+
+## Unbound PersistentVolumeClaims
+
+If your Consul server pods are stuck in the `Pending` state, check if the PersistentVolumeClaims (PVCs) are bound to PersistentVolumes (PVs). If they are not bound, you will see an error similar to the following:
+
+<CodeBlockConfig highlight="7,14">
+
+```shell-session
+$ kubectl describe pods --namespace consul consul-server-0 
+Name:             consul-server-0
+Namespace:        consul
+
+##...
+
+Status:           Pending
+
+##...
+
+Events:
+  Type     Reason            Age                  From               Message
+  ----     ------            ----                 ----               -------
+  Warning  FailedScheduling  3m29s (x3 over 13m)  default-scheduler  0/3 nodes are available: pod has unbound immediate PersistentVolumeClaims. preemption: 0/3 nodes are available: 3 Preemption is not helpful for scheduling.
+```
+
+</CodeBlockConfig>
+
+There are two ways to resolve this issue. The fastest and simplest option is to use an up-to-date version of the Helm chart or `consul-k8s` tool to deploy Consul. The `consul-k8s` tool  automatically creates the required PVs for you.
+
+If you cannot use a newer version of the Helm chart or `consul-k8s` tool, you can manually create the `StorageClass` object that governs the creation of PVs, and then specify it in the Consul Helm chart. For example, you can use the following YAML to create a `StorageClass` called `ebs-sc` for AWS EBS volumes:
+
+```yaml
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: ebs-sc
+provisioner: ebs.csi.aws.com
+volumeBindingMode: WaitForFirstConsumer
+parameters:
+  csi.storage.k8s.io/fstype: xfs
+  type: io1
+  iopsPerGB: "50"
+  encrypted: "true"
+```
+
+Finally, specify the [StorageClass](/consul/docs/reference/k8s/helm#v-server-storageclass) in the Consul Helm chart values and redeploy Consul to Kubernetes.
+
+```yaml
+##...
+server:
+  storageClass: "ebs-sc"
+##...
+```