diff options
Diffstat (limited to 'doc/user/clusters')
| -rw-r--r-- | doc/user/clusters/agent/index.md | 16 | ||||
| -rw-r--r-- | doc/user/clusters/agent/runner.md | 452 | ||||
| -rw-r--r-- | doc/user/clusters/applications.md | 17 |
3 files changed, 470 insertions, 15 deletions
diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 5963485aebc..2c0d9b6c9ce 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -20,9 +20,10 @@ tasks in a secure and cloud-native way. It enables: (network address translation). - Pull-based GitOps deployments by leveraging the [GitOps Engine](https://github.com/argoproj/gitops-engine). -- Real-time access to API endpoints within a cluster. +- Real-time access to API endpoints in a cluster. -Many more features are planned. Please [review our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329). +Many more features are planned. Please review [our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329) +and [our development documentation](../../../development/agent/index.md). ## GitLab Agent GitOps workflow @@ -169,7 +170,7 @@ gitops: GitLab [versions 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) also supports manifest projects containing multiple directories (or subdirectories) of YAML files. For more information see our -documentation on the [Kubernetes Agent configuration respository](repository.md). +documentation on the [Kubernetes Agent configuration repository](repository.md). ### Create an Agent record in GitLab @@ -266,7 +267,7 @@ example [`resources.yml` file](#example-resourcesyml-file) in the following ways [Support TLS for gRPC communication issue](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) for progress updates. - When deploying KAS through the [GitLab chart](https://docs.gitlab.com/charts/), it's possible to customize the `kas-address` for `wss` and `ws` schemes to whatever you need. - Check the [chart's KAS Ingress docs](https://docs.gitlab.com/charts/charts/gitlab/kas/#ingress) + Check the [chart's KAS Ingress documentation](https://docs.gitlab.com/charts/charts/gitlab/kas/#ingress) to learn more about it. - In the near future, Omnibus GitLab intends to provision `gitlab-kas` under a sub-domain by default, instead of the `/-/kubernetes-agent` path. Please follow [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5784) for details. - If you defined your own secret name, replace `gitlab-agent-token` with your @@ -436,12 +437,9 @@ spec: The following example projects can help you get started with the Kubernetes Agent. -### Simple NGINX deployment - -This basic GitOps example deploys NGINX: - - [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent) -- [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) +- This basic GitOps example deploys NGINX: [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) +- [Install GitLab Runner](runner.md) ### Deploying GitLab Runner with the Agent diff --git a/doc/user/clusters/agent/runner.md b/doc/user/clusters/agent/runner.md new file mode 100644 index 00000000000..715b27f951a --- /dev/null +++ b/doc/user/clusters/agent/runner.md @@ -0,0 +1,452 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Install GitLab Runner with Kubernetes Agent **(PREMIUM ONLY)** + +These instructions to install the GitLab Runner assume the +[GitLab Kubernetes Agent](index.md) is already configured. + +1. Review the possible [Runner chart YAML values](https://gitlab.com/gitlab-org/charts/gitlab-runner/blob/master/values.yaml) in the Runner chart documentation, + and create a `runner-chart-values.yaml` file with the configuration that fits + your needs, such as: + + ```yaml + # The GitLab Server URL (with protocol) that want to register the runner against + # ref: https://docs.gitlab.com/runner/commands/README.html#gitlab-runner-register + # + gitlabUrl: https://gitlab.my.domain.example.com/ + + # The Registration Token for adding new Runners to the GitLab Server. This must + # be retrieved from your GitLab Instance. + # ref: https://docs.gitlab.com/ce/ci/runners/README.html + # + runnerRegistrationToken: "yrnZW46BrtBFqM7xDzE7dddd" + + # For RBAC support: + rbac: + create: true + + # Run all containers with the privileged flag enabled + # This will allow the docker:dind image to run if you need to run Docker + # commands. Please read the docs before turning this on: + # ref: https://docs.gitlab.com/runner/executors/kubernetes.html#using-dockerdind + runners: + privileged: true + ``` + +1. Create a single manifest file to install the Runner chart with your cluster agent, + replacing `GITLAB GITLAB-RUNNER` with your namespace: + + ```shell + helm template --namespace GITLAB GITLAB-RUNNER -f runner-chart-values.yaml gitlab/gitlab-runner > runner-manifest.yaml + ``` + + An [example file is available](#example-runner-manifest). + +1. Push your `runner-manifest.yaml` to your manifest repository. + +## Example Runner manifest + +```yaml +# This code is an example of a runner manifest looks like. +# Create your own manifest.yaml file to meet your project's needs. + +--- +# Source: gitlab-runner/templates/service-account.yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + annotations: + name: gitlab-runner-gitlab-runner + labels: + app: gitlab-runner-gitlab-runner + chart: gitlab-runner-0.21.1 + release: "gitlab-runner" + heritage: "Helm" +--- +# Source: gitlab-runner/templates/secrets.yaml +apiVersion: v1 +kind: Secret +metadata: + name: "gitlab-runner-gitlab-runner" + labels: + app: gitlab-runner-gitlab-runner + chart: gitlab-runner-0.21.1 + release: "gitlab-runner" + heritage: "Helm" +type: Opaque +data: + runner-registration-token: "FAKE-TOKEN" + runner-token: "" +--- +# Source: gitlab-runner/templates/configmap.yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: gitlab-runner-gitlab-runner + labels: + app: gitlab-runner-gitlab-runner + chart: gitlab-runner-0.21.1 + release: "gitlab-runner" + heritage: "Helm" +data: + entrypoint: | + #!/bin/bash + set -e + mkdir -p /home/gitlab-runner/.gitlab-runner/ + cp /scripts/config.toml /home/gitlab-runner/.gitlab-runner/ + + # Register the runner + if [[ -f /secrets/accesskey && -f /secrets/secretkey ]]; then + export CACHE_S3_ACCESS_KEY=$(cat /secrets/accesskey) + export CACHE_S3_SECRET_KEY=$(cat /secrets/secretkey) + fi + + if [[ -f /secrets/gcs-applicaton-credentials-file ]]; then + export GOOGLE_APPLICATION_CREDENTIALS="/secrets/gcs-applicaton-credentials-file" + elif [[ -f /secrets/gcs-application-credentials-file ]]; then + export GOOGLE_APPLICATION_CREDENTIALS="/secrets/gcs-application-credentials-file" + else + if [[ -f /secrets/gcs-access-id && -f /secrets/gcs-private-key ]]; then + export CACHE_GCS_ACCESS_ID=$(cat /secrets/gcs-access-id) + # echo -e used to make private key multiline (in google json auth key private key is oneline with \n) + export CACHE_GCS_PRIVATE_KEY=$(echo -e $(cat /secrets/gcs-private-key)) + fi + fi + + if [[ -f /secrets/runner-registration-token ]]; then + export REGISTRATION_TOKEN=$(cat /secrets/runner-registration-token) + fi + + if [[ -f /secrets/runner-token ]]; then + export CI_SERVER_TOKEN=$(cat /secrets/runner-token) + fi + + if ! sh /scripts/register-the-runner; then + exit 1 + fi + + # Run pre-entrypoint-script + if ! bash /scripts/pre-entrypoint-script; then + exit 1 + fi + + # Start the runner + exec /entrypoint run --user=gitlab-runner \ + --working-directory=/home/gitlab-runner + + config.toml: | + concurrent = 10 + check_interval = 30 + log_level = "info" + listen_address = ':9252' + configure: | + set -e + cp /init-secrets/* /secrets + register-the-runner: | + #!/bin/bash + MAX_REGISTER_ATTEMPTS=30 + + for i in $(seq 1 "${MAX_REGISTER_ATTEMPTS}"); do + echo "Registration attempt ${i} of ${MAX_REGISTER_ATTEMPTS}" + /entrypoint register \ + --non-interactive + + retval=$? + + if [ ${retval} = 0 ]; then + break + elif [ ${i} = ${MAX_REGISTER_ATTEMPTS} ]; then + exit 1 + fi + + sleep 5 + done + + exit 0 + + check-live: | + #!/bin/bash + if /usr/bin/pgrep -f .*register-the-runner; then + exit 0 + elif /usr/bin/pgrep gitlab.*runner; then + exit 0 + else + exit 1 + fi + + pre-entrypoint-script: | +--- +# Source: gitlab-runner/templates/role.yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: "Role" +metadata: + name: gitlab-runner-gitlab-runner + labels: + app: gitlab-runner-gitlab-runner + chart: gitlab-runner-0.21.1 + release: "gitlab-runner" + heritage: "Helm" +rules: +- apiGroups: [""] + resources: ["*"] + verbs: ["*"] +--- +# Source: gitlab-runner/templates/role-binding.yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: "RoleBinding" +metadata: + name: gitlab-runner-gitlab-runner + labels: + app: gitlab-runner-gitlab-runner + chart: gitlab-runner-0.21.1 + release: "gitlab-runner" + heritage: "Helm" +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: "Role" + name: gitlab-runner-gitlab-runner +subjects: +- kind: ServiceAccount + name: gitlab-runner-gitlab-runner + namespace: "gitlab" +--- +# Source: gitlab-runner/templates/deployment.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: gitlab-runner-gitlab-runner + labels: + app: gitlab-runner-gitlab-runner + chart: gitlab-runner-0.21.1 + release: "gitlab-runner" + heritage: "Helm" +spec: + replicas: 1 + selector: + matchLabels: + app: gitlab-runner-gitlab-runner + template: + metadata: + labels: + app: gitlab-runner-gitlab-runner + chart: gitlab-runner-0.21.1 + release: "gitlab-runner" + heritage: "Helm" + annotations: + checksum/configmap: a6623303f6fcc3a043e87ea937bb8399d2d0068a901aa9c3419ed5c7a5afa9db + checksum/secrets: 32c7d2c16918961b7b84a005680f748e774f61c6f4e4da30650d400d781bbb30 + prometheus.io/scrape: 'true' + prometheus.io/port: '9252' + spec: + securityContext: + runAsUser: 100 + fsGroup: 65533 + terminationGracePeriodSeconds: 3600 + initContainers: + - name: configure + command: ['sh', '/config/configure'] + image: gitlab/gitlab-runner:alpine-v13.4.1 + imagePullPolicy: "IfNotPresent" + env: + + - name: CI_SERVER_URL + value: "https://gitlab.qa.joaocunha.eu/" + - name: CLONE_URL + value: "" + - name: RUNNER_REQUEST_CONCURRENCY + value: "1" + - name: RUNNER_EXECUTOR + value: "kubernetes" + - name: REGISTER_LOCKED + value: "true" + - name: RUNNER_TAG_LIST + value: "" + - name: RUNNER_OUTPUT_LIMIT + value: "4096" + - name: KUBERNETES_IMAGE + value: "ubuntu:16.04" + + - name: KUBERNETES_PRIVILEGED + value: "true" + + - name: KUBERNETES_NAMESPACE + value: "gitlab" + - name: KUBERNETES_POLL_TIMEOUT + value: "180" + - name: KUBERNETES_CPU_LIMIT + value: "" + - name: KUBERNETES_CPU_LIMIT_OVERWRITE_MAX_ALLOWED + value: "" + - name: KUBERNETES_MEMORY_LIMIT + value: "" + - name: KUBERNETES_MEMORY_LIMIT_OVERWRITE_MAX_ALLOWED + value: "" + - name: KUBERNETES_CPU_REQUEST + value: "" + - name: KUBERNETES_CPU_REQUEST_OVERWRITE_MAX_ALLOWED + value: "" + - name: KUBERNETES_MEMORY_REQUEST + value: "" + - name: KUBERNETES_MEMORY_REQUEST_OVERWRITE_MAX_ALLOWED + value: "" + - name: KUBERNETES_SERVICE_ACCOUNT + value: "" + - name: KUBERNETES_SERVICE_CPU_LIMIT + value: "" + - name: KUBERNETES_SERVICE_MEMORY_LIMIT + value: "" + - name: KUBERNETES_SERVICE_CPU_REQUEST + value: "" + - name: KUBERNETES_SERVICE_MEMORY_REQUEST + value: "" + - name: KUBERNETES_HELPER_CPU_LIMIT + value: "" + - name: KUBERNETES_HELPER_MEMORY_LIMIT + value: "" + - name: KUBERNETES_HELPER_CPU_REQUEST + value: "" + - name: KUBERNETES_HELPER_MEMORY_REQUEST + value: "" + - name: KUBERNETES_HELPER_IMAGE + value: "" + - name: KUBERNETES_PULL_POLICY + value: "" + volumeMounts: + - name: runner-secrets + mountPath: /secrets + readOnly: false + - name: scripts + mountPath: /config + readOnly: true + - name: init-runner-secrets + mountPath: /init-secrets + readOnly: true + resources: + {} + serviceAccountName: gitlab-runner-gitlab-runner + containers: + - name: gitlab-runner-gitlab-runner + image: gitlab/gitlab-runner:alpine-v13.4.1 + imagePullPolicy: "IfNotPresent" + lifecycle: + preStop: + exec: + command: ["/entrypoint", "unregister", "--all-runners"] + command: ["/bin/bash", "/scripts/entrypoint"] + env: + + - name: CI_SERVER_URL + value: "https://gitlab.qa.joaocunha.eu/" + - name: CLONE_URL + value: "" + - name: RUNNER_REQUEST_CONCURRENCY + value: "1" + - name: RUNNER_EXECUTOR + value: "kubernetes" + - name: REGISTER_LOCKED + value: "true" + - name: RUNNER_TAG_LIST + value: "" + - name: RUNNER_OUTPUT_LIMIT + value: "4096" + - name: KUBERNETES_IMAGE + value: "ubuntu:16.04" + + - name: KUBERNETES_PRIVILEGED + value: "true" + + - name: KUBERNETES_NAMESPACE + value: "gitlab" + - name: KUBERNETES_POLL_TIMEOUT + value: "180" + - name: KUBERNETES_CPU_LIMIT + value: "" + - name: KUBERNETES_CPU_LIMIT_OVERWRITE_MAX_ALLOWED + value: "" + - name: KUBERNETES_MEMORY_LIMIT + value: "" + - name: KUBERNETES_MEMORY_LIMIT_OVERWRITE_MAX_ALLOWED + value: "" + - name: KUBERNETES_CPU_REQUEST + value: "" + - name: KUBERNETES_CPU_REQUEST_OVERWRITE_MAX_ALLOWED + value: "" + - name: KUBERNETES_MEMORY_REQUEST + value: "" + - name: KUBERNETES_MEMORY_REQUEST_OVERWRITE_MAX_ALLOWED + value: "" + - name: KUBERNETES_SERVICE_ACCOUNT + value: "" + - name: KUBERNETES_SERVICE_CPU_LIMIT + value: "" + - name: KUBERNETES_SERVICE_MEMORY_LIMIT + value: "" + - name: KUBERNETES_SERVICE_CPU_REQUEST + value: "" + - name: KUBERNETES_SERVICE_MEMORY_REQUEST + value: "" + - name: KUBERNETES_HELPER_CPU_LIMIT + value: "" + - name: KUBERNETES_HELPER_MEMORY_LIMIT + value: "" + - name: KUBERNETES_HELPER_CPU_REQUEST + value: "" + - name: KUBERNETES_HELPER_MEMORY_REQUEST + value: "" + - name: KUBERNETES_HELPER_IMAGE + value: "" + - name: KUBERNETES_PULL_POLICY + value: "" + livenessProbe: + exec: + command: ["/bin/bash", "/scripts/check-live"] + initialDelaySeconds: 60 + timeoutSeconds: 1 + periodSeconds: 10 + successThreshold: 1 + failureThreshold: 3 + readinessProbe: + exec: + command: ["/usr/bin/pgrep","gitlab.*runner"] + initialDelaySeconds: 10 + timeoutSeconds: 1 + periodSeconds: 10 + successThreshold: 1 + failureThreshold: 3 + ports: + - name: metrics + containerPort: 9252 + volumeMounts: + - name: runner-secrets + mountPath: /secrets + - name: etc-gitlab-runner + mountPath: /home/gitlab-runner/.gitlab-runner + - name: scripts + mountPath: /scripts + resources: + {} + volumes: + - name: runner-secrets + emptyDir: + medium: "Memory" + - name: etc-gitlab-runner + emptyDir: + medium: "Memory" + - name: init-runner-secrets + projected: + sources: + - secret: + name: "gitlab-runner-gitlab-runner" + items: + - key: runner-registration-token + path: runner-registration-token + - key: runner-token + path: runner-token + - name: scripts + configMap: + name: gitlab-runner-gitlab-runner +``` diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 53be7e995d5..b03dfb79ae0 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -100,7 +100,7 @@ include: - template: Managed-Cluster-Applications.gitlab-ci.yml apply: - image: "registry.gitlab.com/gitlab-org/cluster-integration/cluster-applications:v0.34.1" + image: "registry.gitlab.com/gitlab-org/cluster-integration/cluster-applications:v0.37.0" ``` ### Use the template with a custom environment @@ -1268,6 +1268,11 @@ record. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21966) in GitLab 12.7. +WARNING: +The Web Application Firewall is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/271276) +in GitLab 13.6, and planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/271349) +in GitLab 14.0. + A Web Application Firewall (WAF) examines traffic being sent or received, and can block malicious traffic before it reaches your application. The benefits of a WAF are: @@ -1296,7 +1301,7 @@ To enable WAF, switch its respective toggle to the enabled position when install or updating [Ingress application](#ingress). If this is your first time using the GitLab WAF, we recommend you follow the -[quick start guide](../../topics/web_application_firewall/quick_start_guide.md). +[quick start guide](../project/clusters/protect/web_application_firewall/quick_start_guide.md). There is a small performance overhead by enabling ModSecurity. If this is considered significant for your application, you can disable ModSecurity's @@ -1308,7 +1313,7 @@ rule engine for your deployed application in any of the following ways: 1. Switch its respective toggle to the disabled position, and then apply changes by selecting **Save changes** to reinstall Ingress with the recent changes. - + ##### Logging and blocking modes @@ -1321,7 +1326,7 @@ To help you tune your WAF rules, you can globally set your WAF to either To change your WAF's mode: 1. If you haven't already done so, - [install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md). + [install ModSecurity](../project/clusters/protect/web_application_firewall/quick_start_guide.md). 1. Navigate to **Operations > Kubernetes**. 1. In **Applications**, scroll to **Ingress**. 1. Under **Global default**, select your desired mode. @@ -1337,12 +1342,12 @@ The **ModSecurity** user interface controls are disabled if the version deployed differs from the one available in GitLab. However, actions at the [Ingress](#ingress) level, such as uninstalling, can still be performed: - + Update [Ingress](#ingress) to the most recent version to take advantage of bug fixes, security fixes, and performance improvements. To update the [Ingress application](#ingress), you must first uninstall it, and then re-install -it as described in [Install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md). +it as described in [Install ModSecurity](../project/clusters/protect/web_application_firewall/quick_start_guide.md). ##### Viewing Web Application Firewall traffic |