Diagnose your Configuration with Istioctl Analyze

    You can analyze your current Kubernetes cluster by running:

    And that’s it! It’ll give you any recommendations that apply.

    For example, if you forgot to enable Istio injection (a very common issue), you would get the following warning:

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

    Analyzing live clusters, local files, or both

    The example above is doing analysis on a live cluster. But the tool also supports performing analysis of a set of local Kubernetes yaml configuration files, or on a combination of local files and a live cluster. When analyzing a set of local files, the file set is expected to be fully self-contained. Typically, this is used to analyze the entire set of configuration files that are intended to be deployed to a cluster.

    Analyze a specific set of local Kubernetes yaml files:

    1. $ istioctl analyze --use-kube=false a.yaml b.yaml

    Analyze all yaml files in the current folder:

    1. $ istioctl analyze --use-kube=false *.yaml

    Simulate applying the files in the current folder to the current cluster:

    You can run istioctl analyze --help to see the full set of options.

    We’re continuing to add more analysis capability and we’d love your help in identifying more use cases. If you’ve discovered some Istio configuration “gotcha”, some tricky situation that caused you some problems, open an issue and let us know. We might be able to automatically flag this problem so that others can discover and avoid the problem in the first place.

    To do this, describing your scenario. For example:

    • Look at all the virtual services
    • For each, look at their list of gateways
    • If some of the gateways don’t exist, produce an error

    We already have an analyzer for this specific scenario, so this is just an example to illustrate what the kind of information you should provide.

    Q&A

    • What Istio release does this tool target?

      Like other istioctl tools, we generally recommend using a downloaded version that matches the version deployed in your cluster.

      For the time being, analysis is generally backwards compatible, so that you can e.g. run the 1.4 version of istioctl analyze against a cluster running Istio 1.1 and expect to get useful feedback. Analysis rules that are not meaningful with an older Istio release will be skipped.

    • What analyzers are supported today?

      We’re still working to documenting the analyzers. In the meantime, you can see all the analyzers in the .

      You can also see what configuration analysis messages are supported to get an idea of what is currently covered.

    • Can analysis do anything harmful to my cluster?

      Analysis never changes configuration state. It is a completely read-only operation and so will never alter the state of a cluster.

    • What about analysis that goes beyond configuration?

      Today, the analysis is purely based on Kubernetes configuration, but in the future we’d like to expand beyond that. For example, we could allow analyzers to also look at logs to generate recommendations.

    The following information describes an experimental feature, which is intended for evaluation purposes only.

    Starting with Istio 1.5, Galley can be set up to perform configuration analysis alongside the configuration distribution that it is primarily responsible for, via the istiod.enableAnalysis flag. This analysis uses the same logic and error messages as when using istioctl analyze. Validation messages from the analysis are written to the status subresource of the affected Istio resource.

    For example. if you have a misconfigured gateway on your “ratings” virtual service, running kubectl get virtualservice ratings would give you something like:

    1. apiVersion: networking.istio.io/v1alpha3
    2. kind: VirtualService
    3. metadata:
    4.   annotations:
    5.     kubectl.kubernetes.io/last-applied-configuration: |
    6.       {"apiVersion":"networking.istio.io/v1alpha3","kind":"VirtualService","metadata":{"annotations":{},"name":"ratings","namespace":"default"},"spec":{"hosts":["ratings"],"http":[{"route":[{"destination":{"host":"ratings","subset":"v1"}}]}]}}
    7.   creationTimestamp: "2019-09-04T17:31:46Z"
    8.   generation: 11
    9.   name: ratings
    11.   resourceVersion: "12760039"
    12.   selfLink: /apis/networking.istio.io/v1alpha3/namespaces/default/virtualservices/ratings
    13.   uid: dec86702-cf39-11e9-b803-42010a8a014a
    14. spec:
    15.   gateways:
    16.   - bogus-gateway
    17.   hosts:
    18.   - ratings
    19.   http:
    20.     - destination:
    21.         host: ratings
    22.         subset: v1
    23. status:
    24.   validationMessages:
    25.   - code: IST0101
    26.     level: Error
    27.     message: 'Referenced gateway not found: "bogus-gateway"'

    enableAnalysis runs in the background, and will keep the status field of a resource up to date with its current validation status. Note that this isn’t a replacement for :

    • Not all resources have a custom status field (e.g. Kubernetes namespace resources), so messages attached to those resources won’t show validation messages.
    • enableAnalysis only works on Istio versions starting with 1.5, while istioctl analyze can be used with older versions.
    • While it makes it easy to see what’s wrong with a particular resource, it’s harder to get a holistic view of validation status in the mesh.

    You can enable this feature with:

    1. $ istioctl manifest apply --set values.global.istiod.enableAnalysis=true
    1. $ istioctl analyze -k --all-namespaces
    2. Warn [IST0102] (Namespace frod) The namespace is not enabled for Istio injection. Run 'kubectl label namespace frod istio-injection=enabled' to enable it, or 'kubectl label namespace frod istio-injection=disabled' to explicitly mark it as not needing injection
    3. Error: Analyzers found issues.
    4. See https://istio.io/docs/reference/config/analysis for more information about causes and resolutions.

    Because you don’t have permissions to update the namespace, you cannot resolve the message by annotating the namespace. Instead, you can direct istioctl analyze to suppress the above message on the resource:

    The syntax used for suppression is the same syntax used throughout istioctl when referring to resources: <kind> <name>.<namespace>, or just <kind> <name> for cluster-scoped resources like Namespace. If you want to suppress multiple objects, you can either repeat the --suppress argument or use wildcards:

    1. $ # Suppress code IST0102 on namespace frod and IST0107 on all pods in namespace baz
    2. $ istioctl analyze -k --all-namespaces --suppress "IST0102=Namespace frod" --suppress "IST0107=Pod *.baz"

    You can also ignore specific analyzer messages using an annotation on the resource. For example, to ignore code IST0107 (MisplacedAnnotation) on resource deployment/my-deployment:

    1. $ kubectl annotate deployment my-deployment galley.istio.io/analyze-suppress=IST0107

    To ignore multiple codes for a resource, separate each code with a comma:

      See also

      Understand your Mesh with Istioctl Describe

      Shows you how to use istioctl describe to verify the configurations of a pod in your mesh.

      Analyze your Istio configuration to detect potential issues and get general insights.

      Customizable Install with Istioctl

      Install and customize any Istio configuration profile for in-depth evaluation or production use.

      Provision and manage DNS certificates in Istio.

      Introducing the Istio Operator

      Introduction to Istio’s new operator-based installation and control plane management feature.

      A more secure way to manage Istio webhooks.