istioctl analyze messages documentation (#5291)

* Added first draft of all analyzer messages

* Fixed linter errors

* Add glossary entry

* Implemented PR comments

* Addressed more PR comments

* More PR comments

* PR comments implemented

* More PR comment fixes

* Removed blank line, updated annotation gloss entry

content/en/docs/reference/config/analysis/ist0001/index.md

@@ -3,4 +3,7 @@ title: InternalError
 layout: analysis-message
 ---
 
-We've done something bad. Why did we do something bad? We should stop doing something bad!
+This error is most likely caused by an internal problem in Istio, not user error.
+
+To resolve this problem, check if this is a known issue or report it as a new one using
+the [Istio issues page](https://github.com/istio/istio/issues).

content/en/docs/reference/config/analysis/ist0101/index.md

@@ -0,0 +1,50 @@
+---
+title: ReferencedResourceNotFound
+layout: analysis-message
+---
+
+This message occurs when an Istio resource references another resource that does
+not exist. This will lead to errors when Istio tries to look up the referenced
+resource but cannot find it.
+
+For example, you receive this error:
+
+{{< text plain >}}
+Error [IST0101] (VirtualService httpbin.default) Referenced gateway not found: "httpbin-gateway-bogus"
+{{< /text >}}
+
+In this example, the `VirtualService` refers to a gateway that does not exist:
+
+{{< text yaml >}}
+apiVersion: networking.istio.io/v1alpha3
+kind: Gateway
+metadata:
+  name: httpbin-gateway
+spec:
+  selector:
+    istio: ingressgateway
+  servers:
+  - port:
+      number: 80
+      name: http2
+      protocol: HTTP2
+    hosts:
+    - "*"
+---
+apiVersion: networking.istio.io/v1alpha3
+kind: VirtualService
+metadata:
+  name: httpbin
+spec:
+  hosts:
+  - "*"
+  gateways:
+  - httpbin-gateway-bogus #  Should have been "httpbin-gateway"
+  http:
+  - route:
+    - destination:
+        host: httpbin-gateway
+{{< /text >}}
+
+To resolve this problem, look for the resource type in the detailed error
+message, correct your Istio configuration and try again.

content/en/docs/reference/config/analysis/ist0102/index.md

@@ -0,0 +1,27 @@
+---
+title: NamespaceNotInjected
+layout: analysis-message
+---
+
+This message occurs when you have a namespace that is missing the
+[annotation](/docs/reference/config/annotations/) to indicate whether the
+namespace is auto-injected, for example `sidecar.istio.io/inject`.
+
+For example, you receive this error:
+
+{{< text plain >}}
+Warn [IST0102] (Namespace default) The namespace is not enabled for Istio
+injection. Run 'kubectl label namespace default istio-injection=enabled' to
+enable it, or 'kubectl label namespace default istio-injection=disabled' to
+explicitly mark it as not needing injection Error: Analyzer found issues.
+{{< /text >}}
+
+To resolve this problem, use an annotation to explicitly declare whether
+or not you want the namespace to be auto-injected. For example:
+
+{{< text bash >}}
+$ kubectl label namespace <namespace-name> istio-injection=enabled
+{{< /text >}}
+
+It is strongly recommended to explicitly define the desired injection behavior.
+Forgetting to annotate a namespace is a common cause of errors.

content/en/docs/reference/config/analysis/ist0103/index.md

@@ -0,0 +1,17 @@
+---
+title: PodMissingProxy
+layout: analysis-message
+---
+
+This message occurs when the sidecar is not present or not working correctly.
+
+This most commonly occurs when you enable auto-injection but do not restart your
+pods afterwards, causing the sidecar to be missing.
+
+To resolve this problem, restart your pods and try again.
+
+For example, to restart the pods, use this command:
+
+{{< text bash >}}
+$ kubectl rollout restart deployment
+{{< /text >}}

content/en/docs/reference/config/analysis/ist0104/index.md

@@ -0,0 +1,41 @@
+---
+title: GatewayPortNotOnWorkload
+layout: analysis-message
+---
+
+This message occurs when a gateway (usually `istio-ingressgateway`) offers a
+port that the Kubernetes service workload selected by the gateway does not.
+
+For example, your Istio configuration contains these values:
+
+{{< text yaml >}}
+# Gateway with bogus port
+
+apiVersion: networking.istio.io/v1alpha3
+kind: Gateway
+metadata:
+  name: httpbin-gateway
+spec:
+  selector:
+    istio: ingressgateway
+  servers:
+  - port:
+      number: 80
+      name: http
+      protocol: HTTP
+    hosts:
+    - "*"
+  - port:
+      number: 8004
+      name: http2
+      protocol: HTTP
+    hosts:
+    - "*"
+{{< /text >}}
+
+In this example, the `GatewayPortNotOnWorkload` message occurs because this
+configuration uses port 8004, but a default `IngressGateway` is only open on ports
+80, 443, 31400, and 15443.
+
+To resolve this problem, change your gateway configuration to use a valid port
+on the workload and try again.

content/en/docs/reference/config/analysis/ist0105/index.md

@@ -3,10 +3,10 @@ title: IstioProxyVersionMismatch
 layout: analysis-message
 ---
 
-This message is emitted regarding a pod when:
+This message occurs regarding a pod when:
 
 * Automatic sidecar injection is enabled (default enabled unless explicitly
-  disabled via the helm template variable `sidecarInjectorWebhook.enabled`)
+  disabled during installation.)
 * The pod is running in a namespace where sidecar injection is enabled (the
   namespace has the label `istio-injection=enabled`)
 * The proxy version running on the sidecar does not match the version used by
@@ -17,11 +17,11 @@ Istio (which includes the sidecar injector), all running workloads with an Istio
 sidecar must be recreated to allow the new version of the sidecar to be
 injected.
 
-The easiest way to update the sidecar version is to redeploy your application
+To resolve this problem, update the sidecar version by redeploying your application
 using your normal rollout strategy. For a Kubernetes deployment:
 
-* If you're using Kubernetes version 1.15 or above, you can run `kubectl rollout
-  restart <my-deployment>` to trigger a new rollout.
+* If you're using Kubernetes 1.15 or higher, you can run
+  `kubectl rollout restart <my-deployment>` to trigger a new rollout.
 * Alternatively, you can modify the deployment's `template` field to force a new
-  rollout. This is often done by adding a label like `force-redeploy=<current
-  timestamp>` to the pod definition in the template.
+  rollout. This is often done by adding a label like
+  `force-redeploy=<current-timestamp>` to the pod definition in the template.

content/en/docs/reference/config/analysis/ist0106/index.md

@@ -0,0 +1,47 @@
+---
+title: SchemaValidationError
+layout: analysis-message
+---
+
+This message occurs when your Istio configuration does not successfully pass
+schema validation.
+
+For example, you receive this error:
+
+{{< text plain >}}
+Error [IST0106] (VirtualService ratings-bogus-weight-default.default) Schema validation error: percentage 888 is not in range 0..100
+{{< /text >}}
+
+and your Istio configuration contains these values:
+
+{{< text yaml >}}
+apiVersion: networking.istio.io/v1alpha3
+kind: VirtualService
+metadata:
+  name: ratings-bogus-weight-default
+  namespace: default
+spec:
+  hosts:
+  - ratings
+  http:
+  - route:
+    - destination:
+        host: ratings
+        subset: v1
+      weight: 999
+    - destination:
+        host: ratings
+        subset: v2
+      weight: 888
+{{< /text >}}
+
+In this example, the error message indicates that the `weight` element has an
+invalid value when checked against the schema.
+
+To resolve this problem, refer to the
+[message details](/docs/reference/config/analysis/message-format/) field to determine
+which element or value does not adhere to the schema, correct the error and try
+again.
+
+For details about the expected schema for Istio resources, see the
+[configuration reference](/docs/reference/config/).

content/en/docs/reference/config/analysis/ist0107/index.md

@@ -0,0 +1,14 @@
+---
+title: MisplacedAnnotation
+layout: analysis-message
+---
+
+This message occurs when an Istio {{< gloss >}}annotation{{< /gloss >}} is attached to an invalid resource,
+or to a resource in the wrong location.
+
+For example, this could occur if you create a deployment and attach the
+annotation to the deployment instead of attaching the annotation to the pods it
+creates.
+
+To resolve this problem, verify that your annotations are correctly placed and
+try again.

content/en/docs/reference/config/analysis/ist0108/index.md

@@ -0,0 +1,10 @@
+---
+title: UnknownAnnotation
+layout: analysis-message
+---
+
+This message occurs when you attach an unrecognized annotation in the format `*.istio.io` to a namespace.
+
+Istio only recognizes certain [annotation names](/docs/reference/config/annotations/).
+
+To resolve this problem, check the name of your annotation and try again.

content/en/docs/reference/config/analysis/ist0109/index.md

@@ -0,0 +1,12 @@
+---
+title: ConflictingMeshGatewayVirtualServiceHosts
+layout: analysis-message
+---
+
+This message occurs when Istio detects an overlap between virtual service
+resources. For example, you have multiple virtual services defined to use the
+same hostname and gateway, where the gateway is set to `mesh` or no gateway
+specified.
+
+To resolve this problem, check your Istio configuration, remove the conflicting
+values and try again.

content/en/docs/reference/config/analysis/message-format/index.md

@@ -0,0 +1,23 @@
+---
+title: Analyzer Message Format
+---
+
+The `istioctl analyze` command provides messages in the format:
+
+{{< text plain >}}
+<level> [<code>] (<affected-resource>) <message-details>
+{{< /text >}}
+
+The `<affected-resource>` field expands to:
+
+{{< text plain >}}
+<resource-kind> <resource-name>.<resource-namespace>
+{{< /text >}}
+
+For example:
+
+{{< text plain >}}
+Error [IST0101] (VirtualService httpbin.default) Referenced gateway not found: "httpbin-gateway-bogus"
+{{< /text >}}
+
+The `<message-details>` field contains a detailed description that may contain further information to help resolve the problem. The namespace suffix is omitted for cluster-scoped resources, for example `namespace`.

content/en/docs/reference/glossary/annotation.md

@@ -0,0 +1,8 @@
+---
+title: Annotation
+---
+
+Annotation refers to a
+[Kubernetes annotation](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/)
+attached to a resource, for example a pod. For a list of valid Istio-specific annotations, see
+[Resource Annotations](/docs/reference/config/annotations/).