diff options
Diffstat (limited to 'doc/user/infrastructure/clusters')
7 files changed, 308 insertions, 151 deletions
diff --git a/doc/user/infrastructure/clusters/connect/index.md b/doc/user/infrastructure/clusters/connect/index.md index 06d1307984d..004f4409919 100644 --- a/doc/user/infrastructure/clusters/connect/index.md +++ b/doc/user/infrastructure/clusters/connect/index.md @@ -8,10 +8,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w The [certificate-based Kubernetes integration with GitLab](../index.md) was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) -in GitLab 14.5. To connect your clusters, use the [GitLab Agent](../../../clusters/agent/index.md). +in GitLab 14.5. To connect your clusters, use the [GitLab agent](../../../clusters/agent/index.md). <!-- TBA: (We need to resolve https://gitlab.com/gitlab-org/gitlab/-/issues/343660 before adding this line) -If you don't have a cluster yet, create one and connect it to GitLab through the Agent. +If you don't have a cluster yet, create one and connect it to GitLab through the agent. You can also create a new cluster from GitLab using [Infrastructure as Code](../../iac/index.md#create-a-new-cluster-through-iac). --> diff --git a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md new file mode 100644 index 00000000000..87b8f510289 --- /dev/null +++ b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md @@ -0,0 +1,132 @@ +--- +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 +--- + +# Create an Amazon EKS cluster + +You can create a cluster on Amazon Elastic Kubernetes Service (EKS) through +[Infrastructure as Code (IaC)](../../index.md). This process uses the AWS and +Kubernetes Terraform providers to create EKS clusters. You connect the clusters to GitLab +by using the GitLab agent for Kubernetes. + +**Prerequisites:** + +- An Amazon Web Services (AWS) account, with a set of configured + [security credentials](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-prereqs.html). +- [A runner](https://docs.gitlab.com/runner/install/) you can use to run the GitLab CI/CD pipeline. + +**Steps:** + +1. [Import the example project](#import-the-example-project). +1. [Register the agent for Kubernetes](#register-the-agent). +1. [Configure your project](#configure-your-project). +1. [Provision your cluster](#provision-your-cluster). + +## Import the example project + +To create a cluster from GitLab using Infrastructure as Code, you must +create a project to manage the cluster from. In this tutorial, you start with +a sample project and modify it according to your needs. + +Start by [importing the example project by URL](../../../project/import/repo_by_url.md). + +To import the project: + +1. On the top bar, select **Menu > Create new project**. +1. Select **Import project**. +1. Select **Repo by URL**. +1. For the **Git repository URL**, enter `https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks.git`. +1. Complete the fields and select **Create project**. + +This project provides you with: + +- An Amazon [Virtual Private Cloud (VPC)](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks/-/blob/main/vpc.tf). +- An Amazon [Elastic Kubernetes Service (EKS)](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks/-/blob/main/eks.tf) cluster. +- The [GitLab agent for Kubernetes](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks/-/blob/main/agent.tf) installed in the cluster. + +## Register the agent + +To create a GitLab agent for Kubernetes: + +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. Select **Actions**. +1. From the **Select an agent** dropdown list, select `eks-agent` and select **Register an agent**. +1. GitLab generates a registration token for the agent. Securely store this secret token, as you will need it later. +1. GitLab provides an address for the agent server (KAS), which you will also need later. + +## Configure your project + +Use CI/CD environment variables to configure your project. + +**Required configuration:** + +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Variables**. +1. Set the variable `AWS_ACCESS_KEY_ID` to your AWS access key ID. +1. Set the variable `AWS_SECRET_ACCESS_KEY` to your AWS secret access key. +1. Set the variable `TF_VAR_agent_token` to the agent token displayed in the previous task. +1. Set the variable `TF_VAR_kas_address` to the agent server address displayed in the previous task. + +**Optional configuration:** + +The file [`variables.tf`](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks/-/blob/main/variables.tf) +contains other variables that you can override according to your needs: + +- `TF_VAR_region`: Set your cluster's region. +- `TF_VAR_cluster_name`: Set your cluster's name. +- `TF_VAR_cluster_version`: Set the version of Kubernetes. +- `TF_VAR_instance_type`: Set the instance type for the Kubernetes nodes. +- `TF_VAR_instance_count`: Set the number of Kubernetes nodes. +- `TF_VAR_agent_version`: Set the version of the GitLab agent. +- `TF_VAR_agent_namespace`: Set the Kubernetes namespace for the GitLab agent. + +View the [AWS Terraform provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) and the [Kubernetes Terraform provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs) documentation for further resource options. + +## Provision your cluster + +After configuring your project, manually trigger the provisioning of your cluster. In GitLab: + +1. On the left sidebar, go to **CI/CD > Pipelines**. +1. Next to **Play** (**{play}**), select the dropdown icon (**{angle-down}**). +1. Select **Deploy** to manually trigger the deployment job. + +When the pipeline finishes successfully, you can view the new cluster: + +- In AWS: From the [EKS console](https://console.aws.amazon.com/eks/home), select **Amazon EKS > Clusters**. +- In GitLab: On the left sidebar, select **Infrastructure > Kubernetes clusters**. + +## Use your cluster + +After you provision the cluster, it is connected to GitLab and is ready for deployments. To check the connection: + +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. In the list, view the **Connection status** column. + +For more information about the capabilities of the connection, see [the GitLab agent for Kubernetes documentation](../index.md). + +## Remove the cluster + +A cleanup job is not included in your pipeline by default. To remove all created resources, you +must modify your GitLab CI/CD template before running the cleanup job. + +To remove all resources: + +1. Add the following to your `.gitlab-ci.yml` file: + + ```yaml + stages: + - init + - validate + - build + - deploy + - cleanup + + destroy: + extends: .destroy + needs: [] + ``` + +1. On the left sidebar, select **CI/CD > Pipelines** and select the most recent pipeline. +1. For the `destroy` job, select **Play** (**{play}**). diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md index d1e3bd47b89..1ed8b0ef350 100644 --- a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md @@ -4,65 +4,59 @@ 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 --- -# New GKE cluster through IaC (DEPRECATED) - -> [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. - -WARNING: -The process described on this page uses cluster certificates to connect the -new cluster to GitLab, [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -You can still create a cluster and then connect it to GitLab through the [Agent](../index.md). -[An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/343660) -to migrate this functionality to the [Agent](../index.md). +# Create a Google GKE cluster Learn how to create a new cluster on Google Kubernetes Engine (GKE) through -[Infrastructure as Code (IaC)](../../index.md). - -This process combines the GitLab Terraform and Google Terraform providers -with Kubernetes to help you create GKE clusters and deploy them through -GitLab. - -This document describes how to set up a [group-level cluster](../../../group/clusters/index.md) on GKE by importing an example project to get you started. -You can then modify the project files according to your needs. +[Infrastructure as Code (IaC)](../../index.md). This process uses the Google +and Kubernetes Terraform providers create GKE clusters. You connect the clusters to GitLab +by using the GitLab agent for Kubernetes. **Prerequisites:** -- A GitLab group. -- A GitLab user with the Maintainer role in the group. -- A [GitLab personal access token](../../../profile/personal_access_tokens.md) with `api` access, created by a user with at least the Maintainer role in the group. - A [Google Cloud Platform (GCP) service account](https://cloud.google.com/docs/authentication/getting-started). +- [A runner](https://docs.gitlab.com/runner/install/) you can use to run the GitLab CI/CD pipeline. **Steps:** 1. [Import the example project](#import-the-example-project). -1. [Create your GCP and GitLab credentials](#create-your-gcp-and-gitlab-credentials). +1. [Register the agent for Kubernetes](#register-the-agent). +1. [Create your GCP credentials](#create-your-gcp-credentials). 1. [Configure your project](#configure-your-project). -1. [Deploy your cluster](#deploy-your-cluster). +1. [Provision your cluster](#provision-your-cluster). ## Import the example project -To create a new group-level cluster from GitLab using Infrastructure as Code, it is necessary -to create a project to manage the cluster from. In this tutorial, we import a pre-configured -sample project to help you get started. +To create a cluster from GitLab using Infrastructure as Code, you must +create a project to manage the cluster from. In this tutorial, you start with +a sample project and modify it according to your needs. -Start by [importing the example project by URL](../../../project/import/repo_by_url.md). Use `https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke.git` as URL. +Start by [importing the example project by URL](../../../project/import/repo_by_url.md). -This project provides you with the following resources: +To import the project: + +1. On the top bar, select **Menu > Create new project**. +1. Select **Import project**. +1. Select **Repo by URL**. +1. For the **Git repository URL**, enter `https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke.git`. +1. Complete the fields and select **Create project**. + +This project provides you with: - A [cluster on Google Cloud Platform (GCP)](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke/-/blob/master/gke.tf) with defaults for name, location, node count, and Kubernetes version. -- A [`gitlab-admin` K8s service account](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke/-/blob/master/gitlab-admin.tf) with `cluster-admin` privileges. -- The new group-level cluster connected to GitLab. -- Pre-configures Terraform files: - - ```plaintext - ├── backend.tf # State file Location Configuration - ├── gke.tf # Google GKE Configuration - ├── gitlab-admin.tf # Adding kubernetes service account - └── group_cluster.tf # Registering kubernetes cluster to GitLab `apps` Group - ``` +- The [GitLab agent for Kubernetes](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke/-/blob/master/agent.tf) installed in the cluster. -## Create your GCP and GitLab credentials +## Register the agent + +To create a GitLab agent for Kubernetes: + +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. Select **Actions**. +1. From the **Select an agent** dropdown list, select `gke-agent` and select **Register an agent**. +1. GitLab generates a registration token for the agent. Securely store this secret token, as you will need it later. +1. GitLab provides an address for the agent server (KAS), which you will also need later. + +## Create your GCP credentials To set up your project to communicate to GCP and the GitLab API: @@ -85,18 +79,14 @@ The Admin role creates a service account in the `kube-system` namespace. ## Configure your project -**Required configuration:** - -Use CI/CD environment variables to configure your project as detailed below. +Use CI/CD environment variables to configure your project. **Required configuration:** 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Variables**. -1. Set the variable `TF_VAR_gitlab_token` to the GitLab personal access token you just created. 1. Set the variable `BASE64_GOOGLE_CREDENTIALS` to the `base64` encoded JSON file you just created. 1. Set the variable `TF_VAR_gcp_project` to your GCP's `project` name. -1. Set the variable `TF_VAR_gitlab_group` to the name of the group you want to connect your cluster to. If your group's URL is `https://gitlab.example.com/my-example-group`, `my-example-group` is your group's name. **Optional configuration:** @@ -105,22 +95,57 @@ contains other variables that you can override according to your needs: - `TF_VAR_gcp_region`: Set your cluster's region. - `TF_VAR_cluster_name`: Set your cluster's name. -- `TF_VAR_machine_type`: Set the machine type for the Kubernetes nodes. - `TF_VAR_cluster_description`: Set a description for the cluster. We recommend setting this to `$CI_PROJECT_URL` to create a reference to your GitLab project on your GCP cluster detail page. This way you know which project was responsible for provisioning the cluster you see on the GCP dashboard. -- `TF_VAR_base_domain`: Set to the base domain to provision resources under. -- `TF_VAR_environment_scope`: Set to the environment scope for your cluster. +- `TF_VAR_machine_type`: Set the machine type for the Kubernetes nodes. +- `TF_VAR_node_count`: Set the number of Kubernetes nodes. +- `TF_VAR_agent_version`: Set the version of the GitLab agent. +- `TF_VAR_agent_namespace`: Set the Kubernetes namespace for the GitLab agent. -Refer to the [GitLab Terraform provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs) and the [Google Terraform provider](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference) documentation for further resource options. +Refer to the [Google Terraform provider](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference) and the [Kubernetes Terraform provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs) documentation for further resource options. -## Deploy your cluster +## Provision your cluster -After configuring your project, manually trigger the deployment of your cluster. In GitLab: +After configuring your project, manually trigger the provisioning of your cluster. In GitLab: -1. From your project's sidebar, go to **CI/CD > Pipelines**. -1. Select the dropdown icon (**{angle-down}**) next to the play icon (**{play}**). -1. Select **deploy** to manually trigger the deployment job. +1. On the left sidebar, go to **CI/CD > Pipelines**. +1. Next to **Play** (**{play}**), select the dropdown icon (**{angle-down}**). +1. Select **Deploy** to manually trigger the deployment job. When the pipeline finishes successfully, you can see your new cluster: - In GCP: on your [GCP console's Kubernetes list](https://console.cloud.google.com/kubernetes/list). - In GitLab: from your project's sidebar, select **Infrastructure > Kubernetes clusters**. + +## Use your cluster + +After you provision the cluster, it is connected to GitLab and is ready for deployments. To check the connection: + +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. In the list, view the **Connection status** column. + +For more information about the capabilities of the connection, see [the GitLab agent for Kubernetes documentation](../index.md). + +## Remove the cluster + +A cleanup job is not included in your pipeline by default. To remove all created resources, you +must modify your GitLab CI/CD template before running the cleanup job. + +To remove all resources: + +1. Add the following to your `.gitlab-ci.yml` file: + + ```yaml + stages: + - init + - validate + - build + - deploy + - cleanup + + destroy: + extends: .destroy + needs: [] + ``` + +1. On the left sidebar, select **CI/CD > Pipelines** and select the most recent pipeline. +1. For the `destroy` job, select **Play** (**{play}**). diff --git a/doc/user/infrastructure/clusters/deploy/inventory_object.md b/doc/user/infrastructure/clusters/deploy/inventory_object.md index 47063dcae96..d76ef0b9359 100644 --- a/doc/user/infrastructure/clusters/deploy/inventory_object.md +++ b/doc/user/infrastructure/clusters/deploy/inventory_object.md @@ -4,66 +4,74 @@ 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 --- -# Inventory object **(PREMIUM)** +# Tracking cluster resources managed by GitLab **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0. -An inventory object is a `ConfigMap` object for keeping track of the set of objects applied to a cluster. -When you remove objects from a manifest repository, the Agent uses a corresponding inventory object to -prune (delete) objects from the cluster. +GitLab uses an inventory object to track the resources you deploy to your cluster. +The inventory object is a `ConfigMap` that contains a list of controlled objects. +The managed resources use the `cli-utils.sigs.k8s.io/inventory-id` annotation. -The Agent creates an inventory object for each manifest project specified in the -`gitops.manifest_projects` configuration section. The inventory object has to be stored somewhere in the cluster. -The default behavior is: +## Default location of the inventory object -- The `namespace` used comes from `gitops.manifest_projects[].default_namespace`. If you don't specify this parameter - explicitly, the inventory object is stored in the `default` namespace. -- The `name` is generated from the numeric project ID of the manifest project and the numeric agent ID. +In the agent configuration file, you specify a list of projects. For example: - This way the Agent constructs the name and local where the inventory object is - stored in the cluster. +```yaml +gitops: + manifest_projects: + - id: gitlab-org/cluster-integration/gitlab-agent + default_namespace: my-ns +``` -The Agent cannot locate the existing inventory object if you: +The agent creates an inventory object for every item in the `manifest_projects` list. +The inventory object is stored in the namespace you specify for `default_namespace`. -- Change `gitops.manifest_projects[].default_namespace` parameter. -- Move manifests into another project. +The name and location of the inventory object is based on: -## Inventory object template +- The `default_namespace`. If you don't specify this parameter, + the inventory object is stored in the `default` namespace. +- The `name`, which is the ID of the project with the manifest and the ID of the agent. -The inventory object template is a `ConfigMap` object that allows you to configure the namespace and the name of the inventory -object. Store this template with manifest files in a single group. +WARNING: +The agent cannot locate the existing inventory object if you change +the `default_namespace` parameter or move manifests to another project. -Example inventory object template: +## Change the location of the inventory object -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: unique-name-for-the-inventory - namespace: my-project-namespace - labels: - cli-utils.sigs.k8s.io/inventory-id: unique-name-for-the-inventory -``` +You can configure the namespace and the name of the inventory object. +This action changes the location of the object in the cluster. + +1. Create an inventory object template, which is a `ConfigMap` object. + For example: + + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + name: unique-name-for-the-inventory + namespace: my-project-namespace + labels: + cli-utils.sigs.k8s.io/inventory-id: unique-name-for-the-inventory + ``` + +1. Specify a `namespace` and `name`. Ensure that the `name` is unique so it doesn't conflict with other + inventory objects in the same namespace in the future. +1. Ensure the value for `cli-utils.sigs.k8s.io/inventory-id` is unique. This value is used for objects + tracked by this inventory object. Their `config.k8s.io/owning-inventory` annotation is set to this value. + + The value doesn't have to match the `name` but it's convenient to set them to the same value. + +1. Save the file with the manifest files as a single logical group. -- The `namespace` and `name` fields configure where the real inventory object is created. -- The `cli-utils.sigs.k8s.io/inventory-id` label with its corresponding value is set on the inventory object, created - from this template. Make sure that the value is unique (for example, a string of random characters) and doesn't clash - with any existing or future inventory object templates. -- Objects tracked by this inventory object have the `config.k8s.io/owning-inventory` annotation set to the value of - the `cli-utils.sigs.k8s.io/inventory-id` label. -- The label's value doesn't have to match the `name` but it's convenient to have them set to the same value. -- Make sure that the `name` is unique so that it doesn't conflict with another inventory object in the same - namespace in the future. +## `inventory_policy` options -## Using GitOps with pre-existing Kubernetes objects +Sometimes your manifest changes affect resources that aren't tracked by the GitLab inventory object. -The Agent treats manifest files in the manifest repository as the source of truth. When it applies -objects from the files to the cluster, it tracks them in an inventory object. If an object already exists, -The Agent behaves differently based on the `gitops.manifest_projects[].inventory_policy` configuration. -Check the table below with the available options and when to use them. +To change how the agent behaves when it overwrites existing and previously untracked resources, +change the `inventory_policy` value. `inventory_policy` value | Description | ------------------------ | ------------------------------------------------------------------------------------------- | -`must_match` | This is the default policy. A live object must have the `config.k8s.io/owning-inventory` annotation set to the same value as the `cli-utils.sigs.k8s.io/inventory-id` label on the corresponding inventory object to be updated. Object is not updated and an error is reported if the values don't match or the object doesn't have the annotation. | -`adopt_if_no_inventory` | This mode allows to "adopt" an object if it doesn't have the `config.k8s.io/owning-inventory` annotation. Use this mode if you want to start managing existing objects using the GitOps feature. Once all objects have been "adopted", we recommend you to put the setting back into the default `must_match` mode to avoid any unexpected adoptions. | -`adopt_all` | This mode allows to "adopt" an object even if it has the `config.k8s.io/owning-inventory` annotation set to a different value. This mode can be useful if you want to migrate a set of objects from one agent to another one or from some other tool to the Agent. Once all objects have been "adopted", we recommend you to put the setting back into the default `must_match` mode to avoid any unexpected adoptions. | +`must_match` | The default policy. To be updated, a live object must have the `config.k8s.io/owning-inventory` annotation set to the same value as the `cli-utils.sigs.k8s.io/inventory-id` label on the corresponding inventory object. If the values don't match or the object doesn't have the annotation, the object is not updated and an error is reported. | +`adopt_if_no_inventory` | Adopt an object if it doesn't have the `config.k8s.io/owning-inventory` annotation. Use this mode if you want to start managing existing objects by using the GitOps feature. To avoid unexpected adoptions, after all objects have been adopted, put the setting back to the default `must_match` mode. | +`adopt_all` | Adopt an object even if it has the `config.k8s.io/owning-inventory` annotation set to a different value. Use this mode if you want to migrate a set of objects from one agent to another, or from some other tool to the agent. To avoid unexpected adoptions, after all objects have been adopted, put the setting back to the default `must_match` mode. | diff --git a/doc/user/infrastructure/clusters/index.md b/doc/user/infrastructure/clusters/index.md index 144a8cd2d31..cd7c5feb284 100644 --- a/doc/user/infrastructure/clusters/index.md +++ b/doc/user/infrastructure/clusters/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Kubernetes clusters **(FREE)** -To connect clusters to GitLab, use the [GitLab Agent](../../clusters/agent/index.md). +To connect clusters to GitLab, use the [GitLab agent](../../clusters/agent/index.md). ## Certificate-based Kubernetes integration (DEPRECATED) @@ -24,7 +24,7 @@ It had the following issues: - Users were constantly reporting issues with features based on this model. For this reason, we started to build features based on a new model, the -[GitLab Agent](../../clusters/agent/index.md). +[GitLab agent](../../clusters/agent/index.md). Maintaining both methods in parallel caused a lot of confusion and significantly increased the complexity to use, develop, maintain, and document them. For this reason, we decided to deprecate them to focus on the @@ -38,7 +38,7 @@ Follow this [epic](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) for updates. You can find technical information about why we moved away from cluster certificates into -the GitLab Agent model on the [Agent's blueprint documentation](../../../architecture/blueprints/gitlab_to_kubernetes_communication/index.md). +the GitLab agent model on the [agent's blueprint documentation](../../../architecture/blueprints/gitlab_to_kubernetes_communication/index.md). ## Deprecated features @@ -67,6 +67,5 @@ The concept of [project-level](../../project/clusters/index.md), [instance-level](../../instance/clusters/index.md) clusters becomes extinct in the new model, although the functionality remains to some extent. -The Agent is always configured in a single GitLab project, but you can use the CI/CD Tunnel to -[authorize other projects and groups to use the same Agent](../../clusters/agent/repository.md#authorize-projects-and-groups-to-use-an-agent). +The agent is always configured in a single GitLab project and you can expose the cluster connection to other projects and groups to [access it from GitLab CI/CD](../../clusters/agent/ci_cd_tunnel.md). By doing so, you are granting these projects and groups access to the same cluster, which is similar to group-level clusters' use case. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md index 841f2af7863..4faf5f46418 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md @@ -4,7 +4,7 @@ group: Runner info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Install GitLab Runner with a cluster management project +# Install GitLab Runner with a cluster management project **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. diff --git a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md index 1dd1c760bcc..01530422e4a 100644 --- a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md +++ b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md @@ -4,85 +4,78 @@ 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 --- -# Migrate to the GitLab Agent for Kubernetes **(FREE)** +# Migrate to the GitLab agent for Kubernetes **(FREE)** -The first integration between GitLab and Kubernetes used cluster certificates -to connect the cluster to GitLab. -This method was [deprecated](https://about.gitlab.com/blog/2021/11/15/deprecating-the-cert-based-kubernetes-integration/) -in GitLab 14.5 in favor of the [GitLab Agent for Kubernetes](../../clusters/agent/index.md). +To connect your Kubernetes cluster with GitLab, you can use: -To make sure your clusters connected to GitLab do not break in the future, -we recommend you migrate to the GitLab Agent as soon as possible by following -the processes described in this document. +- [A GitOps workflow](../../clusters/agent/gitops.md). +- [A GitLab CI/CD workflow](../../clusters/agent/ci_cd_tunnel.md). +- [A certificate-based integration](index.md). -The certificate-based integration was used for some popular GitLab features such as, -GitLab Managed Apps, GitLab-managed clusters, and Auto DevOps. +The certificate-based integration is +[**deprecated**](https://about.gitlab.com/blog/2021/11/15/deprecating-the-cert-based-kubernetes-integration/) +in GitLab 14.5. It is expected to be +[turned off by default in 15.0](../../../update/deprecations.md#certificate-based-integration-with-kubernetes) +and removed in GitLab 15.6. + +If you are using the certificate-based integration, you should move to another workflow as soon as possible. -As a general rule, migrating clusters that rely on GitLab CI/CD can be -achieved using the [CI/CD Tunnel](../../clusters/agent/ci_cd_tunnel.md) -provided by the Agent. +As a general rule, to migrate clusters that rely on GitLab CI/CD, +you can use the [CI/CD workflow](../../clusters/agent/ci_cd_tunnel.md). +This workflow uses an agent to connect to your cluster. The agent: + +- Is not exposed to the internet. +- Does not require full cluster-admin access to GitLab. NOTE: -The GitLab Agent for Kubernetes does not intend to provide feature parity with the -certificate-based cluster integrations. As a result, the Agent doesn't support -all the features available to clusters connected through certificates. +The certificate-based integration was used for popular GitLab features like +GitLab Managed Apps, GitLab-managed clusters, and Auto DevOps. +Some features are currently available only when using certificate-based integration. ## Migrate cluster application deployments ### Migrate from GitLab-managed clusters With GitLab-managed clusters, GitLab creates separate service accounts and namespaces -for every branch and deploys using these resources. +for every branch and deploys by using these resources. -To achieve a similar result with the GitLab Agent, you can use [impersonation](../../clusters/agent/repository.md#use-impersonation-to-restrict-project-and-group-access) +The GitLab agent uses [impersonation](../../clusters/agent/ci_cd_tunnel.md#use-impersonation-to-restrict-project-and-group-access) strategies to deploy to your cluster with restricted account access. To do so: 1. Choose the impersonation strategy that suits your needs. 1. Use Kubernetes RBAC rules to manage impersonated account permissions in Kubernetes. -1. Use the `access_as` attribute in your Agent’s configuration file to define the impersonation. +1. Use the `access_as` attribute in your agent configuration file to define the impersonation. ### Migrate from Auto DevOps -To configure your Auto DevOps project to use the GitLab Agent: +To configure your Auto DevOps project to use the GitLab agent: -1. Follow the steps to [install an agent](../../clusters/agent/install/index.md) on your cluster. -1. Go to the project in which you use Auto DevOps. -1. From the sidebar, select **Settings > CI/CD** and expand **Variables**. +1. Follow the steps to [install an agent](../../clusters/agent/install/index.md) in your cluster. +1. Go to the project where you use Auto DevOps. +1. On the left sidebar, select **Settings > CI/CD** and expand **Variables**. 1. Select **Add new variable**. 1. Add `KUBE_CONTEXT` as the key, `path/to/agent/project:agent-name` as the value, and select the environment scope of your choice. 1. Select **Add variable**. 1. Repeat the process to add another variable, `KUBE_NAMESPACE`, setting the value for the Kubernetes namespace you want your deployments to target, and set the same environment scope from the previous step. -1. From the sidebar, select **Infrastructure > Kubernetes clusters**. +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. 1. From the certificate-based clusters section, open the cluster that serves the same environment scope. 1. Select the **Details** tab and disable the cluster. -1. To activate the changes, from the project's sidebar, select **CI/CD > Variables > Run pipeline**. +1. To activate the changes, on the left sidebar, select **CI/CD > Variables > Run pipeline**. -### Migrate generic deployments - -When you use Kubernetes contexts to reach the cluster from GitLab, you can use the [CI/CD Tunnel](../../clusters/agent/ci_cd_tunnel.md) -directly. It injects the available contexts into your CI environment automatically: +For an example, [view this project](https://gitlab.com/gitlab-examples/ops/gitops-demo/hello-world-service). -1. Follow the steps to [install an agent](../../clusters/agent/install/index.md) on your cluster. -1. Go to the project in which you use Auto DevOps. -1. From the sidebar, select **Settings > CI/CD** and expand **Variables**. -1. Select **Add new variable**. -1. Add `KUBE_CONTEXT` as the key, `path/to/agent-configuration-project:your-agent-name` as the value, and select the environment scope of your choice. -1. Edit your `.gitlab-ci.yml` file and set the Kubernetes context to the `KUBE_CONTEXT` you defined in the previous step: +### Migrate generic deployments - ```yaml - <your job name>: - script: - - kubectl config use-context $KUBE_CONTEXT - ``` +Follow the process for the [CI/CD workflow](../../clusters/agent/ci_cd_tunnel.md). -## Migrate from GitLab Managed Applications +## Migrate from GitLab Managed applications -Follow the process to [migrate from GitLab Managed Apps to the Cluster Management Project](../../clusters/migrating_from_gma_to_project_template.md). +Follow the process to [migrate from GitLab Managed Apps to the cluster management project](../../clusters/migrating_from_gma_to_project_template.md). -## Migrating a Cluster Management project +## Migrate a cluster management project -See [how to use a cluster management project with the GitLab Agent](../../clusters/management_project_template.md#use-the-agent-with-the-cluster-management-project-template). +See [how to use a cluster management project with the GitLab agent](../../clusters/management_project_template.md). ## Migrate cluster monitoring features -Cluster monitoring features are not supported by the GitLab Agent for Kubernetes yet. +Cluster monitoring features are not yet supported by the GitLab agent for Kubernetes. |