diff --git a/README.md b/README.md
index 4355172e..dab3b810 100644
--- a/README.md
+++ b/README.md
@@ -86,6 +86,8 @@ spec:
     kind: HorizontalPodAutoscaler
     name: podinfo
   service:
+    # service name (optional)
+    name: podinfo
     # ClusterIP port number
     port: 9898
     # container port name or number (optional)
diff --git a/docs/gitbook/faq.md b/docs/gitbook/faq.md
index 1cec5a75..a6236a8b 100644
--- a/docs/gitbook/faq.md
+++ b/docs/gitbook/faq.md
@@ -188,6 +188,8 @@ spec:
     kind: Deployment
     name: podinfo
   service:
+    # service name (optional)
+    name: podinfo
     # ClusterIP port number (required)
     port: 9898
     # container port name or number
@@ -196,19 +198,21 @@ spec:
     portName: http
 ```
 
+If the `service.name` is not specified, then `targetRef.name` is used for the apex domain and canary/primary services name prefix.
+You should treat the service name as an immutable field, changing it could result in routing conflicts.
+
 Based on the canary spec service, Flagger generates the following Kubernetes ClusterIP service:
 
-* `<targetRef.name>.<namespace>.svc.cluster.local`  
+* `<service.name>.<namespace>.svc.cluster.local`  
     selector `app=<name>-primary`
-* `<targetRef.name>-primary.<namespace>.svc.cluster.local`  
+* `<service.name>-primary.<namespace>.svc.cluster.local`  
     selector `app=<name>-primary`
-* `<targetRef.name>-canary.<namespace>.svc.cluster.local`  
+* `<service.name>-canary.<namespace>.svc.cluster.local`  
     selector `app=<name>`
 
 This ensures that traffic coming from a namespace outside the mesh to `podinfo.test:9898`
 will be routed to the latest stable release of your app. 
 
-
 ```yaml
 apiVersion: v1
 kind: Service
diff --git a/docs/gitbook/how-it-works.md b/docs/gitbook/how-it-works.md
index 717d1b6e..7a6ad1e8 100644
--- a/docs/gitbook/how-it-works.md
+++ b/docs/gitbook/how-it-works.md
@@ -32,6 +32,8 @@ spec:
     kind: HorizontalPodAutoscaler
     name: podinfo
   service:
+    # service name (optional)
+    name: podinfo
     # ClusterIP port number
     port: 9898
     # ClusterIP port name can be http or grpc (default http)