kotovalexarian-likes-gitlab
/
gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity
gitlab-org--gitlab-foss/doc/user/clusters/agent/index.md

11 KiB
Raw Blame History

stage group info
Configure Configure 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

Connecting a Kubernetes cluster with GitLab

  • Introduced in GitLab 13.4.
  • Support for grpcs introduced in GitLab 13.6.
  • Introduced in GitLab 13.10, KAS became available on GitLab.com under wss://kas.gitlab.com through an Early Adopter Program.
  • Introduced in GitLab 13.11, the GitLab Agent became available to every project on GitLab.com.
  • Moved from GitLab Premium to GitLab Free in 14.5.
  • Renamed from "GitLab Kubernetes Agent" to "GitLab Agent for Kubernetes" in GitLab 14.6.

The GitLab Agent for Kubernetes ("Agent", for short) is an active in-cluster component for connecting Kubernetes clusters to GitLab safely to support cloud-native deployment, management, and monitoring.

The Agent is installed into the cluster through code, providing you with a fast, safe, stable, and scalable solution.

With GitOps, you can manage containerized clusters and applications from a Git repository that:

  • Is the single source of truth of your system.
  • Is the single place where you operate your system.
  • Is a single resource to monitor your system.

By combining GitLab, Kubernetes, and GitOps, it results in a robust infrastructure:

  • GitLab as the GitOps operator.
  • Kubernetes as the automation and convergence system.
  • GitLab CI/CD as the Continuous Integration and Continuous Deployment engine.

Beyond that, you can use all the features offered by GitLab as the all-in-one DevOps platform for your product and your team.

Supported cluster versions

GitLab is committed to support at least two production-ready Kubernetes minor versions at any given time. We regularly review the versions we support, and provide a three-month deprecation period before we remove support of a specific version. The range of supported versions is based on the evaluation of:

GitLab supports the following Kubernetes versions, and you can upgrade your Kubernetes version to any supported version at any time:

  • 1.20 (support ends on July 22, 2022)
  • 1.19 (support ends on February 22, 2022)
  • 1.18 (support ends on November 22, 2021)
  • 1.17 (support ends on September 22, 2021)

Adding support to other versions of Kubernetes is managed under this epic.

Some GitLab features may support versions outside the range provided here.

Agent's features

By using the Agent, you can:

See the Agent roadmap to track its development.

To contribute to the Agent, see the Agent's development documentation.

Agent's GitOps workflow (PREMIUM)

The Agent uses multiple GitLab projects to provide a flexible workflow that can suit various needs. This diagram shows these repositories and the main actors involved in a deployment:

sequenceDiagram
  participant D as Developer
  participant A as Application code repository
  participant M as Manifest repository
  participant K as GitLab Agent
  participant C as Agent configuration repository
  loop Regularly
    K-->>C: Grab the configuration
  end
  D->>+A: Pushing code changes
  A->>M: Updating manifest
  loop Regularly
    K-->>M: Watching changes
    M-->>K: Pulling and applying changes
  end

For more details, refer to our architecture documentation in the Agent project.

Install the Agent in your cluster

To connect your cluster to GitLab, install the Agent on your cluster.

GitOps deployments (PREMIUM)

To perform GitOps deployments with the Agent, you need:

  • A properly-configured Kubernetes cluster where the Agent is running.
  • A configuration repository that contains a config.yaml file, which tells the Agent the repositories to synchronize with the cluster.
  • A manifest repository that contains manifest files. Any changes to manifest files are applied to the cluster.

You can use a single GitLab project or different projects for the Agent configuration and manifest files, as follows:

  • Single GitLab project (recommended): When you use a single repository to hold both the manifest and the configuration files, these projects can be either private or public.
  • Two GitLab projects: When you use two different GitLab projects (one for manifest files and another for configuration files), the manifests project must be public, while the configuration project can be either private or public.

Support for separated private manifest and configuration repositories is tracked in this issue.

Kubernetes Network Security Alerts (ULTIMATE)

Deprecated in GitLab 14.8, and planned for removal in GitLab 15.0.

WARNING: Cilium integration is in its end-of-life process. It's deprecated for use in GitLab 14.8, and planned for removal in GitLab 15.0.

The GitLab Agent also provides an integration with Cilium. This integration provides a simple way to generate network policy-related alerts and to surface those alerts in GitLab.

There are several components that work in concert for the Agent to generate the alerts:

The setup process follows the same Agent's installation steps, with the following differences:

  • When you define a configuration repository, you must do so with Cilium settings.
  • You do not need to specify the gitops configuration section.

Remove an agent

You can remove an agent using the GitLab UI or through the GraphQL API.

Remove an agent through the GitLab UI

Introduced in GitLab 14.7.

To remove an agent from the UI:

  1. Go to your agent's configuration repository.
  2. From your project's sidebar, select Infrastructure > Kubernetes clusters.
  3. 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.

    query{
  project(fullPath: "<full-path-to-agent-configuration-project>") {
    clusterAgent(name: "<agent-name>") {
      id
      tokens {
        edges {
          node {
            id
          }
        }
      }
    }
  }
}

  2. Remove an agent record with GraphQL by deleting the clusterAgentToken.

    mutation deleteAgent {
  clusterAgentDelete(input: { id: "<cluster-agent-id>" } ) {
    errors
  }
}

mutation deleteToken {
  clusterAgentTokenDelete(input: { id: "<cluster-agent-token-id>" }) {
    errors
  }
}

  3. Verify whether the removal occurred successfully. If the output in the Pod logs includes unauthenticated, it means that the agent was successfully removed:

    {
    "level": "warn",
    "time": "2021-04-29T23:44:07.598Z",
    "msg": "GetConfiguration.Recv failed",
    "error": "rpc error: code = Unauthenticated desc = unauthenticated"
}

  4. Delete the Agent in your cluster:

    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 from the certificate-based integration depending on the features you use.

Related topics