Install Coral with Terraform + Helm

Before you apply

• Turn on the cluster’s OIDC issuer and workload identity (oidc_issuer_enabled and workload_identity_enabled).
• Point the azurerm provider at the cluster’s subscription.
• Custom role names are unique across a tenant, so only one module call creates the role. Every other cluster passes that call’s role_definition_id output. If those clusters are in other subscriptions, list those subscriptions in the creating call’s role_assignable_scopes.

The module

module "zoorik_coral" {
  source          = "getzoorik/zoorik-coral/azurerm"
  version         = "~> 0.1"
  cluster_id      = "<AKS resource id>"
  location        = "<region>"
  oidc_issuer_url = "<the cluster's OIDC issuer URL>"
}

It creates the user-assigned managed identity zoorik-agent-<cluster> with the federated credential zoorik-agent, the custom role Zoorik Node Removal v2 and one assignment of that role, scoped to this cluster only. Its output client_id is the client id of the agent’s identity.

Then install the agent

Install the chart as Install Coral with Helm says, with these values:

clusterResourceId: <cluster_id>
serviceAccount:
  annotations:
    azure.workload.identity/client-id: <client_id>

The namespace and the service account are both fixed at zoorik-agent, because the federated credential is bound to them.

Before you apply

• For Pod Identity, install the eks-pod-identity-agent add-on, unless EKS Auto Mode is on.
• For Pod Identity, apply this module before installing the chart: the agent gets AWS credentials only if the association exists when its pod starts. If the agent already runs, restart it once after the apply: kubectl --context <context> -n zoorik-agent rollout restart deployment/zoorik-agent.
• For IRSA, set irsa_oidc_issuer_url. The cluster’s IAM OIDC provider must already exist.
• Point the aws provider at the cluster’s account and region.

The module

module "zoorik_coral" {
  source       = "getzoorik/zoorik-coral/aws"
  version      = "~> 0.1"
  cluster_name = "<EKS cluster name>"
}

It creates the IAM role zoorik-agent-<cluster>, its inline policy and the EKS Pod Identity association for zoorik-agent/zoorik-agent. With irsa_oidc_issuer_url set, the role trusts the cluster’s IAM OIDC provider instead, and no association is created. Its output role_arn is the ARN of the agent’s role.

Then install the agent

Install the chart as Install Coral with Helm says. With Pod Identity, set only:

clusterResourceId: <cluster ARN>

With IRSA:

clusterResourceId: <cluster ARN>
serviceAccount:
  annotations:
    eks.amazonaws.com/role-arn: <role_arn>

Machine deletion and pool-minimum lowering are on by default (lower_minimums = true), the same as zoorikctl’s default Yes. With lower_minimums = false, the agent cannot lower a pool’s or group’s minimum.

The agent records the old minimum in the tags coral.zoorik.com_original-min and coral.zoorik.com_lowered-min (AKS) or coral.zoorik.com/original-min and coral.zoorik.com/lowered-min (EKS), and disconnect puts it back.

If Terraform manages your node pools, ignore what the agent changes, or each apply undoes it. On AKS:

lifecycle {
  ignore_changes = [
    min_count,
    tags["coral.zoorik.com_original-min"],
    tags["coral.zoorik.com_lowered-min"],
  ]
}

On the cluster’s default pool, the same fields sit under default_node_pool[0]. On EKS, each node the agent removes also lowers the group’s desired size. For aws_eks_node_group:

lifecycle {
  ignore_changes = [
    scaling_config[0].min_size,
    scaling_config[0].desired_size,
    tags["coral.zoorik.com/original-min"],
    tags["coral.zoorik.com/lowered-min"],
  ]
}

For aws_autoscaling_group, ignore min_size, desired_capacity and tag.