Backport of docs - add service sync annotations and k8s service weigh…

…t annotation into release/1.14.x (#18038) * backport of commit e1bf428 * manual merge --------- Co-authored-by: David Yu <[email protected]>
hashicorp · Jul 6, 2023 · 0c4b6d7 · 0c4b6d7
1 parent d4014ac
commit 0c4b6d7
Show file tree

Hide file tree

Showing 2 changed files with 67 additions and 14 deletions.
diff --git a/website/content/docs/k8s/annotations-and-labels.mdx b/website/content/docs/k8s/annotations-and-labels.mdx
@@ -9,13 +9,21 @@ description: >-
 
 ## Overview
 
-Consul on Kubernetes provides a few options for customizing how connect-inject behavior should be configured.
+Consul on Kubernetes provides a few options for customizing how connect-inject or service sync behavior should be configured.
 This allows the user to configure natively configure Consul on select Kubernetes resources (i.e. pods, services).
 
-- [Annotations](#annotations)
-- [Labels](#labels)
+- [Consul Service Mesh](#consul-service-mesh)
+  - [Annotations](#annotations)
+  - [Labels](#labels)
+- [Service Sync](#service-sync)
+  - [Annotations](#annotations-1)
 
-## Annotations
+The noun _connect_ is used throughout this documentation to refer to the connect
+subsystem that provides Consul's service mesh capabilities.
+
+## Consul Service Mesh
+
+### Annotations
 
 The following Kubernetes resource annotations could be used on a pod to control connect-inject behavior:
 
@@ -73,7 +81,7 @@ The following Kubernetes resource annotations could be used on a pod to control
   local port to listen for those connections. When transparent proxy is enabled,
   this annotation is optional. This annotation can be either _labeled_ or _unlabeled_. We recommend the labeled format because it has a more consistent syntax and can be used to reference cluster peers as upstreams.
 
-- **Labeled** (requires Consul on Kubernetes v0.45.0+):
+ - **Labeled**:
 
       The labeled annotation format allows you to reference any service as an upstream. You can specify a Consul Enterprise namespace. You can also specify an admin partition in the same datacenter, a cluster peer, or a WAN-federated datacenter.
 
@@ -130,7 +138,7 @@ The following Kubernetes resource annotations could be used on a pod to control
           "consul.hashicorp.com/connect-service-upstreams":"[service-name]:[port]:[optional datacenter]"
         ```
 
-      - Namespace (requires Consul Enterprise 1.7+): Upstream services may be running in a different namespace. Place
+      - Namespace: Upstream services may be running in a different namespace. Place
       the upstream namespace after the service name. For additional details about configuring the injector, refer to [Consul Enterprise namespaces](#consul-enterprise-namespaces) .
 
         ```yaml
@@ -141,7 +149,7 @@ The following Kubernetes resource annotations could be used on a pod to control
         If the namespace is not specified, the annotation defaults to the namespace of the source service.
         Consul Enterprise v1.7 and older interprets the value placed in the namespace position as part of the service name.
 
-      - Admin partitions (requires Consul Enterprise 1.11+): Upstream services may be running in a different
+      - Admin partitions: Upstream services may be running in a different
         partition. When specifying a partition, you must also specify a namespace. Place the partition name after the namespace. If you specify the name of the datacenter, it must be the local datacenter. Communicating across partitions using this method is only supported within a
         datacenter. For cross partition communication across datacenters, [establish a cluster
         peering connection](/consul/docs/k8s/connect/cluster-peering/usage/establish-peering) and set the upstream with a labeled annotation format.
@@ -188,6 +196,13 @@ The following Kubernetes resource annotations could be used on a pod to control
     consul.hashicorp.com/kubernetes-service: 'service-name-to-use'
   ```
 
+- `consul.hashicorp.com/service-weight:` - Configure ability to support weighted loadbalancing by service annotation for Catalog Sync. The integer provided will be applied as a weight for the `passing` state for the health of the service. See [weights](/consul/docs/services/configuration/services-configuration-reference#weights) in service configuration for more information on how this is leveraged for services in the Catalog. 
+
+  ```yaml
+  annotations:
+    consul.hashicorp.com/service-weight: 10
+  ```
+
 - `consul.hashicorp.com/service-tags` - A comma separated list of tags that will
   be applied to the Consul service and its sidecar.
 
@@ -262,7 +277,7 @@ The following Kubernetes resource annotations could be used on a pod to control
     "consul.hashicorp.com/consul-sidecar-user-volume-mount": "[{\"name\": \"secrets-store-mount\", \"mountPath\": \"/mnt/secrets-store\"}]"
   ```
 
-## Labels
+### Labels
 
 Resource labels could be used on a Kubernetes service to control connect-inject behavior.
 
@@ -273,3 +288,45 @@ Resource labels could be used on a Kubernetes service to control connect-inject
   registration to ignore all services except for the one which should be used for routing requests
   using Consul.
 
+## Service Sync 
+
+### Annotations
+
+The following Kubernetes resource annotations could be used on a pod to [Service Sync](https://developer.hashicorp.com/consul/docs/k8s/service-sync) behavior:
+
+- `consul.hashicorp.com/service-sync`: If this is set to `true`, then the Kubernetes service is explicitly configured to be synced to Consul.  
+
+  ```yaml
+  annotations:
+    'consul.hashicorp.com/service-sync': 'true'
+  ```
+
+- `consul.hashicorp.com/service-port`: Configures the port to register to the Consul Catalog for the Kubernetes service. The annotation value may be a name of a port (recommended) or an exact port value. Refer to [service ports](https://developer.hashicorp.com/consul/docs/k8s/service-sync#service-ports) for more information. 
+
+  ```yaml
+  annotations:
+    'consul.hashicorp.com/service-port': 'http'
+  ```
+
+- `consul.hashicorp.com/service-tags`: A comma separated list of strings (without whitespace) to use for registering tags to the service registered to Consul. These custom tags automatically include the `k8s` tag which can't be disabled.
+
+  ```yaml
+  annotations:
+    'consul.hashicorp.com/service-tags': 'primary,foo'
+  ```
+
+- `consul.hashicorp.com/service-meta-KEY`: A map for specifying service metadata for Consul services. The "KEY" below can be set to any key. This allows you to set multiple meta values.
+
+  ```yaml
+  annotations:
+    'consul.hashicorp.com/service-meta-KEY': 'value'
+  ```
+
+- `consul.hashicorp.com/service-weight:` - Configures ability to support weighted loadbalancing by service annotation for Catalog Sync. The integer provided will be applied as a weight for the `passing` state for the health of the service. Refer to [weights](/consul/docs/services/configuration/services-configuration-reference#weights) in service configuration for more information on how this is leveraged for services in the Consul catalog. 
+
+  ```yaml
+  annotations:
+    consul.hashicorp.com/service-weight: 10
+  ```
+
+
diff --git a/website/content/docs/k8s/service-sync.mdx b/website/content/docs/k8s/service-sync.mdx
@@ -12,7 +12,7 @@ services are available to Consul agents and services in Consul can be available
 as first-class Kubernetes services. This functionality is provided by the
 [consul-k8s project](https://github.com/hashicorp/consul-k8s) and can be
 automatically installed and configured using the
-[Consul Helm chart](/docs/k8s/installation/install).
+[Consul K8s Helm chart](/consul/docs/k8s/installation/install).
 
 ![screenshot of a Kubernetes service in the UI](/img/k8s-service.png)
 
@@ -31,11 +31,7 @@ service discovery, including hosted services like databases.
 
 ~> Enabling both Service Mesh and Service Sync on the same Kubernetes services is not supported, as Service Mesh also registers Kubernetes service instances to Consul. Ensure that Service Sync is only enabled for namespaces and services that are not injected with the Consul sidecar for Service Mesh as described in [Sync Enable/Disable](/docs/k8s/service-sync#sync-enable-disable).
 
-The service sync uses an external long-running process in the
-[consul-k8s project](https://github.com/hashicorp/consul-k8s). This process
-can run either inside or outside of a Kubernetes cluster. However, running this process within
-the Kubernetes cluster is generally easier since it is automated using the
-[Helm chart](/docs/k8s/helm).
+The service sync feature deploys a long-running process which can run either inside or outside of a Kubernetes cluster. However, running this process within the Kubernetes cluster is generally easier since it is automated using the [Helm chart](/consul/docs/k8s/helm).
 
 The Consul server cluster can run either in or out of a Kubernetes cluster.
 The Consul server cluster does not need to be running on the same machine