Kubernetes Service fields like clusterIP are immutable once created. This error occurs when trying to update these protected fields. The solution is to delete and recreate the Service or resource with your desired configuration.
In Kubernetes, certain resource fields are immutable—they cannot be changed after the resource is created. This is by design, following Kubernetes' immutable infrastructure paradigm. The most commonly affected field is the Service's clusterIP, which is automatically assigned by Kubernetes and cannot be modified. When you attempt to update these immutable fields through Terraform, kubectl, Helm, or other tools, Kubernetes rejects the change with a "field is immutable" error. This is a safety mechanism to prevent configuration drift and ensure cluster stability.
Read the error message carefully to determine which field cannot be modified. Look for the specific field name in the error output:
spec.clusterIP: Invalid value: "": field is immutableThis tells you the exact field that Kubernetes won't allow you to change. Common immutable fields include:
- spec.clusterIP (Service)
- spec.selector (Deployment)
- metadata.name (all resources)
Delete the resource that has the immutable field you're trying to change. In Terraform, you can delete the resource from state:
terraform destroy -target=kubernetes_service.your_serviceOr manually delete from the cluster:
kubectl delete service my-serviceFor Helm releases, delete the Service before upgrading if necessary:
kubectl delete service my-release-service
helm upgrade my-release my-chartModify your Terraform, Kubernetes YAML, or Helm values to include the changes you want:
resource "kubernetes_service" "my_service" {
metadata {
name = "my-service"
}
spec {
selector = {
app = "my-app"
}
port {
port = 80
target_port = 8080
}
# If changing to ClusterIP, omit this field to let Kubernetes assign it
# type = "LoadBalancer"
}
}If you need a specific clusterIP, explicitly specify it in the configuration before initial creation—never try to change it later.
Apply the new configuration to recreate the Service or resource:
terraform applyOr with kubectl:
kubectl apply -f service.yamlOr with Helm:
helm upgrade --install my-release my-chartKubernetes will create a new Service with a newly assigned clusterIP.
If you're still getting the error after deletion, the issue may be the kubectl.kubernetes.io/last-applied-configuration annotation. Remove it:
kubectl annotate service my-service kubectl.kubernetes.io/last-applied-configuration- --overwriteThe trailing dash tells Kubernetes to remove the annotation. This clears cached configuration metadata that may be causing conflicts.
If using Helm, ensure your Service has the correct Helm-specific annotations and labels to avoid metadata conflicts on future upgrades:
apiVersion: v1
kind: Service
metadata:
name: my-service
annotations:
meta.helm.sh/release-name: my-release
meta.helm.sh/release-namespace: default
labels:
app.kubernetes.io/managed-by: Helm
spec:
# ... rest of specThis prevents Helm from trying to re-apply conflicting field values on upgrades.
Immutable infrastructure principle: Kubernetes follows the immutable infrastructure paradigm, which means infrastructure should not be modified after deployment. If changes are needed, resources should be destroyed and recreated. This design ensures predictability and reduces configuration drift.
Specific immutable fields by resource type:
- Service: spec.clusterIP, spec.type (mostly)
- Deployment: spec.selector (in apps/v1)
- StatefulSet: spec.serviceName
Provider-specific considerations:
- Terraform Kubernetes provider: Use terraform taint to force recreation when immutable fields change
- Helm: Always handle Service recreation carefully—consider using helm delete before helm upgrade when Service specs change fundamentally
- kubectl: Use kubectl replace --force as a last resort; it will delete and recreate the resource
For managed Kubernetes services (EKS, GKE, AKS), the same immutability rules apply, but the infrastructure management may be more restricted.
Error: Error rendering template: template not found
How to fix "template not found" error in Terraform
Error: Error generating private key
How to fix 'Error generating private key' in Terraform
Error: Error creating local file: open: permission denied
How to fix "Error creating local file: permission denied" in Terraform
Error: line endings have changed from CRLF to LF
Line endings have changed from CRLF to LF in Terraform
Error: Error making HTTP request: 500 Internal Server Error
HTTP 500 Internal Server Error in Terraform