Docs for Consul namespaces in kube

website/source/docs/platform/k8s/connect.html.md

@@ -18,7 +18,7 @@ your cluster, making configuration for Kubernetes automatic.
 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/platform/k8s/helm.html).
+[Consul Helm chart](/docs/platform/k8s/run.html).
 
 ## Usage
 
@@ -132,8 +132,8 @@ Pods must specify upstream dependencies with the
 This annotation declares the names of any upstream dependencies and a
 local port for the proxy to listen on. When a connection is established to that local
 port, the proxy establishes a connection to the target service
-("static-server" in this example) using
+(`static-server` in this example) using
-mutual TLS and identifying as the source service ("static-client" in this
+mutual TLS and identifying as the source service (`static-client` in this
 example).
 
 The injector will also set environment variables `<NAME>_CONNECT_SERVICE_HOST`
@@ -206,6 +206,23 @@ Annotations can be used to configure the injection behavior.
         annotations:
           "consul.hashicorp.com/connect-service-upstreams":"[service-name]:[port]:[optional datacenter]"
         ```
+    * Consul Enterprise Namespaces
+    
+        If running Consul Enterprise 1.7+, your upstream services may be running in different
+        namespaces. The upstream namespace can be specified after the service name
+        as `[service-name].[namespace]`. See [Consul Enterprise Namespaces](#consul-enterprise-namespaces)
+        below for more details on configuring the injector.
+        
+        ```yaml
+        annotations:
+          "consul.hashicorp.com/connect-service-upstreams":"[service-name].[service-namespace]:[port]:[optional datacenter]"
+        ```
+      
+        -> **NOTE:** If the namespace is not specified it will default to the namespace
+        of the source service.
+
+        ~> **WARNING:** Setting a namespace when not using Consul Enterprise or using a version < 1.7
+        is not supported. It will be treated as part of the service name.
 
     * [Prepared Query](https://www.consul.io/docs/connect/proxies.html#upstreams)
 
@@ -303,7 +320,7 @@ provided by the
 [consul-k8s project](https://github.com/hashicorp/consul-k8s).
 This enables the automatic pod mutation shown in the usage section above.
 Installation of the mutating admission webhook is automated using the
-[Helm chart](/docs/platform/k8s/helm.html).
+[Helm chart](/docs/platform/k8s/run.html).
 
 To install the Connect injector, enable the Connect injection feature using
 [Helm values](/docs/platform/k8s/helm.html#configuration-values-) and
@@ -319,23 +336,167 @@ connectInject:
 
 client:
   enabled: true
-  grpc: true
 ```
 
 This will configure the injector to inject when the
-[injection annotation](#)
+[injection annotation](#consul-hashicorp-com-connect-inject)
-is present. Other values in the Helm chart can be used to limit the namespaces
+is set to `true`. Other values in the Helm chart can be used to limit the namespaces
 the injector runs in, enable injection by default, and more.
 
-As noted above, the Connect auto-injection requires that local client agents
+~> NOTE: If setting `global.bootstrapACLs: true`, it's important that your pod's `ServiceAccount`
-are configured. These client agents must be successfully joined to a Consul
-cluster.
-The Consul server cluster can run either in or out of a Kubernetes cluster.
-
-~> NOTE: If setting `global.bootstrapACLs: true`, it's important that your Pod's `ServiceAccount`
   has the **same name** as the Consul service that's being registered. If not, the init
   container will log: `Error logging in: Unexpected response code: 403 (rpc error making call: rpc error making call: Permission denied)`.
 
+### Controlling Injection Via Annotation
+
+By default, the injector will inject only when the
+[injection annotation](#consul-hashicorp-com-connect-inject)
+on the pod (not the deployment) is set to `true`:
+
+```yaml
+annotations:
+  "consul.hashicorp.com/connect-inject": "true"
+```
+
+### Injection Defaults
+
+If you wish for the injector to always inject, you can set the default to `true`
+in the Helm chart:
+
+```yaml
+connectInject:
+  enabled: true
+  default: true
+```
+
+You can then exclude specific pods via annotation:
+
+```yaml
+annotations:
+  "consul.hashicorp.com/connect-inject": "false"
+```
+
+### Controlling Injection Via Namespace
+
+You can control which Kubernetes namespaces are allowed to be injected via
+the `k8sAllowNamespaces` and `k8sDenyNamespaces` keys:
+
+```yaml
+connectInject:
+  enabled: true
+  k8sAllowNamespaces: ["*"]
+  k8sDenyNamespaces: []
+```
+
+In the default configuration (shown above), services from all namespaces are allowed
+to be injected. Whether or not they're injected depends on the value of `connectInject.default`
+and the `consul.hashicorp.com/connect-inject` annotation.
+
+If you wish to only enable injection in specific namespaces, you can list only those
+namespaces in the `k8sAllowNamespaces` key. In the configuration below
+only the `my-ns-1` and `my-ns-2` namespaces will be enabled for injection.
+All other namespaces will be ignored, even if the connect inject [annotation](#consul-hashicorp-com-connect-inject)
+is set.
+
+```yaml
+connectInject:
+  enabled: true
+  k8sAllowNamespaces: ["my-ns-1", "my-ns-2"]
+  k8sDenyNamespaces: []
+```
+
+If you wish to enable injection in every namespace *except* specific namespaces, you can
+use `*` in the allow list to allow all namespaces and then specify the namespaces to exclude in the deny list:
+
+```yaml
+syncCatalog:
+  enabled: true
+  k8sAllowNamespaces: ["*"]
+  k8sDenyNamespaces: ["no-sync-ns-1", "no-sync-ns-2"]
+```
+
+-> **NOTE:** The deny list takes precedence over the allow list. If a namespace
+is listed in both lists, it will **not** be synced. 
+
+~> **NOTE:** The `kube-system` and `kube-public` namespaces will never be injected.
+
+
+### Consul Clients Required
+
+Connect injection requires that local client agents
+are running on each Kubernetes node. These client agents must be joined to a Consul
+server cluster.
+The Consul server cluster can run either in or out of a Kubernetes cluster.
+
+### Consul Enterprise Namespaces
+
+Consul Enterprise 1.7+ supports Consul namespaces. When Kubernetes pods are registered
+into Consul, you can control which Consul namespace they are registered into.
+
+There are three options available:
+
+1. **Single Destination Namespace** – Register all Kubernetes pods, regardless of namespace,
+into the same Consul namespace.
+
+    This can be configured with:
+    
+    ```yaml
+    global:
+      enableConsulNamespaces: true
+
+    connectInject:
+      enabled: true
+      consulNamespaces:
+        consulDestinationNamespace: "my-consul-ns"
+    ```
+
+       -> **NOTE:** If the destination namespace does not exist we will create it.
+
+1. **Mirror Namespaces** - Register each Kubernetes pod into a Consul namespace with the same name as its Kubernetes namespace.
+For example, pod `foo` in Kubernetes namespace `ns-1` will be synced to the Consul namespace `ns-1`.
+If a mirrored namespace does not exist in Consul, it will be created.
+     
+    This can be configured with:
+    
+    ```yaml
+    global:
+      enableConsulNamespaces: true
+
+    connectInject:
+      enabled: true
+      consulNamespaces:
+        mirroringK8S: true
+    ```
+1. **Mirror Namespaces With Prefix** - Register each Kubernetes pod into a Consul namespace with the same name as its Kubernetes
+namespace **with a prefix**.
+For example, given a prefix `k8s-`, pod `foo` in Kubernetes namespace `ns-1` will be synced to the Consul namespace `k8s-ns-1`.
+
+    This can be configured with:
+    
+    ```yaml
+    global:
+      enableConsulNamespaces: true
+
+    connectInject:
+      enabled: true
+      consulNamespaces:
+        mirroringK8S: true
+        mirroringK8SPrefix: "k8s-"
+    ```
+
+### Consul Enterprise Namespace Upstreams
+   
+To specify the namespace of your upstream services in the upstream annotation,
+use the format `[service-name].[namespace]:[port]:[optional datacenter]`:
+
+```yaml
+annotations:
+  "consul.hashicorp.com/connect-inject": "true"
+  "consul.hashicorp.com/connect-service-upstreams": "[service-name].[namespace]:[port]:[optional datacenter]"
+```
+
+See [consul.hashicorp.com/connect-service-upstreams](#consul-hashicorp-com-connect-service-upstreams) for more details.
+
 ### Verifying the Installation
 
 To verify the installation, run the

website/source/docs/platform/k8s/helm.html.md

@@ -372,7 +372,7 @@ to run the sync program.
   A [selector](/docs/acl/acl-auth-methods.html#binding-rules) for restricting automatic injection to only matching services based on
   their associated service account. By default, services using the `default` Kubernetes service account will not have a proxy injected.
   
-  * <a name="v-connectinject-aclinjecttoken" href="#v-connectinject-aclinjecttoken">`aclInjectToken`</a> - Refers to a Kubernetes secret that you have created that contains an ACL token for your Consul cluster which allows the Connect injector the correct permissions. This is only needed if Consul namespaces and ACLs are enabled on the Consul cluster and you are not setting `global.bootstrapACLs` to `true`. This token needs to have `operator = "write"` privileges.
+  * <a name="v-connectinject-aclinjecttoken" href="#v-connectinject-aclinjecttoken">`aclInjectToken`</a> - Refers to a Kubernetes secret that you have created that contains an ACL token for your Consul cluster which allows the Connect injector the correct permissions. This is only needed if Consul namespaces and ACLs are enabled on the Consul cluster and you are not setting `global.bootstrapACLs` to `true`. This token needs to have `operator = "write"` privileges so that it can create namespaces.
   
       - <a name="v-connectinject-aclinjecttoken-secretname" href="#v-synccatalog-aclinjecttoken-secretname">secretName </a>`(string: null)` - The name of the Kubernetes secret.
     

website/source/docs/platform/k8s/service-sync.html.md

@@ -13,7 +13,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/platform/k8s/helm.html).
+[Consul Helm chart](/docs/platform/k8s/run.html).
 
 **Why sync Kubernetes services to Consul?** Kubernetes services synced to the
 Consul catalog enable Kubernetes services to be accessed by any node that
@@ -38,10 +38,10 @@ the Kubernetes cluster is generally easier since it is automated using the
 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
 or same platform as the sync process. The sync process needs to be configured
-with the address to the Consul cluster as well as any additional access
+with the address to a Consul agent as well as any additional access
 information such as ACL tokens.
 
-To install the sync, enable the catalog sync feature using
+To install the sync process, enable the catalog sync feature using
 [Helm values](/docs/platform/k8s/helm.html#configuration-values-) and
 upgrade the installation using `helm upgrade` for existing installs or
 `helm install` for a fresh install.
@@ -159,10 +159,17 @@ to `false` in the Helm chart values file.
 
 ### Sync Enable/Disable
 
-By default, all valid services (as explained above) are synced. This default can
+By default, all valid service types (as explained above) are synced from every Kubernetes
-be changed using the [configuration](/docs/platform/k8s/helm.html#v-synccatalog-default).
+namespace (except for `kube-system` and `kube-public`).
-Syncing can also be explicitly enabled or disabled using an
+If you wish to only sync specific services via annotation, set the default to `false`:
-annotation:
+
+```yaml
+syncCatalog:
+  enabled: true
+  default: false
+```
+
+And explicitly enable syncing specific services via the `consul.hashicorp.com/service-sync` annotation:
 
 ```yaml
 kind: Service
@@ -170,9 +177,50 @@ apiVersion: v1
 metadata:
   name: my-service
   annotations:
-    "consul.hashicorp.com/service-sync": "false"
+    "consul.hashicorp.com/service-sync": "true"
 ```
 
+-> **NOTE:** If the annotation is set to `false` when the default sync is `true`, the service will **not** be synced.
+
+You can allow or deny syncing from specific Kubernetes namespaces by setting the
+`k8sAllowNamespaces` and `k8sDenyNamespaces` keys:
+
+```yaml
+syncCatalog:
+  enabled: true
+  default: true
+  k8sAllowNamespaces: ["*"]
+  k8sDenyNamespaces: ["kube-system", "kube-public"]
+```
+
+In the default configuration (shown above), services from all namespaces except for
+`kube-system` and `kube-public` will be synced.
+
+If you wish to only sync from specific namespaces, you can list only those
+namespaces in the `k8sAllowNamespaces` key:
+
+```yaml
+syncCatalog:
+  enabled: true
+  default: true
+  k8sAllowNamespaces: ["my-ns-1", "my-ns-2"]
+  k8sDenyNamespaces: []
+```
+
+If you wish to sync from every namespace *except* specific namespaces, you can
+use `*` in the allow list and then specify the non-syncing namespaces in the deny list:
+
+```yaml
+syncCatalog:
+  enabled: true
+  default: true
+  k8sAllowNamespaces: ["*"]
+  k8sDenyNamespaces: ["no-sync-ns-1", "no-sync-ns-2"]
+```
+
+-> **NOTE:** The deny list takes precedence over the allow list. If a namespace
+is listed in both lists, it will **not** be synced. 
+
 ### Service Name
 
 When a Kubernetes service is synced to Consul, the name of the service in Consul
@@ -252,6 +300,72 @@ metadata:
     "consul.hashicorp.com/service-meta-KEY": "value"
 ```
 
+### Consul Enterprise Namespaces
+
+Consul Enterprise supports Consul namespaces. These can be used when syncing
+from Kubernetes to Consul (although not vice-versa).
+
+There are three options available:
+
+1. **Single Destination Namespace** – Sync all Kubernetes services, regardless of namespace,
+into the same Consul namespace.
+
+    This can be configured with:
+    
+    ```yaml
+    global:
+      enableConsulNamespaces: true
+
+    syncCatalog:
+      enabled: true
+      consulNamespaces:
+        consulDestinationNamespace: "my-consul-ns"
+    ```
+1. **Mirror Namespaces** - Each Kubernetes service will be synced to a Consul namespace with the same name as its Kubernetes namespace.
+For example, service `foo` in Kubernetes namespace `ns-1` will be synced to the Consul namespace `ns-1`.
+If a mirrored namespace does not exist in Consul, it will be created.
+     
+    This can be configured with:
+    
+    ```yaml
+    global:
+      enableConsulNamespaces: true
+
+    syncCatalog:
+      enabled: true
+      consulNamespaces:
+        mirroringK8S: true
+   
+    addK8SNamespaceSuffix: false
+    ```
+1. **Mirror Namespaces With Prefix** - Each Kubernetes service will be synced to a Consul namespace with the same name as its Kubernetes
+namespace **with a prefix**.
+For example, given a prefix `k8s-`, service `foo` in Kubernetes namespace `ns-1` will be synced to the Consul namespace `k8s-ns-1`.
+
+    This can be configured with:
+    
+    ```yaml
+    global:
+      enableConsulNamespaces: true
+
+    syncCatalog:
+      enabled: true
+      consulNamespaces:
+        mirroringK8S: true
+        mirroringK8SPrefix: "k8s-"
+
+    addK8SNamespaceSuffix: false
+    ```
+    
+-> Note that in both mirroring examples we're setting `addK8SNamespaceSuffix: false`. If set to `true`
+(the default), the Kubernetes namespace will be added as a suffix to each
+Consul service name. For example Kubernetes service `foo` in namespace `k8s-ns`
+would be registered into Consul with the name `foo-k8s-ns`.
+This is useful when syncing from multiple Kubernetes namespaces to
+a single consul namespace but is likely something you'll want turned off
+when mirroring namespaces since services won't overlap with services from
+other namespaces.
+
 ## Consul to Kubernetes
 
 This syncs Consul services into first-class Kubernetes services.