Document CRDs and kube namespaces (#9502)

* Document CRDs and kube namespaces

website/content/docs/agent/config-entries/ingress-gateway.mdx

@@ -849,6 +849,11 @@ spec:
           name: 'name',
           description: 'Set to the name of the service being configured.',
         },
+        {
+          name: 'namespace',
+          description:
+            'If running Consul Open Source, the namespace is ignored (see [Kubernetes Namespaces in Consul OSS](/docs/k8s/crds#consul-oss)). If running Consul Enterprise see [Kubernetes Namespaces in Consul Enterprise](/docs/k8s/crds#consul-enterprise) for more details.',
+        },
       ],
       hcl: false,
     },

website/content/docs/agent/config-entries/proxy-defaults.mdx

@@ -156,7 +156,17 @@ spec:
     },
     {
       name: 'metadata',
-      children: [{ name: 'name', description: 'Must be set to `global`' }],
+      children: [
+        {
+          name: 'name',
+          description: 'Must be set to `global`',
+        },
+        {
+          name: 'namespace',
+          description:
+            'If running Consul Open Source, the namespace is ignored (see [Kubernetes Namespaces in Consul OSS](/docs/k8s/crds#consul-oss)). If running Consul Enterprise see [Kubernetes Namespaces in Consul Enterprise](/docs/k8s/crds#consul-enterprise) for more details.',
+        },
+      ],
       hcl: false,
     },
     {

website/content/docs/agent/config-entries/service-defaults.mdx

@@ -91,6 +91,11 @@ spec:
           name: 'name',
           description: 'Set to the name of the service being configured.',
         },
+        {
+          name: 'namespace',
+          description:
+            'If running Consul Open Source, the namespace is ignored (see [Kubernetes Namespaces in Consul OSS](/docs/k8s/crds#consul-oss)). If running Consul Enterprise see [Kubernetes Namespaces in Consul Enterprise](/docs/k8s/crds#consul-enterprise) for more details.',
+        },
       ],
       hcl: false,
     },

website/content/docs/agent/config-entries/service-intentions.mdx

@@ -108,7 +108,7 @@ spec:
 </Tab>
 </Tabs>
 
-## gRPC
+### gRPC
 
 <Tabs>
 <Tab heading="HCL">
@@ -196,7 +196,7 @@ spec:
 </Tab>
 </Tabs>
 
-## L4 and L7
+### L4 and L7
 
 <Tabs>
 <Tab heading="HCL">
@@ -306,7 +306,12 @@ spec:
         {
           name: 'name',
           description:
-            'Unlike other config entries, the `metadata.name` field is not used to set the name of the service being configured. Instead, that is set in `spec.destination.name`. Thus this name can be set to anything.',
+            'Unlike other config entries, the `metadata.name` field is not used to set the name of the service being configured. Instead, that is set in `spec.destination.name`. Thus this name can be set to anything. See [ServiceIntentions Special Case (OSS)](/docs/k8s/crds#serviceintentions-special-case) or [ServiceIntentions Special Case (Enterprise)](/docs/k8s/crds#serviceintentions-special-case-enterprise) for more details.',
+        },
+        {
+          name: 'namespace',
+          description:
+            'If running Consul Open Source, the namespace is ignored (see [Kubernetes Namespaces in Consul OSS](/docs/k8s/crds#consul-oss)). If running Consul Enterprise see [Kubernetes Namespaces in Consul Enterprise](/docs/k8s/crds#consul-enterprise) for more details.',
         },
       ],
       hcl: false,
@@ -326,9 +331,9 @@ spec:
           name: 'namespace',
           hcl: false,
           enterprise: true,
-          type: 'string: <required>',
+          type: 'string: <optional>',
           description:
-            "Specifies the namespaces the config entry will apply to. This may be set to the wildcard character (`*`) to match all services in all namespaces that don't otherwise have intentions defined.",
+            "Specifies the namespaces the config entry will apply to. This may be set to the wildcard character (`*`) to match all services in all namespaces that don't otherwise have intentions defined. If not set, the namespace used will depend on the `connectInject.consulNamespaces` configuration. See [ServiceIntentions Special Case (Enterprise)](/docs/k8s/crds#serviceintentions-special-case-enterprise) for more details.",
         },
       ],
     },

website/content/docs/agent/config-entries/service-resolver.mdx

@@ -228,6 +228,11 @@ spec:
           name: 'name',
           description: 'Set to the name of the service being configured.',
         },
+        {
+          name: 'namespace',
+          description:
+            'If running Consul Open Source, the namespace is ignored (see [Kubernetes Namespaces in Consul OSS](/docs/k8s/crds#consul-oss)). If running Consul Enterprise see [Kubernetes Namespaces in Consul Enterprise](/docs/k8s/crds#consul-enterprise) for more details.',
+        },
       ],
       hcl: false,
     },

