Add cluster name and description to CyberArk Discovery and Context snapshot

- Add ClusterName and ClusterDescription fields to Snapshot struct
- Populate these fields from Options in PostDataReadingsWithOptions
- Add clusterName and clusterDescription Helm values and docs
- Populate cluster_id and cluster_description in the rendered configmap
- Update values.schema.json to include descriptions for the new values
- Add ClusterDescription field to pkg/agent Config and CombinedConfig
- Default MachineHub cluster ID from ARK_USERNAME env when not set
- Clarify comments and add TODO about ClusterID vs ClusterName naming

Signed-off-by: Richard Wall <[email protected]>

Author: wallrj-cyberark

deploy/charts/disco-agent/README.md

@@ -277,6 +277,24 @@ Example: excludeAnnotationKeysRegex: ['^kapp\.k14s\.io/original.*']
 > ```yaml
 > []
 > ```
+#### **config.clusterName** ~ `string`
+> Default value:
+> ```yaml
+> ""
+> ```
+
+A human readable name for the cluster where the agent is deployed (optional).  
+  
+This cluster name will be associated with the data that the agent uploads to the Discovery and Context service. If empty (the default), the service account name will be used instead.
+#### **config.clusterDescription** ~ `string`
+> Default value:
+> ```yaml
+> ""
+> ```
+
+A short description of the cluster where the agent is deployed (optional).  
+  
+This description will be associated with the data that the agent uploads to the Discovery and Context service. The description should include contact information such as the email address of the cluster administrator, so that any problems and risks identified by the Discovery and Context service can be communicated to the people responsible for the affected secrets.
 #### **authentication.secretName** ~ `string`
 > Default value:
 > ```yaml

deploy/charts/disco-agent/templates/configmap.yaml

@@ -7,6 +7,8 @@ metadata:
     {{- include "disco-agent.labels" . | nindent 4 }}
 data:
   config.yaml: |-
+    cluster_id: {{ .Values.config.clusterName | quote }}
+    cluster_description: {{ .Values.config.clusterDescription | quote }}
     period: {{ .Values.config.period | quote }}
     {{- with .Values.config.excludeAnnotationKeysRegex }}
     exclude-annotation-keys-regex:

deploy/charts/disco-agent/values.schema.json

@@ -104,6 +104,12 @@
     "helm-values.config": {
       "additionalProperties": false,
       "properties": {
+        "clusterDescription": {
+          "$ref": "#/$defs/helm-values.config.clusterDescription"
+        },
+        "clusterName": {
+          "$ref": "#/$defs/helm-values.config.clusterName"
+        },
         "excludeAnnotationKeysRegex": {
           "$ref": "#/$defs/helm-values.config.excludeAnnotationKeysRegex"
         },
@@ -116,6 +122,16 @@
       },
       "type": "object"
     },
+    "helm-values.config.clusterDescription": {
+      "default": "",
+      "description": "A short description of the cluster where the agent is deployed (optional).\n\nThis description will be associated with the data that the agent uploads to the Discovery and Context service. The description should include contact information such as the email address of the cluster administrator, so that any problems and risks identified by the Discovery and Context service can be communicated to the people responsible for the affected secrets.",
+      "type": "string"
+    },
+    "helm-values.config.clusterName": {
+      "default": "",
+      "description": "A human readable name for the cluster where the agent is deployed (optional).\n\nThis cluster name will be associated with the data that the agent uploads to the Discovery and Context service. If empty (the default), the service account name will be used instead.",
+      "type": "string"
+    },
     "helm-values.config.excludeAnnotationKeysRegex": {
       "default": [],
       "description": "You can configure the agent to exclude some annotations or labels from being pushed . All Kubernetes objects are affected. The objects are still pushed, but the specified annotations and labels are removed before being pushed.\n\nDots is the only character that needs to be escaped in the regex. Use either double quotes with escaped single quotes or unquoted strings for the regex to avoid YAML parsing issues with `\\.`.\n\nExample: excludeAnnotationKeysRegex: ['^kapp\\.k14s\\.io/original.*']",

deploy/charts/disco-agent/values.yaml

@@ -138,6 +138,22 @@ config:
   excludeAnnotationKeysRegex: []
   excludeLabelKeysRegex: []
 
+  # A human readable name for the cluster where the agent is deployed (optional).
+  #
+  # This cluster name will be associated with the data that the agent uploads to
+  # the Discovery and Context service. If empty (the default), the service
+  # account name will be used instead.
+  clusterName: ""
+
+  # A short description of the cluster where the agent is deployed (optional).
+  #
+  # This description will be associated with the data that the agent uploads to
+  # the Discovery and Context service. The description should include contact
+  # information such as the email address of the cluster administrator, so that
+  # any problems and risks identified by the Discovery and Context service can
+  # be communicated to the people responsible for the affected secrets.
+  clusterDescription: ""
+
 authentication:
   secretName: agent-credentials
 

internal/cyberark/dataupload/dataupload.go

@@ -51,6 +51,10 @@ type Snapshot struct {
 	AgentVersion string `json:"agent_version"`
 	// ClusterID is the unique ID of the Kubernetes cluster which this snapshot was taken from.
 	ClusterID string `json:"cluster_id"`
+	// ClusterName is the name of the Kubernetes cluster which this snapshot was taken from.
+	ClusterName string `json:"cluster_name"`
+	// ClusterDescription is an optional description of the Kubernetes cluster which this snapshot was taken from.
+	ClusterDescription string `json:"cluster_description,omitempty"`
 	// K8SVersion is the version of Kubernetes which the cluster is running.
 	K8SVersion string `json:"k8s_version"`
 	// Secrets is a list of Secret resources in the cluster. Not all Secret

pkg/agent/config.go

@@ -49,7 +49,13 @@ type Config struct {
 	OrganizationID string `yaml:"organization_id"`
 
 	// ClusterID is the cluster that the agent is scanning. Used in all modes.
-	ClusterID          string             `yaml:"cluster_id"`
+	//
+	// TODO(wallrj): ClusterID and ClusterName have become somewhat confusing
+	// naming-wise. We should consider renaming ClusterID to ClusterName
+	ClusterID string `yaml:"cluster_id"`
+	// ClusterDescription is a short description of the cluster. It should
+	// contain contact details of the cluster administrator, so that any risks
+	// identified by the backend can be communicated.
 	ClusterDescription string             `yaml:"cluster_description"`
 	DataGatherers      []DataGatherer     `yaml:"data-gatherers"`
 	VenafiCloud        *VenafiCloudConfig `yaml:"venafi-cloud,omitempty"`
@@ -340,8 +346,8 @@ const (
 	MachineHub                  OutputMode = "MachineHub"
 )
 
-// The command-line flags and the config file are combined into this struct by
-// ValidateAndCombineConfig.
+// The command-line flags and the config file and some environment variables are
+// combined into this struct by ValidateAndCombineConfig.
 type CombinedConfig struct {
 	DataGatherers  []DataGatherer
 	Period         time.Duration
@@ -352,7 +358,10 @@ type CombinedConfig struct {
 
 	OutputMode OutputMode
 
-	// Used by all TLSPK modes.
+	// Used by all modes.
+	//
+	// TODO(wallrj): ClusterID and ClusterName have become somewhat confusing
+	// consider renaming ClusterID to ClusterName.
 	ClusterID string
 
 	// Used by JetstackSecureOAuth, JetstackSecureAPIToken, and
@@ -364,7 +373,11 @@ type CombinedConfig struct {
 	EndpointPath   string // Deprecated.
 
 	// VenafiCloudKeypair mode only.
-	UploadPath         string
+	UploadPath string
+
+	// ClusterDescription is a short description of the cluster. It should
+	// contain contact details of the cluster administrator so that risks identified
+	// by the backend can be communicated.
 	ClusterDescription string
 
 	// VenafiCloudVenafiConnection mode only.
@@ -557,8 +570,11 @@ func ValidateAndCombineConfig(log logr.Logger, cfg Config, flags AgentCmdFlags)
 			organizationID = cfg.OrganizationID
 			clusterID = cfg.ClusterID
 		case MachineHub:
-			if cfg.ClusterID != "" {
-				log.Info(fmt.Sprintf(`Ignoring the cluster_id field in the config file. This field is not needed in %s mode.`, res.OutputMode))
+			clusterID = cfg.ClusterID
+			if clusterID == "" {
+				if arkUsername, found := os.LookupEnv("ARK_USERNAME"); found {
+					clusterID = arkUsername
+				}
 			}
 			if cfg.OrganizationID != "" {
 				log.Info(fmt.Sprintf(`Ignoring the organization_id field in the config file. This field is not needed in %s mode.`, res.OutputMode))

pkg/client/client_cyberark.go

@@ -52,18 +52,20 @@ func NewCyberArk(httpClient *http.Client) (*CyberArkClient, error) {
 // It initializes a data upload client with the configured HTTP client and credentials,
 // then uploads a snapshot.
 // The supplied Options are not used by this publisher.
-func (o *CyberArkClient) PostDataReadingsWithOptions(ctx context.Context, readings []*api.DataReading, _ Options) error {
+func (o *CyberArkClient) PostDataReadingsWithOptions(ctx context.Context, readings []*api.DataReading, opts Options) error {
 	log := klog.FromContext(ctx)
-	var snapshot dataupload.Snapshot
+	snapshot := dataupload.Snapshot{
+		ClusterName:        opts.ClusterName,
+		ClusterDescription: opts.ClusterDescription,
+		AgentVersion:       version.PreflightVersion,
+	}
 	if err := convertDataReadings(defaultExtractorFunctions, readings, &snapshot); err != nil {
 		return fmt.Errorf("while converting data readings: %s", err)
 	}
 
 	// Minimize the snapshot to reduce size and improve privacy
 	minimizeSnapshot(log.V(logs.Debug), &snapshot)
 
-	snapshot.AgentVersion = version.PreflightVersion
-
 	cfg, err := o.configLoader()
 	if err != nil {
 		return err