Document required metadata for cluster-credentials secret in linkerd namespace

[Majkel1999]

What problem are you trying to solve?

When using the linkerd-multicluster extensions, the cluster-credentials-... Secret, residing in LinkerD control-plane namespace, has required labels and annotations - https://github.com/linkerd/linkerd2/blob/ce950d17c60eab8c7c2a3e67c130241f96056ac2/controller/api/destination/watcher/cluster_store.go#L63C1-L67.

If the labels are not present, the linkerd-destination deployment will throw errors like:

Failed to get remote cluster <remote-cluster-name> addr=":8086" component=server remote="<ip>"

This is not documented and causes issues when deploying this secret without that specific metadata - for example using any automated secret manager or any other CI/CD tooling.

How should the problem be solved?

Document the required metadata and how to troubleshoot this issue. This should include both the required labels and annotations, as well as example log output from linkerd-destination to ensure the process is easy to follow.

Any alternatives you've considered?

Using the cluster-credentials-<remote-cluster-name> Secret name as an indicator of the correct credentials. This obviously has it's own issues, but would solve that.

How would users interact with this feature?

No response

Would you like to work on this feature?

yes

[kflynn]

Hi @Majkel1999, thanks for calling this out! If you'd like to work on it, a PR into the https://github.com/linkerd/website repo is the easiest way -- check out the linkerd.io/content/2.14/reference directory. Let me know if you have questions!

[Majkel1999]

Hi @kflynn, taking a look at the structure of docs it's not clear for me where it'd be best to document that - there's no Troubleshooting page, which would fit best. I suppose adding this to the end of linkerd.io/content/2.14/tasks/pod-to-pod-multicluster.md would be the best. Let me know what you think of it.

Edit

My proposition: linkerd/website#1705

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 14 days if no further activity occurs. Thank you for your contributions.