Skip to content

Upgrade Third-Party Dependencies

This page outlines the process for upgrading third-party dependencies for OpenTofu-based infrastructure deployments.

Third-party dependencies refer to the software that is installed by the OpenTofu scripts to support the deployment of kdb Insights Enterprise.

When to upgrade

Each release of kdb Insights Enterprise includes a Third-party Dependencies section in the release notes. This section lists the specific versions of the third-party infrastructure components that have been tested and verified for compatibility with that specific kdb Insights Enterprise release and provides links to download the required files.

To ensure continued stability, compatibility, and support, it is recommended that you update these dependencies in conjunction with the corresponding upgrade of kdb Insights Enterprise.

Upgrade a dependency

scripts/terraform.sh provides a single upgrade command that upgrades one dependency at a time: it optionally updates the pinned version, runs tofu init, plans the change scoped to just that dependency, shows you the plan, and only applies it once you confirm.

  1. Switch to your local kxi-terraform directory.

  2. Run the manage-cluster.sh script.

    ./scripts/manage-cluster.sh

    .\scripts\manage-cluster.bat

  3. Run the upgrade command, giving it the dependency name from the table below and the new version (see the kdb Insights Enterprise release notes for the version to use):

    ./scripts/terraform.sh upgrade <dependency> <version>

  4. Review the plan the command prints, and confirm when prompted to apply it. If you decline, no changes are applied and the plan is left on disk for inspection.

  5. Verify the new version.

    helm ls -n <namespace>
Dependency name Cloud(s) Namespace (for helm ls)
cert-manager AWS, ACS, GCP cert-manager
nginx-community AWS, ACS, GCP nginx-community
rook-ceph AWS, ACS, GCP rook-ceph — see Upgrade Rook-Ceph below, it must be upgraded one minor version at a time
metrics-server AWS kube-system
cluster-autoscaler AWS kube-system
aws-cloudwatch-metrics AWS amazon-cloudwatch
aws-efs-csi-driver AWS kube-system
aws-load-balancer-controller AWS kube-system
aws-ebs-csi-driver AWS kube-system
aws-fsx-lustre-csi-driver AWS kube-system

Note

If a dependency is disabled on your deployment (for example rook-ceph when enable_rook_ceph = false), the command exits with an error telling you no matching resource was found in state, instead of silently doing nothing.

Upgrade Rook-Ceph

Important

Rook-Ceph must be upgraded one minor version at a time. For example, to upgrade from 1.15.9 to 1.17.0, two sequential minor version upgrades are required: 1.15.9 -> 1.16.7 -> 1.17.0.

Review the rook-ceph release notes for breaking changes.

Read the rook-ceph upgrade documentation for more details.

Run the upgrade command once per minor version, in sequence:

./scripts/terraform.sh upgrade rook-ceph 1.16.7
./scripts/terraform.sh upgrade rook-ceph 1.17.0

Each run upgrades both the rook-ceph operator and the rook-ceph-cluster Helm releases together, planning and applying them as one change.

Ingress post upgrade steps

If you have deployed kdb Insights Enterprise with Encryption in flight enabled, you need to re-enable this setting on your chosen Ingress Controller post upgrade.

This involves using helm and the kxi cli to interact with your kdb Insight Enterprise deploy. Follow the steps below:

nginx-community

  1. Get your kdb Insights Enterprise values using helm:

    INSIGHTS_NAMESPACE=<insights namespace>
helm get values -n $INSIGHTS_NAMESPACE insights -o yaml > insights-values.yaml

  2. Download and install the latest kxi cli, refer to the installation guide for more details.

    Note

    Requires kxi cli version 1.18.3 or greater!

  3. Get your current ingress controller settings:

    helm get values -n nginx-community nginx-community -o yaml > nginx-community-values.yaml.1

  4. Run the kxi cli to update your ingress controller settings:

    INSIGHTS_VERSION=<insights version>
kxi task run nginx-f5 --version $INSIGHTS_VERSION --encryption true -f insights-values.yaml

  5. Get your updated ingress controller settings:

    helm get values -n nginx-community nginx-community -o yaml > nginx-community-values.yaml.2

  6. Diff your ingress controller settings and ensure the istio podAnnotations and podLabels are present:

    diff nginx-community-values.yaml.1 nginx-community-values.yaml.2

    The output should look similar to the below:

    >   podAnnotations:
