How to fix Error creating Kubernetes Service: field is immutable in Terraform

TerraformINTERMEDIATEMEDIUMUpdated Dec 31, 2025· 188 views

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.

Quick fix

Fixes Error creating Kubernetes Service: field is immutable

spec.clusterIP: Invalid value: "": field is immutable
  1. Identify which field is immutable
  2. Delete the existing Service or resource
  3. Update your configuration with the new values
  4. Recreate the resource with updated configuration
terraform — error
spec.clusterIP: Invalid value: "": field is immutable
Error creating Kubernetes Service: field is immutable

What this error means

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.

Typical symptoms

  • Terraform apply fails with an error message containing 'field is immutable'
  • The error specifically mentions 'spec.clusterIP: Invalid value: "":field is immutable'
  • Helm upgrades fail when trying to modify Service specifications
  • kubectl replace or kubectl apply commands reject Service updates

Common causes

  1. Attempting to change the clusterIP of an existing Service (most common)
  2. Modifying label selectors in Deployments after initial creation
  3. The last-applied-configuration annotation contains conflicting field values
  4. Helm or other tools trying to enforce default values on immutable fields
  5. Using kubectl apply with empty or null values for immutable fields

How to fix "Error creating Kubernetes Service: field is immutable"

1Identify which field is immutable

Read the error message carefully to determine which field cannot be modified. Look for the specific field name in the error output:

bash
spec.clusterIP: Invalid value: "": field is immutable

This 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)

2Delete the existing Service or resource

Delete the resource that has the immutable field you're trying to change. In Terraform, you can delete the resource from state:

bash
terraform destroy -target=kubernetes_service.your_service

Or manually delete from the cluster:

bash
kubectl delete service my-service

For Helm releases, delete the Service before upgrading if necessary:

bash
kubectl delete service my-release-service
helm upgrade my-release my-chart
3Update your configuration with the new values

Modify your Terraform, Kubernetes YAML, or Helm values to include the changes you want:

hcl
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.

4Recreate the resource with updated configuration

Apply the new configuration to recreate the Service or resource:

bash
terraform apply

Or with kubectl:

bash
kubectl apply -f service.yaml

Or with Helm:

bash
helm upgrade --install my-release my-chart

Kubernetes will create a new Service with a newly assigned clusterIP.

5Handle last-applied-configuration annotation issues

If you're still getting the error after deletion, the issue may be the kubectl.kubernetes.io/last-applied-configuration annotation. Remove it:

bash
kubectl annotate service my-service kubectl.kubernetes.io/last-applied-configuration- --overwrite

The trailing dash tells Kubernetes to remove the annotation. This clears cached configuration metadata that may be causing conflicts.

6For Helm users: add proper metadata

If using Helm, ensure your Service has the correct Helm-specific annotations and labels to avoid metadata conflicts on future upgrades:

yaml
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 spec

This prevents Helm from trying to re-apply conflicting field values on upgrades.

Advanced notes

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.

Frequently asked questions

What does "Error creating Kubernetes Service: field is immutable" mean?
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.
How do I fix "Error creating Kubernetes Service: field is immutable"?
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.
What causes "Error creating Kubernetes Service: field is immutable"?
Attempting to change the clusterIP of an existing Service (most common) Modifying label selectors in Deployments after initial creation The last-applied-configuration annotation contains conflicting field values
Is the "Error creating Kubernetes Service: field is immutable" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading