Add a new Runs Collector controller (#637)

Author: arybolovlev

.changes/unreleased/FEATURES-637-20250922-132243.yaml

@@ -0,0 +1,5 @@
+kind: FEATURES
+body: '`RunsCollector`: Introduce a new controller that scrapes HCP Terraform run statuses from a specified Agent Pool and exposes them as Prometheus-compatible metrics.'
+time: 2025-09-22T13:22:43.774802+02:00
+custom:
+    PR: "637"

.changes/unreleased/NOTES-637-20250922-132629.yaml

@@ -0,0 +1,5 @@
+kind: NOTES
+body: '`RunsCollector`: Add new Prometheus-compatible metrics `hcp_tf_runs` and `hcp_tf_runs_total` to collect pending runs by status and the total number of pending runs by status, respectively. These metrics are in the alpha stage and subject to change.'
+time: 2025-09-22T13:26:29.977557+02:00
+custom:
+    PR: "637"

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

@@ -84,6 +84,7 @@ jobs:
             --set controllers.agentToken.workers=5 \
             --set controllers.module.workers=5 \
             --set controllers.project.workers=5 \
+            --set controllers.runsCollector.workers=5 \
             --set controllers.workspace.workers=5
 
       - name: Run end-to-end test suite

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

@@ -86,6 +86,7 @@ jobs:
             --set controllers.agentToken.workers=5 \
             --set controllers.module.workers=5 \
             --set controllers.project.workers=5 \
+            --set controllers.runsCollector.workers=5 \
             --set controllers.workspace.workers=5
 
       - name: Run end-to-end test suite

Dockerfile

@@ -7,7 +7,7 @@
 # Every target has a BIN_NAME argument that must be provided via --build-arg=BIN_NAME=<name>
 # when building.
 
-ARG GO_VERSION=1.24.3
+ARG GO_VERSION=1.25.1
 
 # ===================================
 #

Makefile

@@ -249,7 +249,7 @@ YQ = $(LOCALBIN)/yq-$(YQ_VERSION)
 KUSTOMIZE_VERSION ?= v5.3.0
 CONTROLLER_TOOLS_VERSION ?= v0.16.5
 ENVTEST_VERSION ?= release-0.19
-CRD_REF_DOCS_VERSION ?= v0.1.0
+CRD_REF_DOCS_VERSION ?= v0.2.0
 HELM_DOCS_VERSION ?= v1.14.2
 HASHICORP_COPYWRITE_VERSION ?= v0.19.0
 GOLANGCI_LINT_VERSION ?= v1.61.0

PROJECT

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

README.md

@@ -19,6 +19,7 @@ The Operator can manage the following types of resources:
 - `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)
+- `Runs Collector` Runs scrapes HCP Terraform run statuses from a given Agent Pool and exposes them as Prometheus-compatible metrics. Learn more about [Runs](https://developer.hashicorp.com/terraform/cloud-docs/run/remote-operations).
 - `Workspace` manages [HCP Terraform Workspaces](https://developer.hashicorp.com/terraform/cloud-docs/workspaces)
 
 ## Getting started
@@ -60,6 +61,7 @@ Controllers usage guides:
 - [AgentToken](./docs/agenttoken.md)
 - [Module](./docs/module.md)
 - [Project](./docs/project.md)
+- [Runs Collector](./docs/runs_collector.md)
 - [Workspace](./docs/workspace.md)
 
 Annotations and Labels used by HCP Terraform Operator can be found [here](./docs/annotations-and-labels.md).
@@ -115,6 +117,7 @@ If you encounter any issues with the Operator there are a number of ways how to
     $ kubectl get agenttoken <NAME>
     $ kubectl get module <NAME>
     $ kubectl get project <NAME>
+    $ kubectl get runscollector <NAME>
     $ kubectl get workspace <NAME>
     ```
 
@@ -125,6 +128,7 @@ If you encounter any issues with the Operator there are a number of ways how to
     $ kubectl describe agenttoken <NAME>
     $ kubectl describe module <NAME>
     $ kubectl describe project <NAME>
+    $ kubectl describe runscollector <NAME>
     $ kubectl describe workspace <NAME>
     ```
 

api/v1alpha2/project_types.go

@@ -193,7 +193,7 @@ type ProjectStatus struct {
 
 // Project manages HCP Terraform Projects.
 // More information:
-// - https://developer.hashicorp.com/terraform/cloud-docs/projects/manage
+//   - https://developer.hashicorp.com/terraform/cloud-docs/projects/manage
 type Project struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`

api/v1alpha2/runscollector_types.go

@@ -0,0 +1,61 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package v1alpha2
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+type RunsCollectorSpec 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 Agent Pool name or ID from which the controller will collect runs.
+	// More information:
+	//   - https://developer.hashicorp.com/terraform/cloud-docs/run/states
+	AgentPool *AgentPoolRef `json:"agentPool"`
+}
+
+type RunsCollectorStatus struct {
+	// Real world state generation.
+	ObservedGeneration int64 `json:"observedGeneration"`
+	// The Agent Pool name or ID from which the controller will collect runs.
+	AgentPool *AgentPoolRef `json:"agentPool,omitempty"`
+}
+
+//+kubebuilder:object:root=true
+//+kubebuilder:subresource:status
+//+kubebuilder:printcolumn:name="Pool ID",type=string,JSONPath=`.status.pool.ID`
+//+kubebuilder:printcolumn:name="Pool Name",type=string,JSONPath=`.status.pool.Name`
+//+kubebuilder:metadata:labels="app.terraform.io/crd-schema-version=v25.9.0"
+
+// Runs Collector scraptes HCP Terraform Run statuses from a given Agent Pool and exposes them as Prometheus-compatible metrics.
+// More information:
+//   - https://developer.hashicorp.com/terraform/cloud-docs/run/remote-operations
+type RunsCollector struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec   RunsCollectorSpec   `json:"spec"`
+	Status RunsCollectorStatus `json:"status,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+
+// RunsCollectorList contains a list of RunsCollector.
+type RunsCollectorList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []RunsCollector `json:"items"`
+}
+
+func init() {
+	SchemeBuilder.Register(&RunsCollector{}, &RunsCollectorList{})
+}