Deprecate the Kubernetes service docs

parent 5b0e96d0
# Web terminals
> [Introduced][ce-7690] in GitLab 8.15. Only project masters and owners can
access web terminals.
in GitLab 8.15. Only project masters and owners can access web terminals.
With the introduction of the [Kubernetes project service][kubservice], GitLab
gained the ability to store and use credentials for a Kubernetes cluster. One
of the things it uses these credentials for is providing access to
[web terminals](../../ci/environments.html#web-terminals) for environments.
With the introduction of the [Kubernetes integration](../../user/project/clusters/,
GitLab gained the ability to store and use credentials for a Kubernetes cluster.
One of the things it uses these credentials for is providing access to
[web terminals](../../ci/ for environments.
## How it works
......@@ -80,6 +81,3 @@ Terminal sessions use long-lived connections; by default, these may last
forever. You can configure a maximum session time in the Admin area of your
GitLab instance if you find this undesirable from a scalability or security
point of view.
[kubservice]: ../../user/project/integrations/
# Auto Deploy
> [Introduced][mr-8135] in GitLab 8.15.
> Auto deploy is an experimental feature and is **not recommended for Production use** at this time.
> As of GitLab 9.1, access to the container registry is only available while the
Pipeline is running. Restarting a pod, scaling a service, or other actions which
require on-going access **will fail**. On-going secure access is planned for a
subsequent release.
> As of GitLab 10.0, Auto Deploy templates are **deprecated** and the
functionality has been included in [Auto
Auto deploy is an easy way to configure GitLab CI for the deployment of your
application. GitLab Community maintains a list of `.gitlab-ci.yml`
templates for various infrastructure providers and deployment scripts
powering them. These scripts are responsible for packaging your application,
setting up the infrastructure and spinning up necessary services (for
example a database).
## How it works
The Autodeploy templates are based on the [kubernetes-deploy][kube-deploy]
project which is used to simplify the deployment process to Kubernetes by
providing intelligent `build`, `deploy`, and `destroy` commands which you can
use in your `.gitlab-ci.yml` as is. It uses [Herokuish](,
which uses [Heroku buildpacks](
to do some of the work, plus some of GitLab's own tools to package it all up. For
your convenience, a [Docker image][kube-image] is also provided.
You can use the [Kubernetes project service](../../user/project/integrations/
to store credentials to your infrastructure provider and they will be available
during the deployment.
## Quick start
We made a [simple guide]( to using Auto Deploy with
For a demonstration of GitLab Auto Deploy, read the blog post [Auto Deploy from GitLab to an OpenShift Container Cluster](
## Supported templates
The list of supported auto deploy templates is available in the
[gitlab-ci-yml project][auto-deploy-templates].
## Configuration
In order to understand why the following steps are required, read the
[how it works](#how-it-works) section.
To configure Autodeploy, you will need to:
1. Enable a deployment [project service][project-services] to store your
credentials. For example, if you want to deploy to OpenShift you have to
enable [Kubernetes service][kubernetes-service].
1. Configure GitLab Runner to use the
[Docker or Kubernetes executor]( with
[privileged mode enabled][docker-in-docker].
1. Navigate to the "Project" tab and click "Set up auto deploy" button.
![Auto deploy button](img/auto_deploy_button.png)
1. Select a template.
![Dropdown with auto deploy templates](img/auto_deploy_dropdown.png)
1. Commit your changes and create a merge request.
1. Test your deployment configuration using a [Review App][review-app] that was
created automatically for you.
## Private project support
> Experimental support [introduced][mr-2] in GitLab 9.1.
When a project has been marked as private, GitLab's [Container Registry][container-registry] requires authentication when downloading containers. Auto deploy will automatically provide the required authentication information to Kubernetes, allowing temporary access to the registry. Authentication credentials will be valid while the pipeline is running, allowing for a successful initial deployment.
After the pipeline completes, Kubernetes will no longer be able to access the container registry. Restarting a pod, scaling a service, or other actions which require on-going access to the registry will fail. On-going secure access is planned for a subsequent release.
## PostgreSQL database support
> Experimental support [introduced][mr-8] in GitLab 9.1.
In order to support applications that require a database, [PostgreSQL][postgresql] is provisioned by default. Credentials to access the database are preconfigured, but can be customized by setting the associated [variables](#postgresql-variables). These credentials can be used for defining a `DATABASE_URL` of the format: `postgres://user:password@postgres-host:postgres-port/postgres-database`. It is important to note that the database itself is temporary, and contents will be not be saved.
PostgreSQL provisioning can be disabled by setting the variable `DISABLE_POSTGRES` to `"yes"`.
The following PostgreSQL variables are supported:
1. `DISABLE_POSTGRES: "yes"`: disable automatic deployment of PostgreSQL
1. `POSTGRES_USER: "my-user"`: use custom username for PostgreSQL
1. `POSTGRES_PASSWORD: "password"`: use custom password for PostgreSQL
1. `POSTGRES_DB: "my database"`: use custom database name for PostgreSQL
## Auto Monitoring
> Introduced in [GitLab 9.5](
Apps auto-deployed using one the [Kubernetes templates](#supported-templates) can also be automatically monitored for:
* Response Metrics: latency, throughput, error rate
* System Metrics: CPU utilization, memory utilization
Metrics are gathered from [nginx-ingress](../../user/project/integrations/prometheus_library/ and [Kubernetes](../../user/project/integrations/prometheus_library/
To view the metrics, open the [Monitoring dashboard for a deployed environment](../
![Auto Metrics](img/auto_monitoring.png)
### Configuring Auto Monitoring
If GitLab has been deployed using the [omnibus-gitlab](../../install/kubernetes/ Helm chart, no configuration is required.
If you have installed GitLab using a different method:
1. [Deploy Prometheus](../../user/project/integrations/ into your Kubernetes cluster
1. If you would like response metrics, ensure you are running at least version 0.9.0 of NGINX Ingress and [enable Prometheus metrics](
1. Finally, [annotate]( the NGINX Ingress deployment to be scraped by Prometheus using ` "true"` and ` "10254"`.
[project-services]: ../../user/project/integrations/
[kubernetes-service]: ../../user/project/integrations/
[docker-in-docker]: ../docker/
[review-app]: ../review_apps/
[kube-image]: "Kubernetes deploy Container Registry"
[kube-deploy]: "Kubernetes deploy example project"
This document was moved to [another location](../../topics/autodevops/
......@@ -24,7 +24,7 @@ Environments are like tags for your CI jobs, describing where code gets deployed
Deployments are created when [jobs] deploy versions of code to environments,
so every environment can have one or more deployments. GitLab keeps track of
your deployments, so you always know what is currently being deployed on your
servers. If you have a deployment service such as [Kubernetes][kubernetes-service]
servers. If you have a deployment service such as [Kubernetes][kube]
enabled for your project, you can use it to assist with your deployments, and
can even access a [web terminal](#web-terminals) for your environment from within GitLab!
......@@ -604,7 +604,7 @@ Web terminals were added in GitLab 8.15 and are only available to project
masters and owners.
If you deploy to your environments with the help of a deployment service (e.g.,
the [Kubernetes service][kubernetes-service]), GitLab can open
the [Kubernetes integration][kube]), GitLab can open
a terminal session to your environment! This is a very powerful feature that
allows you to debug issues without leaving the comfort of your web browser. To
enable it, just follow the instructions given in the service integration
......@@ -670,7 +670,6 @@ Below are some links you may find interesting:
[jobs]: yaml/
[yaml]: yaml/
[kubernetes-service]: ../user/project/integrations/
[environments]: #environments
[deployments]: #deployments
[permissions]: ../user/
......@@ -682,5 +681,5 @@ Below are some links you may find interesting:
[gitlab-flow]: ../workflow/
[gitlab runner]:
[git-strategy]: yaml/
[kube]: ../user/project/integrations/
[kube]: ../user/project/clusters/
[prom]: ../user/project/integrations/
......@@ -215,8 +215,8 @@ are set in the build environment. These variables are only defined for
[deployment jobs](../ Please consult the documentation of
the project services that you are using to learn which variables they define.
An example project service that defines deployment variables is
[Kubernetes Service](../../user/project/integrations/
An example project service that defines deployment variables is the
[Kubernetes integration](../../user/project/clusters/
## Debug tracing
last_updated: 2017-12-28
# GitLab Kubernetes / OpenShift integration
CAUTION: **Warning:**
The Kubernetes service integration has been deprecated in GitLab 10.3. If the
service is active, the cluster information will still be editable, however we
advise to disable and reconfigure the clusters using the new
[Clusters](../clusters/ page. If the service is inactive, the fields
will not be editable. Read [GitLab 10.3 release post]( for more information.
GitLab can be configured to interact with Kubernetes, or other systems using the
Kubernetes API (such as OpenShift).
Each project can be configured to connect to a different Kubernetes cluster, see
the [configuration](#configuration) section.
## Configuration
Navigate to the [Integrations page](
of your project and select the **Kubernetes** service to configure it. Fill in
all the needed parameters, check the "Active" checkbox and hit **Save changes**
for the changes to take effect.
![Kubernetes configuration settings](img/kubernetes_configuration.png)
The Kubernetes service takes the following parameters:
- **API URL** -
It's the URL that GitLab uses to access the Kubernetes API. Kubernetes
exposes several APIs, we want the "base" URL that is common to all of them,
e.g., `` rather than ``.
- **CA certificate** (optional) -
If the API is using a self-signed TLS certificate, you'll also need to include
the `ca.crt` contents here.
- **Project namespace** (optional) - The following apply:
- By default you don't have to fill it in; by leaving it blank, GitLab will
create one for you.
- Each project should have a unique namespace.
- The project namespace is not necessarily the namespace of the secret, if
you're using a secret with broader permissions, like the secret from `default`.
- You should **not** use `default` as the project namespace.
- If you or someone created a secret specifically for the project, usually
with limited permissions, the secret's namespace and project namespace may
be the same.
- **Token** -
GitLab authenticates against Kubernetes using service tokens, which are
scoped to a particular `namespace`. If you don't have a service token yet,
you can follow the
[Kubernetes documentation](
to create one. You can also view or create service tokens in the
[Kubernetes dashboard](
(under **Config > Secrets**).
TIP: **Tip:**
If you have a single cluster that you want to use for all your projects,
you can pre-fill the settings page with a default template. To configure the
template, see [Services Templates](
## Deployment variables
The Kubernetes service exposes the following
[deployment variables](../../../ci/variables/ in the
GitLab CI/CD build environment:
- `KUBE_URL` - Equal to the API URL.
- `KUBE_TOKEN` - The Kubernetes token.
- `KUBE_NAMESPACE` - The Kubernetes namespace is auto-generated if not specified.
The default value is `<project_name>-<project_id>`. You can overwrite it to
use different one if needed, otherwise the `KUBE_NAMESPACE` variable will
receive the default value.
- `KUBE_CA_PEM_FILE` - Only present if a custom CA bundle was specified. Path
to a file containing PEM data.
- `KUBE_CA_PEM` (deprecated) - Only if a custom CA bundle was specified. Raw PEM data.
- `KUBECONFIG` - Path to a file containing `kubeconfig` for this deployment.
CA bundle would be embedded if specified.
## What you can get with the Kubernetes integration
Here's what you can do with GitLab if you enable the Kubernetes integration.
### Deploy Boards
> Available in [GitLab Premium][ee].
GitLab's Deploy Boards offer a consolidated view of the current health and
status of each CI [environment](../../../ci/ running on Kubernetes,
displaying the status of the pods in the deployment. Developers and other
teammates can view the progress and status of a rollout, pod by pod, in the
workflow they already use without any need to access Kubernetes.
[> Read more about Deploy Boards](
### Canary Deployments
> Available in [GitLab Premium][ee].
Leverage [Kubernetes' Canary deployments](
and visualize your canary deployments right inside the Deploy Board, without
the need to leave GitLab.
[> Read more about Canary Deployments](
### Kubernetes monitoring
Automatically detect and monitor Kubernetes metrics. Automatic monitoring of
[NGINX ingress](./prometheus_library/ is also supported.
[> Read more about Kubernetes monitoring](prometheus_library/
### Auto DevOps
Auto DevOps automatically detects, builds, tests, deploys, and monitors your
To make full use of Auto DevOps(Auto Deploy, Auto Review Apps, and Auto Monitoring)
you will need the Kubernetes project integration enabled.
[> Read more about Auto DevOps](../../../topics/autodevops/
### Web terminals
NOTE: **Note:**
Introduced in GitLab 8.15. You must be the project owner or have `master` permissions
to use terminals. Support is limited to the first container in the
first pod of your environment.
When enabled, the Kubernetes service adds [web terminal](../../../ci/
support to your [environments](../../../ci/ This is based on the `exec` functionality found in
Docker and Kubernetes, so you get a new shell session within your existing
containers. To use this integration, you should deploy to Kubernetes using
the deployment variables above, ensuring any pods you create are labelled with
`app=$CI_ENVIRONMENT_SLUG`. GitLab will do the rest!
This document was moved to [another location](../clusters/
......@@ -39,7 +39,6 @@ Click on the service links to see further configuration instructions and details
| [Irker (IRC gateway)]( | Send IRC messages, on update, to a list of recipients through an Irker gateway |
| [JIRA]( | JIRA issue tracker |
| JetBrains TeamCity CI | A continuous integration and build server |
| [Kubernetes]( _(Has been deprecated in GitLab 10.3)_ | A containerized deployment service |
| [Mattermost slash commands]( | Mattermost chat and ChatOps slash commands |
| [Mattermost Notifications]( | Receive event notifications in Mattermost |
| [Microsoft teams]( | Receive notifications for actions that happen on GitLab into a room on Microsoft Teams using Office 365 Connectors |
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