ContextQMD
Back to Gitlabhq

Managing the agent for Kubernetes instances

doc/user/clusters/agent/work_with_agent.md

18.11.28.6 KB
Original Source

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Use the following tasks when you work with the agent for Kubernetes.

View your agents

The installed agentk version is displayed on the Agent tab.

Prerequisites:

  • You must have the Developer, Maintainer, or Owner role.

To view the list of agents:

  1. In the top bar, select Search or go to and find the project that contains your agent configuration file. You cannot view registered agents from a project that does not contain the agent configuration file.
  2. Select Operate > Kubernetes clusters.
  3. Select Agent tab to view clusters connected to GitLab through the agent.

On this page, you can view:

  • All the registered agents for the current project.
  • The connection status.
  • The version of agentk installed on your cluster.
  • The path to each agent configuration file.

Configure your agent

To configure your agent:

You can quickly locate an agent configuration file from the list of agents. The Configuration column indicates the location of the config.yaml file, or shows how to create one.

The agent configuration file manages the various agent features:

Available configuration file fields

The configuration file format for the agent is defined as a protocol buffer message in the source repository.

To view all the available configuration file fields:

  1. Go to ConfigurationFile in the generated documentation to view the fields for the whole agent configuration file.
  2. Select any field types for more information on the structure of the field.

View shared agents

{{< history >}}

{{< /history >}}

In addition to the agents owned by your project, you can also view agents shared with the ci_access and user_access keywords. Once an agent is shared with a project, it automatically appears in the project agent tab.

To view the list of shared agents:

  1. In the top bar, select Search or go to and find your project.
  2. Select Operate > Kubernetes clusters.
  3. Select the Agent tab.

The list of shared agents and their clusters are displayed.

View an agent's activity information

The activity logs help you to identify problems and get the information you need for troubleshooting. You can see events from a week before the current date. To view an agent's activity:

  1. In the top bar, select Search or go to and find the project that contains your agent configuration file.
  2. Select Operate > Kubernetes clusters.
  3. Select the agent you want to see activity for.

The activity list includes:

  • Agent registration events: When a new token is created.
  • Connection events: When an agent is successfully connected to a cluster.

The connection status is logged when you connect an agent for the first time or after more than an hour of inactivity.

View and provide feedback about the UI in this epic.

Debug the agent

{{< history >}}

{{< /history >}}

To debug the cluster-side component (agentk) of the agent, set the log level according to the available options:

  • error
  • info
  • debug

The agent has two loggers:

  • A general purpose logger, which defaults to info.
  • A gRPC logger, which defaults to error.

You can change your log levels by using a top-level observability section in the agent configuration file, for example setting the levels to debug and warn:

yaml
observability:
  logging:
    level: debug
    grpc_level: warn

When grpc_level is set to info or below, there are a lot of gRPC logs.

Commit the configuration changes and inspect the agent service logs:

shell
kubectl logs -f -l=app=gitlab-agent -n gitlab-agent

For more information about debugging, see troubleshooting documentation.

Reset the agent token

{{< history >}}

  • Two-token limit introduced in GitLab 16.1 with a flag named cluster_agents_limit_tokens_created.
  • Two-token limit generally available in GitLab 16.2. Feature flag cluster_agents_limit_tokens_created removed.

{{< /history >}}

An agent can have only two active tokens at one time.

To reset the agent token without downtime:

  1. Create a new token:
    1. In the top bar, select Search or go to and find your project.
    2. Select Operate > Kubernetes clusters.
    3. Select the agent you want to create a token for.
    4. On the Access tokens tab, select Create token.
    5. Enter token's name and description (optional) and select Create token.
  2. Securely store the generated token.
  3. Use the token to install the agent in your cluster and to update the agent to another version.
  4. To delete the token you're no longer using, return to the token list and select Revoke ({{< icon name="remove" >}}).

Remove an agent

You can remove an agent by using the GitLab UI or the GraphQL API. The agent and any associated tokens are removed from GitLab, but no changes are made in your Kubernetes cluster. You must clean up those resources manually.

Remove an agent through the GitLab UI

To remove an agent from the UI:

  1. In the top bar, select Search or go to and find the project that contains your agent configuration file.
  2. Select Operate > Kubernetes clusters.
  3. In the table, in the row for your agent, in the Options column, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}).
  4. 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 GitLab Self-Managed, go to https://gitlab.example.com/-/graphql-explorer, replacing gitlab.example.com with your instance's URL.
    graphql
    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.

    graphql
    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:

    json
    {
    "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:

    shell
    kubectl delete -n gitlab-kubernetes-agent -f ./resources.yml