Working with the agent for Kubernetes

Use the following tasks when working with the agent for Kubernetes.

View your agents

Introduced in GitLab 14.8, the installed agentk version is displayed on the Agent tab.

Prerequisite:

  • You must have at least the Developer role.

To view the list of agents:

  1. On the top bar, select Menu > Projects and find the project that contains your agent configuration file.
  2. On the left sidebar, select Infrastructure > 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.

View an agent’s activity information

Introduced in GitLab 14.6.

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. On the top bar, select Menu > Projects and find the project that contains your agent configuration file.
  2. On the left sidebar, select Infrastructure > 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

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

  • off
  • warning
  • error
  • info
  • debug

The log level defaults to info. You can change it by using a top-level observability section in the configuration file, for example: 

observability:
  logging:
    level: debug

Reset the agent token

Introduced in GitLab 14.9.

To reset the agent token without downtime:

  1. Create a new token:
    1. On the top bar, select Menu > Projects and find your project.
    2. On the left sidebar, select Infrastructure > Kubernetes clusters.
    3. Select the agent you want to create a token for.
    4. On the 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. Delete the token you’re no longer using.

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

Introduced in GitLab 14.7.

To remove an agent from the UI:

  1. On the top bar, select Menu > Projects and find the project that contains the agent configuration file.
  2. From the left sidebar, select Infrastructure > Kubernetes clusters.
  3. In the table, in the row for your agent, in the Options column, select the vertical ellipsis ().
  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 self-managed GitLab, go to https://gitlab.example.com/-/graphql-explorer, replacing gitlab.example.com with your 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

Surface network security alerts from cluster to GitLab

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

caution
Cilium integration is in its end-of-life process. It’s deprecated in GitLab 14.8, and planned for removal in GitLab 15.0.

The agent for Kubernetes 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.

Several components 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.

To integrate, add a top-level cilium section to your config.yml file. Currently, the only configuration option is the Hubble relay address: 

cilium:
  hubble_relay_address: "<hubble-relay-host>:<hubble-relay-port>"

If your Cilium integration was performed through GitLab Managed Apps or the cluster management template, you can use hubble-relay.gitlab-managed-apps.svc.cluster.local:80 as the address: 

cilium:
  hubble_relay_address: "hubble-relay.gitlab-managed-apps.svc.cluster.local:80"