docs: document cred management with cli + specific support for ecr and google artifact registry

[krancour]

Fixes #2067

[netlify]

✅ Deploy Preview for docs-kargo-akuity-io ready!

Name	Link
🔨 Latest commit	b94cb52
🔍 Latest deploy log	https://app.netlify.com/sites/docs-kargo-akuity-io/deploys/665a617b83ecf1000875eeea
😎 Deploy Preview	https://deploy-preview-2077.kargo.akuity.io
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 45.62%. Comparing base (fde59de) to head (b94cb52).
Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2077   +/-   ##
=======================================
  Coverage   45.62%   45.62%           
=======================================
  Files         238      238           
  Lines       16485    16485           
=======================================
  Hits         7522     7522           
  Misses       8592     8592           
  Partials      371      371           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[jessesuen]

Google Artifact Registry does not directly support long-lived credentials,

Actually, unlike ECR, GAR can be accessed with a long-lived service account key as a password, so we should change this wording. Credentials look like:

username: _json_key_base64
password: base64 encoded of some json like:

{
  "type": "service_account",
  "project_id": "myproject",
  "private_key_id": "xxxxxx",
  "private_key": "-----BEGIN PRIVATE KEY-----\nyyyyyyy==\n-----END PRIVATE KEY-----\n",
  "client_email": "foo@myproject.iam.gserviceaccount.com",
  "client_id": "12345",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/foo%40myproject.iam.gserviceaccount.com"
}

This is documented at https://cloud.google.com/artifact-registry/docs/docker/authentication#json-key,

We can point them there if they prefer/need to use long-lived credentials and explain that GAR supports two methods of accessing private repos.

TBH, I'm not sure what benefits "Access Token" auth has over "Service Account Key" since Access Token would still need a long lived service account credential anyways.

[krancour]

🤦‍♂️ Embarrassed that I missed that part of the docs, and also question the value of access tokens under these circumstances. I will document this as a third option for authenticating to GAR. For my own edification, I might also research if/why exchanging a service account key for an access token might have any benefit over using the key directly.

[krancour]

Addressed. Directly using the service account token is now listed as an option that works, but which Google discourages.

I have also posted a question about that recommendation on security.stackexchange.com.

https://security.stackexchange.com/questions/277163/why-use-access-token-for-google-artifact-registry-access

[krancour]

I have much more clarity about this now, and it would have been obvious if I'd re-read my own code after the inital confusion had set in...

I think I allowed the fact that _json_key_base64 and a base64-encoded service account key can be used as user/pass in basic auth to the registry to mislead me into believing that gcloud auth print-access-token (or programmatic equivalent) was using the service account key in the same way -- which is totally not the case.

The service account key is actually used to sign a JWT and it is the JWT that is exchanged for an access token -- meaning that when you request an access token, the service account key does not at any point traverse the wire.

It's right here:

kargo/internal/credentials/gar/service_account_key.go

Lines 105 to 113 in 088fc4d

	config, err := google.JWTConfigFromJSON(decodedKey, "https://www.googleapis.com/auth/devstorage.read_write")
	if err != nil {
	return "", fmt.Errorf("error parsing service account key: %w", err)
	}
	tokenSource := config.TokenSource(ctx)
	token, err := tokenSource.Token()
	if err != nil {
	return "", fmt.Errorf("error getting access token: %w", err)
	}

This being the case, the benefits of obtaining an access token over using the service account key to access the registry directly are more obvious.

Two action items for me:

1. Without going into exhaustive detail, understanding this much better now compels me to somewhat strengthen my caution against the most direct approach. I will amend this PR accordingly.

2. While researching, I noticed that when requesting the access token, I am requesting a read/write scope, which is quite unnecessary for how Kargo interacts with a registry, which is always in a read-only fashion. I will fix this in a separate PR.

[krancour]

Docs amended in b94cb52