Skip to content

G
gitlab-ce
Commit 40195e26 authored by Craig Norris's avatar Craig Norris
Browse files
Options

Merge branch 'aqualls-notes-applications-page' into 'master' 

Applications page: tidy formatting, strip notes

See merge request gitlab-org/gitlab!44509
parents dae542bb 7d8e28b2
Hide whitespace changes
Inline Side-by-side
Showing with 218 additions and 174 deletions
doc/.vale/gitlab/spelling-exceptions.txt
View file @ 40195e26
......@@ -142,6 +142,7 @@ Facebook
failover
failovers
failsafe
Falco
fastlane
favicon
Filebeat
......@@ -513,6 +514,9 @@ unprioritized
unprotect
unprotected
unprotects
unprovision
unprovisioned
unprovisions
unpublish
unpublished
unpublishes
......
doc/user/clusters/applications.md
View file @ 40195e26
......@@ -47,13 +47,12 @@ namespace called `gitlab-managed-apps`.
Some applications are installable only for a project-level cluster.
Support for installing these applications in a group-level cluster is
planned for future releases.
For updates, see [the issue tracking
progress](https://gitlab.com/gitlab-org/gitlab/-/issues/24411).
For updates, see the [issue tracking progress](https://gitlab.com/gitlab-org/gitlab/-/issues/24411).
CAUTION: **Caution:**
If you have an existing Kubernetes cluster with Helm already installed,
you should be careful as GitLab cannot detect it. In this case, installing
Helm via the applications will result in the cluster having it twice, which
Helm with the applications results in the cluster having it twice, which
can lead to confusion during deployments.
In GitLab versions 11.6 and greater, Helm is upgraded to the latest version
......@@ -120,7 +119,7 @@ needs. If a project-specific runner is desired, or there are no shared runners,
you can deploy one.
The deployed runner is set as **privileged**. Root access to the underlying
server is required to build Docker images, so it is the default. Be sure to read
server is required to build Docker images, so it's the default. Be sure to read
the [security implications](../project/clusters/index.md#security-implications)
before deploying one.
......@@ -175,18 +174,17 @@ If the endpoint doesn't appear and your cluster runs on Google Kubernetes Engine
1. Review [Google Cloud's Status](https://status.cloud.google.com/) for service
disruptions.
The [`stable/nginx-ingress`](https://github.com/helm/charts/tree/master/stable/nginx-ingress)
chart is used to install this application with a
[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/ingress/values.yaml)
file.
After installing, you may see a `?` for **Ingress IP Address** depending on the
cloud provider. For EKS specifically, this is because the ELB is created
with a DNS name, not an IP address. If GitLab is still unable to
determine the endpoint of your Ingress or Knative application, you can
[determine it manually](#determining-the-external-endpoint-manually).
NOTE: **Note:**
The [`stable/nginx-ingress`](https://github.com/helm/charts/tree/master/stable/nginx-ingress)
chart is used to install this application with a
[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/ingress/values.yaml)
file.
#### Determining the external endpoint manually
If the cluster is on GKE, click the **Google Kubernetes Engine** link in the
......@@ -197,7 +195,7 @@ the `gcloud` command in a local terminal or using the **Cloud Shell**.
If the cluster is not on GKE, follow the specific instructions for your
Kubernetes provider to configure `kubectl` with the right credentials.
The output of the following examples will show the external endpoint of your
The output of the following examples show the external endpoint of your
cluster. This information can then be used to set up DNS entries and forwarding
rules that allow external access to your deployed applications.
......@@ -218,7 +216,7 @@ rules that allow external access to your deployed applications.
If EKS is used, an [Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/)
is also created, which will incur additional AWS costs.
- For Istio/Knative, the command will be different:
- For Istio/Knative, the command is different:
```shell
kubectl get svc --namespace=istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} '
......@@ -291,7 +289,7 @@ There is a small performance overhead by enabling ModSecurity. If this is
considered significant for your application, you can disable ModSecurity's
rule engine for your deployed application in any of the following ways:
1. Set [the deployment variable](../../topics/autodevops/index.md)
1. Set the [deployment variable](../../topics/autodevops/index.md)
`AUTO_DEVOPS_MODSECURITY_SEC_RULE_ENGINE` to `Off` to prevent ModSecurity
from processing any requests for the given application or environment.
1. Switch its respective toggle to the disabled position, and then apply changes
......@@ -341,7 +339,7 @@ You can view Web Application Firewall traffic by navigating to your project's
tracked over time:
- The total amount of traffic to your application.
- The proportion of traffic that is considered anomalous by the Web Application
- The proportion of traffic that's considered anomalous by the Web Application
Firewall's default [OWASP ruleset](https://www.modsecurity.org/CRS/Documentation/).
If a significant percentage of traffic is anomalous, investigate it for potential threats
......@@ -369,8 +367,9 @@ for project-level clusters and group members for group-level clusters with
[Developer or higher](../permissions.md) access to the associated project or group.
GitLab uses a [custom Jupyter image](https://gitlab.com/gitlab-org/jupyterhub-user-image/blob/master/Dockerfile)
that installs additional useful packages on top of the base Jupyter. You
will also see ready-to-use DevOps Runbooks built with Nurtch's [Rubix library](https://github.com/Nurtch/rubix).
that installs additional useful packages on top of the base Jupyter. Ready-to-use
DevOps Runbooks built with Nurtch's [Rubix library](https://github.com/Nurtch/rubix)
are also available.
More information on creating executable runbooks can be found in
[our Runbooks documentation](../project/clusters/runbooks/index.md#configure-an-executable-runbook-with-gitlab).
......@@ -413,7 +412,7 @@ You can clone repositories from the files tab in Jupyter:
[Knative](https://cloud.google.com/knative/) provides a platform to
create, deploy, and manage serverless workloads from a Kubernetes
cluster. It is used in conjunction with, and includes
cluster. It's used in conjunction with, and includes
[Istio](https://istio.io) to provide an external IP address for all
programs hosted by Knative.
......@@ -436,10 +435,10 @@ your Kubernetes cluster to have
open-source monitoring and alerting system useful to supervise your
deployed applications.
GitLab is able to monitor applications automatically, using the
GitLab is able to monitor applications by using the
[Prometheus integration](../project/integrations/prometheus.md). Kubernetes container CPU and
memory metrics are automatically collected, and response metrics are retrieved
from NGINX Ingress as well.
memory metrics are collected, and response metrics are also retrieved
from NGINX Ingress.
The [`stable/prometheus`](https://github.com/helm/charts/tree/master/stable/prometheus)
chart is used to install this application with a
......@@ -470,7 +469,7 @@ The Crossplane GitLab-managed application:
project repository.
- Can then be used to provision infrastructure or managed applications such as
PostgreSQL (for example, CloudSQL from GCP or RDS from AWS) and other services
required by the application via the Auto DevOps pipeline.
required by the application with the Auto DevOps pipeline.
[`alpha/crossplane`](https://github.com/crossplane/crossplane/tree/v0.4.1/cluster/charts/crossplane) chart v0.4.1 is used to
install Crossplane using the
......@@ -494,6 +493,10 @@ querying. GitLab then connects to Elasticsearch for logs, instead of the
Kubernetes API, giving you access to more advanced querying capabilities. Log
data is deleted after 30 days, using [Curator](https://www.elastic.co/guide/en/elasticsearch/client/curator/5.5/about.html).
The Elastic Stack cluster application is intended as a log aggregation solution
and is not related to our [Advanced Search](../search/advanced_global_search.md)
functionality, which uses a separate Elasticsearch cluster.
To enable log shipping:
1. Ensure your cluster contains at least three nodes of instance types larger
......@@ -511,11 +514,6 @@ colocated, and each requires one CPU and 2 GB of RAM, making them
incompatible with clusters containing fewer than three nodes, or consisting of
`f1-micro`, `g1-small`, `n1-standard-1`, or `*-highcpu-2` instance types.
NOTE: **Note:**
The Elastic Stack cluster application is intended as a log aggregation solution
and is not related to our [Advanced Search](../search/advanced_global_search.md)
functionality, which uses a separate Elasticsearch cluster.
#### Optional: deploy Kibana to perform advanced queries
If you are an advanced user and have direct access to your Kubernetes cluster using `kubectl` and `helm`, you can deploy Kibana manually.
......@@ -562,8 +560,8 @@ your data. Fluentd sends logs in syslog format.
To enable Fluentd:
1. Navigate to **Operations > Kubernetes** and click
**Applications**. You will be prompted to enter a host, port and protocol
where the WAF logs will be sent to via syslog.
**Applications**. Enter a host, port, and protocol
for sending the WAF logs with syslog.
1. Provide the host domain name or URL in **SIEM Hostname**.
1. Provide the host port number in **SIEM Port**.
1. Select a **SIEM Protocol**.
......@@ -583,7 +581,7 @@ to get started.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20822) in GitLab 12.6.
CAUTION: **Warning:**
This is an _alpha_ feature, and it is subject to change at any time without
This is an _alpha_ feature, and is subject to change at any time without
prior notice.
This alternative method allows users to install GitLab-managed
......@@ -623,7 +621,6 @@ To install applications using GitLab CI/CD:
- template: Managed-Cluster-Applications.gitlab-ci.yml
```
NOTE: **Note:**
The job provided by this template connects to the cluster using tools provided
in a custom Docker image. It requires that you have a runner registered with the Docker,
Kubernetes, or Docker Machine executor.
......@@ -641,11 +638,10 @@ To install applications using GitLab CI/CD:
1. Optionally, define `.gitlab/managed-apps/<application>/values.yaml` file to
customize values for the installed application.
A GitLab CI/CD pipeline will then run on the `master` branch to install the
A GitLab CI/CD pipeline runs on the `master` branch to install the
applications you have configured. In case of pipeline failure, the
output of the [Helm
Tiller](https://v2.helm.sh/docs/install/#running-tiller-locally) binary
will be saved as a [CI job artifact](../../ci/pipelines/job_artifacts.md).
output of the [Helm Tiller](https://v2.helm.sh/docs/install/#running-tiller-locally) binary
is saved as a [CI job artifact](../../ci/pipelines/job_artifacts.md).
### Important notes
......@@ -653,10 +649,10 @@ Note the following:
- We recommend using the cluster management project exclusively for managing deployments to a cluster.
Do not add your application's source code to such projects.
- When you set the value for `installed` key back to `false`, the application will be
- When you set the value for `installed` key back to `false`, the application is
unprovisioned from the cluster.
- If you update `.gitlab/managed-apps/<application>/values.yaml` with new values, the
application will be redeployed.
application is redeployed.
### Install Ingress using GitLab CI/CD
......@@ -668,7 +664,7 @@ ingress:
installed: true
```
Ingress will then be installed into the `gitlab-managed-apps` namespace
Ingress is installed into the `gitlab-managed-apps` namespace
of your cluster.
You can customize the installation of Ingress by defining a
......@@ -677,9 +673,10 @@ management project. Refer to the
[chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress)
for the available configuration options.
NOTE: **Note:**
Support for installing the Ingress managed application is provided by the GitLab Configure group.
If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group).
If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new),
and ping at least 2 people from the
[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group).
### Install cert-manager using GitLab CI/CD
......@@ -689,7 +686,8 @@ cert-manager is installed using GitLab CI/CD by defining configuration in
cert-manager:
- Is installed into the `gitlab-managed-apps` namespace of your cluster.
- Can be installed with or without a default [Let's Encrypt `ClusterIssuer`](https://cert-manager.io/docs/configuration/acme/), which requires an
- Can be installed with or without a default
[Let's Encrypt `ClusterIssuer`](https://cert-manager.io/docs/configuration/acme/), which requires an
email address to be specified. The email address is used by Let's Encrypt to
contact you about expiring certificates and issues related to your account.
......@@ -718,9 +716,11 @@ management project. Refer to the
[chart](https://hub.helm.sh/charts/jetstack/cert-manager) for the
available configuration options.
NOTE: **Note:**
Support for installing the Cert Manager managed application is provided by the GitLab Configure group.
If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group).
Support for installing the Cert Manager managed application is provided by the
GitLab Configure group. If you run into unknown issues,
[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at
least 2 people from the
[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group).
### Install Sentry using GitLab CI/CD
......@@ -735,7 +735,7 @@ sentry:
installed: true
```
Sentry will then be installed into the `gitlab-managed-apps` namespace
Sentry is installed into the `gitlab-managed-apps` namespace
of your cluster.
You can customize the installation of Sentry by defining
......@@ -750,8 +750,10 @@ We recommend you pay close attention to the following configuration options:
- `user`. Where you can set the login credentials for the default admin user.
- `postgresql`. For a PostgreSQL password that can be used when running future updates.
NOTE: **Note:**
When upgrading it is important to provide the existing PostgreSQL password (given using the `postgresql.postgresqlPassword` key) or you will receive authentication errors. See the [PostgreSQL chart documentation](https://github.com/helm/charts/tree/master/stable/postgresql#upgrade) for more information.
When upgrading, it's important to provide the existing PostgreSQL password (given
using the `postgresql.postgresqlPassword` key) to avoid authentication errors.
Read the [PostgreSQL chart documentation](https://github.com/helm/charts/tree/master/stable/postgresql#upgrade)
for more information.
Here is an example configuration for Sentry:
......@@ -783,9 +785,11 @@ postgresql:
postgresqlPassword: example-postgresql-password
```
NOTE: **Note:**
Support for installing the Sentry managed application is provided by the GitLab Health group.
If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Health group](https://about.gitlab.com/handbook/product/product-categories/#health-group).
Support for installing the Sentry managed application is provided by the
GitLab Health group. If you run into unknown issues,
[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at
least 2 people from the
[Health group](https://about.gitlab.com/handbook/product/product-categories/#health-group).
### Install PostHog using GitLab CI/CD
......@@ -800,13 +804,14 @@ posthog:
```
You can customize the installation of PostHog by defining `.gitlab/managed-apps/posthog/values.yaml`
in your cluster management project. Refer to the [Configuration section of the PostHog chart's README](https://github.com/PostHog/charts/tree/master/charts/posthog)
in your cluster management project. Refer to the
[Configuration section of the PostHog chart's README](https://github.com/PostHog/charts/tree/master/charts/posthog)
for the available configuration options.
NOTE: **Note:**
You must provide a PostgreSQL password in `postgresql.postgresqlPassword`
or you will receive authentication errors.
See the [PostgreSQL chart documentation](https://github.com/helm/charts/tree/master/stable/postgresql#upgrade) for more information.
to avoid authentication errors. Read the
[PostgreSQL chart documentation](https://github.com/helm/charts/tree/master/stable/postgresql#upgrade)
for more information.
Redis pods are restarted between upgrades. To prevent downtime, provide a Redis
password using the `redis.password` key. This prevents a new password from
......@@ -832,9 +837,9 @@ redis:
password: example-redis-password
```
NOTE: **Note:**
Support for the PostHog managed application is provided by the PostHog team.
If you run into issues, please [open a support ticket](https://github.com/PostHog/posthog/issues/new/choose) directly.
If you run into issues,
[open a support ticket](https://github.com/PostHog/posthog/issues/new/choose) directly.
### Install Prometheus using GitLab CI/CD
......@@ -858,9 +863,10 @@ project. Refer to the
[Configuration section of the Prometheus chart's README](https://github.com/helm/charts/tree/master/stable/prometheus#configuration)
for the available configuration options.
NOTE: **Note:**
Support for installing the Prometheus managed application is provided by the GitLab APM group.
If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [APM group](https://about.gitlab.com/handbook/product/product-categories/#apm-group).
Support for installing the Prometheus managed application is provided by the
GitLab APM group. If you run into unknown issues,
[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at
least 2 people from the [APM group](https://about.gitlab.com/handbook/product/product-categories/#apm-group).
### Install GitLab Runner using GitLab CI/CD
......@@ -876,16 +882,17 @@ gitlabRunner:
GitLab Runner is installed into the `gitlab-managed-apps` namespace of your cluster.
In order for GitLab Runner to function, you **must** specify the following:
For GitLab Runner to function, you _must_ specify the following:
- `gitlabUrl` - the GitLab server full URL (for example, `https://gitlab.example.com`) to register the Runner against.
- `runnerRegistrationToken` - The registration token for adding new runners to GitLab. This must be
[retrieved from your GitLab instance](../../ci/runners/README.md).
- `gitlabUrl`: The GitLab server full URL (for example, `https://gitlab.example.com`)
to register the Runner against.
- `runnerRegistrationToken`: The registration token for adding new runners to GitLab.
This must be [retrieved from your GitLab instance](../../ci/runners/README.md).
These values can be specified using [CI variables](../../ci/variables/README.md):
- `GITLAB_RUNNER_GITLAB_URL` will be used for `gitlabUrl`.
- `GITLAB_RUNNER_REGISTRATION_TOKEN` will be used for `runnerRegistrationToken`
- `GITLAB_RUNNER_GITLAB_URL` is used for `gitlabUrl`.
- `GITLAB_RUNNER_REGISTRATION_TOKEN` is used for `runnerRegistrationToken`
You can customize the installation of GitLab Runner by defining
`.gitlab/managed-apps/gitlab-runner/values.yaml` file in your cluster
......@@ -893,9 +900,11 @@ management project. Refer to the
[chart](https://gitlab.com/gitlab-org/charts/gitlab-runner) for the
available configuration options.
NOTE: **Note:**
Support for installing the GitLab Runner managed application is provided by the GitLab Runner group.
If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Runner group](https://about.gitlab.com/handbook/product/product-categories/#runner-group).
Support for installing the GitLab Runner managed application is provided by the
GitLab Runner group. If you run into unknown issues,
[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at
least 2 people from the
[Runner group](https://about.gitlab.com/handbook/product/product-categories/#runner-group).
### Install Cilium using GitLab CI/CD
......@@ -932,8 +941,10 @@ for the available configuration options.
You can check Cilium's installation status on the cluster management page:
- [Project-level cluster](../project/clusters/index.md): Navigate to your project's **Operations > Kubernetes** page.
- [Group-level cluster](../group/clusters/index.md): Navigate to your group's **Kubernetes** page.
- [Project-level cluster](../project/clusters/index.md): Navigate to your project's
**Operations > Kubernetes** page.
- [Group-level cluster](../group/clusters/index.md): Navigate to your group's
**Kubernetes** page.
CAUTION: **Caution:**
Installation and removal of the Cilium requires a **manual**
......@@ -943,12 +954,11 @@ of all affected pods in all namespaces to ensure that they are
by the correct networking plugin.
NOTE: **Note:**
Major upgrades might require additional setup steps, please consult
the official [upgrade guide](https://docs.cilium.io/en/stable/install/upgrade/) for more
information.
Major upgrades might require additional setup steps. For more information, see
the official [upgrade guide](https://docs.cilium.io/en/stable/install/upgrade/).
By default, Cilium's [audit
mode](https://docs.cilium.io/en/v1.8/gettingstarted/policy-creation/?highlight=policy-audit#enable-policy-audit-mode)
By default, Cilium's
[audit mode](https://docs.cilium.io/en/v1.8/gettingstarted/policy-creation/?highlight=policy-audit#enable-policy-audit-mode)
is enabled. In audit mode, Cilium doesn't drop disallowed packets. You
can use `policy-verdict` log to observe policy-related decisions. You
can disable audit mode by adding the following to
......@@ -990,7 +1000,7 @@ global:
enabled: false
```
You can also adjust Helm values for Hubble via
You can also adjust Helm values for Hubble by using
`.gitlab/managed-apps/cilium/values.yaml`:
```yaml
......@@ -1002,9 +1012,11 @@ global:
- 'flow:sourceContext=namespace;destinationContext=namespace'
```
NOTE: **Note:**
Support for installing the Cilium managed application is provided by the GitLab Container Security group.
If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group).
Support for installing the Cilium managed application is provided by the
GitLab Container Security group. If you run into unknown issues,
[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at
least 2 people from the
[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group).
### Install Falco using GitLab CI/CD
......@@ -1030,17 +1042,20 @@ management project. Refer to the
for the available configuration options.
CAUTION: **Caution:**
By default eBPF support is enabled and Falco will use an [eBPF probe](https://falco.org/docs/event-sources/drivers/#using-the-ebpf-probe) to pass system calls to userspace.
If your cluster doesn't support this, you can configure it to use Falco kernel module instead by adding the following to `.gitlab/managed-apps/falco/values.yaml`:
By default eBPF support is enabled and Falco uses an
[eBPF probe](https://falco.org/docs/event-sources/drivers/#using-the-ebpf-probe)
to pass system calls to user space. If your cluster doesn't support this, you can
configure it to use Falco kernel module instead by adding the following to
`.gitlab/managed-apps/falco/values.yaml`:
```yaml
ebpf:
enabled: false
```
In rare cases where automatic probe installation on your cluster isn't possible and the kernel/probe
isn't precompiled, you may need to manually prepare the kernel module or eBPF probe with
[driverkit](https://github.com/falcosecurity/driverkit#against-a-kubernetes-cluster)
In rare cases where probe installation on your cluster isn't possible and the kernel/probe
isn't pre-compiled, you may need to manually prepare the kernel module or eBPF probe with
[`driverkit`](https://github.com/falcosecurity/driverkit#against-a-kubernetes-cluster)
and install it on each cluster node.
By default, Falco is deployed with a limited set of rules. To add more rules, add the following to
......@@ -1093,16 +1108,18 @@ You can check these logs with the following command:
kubectl -n gitlab-managed-apps logs -l app=falco
```
NOTE: **Note:**
Support for installing the Falco managed application is provided by the GitLab Container Security group.
If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group).
Support for installing the Falco managed application is provided by the
GitLab Container Security group. If you run into unknown issues,
[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at
least 2 people from the
[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group).
### Install Vault using GitLab CI/CD
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9982) in GitLab 12.9.
[Hashicorp Vault](https://www.vaultproject.io/) is a secrets management solution which
can be used to safely manage and store passwords, credentials, certificates and more. A Vault
[HashiCorp Vault](https://www.vaultproject.io/) is a secrets management solution which
can be used to safely manage and store passwords, credentials, certificates, and more. A Vault
installation could be leveraged to provide a single secure data store for credentials
used in your applications, GitLab CI/CD jobs, and more. It could also serve as a way of
providing SSL/TLS certificates to systems and deployments in your infrastructure. Leveraging
......@@ -1120,24 +1137,25 @@ vault:
installed: true
```
By default you will get a basic Vault setup with no scalable
storage backend. This is enough for simple testing and small-scale deployments, though has limits
to how much it can scale, and as it is a single instance deployment, you will experience downtime
when upgrading the Vault application.
By default you receive a basic Vault setup with no scalable storage backend. This
is enough for simple testing and small-scale deployments, though has limits
to how much it can scale, and as it's a single instance deployment, upgrading the
Vault application causes downtime.
To optimally use Vault in a production environment, it's ideal to have a good understanding
of the internals of Vault and how to configure it. This can be done by reading the [Vault Configuration guide](../../ci/secrets/#configure-your-vault-server),
[the Vault documentation](https://www.vaultproject.io/docs/internals) as well as
of the internals of Vault and how to configure it. This can be done by reading
the [Vault Configuration guide](../../ci/secrets/#configure-your-vault-server),
the [Vault documentation](https://www.vaultproject.io/docs/internals) and
the Vault Helm chart [`values.yaml` file](https://github.com/hashicorp/vault-helm/blob/v0.3.3/values.yaml).
At a minimum you will likely set up:
At a minimum, most users set up:
- A [seal](https://www.vaultproject.io/docs/configuration/seal) for extra encryption
of the master key.
- A [storage backend](https://www.vaultproject.io/docs/configuration/storage) that is
of the main key.
- A [storage backend](https://www.vaultproject.io/docs/configuration/storage) that's
suitable for environment and storage security requirements.
- [HA Mode](https://www.vaultproject.io/docs/concepts/ha).
- [The Vault UI](https://www.vaultproject.io/docs/configuration/ui).
- The [Vault UI](https://www.vaultproject.io/docs/configuration/ui).
The following is an example values file (`.gitlab/managed-apps/vault/values.yaml`)
that configures Google Key Management Service for auto-unseal, using a Google Cloud Storage backend, enabling
......@@ -1167,7 +1185,7 @@ server:
path = "gcs://my-vault-storage/vault-bucket"
ha_enabled = "true"
}
# Configure Vault to automatically unseal storage using a GKMS key
# Configure Vault to unseal storage using a GKMS key
seal "gcpckms" {
project = "vault-helm-dev-246514"
region = "global"
......@@ -1176,10 +1194,13 @@ server:
}
```
Once you have successfully installed Vault, you will need to [initialize the Vault](https://learn.hashicorp.com/tutorials/vault/getting-started-deploy#initializing-the-vault)
and obtain the initial root token. You will need access to your Kubernetes cluster that Vault has been deployed into in order to do this.
To initialize the Vault, get a shell to one of the Vault pods running inside Kubernetes (typically this is done by using the `kubectl` command line tool).
Once you have a shell into the pod, run the `vault operator init` command:
Once you have successfully installed Vault, you must
[initialize the Vault](https://learn.hashicorp.com/tutorials/vault/getting-started-deploy#initializing-the-vault)
and obtain the initial root token. You need access to your Kubernetes cluster that
Vault has been deployed into in order to do this. To initialize the Vault, get a
shell to one of the Vault pods running inside Kubernetes (typically this is done
by using the `kubectl` command line tool). Once you have a shell into the pod,
run the `vault operator init` command:
```shell
kubectl -n gitlab-managed-apps exec -it vault-0 sh
......@@ -1187,11 +1208,13 @@ kubectl -n gitlab-managed-apps exec -it vault-0 sh
```
This should give you your unseal keys and initial root token. Make sure to note these down
and keep these safe as you will need them to unseal the Vault throughout its lifecycle.
and keep these safe, as they're required to unseal the Vault throughout its lifecycle.
NOTE: **Note:**
Support for installing the Vault managed application is provided by the GitLab Release Management group.
If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Release Management group](https://about.gitlab.com/handbook/product/product-categories/#release-management-group).
Support for installing the Vault managed application is provided by the
GitLab Release Management group. If you run into unknown issues,
[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at
least 2 people from the
[Release Management group](https://about.gitlab.com/handbook/product/product-categories/#release-management-group).
### Install JupyterHub using GitLab CI/CD
......@@ -1211,7 +1234,7 @@ In the configuration:
- `gitlabProjectIdWhitelist` restricts GitLab authentication to only members of the specified projects.
- `gitlabGroupWhitelist` restricts GitLab authentication to only members of the specified groups.
- Specifying an empty array for both will allow any user on the GitLab instance to sign in.
- Specifying an empty array for both allows any user on the GitLab instance to sign in.
JupyterHub is installed into the `gitlab-managed-apps` namespace of your cluster.
......@@ -1223,17 +1246,19 @@ Set:
In addition, the following variables must be specified using [CI variables](../../ci/variables/README.md):
| CI Variable | Description |
|:---------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `JUPYTERHUB_PROXY_SECRET_TOKEN` | Secure string used for signing communications from the hub. See[`proxy.secretToken`](https://zero-to-jupyterhub.readthedocs.io/en/stable/reference/reference.html#proxy-secrettoken). |
| `JUPYTERHUB_COOKIE_SECRET` | Secure string used for signing secure cookies. See [`hub.cookieSecret`](https://zero-to-jupyterhub.readthedocs.io/en/stable/reference/reference.html#hub-cookiesecret). |
| `JUPYTERHUB_HOST` | Hostname used for the installation. For example, `jupyter.gitlab.example.com`. |
| `JUPYTERHUB_GITLAB_HOST` | Hostname of the GitLab instance used for authentication. For example, `gitlab.example.com`. |
| `JUPYTERHUB_AUTH_CRYPTO_KEY` | A 32-byte encryption key used to set [`auth.state.cryptoKey`](https://zero-to-jupyterhub.readthedocs.io/en/stable/reference/reference.html#auth-state-cryptokey). |
| `JUPYTERHUB_AUTH_GITLAB_CLIENT_ID` | "Application ID" for the OAuth Application. |
| `JUPYTERHUB_AUTH_GITLAB_CLIENT_SECRET` | "Secret" for the OAuth Application. |
By default, JupyterHub will be installed using a
- `JUPYTERHUB_PROXY_SECRET_TOKEN` - Secure string used for signing communications
from the hub. Read [`proxy.secretToken`](https://zero-to-jupyterhub.readthedocs.io/en/stable/reference/reference.html#proxy-secrettoken).
- `JUPYTERHUB_COOKIE_SECRET` - Secure string used for signing secure cookies. Read
[`hub.cookieSecret`](https://zero-to-jupyterhub.readthedocs.io/en/stable/reference/reference.html#hub-cookiesecret).
- `JUPYTERHUB_HOST` - Hostname used for the installation. For example, `jupyter.gitlab.example.com`.
- `JUPYTERHUB_GITLAB_HOST` - Hostname of the GitLab instance used for authentication.
For example, `gitlab.example.com`.
- `JUPYTERHUB_AUTH_CRYPTO_KEY` - A 32-byte encryption key used to set
[`auth.state.cryptoKey`](https://zero-to-jupyterhub.readthedocs.io/en/stable/reference/reference.html#auth-state-cryptokey).
- `JUPYTERHUB_AUTH_GITLAB_CLIENT_ID` - "Application ID" for the OAuth Application.
- `JUPYTERHUB_AUTH_GITLAB_CLIENT_SECRET` - "Secret" for the OAuth Application.
By default, JupyterHub is installed using a
[default values file](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications/-/blob/master/src/default-data/jupyterhub/values.yaml.gotmpl).
You can customize the installation of JupyterHub by defining a
`.gitlab/managed-apps/jupyterhub/values.yaml` file in your cluster management project.
......@@ -1242,9 +1267,11 @@ Refer to the
[chart reference](https://zero-to-jupyterhub.readthedocs.io/en/stable/reference/reference.html) for the
available configuration options.
NOTE: **Note:**
Support for installing the JupyterHub managed application is provided by the GitLab Configure group.
If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group).
If you run into unknown issues,
[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at
least 2 people from the
[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group).
### Install Elastic Stack using GitLab CI/CD
......@@ -1262,7 +1289,9 @@ elasticStack:
Elastic Stack is installed into the `gitlab-managed-apps` namespace of your cluster.
You can check the default [`values.yaml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/vendor/elastic_stack/values.yaml) we set for this chart.
You can check the default
[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/vendor/elastic_stack/values.yaml)
we set for this chart.
You can customize the installation of Elastic Stack by defining
`.gitlab/managed-apps/elastic-stack/values.yaml` file in your cluster
......@@ -1271,11 +1300,14 @@ management project. Refer to the
available configuration options.
NOTE: **Note:**
In this alpha implementation of installing Elastic Stack through CI, reading the environment logs through Elasticsearch is unsupported. This is supported if [installed via the UI](#elastic-stack).
In this alpha implementation of installing Elastic Stack through CI, reading the
environment logs through Elasticsearch is unsupported. This is supported if
[installed with the UI](#elastic-stack).
NOTE: **Note:**
Support for installing the Elastic Stack managed application is provided by the GitLab APM group.
If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [APM group](https://about.gitlab.com/handbook/product/product-categories/#apm-group).
Support for installing the Elastic Stack managed application is provided by the
GitLab APM group. If you run into unknown issues,
[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at
least 2 people from the [APM group](https://about.gitlab.com/handbook/product/product-categories/#apm-group).
### Install Crossplane using GitLab CI/CD
......@@ -1303,22 +1335,24 @@ management project. Refer to the
[chart](https://github.com/crossplane/crossplane/tree/master/cluster/charts/crossplane#configuration) for the
available configuration options. Note that this link points to the documentation for the current development release, which may differ from the version you have installed.
NOTE: **Note:**
Support for the Crossplane managed application is provided by the Crossplane team.
If you run into issues, please [open a support ticket](https://github.com/crossplane/crossplane/issues/new/choose) directly.
If you run into issues,
[open a support ticket](https://github.com/crossplane/crossplane/issues/new/choose) directly.
### Install Fluentd using GitLab CI/CD
> [Introduced](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications/-/merge_requests/76) in GitLab 12.10.
To install Fluentd into the `gitlab-managed-apps` namespace of your cluster using GitLab CI/CD, define the following configuration in `.gitlab/managed-apps/config.yaml`:
To install Fluentd into the `gitlab-managed-apps` namespace of your cluster using
GitLab CI/CD, define the following configuration in `.gitlab/managed-apps/config.yaml`:
```yaml
Fluentd:
installed: true
```
You can also review the default values set for this chart in the [`values.yaml`](https://github.com/helm/charts/blob/master/stable/fluentd/values.yaml) file.
You can also review the default values set for this chart in the
[`values.yaml`](https://github.com/helm/charts/blob/master/stable/fluentd/values.yaml) file.
You can customize the installation of Fluentd by defining
`.gitlab/managed-apps/fluentd/values.yaml` file in your cluster management
......@@ -1326,14 +1360,15 @@ project. Refer to the
[configuration chart for the current development release of Fluentd](https://github.com/helm/charts/tree/master/stable/fluentd#configuration)
for all available configuration options.
NOTE: **Note:**
The configuration chart link points to the current development release, which
may differ from the version you have installed. To ensure compatibility, switch
to the specific branch or tag you are using.
NOTE: **Note:**
Support for installing the Fluentd managed application is provided by the GitLab Container Security group.
If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group).
Support for installing the Fluentd managed application is provided by the
GitLab Container Security group. If you run into unknown issues,
[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at
least 2 people from the
[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group).
### Install Knative using GitLab CI/CD
......@@ -1355,11 +1390,14 @@ Here is an example configuration for Knative:
domain: 'my.wildcard.A.record.dns'
```
If you plan to use GitLab Serverless capabilities, be sure to set an A record wildcard domain on your custom configuration.
If you plan to use GitLab Serverless capabilities, be sure to set an `A record`
wildcard domain on your custom configuration.
NOTE: **Note:**
Support for installing the Knative managed application is provided by the GitLab Configure group.
If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group).
Support for installing the Knative managed application is provided by the
GitLab Configure group. If you run into unknown issues,
[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at
least 2 people from the
[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group).
#### Knative Metrics
......@@ -1385,14 +1423,16 @@ kubectl delete -f https://gitlab.com/gitlab-org/cluster-integration/cluster-appl
> [Introduced](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications/-/merge_requests/100) in GitLab 13.1.
To install AppArmor into the `gitlab-managed-apps` namespace of your cluster using GitLab CI/CD, define the following configuration in `.gitlab/managed-apps/config.yaml`:
To install AppArmor into the `gitlab-managed-apps` namespace of your cluster using
GitLab CI/CD, define the following configuration in `.gitlab/managed-apps/config.yaml`:
```yaml
apparmor:
installed: true
```
You can define one or more AppArmor profiles by adding them into `.gitlab/managed-apps/apparmor/values.yaml` as the following:
You can define one or more AppArmor profiles by adding them into
`.gitlab/managed-apps/apparmor/values.yaml` as the following:
```yaml
profiles:
......@@ -1406,25 +1446,27 @@ Refer to the [AppArmor chart](https://gitlab.com/gitlab-org/charts/apparmor) for
#### Using AppArmor profiles in your deployments
After installing AppAmor, you can use profiles by adding Pod Annotations. If you're using Auto
DevOps, you can [customize `auto-deploy-values.yaml`](../../topics/autodevops/customize.md#customize-values-for-helm-chart)
to annotate your pods. Although it's helpful to be aware of the [list of custom attributes](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app#gitlabs-auto-deploy-helm-chart), you're only required to set
`podAnnotations` as follows:
After installing AppAmor, you can use profiles by adding Pod Annotations. If you're using
Auto DevOps, you can [customize `auto-deploy-values.yaml`](../../topics/autodevops/customize.md#customize-values-for-helm-chart)
to annotate your pods. Although it's helpful to be aware of the
[list of custom attributes](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app#gitlabs-auto-deploy-helm-chart),
you're only required to set `podAnnotations` as follows:
```yaml
podAnnotations:
container.apparmor.security.beta.kubernetes.io/auto-deploy-app: localhost/profile-one
```
The only information to be changed here is the profile name which is `profile-one` in this example. Refer to the [AppArmor tutorial](https://kubernetes.io/docs/tutorials/clusters/apparmor/#securing-a-pod) for more information on how AppArmor is integrated in Kubernetes.
The only information to be changed here is the profile name which is `profile-one`
in this example. Refer to the [AppArmor tutorial](https://kubernetes.io/docs/tutorials/clusters/apparmor/#securing-a-pod)
for more information on how AppArmor is integrated in Kubernetes.
#### Using PodSecurityPolicy in your deployments
NOTE: **Note:**
To enable AppArmor annotations on a Pod Security Policy you must first
load the correspondingAppArmor profile.
load the corresponding AppArmor profile.
[Pod Security Policies](https://kubernetes.io/docs/concepts/policy/pod-security-policy/)are
[Pod Security Policies](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) are
resources at the cluster level that control security-related
properties of deployed pods. You can use such a policy to enable
loaded AppArmor profiles and apply necessary pod restrictions across a
......@@ -1452,14 +1494,14 @@ securityPolicies:
- '*'
```
This example creates a single policy named `example` with the provided
specification, and enables [AppArmor
annotations](https://kubernetes.io/docs/tutorials/clusters/apparmor/#podsecuritypolicy-annotations)on
it.
This example creates a single policy named `example` with the provided specification,
and enables [AppArmor annotations](https://kubernetes.io/docs/tutorials/clusters/apparmor/#podsecuritypolicy-annotations) on it.
NOTE: **Note:**
Support for installing the AppArmor managed application is provided by the GitLab Container Security group.
If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group).
Support for installing the AppArmor managed application is provided by the
GitLab Container Security group. If you run into unknown issues,
[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping
at least 2 people from the
[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group).
## Browse applications logs
......@@ -1487,9 +1529,7 @@ To upgrade an application:
1. Select your cluster.
1. If an upgrade is available, the **Upgrade** button is displayed. Click the button to upgrade.
NOTE: **Note:**
Upgrades will reset values back to the values built into the `runner`
chart plus the values set by
Upgrades reset values back to the values built into the `runner` chart, plus the values set by
[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/runner/values.yaml)
## Uninstalling applications
......@@ -1500,16 +1540,16 @@ The applications below can be uninstalled.
| Application | GitLab version | Notes |
| ----------- | -------------- | ----- |
| cert-manager | 12.2+ | The associated private key will be deleted and cannot be restored. Deployed applications will continue to use HTTPS, but certificates will not be renewed. Before uninstalling, you may wish to [back up your configuration](https://cert-manager.io/docs/tutorials/backup/) or [revoke your certificates](https://letsencrypt.org/docs/revoking/). |
| GitLab Runner | 12.2+ | Any running pipelines will be canceled. |
| Helm | 12.2+ | The associated Tiller pod, the `gitlab-managed-apps` namespace, and all of its resources will be deleted and cannot be restored. |
| Ingress | 12.1+ | The associated load balancer and IP will be deleted and cannot be restored. Furthermore, it can only be uninstalled if JupyterHub is not installed. |
| JupyterHub | 12.1+ | All data not committed to GitLab will be deleted and cannot be restored. |
| Knative | 12.1+ | The associated IP will be deleted and cannot be restored. |
| Prometheus | 11.11+ | All data will be deleted and cannot be restored. |
| Crossplane | 12.5+ | All data will be deleted and cannot be restored. |
| Elastic Stack | 12.7+ | All data will be deleted and cannot be restored. |
| Sentry | 12.6+ | The PostgreSQL persistent volume will remain and should be manually removed for complete uninstall. |
| cert-manager | 12.2+ | The associated private key is deleted and cannot be restored. Deployed applications continue to use HTTPS, but certificates aren't renewed. Before uninstalling, you may want to [back up your configuration](https://cert-manager.io/docs/tutorials/backup/) or [revoke your certificates](https://letsencrypt.org/docs/revoking/). |
| GitLab Runner | 12.2+ | Any running pipelines are canceled. |
| Helm | 12.2+ | The associated Tiller pod, the `gitlab-managed-apps` namespace, and all of its resources are deleted and cannot be restored. |
| Ingress | 12.1+ | The associated load balancer and IP are deleted and cannot be restored. Furthermore, it can only be uninstalled if JupyterHub is not installed. |
| JupyterHub | 12.1+ | All data not committed to GitLab are deleted and cannot be restored. |
| Knative | 12.1+ | The associated IP are deleted and cannot be restored. |
| Prometheus | 11.11+ | All data are deleted and cannot be restored. |
| Crossplane | 12.5+ | All data are deleted and cannot be restored. |
| Elastic Stack | 12.7+ | All data are deleted and cannot be restored. |
| Sentry | 12.6+ | The PostgreSQL persistent volume remains and should be manually removed for complete uninstall. |
To uninstall an application:
......@@ -1522,8 +1562,7 @@ To uninstall an application:
1. Click the **Uninstall** button for the application.
Support for uninstalling all applications is planned for progressive rollout.
To follow progress, see [the relevant
epic](https://gitlab.com/groups/gitlab-org/-/epics/1201).
To follow progress, see the [relevant epic](https://gitlab.com/groups/gitlab-org/-/epics/1201).
## Troubleshooting applications
......@@ -1537,9 +1576,10 @@ To avoid installation errors:
- Before starting the installation of applications, make sure that time is synchronized
between your GitLab server and your Kubernetes cluster.
- Ensure certificates are not out of sync. When installing applications, GitLab expects a new cluster with no previous installation of Helm.
- Ensure certificates are not out of sync. When installing applications, GitLab
expects a new cluster with no previous installation of Helm.
You can confirm that the certificates match via `kubectl`:
You can confirm that the certificates match by using `kubectl`:
```shell
kubectl get configmaps/values-content-configuration-ingress -n gitlab-managed-apps -o \
......@@ -1577,5 +1617,5 @@ Installing Prometheus is failing with the following error:
Error: Could not get apiVersions from Kubernetes: unable to retrieve the complete list of server APIs: admission.certmanager.k8s.io/v1beta1: the server is currently unable to handle the request
```
This is a bug that was introduced in Helm `2.15` and fixed in `3.0.2`. As a workaround, you'll need
to make sure that [`cert-manager`](#cert-manager) is installed successfully prior to installing Prometheus.
This is a bug that was introduced in Helm `2.15` and fixed in `3.0.2`. As a workaround,
ensure [`cert-manager`](#cert-manager) is installed successfully prior to installing Prometheus.
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7