diff options
Diffstat (limited to 'doc/user/clusters/agent')
| -rw-r--r-- | doc/user/clusters/agent/ci_cd_tunnel.md | 71 | ||||
| -rw-r--r-- | doc/user/clusters/agent/index.md | 347 | ||||
| -rw-r--r-- | doc/user/clusters/agent/install/index.md | 250 | ||||
| -rw-r--r-- | doc/user/clusters/agent/repository.md | 102 | ||||
| -rw-r--r-- | doc/user/clusters/agent/troubleshooting.md | 193 |
5 files changed, 576 insertions, 387 deletions
diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md index f1c49b87383..5fe772d9686 100644 --- a/doc/user/clusters/agent/ci_cd_tunnel.md +++ b/doc/user/clusters/agent/ci_cd_tunnel.md @@ -12,53 +12,52 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) to GitLab Free in 14.5. > - Support for Omnibus installations was [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5686) in GitLab 14.5. -The CI/CD Tunnel enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network -connectivity between GitLab Runner and a cluster. GitLab Runner does not have to be running in the same cluster. +To use GitLab CI/CD to safely deploy your application to a cluster, you can use the CI/CD Tunnel. -Only CI/CD jobs set in the configuration project can access one of the configured agents. +You can authorize multiple projects to access the same cluster, so you +can keep your application's codebase in one repository and configure +your cluster in another. This method is scalable and can save you resources. -## Prerequisites - -- An existing Kubernetes cluster. -- An agent [installed on your cluster](install/index.md#install-the-agent-into-the-cluster). +To ensure access to your cluster is safe, only the projects you +authorize can access your Agent through the CI/CD Tunnel. -## Use the CI/CD Tunnel to run Kubernetes commands from GitLab CI/CD - -If your project has access to one or more Agent records available, its CI/CD -jobs provide a `KUBECONFIG` variable compatible with `kubectl`. +## Prerequisites -Also, each Agent has a separate context (`kubecontext`). By default, -there isn't any context selected. -Contexts are named in the following format: `<agent-configuration-project-path>:<agent-name>`. -To get the list of available contexts, run `kubectl config get-contexts`. +To use the CI/CD Tunnel, you need an existing Kubernetes cluster connected to GitLab through the +[GitLab Agent](install/index.md#install-the-agent-onto-the-cluster). -## Share the CI/CD Tunnel provided by an Agent with other projects and groups +To run your CI/CD jobs using the CI/CD Tunnel, you do not need to have a runner in the same cluster. -The Agent can be configured to enable access to the CI/CD Tunnel to other projects or all the projects under a given group. This way you can have a single agent serving all the requests for several projects saving on resources and maintenance. +## How the CI/CD Tunnel works -You can read more on how to [authorize access in the Agent configuration reference](repository.md#authorize-projects-and-groups-to-use-an-agent). +When you authorize a project to use an Agent, the Tunnel automatically +injects a `KUBECONFIG` variable into its CI/CD jobs. This way, you can +run `kubectl` commands from GitLab CI/CD scripts that belong to the +authorized project. -## Restrict access of authorized projects and groups **(PREMIUM)** +When you authorize a group, all the projects that belong to that group +become authorized to access the selected Agent. -You can [configure various impersonations](repository.md#use-impersonation-to-restrict-project-and-group-access) to restrict the permissions of a shared CI/CD Tunnel. +An Agent can only authorize projects or groups in the same group +hierarchy as the Agent's configuration project. You can authorize +up to 100 projects and 100 groups per Agent. -## Example for a `kubectl` command using the CI/CD Tunnel +Also, each Agent has a separate context (`kubecontext`). +The Tunnel uses this information to safely allow access to the cluster from +jobs running in the projects you authorized. -The following example shows a CI/CD job that runs a `kubectl` command using the CI/CD Tunnel. -You can run any Kubernetes-specific commands similarly, such as `kubectl`, `helm`, -`kpt`, and so on. To do so: +### `~/.kube/cache` permissions + +`kubectl` and other tools based on the same libraries (such as Helm, `kpt`, and `kustomize`) cache information about +the cluster in `~/.kube/cache`. If this directory is not writable, the tool fetches information on each invocation, +making interactions slower and creating unnecessary load on the cluster. Make sure that this directory in the container image +you use is writable for the best experience. -1. Set your Agent's context in the first command with the format `<agent-configuration-project-path>:<agent-name>`. -1. Run Kubernetes commands. +## Configure the CI/CD Tunnel -For example: +The CI/CD Tunnel is configured directly through the +Agent's configuration file ([`config.yaml`](repository.md)) to: -```yaml - deploy: - image: - name: bitnami/kubectl:latest - entrypoint: [""] - script: - - kubectl config use-context path/to/agent-configuration-project:your-agent-name - - kubectl get pods -``` +- Authorize [projects](repository.md#authorize-projects-to-use-an-agent) and [groups](repository.md#authorize-groups-to-use-an-agent) to use the same Agent. +- [Run `kubectl` commands using the CI/CD Tunnel](repository.md#run-kubectl-commands-using-the-cicd-tunnel). +- [Restrict access of authorized projects and groups through impersonation strategies](repository.md#use-impersonation-to-restrict-project-and-group-access). diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index a235c0ef6f8..3fb141e402f 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -4,60 +4,71 @@ 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 --- -# GitLab Agent for Kubernetes **(FREE)** +# Connecting a Kubernetes cluster with GitLab > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in GitLab 13.4. > - Support for `grpcs` [introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) in GitLab 13.6. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300960) in GitLab 13.10, KAS became available on GitLab.com under `wss://kas.gitlab.com` through an Early Adopter Program. -> - Introduced in GitLab 13.11, the GitLab Agent became available to every project on GitLab.com. +> - Agent Server [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300960) on GitLab.com under `wss://kas.gitlab.com` through an Early Adopter Program in GitLab 13.10. +> - The agent became available to every project on GitLab.com in GitLab 13.11. > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5. -> - [Renamed](https://gitlab.com/groups/gitlab-org/-/epics/7167) from "GitLab Kubernetes Agent" to "GitLab Agent for Kubernetes" in GitLab 14.6. +> - [Renamed](https://gitlab.com/groups/gitlab-org/-/epics/7167) from "GitLab Kubernetes Agent" to "GitLab agent for Kubernetes" in GitLab 14.6. -The [GitLab Agent for Kubernetes](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) ("Agent", for short) -is an active in-cluster component for connecting Kubernetes clusters to GitLab safely to support cloud-native deployment, management, and monitoring. +You can connect your Kubernetes cluster with GitLab to deploy, manage, +and monitor your cloud-native solutions. You can choose from two primary workflows. -The Agent is installed into the cluster through code, providing you with a fast, safe, stable, and scalable solution. +In a **GitOps workflow**, you keep your Kubernetes manifests in GitLab. You install a GitLab agent in your cluster, and +any time you update your manifests, the agent updates the cluster. This workflow is fully driven with Git and is considered pull-based, +because the cluster is pulling updates from your GitLab repository. + +In a **CI/CD** workflow, you use GitLab CI/CD to query and update your cluster by using the Kubernetes API. +This workflow is considered push-based, because GitLab is pushing requests from GitLab CI/CD to your cluster. + +Both of these workflows require you to [install an agent in your cluster](install/index.md). + +## Supported cluster versions + +GitLab supports the following Kubernetes versions. You can upgrade your +Kubernetes version to a supported version at any time: + +- 1.20 (support ends on July 22, 2022) +- 1.19 (support ends on February 22, 2022) +- 1.18 (support ends on November 22, 2021) +- 1.17 (support ends on September 22, 2021) + +GitLab supports at least two production-ready Kubernetes minor +versions at any given time. GitLab regularly reviews the supported versions and +provides a three-month deprecation period before removing support for a specific +version. The list of supported versions is based on: + +- The versions supported by major managed Kubernetes providers. +- The versions [supported by the Kubernetes community](https://kubernetes.io/releases/version-skew-policy/#supported-versions). + +[This epic](https://gitlab.com/groups/gitlab-org/-/epics/4827) tracks support for other Kubernetes versions. + +Some GitLab features might work on versions not listed here. + +## Using Kubernetes with GitOps **(PREMIUM)** With GitOps, you can manage containerized clusters and applications from a Git repository that: - Is the single source of truth of your system. - Is the single place where you operate your system. -- Is a single resource to monitor your system. -By combining GitLab, Kubernetes, and GitOps, it results in a robust infrastructure: +By combining GitLab, Kubernetes, and GitOps, you can have: - GitLab as the GitOps operator. - Kubernetes as the automation and convergence system. -- GitLab CI/CD as the Continuous Integration and Continuous Deployment engine. +- GitLab CI/CD for Continuous Integration and the agent for Continuous Deployment. Beyond that, you can use all the features offered by GitLab as the all-in-one DevOps platform for your product and your team. -## Agent's features +### GitOps workflow **(PREMIUM)** -By using the Agent, you can: - -- Connect GitLab with a Kubernetes cluster behind a firewall or a -Network Address Translation (NAT). -- Have real-time access to API endpoints in your cluster from GitLab CI/CD. -- Use GitOps to configure your cluster through the [Agent's repository](repository.md). -- Perform pull-based or push-based GitOps deployments. -- Configure [Network Security Alerts](#kubernetes-network-security-alerts) -based on [Container Network Policies](../../application_security/policies/index.md#container-network-policy). -- Track objects applied to your cluster through [inventory objects](../../infrastructure/clusters/deploy/inventory_object.md). -- Use the [CI/CD Tunnel](ci_cd_tunnel.md) to access Kubernetes clusters -from GitLab CI/CD jobs while keeping the cluster's APIs safe and unexposed -to the internet. -- [Deploy the GitLab Runner in a Kubernetes cluster](https://docs.gitlab.com/runner/install/kubernetes-agent.html). - -See the [Agent roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329) to track its development. - -To contribute to the Agent, see the [Agent's development documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/doc). - -## Agent's GitOps workflow **(PREMIUM)** - -The Agent uses multiple GitLab projects to provide a flexible workflow +The agent uses multiple GitLab projects to provide a flexible workflow that can suit various needs. This diagram shows these repositories and the main +The agent uses multiple GitLab projects to provide a flexible workflow. +This diagram shows these repositories and the main actors involved in a deployment: ```mermaid @@ -65,7 +76,7 @@ sequenceDiagram participant D as Developer participant A as Application code repository participant M as Manifest repository - participant K as GitLab Agent + participant K as GitLab agent participant C as Agent configuration repository loop Regularly K-->>C: Grab the configuration @@ -78,61 +89,28 @@ sequenceDiagram end ``` -For more details, refer to our [architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture) in the Agent project. - -## Install the Agent in your cluster - -See how to [install the Agent in your cluster](install/index.md). - -## GitOps deployments **(PREMIUM)** - -To perform GitOps deployments with the Agent, you need: +For details, view the [architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture). -- A properly-configured Kubernetes cluster where the Agent is running. -- A [configuration repository](repository.md) that contains a -`config.yaml` file, which tells the Agent the repositories to synchronize -with the cluster. -- A manifest repository that contains manifest files. Any changes to manifest files are applied to the cluster. +To perform GitOps deployments, you need: -You can use a single GitLab project or different projects for the Agent -configuration and manifest files, as follows: +- A properly-configured Kubernetes cluster where the GitLab agent is running. +- A project that contains the agent's configuration file (`config.yaml`) in the repository. + This file tells the agent which repositories to synchronize with the cluster. +- A project that contains Kubernetes manifests. Any changes to manifests are applied to the cluster. -- Single GitLab project (recommended): When you use a single repository to hold - both the manifest and the configuration files, these projects can be either - private or public. -- Two GitLab projects: When you use two different GitLab projects (one for - manifest files and another for configuration files), the manifests project must - be public, while the configuration project can be either private or public. +You can keep the agent's configuration file and Kubernetes manifests in one project, or you can use multiple. -Support for separated private manifest and configuration repositories is tracked in this [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/220912). +- One GitLab project (recommended): When you use one project for both the Kubernetes manifests + and the agent's configuration file, the projects can be either private or public. +- Two GitLab projects: When you use two different GitLab projects (one for Kubernetes + manifests and another for the agent's configuration file), the project with Kubernetes manifests must + be public. The project with the agent's configuration file can be either private or public. -## Kubernetes Network Security Alerts **(ULTIMATE)** - -The GitLab Agent also provides an integration with Cilium. This integration provides a simple way to -generate network policy-related alerts and to surface those alerts in GitLab. - -There are several components that work in concert for the Agent to generate the alerts: - -- A working Kubernetes cluster. -- Cilium integration through either of these options: - - Installation through [cluster management template](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium). - - Enablement of [hubble-relay](https://docs.cilium.io/en/v1.8/concepts/overview/#hubble) on an - existing installation. -- One or more network policies through any of these options: - - Use the [Container Network Policy editor](../../application_security/policies/index.md#container-network-policy-editor) to create and manage policies. - - Use an [AutoDevOps](../../application_security/policies/index.md#container-network-policy) configuration. - - Add the required labels and annotations to existing network policies. -- A configuration repository with [Cilium configured in `config.yaml`](repository.md#surface-network-security-alerts-from-cluster-to-gitlab) - -The setup process follows the same [Agent's installation steps](install/index.md), -with the following differences: - -- When you define a configuration repository, you must do so with [Cilium settings](repository.md#surface-network-security-alerts-from-cluster-to-gitlab). -- You do not need to specify the `gitops` configuration section. +Support for separate private projects is tracked in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/283885). ## Remove an agent -You can remove an agent using the [GitLab UI](#remove-an-agent-through-the-gitlab-ui) or through the [GraphQL API](#remove-an-agent-with-the-gitlab-graphql-api). +You can remove an agent by using the [GitLab UI](#remove-an-agent-through-the-gitlab-ui) or the [GraphQL API](#remove-an-agent-with-the-gitlab-graphql-api). ### Remove an agent through the GitLab UI @@ -140,16 +118,16 @@ You can remove an agent using the [GitLab UI](#remove-an-agent-through-the-gitla To remove an agent from the UI: -1. Go to your agent's configuration repository. -1. From your project's sidebar, select **Infrastructure > Kubernetes clusters**. -1. Select your agent from the table, and then in the **Options** column, click the vertical ellipsis -(**{ellipsis_v}**) button and select **Delete agent**. +1. On the top bar, select **Menu > Projects** and find the project that contains the agent's configuration file. +1. From the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. In the table, in the row for your agent, in the **Options** column, select the vertical ellipsis (**{ellipsis_v}**). +1. Select **Delete agent**. ### Remove an agent with the GitLab GraphQL API 1. Get the `<cluster-agent-token-id>` from a query in the interactive GraphQL explorer. -For GitLab.com, go to <https://gitlab.com/-/graphql-explorer> to open GraphQL Explorer. -For self-managed GitLab instances, go to `https://gitlab.example.com/-/graphql-explorer`, replacing `gitlab.example.com` with your own instance's URL. + - For GitLab.com, go to <https://gitlab.com/-/graphql-explorer> to open GraphQL Explorer. + - For self-managed GitLab, go to `https://gitlab.example.com/-/graphql-explorer`, replacing `gitlab.example.com` with your instance's URL. ```graphql query{ @@ -195,185 +173,48 @@ For self-managed GitLab instances, go to `https://gitlab.example.com/-/graphql-e } ``` -1. Delete the Agent in your cluster: +1. Delete the agent in your cluster: ```shell kubectl delete -n gitlab-kubernetes-agent -f ./resources.yml ``` -## Migrating to the GitLab Agent from the legacy certificate-based integration - -Find out how to [migrate to the GitLab Agent for Kubernetes](../../infrastructure/clusters/migrate_to_gitlab_agent.md) from the certificate-based integration depending on the features you use. - -## Troubleshooting - -If you face any issues while using the Agent, read the -service logs with the following command: - -```shell -kubectl logs -f -l=app=gitlab-kubernetes-agent -n gitlab-kubernetes-agent -``` - -GitLab administrators can additionally view the [GitLab Agent Server logs](../../../administration/clusters/kas.md#troubleshooting). - -### Agent logs - -#### Transport: Error while dialing failed to WebSocket dial +## Migrating to the agent from the legacy certificate-based integration -```json -{ - "level": "warn", - "time": "2020-11-04T10:14:39.368Z", - "msg": "GetConfiguration failed", - "error": "rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://gitlab-kas:443/-/kubernetes-agent\\\": dial tcp: lookup gitlab-kas on 10.60.0.10:53: no such host\"" -} -``` - -This error is shown if there are some connectivity issues between the address -specified as `kas-address`, and your Agent pod. To fix it, make sure that you -specified the `kas-address` correctly. - -```json -{ - "level": "error", - "time": "2021-06-25T21:15:45.335Z", - "msg": "Reverse tunnel", - "mod_name": "reverse_tunnel", - "error": "Connect(): rpc error: code = Unavailable desc = connection error: desc= \"transport: Error while dialing failed to WebSocket dial: expected handshake response status code 101 but got 301\"" -} -``` - -This error occurs if the `kas-address` doesn't include a trailing slash. To fix it, make sure that the -`wss` or `ws` URL ends with a trailing slash, such as `wss://GitLab.host.tld:443/-/kubernetes-agent/` -or `ws://GitLab.host.tld:80/-/kubernetes-agent/`. - -#### ValidationError(Deployment.metadata) - -```json -{ - "level": "info", - "time": "2020-10-30T08:56:54.329Z", - "msg": "Synced", - "project_id": "root/kas-manifest001", - "resource_key": "apps/Deployment/kas-test001/nginx-deployment", - "sync_result": "error validating data: [ValidationError(Deployment.metadata): unknown field \"replicas\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"selector\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"template\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta]" -} -``` +Find out how to [migrate to the agent for Kubernetes](../../infrastructure/clusters/migrate_to_gitlab_agent.md) from the certificate-based integration. -This error is shown if a manifest file is malformed, and Kubernetes can't -create specified objects. Make sure that your manifest files are valid. You -may try using them to create objects in Kubernetes directly for more troubleshooting. +## Kubernetes network security alerts **(ULTIMATE)** -#### Error while dialing failed to WebSocket dial: failed to send handshake request - -```json -{ - "level": "warn", - "time": "2020-10-30T09:50:51.173Z", - "msg": "GetConfiguration failed", - "error": "rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent\\\": net/http: HTTP/1.x transport connection broken: malformed HTTP response \\\"\\\\x00\\\\x00\\\\x06\\\\x04\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x05\\\\x00\\\\x00@\\\\x00\\\"\"" -} -``` - -This error is shown if you configured `wss` as `kas-address` on the agent side, -but KAS on the server side is not available via `wss`. To fix it, make sure the -same schemes are configured on both sides. - -It's not possible to set the `grpc` scheme due to the issue -[It is not possible to configure KAS to work with `grpc` without directly editing GitLab KAS deployment](https://gitlab.com/gitlab-org/gitlab/-/issues/276888). To use `grpc` while the -issue is in progress, directly edit the deployment with the -`kubectl edit deployment gitlab-kas` command, and change `--listen-websocket=true` to `--listen-websocket=false`. After running that command, you should be able to use -`grpc://gitlab-kas.<YOUR-NAMESPACE>:8150`. - -#### Decompressor is not installed for grpc-encoding - -```json -{ - "level": "warn", - "time": "2020-11-05T05:25:46.916Z", - "msg": "GetConfiguration.Recv failed", - "error": "rpc error: code = Unimplemented desc = grpc: Decompressor is not installed for grpc-encoding \"gzip\"" -} -``` +> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. -This error is shown if the version of the agent is newer that the version of KAS. -To fix it, make sure that both `agentk` and KAS use the same versions. +WARNING: +Cilium integration is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) +for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 15.0. -#### Certificate signed by unknown authority +The agent for Kubernetes also provides an integration with Cilium. This integration provides a simple way to +generate network policy-related alerts and to surface those alerts in GitLab. -```json -{ - "level": "error", - "time": "2021-02-25T07:22:37.158Z", - "msg": "Reverse tunnel", - "mod_name": "reverse_tunnel", - "error": "Connect(): rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent/\\\": x509: certificate signed by unknown authority\"" -} -``` +Several components work in concert for the agent to generate the alerts: -This error is shown if your GitLab instance is using a certificate signed by an internal CA that -is unknown to the agent. One approach to fixing it is to present the CA certificate file to the agent -via a Kubernetes `configmap` and mount the file in the agent `/etc/ssl/certs` directory from where it -will be picked up automatically. +- A working Kubernetes cluster. +- Cilium integration through either of these options: + - Installation through [cluster management template](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium). + - Enablement of [hubble-relay](https://docs.cilium.io/en/v1.8/concepts/overview/#hubble) on an + existing installation. +- One or more network policies through any of these options: + - Use the [Container Network Policy editor](../../application_security/policies/index.md#container-network-policy-editor) to create and manage policies. + - Use an [AutoDevOps](../../application_security/policies/index.md#container-network-policy) configuration. + - Add the required labels and annotations to existing network policies. +- A configuration repository with [Cilium configured in `config.yaml`](repository.md#surface-network-security-alerts-from-cluster-to-gitlab) -For example, if your internal CA certificate is `myCA.pem`: +The setup process follows the same [agent's installation steps](install/index.md), +with the following differences: -```plaintext -kubectl -n gitlab-kubernetes-agent create configmap ca-pemstore --from-file=myCA.pem -``` +- When you define a configuration repository, you must do so with [Cilium settings](repository.md#surface-network-security-alerts-from-cluster-to-gitlab). +- You do not need to specify the `gitops` configuration section. -Then in `resources.yml`: - -```yaml - spec: - serviceAccountName: gitlab-kubernetes-agent - containers: - - name: agent - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>" - args: - - --token-file=/config/token - - --kas-address - - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com. - # - wss://gitlab.host.tld:443/-/kubernetes-agent/ - # - wss://kas.gitlab.com # for GitLab.com users, use this KAS. - # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker. - volumeMounts: - - name: token-volume - mountPath: /config - - name: ca-pemstore-volume - mountPath: /etc/ssl/certs/myCA.pem - subPath: myCA.pem - volumes: - - name: token-volume - secret: - secretName: gitlab-kubernetes-agent-token - - name: ca-pemstore-volume - configMap: - name: ca-pemstore - items: - - key: myCA.pem - path: myCA.pem -``` +## Related topics -Alternatively, you can mount the certificate file at a different location and include it using the -`--ca-cert-file` agent parameter: - -```yaml - containers: - - name: agent - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>" - args: - - --ca-cert-file=/tmp/myCA.pem - - --token-file=/config/token - - --kas-address - - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com. - # - wss://gitlab.host.tld:443/-/kubernetes-agent/ - # - wss://kas.gitlab.com # for GitLab.com users, use this KAS. - # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker. - volumeMounts: - - name: token-volume - mountPath: /config - - name: ca-pemstore-volume - mountPath: /tmp/myCA.pem - subPath: myCA.pem -``` +- [Troubleshooting](troubleshooting.md) +- [Contribute to the GitLab agent's development](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/doc) diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index b2372789284..4d196e57f8f 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -6,112 +6,140 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Install the GitLab Agent **(FREE)** -> [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5. +> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5. +> - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/594) multi-arch images in GitLab 14.8. The first multi-arch release is `v14.8.1`. It supports AMD64 and ARM64 architectures. -To get started with the Agent, install it in your cluster. +To connect a cluster to GitLab, you need to install the GitLab Agent +onto your cluster. -## Prerequisites **(SELF)** +## Prerequisites -- An existing Kubernetes cluster. +- An existing Kubernetes cluster. If you don't have a cluster yet, you can create a new cluster on cloud providers, such as: + - [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine/docs/quickstart) + - [Amazon Elastic Kubernetes Service (EKS)](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html) + - [Digital Ocean](https://docs.digitalocean.com/products/kubernetes/quickstart/) - On self-managed GitLab instances, a GitLab administrator needs to set up the [GitLab Agent Server (KAS)](../../../../administration/clusters/kas.md). ## Installation steps -To install the [Agent](../index.md) in your cluster: +To install the GitLab Agent on your cluster: 1. [Define a configuration repository](#define-a-configuration-repository). -1. [Register an agent with GitLab](#register-an-agent-with-gitlab). -1. [Install the agent into the cluster](#install-the-agent-into-the-cluster). +1. [Register the Agent with GitLab](#register-the-agent-with-gitlab). +1. [Install the Agent onto the cluster](#install-the-agent-onto-the-cluster). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a GitLab 14.2 [walking-through video](https://www.youtube.com/watch?v=XuBpKtsgGkE) with this process. +When you complete the installation process, you can +[view your Agent's status and activity information](#view-your-agents). +You can also [configure](#configure-the-agent) it to your needs. + ### Define a configuration repository > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the Agent manifest configuration can be added to multiple directories (or subdirectories) of its repository. > - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. -To create an agent, you need a GitLab repository to hold the configuration file. +To create an Agent, you need a GitLab repository to hold its +configuration file. If you already have a repository holding your +cluster's manifest files, you can use it to store your +Agent's configuration file and sync them with no further steps. -After installed, when you update the configuration file, GitLab transmits the -information to the cluster automatically without downtime. +#### Create the Agent's configuration file -In your repository, add the Agent configuration file under: +To create an Agent, go to the repository where you want to store +it and add the Agent's configuration file under: ```plaintext .gitlab/agents/<agent-name>/config.yaml ``` -Make sure that `<agent-name>` conforms to the [Agent's naming format](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md#agent-identity-and-name). - -WARNING: -The agent is only recognized if you use `.yaml` extension for the `config.yaml` file. The extension `.yml` is **not** recognized. - -You **don't have to add any content** to this file when you create it. The fact that the file exists -tells GitLab that this is an agent configuration file and enables the [CI/CD tunnel](../ci_cd_tunnel.md#example-for-a-kubectl-command-using-the-cicd-tunnel). Later on, you can use this -file to [configure the agent](../repository.md) by setting up parameters such as: +You **don't have to add any content** to this file at the moment you +create it. The fact that the file exists tells GitLab that this is +an Agent. You can edit it later to [configure the Agent](#configure-the-agent). -- Groups and projects that can access the agent via the [CI/CD Tunnel](../ci_cd_tunnel.md). -- [Manifest projects to synchronize](../repository.md#synchronize-manifest-projects). -- The address of the `hubble-relay` for the [Network Security policy integrations](../../../project/clusters/protect/index.md). +When creating this file, pay special attention to: -To see all the settings available, read the [Agent configuration repository documentation](../repository.md). +- The [Agent's naming format](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md#agent-identity-and-name). +- The file extension: use the `.yaml` extension (`config.yaml`). The `.yml` extension is **not** recognized. -### Register an agent with GitLab +### Register the Agent with GitLab > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5786) in GitLab 14.1, you can create a new Agent record directly from the GitLab UI. -Next, create a GitLab Rails Agent record to associate it with -the configuration repository project. Creating this record also creates a Secret needed to configure -the Agent in subsequent steps. +Now that you've created your Agent's configuration file, register it +with GitLab. +When you register the Agent, GitLab generates a token that you need for +installing the Agent onto your cluster. -In GitLab: +In GitLab, go to the project where you added your Agent's configuration +file and: 1. Ensure that [GitLab CI/CD is enabled in your project](../../../../ci/enable_or_disable_ci.md#enable-cicd-in-a-project). 1. From your project's sidebar, select **Infrastructure > Kubernetes clusters**. 1. Select **Actions**. -1. From the **Select an agent** dropdown, select the agent you want to connect and select **Register an agent** to access the installation form. -1. The form reveals your registration token. Securely store this secret token as you cannot view it again. -1. Copy the command under **Recommended installation method**. +1. From the **Select an Agent** dropdown list, select the Agent you want to register and select **Register an Agent**. +1. GitLab generates a registration token for this Agent. Securely store this secret token, as you need it to install the Agent onto your cluster and to [update the Agent](#update-the-agent-version) to another version. +1. Copy the command under **Recommended installation method**. You need it to install the Agent onto your cluster through the one-liner installation method. + +### Install the Agent onto the cluster -### Install the agent into the cluster +To connect your cluster to GitLab, install the registered Agent +onto your cluster. To install it, you can use either: -In your computer: +- [The one-liner installation method](#one-liner-installation). +- [The advanced installation method](#advanced-installation). -1. Open your local terminal and connect to your cluster. +You can use the one-liner installation for trying to use the Agent for the first time, to do internal setups with +high trust, and to quickly get started. For long-term production usage, you may want to use the advanced installation +method to benefit from more configuration options. + +#### One-liner installation + +The one-liner installation is the simplest process, but you need +Docker installed locally. If you don't have it, you can either install +it or opt to the [advanced installation method](#advanced-installation). + +To install the Agent on your cluster using the one-liner installation: + +1. In your computer, open the terminal and connect to your cluster. 1. Run the command you copied when registering your cluster in the previous step. -See the following sections to learn about customizing the installation. +Optionally, you can [customize the one-liner installation command](#customize-the-one-liner-installation). -## Simple installation method +##### Customize the one-liner installation -The command provided by GitLab does the following things: +The one-liner command generated by GitLab: - Creates a namespace for the deployment (`gitlab-kubernetes-agent`). -- Sets up a service account with `cluster-admin` rights. Read more on [how you can restrict this service account](#customize-the-permissions-for-the-agentk-service-account). -- Creates a `Secret` resource for the agent registration token. +- Sets up a service account with `cluster-admin` rights (see [how to restrict this service account](#customize-the-permissions-for-the-agentk-service-account)). +- Creates a `Secret` resource for the Agent's registration token. - Creates a `Deployment` resource for the `agentk` pod. -The one-liner installer can be customized at the command line. To find out the various options the above Docker container supports, run: +You can edit these parameters according to your needs to customize the +one-liner installation command at the command line. To find all available +options, run in your terminal: ```shell docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help ``` WARNING: -`--agent-version stable` can be used to refer to the latest stable release at the time when the command runs. It's fine for -testing purposes but for production please make sure to specify a matching version explicitly. - -## Advanced installation method +`--agent-version stable` can be used to refer to the latest stable +release at the time when the command runs. It's fine for testing +purposes but for production please make sure to specify a matching +version explicitly. -For more advanced configurations, we recommend to use [the `kpt` based installation method](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent). +#### Advanced installation -Otherwise, follow the manual installation steps described below. +For advanced installation options, use [the `kpt` installation method](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent). -### Customize the permissions for the `agentk` service account +##### Customize the permissions for the `agentk` service account -The GitLab Agent for Kubernetes allows you to fully own your cluster and requires only the permissions you give. Still, for easy getting started, by default the generated manifests provide `cluster-admin` rights to the agent. +The GitLab Agent allows you to fully own your cluster and grant GitLab +the permissions you want. Still, to facilitate the process, by default the +generated manifests provide `cluster-admin` rights to the Agent. -As part of the advanced installation method, you can restrict the agent access rights using Kustomize overlays. [An example is commented out](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/build/deployment/gitlab-agent/cluster/kustomization.yaml) in the `kpt` package you retrieved as part of the installation. +You can restrict the Agent's access rights using Kustomize overlays. [An example is commented out](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/build/deployment/gitlab-agent/cluster/kustomization.yaml) in the `kpt` package you retrieved as part of the installation. To create restricted permissions: @@ -121,50 +149,115 @@ To create restricted permissions: The above setup allows you to regularly update from the upstream package using `kpt pkg update gitlab-agent --strategy resource-merge` and maintain your customizations at the same time. -## Example projects +## Configure the Agent -The following example projects can help you get started with the Agent. +When successfully installed, you can [configure the Agent](../repository.md) +by editing its configuration file. +When you update the configuration file, GitLab transmits the +information to the cluster automatically without downtime. -- [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent) -- This basic GitOps example deploys NGINX: [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) +## View your Agents -## View installed Agents +> The version of installed `agentk` shown on the Agent tab [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340882) in GitLab 14.8. +If you have at least the Developer role, you can access the Agent's +configuration repository and view the Agent's list: -Users with at least the [Developer](../../../permissions.md) can access the user interface -for the Agent at **Infrastructure > Kubernetes clusters**, under the -**Agent** tab. This page lists all registered agents for the current project, -and the configuration directory for each agent: +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. Select **Agent** tab to view clusters connected to GitLab through the Agent. - +On this page, you can view: -Additional management interfaces are planned for the GitLab Agent. -[Provide more feedback in the related epic](https://gitlab.com/groups/gitlab-org/-/epics/4739). +- All the registered Agents for the current project. +- The connection status. +- The version of `agentk` installed on your cluster. +- The path to each Agent's configuration file. -## View Agent activity information +Furthermore, if you select one of the Agents on your list, you can view its +[activity information](#view-the-agents-activity-information). + +### View the Agent's activity information > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/277323) in GitLab 14.6. -Users with at least the [Developer](../../../permissions.md) can view the Agent's activity events. -The activity logs help you to identify problems and get the information you need for troubleshooting. -You can see events from a week before the current date. -To access an agent's activity: +The activity logs help you to identify problems and get the information +you need for troubleshooting. You can see events from a week before the +current date. To access an Agent's activity: + +1. In your Agent's repository, go to the Agents list as described [above](#view-your-agents). +1. Select the Agent you want to see the activity. + +The activity list includes: + +- Agent registration events: when a new token is **created**. +- Connection events: when an Agent is successfully **connected** to a cluster. + +Note that the connection status is logged when you connect an Agent for +the first time or after more than an hour of inactivity. -1. Go to your agent's configuration repository. -1. From the sidebar, select **Infrastructure > Kubernetes clusters**. +To check what else is planned for the Agent's UI and provide feedback, +see the [related epic](https://gitlab.com/groups/gitlab-org/-/epics/4739). + +### View vulnerabilities in cluster images **(ULTIMATE)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6346) in GitLab 14.8 [with a flag](../../../../administration/feature_flags.md) named `cluster_vulnerabilities`. Enabled by default. + +Users with at least the [Developer role](../../../permissions.md) +can view cluster vulnerabilities. You can access them through the [vulnerability report](../../../application_security/vulnerabilities/index.md) +or in your cluster's image through the following process: + +1. Configure [cluster image scanning](../../../application_security/cluster_image_scanning/index.md) + to your build process. +1. Go to your Agent's configuration repository. +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. 1. Select the **Agent** tab. -1. Select the agent you want to see the activity. +1. Select the Agent you want to see the vulnerabilities for. + + + +## Create multiple Agents + +You can create and install multiple Agents using the same process +documented above. Give each Agent's configuration file a unique name +and you're good to go. You can create multiple Agents, for example: + +- To reach your cluster from different projects. +- To connect multiple clusters to GitLab. + +## Update the Agent version + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340882) in GitLab 14.8, GitLab warns you on the Agent's list page to update the Agent version installed on your cluster. + +To update the Agent's version on your cluster, you need to re-run the [installation command](#install-the-agent-onto-the-cluster) +with a newer `--agent-version`. Make sure to specify the other required parameters: `--kas-address`, `--namespace`, and `--agent-token`. +You can find the available `agentk` versions in [the container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/1223205?sort=desc). -You can see the following events on the activity list: +If you don't have access to your Agent's token, you can retrieve it from your cluster: -- Agent registration: - - When a new token is **created**. -- Connection events: - - When an agent is successfully **connected** to a cluster. +1. On your computer, open the terminal and connect to your cluster. +1. To retrieve the namespace, run: -Note that the connection status is logged when you connect an agent for the first time -or after more than an hour of inactivity. + ```shell + kubectl get namespaces + ``` - +1. To retrieve the secret, run: + + ```shell + kubectl -n <namespace> get secrets + ``` + +1. To retrieve the token, run: + + ```shell + kubectl -n <namespace> get secret <secret-name> --template={{.data.token}} | base64 --decode + ``` + +## Example projects + +The following example projects can help you get started with the Agent. + +- [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent) +- This basic GitOps example deploys NGINX: [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) ## Upgrades and version compatibility @@ -178,7 +271,8 @@ A feature introduced in a given GitLab minor version might work with other `agen To make sure that it works, use at least the same `agentk` and `kas` minor version. For example, if your GitLab version is 14.2, use at least `agentk` 14.2 and `kas` 14.2. -We recommend upgrading your `kas` installations together with GitLab instances' upgrades, and to upgrade the `agentk` installations after upgrading GitLab. +We recommend upgrading your `kas` installations together with GitLab instances' upgrades, and to +[upgrade the `agentk` installations](#update-the-agent-version) after upgrading GitLab. The available `agentk` and `kas` versions can be found in [the container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/). diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index 22964fde395..a9d9fd1c13d 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -40,6 +40,9 @@ with Kubernetes resource definitions in YAML or JSON format. The Agent monitors each project you declare, and when the project changes, GitLab deploys the changes using the Agent. +WARNING: +When using separate GitLab projects for manifest files and configuration repository, the manifests project must be public. + To use multiple YAML files, specify a `paths` attribute in the `gitops.manifest_projects` section. ```yaml @@ -150,26 +153,19 @@ gitops: ## Authorize projects and groups to use an Agent -> - Group authorization [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. -> - Project authorization [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327850) in GitLab 14.4. - -If you use the same cluster across multiple projects, you can set up the [CI/CD Tunnel](ci_cd_tunnel.md) -to grant access to an Agent from one or more projects or groups. This way, all the authorized -projects can access the same Agent, which facilitates you to save resources and have a scalable setup. +With the [CI/CD Tunnel](ci_cd_tunnel.md), you can authorize [projects](#authorize-projects-to-use-an-agent) +and [groups](#authorize-groups-to-use-an-agent) to use an Agent. -When you authorize a project to use an agent through the [CI/CD Tunnel](ci_cd_tunnel.md), -the selected Kubernetes context is automatically injected into CI/CD jobs, allowing you to -run Kubernetes commands from your authorized projects' scripts. When you authorize a group, -all the projects that belong to that group can access the selected agent. - -An Agent can only authorize projects or groups in the same group hierarchy as the Agent's configuration -project. You can authorize up to 100 projects and 100 groups per Agent. +Then, you can reach your cluster from authorized projects and [run Kubernetes commands from GitLab CI/CD scripts](#run-kubectl-commands-using-the-cicd-tunnel) +in these projects. ### Authorize projects to use an Agent -To grant projects access to the Agent through the [CI/CD Tunnel](ci_cd_tunnel.md): +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327850) in GitLab 14.4. + +To grant projects access to the Agent through the CI/CD Tunnel: -1. Go to your Agent's configuration project. +1. Go to your Agent's configuration repository. 1. Edit the Agent's configuration file (`config.yaml`). 1. Add the `projects` attribute into `ci_access`. 1. Identify the project through its path: @@ -182,9 +178,11 @@ To grant projects access to the Agent through the [CI/CD Tunnel](ci_cd_tunnel.md ### Authorize groups to use an Agent +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. + To grant access to all projects within a group: -1. Go to your Agent's configuration project. +1. Go to your Agent's configuration repository. 1. Edit the Agent's configuration file (`config.yaml`). 1. Add the `groups` attribute into `ci_access`. 1. Identify the group or subgroup through its path: @@ -195,7 +193,64 @@ To grant access to all projects within a group: - id: path/to/group/subgroup ``` -### Use impersonation to restrict project and group access **(PREMIUM)** +## Run `kubectl` commands using the CI/CD Tunnel + +After you authorize your project or group to use the Agent, you need to +configure the project's `.gitlab-ci.yaml` file to access the Agent. +This makes it possible to deploy applications to your cluster and run +any Kubernetes-specific commands from the authorized project. + +First, configure your Agent: + +1. Go to your Agent's configuration repository. +1. Edit your Agent's `config.yaml` file authorizing the [project](#authorize-projects-to-use-an-agent) or [group](#authorize-groups-to-use-an-agent) you want to run Kubernetes commands from. + +Then, configure the other project: + +1. Go to the project where you want to run Kubernetes commands from. +1. Edit your project's `.gitlab-ci.yml` file. +1. Set your Agent's context in the first command of the script with the format `path/to/agent/repository:agent-name`. +1. Run Kubernetes commands. + +For example: + +```yaml + deploy: + image: + name: bitnami/kubectl:latest + entrypoint: [""] + script: + - kubectl config use-context path/to/agent/repository:agent-name + - kubectl get pods +``` + +When you use the Agent, KubeContexts are named as `path/to/agent/repository:agent-name`. + +To get the list of available contexts: + +1. Open your terminal and connect to your cluster. +1. Run `kubectl config get-contexts`. + +### `kubectl` commands not supported + +The commands `kubectl exec`, `kubectl cp`, and `kubectl attach` are not supported by the CI/CD tunnel. +Anything else that uses the same API endpoints does not work either as they use the deprecated +SPDY protocol. +We [plan to add support for these features](https://gitlab.com/gitlab-org/gitlab/-/issues/346248) +in a future version of GitLab. + +### `kubectl` requires TLS + +`kubectl` would never send credentials over an unencrypted connection. Self-managed users should ensure that their +GitLab instance is configured with TLS for the CI/CD tunnel feature to work. Trying to use it without TLS +would produce errors: + +```shell +$ kubectl get pods +error: You must be logged in to the server (the server has asked for the client to provide credentials) +``` + +## Use impersonation to restrict project and group access **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345014) in GitLab 14.5. @@ -211,11 +266,11 @@ You can impersonate: - The CI job that accesses the cluster. - A specific user or system account defined within the cluster. -#### Impersonate the Agent +### Impersonate the Agent The Agent is impersonated by default. You don't need to do anything to impersonate it. -#### Impersonate the CI job that accesses the cluster +### Impersonate the CI job that accesses the cluster To impersonate the CI job that accesses the cluster, add the `ci_job: {}` key-value under the `access_as` key. @@ -261,7 +316,7 @@ ci_access: ci_job: {} ``` -#### Impersonate a static identity +### Impersonate a static identity For the given CI/CD Tunnel connection, you can use a static identity for the impersonation. @@ -278,6 +333,13 @@ See the [official Kubernetes documentation for more details](https://kubernetes. ## Surface network security alerts from cluster to GitLab **(ULTIMATE)** +> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. + +WARNING: +Cilium integration is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) +for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 15.0. + The GitLab Agent provides an [integration with Cilium](index.md#kubernetes-network-security-alerts). To integrate, add a top-level `cilium` section to your `config.yml` file. Currently, the only configuration option is the Hubble relay address: diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md new file mode 100644 index 00000000000..2c9f98b7c45 --- /dev/null +++ b/doc/user/clusters/agent/troubleshooting.md @@ -0,0 +1,193 @@ +--- +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 +--- + +# Troubleshooting the GitLab Agent for Kubernetes + +When you are using the GitLab Agent for Kubernetes, you might experience issues you need to troubleshoot. + +You can start by viewing the service logs: + +```shell +kubectl logs -f -l=app=gitlab-agent -n gitlab-kubernetes-agent +``` + +If you are a GitLab administrator, you can also view the [GitLab Agent Server logs](../../../administration/clusters/kas.md#troubleshooting). + +## Transport: Error while dialing failed to WebSocket dial + +```json +{ + "level": "warn", + "time": "2020-11-04T10:14:39.368Z", + "msg": "GetConfiguration failed", + "error": "rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://gitlab-kas:443/-/kubernetes-agent\\\": dial tcp: lookup gitlab-kas on 10.60.0.10:53: no such host\"" +} +``` + +This error is shown if there are some connectivity issues between the address +specified as `kas-address`, and your Agent pod. To fix it, make sure that you +specified the `kas-address` correctly. + +```json +{ + "level": "error", + "time": "2021-06-25T21:15:45.335Z", + "msg": "Reverse tunnel", + "mod_name": "reverse_tunnel", + "error": "Connect(): rpc error: code = Unavailable desc = connection error: desc= \"transport: Error while dialing failed to WebSocket dial: expected handshake response status code 101 but got 301\"" +} +``` + +This error occurs if the `kas-address` doesn't include a trailing slash. To fix it, make sure that the +`wss` or `ws` URL ends with a trailing slash, such as `wss://GitLab.host.tld:443/-/kubernetes-agent/` +or `ws://GitLab.host.tld:80/-/kubernetes-agent/`. + +## ValidationError(Deployment.metadata) + +```json +{ + "level": "info", + "time": "2020-10-30T08:56:54.329Z", + "msg": "Synced", + "project_id": "root/kas-manifest001", + "resource_key": "apps/Deployment/kas-test001/nginx-deployment", + "sync_result": "error validating data: [ValidationError(Deployment.metadata): unknown field \"replicas\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"selector\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"template\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta]" +} +``` + +This error is shown if a manifest file is malformed, and Kubernetes can't +create specified objects. Make sure that your manifest files are valid. You +may try using them to create objects in Kubernetes directly for more troubleshooting. + +## Error while dialing failed to WebSocket dial: failed to send handshake request + +```json +{ + "level": "warn", + "time": "2020-10-30T09:50:51.173Z", + "msg": "GetConfiguration failed", + "error": "rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent\\\": net/http: HTTP/1.x transport connection broken: malformed HTTP response \\\"\\\\x00\\\\x00\\\\x06\\\\x04\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x05\\\\x00\\\\x00@\\\\x00\\\"\"" +} +``` + +This error is shown if you configured `wss` as `kas-address` on the agent side, +but KAS on the server side is not available via `wss`. To fix it, make sure the +same schemes are configured on both sides. + +It's not possible to set the `grpc` scheme due to the issue +[It is not possible to configure KAS to work with `grpc` without directly editing GitLab KAS deployment](https://gitlab.com/gitlab-org/gitlab/-/issues/276888). To use `grpc` while the +issue is in progress, directly edit the deployment with the +`kubectl edit deployment gitlab-kas` command, and change `--listen-websocket=true` to `--listen-websocket=false`. After running that command, you should be able to use +`grpc://gitlab-kas.<YOUR-NAMESPACE>:8150`. + +## Decompressor is not installed for grpc-encoding + +```json +{ + "level": "warn", + "time": "2020-11-05T05:25:46.916Z", + "msg": "GetConfiguration.Recv failed", + "error": "rpc error: code = Unimplemented desc = grpc: Decompressor is not installed for grpc-encoding \"gzip\"" +} +``` + +This error is shown if the version of the agent is newer that the version of KAS. +To fix it, make sure that both `agentk` and KAS use the same versions. + +## Certificate signed by unknown authority + +```json +{ + "level": "error", + "time": "2021-02-25T07:22:37.158Z", + "msg": "Reverse tunnel", + "mod_name": "reverse_tunnel", + "error": "Connect(): rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent/\\\": x509: certificate signed by unknown authority\"" +} +``` + +This error is shown if your GitLab instance is using a certificate signed by an internal CA that +is unknown to the agent. One approach to fixing it is to present the CA certificate file to the agent +via a Kubernetes `configmap` and mount the file in the agent `/etc/ssl/certs` directory from where it +will be picked up automatically. + +For example, if your internal CA certificate is `myCA.pem`: + +```plaintext +kubectl -n gitlab-kubernetes-agent create configmap ca-pemstore --from-file=myCA.pem +``` + +Then in `resources.yml`: + +```yaml + spec: + serviceAccountName: gitlab-kubernetes-agent + containers: + - name: agent + image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>" + args: + - --token-file=/config/token + - --kas-address + - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com. + # - wss://gitlab.host.tld:443/-/kubernetes-agent/ + # - wss://kas.gitlab.com # for GitLab.com users, use this KAS. + # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker. + volumeMounts: + - name: token-volume + mountPath: /config + - name: ca-pemstore-volume + mountPath: /etc/ssl/certs/myCA.pem + subPath: myCA.pem + volumes: + - name: token-volume + secret: + secretName: gitlab-kubernetes-agent-token + - name: ca-pemstore-volume + configMap: + name: ca-pemstore + items: + - key: myCA.pem + path: myCA.pem +``` + +Alternatively, you can mount the certificate file at a different location and include it using the +`--ca-cert-file` agent parameter: + +```yaml + containers: + - name: agent + image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>" + args: + - --ca-cert-file=/tmp/myCA.pem + - --token-file=/config/token + - --kas-address + - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com. + # - wss://gitlab.host.tld:443/-/kubernetes-agent/ + # - wss://kas.gitlab.com # for GitLab.com users, use this KAS. + # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker. + volumeMounts: + - name: token-volume + mountPath: /config + - name: ca-pemstore-volume + mountPath: /tmp/myCA.pem + subPath: myCA.pem +``` + +## Project not found + +```json +{ + "level ":"error ", + "time ":"2022-01-05T15:18:11.331Z", + "msg ":"GetObjectsToSynchronize.Recv failed ", + "mod_name ":"gitops ", + "error ":"rpc error: code = NotFound desc = project not found ", +} +``` + +This error is shown if the manifest project is not public. To fix it, +[make sure your manifest project is public](repository.md#synchronize-manifest-projects) or your manifest files +are stored in the Agent's configuration repository. |