From 8b34ab446ac63ef02a342e205c3b99ebbb596f4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marko=20Mudrini=C4=87?= Date: Wed, 26 Jul 2023 19:09:13 +0200 Subject: [PATCH] Update package manager instructions with community-hosted repos MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Marko Mudrinić --- .../tools/kubeadm/create-cluster-kubeadm.md | 5 +- .../tools/kubeadm/install-kubeadm.md | 136 +++++++++++++++-- .../kubeadm/kubeadm-upgrade.md | 142 ++++++++++++++++++ .../kubeadm/upgrading-linux-nodes.md | 142 ++++++++++++++++++ .../docs/tasks/tools/install-kubectl-linux.md | 122 ++++++++++++++- 5 files changed, 530 insertions(+), 17 deletions(-) diff --git a/content/en/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md b/content/en/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md index 0aa004640613e..922e76bde9c01 100644 --- a/content/en/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md +++ b/content/en/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md @@ -76,9 +76,8 @@ Install a {{< glossary_tooltip term_id="container-runtime" text="container runti For detailed instructions and other prerequisites, see [Installing kubeadm](/docs/setup/production-environment/tools/kubeadm/install-kubeadm/). {{< note >}} -If you have already installed kubeadm, run -`apt-get update && apt-get upgrade` or -`yum update` to get the latest version of kubeadm. +If you have already installed kubeadm, see the first two steps of the +[Upgrading Linux nodes](/docs/tasks/administer-cluster/kubeadm/upgrading-linux-nodes) document for information on how to upgrade kubeadm. When you upgrade, the kubelet restarts every few seconds as it waits in a crashloop for kubeadm to tell it what to do. This crashloop is expected and normal. diff --git a/content/en/docs/setup/production-environment/tools/kubeadm/install-kubeadm.md b/content/en/docs/setup/production-environment/tools/kubeadm/install-kubeadm.md index 6fbe04549d777..22aac3fdea100 100644 --- a/content/en/docs/setup/production-environment/tools/kubeadm/install-kubeadm.md +++ b/content/en/docs/setup/production-environment/tools/kubeadm/install-kubeadm.md @@ -147,6 +147,58 @@ For more information on version skews, see: {{< tabs name="k8s_install" >}} {{% tab name="Debian-based distributions" %}} +{{< warning >}} +Kubernetes has two different package repositories starting from August 2023. +The Google-hosted repository is considered deprecated and we will stop +publishing packages to that repository starting with Kubernetes 1.30. +The community-hosted repositories are replacement for the Google-hosted +repository. There are some important considerations for the community-hosted +repositories: + +- We strongly recommend using the community-hosted repositories especially for + all new setups. For existing setups, manual migration outlined in the + document linked below is required. +- The community-hosted repositories contains only packages starting from + Kubernetes 1.24.0. +- We have a different repository for each Kubernetes minor release. + Please take this into consideration when upgrading to a new minor release. + +For more details about community-hosted repositories, we strongly recommend +checking out the following document: TBD +{{< /warning >}} + +### Community-hosted repositories + +1. Update the `apt` package index and install packages needed to use the Kubernetes `apt` repository: + + ```shell + sudo apt-get update + sudo apt-get install -y apt-transport-https ca-certificates curl + ``` + +2. Download the public signing key for community repositories. The same signing key is used for all repositories so you can disregard the version in URL: + + ```shell + curl -fsSL https://pkgs.k8s.io/core:/stable:/{{< param "version" >}}/deb/Release.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/kubernetes-apt-keyring.gpg > /dev/null + ``` + +3. Add the appropriate Kubernetes `apt` repository. If you're using Kubernetes version different than {{< param "version" >}}, + replace {{< param "version" >}} with the desired minor version in commands below: + + ```shell + echo 'deb https://pkgs.k8s.io/core:/stable:/{{< param "version" >}}/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list + ``` + +4. Update `apt` package index, install kubelet, kubeadm and kubectl, and pin their version: + + ```shell + sudo apt-get update + sudo apt-get install -y kubelet kubeadm kubectl + sudo apt-mark hold kubelet kubeadm kubectl + ``` + +### Google-hosted repository (Deprecated) + 1. Update the `apt` package index and install packages needed to use the Kubernetes `apt` repository: ```shell @@ -180,7 +232,76 @@ You can create this directory if you need to, making it world-readable but write {{% /tab %}} {{% tab name="Red Hat-based distributions" %}} -```bash + +{{< warning >}} +Kubernetes has two different package repositories starting from August 2023. +The Google-hosted repository is considered deprecated and we will stop +publishing packages to that repository starting with Kubernetes 1.30. +The community-hosted repositories are replacement for the Google-hosted +repository. There are some important considerations for the community-hosted +repositories: + +- We strongly recommend using the community-hosted repositories especially for + all new setups. For existing setups, manual migration outlined in the + document linked below is required. +- The community-hosted repositories contains only packages starting from + Kubernetes 1.24.0. +- We have a different repository for each Kubernetes minor release. + Please take this into consideration when upgrading to a new minor release. + +For more details about community-hosted repositories, we strongly recommend +checking out the following document: TBD +{{< /warning >}} + +### Prerequisites + +These prerequisites must be satisfied regardless if you're using +community-hosted or Google-hosted repositories. + +1. Set SELinux in the permissive mode: + +```shell +# Set SELinux in permissive mode (effectively disabling it) +sudo setenforce 0 +sudo sed -i 's/^SELINUX=enforcing$/SELINUX=permissive/' /etc/selinux/config +``` + + **Notes:** + + - Setting SELinux in permissive mode by running `setenforce 0` and `sed ...` effectively disables it. + This is required to allow containers to access the host filesystem, which is needed by pod networks for example. + You have to do this until SELinux support is improved in the kubelet. + + - You can leave SELinux enabled if you know how to configure it but it may require settings that are not supported by kubeadm. + +### Community-hosted repositories + +2. Add the Kubernetes `yum` repository. If you're using Kubernetes version different than {{< param "version" >}}, replace {{< param "version" >}} with the desired minor version in command below: + +```shell +cat <}}/rpm/ +enabled=1 +gpgcheck=1 +gpgkey=https://pkgs.k8s.io/core:/stable:/{{< param "version" >}}/rpm/repodata/repomd.xml.key +exclude=kubelet kubeadm kubectl +EOF +``` + +3. Install kubelet, kubeadm and kubectl, and enable kubelet to ensure it's automatically started on startup: + +```shell +sudo yum install -y kubelet kubeadm kubectl --disableexcludes=kubernetes +sudo systemctl enable --now kubelet +``` + +### Google-hosted repository (Deprecated) + +2. Add the Kubernetes `yum` repository: + +```shell cat < +## Changing the package repository + +{{< warning >}} + +Follow this step only if you use the community-hosted repositories. +{{< /warning >}} + +{{< tabs name="k8s_install_versions" >}} +{{% tab name="Ubuntu, Debian or HypriotOS" %}} + +Check if you're using the community-hosted repositories or the Google-hosted +repository: + +```shell +cat /etc/apt/sources.list.d/kubernetes.list +``` + +If you see the URL similar to: + +``` +deb https://pkgs.k8s.io/core:/stable:/v{{< skew currentVersionAddMinor -1 "." >}}/deb/ / +``` + +**You're using the community-hosted repositories and you need to change +the package repository.** Otherwise, skip to the next step, but please note that, +we strongly recommend migrating to the community-hosted repositories as +the Google-hosted repository is considered deprecated. See the following +document for more information about migrating to the community-hosted +repositories: TBD + +{{< note >}} +The URL for the community-hosted repositories is not limited to `pkgs.k8s.io`, +it can be one of: + +- `pkgs.k8s.io` +- `pkgs.kubernetes.io` +- `packages.kubernetes.io` +- `packages.kubernetes.io` +{{}} + +Change the repository URL in a way that the URL contains the Kubernetes +minor version that you want to upgrade to. Open the `apt` repository definition +in a text editor of your choice, for example: + +```shell +nano /etc/apt/sources.list.d/kubernetes.list +``` + +You will see a single line with the URL that contains your current Kubernetes +minor version. For example, if you're using v{{< skew currentVersionAddMinor -1 "." >}}, +you should see this: + +``` +deb https://pkgs.k8s.io/core:/stable:/v{{< skew currentVersionAddMinor -1 "." >}}/deb/ / +``` + +Change the version to the next available minor release, for example: + +``` +deb https://pkgs.k8s.io/core:/stable:/{{< param "version" >}}/deb/ / +``` + +Save the file and exit your text editor. + +{{% /tab %}} +{{% tab name="CentOS, RHEL or Fedora" %}} + +Check if you're using the community-hosted repositories or the Google-hosted +repository: + +```shell +cat /etc/yum.repos.d/kubernetes.repo +``` + +If you see the `baseurl` similar to: + +``` +[kubernetes] +name=Kubernetes +baseurl=https://pkgs.k8s.io/core:/stable:/v{{< skew currentVersionAddMinor -1 "." >}}/rpm/ +enabled=1 +gpgcheck=1 +gpgkey=https://pkgs.k8s.io/core:/stable:/v{{< skew currentVersionAddMinor -1 "." >}}/rpm/repodata/repomd.xml.key +exclude=kubelet kubeadm kubectl +``` + +**You're using the community-hosted repositories and you need to change +the package repository.** Otherwise, skip to the next step, but please note that, +we strongly recommend migrating to the community-hosted repositories as +the Google-hosted repository is considered deprecated. See the following +document for more information about migrating to the community-hosted +repositories: TBD + +{{< note >}} +The URL for the community-hosted repositories is not limited to `pkgs.k8s.io`, +it can be one of: + +- `pkgs.k8s.io` +- `pkgs.kubernetes.io` +- `packages.kubernetes.io` +- `packages.kubernetes.io` +{{}} + +Change the repository URLs in a way that URLs contain the Kubernetes +minor version that you want to upgrade to. Open the `yum` repository definition +in a text editor of your choice, for example: + +```shell +nano /etc/yum.repos.d/kubernetes.repo +``` + +You will see two lines with URLs that contain your current Kubernetes +minor version. For example, if you're using v{{< skew currentVersionAddMinor -1 "." >}}, +you should see this: + +``` +[kubernetes] +name=Kubernetes +baseurl=https://pkgs.k8s.io/core:/stable:/v{{< skew currentVersionAddMinor -1 "." >}}/rpm/ +enabled=1 +gpgcheck=1 +gpgkey=https://pkgs.k8s.io/core:/stable:/v{{< skew currentVersionAddMinor -1 "." >}}/rpm/repodata/repomd.xml.key +exclude=kubelet kubeadm kubectl +``` + +Change the version to the next available minor release, for example: + +``` +[kubernetes] +name=Kubernetes +baseurl=https://pkgs.k8s.io/core:/stable:/v{{< param "version" >}}/rpm/ +enabled=1 +gpgcheck=1 +gpgkey=https://pkgs.k8s.io/core:/stable:/v{{< param "version" >}}/rpm/repodata/repomd.xml.key +exclude=kubelet kubeadm kubectl +``` + +Save the file and exit your text editor. + +{{% /tab %}} +{{< /tabs >}} + ## Determine which version to upgrade to Find the latest patch release for Kubernetes {{< skew currentVersion >}} using the OS package manager: diff --git a/content/en/docs/tasks/administer-cluster/kubeadm/upgrading-linux-nodes.md b/content/en/docs/tasks/administer-cluster/kubeadm/upgrading-linux-nodes.md index ca801250a785a..82a2cbb11a601 100644 --- a/content/en/docs/tasks/administer-cluster/kubeadm/upgrading-linux-nodes.md +++ b/content/en/docs/tasks/administer-cluster/kubeadm/upgrading-linux-nodes.md @@ -17,6 +17,148 @@ upgrade the control plane nodes before upgrading your Linux Worker nodes. +## Changing the package repository + +{{< warning >}} + +Follow this step only if you use the community-hosted repositories. +{{< /warning >}} + +{{< tabs name="k8s_install_versions" >}} +{{% tab name="Ubuntu, Debian or HypriotOS" %}} + +Check if you're using the community-hosted repositories or the Google-hosted +repository: + +```shell +cat /etc/apt/sources.list.d/kubernetes.list +``` + +If you see the URL similar to: + +``` +deb https://pkgs.k8s.io/core:/stable:/v{{< skew currentVersionAddMinor -1 "." >}}/deb/ / +``` + +**You're using the community-hosted repositories and you need to change +the package repository.** Otherwise, skip to the next step, but please note that, +we strongly recommend migrating to the community-hosted repositories as +the Google-hosted repository is considered deprecated. See the following +document for more information about migrating to the community-hosted +repositories: TBD + +{{< note >}} +The URL for the community-hosted repositories is not limited to `pkgs.k8s.io`, +it can be one of: + +- `pkgs.k8s.io` +- `pkgs.kubernetes.io` +- `packages.kubernetes.io` +- `packages.kubernetes.io` +{{}} + +Change the repository URL in a way that the URL contains the Kubernetes +minor version that you want to upgrade to. Open the `apt` repository definition +in a text editor of your choice, for example: + +```shell +nano /etc/apt/sources.list.d/kubernetes.list +``` + +You will see a single line with the URL that contains your current Kubernetes +minor version. For example, if you're using v{{< skew currentVersionAddMinor -1 "." >}}, +you should see this: + +``` +deb https://pkgs.k8s.io/core:/stable:/v{{< skew currentVersionAddMinor -1 "." >}}/deb/ / +``` + +Change the version to the next available minor release, for example: + +``` +deb https://pkgs.k8s.io/core:/stable:/{{< param "version" >}}/deb/ / +``` + +Save the file and exit your text editor. + +{{% /tab %}} +{{% tab name="CentOS, RHEL or Fedora" %}} + +Check if you're using the community-hosted repositories or the Google-hosted +repository: + +```shell +cat /etc/yum.repos.d/kubernetes.repo +``` + +If you see the `baseurl` similar to: + +``` +[kubernetes] +name=Kubernetes +baseurl=https://pkgs.k8s.io/core:/stable:/v{{< skew currentVersionAddMinor -1 "." >}}/rpm/ +enabled=1 +gpgcheck=1 +gpgkey=https://pkgs.k8s.io/core:/stable:/v{{< skew currentVersionAddMinor -1 "." >}}/rpm/repodata/repomd.xml.key +exclude=kubelet kubeadm kubectl +``` + +**You're using the community-hosted repositories and you need to change +the package repository.** Otherwise, skip to the next step, but please note that, +we strongly recommend migrating to the community-hosted repositories as +the Google-hosted repository is considered deprecated. See the following +document for more information about migrating to the community-hosted +repositories: TBD + +{{< note >}} +The URL for the community-hosted repositories is not limited to `pkgs.k8s.io`, +it can be one of: + +- `pkgs.k8s.io` +- `pkgs.kubernetes.io` +- `packages.kubernetes.io` +- `packages.kubernetes.io` +{{}} + +Change the repository URLs in a way that URLs contain the Kubernetes +minor version that you want to upgrade to. Open the `yum` repository definition +in a text editor of your choice, for example: + +```shell +nano /etc/yum.repos.d/kubernetes.repo +``` + +You will see two lines with URLs that contain your current Kubernetes +minor version. For example, if you're using v{{< skew currentVersionAddMinor -1 "." >}}, +you should see this: + +``` +[kubernetes] +name=Kubernetes +baseurl=https://pkgs.k8s.io/core:/stable:/v{{< skew currentVersionAddMinor -1 "." >}}/rpm/ +enabled=1 +gpgcheck=1 +gpgkey=https://pkgs.k8s.io/core:/stable:/v{{< skew currentVersionAddMinor -1 "." >}}/rpm/repodata/repomd.xml.key +exclude=kubelet kubeadm kubectl +``` + +Change the version to the next available minor release, for example: + +``` +[kubernetes] +name=Kubernetes +baseurl=https://pkgs.k8s.io/core:/stable:/v{{< param "version" >}}/rpm/ +enabled=1 +gpgcheck=1 +gpgkey=https://pkgs.k8s.io/core:/stable:/v{{< param "version" >}}/rpm/repodata/repomd.xml.key +exclude=kubelet kubeadm kubectl +``` + +Save the file and exit your text editor. + +{{% /tab %}} +{{< /tabs >}} + ## Upgrading worker nodes ### Upgrade kubeadm diff --git a/content/en/docs/tasks/tools/install-kubectl-linux.md b/content/en/docs/tasks/tools/install-kubectl-linux.md index 2b27ea7b47ed2..6c348ca3646b4 100644 --- a/content/en/docs/tasks/tools/install-kubectl-linux.md +++ b/content/en/docs/tasks/tools/install-kubectl-linux.md @@ -22,9 +22,20 @@ Using the latest compatible version of kubectl helps avoid unforeseen issues. The following methods exist for installing kubectl on Linux: -- [Install kubectl binary with curl on Linux](#install-kubectl-binary-with-curl-on-linux) -- [Install using native package management](#install-using-native-package-management) -- [Install using other package management](#install-using-other-package-management) +- [{{% heading "prerequisites" %}}](#-heading-prerequisites-) +- [Install kubectl on Linux](#install-kubectl-on-linux) + - [Install kubectl binary with curl on Linux](#install-kubectl-binary-with-curl-on-linux) + - [Install using native package management](#install-using-native-package-management) + - [Community-hosted repositories](#community-hosted-repositories) + - [Google-hosted repository (Deprecated)](#google-hosted-repository-deprecated) + - [Community-hosted repositories](#community-hosted-repositories-1) + - [Google-hosted repository (Deprecated)](#google-hosted-repository-deprecated-1) + - [Install using other package management](#install-using-other-package-management) +- [Verify kubectl configuration](#verify-kubectl-configuration) +- [Optional kubectl configurations and plugins](#optional-kubectl-configurations-and-plugins) + - [Enable shell autocompletion](#enable-shell-autocompletion) + - [Install `kubectl convert` plugin](#install-kubectl-convert-plugin) +- [{{% heading "whatsnext" %}}](#-heading-whatsnext-) ### Install kubectl binary with curl on Linux @@ -141,6 +152,58 @@ The following methods exist for installing kubectl on Linux: {{< tabs name="kubectl_install" >}} {{% tab name="Debian-based distributions" %}} +{{< warning >}} +Kubernetes has two different package repositories starting from August 2023. +The Google-hosted repository is considered deprecated and we will stop +publishing packages to that repository starting with Kubernetes 1.30. +The community-hosted repositories are replacement for the Google-hosted +repository. There are some important considerations for the community-hosted +repositories: + +- We strongly recommend using the community-hosted repositories especially for + all new setups. For existing setups, manual migration outlined in the + document linked below is required. +- The community-hosted repositories contains only packages starting from + Kubernetes 1.24.0. +- We have a different repository for each Kubernetes minor release. + Please take this into consideration when upgrading to a new minor release. + +For more details about community-hosted repositories, we strongly recommend +checking out the following document: TBD +{{< /warning >}} + +### Community-hosted repositories + +1. Update the `apt` package index and install packages needed to use the Kubernetes `apt` repository: + + ```shell + sudo apt-get update + sudo apt-get install -y apt-transport-https ca-certificates curl + ``` + +2. Download the public signing key for community repositories. The same signing key is used for all repositories so you can disregard the version in URL: + + ```shell + curl -fsSL https://pkgs.k8s.io/core:/stable:/{{< param "version" >}}/deb/Release.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/kubernetes-apt-keyring.gpg > /dev/null + ``` + +3. Add the appropriate Kubernetes `apt` repository. If you're using Kubernetes version different than {{< param "version" >}}, + replace {{< param "version" >}} with the desired minor version in commands below: + + ```shell + echo 'deb https://pkgs.k8s.io/core:/stable:/{{< param "version" >}}/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list + ``` + +4. Update `apt` package index with the new repository and install kubectl: + + ```shell + sudo apt-get update + sudo apt-get install -y kubelet kubeadm kubectl + sudo apt-mark hold kubelet kubeadm kubectl + ``` + +### Google-hosted repository (Deprecated) + 1. Update the `apt` package index and install packages needed to use the Kubernetes `apt` repository: ```shell @@ -181,6 +244,54 @@ You can create this directory if you need to, making it world-readable but write {{% /tab %}} {{% tab name="Red Hat-based distributions" %}} + +{{< warning >}} +Kubernetes has two different package repositories starting from August 2023. +The Google-hosted repository is considered deprecated and we will stop +publishing packages to that repository starting with Kubernetes 1.30. +The community-hosted repositories are replacement for the Google-hosted +repository. There are some important considerations for the community-hosted +repositories: + +- We strongly recommend using the community-hosted repositories especially for + all new setups. For existing setups, manual migration outlined in the + document linked below is required. +- The community-hosted repositories contains only packages starting from + Kubernetes 1.24.0. +- We have a different repository for each Kubernetes minor release. + Please take this into consideration when upgrading to a new minor release. + +For more details about community-hosted repositories, we strongly recommend +checking out the following document: TBD +{{< /warning >}} + +### Community-hosted repositories + +1. Add the Kubernetes `yum` repository. If you're using Kubernetes version different than {{< param "version" >}}, + replace {{< param "version" >}} with the desired minor version in command below: + +```bash +cat <}}/rpm/ +enabled=1 +gpgcheck=1 +gpgkey=https://pkgs.k8s.io/core:/stable:/{{< param "version" >}}/rpm/repodata/repomd.xml.key +exclude=kubelet kubeadm kubectl +EOF +``` + +2. Install kubectl using `yum`: + +```bash +sudo yum install -y kubectl +``` + +### Google-hosted repository (Deprecated) + +1. Add the Kubernetes `yum` repository: + ```bash cat <