Add tracking method to cluster agent token

Add track_usage to cluster agent token model and kas API.
Add last_used_at to GraphQl.
Update associated tests and docs.

app/models/clusters/agent_token.rb

@@ -2,11 +2,17 @@
 
 module Clusters
   class AgentToken < ApplicationRecord
+    include RedisCacheable
     include TokenAuthenticatable
+
     add_authentication_token_field :token, encrypted: :required, token_generator: -> { Devise.friendly_token(50) }
+    cached_attr_reader :last_contacted_at
 
     self.table_name = 'cluster_agent_tokens'
 
+    # The `UPDATE_USED_COLUMN_EVERY` defines how often the token DB entry can be updated
+    UPDATE_USED_COLUMN_EVERY = (40.minutes..55.minutes).freeze
+
     belongs_to :agent, class_name: 'Clusters::Agent', optional: false
     belongs_to :created_by_user, class_name: 'User', optional: true
 
@@ -14,5 +20,27 @@ module Clusters
 
     validates :description, length: { maximum: 1024 }
     validates :name, presence: true, length: { maximum: 255 }, on: :create
+
+    def track_usage
+      track_values = { last_used_at: Time.current.utc }
+
+      cache_attributes(track_values)
+
+      # Use update_column so updated_at is skipped
+      update_columns(track_values) if can_update_track_values?
+    end
+
+    private
+
+    def can_update_track_values?
+      # Use a random threshold to prevent beating DB updates.
+      last_used_at_max_age = Random.rand(UPDATE_USED_COLUMN_EVERY)
+
+      real_last_used_at = read_attribute(:last_used_at)
+
+      # Handle too many updates from high token traffic
+      real_last_used_at.nil? ||
+        (Time.current - real_last_used_at) >= last_used_at_max_age
+    end
   end
 end

changelogs/unreleased/322128-update-token-used-field.yml

+---
+title: Track agent token last_used
+merge_request: 56143
+author:
+type: added

doc/api/graphql/reference/index.md

@@ -1328,6 +1328,7 @@ An edge in a connection.
 | `createdByUser` | [`User`](#user) | The user who created the token. |
 | `description` | [`String`](#string) | Description of the token. |
 | `id` | [`ClustersAgentTokenID!`](#clustersagenttokenid) | Global ID of the token. |
+| `lastUsedAt` | [`Time`](#time) | Timestamp the token was last used. |
 | `name` | [`String`](#string) | Name given to the token. |
 
 ### `ClusterAgentTokenConnection`

ee/app/graphql/types/clusters/agent_token_type.rb

@@ -29,6 +29,11 @@ module Types
             null: true,
             description: 'Description of the token.'
 
+      field :last_used_at,
+            Types::TimeType,
+            null: true,
+            description: 'Timestamp the token was last used.'
+
       field :id,
             ::Types::GlobalIDType[::Clusters::AgentToken],
             null: false,

ee/spec/graphql/types/clusters/agent_token_type_spec.rb

@@ -3,7 +3,7 @@
 require 'spec_helper'
 
 RSpec.describe GitlabSchema.types['ClusterAgentToken'] do
-  let(:fields) { %i[cluster_agent created_at created_by_user description id name] }
+  let(:fields) { %i[cluster_agent created_at created_by_user description id last_used_at name] }
 
   it { expect(described_class.graphql_name).to eq('ClusterAgentToken') }
 

lib/api/internal/kubernetes.rb

@@ -54,6 +54,8 @@ module API
           forbidden! unless agent_token
 
           forbidden! unless Gitlab::Kas.included_in_gitlab_com_rollout?(agent.project)
+
+          agent_token.track_usage
         end
       end
 

spec/models/clusters/agent_token_spec.rb

@@ -24,4 +24,53 @@ RSpec.describe Clusters::AgentToken do
       expect(agent_token.token.length).to be >= 50
     end
   end
+
+  describe '#track_usage', :clean_gitlab_redis_cache do
+    let(:agent_token) { create(:cluster_agent_token) }
+
+    subject { agent_token.track_usage }
+
+    context 'when last_used_at was updated recently' do
+      before do
+        agent_token.update!(last_used_at: 10.minutes.ago)
+      end
+
+      it 'updates cache but not database' do
+        expect { subject }.not_to change { agent_token.reload.read_attribute(:last_used_at) }
+
+        expect_redis_update
+      end
+    end
+
+    context 'when last_used_at was not updated recently' do
+      it 'updates cache and database' do
+        does_db_update
+        expect_redis_update
+      end
+
+      context 'with invalid token' do
+        before do
+          agent_token.description = SecureRandom.hex(2000)
+        end
+
+        it 'still updates caches and database' do
+          expect(agent_token).to be_invalid
+
+          does_db_update
+          expect_redis_update
+        end
+      end
+    end
+
+    def expect_redis_update
+      Gitlab::Redis::Cache.with do |redis|
+        redis_key = "cache:#{described_class.name}:#{agent_token.id}:attributes"
+        expect(redis.get(redis_key)).to be_present
+      end
+    end
+
+    def does_db_update
+      expect { subject }.to change { agent_token.reload.read_attribute(:last_used_at) }
+    end
+  end
 end

spec/requests/api/internal/kubernetes_spec.rb

@@ -51,6 +51,12 @@ RSpec.describe API::Internal::Kubernetes do
     end
   end
 
+  shared_examples 'agent token tracking' do
+    it 'tracks token usage' do
+      expect { response }.to change { agent_token.reload.read_attribute(:last_used_at) }
+    end
+  end
+
   describe 'POST /internal/kubernetes/usage_metrics' do
     def send_request(headers: {}, params: {})
       post api('/internal/kubernetes/usage_metrics'), params: params, headers: headers.reverse_merge(jwt_auth_headers)
@@ -101,6 +107,8 @@ RSpec.describe API::Internal::Kubernetes do
       let(:agent) { agent_token.agent }
       let(:project) { agent.project }
 
+      shared_examples 'agent token tracking'
+
       it 'returns expected data', :aggregate_failures do
         send_request(headers: { 'Authorization' => "Bearer #{agent_token.token}" })
 
@@ -169,6 +177,8 @@ RSpec.describe API::Internal::Kubernetes do
     context 'an agent is found' do
       let_it_be(:agent_token) { create(:cluster_agent_token) }
 
+      shared_examples 'agent token tracking'
+
       context 'project is public' do
         let(:project) { create(:project, :public) }