website/content/docs/agent/config-entries/service-router.mdx

@@ -263,6 +263,11 @@ spec:
           name: 'name',
           description: 'Set to the name of the service being configured.',
         },
+        {
+          name: 'namespace',
+          description:
+            'If running Consul Open Source, the namespace is ignored (see [Kubernetes Namespaces in Consul OSS](/docs/k8s/crds#consul-oss)). If running Consul Enterprise see [Kubernetes Namespaces in Consul Enterprise](/docs/k8s/crds#consul-enterprise) for more details.',
+        },
       ],
       hcl: false,
     },

website/content/docs/agent/config-entries/service-splitter.mdx

@@ -171,6 +171,11 @@ spec:
           name: 'name',
           description: 'Set to the name of the service being configured.',
         },
+        {
+          name: 'namespace',
+          description:
+            'If running Consul Open Source, the namespace is ignored (see [Kubernetes Namespaces in Consul OSS](/docs/k8s/crds#consul-oss)). If running Consul Enterprise see [Kubernetes Namespaces in Consul Enterprise](/docs/k8s/crds#consul-enterprise) for more details.',
+        },
       ],
       hcl: false,
     },

website/content/docs/agent/config-entries/terminating-gateway.mdx

@@ -640,6 +640,11 @@ and configure default certificates for mutual TLS. Also override the SNI and CA
           name: 'name',
           description: 'Set to the name of the gateway being configured.',
         },
+        {
+          name: 'namespace',
+          description:
+            'If running Consul Open Source, the namespace is ignored (see [Kubernetes Namespaces in Consul OSS](/docs/k8s/crds#consul-oss)). If running Consul Enterprise see [Kubernetes Namespaces in Consul Enterprise](/docs/k8s/crds#consul-enterprise) for more details.',
+        },
       ],
       hcl: false,
     },

website/content/docs/k8s/crds/index.mdx

@@ -173,3 +173,211 @@ to be deleted since that would put Consul into a broken state.
 
 In order to delete the `ServiceDefaults` config, you would need to first delete
 the `ServiceSplitter`.
