github.com/tiancandevloper/helm@v2.17.0+incompatible/docs/kubernetes_apis.md (about) 1 # Deprecated Kubernetes APIs 2 3 Kubernetes is an API-driven system and the API evolves over time to reflect 4 the evolving understanding of the problem space. This is common practice 5 across systems and their APIs. An important part of evolving APIs is a good 6 deprecation policy and process to inform users of how changes to APIs are 7 implemented. In other words, consumers of your API need to know in advance and 8 in what release an API will be removed or changed. This removes the element of 9 surprise and breaking changes to consumers. 10 11 The [Kubernetes deprecation policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/) 12 documents how Kubernetes handles the changes to its API versions. The policy 13 for deprecation states the timeframe that API versions will be supported following 14 a deprecation announcement. It is therefore important to be aware of deprecation 15 announcements and know when API versions will be removed, to help minimize the 16 effect. 17 18 This is an example of an announcement [for the removal of deprecated API versions in Kubernetes 1.16](https://kubernetes.io/blog/2019/07/18/api-deprecations-in-1-16/) 19 and was advertised a few months prior to the release. These API versions would 20 have been announced for deprecation prior to this again. This shows that there 21 is a good policy in place which informs consumers of API version support. 22 23 Helm templates specify a [Kubernetes API group](https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-groups) 24 when defining a Kubernetes object, similar to a Kubernetes manifest file. It is 25 specified in the `apiVersion` field of the template and it identifies the API 26 version of the Kubernetes object. This means that Helm users and chart maintainers 27 need to be aware when Kubernetes API versions have been deprecated and in what 28 Kubernetes version they will be removed. 29 30 ## Chart Maintainers 31 32 You should audit your charts checking for Kubernetes API versions that are 33 deprecated or are removed in a Kubernetes version. The API versions found as 34 due to be or that are now out of support, should be updated to the supported 35 version and a new version of the chart released. The API version is defined by 36 the `kind` and `apiVersion` fields. For example, here is a removed `Deployment` 37 object API version in Kubernetes 1.16: 38 39 ```yaml 40 apiVersion: apps/v1beta1 41 kind: Deployment 42 ``` 43 44 ## Helm Users 45 46 You should audit the charts that you use (similar to [chart maintainers](#chart-maintainers)) 47 and identify any charts where API versions are deprecated or removed in a 48 Kubernetes version. For the charts identified, you need to check for the latest 49 version of the chart (which has supported API versions) or update the chart 50 yourself. 51 52 Additionally, you also need to audit any charts deployed (i.e. Helm releases) 53 checking again for any deprecated or removed API versions. This can be done by 54 getting details of a release using the `helm get manifest` command. 55 56 The means for updating a Helm release to supported APIs depends on your findings 57 as follows: 58 59 1. If you find deprecated API versions only then: 60 - Perform a `helm upgrade` with a version of the chart with supported Kubernetes 61 API versions 62 - Add a description in the upgrade, something along the lines to not perform a 63 rollback to a Helm version prior to this current version 64 2. If you find any API version(s) that is/are removed in a Kubernetes version 65 then: 66 - If you are running a Kubernetes version where the API version(s) are still 67 available (for example, you are on Kubernetes 1.15 and found you use APIs that 68 will be removed in Kubernetes 1.16): 69 - Follow the step 1 procedure 70 - Otherwise (for example, you are already running a Kubernetes version where 71 some API versions reported by `helm get manifest` are no longer available): 72 - You need to edit the release manifest that is stored in the cluster to 73 update the API versions to supported APIs. See 74 [Updating API Versions of a Release Manifest](#updating-api-versions-of-a-release-manifest) 75 for more details 76 77 > Note: In all cases of updating a Helm release with supported APIs, you should 78 never rollback the release to a version prior to the release version with the 79 supported APIs. 80 81 > Recommendation: The best practice is to upgrade releases using deprecated API 82 versions to supported API versions, prior to upgrading to a kubernetes cluster 83 that removes those API versions. 84 85 If you don't update a release as suggested previously, you will have an error 86 similar to the following when trying to upgrade a release in a Kubernetes version 87 where its API version(s) is/are removed: 88 89 ``` 90 Error: UPGRADE FAILED: current release manifest contains removed kubernetes api(s) 91 for this kubernetes version and it is therefore unable to build the kubernetes 92 objects for performing the diff. error from kubernetes: unable to recognize "": 93 no matches for kind "Deployment" in version "apps/v1beta1" 94 ``` 95 96 Helm fails in this scenario because it attempts to create a diff patch between 97 the current deployed release (which contains the Kubernetes APIs that are removed 98 in this Kubernetes version) against the chart you are passing with the 99 updated/supported API versions. The underlying reason for failure is that when 100 Kubernetes removes an API version, the Kubernetes Go client library can no longer 101 parse the deprecated objects and Helm therefore fails when calling the library. 102 Helm unfortunately is unable to recover from this situation and is no longer able 103 to manage such a release. 104 See [Updating API Versions of a Release Manifest](#updating-api-versions-of-a-release-manifest) 105 for more details on how to recover from this scenario. 106 107 ## Updating API Versions of a Release Manifest 108 109 The manifest is a property of the Helm release object which is stored in the data 110 field of a ConfigMap (default) or Secret in the cluster. The data field contains 111 a gzipped [protobuf object](developers#grpc-and-protobuf) which is base 64 112 encoded (there is an additional base 64 encoding for a Secret). There is 113 a Secret/ConfigMap per release version/revision in the namespace of the release. 114 115 You can use the Helm [mapkubeapis](https://github.com/hickeyma/helm-mapkubeapis) 116 plugin to perform the update of a release to supported APIs. Check out the 117 readme for more details. 118 119 Alternatively, you can follow these manual steps to perform an update of the API 120 versions of a release manifest. Depending on your configuration you will follow 121 the steps for the ConfigMap or Secret backend. 122 123 - Prerequisites: 124 - HELM_PROTOBUF_SCHEMA: [Helm protobuf schema](https://github.com/helm/helm/tree/dev-v2/_proto) 125 - PROTOBUF_SCHEMA: [Protobuf base schema](https://github.com/protocolbuffers/protobuf/tree/master/src) 126 - Get the name of the ConfigMap or Secret associated with the latest deployed release: 127 - ConfigMap backend: `kubectl get configmap -l OWNER=TILLER,STATUS=DEPLOYED,NAME=<release_name> --namespace <tiller_namespace> | awk '{print $1}' | grep -v NAME` 128 - Secrets backend: `kubectl get secret -l OWNER=TILLER,STATUS=DEPLOYED,NAME=<release_name> --namespace <tiller_namespace> | awk '{print $1}' | grep -v NAME` 129 - Get latest deployed release details: 130 - ConfigMap backend: `kubectl get configmap <release_configmap_name> -n <tiller_namespace> -o yaml > release.yaml` 131 - Secrets backend: `kubectl get secret <release_secret_name> -n <tiller_namespace> -o yaml > release.yaml` 132 - Backup the release in case you need to restore if something goes wrong: 133 - `cp release.yaml release.bak` 134 - In case of emergency, restore: `kubectl apply -f release.bak -n <tiller_namespace>` 135 - Decode the release object: 136 - ConfigMap backend: `cat release.yaml | grep -oP '(?<=release: ).*' | base64 -d | gzip -d | protoc --proto_path ${HELM_PROTOBUF_SCHEMA} --proto_path ${PROTOBUF_SCHEMA} --decode hapi.release.Release ${HELM_PROTOBUF_SCHEMA}/hapi/**/* > release.data.decoded` 137 - Secrets backend:`cat release.yaml | grep -oP '(?<=release: ).*' | base64 -d | base64 -d | gzip -d | protoc --proto_path ${HELM_PROTOBUF_SCHEMA} --proto_path ${PROTOBUF_SCHEMA} --decode hapi.release.Release ${HELM_PROTOBUF_SCHEMA}/hapi/**/* > release.data.decoded` 138 - Change API versions of the manifests. Can use any tool (e.g. editor) to make 139 the changes. This is in the `manifest` field of your decoded release 140 object (`release.data.decoded`) 141 - Encode the release object: 142 - ConfigMap backend: `cat release.data.decoded | protoc --proto_path ${HELM_PROTOBUF_SCHEMA} --proto_path ${PROTOBUF_SCHEMA} --encode hapi.release.Release ${HELM_PROTOBUF_SCHEMA}/hapi/**/* | gzip | base64 --wrap 0` 143 - Secrets backend: `cat release.data.decoded | protoc --proto_path ${HELM_PROTOBUF_SCHEMA} --proto_path ${PROTOBUF_SCHEMA} --encode hapi.release.Release ${HELM_PROTOBUF_SCHEMA}/hapi/**/* | gzip | base64 | base64 --wrap 0` 144 - Replace `data.release` property value in the deployed release file (`release.yaml`) 145 with the new encoded release object 146 - Apply file to namespace: `kubectl apply -f release.yaml -n <tiller_namespace>` 147 - Perform a `helm upgrade` with a version of the chart with supported Kubernetes 148 API versions 149 - Add a description in the upgrade, something along the lines to not perform a 150 rollback to a Helm version prior to this current version 151 152 > Note: Ensure to use the `protobuf schema` for the deployed Tiller version, otherwise the decoding might fail