Skip to content

Commit

Permalink
Remove Helm v2 support
Browse files Browse the repository at this point in the history 
Helm [v2.17.0](https://github.com/helm/helm/releases/tag/v2.17.0) was the final
release of Helm v2 in October 2020. Helm v2 is unsupported since November 2020,
as detailed in [Helm 2 and the Charts Project Are Now Unsupported](https://helm.sh/blog/helm-2-becomes-unsupported/).

Helm v2 uses an older version of Kubernetes Go client which is incompatible
with Kubernetes Go Client 1.18+. [helm-mapkubeapis](https://github.com/helm/helm-mapkubeapis)
calls Helm v2 storage APIs which in turn call Kubernetes Go client APIs.
This means that the plugin is restricted to using
Helm [v3.1.3](https://github.com/helm/helm/releases/tag/v3.1.3)
(last Helm v3 release which uses Kubernetes Go Client pre 1.18) which was released in April 2020.

It therefore makes sense to remove Helm v2 support.

Signed-off-by: Martin Hickey <[email protected]>
  • Loading branch information
@hickeyma
hickeyma committed Feb 24, 2022
1 parent 6b80213 commit e81d264
Show file tree
Hide file tree
Showing 10 changed files with 1,417 additions and 646 deletions.
4 changes: 2 additions & 2 deletions .circleci/config.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,14 @@ jobs:
shellcheck -x scripts/install_plugin.sh
untagged-build:
docker:
- image: circleci/golang:1.16
- image: circleci/golang:1.17
working_directory: /go/src/github.com/helm/helm-mapkubeapis
steps:
- checkout
- run: make build
tagged-build:
docker:
- image: circleci/golang:1.16
- image: circleci/golang:1.17
working_directory: /go/src/github.com/helm/helm-mapkubeapis
steps:
- checkout
Expand Down
70 changes: 37 additions & 33 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,17 @@
[![CircleCI](https://circleci.com/gh/helm/helm-mapkubeapis/tree/master.svg?style=svg)](https://circleci.com/gh/helm/helm-mapkubeapis/tree/master)
[![Release](https://img.shields.io/github/release/helm/helm-mapkubeapis.svg?style=flat-square)](https://github.com/helm/helm-mapkubeapis/releases/latest)

`mapkubeapis` is a Helm v2/v3 plugin which updates in-place Helm release metadata that contains deprecated or removed Kubernetes APIs to a new instance with supported Kubernetes APIs. Jump to [background to the issue](#background-to-the-issue) for more details on the problem space that the plugin solves.
`mapkubeapis` is a Helm v3 plugin which updates in-place Helm release metadata that contains deprecated or removed Kubernetes APIs to a new instance with supported Kubernetes APIs. Jump to [background to the issue](#background-to-the-issue) for more details on the problem space that the plugin solves.

> Note: Charts need to be updated also to supported Kubernetes APIs to avoid failure during deployment in a Kubernetes version. This is a separate task to the plugin.
> Note: Charts need to be updated also to supported Kubernetes APIs to avoid failure during deployment in a Kubernetes version. This is a separate task to the plugin.
## Prerequisite

- Helm client with `mapkubeapis` plugin installed on the same system
- Access to the cluster(s) that Helm manages. This access is similar to `kubectl` access using [kubeconfig files](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/).
The `--kubeconfig`, `--kube-context` and `--namespace` flags can be used to set the kubeconfig path, kube context and namespace context to override the environment configuration.
- If you try and upgrade a release with unsupported APIs then the upgrade will fail. This is ok in Helm v3 as it will not generate a failed release for Helm. However, Helm v2 does produce a failed release. This needs to be removed before running the plugin on the release. The command to remove the failed release version is: `kubectl delete configmap/secret <release_name>.v<latest_version_number> --namespace <tiller_namespace>`
- If you try and upgrade a release with unsupported APIs then the upgrade will fail. This is ok in Helm v3 as it will not generate a failed release for Helm.
- The plugin updates the lastest release version. The latest release version should be in a `deployed` state as you want to update a successful deployment. If it is not then you need to delete the latest release version. The command to remove a release version is:
- Helm v2: `kubectl delete configmap/secret <release_name>.v<latest_version_number> --namespace <tiller_namespace>`
- Helm v3: `kubectl delete configmap/secret sh.helm.release.v1.<release_name>.v<latest_version_number> --namespace <release_namespace>`

## Install
Expand Down Expand Up @@ -54,40 +53,42 @@ Flags:
--kube-context string name of the kubeconfig context to use
--kubeconfig string path to the kubeconfig file
--mapfile string path to the API mapping file (default "config/Map.yaml")
--namespace string namespace scope of the release. For Helm v2, this is the Tiller namespace (e.g. kube-system)
-s, --release-storage string for Helm v2 only - release storage type/object. It can be 'secrets' or 'configmaps'. This is only used with the 'tiller-out-cluster' flag (default "secrets")
--tiller-out-cluster for Helm v2 only - when Tiller is not running in the cluster e.g. Tillerless
--v2 run for Helm v2 release (default is Helm v3)
--namespace string namespace scope of the release
```

Example output:

```console
$ helm mapkubeapis v2-oldapi --namespace kube-system --v2
2020/04/17 13:05:45 Release 'v2-oldapi' will be checked for deprecated or removed Kubernetes APIs and will be updated if necessary to supported API versions.
2020/04/17 13:05:45 Get release 'v2-oldapi' latest version.
2020/04/17 13:05:45 Check release 'v2-oldapi' for deprecated or removed APIs...
2020/04/17 13:05:45 Found deprecated or removed Kubernetes API:
"apiVersion: apps/v1beta1
kind: Deployment"
$ helm mapkubeapis cluster-role-example --namespace test-cluster-role-example
2022/02/07 18:48:49 Release 'cluster-role-example' will be checked for deprecated or removed Kubernetes APIs and will be updated if necessary to supported API versions.
2022/02/07 18:48:49 Get release 'cluster-role-example' latest version.
2022/02/07 18:48:49 Check release 'cluster-role-example' for deprecated or removed APIs...
2022/02/07 18:48:49 Found 1 instances of deprecated or removed Kubernetes API:
"apiVersion: rbac.authorization.k8s.io/v1beta1
kind: ClusterRole
"
Supported API equivalent:
"apiVersion: apps/v1
kind: Deployment"
2020/04/17 13:05:45 Found deprecated or removed Kubernetes API:
"apiVersion: extensions/v1beta1
kind: Ingress"
"apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
"
2022/02/07 18:48:49 Found 1 instances of deprecated or removed Kubernetes API:
"apiVersion: rbac.authorization.k8s.io/v1beta1
kind: ClusterRoleBinding
"
Supported API equivalent:
"apiVersion: networking.k8s.io/v1beta1
kind: Ingress"
2020/04/17 13:05:45 Finished checking release 'v2-oldapi' for deprecated or removed APIs.
2020/04/17 13:05:45 Deprecated or removed APIs exist, updating release: v2-oldapi.
2020/04/17 13:05:45 Set status of release version 'v2-oldapi.v1' to 'superseded'.
2020/04/17 13:05:45 Release version 'v2-oldapi.v1' updated successfully.
2020/04/17 13:05:45 Add release version 'v2-oldapi.v2' with updated supported APIs.
2020/04/17 13:05:45 Release version 'v2-oldapi.v2' added successfully.
2020/04/17 13:05:45 Release 'v2-oldapi' with deprecated or removed APIs updated successfully to new version.
2020/04/17 13:05:45 Map of release 'v2-oldapi' deprecated or removed APIs to supported versions, completed successfully.
"apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
"
2022/02/07 18:48:49 Finished checking release 'cluster-role-example' for deprecated or removed APIs.
2022/02/07 18:48:49 Deprecated or removed APIs exist, updating release: cluster-role-example.
2022/02/07 18:48:49 Set status of release version 'cluster-role-example.v1' to 'superseded'.
2022/02/07 18:48:49 Release version 'cluster-role-example.v1' updated successfully.
2022/02/07 18:48:49 Add release version 'cluster-role-example.v2' with updated supported APIs.
2022/02/07 18:48:49 Release version 'cluster-role-example.v2' added successfully.
2022/02/07 18:48:49 Release 'cluster-role-example' with deprecated or removed APIs updated successfully to new version.
2022/02/07 18:48:49 Map of release 'cluster-role-example' deprecated or removed APIs to supported versions, completed successfully.
```

## API Mapping

The mapping information of deprecated or removed APIs to supported APIs is configured in the [Map.yaml](https://github.com/helm/helm-mapkubeapis/blob/master/config/Map.yaml) file. The file is a list of entries similar to the following:
Expand All @@ -102,29 +103,32 @@ The mapping information of deprecated or removed APIs to supported APIs is confi
The plugin when performing update of a Helm release metadata first loads the map file from the `config` directory where the plugin is run from. If the map file is a different name or in a different location, you can use the `--mapfile` flag to specify the different mapping file.

The OOTB mapping file is configured as follows:

- The search and replace strings are in order with `apiVersion` first and then `kind`. This should be changed if the Helm release metadata is rendered with different search/replace string.
- The strings contain UNIX/Linux line feeds. This means that `\n` is used to signify line separation between properties in the strings. This should be changed if the Helm release metadata is rendered in Windows or Mac.
- Each mapping contains the Kubernetes version that the API is deprecated and removed in. This information is important as the plugin checks that the deprecated version (uses removed if deprecated unset) is later than the Kubernetes version that it is running against. If it is then no mapping occurs for this API as it not yet deprecated in this Kubernetes version and hence the new API is not yet supported. Otherwise, the mapping can proceed.

> Note: The Helm release metadata can be checked by following the steps in:
- Helm v2: [Updating API Versions of a Release Manifest](https://github.com/helm/helm/blob/dev-v2/docs/kubernetes_apis.md#updating-api-versions-of-a-release-manifest)
- Helm v3: [Updating API Versions of a Release Manifest](https://helm.sh/docs/topics/kubernetes_apis/#updating-api-versions-of-a-release-manifest)

## Background to the issue

For details on the background to this issue, it is recommended to read the docs appropriate to your Helm version. The docs can be accessed as follows:
- Helm v2: [Deprecated Kubernetes APIs](https://github.com/helm/helm/blob/dev-v2/docs/kubernetes_apis.md)
- Helm v3: [Deprecated Kubernetes APIs](https://helm.sh/docs/topics/kubernetes_apis)

The Helm documentation describes the problem when Helm releases that are already deployed with APIs that are no longer supported. If the Kubernetes cluster (containing such releases) is updated to a version where the APIs are removed, then Helm becomes unable to manage such releases anymore. It does not matter if the chart being passed in the upgrade contains the supported API versions or not.

This is what the `mapkubeapis` plugin resolves. It fixes the issue by mapping releases which contain deprecated or removed Kubernetes APIs to supported APIs. This is performed inline in the release metadata where the existing release is `superseded` and a new release (metadata only) is added. The deployed Kubernetes resources are updated automatically by Kubernetes during upgrade of its version. Once this operation is completed, you can then upgrade using the chart with supported APIs.

## Helm v2 Support

Helm [v2.17.0](https://github.com/helm/helm/releases/tag/v2.17.0) was the final release of Helm v2 in October 2020. Helm v2 is unsupported since November 2020, as detailed in [Helm 2 and the Charts Project Are Now Unsupported](https://helm.sh/blog/helm-2-becomes-unsupported/). `mapkubeapis` Helm v2 support finished in [release v0.2.0](https://github.com/helm/helm-mapkubeapis/releases/tag/v0.2.0).

## Developer (From Source) Install

If you would like to handle the build yourself, this is the recommended way to do it.

You must first have [Go v1.13+](http://golang.org) installed, and then you run:
You must first have [Go v1.17+](http://golang.org) installed, and then you run:

```console
$ mkdir -p ${GOPATH}/src/github.com
Expand Down
18 changes: 6 additions & 12 deletions cmd/mapkubeapis/environment.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,14 +22,11 @@ import (

// EnvSettings defined settings
type EnvSettings struct {
DryRun bool
KubeConfigFile string
KubeContext string
MapFile string
Namespace string
RunV2 bool
StorageType string
TillerOutCluster bool
DryRun bool
KubeConfigFile string
KubeContext string
MapFile string
Namespace string
}

// New returns default env settings
Expand All @@ -49,8 +46,5 @@ func (s *EnvSettings) AddFlags(fs *pflag.FlagSet) {
fs.StringVar(&s.KubeConfigFile, "kubeconfig", "", "path to the kubeconfig file")
fs.StringVar(&s.KubeContext, "kube-context", s.KubeContext, "name of the kubeconfig context to use")
fs.StringVar(&s.MapFile, "mapfile", s.MapFile, "path to the API mapping file")
fs.StringVar(&s.Namespace, "namespace", s.Namespace, "namespace scope of the release. For Helm v2, this is the Tiller namespace e.g. kube-system")
fs.BoolVar(&s.RunV2, "v2", false, "run for Helm v2 release. The default is Helm v3.")
fs.BoolVar(&s.TillerOutCluster, "tiller-out-cluster", false, "for Helm v2 only - when Tiller is not running in the cluster e.g. Tillerless")
fs.StringVarP(&s.StorageType, "release-storage", "s", "secrets", "for Helm v2 only - release storage type/object. It can be 'secrets' or 'configmaps'. This is only used with the 'tiller-out-cluster' flag")
fs.StringVar(&s.Namespace, "namespace", s.Namespace, "namespace scope of the release")
}
23 changes: 2 additions & 21 deletions cmd/mapkubeapis/map.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,6 @@ import (
"github.com/spf13/cobra"

"github.com/helm/helm-mapkubeapis/pkg/common"
v2 "github.com/helm/helm-mapkubeapis/pkg/v2"
v3 "github.com/helm/helm-mapkubeapis/pkg/v3"
)

Expand All @@ -36,9 +35,6 @@ type MapOptions struct {
MapFile string
ReleaseName string
ReleaseNamespace string
RunV2 bool
StorageType string
TillerOutCluster bool
}

var (
Expand Down Expand Up @@ -99,9 +95,6 @@ func runMap(cmd *cobra.Command, args []string) error {
MapFile: settings.MapFile,
ReleaseName: releaseName,
ReleaseNamespace: settings.Namespace,
RunV2: settings.RunV2,
StorageType: settings.StorageType,
TillerOutCluster: settings.TillerOutCluster,
}
kubeConfig := common.KubeConfig{
Context: settings.KubeContext,
Expand Down Expand Up @@ -129,22 +122,10 @@ func Map(mapOptions MapOptions, kubeConfig common.KubeConfig) error {
MapFile: mapOptions.MapFile,
ReleaseName: mapOptions.ReleaseName,
ReleaseNamespace: mapOptions.ReleaseNamespace,
StorageType: mapOptions.StorageType,
TillerOutCluster: mapOptions.TillerOutCluster,
}

if mapOptions.RunV2 {
// default namespace to the Tiller default namespace
if options.ReleaseNamespace == "" {
options.ReleaseNamespace = "kube-system"
}
if err := v2.MapReleaseWithUnSupportedAPIs(options); err != nil {
return err
}
} else {
if err := v3.MapReleaseWithUnSupportedAPIs(options); err != nil {
return err
}
if err := v3.MapReleaseWithUnSupportedAPIs(options); err != nil {
return err
}

log.Printf("Map of release '%s' deprecated or removed APIs to supported versions, completed successfully.\n", mapOptions.ReleaseName)
Expand Down
Loading

0 comments on commit e81d264

Please sign in to comment.