Update documentation to reflect the use of community-owned package repository pkgs.k8s.io

[reylejano]

The Kubernetes project began publishing to community-owned package repository pkgs.k8s.io and no longer publishes to apt.kubernetes.io and yum.kubernetes.io which are Google-hosted package repositories.
apt.kubernetes.io and yum.kubernetes.io will be frozen on Sept 13, 2023.

See pkgs.k8s.io: Introducing Kubernetes Community-Owned Package Repositories blog post for more details

Documentation for releases starting with 1.24 that points to apt.kubernetes.io or yum.kuberenetes.io need to be updated to point to pkgs.k8s.io

Branches to update:

Beta Give feedback

1. main
2. release-1.27
3. release-1.26
4. release-1.25
5. release-1.24

/help

[k8s-ci-robot]

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

Guidelines

Please ensure that the issue body includes answers to the following questions:

• Why are we solving this issue?
• To address this issue, are there any code changes? If there are code changes, what needs to be done in the code and what places can the assignee treat as reference points?
• Does this issue have zero to low barrier of entry?
• How can the assignee reach out to you for help?

For more details on the requirements of such an issue, please see here and ensure that they are met.

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

In response to this:

The Kubernetes project began publishing to community-owned package repository pkgs.k8s.io and no longer publishes to apt.kubernetes.io and yum.kubernetes.io which are Google-hosted package repositories.
apt.kubernetes.io and yum.kubernetes.io will be frozen on Sept 13, 2023.

See pkgs.k8s.io: Introducing Kubernetes Community-Owned Package Repositories blog post for more details

Documentation for releases starting with 1.24 that points to apt.kubernetes.io or yum.kuberenetes.io need to be updated to point to pkgs.k8s.io

### Branches to update:
- [ ] main
- [ ] release-1.27
- [ ] release-1.26
- [ ] release-1.25
- [ ] release-1.24

/help

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.

[jeremyrickard]

@reylejano One tricky thing here is that we won't have packages for all versions back that far. Some of the patch releases will but not others.

[sftim]

/triage accepted
/priority critical-urgent

We're on a tight schedule
/sig release cluster-lifecycle docs

[sftim]

One tricky thing here is that we won't have packages for all versions back that far. Some of the patch releases will but not others.

Is there an issue - in some other repo - about filling in gaps there?

[xmudrii]

I'll be helping with this.
/assign

[sftim]

How's the work going?

• maybe we can lower the priority?

[xmudrii]

@sftim I'll come up with something this week :)

[torenware]

Please, please, consider rolling back these changes until the page makes it clear:

1. How to install kubeadm for any version other than v1.28. The new repo types install only for the current version. To be blunt, this is not how many people will use the doc page, and as someone who helps train people for CKA, I will tell you the change in the page is causing a great deal of confusion.
2. The page did include, until about 9 October, instructions of how to get the old google repos for installing older versions. Now this has been removed. HOW DO YOU EXPECT PEOPLE TO FIND THAT? Again, I am seeing this in courses. You are confusing new users, without a shade of a doubt.

At a minimum, please restore the info about the Google repos for now. Please consider documenting how to install a version different from v1.28: people do need to do that, and it needs to be documented.

This is a bit of a screw up.

[tengqm]

At a minimum, please restore the info about the Google repos for now. Please consider documenting how to install a version different from v1.28: people do need to do that, and it needs to be documented.

The whole community is moving forward constantly, in a fast pace. We the docs team has been updating the main branch to follow whatever changed in the upstream repo/projects.
You will have to switch to the version of the docs that match your k8s release. The main site cannot be used for that purpose because it is always about the latest release (v1.28 today).
There is a version drop down menu in the navigation bar. You can check if that works for you.

[tengqm]

Regarding the change of package repository, please report your concern to the sig-release group. We are documenting the facts for users but we don't manage that change.

[torenware]

No, you are the correct address. Don't push this on the sig-release group; what they did makes sense. It's the doc page that is not serving the community.

People have been coming to this page for many releases to learn how to install kubeadm. It has not been necessary to go back to archived versions of the K8s docs to install to a previous version. Which is confusing the hell out of users. I get 7 to 10 support request from users in our course due the change in the docs that happened in August. You just made it worse. Don't send me to the release team. They are not responsible for doing this. You folks are.

In particular, this page needs to make clear how to install to any supported Kubernetes version, so please consider parameterizing the "1.28" strings in URLs. People who need to install v1.26 or v1.27 (supported versions!!!) are not told that your procedure WILL NOT WORK FOR THEM. And for versions previous to v1.27, they will not find releases at all.

