chore(backport release-1.4): feat: allow specifying a token for job metric logs access + docs (#3779)

Co-authored-by: Kent Rancourt <[email protected]>

Author: akuitybot

charts/kargo/README.md

@@ -137,6 +137,8 @@ the Kargo controller is running.
 | `api.rollouts.integrationEnabled`           | Specifies whether Argo Rollouts integration is enabled. When not enabled, the API server will not be capable of creating/updating/applying AnalysesTemplate resources in the Kargo control plane. When enabled, the API server will perform a sanity check at startup. If Argo Rollouts CRDs are not found, the API server will proceed as if this integration had been explicitly disabled. Explicitly disabling is still preferable if this integration is not desired, as it will grant fewer permissions to the API server.                                                                                                                    | `true`                   |
 | `api.rollouts.logs.enabled`                 | Specifies whether support for streaming logs from AnalysisRuns using a JobMetric provider is enabled. This feature requires you to have forwarded and stored the logs yourself in a place where they can be retrieved with an HTTP GET.                                                                                                                                                                                                                                                                                                                                                                                                            | `false`                  |
 | `api.rollouts.logs.urlTemplate`             | Instructs Kargo on how to construct a URL for the retrieval of relevant logs via HTTP GET. Expressions offset by ${{ }} are supported with the following variables pre-defined and injected with values: project, namespace (the Project namespace), stage, analysisRun (its name), metricName (name of the JobMetric), jobNamespace (namespace of the Job; may be different that the Project namespace as the Job may actually execute in a different cluster), jobName, container (since a Pod associated with a Job could have more than one). Example: "https://logs.kargo.example.com/${{project}}/${{analysisRun}}/${{job}}/${{container}}". | `""`                     |
+| `api.rollouts.logs.tokenSecret.name`        | specifies the name of a Kubernetes Secret managed "out of band" that contains a token usable for accessing job metric logs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `nil`                    |
+| `api.rollouts.logs.tokenSecret.key`         | specifies the key in a Kubernetes Secret (named by name) that is managed "out of band" and contains a token usable for accessing job metric logs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `nil`                    |
 | `api.rollouts.logs.httpHeaders`             | Specifies HTTP headers to include in the HTTP GET request for log retrieval. These are typically used for authentication. The header values support expressions offset by ${{ }}, with the same variables documented for urlTemplate pre-defined and injected with values.                                                                                                                                                                                                                                                                                                                                                                         | `{}`                     |
 
 ### Controller

charts/kargo/templates/api/deployment.yaml

@@ -75,6 +75,13 @@ spec:
           {{- with (concat .Values.global.env .Values.api.env) }}
           {{- toYaml . | nindent 10 }}
           {{- end }}
+          {{- if and .Values.api.rollouts.integrationEnabled .Values.api.rollouts.logs.enabled .Values.api.rollouts.logs.tokenSecret.name .Values.api.rollouts.logs.tokenSecret.key }}
+          - name: ANALYSIS_RUN_LOG_TOKEN
+            valueFrom:
+              secretKeyRef:
+                name: {{ .Values.api.rollouts.logs.tokenSecret.name }}
+                key: {{ .Values.api.rollouts.logs.tokenSecret.key }}
+          {{- end }}
           envFrom:
           - configMapRef:
               name: kargo-api

charts/kargo/values.yaml

@@ -357,6 +357,11 @@ api:
       enabled: false
       ## @param api.rollouts.logs.urlTemplate Instructs Kargo on how to construct a URL for the retrieval of relevant logs via HTTP GET. Expressions offset by ${{ }} are supported with the following variables pre-defined and injected with values: project, namespace (the Project namespace), stage, analysisRun (its name), metricName (name of the JobMetric), jobNamespace (namespace of the Job; may be different that the Project namespace as the Job may actually execute in a different cluster), jobName, container (since a Pod associated with a Job could have more than one). Example: "https://logs.kargo.example.com/${{project}}/${{analysisRun}}/${{job}}/${{container}}".
       urlTemplate: ""
+      tokenSecret:
+        ## @param api.rollouts.logs.tokenSecret.name specifies the name of a Kubernetes Secret managed "out of band" that contains a token usable for accessing job metric logs.
+        name:
+        ## @param api.rollouts.logs.tokenSecret.key specifies the key in a Kubernetes Secret (named by name) that is managed "out of band" and contains a token usable for accessing job metric logs.
+        key:
       ## @param api.rollouts.logs.httpHeaders Specifies HTTP headers to include in the HTTP GET request for log retrieval. These are typically used for authentication. The header values support expressions offset by ${{ }}, with the same variables documented for urlTemplate pre-defined and injected with values.
       httpHeaders: {}
 

docs/docs/40-operator-guide/20-advanced-installation/30-common-configurations.md

@@ -349,6 +349,64 @@ is preferred if this integration is not desired, as it will grant fewer
 permissions to the controller.
 :::
 
+### Logs from Job Metrics
+
+For those utilizing Argo Rollouts integration for verifications,
+[job metrics](https://argoproj.github.io/argo-rollouts/analysis/job/) stand out
+as an especially useful feature because they are implemented as Kubernetes
+[`Job`s](https://kubernetes.io/docs/concepts/workloads/controllers/job/), which
+give users the flexibility to define any arbitrary post-promotion tests they'd
+like to run against a `Stage` by simply providing appropriate `Job` specs
+[as described here](../../50-user-guide/20-how-to-guides/60-verification.md#configuring-analysistemplates).
+In cases such as these, access to logs produced by the `Job`'s underlying `Pod`
+is helpful for debugging purposes and for understanding results.
+
+Since it's common for multiple Kargo controllers to be deployed to many
+different clusters, such logs need to be aggregated in a centralized location
+for the API server to access them and, in-turn, stream them to the Kargo UI or
+CLI. Rather than build support for many different logging stacks, Kargo has
+settled on a "lowest common denominator" approach: The API server can stream
+any logs that it can access via an HTTP GET request.
+
+To facilitate this, operators may, at the time of installation, provide a URL
+template that the API server can use to construct the URL for any job metric logs
+as a function of attributes such as `Project` name, `Stage` name, `AnalysisRun`
+name, and more.
+
+A token can be specified by referencing a Kubernetes `Secret` that is managed
+"out of band." HTTP headers may also be specified, and may reference the token
+if one is provided.
+
+Example:
+
+```yaml
+api:
+  rollouts:
+    integrationEnabled: true
+    logs:
+      enabled: true
+      urlTemplate: https://logs.kargo.example.com/${{project}}/${{analysisRun}}/${{job}}/${{container}}
+      tokenSecret:
+        name: kargo-logs-token
+        key: token
+      httpHeaders:
+        Authentication: "Bearer ${{ token }}"
+```
+
+:::note
+This "lowest common denominator" approach to streaming job metric logs does
+leave it as an exercise for the Kargo administrator to arrange for the
+forwarding and storage of applicable logs.
+
+Users of Kargo via the [Akuity Platform](https://akuity.io/akuity-platform),
+however, will have this seamlessly handled for them.
+:::
+
+:::note
+For more information, refer to the
+[chart documentation](https://github.com/akuity/kargo/blob/main/charts/kargo/README.md).
+:::
+
 ## Resource Management
 
 ### Tuning Concurrent Reconciliation Limits

internal/server/config/config.go

@@ -29,6 +29,7 @@ type ServerConfig struct {
 	PermissiveCORSPolicyEnabled bool
 	RolloutsIntegrationEnabled  bool
 	AnalysisRunLogURLTemplate   string
+	AnalysisRunLogToken         string
 	AnalysisRunLogHTTPHeaders   map[string]string
 }
 
@@ -59,6 +60,7 @@ func ServerConfigFromEnv() ServerConfig {
 		types.MustParseBool(os.GetEnv("ROLLOUTS_INTEGRATION_ENABLED", "true"))
 	if cfg.RolloutsIntegrationEnabled {
 		cfg.AnalysisRunLogURLTemplate = os.GetEnv("ANALYSIS_RUN_LOG_URL_TEMPLATE", "")
+		cfg.AnalysisRunLogToken = os.GetEnv("ANALYSIS_RUN_LOG_TOKEN", "")
 		if headersStr := os.GetEnv("ANALYSIS_RUN_LOG_HTTP_HEADERS", ""); headersStr != "" {
 			kvPairs := strings.Split(headersStr, ",")
 			cfg.AnalysisRunLogHTTPHeaders = make(map[string]string, len(kvPairs))

internal/server/get_analysisrun_logs_v1alpha1.go

@@ -413,7 +413,9 @@ func (s *server) buildRequest(
 	if err != nil {
 		return nil, fmt.Errorf("error creating GET request for log url %s: %w", url, err)
 	}
-	if userInfo, ok := user.InfoFromContext(ctx); ok {
+	if s.cfg.AnalysisRunLogToken != "" {
+		env["token"] = s.cfg.AnalysisRunLogToken
+	} else if userInfo, ok := user.InfoFromContext(ctx); ok {
 		env["token"] = userInfo.BearerToken
 	}
 	for key, valTemplate := range s.cfg.AnalysisRunLogHTTPHeaders {