Skip to content

Commit 1b0b53a

Browse files
jrhoustonjrhouston
committed
Add upgrade guide
1 parent 8496b96 commit 1b0b53a

File tree

1 file changed

+142
-0
lines changed

1 file changed

+142
-0
lines changed

‎docs/guides/v3-upgrade-guide.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
subcategory: ""
3+
page_title: "Kubernetes: Upgrade Guide for Kubernetes Provider v3.0.0"
4+
description: |-
5+
This guide covers the changes introduced in v3.0.0 of the Kubernetes provider and what you may need to do to upgrade your configuration.
6+
---
7+
8+
# Upgrading to v3.0.0 of the Kubernetes provider
9+
10+
This guide covers the changes introduced in v2.0.0 of the Kubernetes provider and what you may need to do to upgrade your configuration.
11+
12+
Use `terraform init` to install version 3 of the provider. Then run `terraform plan` to determine if the upgrade will affect any existing resources. Some resources will have updated defaults and may be modified as a result. Update your config files to match the existing resource settings Then run `terraform plan` again to ensure no resource updates will be applied.
13+
14+
NOTE: Even if there are no resource updates to apply, you may need to run `terraform refresh` to update your state to the newest version.
15+
16+
## Installing and testing this update
17+
18+
The `required_providers` block can be used to move between version 2.x and version 3.x of the Kubernetes provider, for testing purposes. Please note that this is only possible using `terraform plan`. Once you run `terraform apply` or `terraform refresh`, the changes to Terraform State become permanent, and rolling back is no longer an option. It may be possible to roll back the State by making a copy of `.terraform.tfstate` before running `apply` or `refresh`, but this configuration is unsupported.
19+
20+
### Using required_providers to test the update
21+
22+
The version of the Kubernetes provider can be controlled using the `required_providers` block:
23+
24+
```hcl
25+
terraform {
26+
required_providers {
27+
kubernetes = {
28+
source = "hashicorp/kubernetes"
29+
version = ">= 3.0"
30+
}
31+
}
32+
}
33+
```
34+
35+
When the above code is in place, run `terraform init` to upgrade the provider version.
36+
37+
```
38+
$ terraform init -upgrade
39+
```
40+
41+
Then run `terraform plan` to see what changes will be applied.
42+
43+
```
44+
$ export KUBE_CONFIG_PATH=$KUBECONFIG
45+
$ terraform plan
46+
```
47+
48+
Using the output from `terraform plan`, you can make modifications to your existing Terraform config, to avoid any unwanted resource changes.
49+
50+
### Rolling back to version 2.x.x.
51+
52+
If you've run the above upgrade and plan, but you don't want to proceed with the 3.0 upgrade, you can roll back using the following steps. NOTE: this will only work if you haven't run `terraform apply` or `terraform refresh` while testing version 3 of the provider.
53+
54+
Set the provider version back to 2.x.x.
55+
56+
```
57+
terraform {
58+
required_providers {
59+
kubernetes = {
60+
source = "hashicorp/kubernetes"
61+
version = ">= 2.38.0"
62+
}
63+
}
64+
}
65+
```
66+
67+
Then run `terraform init -upgrade` to install the old provider version.
68+
69+
```
70+
$ terraform init -upgrade
71+
72+
Initializing the backend...
73+
74+
Initializing provider plugins...
75+
- Finding hashicorp/kubernetes versions matching "2.38.0"...
76+
- Installing hashicorp/kubernetes v2.38.0...
77+
- Installed hashicorp/kubernetes v2.38.0 (signed by HashiCorp)
78+
```
79+
80+
The provider is now downgraded.
81+
82+
## Changes in v3.0.0
83+
84+
## Dropping support for Terraform versions before `v1.0.0`
85+
86+
This release upgrades the Terraform protocol version used by the provider to the [latest version](https://developer.hashicorp.com/terraform/plugin/terraform-plugin-protocol#protocol-version-6). This protocol version only supports Terraform versions from `v1.0.0`. Configurations dependent on Terraform versions before `v1.0.0` should pin this provider to `v2.x.x`.
87+
88+
### Changes to Kubernetes credentials for `kubernetes_manifest` resource
89+
90+
We have made changes to the way the `kubernetes_manifest` resolves credentials to make it consistent with the other resources. In `v2.x.x` this resource would allow environment variables such as `KUBE_CONFIG_PATH` to override values present in the configuration file. This was inconsistent with how all other resources resolve environent variables, which is to use the value from the environment if no value is specified in the configuration.
91+
92+
### Deprecation of non-versioned resource names
93+
94+
This version of the provider marks all resources which do not have a version suffix as deprecated. A table of unversioned resources and the version suffixed resource that should be used is below.
95+
96+
| Unversioned resource | Version Suffixed Resource |
97+
|-----------------------------------------------|---------------------------------------------------------|
98+
| kubernetes_namespace | kubernetes_namespace_v1 |
99+
| kubernetes_service | kubernetes_service_v1 |
100+
| kubernetes_service_account | kubernetes_service_account_v1 |
101+
| kubernetes_default_service_account | kubernetes_default_service_account_v1 |
102+
| kubernetes_config_map | kubernetes_config_map_v1 |
103+
| kubernetes_secret | kubernetes_secret_v1 |
104+
| kubernetes_pod | kubernetes_pod_v1 |
105+
| kubernetes_endpoints | kubernetes_endpoints_v1 |
106+
| kubernetes_limit_range | kubernetes_limit_range_v1 |
107+
| kubernetes_persistent_volume | kubernetes_persistent_volume_v1 |
108+
| kubernetes_persistent_volume_claim | kubernetes_persistent_volume_claim_v1 |
109+
| kubernetes_replication_controller | kubernetes_replication_controller_v1 |
110+
| kubernetes_resource_quota | kubernetes_resource_quota_v1 |
111+
| kubernetes_api_service | kubernetes_api_service_v1 |
112+
| kubernetes_deployment | kubernetes_deployment_v1 |
113+
| kubernetes_daemonset | kubernetes_daemon_set_v1 |
114+
| kubernetes_stateful_set | kubernetes_stateful_set_v1 |
115+
| kubernetes_job | kubernetes_job_v1 |
116+
| kubernetes_cron_job | kubernetes_cron_job_v1 |
117+
| kubernetes_horizontal_pod_autoscaler | kubernetes_horizontal_pod_autoscaler_v1 or kubernetes_horizontal_pod_autoscaler_v2 |
118+
| kubernetes_certificate_signing_request | kubernetes_certificate_signing_request_v1 |
119+
| kubernetes_role | kubernetes_role_v1 |
120+
| kubernetes_role_binding | kubernetes_role_binding_v1 |
121+
| kubernetes_cluster_role | kubernetes_cluster_role_v1 |
122+
| kubernetes_cluster_role_binding | kubernetes_cluster_role_binding_v1 |
123+
| kubernetes_ingress | kubernetes_ingress_v1 |
124+
| kubernetes_ingress_class | kubernetes_ingress_class_v1 |
125+
| kubernetes_network_policy | kubernetes_network_policy_v1 |
126+
| kubernetes_pod_disruption_budget | kubernetes_pod_disruption_budget_v1 |
127+
| kubernetes_pod_security_policy | *Removed from upstream* |
128+
| kubernetes_priority_class | kubernetes_priority_class_v1 |
129+
| kubernetes_validating_webhook_configuration | kubernetes_validating_webhook_configuration_v1 |
130+
| kubernetes_mutating_webhook_configuration | kubernetes_mutating_webhook_configuration_v1 |
131+
| kubernetes_storage_class | kubernetes_storage_class_v1 |
132+
| kubernetes_csi_driver | kubernetes_csi_driver_v1 |
133+
134+
## Removal of `kubernetes_pod_security_policy`
135+
136+
This resource was removed from the Kubernetes API v1.25 and has been removed from this provider.
137+
138+
## Behaviour of the `wait_for_rollout` attribute of `kubernetes_daemon_set_v1`
139+
140+
A [long standing bug in the wait logic for this resource has been fixed](https://github.com/hashicorp/terraform-provider-kubernetes/issues/2092) where despite this flag being set to true, the resource would not wait for the daemonset to become ready. As this attribute is set to false users may now notice that this resource takes longer to create as it will wait by default.
141+
142+

0 commit comments

Comments
 (0)