This is easily prevented: DOCUMENT THE GOOGLE REPOS AND NOTE THAT THEY WILL BE NEEDED FOR SOME INSTALLS. No one on the release team is forcing you to do what you are doing here. This is your responsibility. Own up to it.

[torenware]

At a minimum, please roll back the change to the page that was made on 9 October (approx). The community is transitioning to the new repos. You are going to need to document use cases where the new repos cannot be used.

[tengqm]

Okay, let's take a step back, focus on the problems to resolve.

1. How to install kubeadm for any version other than v1.28. The new repo types install only for the current version. To be blunt, this is not how many people will use the doc page, and as someone who helps train people for CKA, I will tell you the change in the page is causing a great deal of confusion.

Yes. The new instructions only works for the new versions. Version before 1.24 becomes a history and we have a convention to stop maintaining V-4 or older releases. Even for V-4 -> V-1, we only fix critical bugs.
I'm not quite clear about your suggestion. The new text is about the new way to install k8s packages, and the concern is that we didn't explicit warn the users that these are only for new releases. Am I getting that correct?

2. The page did include, until about 9 October, instructions of how to get the old google repos for installing older versions. Now this has been removed. HOW DO YOU EXPECT PEOPLE TO FIND THAT? Again, I am seeing this in courses. You are confusing new users, without a shade of a doubt.

The thing is not about whether the instructions are removed. It is that those repos will be removed at any time. We have to move on. It is not that we don't want to document that. It is that the infrastructure has been undergoing drastic (disruptive to someone) changes. We don't own the repos, and that is the reason I was suggesting you to go to sig-release.

At a minimum, please restore the info about the Google repos for now. Please consider documenting how to install a version different from v1.28: people do need to do that, and it needs to be documented.

As I have mentioned, the Google repos are going away. They may get sunset any time soon.

[torenware]

The new text is about the new way to install k8s packages, and the concern is that we didn't explicit warn the users that these are only for new releases. Am I getting that correct?

That is indeed a problem. Take the example of someone who needs to install a v1.27 version. You'd think that it would occur to them to change the URL to change "1.28" to "1.27", but I find that by in large. people assume they can install the version they need using the current docs. So yeah, it needs to be more clear that the new system is version specific, and if you want to install an older version, you need to change the URL. This covers about half of the problem people have installing kubeadm in our labs.

The thing is not about whether the instructions are removed. It is that those repos will be removed at any time. We have to move on. It is not that we don't want to document that. It is that the infrastructure has been undergoing drastic (disruptive to someone) changes. We don't own the repos, and that is the reason I was suggesting you to go to sig-release.

I don't know the "politics" involved in Google's sunsetting of the repos, but if Google does this, I would hope that there is retroactive support via pkgs.k8s.io by sig-releases for any K8s release that is still supported. Are there? If there are, the current doc should probably mention the releases supported by the pkgs.k8s.io repos, in particular, the pattern of the URI that can be used. This won't be in the archived doc versions, since they're not getting updates I'd assume.

