Commit d2590b15 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch 'update-chart-for-ga-doc' into 'master'

Update `gitlab` chart docs for GA

See merge request gitlab-org/gitlab-ce!21215
parents 5dac2937 94a812f5
# GitLab Helm Chart # GitLab Helm Chart
> **Note:** The chart is currently **beta**, if you encounter any problems please [open an issue](https://gitlab.com/charts/gitlab/issues/new).
For more information on available GitLab Helm Charts, please see our [overview](index.md#chart-overview). This is the official and recommended way to install GitLab on a cloud native environment.
For more information on other available GitLab Helm Charts, see the [charts overview](index.md#chart-overview).
## Introduction ## Introduction
The `gitlab` chart is the best way to operate GitLab on Kubernetes. This chart contains all the required components to get started, and can scale to large deployments. The `gitlab` chart is the best way to operate GitLab on Kubernetes. This chart
contains all the required components to get started, and can scale to large deployments.
The default deployment includes: The default deployment includes:
...@@ -14,78 +15,94 @@ The default deployment includes: ...@@ -14,78 +15,94 @@ The default deployment includes:
- An auto-scaling, unprivileged [GitLab Runner](https://docs.gitlab.com/runner/) using the Kubernetes executor - An auto-scaling, unprivileged [GitLab Runner](https://docs.gitlab.com/runner/) using the Kubernetes executor
- Automatically provisioned SSL via [Let's Encrypt](https://letsencrypt.org/). - Automatically provisioned SSL via [Let's Encrypt](https://letsencrypt.org/).
### Limitations ## Limitations
Some features and functions are not currently available in the beta release. Some features of GitLab are not currently available:
For details, see [known issues and limitations](https://gitlab.com/charts/gitlab/blob/master/doc/architecture/beta.md#known-issues-and-limitations) in the charts repository.
## Prerequisites - [GitLab Pages](https://gitlab.com/charts/gitlab/issues/37)
- [GitLab Geo](https://gitlab.com/charts/gitlab/issues/8)
- [No in-cluster HA database](https://gitlab.com/charts/gitlab/issues/48)
- MySQL will not be supported, as support is [deprecated within GitLab](https://docs.gitlab.com/omnibus/settings/database.html#using-a-mysql-database-management-server-enterprise-edition-only)
In order to deploy GitLab on Kubernetes, a few prerequisites are required. ## Installing GitLab using the Helm Chart
The `gitlab` chart includes all required dependencies, and takes a few minutes
to deploy.
TIP: **Tip:**
For large scale deployments, we strongly recommend using the
[detailed installation instructions](https://gitlab.com/charts/gitlab/blob/master/doc/installation/README.md)
utilizing [external Postgres, Redis, and object storage](https://gitlab.com/charts/gitlab/tree/master/doc/advanced) services.
### Requirements
In order to deploy GitLab on Kubernetes, the following are required:
1. `helm` and `kubectl` [installed on your computer](preparation/tools_installation.md). 1. `helm` and `kubectl` [installed on your computer](preparation/tools_installation.md).
1. A Kubernetes cluster, version 1.8 or higher. 6vCPU and 16GB of RAM is recommended. 1. A Kubernetes cluster, version 1.8 or higher. 6vCPU and 16GB of RAM is recommended.
* [Google GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/creating-a-container-cluster) - [Google GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/creating-a-container-cluster)
* [Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html) - [Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html)
* [Microsoft AKS](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal) - [Microsoft AKS](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal)
1. A [wildcard DNS entry and external IP address](preparation/networking.md) 1. A [wildcard DNS entry and external IP address](preparation/networking.md)
1. [Authenticate and connect](preparation/connect.md) to the cluster 1. [Authenticate and connect](preparation/connect.md) to the cluster
1. Configure and initialize [Helm Tiller](preparation/tiller.md). 1. Configure and initialize [Helm Tiller](preparation/tiller.md).
## Configuring and Installing GitLab ### Deployment of GitLab to Kubernetes
> **Note**: For deployments to Amazon EKS, there are [additional configuration requirements](preparation/eks.md). To deploy GitLab, the following three parameters are required:
For simple deployments, running all services within Kubernetes, only three parameters are required: - `global.hosts.domain`: the [base domain](preparation/networking.md) of the
- `global.hosts.domain`: the [base domain](preparation/networking.md) of the wildcard host entry. For example, `mycompany.io` if the wild card entry is `*.mycompany.io`. wildcard host entry. For example, `exampe.com` if the wild card entry is
- `global.hosts.externalIP`: the [external IP](preparation/networking.md) which the wildcard DNS resolves to. `*.example.com`.
- `certmanager-issuer.email`: Email address to use when requesting new SSL certificates from Let's Encrypt. - `global.hosts.externalIP`: the [external IP](preparation/networking.md) which
the wildcard DNS resolves to.
- `certmanager-issuer.email`: the email address to use when requesting new SSL
certificates from Let's Encrypt.
For enterprise deployments, or to utilize advanced settings, please use the instructions in the [`gitlab` chart project](https://gitlab.com/charts/gitlab) for the most up to date directions. NOTE: **Note:**
- [External Postgres, Redis, and other dependencies](https://gitlab.com/charts/gitlab/tree/master/doc/advanced) For deployments to Amazon EKS, there are
- [Persistence settings](https://gitlab.com/charts/gitlab/blob/master/doc/installation/storage.md) [additional configuration requirements](preparation/eks.md). A full list of
- [Manual TLS certificates](https://gitlab.com/charts/gitlab/blob/master/doc/installation/tls.md) configuration options is [also available](https://gitlab.com/charts/gitlab/blob/master/doc/installation/command-line-options.md).
- [Manual secret creation](https://gitlab.com/charts/gitlab/blob/master/doc/installation/secrets.md)
For additional configuration options, consult the [full list of settings](https://gitlab.com/charts/gitlab/blob/master/doc/installation/command-line-options.md). Once you have all of your configuration options collected, you can get any
dependencies and run helm. In this example, the helm release is named "gitlab":
## Installing GitLab using the Helm Chart ```sh
Once you have all of your configuration options collected, we can get any dependencies and
run helm. In this example, we've named our helm release "gitlab".
```
helm repo add gitlab https://charts.gitlab.io/ helm repo add gitlab https://charts.gitlab.io/
helm update helm repo update
helm upgrade --install gitlab gitlab/gitlab \ helm upgrade --install gitlab gitlab/gitlab \
--timeout 600 \ --timeout 600 \
--set global.hosts.domain=example.local \ --set global.hosts.domain=example.com \
--set global.hosts.externalIP=10.10.10.10 \ --set global.hosts.externalIP=10.10.10.10 \
--set certmanager-issuer.email=me@example.local --set certmanager-issuer.email=email@example.com
``` ```
### Monitoring the Deployment ### Monitoring the Deployment
This will output the list of resources installed once the deployment finishes which may take 5-10 minutes. This will output the list of resources installed once the deployment finishes,
which may take 5-10 minutes.
The status of the deployment can be checked by running `helm status gitlab` which can also be done while The status of the deployment can be checked by running `helm status gitlab`
the deployment is taking place if you run the command in another terminal. which can also be done while the deployment is taking place if you run the
command in another terminal.
### Initial login ### Initial login
You can access the GitLab instance by visiting the domain name beginning with `gitlab.` followed by the domain specified during installation. From the example above, the URL would be `https://gitlab.example.local`. You can access the GitLab instance by visiting the domain name beginning with
`gitlab.` followed by the domain specified during installation. From the example
above, the URL would be `https://gitlab.example.com`.
If you manually created the secret for initial root password, you If you manually created the secret for initial root password, you
can use that to sign in as `root` user. If not, Gitlab automatically can use that to sign in as `root` user. If not, Gitlab automatically
created a random password for `root` user. This can be extracted by the created a random password for `root` user. This can be extracted by the
following command (replace `<name>` by name of the release - which is `gitlab` following command (replace `<name>` by name of the release - which is `gitlab`
if you used the command above). if you used the command above):
``` ```sh
kubectl get secret <name>-gitlab-initial-root-password -ojsonpath={.data.password} | base64 --decode kubectl get secret <name>-gitlab-initial-root-password -ojsonpath={.data.password} | base64 --decode ; echo
``` ```
## Outgoing email ### Outgoing email
By default outgoing email is disabled. To enable it, provide details for your SMTP server By default outgoing email is disabled. To enable it, provide details for your SMTP server
using the `global.smtp` and `global.email` settings. You can find details for these settings in the using the `global.smtp` and `global.email` settings. You can find details for these settings in the
...@@ -95,14 +112,14 @@ If your SMTP server requires authentication make sure to read the section on pro ...@@ -95,14 +112,14 @@ If your SMTP server requires authentication make sure to read the section on pro
your password in the [secrets documentation](https://gitlab.com/charts/gitlab/blob/master/doc/installation/secrets.md#smtp-password). your password in the [secrets documentation](https://gitlab.com/charts/gitlab/blob/master/doc/installation/secrets.md#smtp-password).
You can disable authentication settings with `--set global.smtp.authentication=""`. You can disable authentication settings with `--set global.smtp.authentication=""`.
If your Kubernetes cluster is on GKE, be aware that smtp [ports 25, 465, and 587 If your Kubernetes cluster is on GKE, be aware that SMTP ports [25, 465, and 587
are blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/#using_standard_email_ports). are blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/#using_standard_email_ports).
## Deploying the Community Edition ### Deploying the Community Edition
To deploy the Community Edition, include these options in your `helm install` command: To deploy the Community Edition, include these options in your `helm install` command:
```shell ```sh
--set gitlab.migrations.image.repository=registry.gitlab.com/gitlab-org/build/cng/gitlab-rails-ce --set gitlab.migrations.image.repository=registry.gitlab.com/gitlab-org/build/cng/gitlab-rails-ce
--set gitlab.sidekiq.image.repository=registry.gitlab.com/gitlab-org/build/cng/gitlab-sidekiq-ce --set gitlab.sidekiq.image.repository=registry.gitlab.com/gitlab-org/build/cng/gitlab-sidekiq-ce
--set gitlab.unicorn.image.repository=registry.gitlab.com/gitlab-org/build/cng/gitlab-unicorn-ce --set gitlab.unicorn.image.repository=registry.gitlab.com/gitlab-org/build/cng/gitlab-unicorn-ce
...@@ -113,15 +130,15 @@ To deploy the Community Edition, include these options in your `helm install` co ...@@ -113,15 +130,15 @@ To deploy the Community Edition, include these options in your `helm install` co
Once your GitLab Chart is installed, configuration changes and chart updates Once your GitLab Chart is installed, configuration changes and chart updates
should be done using `helm upgrade`: should be done using `helm upgrade`:
```bash ```sh
helm upgrade -f values.yaml gitlab gitlab/gitlab helm upgrade --reuse-values gitlab gitlab/gitlab
``` ```
## Uninstalling GitLab using the Helm Chart ## Uninstalling GitLab using the Helm Chart
To uninstall the GitLab Chart, run the following: To uninstall the GitLab Chart, run the following:
```bash ```sh
helm delete gitlab helm delete gitlab
``` ```
......
This diff is collapsed.
...@@ -4,7 +4,8 @@ description: 'Read through the different methods to deploy GitLab on Kubernetes. ...@@ -4,7 +4,8 @@ description: 'Read through the different methods to deploy GitLab on Kubernetes.
# Installing GitLab on Kubernetes # Installing GitLab on Kubernetes
> **Note**: These charts have been tested on Google Kubernetes Engine. Other Kubernetes installations may work as well, if not please [open an issue](https://gitlab.com/charts/issues). NOTE: **Note**: These charts have been tested on Google Kubernetes Engine. Other
Kubernetes installations may work as well, if not please [open an issue](https://gitlab.com/charts/issues).
The easiest method to deploy GitLab on [Kubernetes](https://kubernetes.io/) is The easiest method to deploy GitLab on [Kubernetes](https://kubernetes.io/) is
to take advantage of GitLab's Helm charts. [Helm] is a package to take advantage of GitLab's Helm charts. [Helm] is a package
...@@ -14,30 +15,31 @@ should be deployed, upgraded, and configured. ...@@ -14,30 +15,31 @@ should be deployed, upgraded, and configured.
## Chart Overview ## Chart Overview
* **[GitLab Chart](gitlab_chart.html)**: The recommended GitLab chart, currently in beta. Supports large deployments with horizontal scaling of individual GitLab components, and does not require NFS. - **[GitLab Chart](gitlab_chart.html)**: Deploys GitLab on Kubernetes. Includes all the required components to get started, and can scale to large deployments.
* **[GitLab Runner Chart](gitlab_runner_chart.md)**: For deploying just the GitLab Runner. - **[GitLab Runner Chart](gitlab_runner_chart.md)**: For deploying just the GitLab Runner.
* Other Charts - Other Charts
* [GitLab-Omnibus](gitlab_omnibus.md): Chart based on the Omnibus GitLab linux package, only suitable for small deployments. The chart will be deprecated by the [GitLab chart](#gitlab-chart) when it is GA. - [GitLab-Omnibus](gitlab_omnibus.md): Chart based on the Omnibus GitLab package, only suitable for small deployments. Deprecated, we strongly recommend using the [gitlab](#gitlab-chart) chart.
* [Community Contributed Charts](#community-contributed-charts): Community contributed charts, deprecated by the official GitLab chart. - [Community contributed charts](#community-contributed-charts): Community contributed charts.
## GitLab Chart ## GitLab Chart
> **Note**: This chart is **beta**, while we work on the [remaining items for GA](https://gitlab.com/groups/charts/-/epics/15). This chart contains all the required components to get started, and can scale to
large deployments. It offers a number of benefits:
The best way to operate GitLab on Kubernetes. This chart contains all the required components to get started, and can scale to large deployments. - Horizontal scaling of individual components
- No requirement for shared storage to scale
- Containers do not need `root` permissions
- Automatic SSL with Let's Encrypt
- and plenty more.
This chart offers a number of benefits: Learn more about the [GitLab chart](gitlab_chart.md).
* Horizontal scaling of individual components
* No requirement for shared storage to scale
* Containers do not need `root` permissions
* Automatic SSL with Let's Encrypt
* and plenty more.
Learn more about the [GitLab chart here](gitlab_chart.md) and [here [Video]](https://youtu.be/Z6jWR8Z8dv8).
## GitLab Runner Chart ## GitLab Runner Chart
If you already have a GitLab instance running, inside or outside of Kubernetes, and you'd like to leverage the Runner's [Kubernetes capabilities](https://docs.gitlab.com/runner/executors/kubernetes.html), it can be deployed with the GitLab Runner chart. If you already have a GitLab instance running, inside or outside of Kubernetes,
and you'd like to leverage the Runner's
[Kubernetes capabilities](https://docs.gitlab.com/runner/executors/kubernetes.html),
it can be deployed with the GitLab Runner chart.
Learn more about [gitlab-runner chart](gitlab_runner_chart.md). Learn more about [gitlab-runner chart](gitlab_runner_chart.md).
...@@ -45,11 +47,18 @@ Learn more about [gitlab-runner chart](gitlab_runner_chart.md). ...@@ -45,11 +47,18 @@ Learn more about [gitlab-runner chart](gitlab_runner_chart.md).
### GitLab-Omnibus Chart ### GitLab-Omnibus Chart
> **Note**: This chart is beta, and **will be deprecated** when the [`gitlab`](#gitlab-chart) chart is GA. CAUTION: **Deprecated:**
This chart is **deprecated**. We recommend using the [GitLab Chart](gitlab_chart.md)
instead. A comparison of the two charts is available in [this video](https://youtu.be/Z6jWR8Z8dv8).
It deploys and configures nearly all features of GitLab, including: a [Runner](https://docs.gitlab.com/runner/), [Container Registry](../../user/project/container_registry.html#gitlab-container-registry), [Mattermost](https://docs.gitlab.com/omnibus/gitlab-mattermost/), [automatic SSL](https://github.com/kubernetes/charts/tree/master/stable/kube-lego), and a [load balancer](https://github.com/kubernetes/ingress/tree/master/controllers/nginx). It is based on our [GitLab Omnibus Docker Images](https://docs.gitlab.com/omnibus/docker/README.html). This chart is based on the [GitLab Omnibus Docker images](https://docs.gitlab.com/omnibus/docker/).
It deploys and configures nearly all features of GitLab, including:
Once the [GitLab chart](#gitlab-chart) is GA, this chart will be deprecated. Migrating to the `gitlab` chart will require exporting data out of this instance and importing it into a new deployment. - a [GitLab Runner](https://docs.gitlab.com/runner/)
- [Container Registry](../../user/project/container_registry.html#gitlab-container-registry)
- [Mattermost](https://docs.gitlab.com/omnibus/gitlab-mattermost/)
- [automatic SSL](https://github.com/kubernetes/charts/tree/master/stable/kube-lego)
- and an [NGINX load balancer](https://github.com/kubernetes/ingress/tree/master/controllers/nginx).
Learn more about the [gitlab-omnibus chart](gitlab_omnibus.md). Learn more about the [gitlab-omnibus chart](gitlab_omnibus.md).
......
...@@ -2,19 +2,14 @@ ...@@ -2,19 +2,14 @@
In order to deploy software and settings to a cluster, you must connect and authenticate to it. In order to deploy software and settings to a cluster, you must connect and authenticate to it.
* [GKE cluster](#connect-to-gke-cluster)
* [EKS cluster](#connect-to-eks-cluster)
* [Local minikube cluster](#connect-to-local-minikube-cluster)
## Connect to GKE cluster ## Connect to GKE cluster
The command for connection to the cluster can be obtained from the [Google Cloud Platform Console](https://console.cloud.google.com/kubernetes/list) by the individual cluster. The command for connection to the cluster can be obtained from the
[Google Cloud Platform Console](https://console.cloud.google.com/kubernetes/list)
Look for the **Connect** button in the clusters list page. by the individual cluster.
**Or**
Use the command below, filling in your cluster's informtion: Look for the **Connect** button in the clusters list page or use the command below,
filling in your cluster's information:
``` ```
gcloud container clusters get-credentials <cluster-name> --zone <zone> --project <project-id> gcloud container clusters get-credentials <cluster-name> --zone <zone> --project <project-id>
...@@ -22,7 +17,8 @@ gcloud container clusters get-credentials <cluster-name> --zone <zone> --project ...@@ -22,7 +17,8 @@ gcloud container clusters get-credentials <cluster-name> --zone <zone> --project
## Connect to EKS cluster ## Connect to EKS cluster
For the most up to date instructions, follow the Amazon EKS documentation on [connecting to a cluster](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#eks-configure-kubectl). For the most up to date instructions, follow the Amazon EKS documentation on
[connecting to a cluster](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#eks-configure-kubectl).
## Connect to local minikube cluster ## Connect to local minikube cluster
......
# Networking Prerequisites # Networking Prerequisites
> **Note**: Amazon EKS utilizes Elastic Load Balancers, which are addressed by DNS name and cannot be known ahead of time. Skip this section. NOTE: **Note:**
Amazon EKS utilizes Elastic Load Balancers, which are addressed by DNS name and
cannot be known ahead of time. If you're using EKS, you can skip this section.
The `gitlab` chart configures a GitLab server and Kubernetes cluster which can support dynamic [Review Apps](https://docs.gitlab.com/ee/ci/review_apps/index.html), as well as services like the integrated [Container Registry](https://docs.gitlab.com/ee/user/project/container_registry.html). The `gitlab` chart configures a GitLab server and Kubernetes cluster which can support dynamic [Review Apps](https://docs.gitlab.com/ee/ci/review_apps/index.html), as well as services like the integrated [Container Registry](https://docs.gitlab.com/ee/user/project/container_registry.html).
...@@ -30,7 +32,7 @@ Now that an external IP address has been allocated, ensure that the wildcard DNS ...@@ -30,7 +32,7 @@ Now that an external IP address has been allocated, ensure that the wildcard DNS
Please consult the documentation for your DNS service for more information on creating DNS records: Please consult the documentation for your DNS service for more information on creating DNS records:
* [Google Domains](https://support.google.com/domains/answer/3290350?hl=en) - [Google Domains](https://support.google.com/domains/answer/3290350?hl=en)
* [GoDaddy](https://www.godaddy.com/help/add-an-a-record-19238) - [GoDaddy](https://www.godaddy.com/help/add-an-a-record-19238)
Set `global.hosts.domain` to this DNS name when [deploying GitLab](../gitlab_chart.md#configuring-and-installing-gitlab). Set `global.hosts.domain` to this DNS name when [deploying GitLab](../gitlab_chart.md#configuring-and-installing-gitlab).
# Role Based Access Control # Role Based Access Control
Until Kubernetes 1.7, there were no permissions within a cluster. With the launch of 1.7, there is now a role based access control system ([RBAC](https://kubernetes.io/docs/admin/authorization/rbac/)) which determines what services can perform actions within a cluster. Until Kubernetes 1.7, there were no permissions within a cluster. With the launch
of 1.7, there is now a [role based access control system (RBAC)](https://kubernetes.io/docs/admin/authorization/rbac/)
which determines what services can perform actions within a cluster.
RBAC affects a few different aspects of GitLab: RBAC affects a few different aspects of GitLab:
* [Installation of GitLab using Helm](tiller.md#preparing-for-helm-with-rbac)
* Prometheus monitoring
* GitLab Runner
## Checking that RBAC is enabled - [Installation of GitLab using Helm](tiller.md#preparing-for-helm-with-rbac)
- Prometheus monitoring
- GitLab Runner
Try listing the current cluster roles, if it fails then `RBAC` is disabled ## Checking that RBAC is enabled
This command will output `false` if `RBAC` is disabled and `true` otherwise Try listing the current cluster roles, if it fails then `RBAC` is disabled.
The following command will output `false` if `RBAC` is disabled and `true` otherwise:
`kubectl get clusterroles > /dev/null 2>&1 && echo true || echo false` ```sh
kubectl get clusterroles > /dev/null 2>&1 && echo true || echo false
```
# Configuring and initializing Helm Tiller # Configuring and initializing Helm Tiller
To make use of Helm, you must have a [Kubernetes][k8s-io] cluster. Ensure you can access your cluster using `kubectl`. To make use of Helm, you must have a [Kubernetes][k8s-io] cluster. Ensure you can
access your cluster using `kubectl`.
Helm consists of two parts, the `helm` client and a `tiller` server inside Kubernetes. Helm consists of two parts, the `helm` client and a `tiller` server inside Kubernetes.
> **Note**: If you are not able to run Tiller in your cluster, for example on OpenShift, it is possible to use [Tiller locally](https://gitlab.com/charts/gitlab/tree/master/doc/helm#local-tiller) and avoid deploying it into the cluster. This should only be used when Tiller cannot be normally deployed. NOTE: **Note:**
If you are not able to run Tiller in your cluster, for example on OpenShift, it
is possible to use [Tiller locally](https://gitlab.com/charts/gitlab/tree/master/doc/helm#local-tiller)
and avoid deploying it into the cluster. This should only be used when Tiller
cannot be normally deployed.
## Initialize Helm and Tiller ## Initialize Helm and Tiller
......
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