>     traffic.sidecar.istio.io/excludeInboundPorts: "443"
>     traffic.sidecar.istio.io/includeInboundPorts: ""
>   podLabels:
>     sidecar.istio.io/inject: "true"

AWS cluster third-party dependencies

Note

This section applies to AWS (EKS) only.

The following third-party dependencies are installed on AWS clusters as Helm charts by the config OpenTofu stage. They are all deployed to the kube-system namespace (except aws-cloudwatch-metrics, deployed to amazon-cloudwatch), and their versions are pinned by variables in terraform/k8s_config_aws/variables.tf. The table below lists the current default versions; use it as a reference for the versions you are upgrading from, and use the ./scripts/terraform.sh upgrade <dependency> <version> command above to upgrade each one.

Component Helm repository Version OpenTofu variable upgrade dependency name
aws-ebs-csi-driver https://kubernetes-sigs.github.io/aws-ebs-csi-driver 2.60.1 aws_ebs_csi_driver_helm_version aws-ebs-csi-driver
aws-efs-csi-driver https://kubernetes-sigs.github.io/aws-efs-csi-driver 3.4.1 aws_efs_csi_driver_helm_version aws-efs-csi-driver
aws-load-balancer-controller https://aws.github.io/eks-charts 3.4.0 aws_load_balancer_controller_helm_version aws-load-balancer-controller
cluster-autoscaler https://kubernetes.github.io/autoscaler 9.57.0 cluster_autoscaler_helm_version cluster-autoscaler
metrics-server https://kubernetes-sigs.github.io/metrics-server 3.13.0 metrics_server_helm_version metrics-server
aws-cloudwatch-metrics https://aws.github.io/eks-charts 0.0.11 aws_cloudwatch_metrics_helm_version aws-cloudwatch-metrics
aws-fsx-lustre-csi-driver https://kubernetes-sigs.github.io/aws-fsx-csi-driver 1.17.0 aws_fsx_lustre_csi_driver_helm_version aws-fsx-lustre-csi-driver

Note

These versions are managed by Renovate and are bumped automatically as new versions are released, so the values above reflect the current repository defaults.

Upgrade the EKS managed add-ons

Note

This section applies to AWS (EKS) only.

The coredns, vpc-cni, and kube-proxy components are installed as EKS managed add-ons (aws_eks_addon) rather than as Helm charts. They are declared in the addons block of terraform/modules/k8s_cluster_aws/main.tf in the cluster OpenTofu stage, and no add-on version is pinned. The vpc-cni and kube-proxy add-ons are configured with before_compute = true so they are installed before the node groups are created.

Upgrade automatically with the cluster

Because no addon_version is set, AWS resolves the default add-on version for the active cluster_version. As a result, when you upgrade the Kubernetes version (see Upgrade Kubernetes Cluster), applying the cluster upgrade automatically pulls the matching default add-on versions. No separate step is required in this case.

Re-apply an add-on to pick up the current default

To re-apply an add-on outside of a cluster upgrade (for example, after AWS changes its default version), run:

./scripts/terraform.sh upgrade coredns
./scripts/terraform.sh upgrade vpc-cni
./scripts/terraform.sh upgrade kube-proxy

These commands take no version argument — the add-on has no pinned version, so the command simply re-applies it and picks up the current AWS default.

Pin an add-on to a specific version

Follow these steps to pin an add-on to a specific version independently of a cluster upgrade. This isn't supported by the upgrade command since it requires an OpenTofu code change (adding an addon_version key) rather than just bumping a version variable.

  1. Find the available add-on versions for your Kubernetes version.

    aws eks describe-addon-versions --kubernetes-version <version> --addon-name <coredns|vpc-cni|kube-proxy>

  2. Switch to your local kxi-terraform directory.

  3. Open terraform/modules/k8s_cluster_aws/main.tf and set the addon_version for the relevant add-on in the addons block, for example:

    addons = {
  coredns = {
    addon_version               = "<version>"
    resolve_conflicts_on_create = "OVERWRITE"
    resolve_conflicts_on_update = "OVERWRITE"
  }
  ...
}

  4. Run the manage-cluster.sh script.

    ./scripts/manage-cluster.sh

    .\scripts\manage-cluster.bat

  5. Run the upgrade command for the relevant add-on to plan and apply the change.

    ./scripts/terraform.sh upgrade coredns

  6. Verify the add-on version.

    aws eks describe-addon --cluster-name $TF_VAR_cluster_name --addon-name <addon> --query 'addon.addonVersion'
Back to top