|
| 1 | +--- |
| 2 | +layout: "kubernetes" |
| 3 | +page_title: "Kubernetes: Upgrade Guide for Kubernetes Provider v2.0.0" |
| 4 | +description: |- |
| 5 | + 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. |
| 6 | +--- |
| 7 | + |
| 8 | +# Upgrading to v2.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 | +## Installing and testing this update |
| 13 | + |
| 14 | +Use `terraform init` to install version 2 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. To opt out of this change, see the guide below and update your Terraform config file to match the existing resource settings (for example, set `automount_service_account_token=false`). Then run `terraform plan` again to ensure no resource updates will be applied. |
| 15 | + |
| 16 | +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. Otherwise, some commands might fail with `Error: missing expected {`. |
| 17 | + |
| 18 | +## Changes in v2.0.0 |
| 19 | + |
| 20 | +### Changes to Kubernetes credentials supplied in the provider block |
| 21 | + |
| 22 | +We have made several changes to the way access to Kubernetes is configured in the provider block. |
| 23 | + |
| 24 | +1. The `load_config_file` attribute has been removed. |
| 25 | +2. Support for the `KUBECONFIG` environment variable has been dropped. (Use `KUBE_CONFIG_PATH` or `KUBE_CONFIG_PATHS` instead). |
| 26 | +3. The `config_path` attribute will no longer default to `~/.kube/config`. |
| 27 | + |
| 28 | +The above changes have been made to encourage the best practice of configuring access to Kubernetes in the provider block explicitly, instead of relying upon default paths or `KUBECONFIG` being set. We have done this because allowing the provider to configure its access to Kubernetes implicitly caused confusion with a subset of our users. It also created risk for users who use Terraform to manage multiple clusters. Requiring explicit configuration for Kubernetes in the provider block eliminates the possibility that the configuration will be applied to the wrong cluster. |
| 29 | + |
| 30 | +You will therefore need to explicitly configure access to your Kubernetes cluster in the provider block going forward. For many users this will simply mean specifying the `config_path` attribute in the provider block. Users already explicitly configuring the provider should not be affected by this change, but will need to remove the `load_config_file` attribute if they are currently using it. |
| 31 | + |
| 32 | +### Changes to the `load_balancers_ingress` block on Service and Ingress |
| 33 | + |
| 34 | +We changed the `load_balancers_ingress` block on the Service and Ingress resources and data sources to align with the upstream Kubernetes API. `load_balancers_ingress` was a computed attribute that allowed users to obtain the `ip` or `hostname` of a `load_balancer`. Instead of `load_balancers_ingress`, users should use `status[].load_balancer[].ingress[]` to obtain the `ip` or `hostname` attributes. |
| 35 | + |
| 36 | +```hcl |
| 37 | +output "ingress_hostname" { |
| 38 | + value = kubernetes_ingress.example_ingress.status[0].load_balancer[0].ingress[0].hostname |
| 39 | +} |
| 40 | +``` |
| 41 | + |
| 42 | +### The `automount_service_account_token` attribute now defaults to `true` on Service, Deployment, StatefulSet, and DaemonSet |
| 43 | + |
| 44 | +Previously if `automount_service_account_token = true` was not set on the Service, Deployment, StatefulSet, or DaemonSet resources, the service account token was not mounted, even when a `service_account_name` was specified. This lead to confusion for many users, because our implementation did not align with the default behavior of the Kubernetes API, which defaults to `true` for this attribute. |
| 45 | + |
| 46 | +```hcl |
| 47 | +resource "kubernetes_deployment" "example" { |
| 48 | + metadata { |
| 49 | + name = "terraform-example" |
| 50 | + labels = { |
| 51 | + test = "MyExampleApp" |
| 52 | + } |
| 53 | + } |
| 54 | +
|
| 55 | + spec { |
| 56 | + replicas = 1 |
| 57 | +
|
| 58 | + selector { |
| 59 | + match_labels = { |
| 60 | + test = "MyExampleApp" |
| 61 | + } |
| 62 | + } |
| 63 | +
|
| 64 | + template { |
| 65 | + metadata { |
| 66 | + labels = { |
| 67 | + test = "MyExampleApp" |
| 68 | + } |
| 69 | + } |
| 70 | +
|
| 71 | + spec { |
| 72 | + container { |
| 73 | + image = "nginx:1.7.8" |
| 74 | + name = "example" |
| 75 | + } |
| 76 | + |
| 77 | + service_account_name = "default" |
| 78 | + automount_service_account_token = false |
| 79 | + } |
| 80 | + } |
| 81 | + } |
| 82 | +} |
| 83 | +``` |
| 84 | + |
| 85 | +### Normalize wait defaults across Deployment, DaemonSet, StatefulSet, Service, Ingress, and Job |
| 86 | + |
| 87 | +All of the `wait_for` attributes now default to `true`, including: |
| 88 | +- `wait_for_rollout` on the `kubernetes_deployment`, `kubernetes_daemonset`, and `kubernetes_stateful_set` resources |
| 89 | +- `wait_for_loadbalancer` on the `kubernetes_service` and `kubernetes_ingress` resources |
| 90 | +- `wait_for_completion` on the `kubernetes_job` resource |
| 91 | + |
| 92 | +Previously some of them defaulted to `false` while others defaulted to `true`, causing an inconsistent user experience. If you don't want Terraform to wait for the specified condition before moving on, you must now always set the appropriate attribute to `false` |
| 93 | + |
| 94 | +```hcl |
| 95 | +resource "kubernetes_service" "myapp1" { |
| 96 | + metadata { |
| 97 | + name = "myapp1" |
| 98 | + } |
| 99 | +
|
| 100 | + spec { |
| 101 | + selector = { |
| 102 | + app = kubernetes_pod.example.metadata[0].labels.app |
| 103 | + } |
| 104 | +
|
| 105 | + session_affinity = "ClientIP" |
| 106 | + type = "LoadBalancer" |
| 107 | +
|
| 108 | + port { |
| 109 | + port = 8080 |
| 110 | + target_port = 80 |
| 111 | + } |
| 112 | + } |
| 113 | +
|
| 114 | + wait_for_load_balancer = "false" |
| 115 | +} |
| 116 | +``` |
| 117 | + |
| 118 | +### Changes to the `limits` and `requests` attributes on all resources that support a PodSpec |
| 119 | + |
| 120 | +The `limits` and `requests` attributes on all resources that include a PodSpec, are now a map. This means that `limits {}` must be changed to `limits = {}`, and the same for `requests`. This change impacts the following resources: `kubernetes_deployment`, `kubernetes_daemonset`, `kubernetes_stateful_set`, `kubernetes_pod`, `kubernetes_job`, `kubernetes_cron_job`. |
| 121 | + |
| 122 | +This change was made to enable the use of extended resources, such as GPUs, in these fields. |
| 123 | + |
| 124 | +```hcl |
| 125 | +resource "kubernetes_pod" "test" { |
| 126 | + metadata { |
| 127 | + name = "terraform-example" |
| 128 | + } |
| 129 | +
|
| 130 | + spec { |
| 131 | + container { |
| 132 | + image = "nginx:1.7.9" |
| 133 | + name = "example" |
| 134 | + |
| 135 | + resources { |
| 136 | + limits = { |
| 137 | + cpu = "0.5" |
| 138 | + memory = "512Mi" |
| 139 | + "nvidia/gpu" = "1" |
| 140 | + } |
| 141 | +
|
| 142 | + requests = { |
| 143 | + cpu = "250m" |
| 144 | + memory = "50Mi" |
| 145 | + "nvidia/gpu" = "1" |
| 146 | + } |
| 147 | + } |
| 148 | + } |
| 149 | + } |
| 150 | +} |
| 151 | +``` |
| 152 | + |
| 153 | + |
| 154 | +### Dropped support for Terraform 0.11 |
| 155 | + |
| 156 | +All builds of the Kubernetes provider going forward will no longer work with Terraform 0.11. See [Upgrade Guides](https://www.terraform.io/upgrade-guides/index.html) for how to migrate your configurations to a newer version of Terraform. |
| 157 | + |
| 158 | +### Upgrade to v2 of the Terraform Plugin SDK |
| 159 | + |
| 160 | +Contributors to the provider will be interested to know this upgrade has brought the latest version of the [Terraform Plugin SDK](https://github.com/hashicorp/terraform-plugin-sdk) which introduced a number of enhancements to the developer experience. Details of the changes introduced can be found under [Extending Terraform](https://www.terraform.io/docs/extend/guides/v2-upgrade-guide.html). |
0 commit comments