ambiguity related to --certificate-authority option for kubectl

[lethargosapatheia]

What happened?

When creating a secret, --certificate-authority is mentioned as an option to use a certificate authority in the documentation: https://kubernetes.io/docs/reference/kubectl/generated/kubectl_create/kubectl_create_secret_tls/

This is terribly ambiguous, because, if you haven't used tls secrets before, you might be led to believe that this refers to the CA certificate you're supposed to be inserting in the secret, which is not the case. It actually refers to the CA certificate you can use when running kubectl to connect to and to authenticate the API.

This option is also not present in the kubectl help at all, and neither is it present in the tls secret help (kubectl secret tls --help). So it doesn't seem to be documented otherwise.

What did you expect to happen?

A clearer description of the --certificate-authority option and documentation in the help menu of kubectl.

How can we reproduce it (as minimally and precisely as possible)?

Check --certificate-authority in https://kubernetes.io/docs/reference/kubectl/generated/kubectl_create/kubectl_create_secret_tls/

Anything else we need to know?

No response

Kubernetes version

```console $ kubectl version Client Version: version.Info{Major:"1", Minor:"27", GitVersion:"v1.27.4", GitCommit:"fa3d7990104d7c1f16943a67f11b154b71f6a132", GitTreeState:"clean", BuildDate:"2023-07-19T12:20:54Z", GoVersion:"go1.20.6", Compiler:"gc", Platform:"linux/amd64"} Kustomize Version: v5.0.1 Server Version: version.Info{Major:"1", Minor:"27", GitVersion:"v1.27.4", GitCommit:"fa3d7990104d7c1f16943a67f11b154b71f6a132", GitTreeState:"clean", BuildDate:"2023-07-19T12:14:49Z", GoVersion:"go1.20.6", Compiler:"gc", Platform:"linux/amd64"} ```

Cloud provider

self-hosted/vanilla

OS version

```console # On Linux: $ cat /etc/os-release PRETTY_NAME="Ubuntu 22.04.3 LTS" NAME="Ubuntu" VERSION_ID="22.04" VERSION="22.04.3 LTS (Jammy Jellyfish)" VERSION_CODENAME=jammy ID=ubuntu ID_LIKE=debian HOME_URL="https://www.ubuntu.com/" SUPPORT_URL="https://help.ubuntu.com/" BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/" PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy" UBUNTU_CODENAME=jammy $ uname -a Linux control-plane1 5.15.0-92-generic kubernetes/kubernetes#102-Ubuntu SMP Wed Jan 10 09:33:48 UTC 2024 x86_64 x86_64 x86_64 GNU/Linux ```

Install tools

Container runtime (CRI) and version (if applicable)

Related plugins (CNI, CSI, ...) and versions (if applicable)

[neolit123]

/sig cli auth

[mpuckett159]

/triage accepted /remove sig-auth

Just a couple notes about this issue. There are a few reasons why this seems to be happening:

1. The generated docs list the global flags along with the specific subcommand flags. Normally this isn't an issue however here the name collision is awkward because certificate authority means something to the actual subcommand, which is confusing users.
2. The global flags are listed under an empty header on the generated page, which appears to contain all the global flags for kubectl. See here and if you look at the URL it just says #heading in the link.

I think for a longer term fix for this issue we need to work with sig-docs on consolidating and fixing up the existing kubectl documentation (it is very fractured and duplicated at the moment) and in the mean time we can append some kind of "this is a global flag" text to the front of the flag help text so it gets explicitly called out in the generated docs. Please see here for the place in the code base where this is configured.

In addition to all of this, I'm going to bring this up on the next bi-weekly sig-cli.

[mpuckett159]

/remove-sig auth

[sftim]

The docs generator lives inside https://github.com/kubernetes-sigs/reference-docs/

Let's make this a documentation issue.

/transfer website

[sftim]

/sig docs

[sftim]

/priority backlog

[sftim]

Before we fix the generator code, we ought to merge it - see https://github.com/kubernetes-sigs/reference-docs/pull/349