Document `/logs` API for API server

RichardoC commented 1 year ago

What happened?

While experimenting with the following command, I spotted an API that's not documented in the API one pager, which doesn't conform to the schema I would expect (it's HTML, not JSON)


$ kubectl  get --raw / | grep logs
    "/logs",

$ kubectl  get --raw /logs
<pre>
<a href="acpid.log">acpid.log</a>
<a href="buildkitd.log">buildkitd.log</a>
<a href="cloud-init-output.log">cloud-init-output.log</a>
<a href="containerd.log">containerd.log</a>
<a href="containers/">containers/</a>
<a href="dmesg">dmesg</a>
<a href="lima-init.log">lima-init.log</a>
<a href="messages">messages</a>
<a href="openresty/">openresty/</a>
<a href="pods/">pods/</a>
<a href="rancher-desktop-guestagent.log">rancher-desktop-guestagent.log</a>
<a href="wtmp">wtmp</a>
</pre>

This should be documented, and preferably be json to conform to the other APIs exposed.

What did you expect to happen?

This API would be documented, especially since it's serving up all files from a specific file path and the API should present some sort of json list rather than a webpage.

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


$ kubectl  get --raw / | grep logs
    "/logs",

$ kubectl  get --raw /logs
...

Anything else we need to know?

This is the root cause of https://github.com/rancher-sandbox/docs.rancherdesktop.io/issues/136 and https://github.com/k3s-io/k3s/issues/6709 as I didn't expect an undocumented file server API from kubernetes.

Kubernetes version

```console $ kubectl version WARNING: This version information is deprecated and will be replaced with the output from kubectl version --short. Use --output=yaml|json to get the full version. Client Version: version.Info{Major:"1", Minor:"24", GitVersion:"v1.24.4", GitCommit:"95ee5ab382d64cfe6c28967f36b53970b8374491", GitTreeState:"clean", BuildDate:"2022-08-17T18:54:23Z", GoVersion:"go1.18.5", Compiler:"gc", Platform:"linux/amd64"} Kustomize Version: v4.5.4 Server Version: version.Info{Major:"1", Minor:"24", GitVersion:"v1.24.8+k3s1", GitCommit:"648004e4faeaf9e8705386342e95ec9bd211c2b8", GitTreeState:"clean", BuildDate:"2022-11-18T18:29:47Z", GoVersion:"go1.18.8", Compiler:"gc", Platform:"linux/amd64"} ```

Cloud provider

$ rdctl version rdctl client version: 1.1.0, targeting server version: v0 Rancher Desktop version 1.7.0 on Ubuntu 22.04.1 x64

OS version

```console Ubuntu 22.04.1 ```

Install tools

No response

Container runtime (CRI) and version (if applicable)

No response

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

No response

k8s-ci-robot commented 1 year ago

@RichardoC: This issue is currently awaiting triage.

If a SIG or subproject determines this is a relevant issue, they will accept it by applying the triage/accepted label and provide further guidance.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.

RichardoC commented 1 year ago

/sig docs

RichardoC commented 1 year ago

For anyone seeing this in a panic, it is behind auth (thankfully) A k3s maintainer found the code and details are in https://github.com/k3s-io/k3s/issues/6709#issuecomment-1376460915

brandond commented 1 year ago

FYI, for CLI docs I usually check this page, not the api docs.

This has been deprecated since 1.15 as per https://github.com/kubernetes/kubernetes/pull/77611 - I wonder if that's why it's omitted from the docs? It's still there, and still on by default though.

https://github.com/kubernetes/kubernetes/blob/804d6167111f6858541cef440ccc53887fbbc96a/cmd/kube-apiserver/app/options/options.go#L173-L175

https://github.com/kubernetes/kubernetes/blob/804d6167111f6858541cef440ccc53887fbbc96a/cmd/kube-apiserver/app/options/options.go#L113

brandond commented 1 year ago

/cc @dims @liggitt @cheftako

brandond commented 1 year ago

Funny enough the original report that triggered that PR was also against k3s:

https://github.com/k3s-io/k3s/issues/387 so this is probably considered a duplicate of:
https://github.com/kubernetes/kubernetes/issues/77182

RichardoC commented 1 year ago

FYI, for CLI docs I usually check this page, not the api docs.

This has been deprecated since 1.15 as per kubernetes/kubernetes#77611 - I wonder if that's why it's omitted from the docs? It's still there, and still on by default though.

https://github.com/kubernetes/kubernetes/blob/804d6167111f6858541cef440ccc53887fbbc96a/cmd/kube-apiserver/app/options/options.go#L173-L175

https://github.com/kubernetes/kubernetes/blob/804d6167111f6858541cef440ccc53887fbbc96a/cmd/kube-apiserver/app/options/options.go#L113

While it's a CLI option, the fact it's accessible via the rest API means I'd expect it to be documented there. If it was on another port I'd agree with you

liggitt commented 1 year ago

I'm not sure how https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/ is generated, but the logs endpoint is included in the openapi reference when enabled:

    "/logs/": {
      "get": {
        "operationId": "logFileListHandler",
        "responses": {
          "401": {
            "description": "Unauthorized"
          }
        },
        "schemes": [
          "https"
        ],
        "tags": [
          "logs"
        ]
      }
    },
    "/logs/{logpath}": {
      "get": {
        "operationId": "logFileHandler",
        "responses": {
          "401": {
            "description": "Unauthorized"
          }
        },
        "schemes": [
          "https"
        ],
        "tags": [
          "logs"
        ]
      },
      "parameters": [
        {
          "description": "path to the log",
          "in": "path",
          "name": "logpath",
          "required": true,
          "type": "string",
          "uniqueItems": true
        }
      ]
    },

/transfer website

sftim commented 1 year ago

/kind feature /language en /retitle Document hidden /logs API for API server /sig security /sig api-machinery

sftim commented 1 year ago

Actually /retitle Document /logs API for API server

It's not hidden, just nobody documented it yet. It's nice to document features for posterity before we remove them: the removal might be the first point at which some users look for the docs.

liggitt commented 1 year ago

/remove-sig security

I don't think this is sig-security... more an issue with the openapi → doc generator, right?

RichardoC commented 1 year ago

While we're on the topic, how I can request that we move ahead with removing this API? If that'll happen soon enough we don't need to fix the docs?

liggitt commented 1 year ago

While we're on the topic, how I can request that we move ahead with removing this API? If that'll happen soon enough we don't need to fix the docs?

Let's keep that discussion separate. That API can be turned off if desired, and there's a PR open to default it off (https://github.com/kubernetes/kubernetes/pull/110738)

sftim commented 1 year ago

SIG Security Docs make sure that things readers need to know to secure their cluster are properly documented. Isn't this one of those details?

raesene commented 1 year ago

In case it's of interest, the parameter doesn't show with kube-apiserver --help either. Definitely seeing it documented even if it's removed would be good, as cluster operators will be on affected versions for a while.

Also I can add this to the CIS benchmark for Kubernetes, but ideally for that it's good to have a documentation reference pointing to the flags existence :)

liggitt commented 1 year ago

In case it's of interest, the parameter doesn't show with kube-apiserver --help either.

that definitely needs fixing ... looks like a retread of https://github.com/kubernetes/kubernetes/pull/62621

Also I can add this to the CIS benchmark for Kubernetes

make sure to distinguish between a kube-apiserver instance running on the host and granting access to /var/log and an instance running in a container and only granting access to its own logs in that directory (which is more reasonable)

liggitt commented 1 year ago

FWIW, there's a KEP in progress to expand access to host logs on the kubelet side, which doesn't seem coherent with the goal of reducing access to host logs via the apiserver... commented at https://github.com/kubernetes/kubernetes/pull/96120#pullrequestreview-1262371094 and cross-linked here.

sftim commented 1 year ago

/triage accepted

sftim commented 1 year ago

/sig security That's a SIG who could help document this detail.

k8s-triage-robot commented 4 months ago

This issue has not been updated in over 1 year, and should be re-triaged.

You can:

Confirm that this issue is still relevant with /triage accepted (org members only)
Close this issue with /close

For more details on the triage process, see https://www.kubernetes.dev/docs/guide/issue-triage/

/remove-triage accepted

k8s-triage-robot commented 1 month ago

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

After 90d of inactivity, lifecycle/stale is applied
After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

Mark this issue as fresh with /remove-lifecycle stale
Close this issue with /close
Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

RichardoC commented 1 month ago

/remove-lifecycle stale

kubernetes / website