Merge branch '34758-group-cluster-docs' into 'master'
Documentation for Group-level Kubernetes cluster configuration See merge request gitlab-org/gitlab-ce!22804
This commit is contained in:
commit
b74a4161d5
|
@ -132,7 +132,8 @@ in three places:
|
|||
|
||||
- either under the project's CI/CD settings while [enabling Auto DevOps](#enabling-auto-devops)
|
||||
- or in instance-wide settings in the **admin area > Settings** under the "Continuous Integration and Delivery" section
|
||||
- or at the project or group level as a variable: `AUTO_DEVOPS_DOMAIN` (required if you want to use [multiple clusters](#using-multiple-kubernetes-clusters))
|
||||
- or at the project as a variable: `AUTO_DEVOPS_DOMAIN` (required if you want to use [multiple clusters](#using-multiple-kubernetes-clusters))
|
||||
- or at the group level as a variable: `AUTO_DEVOPS_DOMAIN`
|
||||
|
||||
A wildcard DNS A record matching the base domain(s) is required, for example,
|
||||
given a base domain of `example.com`, you'd need a DNS entry like:
|
||||
|
@ -203,6 +204,12 @@ and verifying that your app is deployed as a review app in the Kubernetes
|
|||
cluster with the `review/*` environment scope. Similarly, you can check the
|
||||
other environments.
|
||||
|
||||
NOTE: **Note:**
|
||||
Auto DevOps is not supported for a group with multiple clusters, as it
|
||||
is not possible to set `AUTO_DEVOPS_DOMAIN` per environment on the group
|
||||
level. This will be resolved in the future with the [following issue](
|
||||
https://gitlab.com/gitlab-org/gitlab-ce/issues/52363).
|
||||
|
||||
## Enabling/Disabling Auto DevOps
|
||||
|
||||
When first using Auto Devops, review the [requirements](#requirements) to ensure all necessary components to make
|
||||
|
|
|
@ -0,0 +1,126 @@
|
|||
# Group-level Kubernetes clusters
|
||||
|
||||
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/34758) in GitLab 11.6.
|
||||
|
||||
CAUTION: **Warning:**
|
||||
Group Cluster integration is currently in **Beta**.
|
||||
|
||||
## Overview
|
||||
|
||||
Similar to [project Kubernetes
|
||||
clusters](../../project/clusters/index.md), Group-level Kubernetes
|
||||
clusters allow you to connect a Kubernetes cluster to your group,
|
||||
enabling you to use the same cluster across multiple projects.
|
||||
|
||||
## Installing applications
|
||||
|
||||
GitLab provides a one-click install for various applications that can be
|
||||
added directly to your cluster.
|
||||
|
||||
NOTE: **Note:**
|
||||
Applications will be installed in a dedicated namespace called
|
||||
`gitlab-managed-apps`. If you have added an existing Kubernetes cluster
|
||||
with Tiller already installed, you should be careful as GitLab cannot
|
||||
detect it. In this event, installing Tiller via the applications will
|
||||
result in the cluster having it twice. This can lead to confusion during
|
||||
deployments.
|
||||
|
||||
| Application | GitLab version | Description | Helm Chart |
|
||||
| ----------- | -------------- | ----------- | ---------- |
|
||||
| [Helm Tiller](https://docs.helm.sh) | 10.2+ | Helm is a package manager for Kubernetes and is required to install all the other applications. It is installed in its own pod inside the cluster which can run the `helm` CLI in a safe environment. | n/a |
|
||||
| [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress) | 10.2+ | Ingress can provide load balancing, SSL termination, and name-based virtual hosting. It acts as a web proxy for your applications and is useful if you want to use [Auto DevOps](../../../topics/autodevops/index.md) or deploy your own web apps. | [stable/nginx-ingress](https://github.com/helm/charts/tree/master/stable/nginx-ingress) |
|
||||
|
||||
## RBAC compatibility
|
||||
|
||||
For each project under a group with a Kubernetes cluster, GitLab will
|
||||
create a restricted service account with [`edit`
|
||||
privileges](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles)
|
||||
in the project namespace.
|
||||
|
||||
NOTE: **Note:**
|
||||
RBAC support was introduced in
|
||||
[GitLab 11.4](https://gitlab.com/gitlab-org/gitlab-ce/issues/29398), and
|
||||
Project namespace restriction was introduced in
|
||||
[GitLab 11.5](https://gitlab.com/gitlab-org/gitlab-ce/issues/51716).
|
||||
|
||||
## Cluster precedence
|
||||
|
||||
GitLab will use the project's cluster before using any cluster belonging
|
||||
to the group containing the project if the project's cluster is available and not disabled.
|
||||
|
||||
In the case of sub-groups, GitLab will use the cluster of the closest ancestor group
|
||||
to the project, provided the cluster is not disabled.
|
||||
|
||||
## Multiple Kubernetes clusters **[PREMIUM]**
|
||||
|
||||
With GitLab Premium, you can associate more than one Kubernetes clusters to your
|
||||
group. That way you can have different clusters for different environments,
|
||||
like dev, staging, production, etc.
|
||||
|
||||
Add another cluster similar to the first one and make sure to
|
||||
[set an environment scope](#environment-scopes) that will
|
||||
differentiate the new cluster from the rest.
|
||||
|
||||
NOTE: **Note:**
|
||||
Auto DevOps is not supported for a group with multiple clusters, as it
|
||||
is not possible to set `AUTO_DEVOPS_DOMAIN` per environment on the group
|
||||
level. This will be resolved in the future with the [following issue](
|
||||
https://gitlab.com/gitlab-org/gitlab-ce/issues/52363).
|
||||
|
||||
## Environment scopes **[PREMIUM]**
|
||||
|
||||
When adding more than one Kubernetes cluster to your project, you need
|
||||
to differentiate them with an environment scope. The environment scope
|
||||
associates clusters with [environments](../../../ci/environments.md)
|
||||
similar to how the [environment-specific
|
||||
variables](../../../ci/variables/README.md#limiting-environment-scopes-of-variables)
|
||||
work.
|
||||
|
||||
While evaluating which environment matches the environment scope of a
|
||||
cluster, [cluster precedence](#cluster-precedence) will take
|
||||
effect. The cluster at the project level will take precedence, followed
|
||||
by the closest ancestor group, followed by that groups' parent and so
|
||||
on.
|
||||
|
||||
For example, let's say we have the following Kubernetes clusters:
|
||||
|
||||
| Cluster | Environment scope | Where |
|
||||
| ---------- | ------------------- | ----------|
|
||||
| Project | `*` | Project |
|
||||
| Staging | `staging/*` | Project |
|
||||
| Production | `production/*` | Project |
|
||||
| Test | `test` | Group |
|
||||
| Development| `*` | Group |
|
||||
|
||||
|
||||
And the following environments are set in [`.gitlab-ci.yml`](../../../ci/yaml/README.md):
|
||||
|
||||
```yaml
|
||||
stages:
|
||||
- test
|
||||
- deploy
|
||||
|
||||
test:
|
||||
stage: test
|
||||
script: sh test
|
||||
|
||||
deploy to staging:
|
||||
stage: deploy
|
||||
script: make deploy
|
||||
environment:
|
||||
name: staging/$CI_COMMIT_REF_NAME
|
||||
url: https://staging.example.com/
|
||||
|
||||
deploy to production:
|
||||
stage: deploy
|
||||
script: make deploy
|
||||
environment:
|
||||
name: production/$CI_COMMIT_REF_NAME
|
||||
url: https://example.com/
|
||||
```
|
||||
|
||||
The result will then be:
|
||||
|
||||
- The Project cluster will be used for the `test` job.
|
||||
- The Staging cluster will be used for the `deploy to staging` job.
|
||||
- The Production cluster will be used for the `deploy to production` job.
|
|
@ -269,6 +269,7 @@ Define project templates at a group-level by setting a group as a template sourc
|
|||
- **Projects**: view all projects within that group, add members to each project,
|
||||
access each project's settings, and remove any project from the same screen.
|
||||
- **Webhooks**: configure [webhooks](../project/integrations/webhooks.md) to your group.
|
||||
- **Kubernetes cluster integration**: connect your GitLab group with [Kubernetes clusters](clusters/index.md).
|
||||
- **Audit Events**: view [Audit Events](https://docs.gitlab.com/ee/administration/audit_events.html#audit-events)
|
||||
for the group. **[STARTER ONLY]**
|
||||
- **Pipelines quota**: keep track of the [pipeline quota](../admin_area/settings/continuous_integration.md) for the group
|
||||
- **Pipelines quota**: keep track of the [pipeline quota](../admin_area/settings/continuous_integration.md) for the group.
|
||||
|
|
|
@ -17,6 +17,11 @@ your account with Google Kubernetes Engine (GKE) so that you can [create new
|
|||
clusters](#adding-and-creating-a-new-gke-cluster-via-gitlab) from within GitLab,
|
||||
or provide the credentials to an [existing Kubernetes cluster](#adding-an-existing-kubernetes-cluster).
|
||||
|
||||
NOTE: **Note:**
|
||||
From [GitLab 11.6](https://gitlab.com/gitlab-org/gitlab-ce/issues/34758) you
|
||||
can also associate a Kubernetes cluster to your groups. Learn more about
|
||||
[group Kubernetes clusters](../../group/clusters/index.md).
|
||||
|
||||
## Adding and creating a new GKE cluster via GitLab
|
||||
|
||||
TIP: **Tip:**
|
||||
|
@ -245,16 +250,18 @@ install it manually.
|
|||
|
||||
## Installing applications
|
||||
|
||||
GitLab provides a one-click install for various applications which will be
|
||||
added directly to your configured cluster. Those applications are needed for
|
||||
[Review Apps](../../../ci/review_apps/index.md) and [deployments](../../../ci/environments.md).
|
||||
GitLab provides a one-click install for various applications which can
|
||||
be added directly to your configured cluster. Those applications are
|
||||
needed for [Review Apps](../../../ci/review_apps/index.md) and
|
||||
[deployments](../../../ci/environments.md).
|
||||
|
||||
NOTE: **Note:**
|
||||
With the exception of Knative, the applications will be installed in a dedicated namespace called
|
||||
`gitlab-managed-apps`. In case you have added an existing Kubernetes cluster
|
||||
with Tiller already installed, you should be careful as GitLab cannot
|
||||
detect it. By installing it via the applications will result into having it
|
||||
twice, which can lead to confusion during deployments.
|
||||
detect it. In this event, installing Tiller via the applications will
|
||||
result in the cluster having it twice. This can lead to confusion during
|
||||
deployments.
|
||||
|
||||
| Application | GitLab version | Description | Helm Chart |
|
||||
| ----------- | :------------: | ----------- | --------------- |
|
||||
|
@ -347,17 +354,13 @@ to reach your apps. This heavily depends on your domain provider, but in case
|
|||
you aren't sure, just create an A record with a wildcard host like
|
||||
`*.example.com.`.
|
||||
|
||||
## Setting the environment scope
|
||||
## Setting the environment scope **[PREMIUM]**
|
||||
|
||||
NOTE: **Note:**
|
||||
This is only available for [GitLab Premium][ee] where you can add more than
|
||||
one Kubernetes cluster.
|
||||
|
||||
When adding more than one Kubernetes clusters to your project, you need to
|
||||
differentiate them with an environment scope. The environment scope associates
|
||||
clusters and [environments](../../../ci/environments.md) in an 1:1 relationship
|
||||
similar to how the
|
||||
[environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-variables)
|
||||
When adding more than one Kubernetes clusters to your project, you need
|
||||
to differentiate them with an environment scope. The environment scope
|
||||
associates clusters with [environments](../../../ci/environments.md)
|
||||
similar to how the [environment-specific
|
||||
variables](../../../ci/variables/README.md#limiting-environment-scopes-of-variables)
|
||||
work.
|
||||
|
||||
The default environment scope is `*`, which means all jobs, regardless of their
|
||||
|
|
Loading…
Reference in New Issue