Our images need READMEs

[spiffxp]

/kind documentation

What happened:

I tried to figure out what the images are in test/images and why they exist. None of them had READMEs to explain this. I tried spelunking through config/jobs to reverse engineer what they are by how they are used. But it appears there is a fair amount of cargo culting happening here, where it's not entirely clear that they are used on purpose for consistent reasons.

What you expected to happen:

Find README.md files in the each of the test/image directories that quickly explained what and why these images were. Things they should and should not be used for, that sort of deal.

It would also have been neat to have an images/README.md that sort of explained why the directory exists. Does our image building tool only operate there, or does it scrape our entire repo and that just happens to be our misc/catchall dir for images that don't directly correlate to subprojects/dirs that we have in this repo?

How to reproduce it (as minimally and precisely as possible):

Try figuring out why we have the images in there that we do.

Images that need READMEs

• https://github.com/kubernetes/test-infra/tree/master/images/alpine
• https://github.com/kubernetes/test-infra/tree/master/images/alpine-bash: removed by images: remove unused images #23617
• https://github.com/kubernetes/test-infra/tree/master/images/bazel
• https://github.com/kubernetes/test-infra/tree/master/images/bazel-krte: removed by images: remove unused images #23617
• https://github.com/kubernetes/test-infra/tree/master/images/bazelbuild
• https://github.com/kubernetes/test-infra/tree/master/images/bigquery
• https://github.com/kubernetes/test-infra/tree/master/images/bootstrap (images: add or update READMEs to trigger some image builds #23555)
• https://github.com/kubernetes/test-infra/tree/master/images/builder
• https://github.com/kubernetes/test-infra/tree/master/images/cluster-api: removed by config/jobs: use community hosted images for more jobs #23587
• https://github.com/kubernetes/test-infra/tree/master/images/gcb-docker-gcloud: images: add/update READMEs to trigger image builds #23656
• https://github.com/kubernetes/test-infra/tree/master/images/gcloud (images: add or update READMEs to trigger some image builds #23555)
• https://github.com/kubernetes/test-infra/tree/master/images/gcloud-bazel
• https://github.com/kubernetes/test-infra/tree/master/images/gcloud-terraform
• https://github.com/kubernetes/test-infra/tree/master/images/git
• https://github.com/kubernetes/test-infra/tree/master/images/krte
• https://github.com/kubernetes/test-infra/tree/master/images/kubekins-e2e
• https://github.com/kubernetes/test-infra/tree/master/images/kubemci
• https://github.com/kubernetes/test-infra/tree/master/images/pull-test-infra-gubernator

[spiffxp]

/priority important-longterm
/milestone v1.16

[spiffxp]

/sig testing
/help
This is not a good first issue, but if someone is willing to try opening a PR with docs, I and others with more context than myself can help iterate.

[k8s-ci-robot]

@spiffxp:
This request has been marked as needing help from a contributor.

Please ensure the request meets the requirements listed here.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-help command.

In response to this:

/sig testing
/help
This is not a good first issue, but if someone is willing to try opening a PR with docs, I and others with more context than myself can help iterate.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[spiffxp]

/area images

[spiffxp]

Most especially kubekins, since that is used by many of our jobs, and I'm having to reverse engineer what should be in there and why, eg: #13870 (comment)

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[fejta-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

[k8s-ci-robot]

@fejta-bot: Closing this issue.

In response to this:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[spiffxp]

/remove-lifecycle rotten
/reopen
Still relevant and a good place for someone to help out from a docs perspective

[k8s-ci-robot]

@spiffxp: Reopened this issue.

In response to this:

/remove-lifecycle rotten
/reopen
Still relevant and a good place for someone to help out from a docs perspective

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[MushuEE]

@spiffxp I can go ahead and create a foundation for the top level README.md with a template for the lower level READMEs + frame all the lower level ones with their respective Images. Might make this effort more distributed.

[spiffxp]

FYI @kubernetes/ci-signal

$ for d in $(find . -type d -maxdepth 1 -mindepth 1 | cut -d/ -f2 | sort); do \
  echo "- [$(test -f $d/README.md && echo x || echo ' ')] https://github.com/kubernetes/test-infra/tree/master/images/$d";
done

(pulled the checklist into the description)

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[spiffxp]

/remove-lifecycle rotten

[spiffxp]

/sig release
/area release-eng
For documenting things like kubekins

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-contributor-experience at kubernetes/community.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-contributor-experience at kubernetes/community.
/lifecycle rotten

[BenTheElder]

/lifecycle frozen

[rajaskakodkar]

/assign

[spiffxp]

#23555 adds READMEs for: bootstrap, gcloud-in-go

[spiffxp]

#23656 adds a README for: gcb-docker-gcloud

[jasonbraganza]

@spiffxp, I have added README documents for the following test-infra images (listed in the issue description):

• https://github.com/kubernetes/test-infra/tree/master/images/alpine by Add Alpine Image README #26204
• https://github.com/kubernetes/test-infra/tree/master/images/gcloud-terraform by Add README.md for gcloud-terraform image #26205
• https://github.com/kubernetes/test-infra/tree/master/images/git by Add README.md for git image #26206
• https://github.com/kubernetes/test-infra/tree/master/images/pull-test-infra-gubernator by Add README.md for pull-test-infra-gubernator image #26207

PTAL, thank you 🙂