Add environment variable information to CLI help and/or introduce kind env command

[jaehanbyun]

What would you like to be added: Add environment variable information to Kind CLI help output and/or introduce a new kind env command to display currently set environment variables (e.g., KIND_EXPERIMENTAL_PROVIDER, KUBECONFIG) and list available configurable environment variables.

Why is this needed: When attempting to use Kind with Podman instead of Docker, users may encounter errors like:

ERROR: failed to list clusters: command "docker ps -a --filter label=io.x-k8s.kind.cluster --format '{{.Label "io.x-k8s.kind.cluster"}}'" failed with error: exit status 1
Command Output: Cannot connect to the Docker daemon at unix:///Users/byeonjaehan/.docker/run/docker.sock. Is the docker daemon running?

However, when checking kind --help, there is no information about the KIND_EXPERIMENTAL_PROVIDER environment variable or other configurable environment variables. This makes it difficult for users to discover how to configure Kind to use alternative container runtimes or other settings.

Proposed Solution:

1. Add a brief section to kind --help output that mentions key environment variables like KIND_EXPERIMENTAL_PROVIDER, KIND_CLUSTER_NAME, and KUBECONFIG.

2. Introduce a new kind env command that:

   • Displays currently set Kind-related environment variables and their values
   • Lists all available Kind environment variables with brief descriptions
   • Optionally allows setting/unsetting environment variables (similar to go env)

[jaehanbyun]

If this proposal is acceptable, I'd be happy to work on implementing it.

[2003Aditya]

Hey! 👋 I went through the issue and the proposal makes complete sense.

Currently, Kind doesn’t surface any information about configurable environment variables like KIND_EXPERIMENTAL_PROVIDER, KIND_CLUSTER_NAME, or KUBECONFIG in the CLI help, which can be confusing for users who run into runtime or provider-related errors (especially when using Podman instead of Docker).

Adding a short “Environment Variables” section in the kind --help output or introducing a new kind env command would make these options much more discoverable. The kind env command could behave similarly to go env, showing currently set Kind-related variables along with their descriptions and default values.

I’d be happy to help draft or implement this feature if needed!

[BenTheElder]

KIND_EXPERIMENTAL_PROVIDER is "EXPERIMENTAL" because it is incomplete and only docker is fully supported, I'm not sure if we want to surface it outside of the docs, but if we did we should add it to the command help for all commands that respect it (and not the ones that don't such as kind build node-image).

This makes it difficult for users to discover how to configure Kind to use alternative container runtimes or other settings.

Please refer to the docs, which do cover this and much more: https://kind.sigs.k8s.io/docs/user/quick-start/

---

KUBECONFIG is a kubernetes standard, ecosystem wide, it would be relevant to kind create cluster, kind delete cluster, and kind export kubeconfig (but not kind get kubeconfig or other commands), but we should leverage the existing Kubernetes docs.

---

KIND_CLUSTER_NAME should be documented by the command help for the commands that accept it already, if not that is a bug, please do send us a PR to fix this.

---

2. Introduce a new kind env command that:

• Displays currently set Kind-related environment variables and their values
• Lists all available Kind environment variables with brief descriptions
• Optionally allows setting/unsetting environment variables (similar to go env)

I don't think this is necessary, go has far more complex and typically system-wide configuration through env, we generally prefer config files and have been trending towards removing these env or at least not adding anymore. I don't want to further encourage unversioned configuration versus config files.

Versioned config allows evolving the format, behaviors and defaults in a way that environment variables do poorly, so we have very few of them.

We pretty much retain the few that exist for compatibility reasons, for now.

The way go env supports setting them is by having a special system wide file, this is a lot of unnecessary complexity for a feature I wouldn't generally recommend using anyhow. Shells have existing functionality for managing environment variables, this is orthogonal to implementing kind. https://kind.sigs.k8s.io/docs/design/principles/#leverage-existing-tooling

[2003Aditya]

@BenTheElder Hey Ben, thanks for clarifying the approach regarding environment variables.

I went through the CLI help texts and documentation to better understand how different environment variables are currently surfaced.

A few quick observations:

• KIND_CLUSTER_NAME is mentioned in some commands (like create cluster) but not in others that also use it (delete, export kubeconfig, get kubeconfig).
• KUBECONFIG appears inconsistently across help outputs — sometimes shown, sometimes just implied.
• KIND_EXPERIMENTAL_PROVIDER is documented as experimental, so I agree it shouldn’t appear in CLI help.

