Commit 4c691b22 authored by Evan Read's avatar Evan Read

Merge branch 'doc-update-docs-for-custom-k8s-namespace' into 'master'

Update documentation for custom k8s namespaces

See merge request gitlab-org/gitlab!25845
parents 8fc245de 5aaf0abb
......@@ -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).
......
......@@ -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
......
......@@ -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
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment