🚀 Add new Agent Token controller

.changes/unreleased/FEATURES-628-20250925-091657.yaml

@@ -0,0 +1,5 @@
+kind: FEATURES
+body: '`AgentToken`: Introduce a new controller that manages tokens in arbitrary agent pools.'
+time: 2025-09-25T09:16:57.344633+02:00
+custom:
+    PR: "628"

.github/pr-labeler.yml

@@ -8,7 +8,8 @@ controller:
 - any:
   - changed-files:
     - any-glob-to-any-file:
-      - 'controllers/*.go'
+      - 'internal/controller/*.go'
+      - 'cmd/*.go'
 
 crd:
 - any:

.github/workflows/helm-end-to-end-tfc.yaml

@@ -81,6 +81,7 @@ jobs:
             --set operator.image.tag=${{ env.DOCKER_METADATA_OUTPUT_VERSION }} \
             --set operator.syncPeriod=30s \
             --set controllers.agentPool.workers=5 \
+            --set controllers.agentToken.workers=5 \
             --set controllers.module.workers=5 \
             --set controllers.project.workers=5 \
             --set controllers.workspace.workers=5

.github/workflows/helm-end-to-end-tfe.yaml

@@ -83,6 +83,7 @@ jobs:
             --set operator.tfeAddress=${{ secrets.TFE_ADDRESS }} \
             --set operator.syncPeriod=30s \
             --set controllers.agentPool.workers=5 \
+            --set controllers.agentToken.workers=5 \
             --set controllers.module.workers=5 \
             --set controllers.project.workers=5 \
             --set controllers.workspace.workers=5

PROJECT

@@ -47,4 +47,13 @@ resources:
   kind: Project
   path: github.com/hashicorp/hcp-terraform-operator/api/v1alpha2
   version: v1alpha2
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: terraform.io
+  group: app
+  kind: AgentToken
+  path: github.com/hashicorp/hcp-terraform-operator/api/v1alpha2
+  version: v1alpha2
 version: "3"

README.md

@@ -16,6 +16,7 @@ Kubernetes Operator allows managing HCP Terraform / Terraform Enterprise resourc
 The Operator can manage the following types of resources:
 
 - `AgentPool` manages [HCP Terraform Agent Pools](https://developer.hashicorp.com/terraform/cloud-docs/agents/agent-pools), [HCP Terraform Agent Tokens](https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/api-tokens#agent-api-tokens) and can perform TFC agent scaling
+- `AgentToken` manages [HCP Terraform Agent Tokens](https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/api-tokens#agent-api-tokens)
 - `Module` implements [API-driven Run Workflows](https://developer.hashicorp.com/terraform/cloud-docs/run/api)
 - `Project` manages [HCP Terraform Projects](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/organize-workspaces-with-projects)
 - `Workspace` manages [HCP Terraform Workspaces](https://developer.hashicorp.com/terraform/cloud-docs/workspaces)
@@ -56,6 +57,7 @@ General usage documentation can be found [here](./docs/usage.md).
 Controllers usage guides:
 
 - [AgentPool](./docs/agentpool.md)
+- [AgentToken](./docs/agenttoken.md)
 - [Module](./docs/module.md)
 - [Project](./docs/project.md)
 - [Workspace](./docs/workspace.md)
@@ -110,6 +112,7 @@ If you encounter any issues with the Operator there are a number of ways how to
 
     ```console
     $ kubectl get agentpool <NAME>
+    $ kubectl get agenttoken <NAME>
     $ kubectl get module <NAME>
     $ kubectl get project <NAME>
     $ kubectl get workspace <NAME>
@@ -119,6 +122,7 @@ If you encounter any issues with the Operator there are a number of ways how to
 
     ```console
     $ kubectl describe agentpool <NAME>
+    $ kubectl describe agenttoken <NAME>
     $ kubectl describe module <NAME>
     $ kubectl describe project <NAME>
     $ kubectl describe workspace <NAME>

api/v1alpha2/agentpool_types.go

@@ -23,7 +23,7 @@ const (
 // In `spec` only the field `Name` is allowed, the rest are used in `status`.
 // More infromation:
 //   - https://developer.hashicorp.com/terraform/cloud-docs/agents
-type AgentToken struct {
+type AgentAPIToken struct {
 	// Agent Token name.
 	//
 	//+kubebuilder:validation:MinLength:=1
@@ -135,7 +135,7 @@ type AgentPoolSpec struct {
 	//
 	//+kubebuilder:validation:MinItems:=1
 	//+optional
-	AgentTokens []*AgentToken `json:"agentTokens,omitempty"`
+	AgentTokens []*AgentAPIToken `json:"agentTokens,omitempty"`
 
 	// Agent deployment settings
 	//+optional
@@ -179,7 +179,7 @@ type AgentPoolStatus struct {
 	// List of the agent tokens generated by the controller.
 	//
 	//+optional
-	AgentTokens []*AgentToken `json:"agentTokens,omitempty"`
+	AgentTokens []*AgentAPIToken `json:"agentTokens,omitempty"`
 	// Name of the agent deployment generated by the controller.
 	//
 	//+optional

api/v1alpha2/agentpool_validation_test.go

@@ -15,7 +15,7 @@ func TestValidateAgentPoolSpecAgentToken(t *testing.T) {
 	successCases := map[string]AgentPool{
 		"HasOnlyName": {
 			Spec: AgentPoolSpec{
-				AgentTokens: []*AgentToken{
+				AgentTokens: []*AgentAPIToken{
 					{
 						Name: "this",
 					},
@@ -24,7 +24,7 @@ func TestValidateAgentPoolSpecAgentToken(t *testing.T) {
 		},
 		"HasMultipleTokens": {
 			Spec: AgentPoolSpec{
-				AgentTokens: []*AgentToken{
+				AgentTokens: []*AgentAPIToken{
 					{
 						Name: "this",
 					},
@@ -47,7 +47,7 @@ func TestValidateAgentPoolSpecAgentToken(t *testing.T) {
 	errorCases := map[string]AgentPool{
 		"HasID": {
 			Spec: AgentPoolSpec{
-				AgentTokens: []*AgentToken{
+				AgentTokens: []*AgentAPIToken{
 					{
 						Name: "this",
 						ID:   "this",
@@ -57,7 +57,7 @@ func TestValidateAgentPoolSpecAgentToken(t *testing.T) {
 		},
 		"HasCreatedAt": {
 			Spec: AgentPoolSpec{
-				AgentTokens: []*AgentToken{
+				AgentTokens: []*AgentAPIToken{
 					{
 						Name:      "this",
 						CreatedAt: pointer.PointerOf(int64(1984)),
@@ -67,7 +67,7 @@ func TestValidateAgentPoolSpecAgentToken(t *testing.T) {
 		},
 		"HasLastUsedAt": {
 			Spec: AgentPoolSpec{
-				AgentTokens: []*AgentToken{
+				AgentTokens: []*AgentAPIToken{
 					{
 						Name:       "this",
 						LastUsedAt: pointer.PointerOf(int64(1984)),
@@ -77,7 +77,7 @@ func TestValidateAgentPoolSpecAgentToken(t *testing.T) {
 		},
 		"HasDuplicateName": {
 			Spec: AgentPoolSpec{
-				AgentTokens: []*AgentToken{
+				AgentTokens: []*AgentAPIToken{
 					{
 						Name: "this",
 					},

api/v1alpha2/agenttoken_types.go

@@ -0,0 +1,113 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package v1alpha2
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// The Management Policy defines how the controller will manage tokens in the specified Agent Pool.
+// - `merge`  — the controller will manage its tokens alongside any existing tokens in the pool, without modifying or deleting tokens it does not own.
+// - `owner`  — the controller assumes full ownership of all agent tokens in the pool, managing and potentially modifying or deleting all tokens, including those not created by it.
+type AgentTokenManagementPolicy string
+
+const (
+	AgentTokenManagementPolicyMerge AgentTokenManagementPolicy = "merge"
+	AgentTokenManagementPolicyOwner AgentTokenManagementPolicy = "owner"
+)
+
+// The Deletion Policy defines how managed tokens and Kubernetes Secrets should be handled when the custom resource is deleted.
+//   - `retain`: When the custom resource is deleted, the operator will remove only the resource itself.
+//     The managed HCP Terraform Agent tokens will remain active on the HCP Terraform side, and the corresponding Kubernetes Secret will not be modified.
+//   - `destroy`: The operator will attempt to delete the managed HCP Terraform Agent tokens and remove the corresponding Kubernetes Secret.
+type AgentTokenDeletionPolicy string
+
+const (
+	AgentTokenDeletionPolicyRetain  AgentTokenDeletionPolicy = "retain"
+	AgentTokenDeletionPolicyDestroy AgentTokenDeletionPolicy = "destroy"
+)
+
+// AgentTokenSpec defines the desired state of AgentToken.
+type AgentTokenSpec struct {
+	// Organization name where the Workspace will be created.
+	// More information:
+	//   - https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/organizations
+	//
+	//+kubebuilder:validation:MinLength:=1
+	Organization string `json:"organization"`
+	// API Token to be used for API calls.
+	Token Token `json:"token"`
+	// The Deletion Policy defines how managed tokens and Kubernetes Secrets should be handled when the custom resource is deleted.
+	// - `retain`: When the custom resource is deleted, the operator will remove only the resource itself.
+	//   The managed HCP Terraform Agent tokens will remain active on the HCP Terraform side, and the corresponding Kubernetes Secret will not be modified.
+	// - `destroy`: The operator will attempt to delete the managed HCP Terraform Agent tokens and remove the corresponding Kubernetes Secret.
+	// Default: `retain`.
+	//
+	//+kubebuilder:validation:Enum:=retain;destroy
+	//+kubebuilder:default=retain
+	//+optional
+	DeletionPolicy AgentTokenDeletionPolicy `json:"deletionPolicy,omitempty"`
+	// The Agent Pool name or ID where the tokens will be managed.
+	AgentPool AgentPoolRef `json:"agentPool"`
+	// The Management Policy defines how the controller will manage tokens in the specified Agent Pool.
+	// - `merge`  — the controller will manage its tokens alongside any existing tokens in the pool, without modifying or deleting tokens it does not own.
+	// - `owner`  — the controller assumes full ownership of all agent tokens in the pool, managing and potentially modifying or deleting all tokens, including those not created by it.
+	// Default: `merge`.
+	//
+	//+kubebuilder:validation:Enum:=merge;owner
+	//+kubebuilder:default=merge
+	//+optional
+	ManagementPolicy AgentTokenManagementPolicy `json:"managementPolicy,omitempty"`
+	// List of the HCP Terraform Agent tokens to manage.
+	//
+	//+kubebuilder:validation:MinItems:=1
+	AgentTokens []AgentAPIToken `json:"agentTokens"`
+	// secretName specifies the name of the Kubernetes Secret
+	// where the HCP Terraform Agent tokens are stored.
+	//
+	//+kubebuilder:validation:MinLength:=1
+	SecretName string `json:"secretName"`
+}
+
+// AgentTokenStatus defines the observed state of AgentToken.
+type AgentTokenStatus struct {
+	// Real world state generation.
+	ObservedGeneration int64 `json:"observedGeneration"`
+	// Agent Pool where tokens are managed by the controller.
+	AgentPool *AgentPoolRef `json:"agentPool,omitempty"`
+	// List of the agent tokens managed by the controller.
+	//
+	//+optional
+	AgentTokens []*AgentAPIToken `json:"agentTokens,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+//+kubebuilder:printcolumn:name="Agent Pool Name",type=string,JSONPath=`.status.agentPool.name`
+//+kubebuilder:printcolumn:name="Agent Pool ID",type=string,JSONPath=`.status.agentPool.id`
+//+kubebuilder:metadata:labels="app.terraform.io/crd-schema-version=v25.9.0"
+
+// AgentToken manages HCP Terraform Agent Tokens.
+// More information:
+// - https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/api-tokens#agent-api-tokens
+type AgentToken struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec   AgentTokenSpec   `json:"spec"`
+	Status AgentTokenStatus `json:"status,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+
+// AgentTokenList contains a list of AgentToken.
+type AgentTokenList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []AgentToken `json:"items"`
+}
+
+func init() {
+	SchemeBuilder.Register(&AgentToken{}, &AgentTokenList{})
+}

api/v1alpha2/agenttoken_validation.go

@@ -0,0 +1,63 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package v1alpha2
+
+import (
+	"fmt"
+
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/runtime/schema"
+	"k8s.io/apimachinery/pkg/util/validation/field"
+)
+
+func (t *AgentToken) ValidateSpec() error {
+	var allErrs field.ErrorList
+
+	allErrs = append(allErrs, t.validateSpecAgentTokens()...)
+
+	if len(allErrs) == 0 {
+		return nil
+	}
+
+	return apierrors.NewInvalid(
+		schema.GroupKind{Group: "", Kind: "AgentToken"},
+		t.Name,
+		allErrs,
+	)
+}
+
+func (t *AgentToken) validateSpecAgentTokens() field.ErrorList {
+	allErrs := field.ErrorList{}
+	atn := make(map[string]int)
+
+	for i, at := range t.Spec.AgentTokens {
+		f := field.NewPath("spec").Child(fmt.Sprintf("agentTokens[%d]", i))
+
+		if at.ID != "" {
+			allErrs = append(allErrs, field.Forbidden(
+				f.Child("id"),
+				"id is not allowed in the spec"),
+			)
+		}
+		if at.CreatedAt != nil {
+			allErrs = append(allErrs, field.Forbidden(
+				f.Child("createdAt"),
+				"createdAt is not allowed in the spec"),
+			)
+		}
+		if at.LastUsedAt != nil {
+			allErrs = append(allErrs, field.Forbidden(
+				f.Child("lastUsedAt"),
+				"lastUsedAt is not allowed in the spec"),
+			)
+		}
+
+		if _, ok := atn[at.Name]; ok {
+			allErrs = append(allErrs, field.Duplicate(f.Child("name"), at.Name))
+		}
+		atn[at.Name] = i
+	}
+
+	return allErrs
+}