Update documentation for custom k8s namespaces

doc/ci/environments.md

@@ -340,6 +340,12 @@ deploy:
   - master
 ```
 
+When deploying to a Kubernetes cluster using GitLab's Kubernetes integration,
+information about the cluster and namespace will be displayed above the job
+trace on the deployment job page:
+
+![Deployment cluster information](img/environments_deployment_cluster_v12_8.png)
+
 NOTE: **Note:**
 Kubernetes configuration is not supported for Kubernetes clusters
 that are [managed by GitLab](../user/project/clusters/index.md#gitlab-managed-clusters).

doc/topics/autodevops/index.md

@@ -181,7 +181,7 @@ To make full use of Auto DevOps, you will need:
   If you have configured GitLab's Kubernetes integration, you can deploy it to
   your cluster by installing the
   [GitLab-managed app for cert-manager](../../user/clusters/applications.md#cert-manager).
-  
+
 If you do not have Kubernetes or Prometheus installed, then Auto Review Apps,
 Auto Deploy, and Auto Monitoring will be silently skipped.
 
@@ -1030,6 +1030,32 @@ It is also possible to copy and paste the contents of the [Auto DevOps
 template] into your project and edit this as needed. You may prefer to do it
 that way if you want to specifically remove any part of it.
 
+### Customizing the Kubernetes namespace
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/27630) in GitLab 12.6.
+
+For **non**-GitLab-managed clusters, the namespace can be customized using
+`.gitlab-ci.yml` by specifying
+[`environment:kubernetes:namespace`](../../ci/environments.md#configuring-kubernetes-deployments).
+For example, the following configuration overrides the namespace used for
+`production` deployments:
+
+```yaml
+include:
+  - template: Auto-DevOps.gitlab-ci.yml
+
+production:
+  environment:
+    kubernetes:
+      namespace: production
+```
+
+When deploying to a custom namespace with Auto DevOps, the service account
+provided with the cluster needs at least the `edit` role within the namespace.
+
+- If the service account can create namespaces, then the namespace can be created on-demand.
+- Otherwise, the namespace must exist prior to deployment.
+
 ### Using components of Auto DevOps
 
 If you only require a subset of the features offered by Auto DevOps, you can include

doc/user/project/clusters/index.md

@@ -281,22 +281,28 @@ GitLab CI/CD build environment.
 | `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This config also embeds the same token defined in `KUBE_TOKEN` so you likely will only need this variable. This variable name is also automatically picked up by `kubectl` so you won't actually need to reference it explicitly if using `kubectl`. |
 | `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, this variable can be used to set a domain per cluster. See [cluster domains](#base-domain) for more information. |
 
-NOTE: **NOTE:**
+NOTE: **Note:**
 Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main
 service account of the cluster integration.
 
 NOTE: **Note:**
 If your cluster was created before GitLab 12.2, default `KUBE_NAMESPACE` will be set to `<project_name>-<project_id>`.
 
-When deploying a custom namespace:
+### Custom namespace
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/27630) in GitLab 12.6.
+
+The Kubernetes integration defaults to project-environment-specific namespaces
+of the form `<project_name>-<project_id>-<environment>` (see [Deployment
+variables](#deployment-variables)).
 
-- The custom namespace must exist in your cluster.
-- The project's deployment service account must have permission to deploy to the namespace.
-- `KUBECONFIG` must be updated to use the custom namespace instead of the GitLab-provided default (this is [not automatic](https://gitlab.com/gitlab-org/gitlab/issues/31519)).
-- If deploying with Auto DevOps, you must *also* override `KUBE_NAMESPACE` with the custom namespace.
+For **non**-GitLab-managed clusters, the namespace can be customized using
+[`environment:kubernetes:namespace`](../../../ci/environments.md#configuring-kubernetes-deployments)
+in `.gitlab-ci.yml`.
 
-CAUTION: **Caution:**
-GitLab does not save custom namespaces in the database. So while deployments work with custom namespaces, GitLab's integration for already-deployed environments will not pick up the customized values. For example, [Deploy Boards](../deploy_boards.md) will not work as intended for those deployments. For more information, see the [related issue](https://gitlab.com/gitlab-org/gitlab/issues/27630).
+NOTE: **Note:** When using a [GitLab-managed cluster](#gitlab-managed-clusters), the
+namespaces are created automatically prior to deployment and [can not be
+customized](https://gitlab.com/gitlab-org/gitlab/issues/38054).
 
 ### Troubleshooting