diff options
Diffstat (limited to 'doc/user/clusters')
| -rw-r--r-- | doc/user/clusters/agent/ci_cd_tunnel.md | 7 | ||||
| -rw-r--r-- | doc/user/clusters/agent/index.md | 27 | ||||
| -rw-r--r-- | doc/user/clusters/agent/install/index.md | 258 | ||||
| -rw-r--r-- | doc/user/clusters/agent/repository.md | 3 | ||||
| -rw-r--r-- | doc/user/clusters/applications.md | 6 |
5 files changed, 51 insertions, 250 deletions
diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md index 93768164df2..f1c49b87383 100644 --- a/doc/user/clusters/agent/ci_cd_tunnel.md +++ b/doc/user/clusters/agent/ci_cd_tunnel.md @@ -19,11 +19,8 @@ Only CI/CD jobs set in the configuration project can access one of the configure ## Prerequisites -- A running [`kas` instance](install/index.md#set-up-the-agent-server). -- A [configuration repository](install/index.md#define-a-configuration-repository) with an agent config file - installed (`.gitlab/agents/<agent-name>/config.yaml`). -- A [registered agent](install/index.md#register-an-agent-with-gitlab). -- The agent [installed in the cluster](install/index.md#install-the-agent-into-the-cluster). +- An existing Kubernetes cluster. +- An agent [installed on your cluster](install/index.md#install-the-agent-into-the-cluster). ## Use the CI/CD Tunnel to run Kubernetes commands from GitLab CI/CD diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index c950a4f0dc0..a235c0ef6f8 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -18,10 +18,6 @@ is an active in-cluster component for connecting Kubernetes clusters to GitLab s The Agent is installed into the cluster through code, providing you with a fast, safe, stable, and scalable solution. -INFO: -Get Network Security Alerts in GitLab by upgrading to Ultimate. -[Try a free 30-day trial now](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-cluster-agent-docs). - With GitOps, you can manage containerized clusters and applications from a Git repository that: - Is the single source of truth of your system. @@ -136,7 +132,22 @@ with the following differences: ## Remove an agent -1. Get the `<cluster-agent-id>` and the `<cluster-agent-token-id>` from a query in the interactive GraphQL explorer. +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). + +### Remove an agent through the GitLab UI + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323055) in GitLab 14.7. + +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**. + +### 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. @@ -157,7 +168,7 @@ For self-managed GitLab instances, go to `https://gitlab.example.com/-/graphql-e } ``` -1. Remove an Agent record with GraphQL by deleting the `clusterAgent` and the `clusterAgentToken`. +1. Remove an agent record with GraphQL by deleting the `clusterAgentToken`. ```graphql mutation deleteAgent { @@ -190,6 +201,10 @@ For self-managed GitLab instances, go to `https://gitlab.example.com/-/graphql-e 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 diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index cf8467a8d28..b2372789284 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -10,42 +10,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w To get started with the Agent, install it in your cluster. -Pre-requisites: +## Prerequisites **(SELF)** - An existing Kubernetes cluster. -- An account on GitLab. +- 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: -1. [Set up the Agent Server](#set-up-the-agent-server) for your GitLab instance. 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. [Generate and copy a Secret token used to connect to the agent](#create-the-kubernetes-secret). -1. [Create manifest files](#create-manifest-files). <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. -### Set up the Agent Server - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10, the GitLab Agent Server (KAS) became available on GitLab.com under `wss://kas.gitlab.com`. - -To use the KAS: - -- If you are a self-managed user, follow the instructions to [install the 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 > - [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: - -1. A GitLab repository to hold the configuration file. -1. Install the Agent in a cluster. +To create an agent, you need a GitLab repository to hold the configuration file. After installed, when you update the configuration file, GitLab transmits the information to the cluster automatically without downtime. @@ -62,7 +47,7 @@ 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. It doesn't do anything so far, but, later on, you can use this +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: - Groups and projects that can access the agent via the [CI/CD Tunnel](../ci_cd_tunnel.md). @@ -71,10 +56,6 @@ file to [configure the agent](../repository.md) by setting up parameters such as To see all the settings available, read the [Agent configuration repository documentation](../repository.md). -### Access your cluster from GitLab CI/CD - -Use the [CI/CD Tunnel](../ci_cd_tunnel.md#example-for-a-kubectl-command-using-the-cicd-tunnel) to access your cluster from GitLab CI/CD. - ### Register an 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. @@ -92,242 +73,53 @@ In GitLab: 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**. +### Install the agent into the cluster + In your computer: 1. Open your local terminal and connect to your cluster. -1. Run the command you copied from the installation form. +1. Run the command you copied when registering your cluster in the previous step. -### Install the agent into the cluster +See the following sections to learn about customizing the installation. -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: +## Simple installation method -```shell -kubectl create namespace gitlab-kubernetes-agent -``` +The command provided by GitLab does the following things: -To perform a one-liner installation, run the command below. Make sure to replace: +- 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. +- Creates a `Deployment` resource for the `agentk` pod. -- `your-agent-token` with the token received from the previous step (identified as `secret` in the JSON output). -- `gitlab-kubernetes-agent` with the namespace you defined in the previous step. -- `wss://kas.gitlab.example.com` with the configured access of the Agent Server (KAS). For GitLab.com users, the KAS is available under `wss://kas.gitlab.com`. -- `--agent-version=vX.Y.Z` with the latest released patch version matching your GitLab installation's major and minor versions. For example, for GitLab v13.9.0, use `--agent-version=v13.9.1`. You can find your GitLab version under the "Help/Help" menu. +The one-liner installer can be customized at the command line. To find out the various options the above Docker container supports, run: ```shell -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=vX.Y.Z --namespace gitlab-kubernetes-agent | kubectl apply -f - +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. -To find out the various options the above Docker container supports, run: - -```shell -docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help -``` - -## Advanced installation +## Advanced installation method 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). Otherwise, follow the manual installation steps described below. -### Create the Kubernetes secret - -After generating the token, you must apply it to the Kubernetes cluster. - -To create your Secret, run: - -```shell -kubectl create secret generic -n gitlab-kubernetes-agent gitlab-kubernetes-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 -example [`resources.yml` file](#example-resourcesyml-file) in the following ways: - -- Replace `namespace: gitlab-kubernetes-agent` with `namespace: <YOUR-DESIRED-NAMESPACE>`. -- You can configure `kas-address` (Agent Server) in several ways. - The agent can use the WebSockets or gRPC protocols to connect to the Agent Server. - Select the option appropriate for your cluster configuration and GitLab architecture: - - The `wss` scheme (an encrypted WebSockets connection) is specified by default - after you install the `gitlab-kas` sub-chart, or enable `gitlab-kas` for Omnibus GitLab. - When using the sub-chart, you must set `wss://kas.host.tld:443` as - `kas-address`, where `host.tld` is the domain you've setup for your GitLab installation. - When using Omnibus GitLab, you must set `wss://GitLab.host.tld:443/-/kubernetes-agent/` as - `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/`). - - 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>:8150`) to use gRPC directly, where `gitlab-kas` - is the name of the service created by `gitlab-kas` chart, and `<your-namespace>` - is the namespace where the chart was installed. - - Specify the `grpcs` scheme to use an encrypted gRPC connection. - - 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. -- If you defined your own secret name, replace `gitlab-kubernetes-agent-token` with your - secret name in the `secretName:` section. - -To apply this file, run the following command: +### Customize the permissions for the `agentk` service account -```shell -kubectl apply -n gitlab-kubernetes-agent -f ./resources.yml -``` - -To review your configuration, run the following command: - -```shell -$ kubectl get pods -n gitlab-kubernetes-agent - -NAMESPACE NAME READY STATUS RESTARTS AGE -gitlab-kubernetes-agent gitlab-kubernetes-agent-77689f7dcb-5skqk 1/1 Running 0 51s -``` - -#### Example `resources.yml` file - -```yaml ---- -apiVersion: v1 -kind: Namespace -metadata: - name: gitlab-kubernetes-agent ---- -apiVersion: v1 -kind: ServiceAccount -metadata: - name: gitlab-kubernetes-agent ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: gitlab-kubernetes-agent -spec: - replicas: 1 - selector: - matchLabels: - app: gitlab-kubernetes-agent - template: - metadata: - labels: - app: gitlab-kubernetes-agent - spec: - serviceAccountName: gitlab-kubernetes-agent - containers: - - name: agent - # Make sure to specify a matching version for production - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:vX.Y.Z" - 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 - volumes: - - name: token-volume - secret: - secretName: gitlab-kubernetes-agent-token - strategy: - type: RollingUpdate - rollingUpdate: - maxSurge: 0 - maxUnavailable: 1 ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: gitlab-kubernetes-agent-write -rules: -- resources: - - '*' - apiGroups: - - '*' - verbs: - - create - - update - - delete - - patch ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: gitlab-kubernetes-agent-write-binding -roleRef: - name: gitlab-kubernetes-agent-write - kind: ClusterRole - apiGroup: rbac.authorization.k8s.io -subjects: -- name: gitlab-kubernetes-agent - kind: ServiceAccount - namespace: gitlab-kubernetes-agent ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: gitlab-kubernetes-agent-read -rules: -- resources: - - '*' - apiGroups: - - '*' - verbs: - - get - - list - - watch ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: gitlab-kubernetes-agent-read-binding -roleRef: - name: gitlab-kubernetes-agent-read - kind: ClusterRole - apiGroup: rbac.authorization.k8s.io -subjects: -- name: gitlab-kubernetes-agent - kind: ServiceAccount - namespace: gitlab-kubernetes-agent -``` - -### Create manifest files +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. -In a previous step, you configured a `config.yaml` to point to the GitLab projects -the Agent should synchronize. Agent monitors each of those projects for changes to the manifest files it contains. You can auto-generate manifest files with a -templating engine or other means. +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. -The agent is authorized to download manifests for the configuration -project, and public projects. Support for other private projects is -planned in the issue [Agent authorization for private manifest -projects](https://gitlab.com/gitlab-org/gitlab/-/issues/220912). +To create restricted permissions: -Each time you push a change to a monitored manifest repository, the Agent logs the change: +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. -```plaintext -2020-09-15_14:09:04.87946 gitlab-k8s-agent : time="2020-09-15T10:09:04-04:00" level=info msg="Config: new commit" agent_id=1 commit_id=e6a3651f1faa2e928fe6120e254c122451be4eea -``` - -#### Example manifest file - -This file creates a minimal `ConfigMap`: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: demo-map - namespace: gitlab-kubernetes-agent # Can be any namespace managed by you that the agent has access to. -data: - key: value -``` +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 diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index c8ab037118e..22964fde395 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -12,9 +12,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [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. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - The [GitLab Agent](index.md) supports hosting your configuration for multiple agents in a single repository. These agents can be running in the same cluster or in multiple clusters, and potentially with more than one agent per cluster. diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 88382648b04..f880e603133 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -54,7 +54,7 @@ Supported applications: - [PostHog](#install-posthog-using-gitlab-cicd) - [Prometheus](#install-prometheus-using-gitlab-cicd) -### Usage +### Prerequisites You can find and import all the files referenced below in the [example cluster applications @@ -95,7 +95,7 @@ applications you have configured. In case of pipeline failure, the output of the [Helm Tiller](https://v2.helm.sh/docs/install/#running-tiller-locally) binary is saved as a [CI job artifact](../../ci/pipelines/job_artifacts.md). -#### Usage in GitLab versions earlier than 13.5 +#### Prerequisites in GitLab versions earlier than 13.5 For GitLab versions 13.5 and earlier, the Ingress, Fluentd, Prometheus, and Sentry apps were fetched from the central Helm stable repository (`https://kubernetes-charts.storage.googleapis.com/`). @@ -443,7 +443,7 @@ You can check the recommended variables for each cluster type in the official do - [Google GKE](https://docs.cilium.io/en/v1.8/gettingstarted/k8s-install-gke/#deploy-cilium) - [AWS EKS](https://docs.cilium.io/en/v1.8/gettingstarted/k8s-install-eks/#deploy-cilium) -Do not use `clusterType` for sandbox environments like [Minikube](https://minikube.sigs.k8s.io/docs/). +Do not use `clusterType` for sandbox environments like [minikube](https://minikube.sigs.k8s.io/docs/). You can customize Cilium's Helm variables by defining the `.gitlab/managed-apps/cilium/values.yaml` file in your cluster |