diff options
Diffstat (limited to 'doc/user/clusters/agent/index.md')
| -rw-r--r-- | doc/user/clusters/agent/index.md | 208 |
1 files changed, 53 insertions, 155 deletions
diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 77b9dbb1c7e..31accfdd9e4 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -4,13 +4,11 @@ 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 Kubernetes Agent **(PREMIUM SELF)** +# GitLab Kubernetes Agent **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. > - [In GitLab 13.10](https://gitlab.com/gitlab-org/gitlab/-/issues/300960), KAS became available on GitLab.com under `wss://kas.gitlab.com` through an Early Adopter Program. - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - Introduced in GitLab 13.11, the GitLab Kubernetes Agent became available to every project on GitLab.com. The [GitLab Kubernetes Agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) is an active in-cluster component for solving GitLab and Kubernetes integration @@ -68,7 +66,7 @@ For more details, please refer to our [full architecture documentation](https:// The setup process involves a few steps to enable GitOps deployments: -1. [Install the Agent server](#install-the-kubernetes-agent-server) for your GitLab instance. +1. [Set up the Kubernetes Agent Server](#set-up-the-kubernetes-agent-server) for your GitLab instance. 1. [Define a configuration repository](#define-a-configuration-repository). 1. [Create an Agent record in GitLab](#create-an-agent-record-in-gitlab). 1. [Generate and copy a Secret token used to connect to the Agent](#create-the-kubernetes-secret). @@ -83,7 +81,7 @@ neither stable nor versioned yet. For this reason, GitLab only guarantees compat between corresponding major.minor (X.Y) versions of GitLab and its cluster side component, `agentk`. -Upgrade your agent installations together with GitLab upgrades. To decide which version of `agentk`to install follow: +Upgrade your agent installations together with GitLab upgrades. To decide which version of `agentk` to install follow: 1. Open the [`GITLAB_KAS_VERSION`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/GITLAB_KAS_VERSION) file from the GitLab Repository, which contains the latest `agentk` version associated with the `master` branch. 1. Change the `master` branch and select the Git tag associated with your version. For instance, you could change it to GitLab [v13.5.3-ee release](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.5.3-ee/GITLAB_KAS_VERSION) @@ -91,88 +89,14 @@ Upgrade your agent installations together with GitLab upgrades. To decide which The available `agentk` and `kas` versions can be found in [the container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/). -### Install the Kubernetes Agent Server **(FREE SELF)** - -[Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.10, -the GitLab Kubernetes Agent Server (KAS) is available on GitLab.com under `wss://kas.gitlab.com`. -If you are a GitLab.com user, skip this step and directly -[set up the configuration repository](#define-a-configuration-repository) -for your agent. - -The GitLab Kubernetes Agent Server (KAS) can be installed through Omnibus GitLab or -through the GitLab Helm Chart. If you don't already have -GitLab installed, please refer to our [installation -documentation](https://docs.gitlab.com/ee/install/README.html). -You can install the KAS within GitLab as explained below according to your GitLab installation method. -You can also opt to use an [external KAS](#use-an-external-kas-installation). - -#### Install KAS with Omnibus - -For [Omnibus](https://docs.gitlab.com/omnibus/) package installations: - -1. Edit `/etc/gitlab/gitlab.rb` to enable the Kubernetes Agent Server: - - ```plaintext - gitlab_kas['enable'] = true - ``` - -1. [Reconfigure GitLab](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). - -To configure any additional options related to GitLab Kubernetes Agent Server, -refer to the **Enable GitLab KAS** section of the -[`gitlab.rb.template`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/files/gitlab-config-template/gitlab.rb.template). - -#### Install KAS with GitLab Helm Chart - -For GitLab [Helm Chart](https://gitlab.com/gitlab-org/charts/gitlab) installations, consider the following Helm v3 example. -If you're using Helm v2, you must modify this example. See our [notes regarding deploy with Helm](https://docs.gitlab.com/charts/installation/deployment.html#deploy-using-helm). - -You must set `global.kas.enabled=true` for the KAS to be properly installed and configured: - -```shell -helm repo add gitlab https://charts.gitlab.io/ -helm repo update -helm upgrade --install gitlab gitlab/gitlab \ - --timeout 600s \ - --set global.hosts.domain=<YOUR_DOMAIN> \ - --set global.hosts.externalIP=<YOUR_IP> \ - --set certmanager-issuer.email=<YOUR_EMAIL> \ - --set global.kas.enabled=true -``` - -To specify other options related to the KAS sub-chart, create a `gitlab.kas` sub-section -of your `values.yaml` file: - -```shell -gitlab: - kas: - # put your KAS custom options here -``` - -For details, read [Using the GitLab-KAS chart](https://docs.gitlab.com/charts/charts/gitlab/kas/). - -#### Use an external KAS installation - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299850) in GitLab 13.10. +### Set up the Kubernetes Agent Server -Besides installing KAS with GitLab, you can opt to configure GitLab to use an external KAS. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10, the GitLab Kubernetes Agent Server (KAS) became available on GitLab.com under `wss://kas.gitlab.com`. -For GitLab instances installed through the GitLab Helm Chart, see [how to configure your external KAS](https://docs.gitlab.com/charts/charts/globals.html#external-kas). +To use the KAS: -For GitLab instances installed through Omnibus packages: - -1. Edit `/etc/gitlab/gitlab.rb` adding the paths to your external KAS: - - ```ruby - gitlab_kas['enable'] = false - gitlab_kas['api_secret_key'] = 'Your shared secret between GitLab and KAS' - - gitlab_rails['gitlab_kas_enabled'] = true - gitlab_rails['gitlab_kas_external_url'] = 'wss://kas.gitlab.example.com' # User-facing URL for the in-cluster agentk - gitlab_rails['gitlab_kas_internal_url'] = 'grpc://kas.internal.gitlab.example.com' # Internal URL for the GitLab backend - ``` - -1. [Reconfigure GitLab](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). +- If you are a self-managed user, follow the instructions to [install the Kubernetes Agent Server](../../../administration/clusters/kas.md). +- If you are a GitLab.com user, when you [set up the configuration repository](#define-a-configuration-repository) for your agent, use `wss://kas.gitlab.com` as the `--kas-address`. ### Define a configuration repository @@ -200,23 +124,9 @@ documentation on the [Kubernetes Agent configuration repository](repository.md). ### Create an Agent record in GitLab -Next, create an GitLab Rails Agent record so the Agent can associate itself with +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. You can create an Agent record either: - -- Through the Rails console: - - ```ruby - project = ::Project.find_by_full_path("path-to/your-configuration-project") - # agent-name should be the same as specified above in the config.yaml - agent = ::Clusters::Agent.create(name: "<agent-name>", project: project) - token = ::Clusters::AgentToken.create(agent: agent) - token.token # this will print out the token you need to use on the next step - ``` - - For full details, read [Starting a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session). - -- Through GraphQL: **(PREMIUM SELF)** +the Agent in subsequent steps. You can create an Agent record with GraphQL: ```graphql mutation createAgent { @@ -257,23 +167,35 @@ the Agent in subsequent steps. You can create an Agent record either: ### Install the Agent into the cluster -Next, install the in-cluster component of the Agent. +To install the in-cluster component of the Agent, first you need to define a namespace. To create a new namespace, +for example, `gitlab-kubernetes-agent`, run: -NOTE: -For GitLab.com users, the KAS is available at `wss://kas.gitlab.com`. +```shell +kubectl create namespace gitlab-kubernetes-agent +``` -#### One-liner installation +To perform a one-liner installation, run the command below. Make sure to replace: -Replace the value of `agent-token` below with the token received from the previous step. Also, replace `kas-address` with the configured access of the Kubernetes Agent Server: +- `your-agent-token` with the token received from the previous step. +- `gitlab-kubernetes-agent` with the namespace you defined in the previous step. +- `wss://kas.gitlab.example.com` with the configured access of the Kubernetes Agent Server (KAS). For GitLab.com users, the KAS is available under `wss://kas.gitlab.com`. ```shell -docker run --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:latest generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version latest | kubectl apply -f - +docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version stable --namespace gitlab-kubernetes-agent | kubectl apply -f - ``` +Set `--agent-version` to the latest released patch version matching your +GitLab installation's major and minor versions. For example, if you have +GitLab v13.9.0, set `--agent-version=v13.9.1`. + +WARNING: +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. + To find out the various options the above Docker container supports, run: ```shell -docker run --rm -it registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:latest generate --help +docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help ``` #### Advanced installation @@ -286,17 +208,11 @@ Otherwise, you can follow below for fully manual, detailed installation steps. After generating the token, you must apply it to the Kubernetes cluster. -1. If you haven't previously defined or created a namespace, run the following command: - - ```shell - kubectl create namespace <YOUR-DESIRED-NAMESPACE> - ``` +To create your Secret, run: -1. Run the following command to create your Secret: - - ```shell - kubectl create secret generic -n <YOUR-DESIRED-NAMESPACE> gitlab-agent-token --from-literal=token='YOUR_AGENT_TOKEN' - ``` +```shell +kubectl create secret generic -n <YOUR_NAMESPACE> gitlab-agent-token --from-literal=token='YOUR_AGENT_TOKEN' +``` The following example file contains the Kubernetes resources required for the Agent to be installed. You can modify this @@ -314,7 +230,7 @@ example [`resources.yml` file](#example-resourcesyml-file) in the following ways `kas-address`, where `GitLab.host.tld` is your GitLab hostname. - When using the sub-chart, specify the `ws` scheme (such as `ws://kas.host.tld:80`) to use an unencrypted WebSockets connection. - When using the Omnibus GitLab, specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent`). + When using the Omnibus GitLab, specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent/`). - Specify the `grpc` scheme if both Agent and Server are installed in one cluster. In this case, you may specify `kas-address` value as `grpc://gitlab-kas.<your-namespace>:5005`) to use gRPC directly, where `gitlab-kas` @@ -326,7 +242,7 @@ example [`resources.yml` file](#example-resourcesyml-file) in the following ways - 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 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. + - 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 secret name in the `secretName:` section. @@ -370,7 +286,8 @@ spec: serviceAccountName: gitlab-agent containers: - name: agent - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:latest" + # Make sure to specify a matching version for production + image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:stable" args: - --token-file=/config/token - --kas-address @@ -549,7 +466,7 @@ cilium: ## Management interfaces Users with at least the [Developer](../../permissions.md) can access the user interface -for the GitLab Kubernetes agent at **Operations > Kubernetes** and selecting the +for the GitLab Kubernetes agent at **Operations > Kubernetes** under the **GitLab Agent managed clusters** tab. This page lists all registered agents for the current project, and the configuration directory for each agent: @@ -561,36 +478,17 @@ Additional management interfaces are planned for the GitLab Kubernetes Agent. ## Troubleshooting If you face any issues while using GitLab Kubernetes Agent, you can read the -service logs with the following commands: - -- KAS pod logs - Tail these logs with the - `kubectl logs -f -l=app=kas -n <YOUR-GITLAB-NAMESPACE>` - command. In Omnibus GitLab, the logs reside in `/var/log/gitlab/gitlab-kas/`. -- Agent pod logs - Tail these logs with the - `kubectl logs -f -l=app=gitlab-agent -n <YOUR-DESIRED-NAMESPACE>` command. - -### KAS logs - GitOps: failed to get project info - -```plaintext -{"level":"warn","time":"2020-10-30T08:37:26.123Z","msg":"GitOps: failed to get project info","agent_id":4,"project_id":"root/kas-manifest001","error":"error kind: 0; status: 404"} -``` - -This error is shown if the specified manifest project `root/kas-manifest001` -doesn't exist, or if a project is private. To fix it, make sure the project exists -and its visibility is [set to public](../../../public_access/public_access.md). +service logs with the following command -### KAS logs - Configuration file not found - -```plaintext -time="2020-10-29T04:44:14Z" level=warning msg="Config: failed to fetch" agent_id=2 error="configuration file not found: \".gitlab/agents/test-agent/config.yaml\ +```shell +kubectl logs -f -l=app=gitlab-agent -n <YOUR-DESIRED-NAMESPACE> ``` -This error is shown if the path to the configuration project was specified incorrectly, -or if the path to `config.yaml` inside the project is not valid. +GitLab administrators can additionally view the [Kubernetes Agent Server logs](../../../administration/clusters/kas.md#troubleshooting). ### Agent logs - Transport: Error while dialing failed to WebSocket dial -```plaintext +```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\""} ``` @@ -610,7 +508,7 @@ may try using them to create objects in Kubernetes directly for more troubleshoo ### Agent logs - Error while dialing failed to WebSocket dial: failed to send handshake request -```plaintext +```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\\\"\""} ``` @@ -626,7 +524,7 @@ issue is in progress, directly edit the deployment with the ### Agent logs - Decompressor is not installed for grpc-encoding -```plaintext +```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\""} ``` @@ -635,7 +533,7 @@ To fix it, make sure that both `agentk` and KAS use the same versions. ### Agent logs - Certificate signed by unknown authority -```plaintext +```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\""} ``` @@ -652,17 +550,17 @@ kubectl -n gitlab-agent create configmap ca-pemstore --from-file=myCA.pem Then in `resources.yml`: -```plaintext +```yaml spec: serviceAccountName: gitlab-agent containers: - name: agent - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:latest" + image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>" args: - --token-file=/config/token - --kas-address - wss://kas.host.tld:443 # change this line for the one below if using Omnibus GitLab - # - wss://gitlab.host.tld:443/-/kubernetes-agent + # - wss://gitlab.host.tld:443/-/kubernetes-agent/ volumeMounts: - name: token-volume mountPath: /config @@ -684,16 +582,16 @@ Then in `resources.yml`: Alternatively, you can mount the certificate file at a different location and include it using the `--ca-cert-file` agent parameter: -```plaintext +```yaml containers: - name: agent - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:latest" + 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 # change this line for the one below if using Omnibus GitLab - # - wss://gitlab.host.tld:443/-/kubernetes-agent + # - wss://gitlab.host.tld:443/-/kubernetes-agent/ volumeMounts: - name: token-volume mountPath: /config |