Based on this, my thought is to make the CLI help a bit more consistent by adding short hints like “(can also be set via KIND_CLUSTER_NAME)” to the relevant commands.

This wouldn’t introduce new variables or behavior — just improve clarity in help text and keep it consistent with the docs.

Would you be open to a small PR for this? I can prepare one once you confirm it fits the project’s direction.

Thanks again for the guidance — just want to make sure I’m aligned before making any changes.

[BenTheElder]

I took a quick look, can we just update the --name flags to align? It should be closely associated with the flag.

KUBECONFIG shouldn't be relevant to most commands. We should make sure the kind docs link to the upstream config management docs, this isn't kind specific and there are standard kubernetes docs dedicated to this

[2003Aditya]

Hi @BenTheElder 👋 I’ve reviewed where the --name flag appears across the CLI and made the description consistent and clearer.

Here’s the updated output after the change:

Aditya | ~/opensource/kind [main *4]
$ ./bin/kind create cluster --help | grep name
./bin/kind delete cluster --help | grep name
./bin/kind export kubeconfig --help | grep name
./bin/kind get kubeconfig --help | grep name
  -n, --name string         cluster name (can also be set via KIND_CLUSTER_NAME, default: kind)
  -n, --name string         cluster name (can also be set via KIND_CLUSTER_NAME, default: kind) (default "kind")
  -n, --name string         cluster name (can also be set via KIND_CLUSTER_NAME, default: kind) (default "kind")
  -n, --name string         cluster name (can also be set via KIND_CLUSTER_NAME, default: kind) (default "kind")

Before I open a PR, could you please confirm if this is the direction you’d like me to take?

Once confirmed, I’ll create a PR with these updates.

[jaehanbyun]

Thank you for the detailed explanation, @BenTheElder. I understand the approach regarding environment variables and the preference for config files over environment variables.

Looking ahead, when podman support becomes GA and the auto-detection mechanism in pkg/cluster/provider.go (lines 117-129) is revisited, it might be worth considering updating the IsAvailable() implementations to check for actual daemon/socket accessibility rather than just binary existence. For instance, using <container_runtime> info or <container_runtime> ps instead of <container_runtime> -v would ensure that auto-detection only selects providers with actually accessible daemons. This could help prevent scenarios where Docker binary exists but the daemon isn't running, while Podman daemon is available but gets skipped due to the detection order.

[aojea]

when podman support becomes GA

just to set expectations, somebody has to work on that , all support so far was me and Ben in spare time and some users contributors, but I do not feel that is something will happen soon

[aliheydarabadii]

Hi! I’d like to take this issue. /assign

To keep the scope small, I’ll start with a first PR that updates the CLI help to list the key env vars (per proposal #1). After that lands, I can follow up with a separate PR for a read-only kind env command (proposal #2), if that sounds good.

[aliheydarabadii]

/assign

[BenTheElder]

Hi! I’d like to take this issue. /assign

To keep the scope small, I’ll start with a first PR that updates the CLI help to list the key env vars (per proposal https://github.com/kubernetes-sigs/kind/pull/1).

After that lands, I can follow up with a separate PR for a read-only kind env command (proposal https://github.com/kubernetes-sigs/kind/pull/2), if that sounds good.

Please read the discussion above, we've suggested alternatives already and haven't agreed to the proposal as-written.

[BenTheElder]

Before I open a PR, could you please confirm if this is the direction you’d like me to take?

Sorry this fell behind for me ... a lot happened in the following weeks. Yes, thank you.

[aliheydarabadii]

Hi! I’d like to take this issue. /assign

To keep the scope small, I’ll start with a first PR that updates the CLI help to list the key env vars (per proposal #1). After that lands, I can follow up with a separate PR for a read-only kind env command (proposal #2), if that sounds good.

Please read the discussion above, we've suggested alternatives already and haven't agreed to the proposal as-written.

Thanks for the clarification. I’ve opened a new PR with a narrower scope based on the discussion above—no kind env command and no global env help. It only aligns the --name flag help across commands and keeps the mention of KIND_CLUSTER_NAME scoped to that flag. Please let me know if this approach looks correct.