+
+## Kubernetes Namespaces
+
+### Consul OSS
+
+Consul Open Source (Consul OSS) ignores Kubernetes namespaces and registers all services into the same
+global Consul registry based on their names. For example, service `web` in Kubernetes namespace
+`web-ns` and service `admin` in Kubernetes namespace `admin-ns` will be registered into
+Consul as `web` and `admin` with the Kubernetes source namespace ignored.
+
+When creating custom resources to configure these services, the namespace of the
+custom resource is also ignored. For example, you can create a `ServiceDefaults`
+custom resource for service `web` in the Kubernetes namespace `admin-ns` even though
+the `web` service is actually running in the `web-ns` namespace (although this is not recommended):
+
+```yaml
+apiVersion: consul.hashicorp.com/v1alpha1
+kind: ServiceDefaults
+metadata:
+  name: web
+  namespace: admin-ns
+spec:
+  protocol: http
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: web
+  namespace: web-ns
+spec: ...
+```
+
+~> **NOTE:** If two custom resources of the same kind **and** the same name are attempted to
+be created in different Kubernetes namespaces, the last one created will not be synced.
+
+#### ServiceIntentions Special Case
+
+`ServiceIntentions` are different from the other custom resources because the
+name of the resource doesn't matter. For other resources, the name of the resource
+determines which service it configures. For example, this resource configures
+the service `web`:
+
+```yaml
+apiVersion: consul.hashicorp.com/v1alpha1
+kind: ServiceDefaults
+metadata:
+  name: web
+spec:
+  protocol: http
+```
+
+For `ServiceIntentions`, because we need to support the ability to create
+wildcard intentions (e.g. `foo => * (allow)` meaning that `foo` can talk to **any** service),
+and because `*` is not a valid Kubernetes resource name, we instead use the field `spec.destination.name`
+to configure the destination service for the intention:
+
+```yaml
+# foo => * (allow)
+apiVersion: consul.hashicorp.com/v1alpha1
+kind: ServiceIntentions
+metadata:
+  name: name-does-not-matter
+spec:
+  destination:
+    name: '*'
+  sources:
+    - name: foo
+      action: allow
+---
+# foo => web (allow)
+apiVersion: consul.hashicorp.com/v1alpha1
+kind: ServiceIntentions
+metadata:
+  name: name-does-not-matter
+spec:
+  destination:
+    name: web
+  sources:
+    - name: foo
+      action: allow
+```
+
+~> **NOTE:** If two `ServiceIntentions` resources set the same `spec.destination.name`, the
+last one created will not be synced.
+
+### Consul Enterprise <EnterpriseAlert inline />
+
+Consul Enterprise supports multiple configurations for how Kubernetes namespaces are mapped
+to Consul namespaces. The Consul namespace that the custom resource is registered
+into depends on the configuration being used but in general, you should create your
+custom resources in the same Kubernetes namespace as the service they're configuring and
+everything will work as expected.
+
+The details on each configuration are:
+
+1. **Mirroring** - The Kubernetes namespace will be "mirrored" into Consul, i.e.
+   service `web` in Kubernetes namespace `web-ns` will be registered as service `web`
+   in the Consul namespace `web-ns`. In the same vein, a `ServiceDefaults` custom resource with
+   name `web` in Kubernetes namespace `web-ns` will configure that same service.
+
+   This is configured via [`connectInject.consulNamespaces`](/docs/k8s/helm#v-connectinject-consulnamespaces):
+
+   ```yaml
+   global:
+     name: consul
+     enableConsulNamespaces: true
+     image: hashicorp/consul-enterprise:<tag>-ent
+   connectInject:
+     consulNamespaces:
+       mirroringK8S: true
+   ```
+
+1. **Mirroring with prefix** - The Kubernetes namespace will be "mirrored" into Consul
+   with a prefix added to the Consul namespace, i.e.
+   if the prefix is `k8s-` then service `web` in Kubernetes namespace `web-ns` will be registered as service `web`
+   in the Consul namespace `k8s-web-ns`. In the same vein, a `ServiceDefaults` custom resource with
+   name `web` in Kubernetes namespace `web-ns` will configure that same service.
+
+   This is configured via [`connectInject.consulNamespaces`](/docs/k8s/helm#v-connectinject-consulnamespaces):
+
+   ```yaml
+   global:
+     name: consul
+     enableConsulNamespaces: true
+     image: hashicorp/consul-enterprise:<tag>-ent
+   connectInject:
+     consulNamespaces:
+       mirroringK8S: true
+       mirroringK8SPrefix: k8s-
+   ```
+
+1. **Single destination namespace** - The Kubernetes namespace is ignored and all services
+   will be registered into the same Consul namespace, i.e. if the destination Consul
+   namespace is `my-ns` then service `web` in Kubernetes namespace `web-ns` will
+   be registered as service `web` in Consul namespace `my-ns`.
+
+   In this configuration, the Kubernetes namespace of the custom resource is ignored.
+   For example, a `ServiceDefaults` custom resource with the name `web` in Kubernetes
+   namespace `admin-ns` will configure the service with name `web` even though that
+   service is running in Kubernetes namespace `web-ns` because the `ServiceDefaults`
+   resource ends up registered into the same Consul namespace `my-ns`.
+
+   This is configured via [`connectInject.consulNamespaces`](/docs/k8s/helm#v-connectinject-consulnamespaces):
+
+   ```yaml
+   global:
+     name: consul
+     enableConsulNamespaces: true
+     image: hashicorp/consul-enterprise:<tag>-ent
+   connectInject:
+     consulNamespaces:
+       consulDestinationNamespace: 'my-ns'
+   ```
+
+   ~> **NOTE:** In this configuration, if two custom resources of the same kind **and** the same name are attempted to
+   be created in two Kubernetes namespaces, the last one created will not be synced.
+
+#### ServiceIntentions Special Case (Enterprise)
+
+`ServiceIntentions` are different from the other custom resources because the
+name of the resource doesn't matter. For other resources, the name of the resource
+determines which service it configures. For example, this resource configures
+the service `web`:
+
+```yaml
+apiVersion: consul.hashicorp.com/v1alpha1
+kind: ServiceDefaults
+metadata:
+  name: web
+spec:
+  protocol: http
+```
+
+For `ServiceIntentions`, because we need to support the ability to create
+wildcard intentions (e.g. `foo => * (allow)` meaning that `foo` can talk to **any** service),
+and because `*` is not a valid Kubernetes resource name, we instead use the field `spec.destination.name`
+to configure the destination service for the intention:
+
+```yaml
+# foo => * (allow)
+apiVersion: consul.hashicorp.com/v1alpha1
+kind: ServiceIntentions
+metadata:
+  name: name-does-not-matter
+spec:
+  destination:
+    name: '*'
+  sources:
+    - name: foo
+      action: allow
+---
+# foo => web (allow)
+apiVersion: consul.hashicorp.com/v1alpha1
+kind: ServiceIntentions
+metadata:
+  name: name-does-not-matter
+spec:
+  destination:
+    name: web
+  sources:
+    - name: foo
+      action: allow
+```
+
+In addition, we support the field `spec.destination.namespace` to configure
+the destination service's Consul namespace. If `spec.destination.namespace`
+is empty, then the Consul namespace used will be the same as the other
+config entries as outlined above.