Skip to content

Commit

Permalink
Move breaking change details into separate docs. add notice on v7.0.0 (…
Browse files Browse the repository at this point in the history 
…#355)

* move breaking change detials into separate docs. add notice on v7.0.0
  • Loading branch information
@lonegunmanb
lonegunmanb authored Apr 26, 2023
1 parent 5419474 commit ca7a93d
Show file tree
Hide file tree
Showing 4 changed files with 138 additions and 94 deletions.
93 changes: 93 additions & 0 deletions NoticeOnUpgradeTov5.0.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# Notice on Upgrade to v5.x

V5.0.0 is a major version upgrade and a lot of breaking changes have been introduced. Extreme caution must be taken during the upgrade to avoid resource replacement and downtime by accident.

Running the `terraform plan` first to inspect the plan is strongly advised.

## Terraform and terraform-provider-azurerm version restrictions

Now Terraform core's lowest version is v1.2.0 and terraform-provider-azurerm's lowest version is v3.21.0.

## variable `user_assigned_identity_id` has been renamed.

variable `user_assigned_identity_id` has been renamed to `identity_ids` and it's type has been changed from `string` to `list(string)`.

## `addon_profile` in outputs is no longer available.

It has been broken into the following new outputs:

* `aci_connector_linux`
* `aci_connector_linux_enabled`
* `azure_policy_enabled`
* `http_application_routing_enabled`
* `ingress_application_gateway`
* `ingress_application_gateway_enabled`
* `key_vault_secrets_provider`
* `key_vault_secrets_provider_enabled`
* `oms_agent`
* `oms_agent_enabled`
* `open_service_mesh_enabled`

## The following variables have been renamed from `enable_xxx` to `xxx_enabled`

* `enable_azure_policy` has been renamed to `azure_policy_enabled`
* `enable_http_application_routing` has been renamed to `http_application_routing_enabled`
* `enable_ingress_application_gateway` has been renamed to `ingress_application_gateway_enabled`
* `enable_log_analytics_workspace` has been renamed to `log_analytics_workspace_enabled`
* `enable_open_service_mesh` has been renamed to `open_service_mesh_enabled`
* `enable_role_based_access_control` has been renamed to `role_based_access_control_enabled`

## `nullable = true` has been added to the following variables so setting them to `null` explicitly will use the default value

* `log_analytics_workspace_enable`
* `os_disk_type`
* `private_cluster_enabled`
* `rbac_aad_managed`
* `rbac_aad_admin_group_object_ids`
* `network_policy`
* `enable_node_public_ip`

## `var.admin_username`'s default value has been removed

In v4.x `var.admin_username` has a default value `azureuser` and has been removed in V5.0.0. Since the `admin_username` argument in `linux_profile` block is a ForceNew argument, any value change to this argument will trigger a Kubernetes cluster replacement **SO THE EXTREME CAUTION MUST BE TAKEN**. The module's callers must set `var.admin_username` to `azureuser` explicitly if they didn't set it before.

## `module.ssh-key` has been removed

The file named `private_ssh_key` which contains the tls private key will be deleted since the `local_file` resource has been removed. Now the private key is exported via `generated_cluster_private_ssh_key` in output and the corresponding public key is exported via `generated_cluster_public_ssh_key` in output.

A `moved` block has been added to relocate the existing `tls_private_key` resource to the new address. If the `var.admin_username` is not `null`, no action is needed.

Resource `tls_private_key`'s creation now is conditional. Users may see the destruction of existing `tls_private_key` in the generated plan if `var.admin_username` is `null`.

## `system_assigned_identity` in the output has been renamed to `cluster_identity`

The `system_assigned_identity` was:

```hcl
output "system_assigned_identity" {
value = azurerm_kubernetes_cluster.main.identity
}
```

Now it has been renamed to `cluster_identity`, and the block has been changed to:

```hcl
output "cluster_identity" {
description = "The `azurerm_kubernetes_cluster`'s `identity` block."
value = try(azurerm_kubernetes_cluster.main.identity[0], null)
}
```

The callers who used to read the cluster's identity block need to remove the index in their expression, from `module.aks.system_assigned_identity[0]` to `module.aks.cluster_identity`.

## The following outputs are now sensitive. All outputs referenced them must be declared as sensitive too

* `client_certificate`
* `client_key`
* `cluster_ca_certificate`
* `generated_cluster_private_ssh_key`
* `host`
* `kube_admin_config_raw`
* `kube_config_raw`
* `password`
* `username`
5 changes: 5 additions & 0 deletions NoticeOnUpgradeTov6.0.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Notice on Upgrade to v6.x

We've added a CI pipeline for this module to speed up our code review and to enforce a high code quality standard, if you want to contribute by submitting a pull request, please read [Pre-Commit & Pr-Check & Test](#Pre-Commit--Pr-Check--Test) section, or your pull request might be rejected by CI pipeline.

A pull request will be reviewed when it has passed Pre Pull Request Check in the pipeline, and will be merged when it has passed the acceptance tests. Once the ci Pipeline failed, please read the pipeline's output, thanks for your cooperation.
32 changes: 32 additions & 0 deletions NoticeOnUpgradeTov7.0.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Notice on Upgrade to v7.x

## Add validation block to enforce users to change `sku_tier` from `Paid` to `Standard`

AzureRM's minimum version is `>= 3.51, < 4.0` now.
[`var.sku_tier` cannot be set to `Paid` anymore](https://github.com/hashicorp/terraform-provider-azurerm/issues/20887), now possible values are `Free` and `Standard`.

## Ignore changes on `kubernetes_version` from outside of Terraform

Related issue: #335

Two new resources would be created when upgrading from v6.x to v7.x:

* `null_resource.kubernetes_version_keeper`
* `azapi_update_resource.aks_cluster_post_create`

`azurerm_kubernetes_cluster.main` resource would ignore change on `kubernetes_version` from outside of Terraform in case AKS cluster's patch version has been upgraded automatically.
When you change `var.kubernetes_version`'s value, it would trigger a re-creation of `null_resource.kubernetes_version_keeper` and re-creation of `azapi_update_resource.aks_cluster_post_create`, which would upgrade the AKS cluster's `kubernetes_version`.

`azapi` provider is required to be configured in your Terraform configuration.

## Fix #315 by amending missing `linux_os_config` block

In v6.0, `default_node_pool.linux_os_config` block won't be added to `azurerm_kubernetes_cluster.main` resource when `var.enable_auto_scaling` is `true`. This bug has been fixed in v7.0.0 so you might see a diff on `azurerm_kubernetes_cluster.main` resource.

## Wrap `log_analytics_solution_id` to an object to fix #263.

`var.log_analytics_solution_id` is now an object with `id` attribute. This change is to fix #263.

## Remove unused net_profile_docker_bridge_cidr

`var.net_profile_docker_bridge_cidr` has been [deprecated](https://github.com/hashicorp/terraform-provider-azurerm/issues/18119) and is not used in the module anymore and has been removed.
102 changes: 8 additions & 94 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,105 +6,19 @@ This Terraform module deploys a Kubernetes cluster on Azure using AKS (Azure Kub

-> **NOTE:** If you have not assigned `client_id` or `client_secret`, A `SystemAssigned` identity will be created.

## Notice on Upgrade to V6.x
## Notice on breaking changes

We've added a CI pipeline for this module to speed up our code review and to enforce a high code quality standard, if you want to contribute by submitting a pull request, please read [Pre-Commit & Pr-Check & Test](#Pre-Commit--Pr-Check--Test) section, or your pull request might be rejected by CI pipeline.
Please be aware that major version(e.g., from 6.8.0 to 7.0.0) update contains breaking changes that may impact your infrastructure. It is crucial to review these changes with caution before proceeding with the upgrade.

A pull request will be reviewed when it has passed Pre Pull Request Check in the pipeline, and will be merged when it has passed the acceptance tests. Once the ci Pipeline failed, please read the pipeline's output, thanks for your cooperation.
In most cases, you will need to adjust your Terraform code to accommodate the changes introduced in the new major version. We strongly recommend reviewing the changelog and migration guide to understand the modifications and ensure a smooth transition.

## Notice on Upgrade to V5.x
To help you in this process, we have provided detailed documentation on the breaking changes, new features, and any deprecated functionalities. Please take the time to read through these resources to avoid any potential issues or disruptions to your infrastructure.

V5.0.0 is a major version upgrade and a lot of breaking changes have been introduced. Extreme caution must be taken during the upgrade to avoid resource replacement and downtime by accident.
* [Notice on Upgrade to v7.x](./NoticeOnUpgradeTov7.0.md)
* [Notice on Upgrade to v6.x](./NoticeOnUpgradeTov6.0.md)
* [Notice on Upgrade to v5.x](./NoticeOnUpgradeTov5.0.md)

Running the `terraform plan` first to inspect the plan is strongly advised.

### Terraform and terraform-provider-azurerm version restrictions

Now Terraform core's lowest version is v1.2.0 and terraform-provider-azurerm's lowest version is v3.21.0.

### variable `user_assigned_identity_id` has been renamed.

variable `user_assigned_identity_id` has been renamed to `identity_ids` and it's type has been changed from `string` to `list(string)`.

### `addon_profile` in outputs is no longer available.

It has been broken into the following new outputs:

* `aci_connector_linux`
* `aci_connector_linux_enabled`
* `azure_policy_enabled`
* `http_application_routing_enabled`
* `ingress_application_gateway`
* `ingress_application_gateway_enabled`
* `key_vault_secrets_provider`
* `key_vault_secrets_provider_enabled`
* `oms_agent`
* `oms_agent_enabled`
* `open_service_mesh_enabled`

### The following variables have been renamed from `enable_xxx` to `xxx_enabled`

* `enable_azure_policy` has been renamed to `azure_policy_enabled`
* `enable_http_application_routing` has been renamed to `http_application_routing_enabled`
* `enable_ingress_application_gateway` has been renamed to `ingress_application_gateway_enabled`
* `enable_log_analytics_workspace` has been renamed to `log_analytics_workspace_enabled`
* `enable_open_service_mesh` has been renamed to `open_service_mesh_enabled`
* `enable_role_based_access_control` has been renamed to `role_based_access_control_enabled`

### `nullable = true` has been added to the following variables so setting them to `null` explicitly will use the default value

* `log_analytics_workspace_enable`
* `os_disk_type`
* `private_cluster_enabled`
* `rbac_aad_managed`
* `rbac_aad_admin_group_object_ids`
* `network_policy`
* `enable_node_public_ip`

### `var.admin_username`'s default value has been removed

In v4.x `var.admin_username` has a default value `azureuser` and has been removed in V5.0.0. Since the `admin_username` argument in `linux_profile` block is a ForceNew argument, any value change to this argument will trigger a Kubernetes cluster replacement **SO THE EXTREME CAUTION MUST BE TAKEN**. The module's callers must set `var.admin_username` to `azureuser` explicitly if they didn't set it before.

### `module.ssh-key` has been removed

The file named `private_ssh_key` which contains the tls private key will be deleted since the `local_file` resource has been removed. Now the private key is exported via `generated_cluster_private_ssh_key` in output and the corresponding public key is exported via `generated_cluster_public_ssh_key` in output.

A `moved` block has been added to relocate the existing `tls_private_key` resource to the new address. If the `var.admin_username` is not `null`, no action is needed.

Resource `tls_private_key`'s creation now is conditional. Users may see the destruction of existing `tls_private_key` in the generated plan if `var.admin_username` is `null`.

### `system_assigned_identity` in the output has been renamed to `cluster_identity`

The `system_assigned_identity` was:

```hcl
output "system_assigned_identity" {
value = azurerm_kubernetes_cluster.main.identity
}
```

Now it has been renamed to `cluster_identity`, and the block has been changed to:

```hcl
output "cluster_identity" {
description = "The `azurerm_kubernetes_cluster`'s `identity` block."
value = try(azurerm_kubernetes_cluster.main.identity[0], null)
}
```

The callers who used to read the cluster's identity block need to remove the index in their expression, from `module.aks.system_assigned_identity[0]` to `module.aks.cluster_identity`.

### The following outputs are now sensitive. All outputs referenced them must be declared as sensitive too

* `client_certificate`
* `client_key`
* `cluster_ca_certificate`
* `generated_cluster_private_ssh_key`
* `host`
* `kube_admin_config_raw`
* `kube_config_raw`
* `password`
* `username`
Remember, upgrading to a major version with breaking changes should be done carefully and thoroughly tested in your environment. If you have any questions or concerns, please don't hesitate to reach out to our support team for assistance.

## Usage in Terraform 1.2.0

Expand Down

0 comments on commit ca7a93d

Please sign in to comment.