If there isn't pkgs.k8s.io support for v1.25 and v1.26, I would hope that the Google repos stays up until they are out of their support window. But especially if there isn't support for them, the current doc needs to reference the Google repos, up until they are sunsetted, since that will affect more than students: it will make it difficult for a lot of shops using K8s to update their clusters :-(

As I have mentioned, the Google repos are going away. They may get sunset any time soon.

They may well, but the docs should cover these repos up until they do. Since it's easy enough to keep a PR warm, it's not that the docs team needs to be caught flat-footed when it happens. But given the potential for disrupting production users of K8s, better to defer removing these references until that happens.

[xmudrii]

How to install kubeadm for any version other than v1.28. The new repo types install only for the current version. To be blunt, this is not how many people will use the doc page, and as someone who helps train people for CKA, I will tell you the change in the page is causing a great deal of confusion.

The install kubeadm document very clearly states the following:

These instructions are for Kubernetes 1.28.

We have never provided backwards-compatibility promises for our documentation. You're supposed to use the same documentation version as your intended Kubernetes version. For example, if you want to install Kubernetes 1.27, you should use docs for 1.27.

The page did include, until about 9 October, instructions of how to get the old google repos for installing older versions. Now this has been removed. HOW DO YOU EXPECT PEOPLE TO FIND THAT? Again, I am seeing this in courses. You are confusing new users, without a shade of a doubt.

The legacy (Google-hosted) repositories are deprecated and frozen. This means that we don't publish any new releases to the legacy repositories. Kubernetes releases that are created after September 13, 2023, are only available in the new community-owned repositories. That said, you should also use the community-owned repositories even for version older than 1.28. We're currently working on updating instructions for earlier docs versions to highlight this.

No, you are the correct address. Don't push this on the sig-release group; what they did makes sense. It's the doc page that is not serving the community.

SIG Release is owning this work (and the relevant KEP), so SIG Release is definitely the correct address. We're trying our best to understand all the feedback that we receive and we very appreciate it, but we also kindly ask all our community members to understand this situation.

In particular, this page needs to make clear how to install to any supported Kubernetes version, so please consider parameterizing the "1.28" strings in URLs. People who need to install v1.26 or v1.27 (supported versions!!!) are not told that your procedure WILL NOT WORK FOR THEM.

As I said earlier, it's clearly stated that these instructions are only for Kubernetes 1.28, but we'll make this message better highlighted.

I don't know the "politics" involved in Google's sunsetting of the repos, but if Google does this, I would hope that there is retroactive support via pkgs.k8s.io by sig-releases for any K8s release that is still supported. Are there?

Yes, there's retroactive support for previous release starting with 1.24.0. Please see the official announcements for more details:

• https://kubernetes.io/blog/2023/08/15/pkgs-k8s-io-introduction/
• https://kubernetes.io/blog/2023/08/31/legacy-package-repository-deprecation/

They may well, but the docs should cover these repos up until they do.

I have to disagree with this point. Providing instructions based on the legacy (Google-hosted) repositories is setting up users for failure. Let's put aside that the legacy repositories might go away at any time. Given that no new releases are published to the legacy repositories, this can make users vulnerable to any vulnerability that might come up in the future. This is very serious and we want users to migrate to the community-owned repositories as soon as possible. It doesn't make sense to document something that's half-functional, or in this case deprecated and frozen.

For the end, I would like to repeat what @cpanato said in the other issue: please be more kind and respectful to the community members, a lot of folks are working on this in their free time. We understand that this is a breaking change, but we had to make it and we tried our best to explain reasons for that in the announcement.

[sftim]

The install kubeadm document very clearly states the following:

These instructions are for Kubernetes 1.28.

It does state this, however we could add the same advice right at the top of the page, and maybe even link to the available alternative versions (see https://kubernetes.io/docs/home/supported-doc-versions/ for some example templating code).

Helping people find the right guide pays off in terms of cutting down the number of issues opened.

[sftim]

For the end, I would like to repeat what @cpanato said in the other issue: please be more kind and respectful to the community members, a lot of folks are working on this in their free time. We understand that this is a breaking change, but we had to make it and we tried our best to explain reasons for that in the announcement.

Also this. Folks, if you're looking to add your thoughts to this tracking issue: don't. This is a tracking issue; we're using it to track work. Even if you're upset, that kind of feedback belongs elsewhere. Take notice.

[xmudrii]

It does state this, however we could add the same advice right at the top of the page, and maybe even link to the available alternative versions (see https://kubernetes.io/docs/home/supported-doc-versions/ for some example templating code).

@sftim I agree with this, I'll see later today how we can improve and better highlight this message

[xmudrii]

I created #43458 to clarify that we have a dedicated package repository for each Kubernetes minor version and that the new package repositories are supporting Kubernetes minor releases starting with v1.24.0.

[reylejano]

Others have chimed in with similar responses.

Please, please, consider rolling back these changes until the page makes it clear:

1. How to install kubeadm for any version other than v1.28. The new repo types install only for the current version. To be blunt, this is not how many people will use the doc page, and as someone who helps train people for CKA, I will tell you the change in the page is causing a great deal of confusion.

This is incorrect. The main page does not need to include installation for previous versions before v1.28 as the main page is for v1.28. For previous versions, please use the relative page for the specific version. SIG Docs currently maintains pages for v1.24 to v1.28
Please see: https://kubernetes.io/docs/home/supported-doc-versions/

At a minimum, please restore the info about the Google repos for now. Please consider documenting how to install a version different from v1.28: people do need to do that, and it needs to be documented.

Installation instructions for v1.24-v1.27 are in their respective pages
See: https://kubernetes.io/docs/home/supported-doc-versions/

[xmudrii]

Required docs changes are backported to all supported release branches (v1.27-v1.24) and the provided feedback has been addressed. There are some follow ups required and we have #43666 to track that. I'm going to close this issue.
/close

[k8s-ci-robot]

@xmudrii: Closing this issue.

In response to this:

Required docs changes are backported to all supported release branches (v1.27-v1.24) and the provided feedback has been addressed. There are some follow ups required and we have #43666 to track that. I'm going to close this issue.
/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.