summaryrefslogtreecommitdiff
path: root/doc/user/clusters
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user/clusters')
-rw-r--r--doc/user/clusters/agent/ci_cd_tunnel.md8
-rw-r--r--doc/user/clusters/agent/gitops.md36
-rw-r--r--doc/user/clusters/agent/index.md6
-rw-r--r--doc/user/clusters/agent/install/index.md182
-rw-r--r--doc/user/clusters/agent/repository.md8
-rw-r--r--doc/user/clusters/agent/troubleshooting.md44
6 files changed, 131 insertions, 153 deletions
diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md
index 73a8470e025..c15041f6b0d 100644
--- a/doc/user/clusters/agent/ci_cd_tunnel.md
+++ b/doc/user/clusters/agent/ci_cd_tunnel.md
@@ -8,6 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327409) in GitLab 14.1.
> - The pre-configured `KUBECONFIG` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2.
+> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) the `ci_access` attribute in GitLab 14.3.
> - The ability to authorize groups was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3.
> - [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.
@@ -69,6 +70,7 @@ To authorize the agent to access the GitLab project where you keep Kubernetes ma
```
- The Kubernetes projects must be in the same group hierarchy as the project where the agent's configuration is.
+ - You can install additional agents into the same cluster to accommodate additional hierarchies.
- You can authorize up to 100 projects.
All CI/CD jobs now include a `KUBECONFIG` with contexts for every shared agent connection.
@@ -91,9 +93,11 @@ To authorize the agent to access all of the GitLab projects in a group or subgro
```
- The Kubernetes projects must be in the same group hierarchy as the project where the agent's configuration is.
+ - You can install additional agents into the same cluster to accommodate additional hierarchies.
+ - All of the subgroups of an authorized group also have access to the same agent (without being specified individually).
- You can authorize up to 100 groups.
-All the projects that belong to the group are now authorized to access the agent.
+All the projects that belong to the group and its subgroups are now authorized to access the agent.
All CI/CD jobs now include a `KUBECONFIG` with contexts for every shared agent connection.
Choose the context to run `kubectl` commands from your CI/CD scripts.
@@ -123,7 +127,7 @@ Run `kubectl config get-contexts`.
When you deploy to an environment that has both a [certificate-based
cluster](../../infrastructure/clusters/index.md) (deprecated) and an agent connection:
-- The certificate-based cluster's context is called `gitlab-deploy`. This context
+- The certificate-based cluster's context is called `gitlab-deploy`. This context
is always selected by default.
- In GitLab 14.9 and later, agent contexts are included in the
`KUBECONFIG`. You can select them by using `kubectl config use-context
diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md
index 8f0e2255121..e99e3b00ec7 100644
--- a/doc/user/clusters/agent/gitops.md
+++ b/doc/user/clusters/agent/gitops.md
@@ -6,7 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Using a GitOps workflow for Kubernetes **(PREMIUM)**
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added.
With GitOps, you can manage containerized clusters and applications from a Git repository that:
@@ -18,6 +19,8 @@ By combining GitLab, Kubernetes, and GitOps, you can have:
- GitLab as the GitOps operator.
- Kubernetes as the automation and convergence system.
- GitLab CI/CD for Continuous Integration and the agent for Continuous Deployment.
+- Built-in automatic drift remediation.
+- Resource management with [server-side applies](https://kubernetes.io/docs/reference/using-api/server-side-apply/) for transparent multi-actor field management.
This diagram shows the repositories and main actors in a GitOps deployment:
@@ -90,6 +93,37 @@ gitops:
| `prune_propagation_policy` | The deletion propagation policy that [should be used for pruning](https://github.com/kubernetes/apimachinery/blob/44113beed5d39f1b261a12ec398a356e02358307/pkg/apis/meta/v1/types.go#L456-L470). Can be: `orphan`, `background`, or `foreground`. Default is `foreground`. |
| `inventory_policy` | Determines whether an inventory object can take over objects that belong to another inventory object or don't belong to any inventory object. This is done by determining if the apply/prune operation can go through for a resource based on comparison of the `inventory-id` value in the package and the `owning-inventory` annotation (`config.k8s.io/owning-inventory`) [in the live object](https://github.com/kubernetes-sigs/cli-utils/blob/d6968048dcd80b1c7b55d9e4f31fc25f71c9b490/pkg/inventory/policy.go#L12-L66). Can be: `must_match`, `adopt_if_no_inventory`, or `adopt_all`. Default is `must_match`. |
+## GitOps annotations
+
+The GitLab agent for Kubernetes has annotations you can use to:
+
+- **Sort resources**: Apply or delete resources in a specific order.
+- **Use apply-time mutation**: Dynamically substitute fields from one resource configuration to another.
+
+The agent has [default sorting](https://github.com/kubernetes-sigs/cli-utils/blob/d7d63f4b62897f584ca9e02b6faf4d2f327a9b09/pkg/ordering/sort.go#L74),
+but with annotations, you can fine-tune the order and apply time-value injection.
+
+To provide the GitOps functionality, the GitLab agent for Kubernetes uses the [`cli-utils` library](https://github.com/kubernetes-sigs/cli-utils/),
+a Kubernetes SIG project. You can read more about the available annotations in the [`cli-utils` documentation](https://github.com/kubernetes-sigs/cli-utils/blob/master/README.md#apply-sort-ordering).
+
+- [Learn more about apply sort ordering](https://github.com/kubernetes-sigs/cli-utils#apply-sort-ordering).
+- [Learn more about apply-time mutation](https://github.com/kubernetes-sigs/cli-utils#apply-time-mutation).
+
+## Automatic drift remediation
+
+Drift happens when the current configuration of an infrastructure resource differs from its expected configuration.
+Typically, this is caused by manually editing resources directly through the service that created the resource. Minimizing the
+risk of drift helps to ensure configuration consistency and successful operations.
+
+In GitLab, the agent for Kubernetes regularly compares the expected state from the `git` repository with
+the known state from the `cluster`. Deviations from the `git` state are fixed at every check. These checks
+happen automatically every 5 minutes. They are not configurable.
+
+The agent uses [server-side applies](https://kubernetes.io/docs/reference/using-api/server-side-apply/).
+As a result, every field in a resource can have different managers. Only fields managed by `git`
+are checked for drift. This facilitates the use of in-cluster controllers to modify resources like
+[Horizontal Pod Autoscalers](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/).
+
## Additional resources
The following documentation and examples can help you get started with a GitOps workflow.
diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md
index a8ad19df2e1..bab3f3137fe 100644
--- a/doc/user/clusters/agent/index.md
+++ b/doc/user/clusters/agent/index.md
@@ -9,12 +9,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w
> - [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.
> - 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.
+> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the GitLab agent became available on GitLab.com.
> - [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.
You can connect your Kubernetes cluster with GitLab to deploy, manage,
-and monitor your cloud-native solutions.
+and monitor your cloud-native solutions.
To connect a Kubernetes cluster to GitLab, you must first [install an agent in your cluster](install/index.md).
@@ -43,8 +43,8 @@ This workflow is considered push-based, because GitLab is pushing requests from
GitLab supports the following Kubernetes versions. You can upgrade your
Kubernetes version to a supported version at any time:
+- 1.21 (support ends on November 22, 2022)
- 1.20 (support ends on July 22, 2022)
-- 1.19 (support ends on February 22, 2022)
GitLab supports at least two production-ready Kubernetes minor
versions at any given time. GitLab regularly reviews the supported versions and
diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md
index fca80a4a291..e76ef9e827d 100644
--- a/doc/user/clusters/agent/install/index.md
+++ b/doc/user/clusters/agent/install/index.md
@@ -39,6 +39,9 @@ To install the agent in your cluster:
You must register an agent with GitLab.
+FLAG:
+In GitLab 14.10, a [flag](../../../../administration/feature_flags.md) named `certificate_based_clusters` changed the **Actions** menu to focus on the agent rather than certificates. The flag is [enabled on GitLab.com and self-managed](https://gitlab.com/groups/gitlab-org/configure/-/epics/8).
+
Prerequisites:
- For a [GitLab CI/CD workflow](../ci_cd_tunnel.md), ensure that
@@ -48,8 +51,7 @@ To register an agent with GitLab:
1. On the top bar, select **Menu > Projects** and find your project.
1. From the left sidebar, select **Infrastructure > Kubernetes clusters**.
-1. Select **Actions**.
-1. From the **Select an agent** dropdown list:
+1. Select **Connect a cluster (agent)**.
- If you want to create a configuration with CI/CD defaults, type a name for the agent.
- If you already have an [agent configuration file](#create-an-agent-configuration-file), select it from the list.
1. Select **Register an agent**.
@@ -61,11 +63,12 @@ To register an agent with GitLab:
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the agent configuration file can be added to multiple directories (or subdirectories) of the repository.
> - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3.
-You can use an agent configuration file to specify details about your implementation.
-Creating a file is optional but is needed if:
+The agent is configured through a configuration file. This file is optional. Without a configuration file, you can still use the CI/CD workflow in the project where the agent is registered.
+
+You need a configuration file if:
-- You use [a GitOps workflow](../gitops.md#gitops-configuration-reference) and you want a more advanced configuration.
-- You use a GitLab CI/CD workflow. In that workflow, you must [authorize the agent](../ci_cd_tunnel.md#authorize-the-agent).
+- You want to use [a GitOps workflow](../gitops.md#gitops-configuration-reference).
+- You want to authorize a different project to use the agent for a [GitLab CI/CD workflow](../ci_cd_tunnel.md#authorize-the-agent).
To create an agent configuration file, go to the GitLab project. In the repository, create a file called `config.yaml` at this path:
@@ -79,104 +82,62 @@ To create an agent configuration file, go to the GitLab project. In the reposito
- For a GitOps workflow, view [the configuration reference](../gitops.md#gitops-configuration-reference) for details.
- For a GitLab CI/CD workflow, you can leave the file blank for now.
-The agent bootstraps with the GitLab installation URL and an access token,
-and you provide the rest of the configuration in your repository, following
-Infrastructure as Code (IaaC) best practices.
-
### Install the agent in the cluster
-To connect your cluster to GitLab, install the registered agent
-in your cluster. To install it, you can use either:
+> Introduced in GitLab 14.10, GitLab recommends using Helm to install the agent.
-- [The one-liner installation method](#one-liner-installation).
-- [The advanced installation method](#advanced-installation).
+To connect your cluster to GitLab, install the registered agent
+in your cluster. You can either:
-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.
+- [Install the agent with Helm](#install-the-agent-with-helm).
+- Or, follow the [advanced installation method](#advanced-installation-method).
-#### One-liner installation
+If you do not know which one to choose, we recommend starting with Helm.
-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).
+#### Install the agent with Helm
-To install the agent on your cluster using the one-liner installation:
+To install the agent on your cluster using Helm:
+1. [Install Helm](https://helm.sh/docs/intro/install/)
1. In your computer, open a terminal and [connect to your cluster](https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster/).
-1. Run the command you copied when registering your cluster in the previous step.
+1. Run the command you copied when registering your agent with GitLab.
-Optionally, you can [customize the one-liner installation command](#customize-the-one-liner-installation).
+Optionally, you can [customize the Helm installation](#customize-the-helm-installation).
-##### Customize the one-liner installation
+##### Customize the Helm installation
-By default, the one-liner command generated by GitLab:
+By default, the Helm installation command generated by GitLab:
-- Creates a namespace for the deployment (`gitlab-agent`).
-- 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 access token.
+- Creates a namespace `gitlab-agent` for the deployment (`--namespace gitlab-agent`). You can skip creating the namespace by omitting the `--create-namespace` flag.
+- Sets up a service account for the agent with `cluster-admin` rights. You can:
+ - Skip creating the service account by adding `--set serviceAccount.create=false` to the `helm install` command. In this case, you must set `serviceAccount.name` to a pre-existing service account.
+ - Skip creating the RBAC permissions by adding `--set rbac.create=false` to the `helm install` command. In this case, you must bring your own RBAC permissions for the agent. Otherwise, it has no permissions at all.
+- Creates a `Secret` resource for the agent's access token. To instead bring your own secret with a token, omit the token (`--set token=...`) and instead use `--set config.secretName=<your secret name>`.
- Creates a `Deployment` resource for the `agentk` pod.
-You can edit these parameters to customize the one-liner installation command.
-To view all available options, open a terminal and run this command:
-
-```shell
-docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help
-
-Usage:
- cli generate [flags]
-
-Flags:
- --agent-token string Access token registered for agent
- --agent-version string Version of the agentk image to use (default "v14.8.1")
- -h, --help help for generate
- --kas-address string GitLab agent server for Kubernetes address
- --name-prefix string The prefix to use for names of Kubernetes objects
- --namespace string Kubernetes namespace to create resources in (default "gitlab-agent")
- --no-rbac Do not include corresponding Roles and RoleBindings for the agent service account
-```
-
-WARNING:
-Use `--agent-version stable` to refer to the latest stable
-release at the time when the command runs. For production, however,
-you should explicitly specify a matching version.
-
-#### Advanced installation
-
-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
-
-You own your cluster and can grant GitLab the permissions you want.
-By default, however, the generated manifests provide `cluster-admin` rights to the agent.
-
-You can restrict the agent's access rights by 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 restrict permissions:
+To see the full list of customizations available, see the Helm chart's [default values file](https://gitlab.com/gitlab-org/charts/gitlab-agent/-/blob/main/values.yaml).
-1. Copy the `cluster` directory.
-1. Edit the `kustomization.yaml` and `components/*` files based on your requirements.
-1. Run `kustomize build <your copied directory> | kubectl apply -f -` to apply your configuration.
+#### Advanced installation method
-#### Update the advanced installation base layer
-
-Now you can update from the upstream package by using `kpt pkg update gitlab-agent --strategy resource-merge`.
-When the advanced installation setup changes, you will not need to change your custom overlays.
+GitLab also provides a [KPT package for the agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent). This method provides greater flexibility, but is only recommended for advanced users.
## Install multiple agents in your cluster
-For total separation between teams, you might need to run multiple `agentk` instances in your cluster.
-You might want multiple agents so you can restrict RBAC for every `agentk` deployment.
+To install a second agent in your cluster, you can follow the [previous steps](#register-the-agent-with-gitlab) a second time. To avoid resource name collisions within the cluster, you must either:
+
+- Use a different release name for the agent, e.g. `second-gitlab-agent`:
-To install multiple agents, follow the
-[advanced installation steps](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent)
-a second time and:
+ ```shell
+ helm upgrade --install second-gitlab-agent gitlab/gitlab-agent ...
+ ```
-1. Change the agent name and create a new configuration file.
-1. Register the new agent. You receive a new access token. Each token should be used only with one agent.
-1. Change the namespace or prefix you use for the installation.
+- Or, install the agent in a different namespace, e.g. `different-namespace`:
-You should also change the RBAC for the installed `agentk`.
+ ```shell
+ helm upgrade --install gitlab-agent gitlab/gitlab-agent \
+ --namespace different-namespace \
+ ...
+ ```
## Example projects
@@ -187,50 +148,37 @@ The following example projects can help you get started with the agent.
- [Auto DevOps setup that uses the CI/CD workflow](https://gitlab.com/gitlab-examples/ops/gitops-demo/hello-world-service)
- [Cluster management project template example that uses the CI/CD workflow](https://gitlab.com/gitlab-examples/ops/gitops-demo/cluster-management)
-## Upgrades and version compatibility
-
-The agent has two major components: `agentk` and `kas`.
-GitLab provides `kas` installers built into the various GitLab installation methods.
-The required `kas` version corresponds to the GitLab `major.minor` (X.Y) versions.
-
-At the same time, `agentk` and `kas` can differ by 1 minor version in either direction. For example,
-`agentk` 14.4 supports `kas` 14.3, 14.4, and 14.5 (regardless of the patch).
+## Updates and version compatibility
-A feature introduced in a given GitLab minor version might work with other `agentk` or `kas` versions.
-To ensure 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](#update-the-agent-version) after upgrading GitLab.
+> [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.
-The available `agentk` and `kas` versions are available in
-[the Container Registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/).
+For the best experience, the version of the agent installed in your cluster should match the GitLab major and minor version. The previous minor version is also supported. For example, if your GitLab version is v14.9.4 (major version 14, minor version 9), then versions v14.9.0 and v14.9.1 of the agent are ideal, but any v14.8.x version of the agent is also supported. See [this page](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/releases) of releases of the GitLab agent.
### 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, re-run the [installation command](#install-the-agent-in-the-cluster)
-with a newer `--agent-version`. Make sure to specify the other required parameters: `--kas-address`, `--namespace`, and `--agent-token`.
-The available `agentk` versions are in [the Container Registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/1223205?sort=desc).
+To update the agent to the latest version, you can run:
-If you don't have access to your agent's access token, you can retrieve it from your cluster:
-
-1. Open a terminal and connect to your cluster.
-1. To retrieve the namespace, run:
+```shell
+helm repo update
+helm upgrade --install gitlab-agent gitlab/gitlab-agent \
+ --namespace gitlab-agent \
+ --reuse-values
+```
- ```shell
- kubectl get namespaces
- ```
+To set a specific version, you can override the `image.tag` value. For example, to install version `v14.9.1`, run:
-1. To retrieve the secret, run:
+```shell
+helm upgrade gitlab-agent gitlab/gitlab-agent \
+ --namespace gitlab-agent \
+ --reuse-values \
+ --set image.tag=v14.9.1
+```
- ```shell
- kubectl -n <namespace> get secrets
- ```
+## Uninstall the agent
-1. To retrieve the access token, run:
+If you [installed the agent with Helm](#install-the-agent-with-helm), then you can also uninstall with Helm. For example, if the release and namespace are both called `gitlab-agent`, then you can uninstall the agent using the following command:
- ```shell
- kubectl -n <namespace> get secret <secret-name> --template={{.data.token}} | base64 --decode
- ```
+```shell
+helm uninstall gitlab-agent \
+ --namespace gitlab-agent
+```
diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md
index 3f743d34e0a..2087c804e26 100644
--- a/doc/user/clusters/agent/repository.md
+++ b/doc/user/clusters/agent/repository.md
@@ -6,11 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Working with the agent for Kubernetes **(FREE)**
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7.
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the GitLab agent became available on GitLab.com.
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) the `ci_access` attribute in GitLab 14.3.
-> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added.
+Use the following tasks when working with the agent for Kubernetes.
## View your agents
@@ -171,7 +167,7 @@ To remove an agent from the UI:
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 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477)
in GitLab 15.0.
The agent for Kubernetes also provides an integration with Cilium. This integration provides a simple way to
diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md
index a5e568837ad..c5c7e46c078 100644
--- a/doc/user/clusters/agent/troubleshooting.md
+++ b/doc/user/clusters/agent/troubleshooting.md
@@ -27,9 +27,8 @@ If you are a GitLab administrator, you can also view the [GitLab agent server lo
}
```
-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.
+This error occurs when there are connectivity issues between the `kas-address`
+and your agent pod. To fix this issue, make sure the `kas-address` is accurate.
```json
{
@@ -41,8 +40,8 @@ specified the `kas-address` correctly.
}
```
-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/`
+This error occurs when the `kas-address` doesn't include a trailing slash. To fix this issue, make sure that the
+`wss` or `ws` URL ends with a trailing slash, like `wss://GitLab.host.tld:443/-/kubernetes-agent/`
or `ws://GitLab.host.tld:80/-/kubernetes-agent/`.
## ValidationError(Deployment.metadata)
@@ -58,9 +57,10 @@ or `ws://GitLab.host.tld:80/-/kubernetes-agent/`.
}
```
-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.
+This error occurs when a manifest file is malformed and Kubernetes can't
+create the specified objects. Make sure that your manifest files are valid.
+
+For additional troubleshooting, try to use the manifest files to create objects in Kubernetes directly.
## Error while dialing failed to WebSocket dial: failed to send handshake request
@@ -73,16 +73,10 @@ may try using them to create objects in Kubernetes directly for more troubleshoo
}
```
-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
+This error occurs when you configured `wss` as `kas-address` on the agent side,
+but the agent server is not available at `wss`. To fix this issue, 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
@@ -94,8 +88,8 @@ issue is in progress, directly edit the deployment with the
}
```
-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.
+This error occurs when the version of the agent is newer that the version of the agent server (KAS).
+To fix it, make sure that both `agentk` and the agent server are the same version.
## Certificate signed by unknown authority
@@ -109,9 +103,11 @@ To fix it, make sure that both `agentk` and KAS use the same versions.
}
```
-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
+This error occurs when your GitLab instance is using a certificate signed by an internal
+certificate authority that is unknown to the agent.
+
+To fix this issue, you can present the CA certificate file to the agent
+by using 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`:
@@ -153,7 +149,7 @@ Then in `resources.yml`:
path: myCA.pem
```
-Alternatively, you can mount the certificate file at a different location and include it using the
+Alternatively, you can mount the certificate file at a different location and specify it for the
`--ca-cert-file` agent parameter:
```yaml
@@ -188,5 +184,5 @@ Alternatively, you can mount the certificate file at a different location and in
}
```
-This error is shown if the manifest project is not public. To fix it, make sure your manifest project is public or your manifest files
-are stored in the agent's configuration repository.
+This error occurs when the project where you keep your manifests is not public. To fix it, make sure your project is public or your manifest files
+are stored in the repository where the agent is configured.
View Lorry Controller Status