Add support for config analysis messages. (#5096)

- This provides the place where we can pour config analysis message
descriptions.

content/en/docs/reference/config/analysis/_index.md

@@ -0,0 +1,10 @@
+---
+title: Configuration Analysis Messages
+description: Documents the individual error and warning messages produced during configurarion analysis.
+weight: 40
+layout: analysis-landing
+---
+
+[`istioctl`](/docs/reference/commands/istioctl/#istioctl-experimental-analyze) provides rich analysis of Istio configuration state in
+order to identity invalid or suboptimal configurations. Here's is a list of the distinct possible
+error or warning messages produced by this analysis.

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

@@ -0,0 +1,6 @@
+---
+title: InternalError
+layout: analysis-message
+---
+
+We've done something bad. Why did we do something bad? We should stop doing something bad!

data/analysis.yaml

@@ -0,0 +1,82 @@
+# Please keep entries ordered by code.
+# NOTE: The range 0000-0100 is reserved for internal and/or future use.
+messages:
+  - name: "InternalError"
+    code: IST0001
+    level: Error
+    description: "There was an internal error in the toolchain. This is almost always a bug in the implementation."
+    template: "Internal error: %v"
+    args:
+      - name: detail
+        type: string
+
+  - name: "NotYetImplemented"
+    code: IST0002
+    level: Error
+    description: "A feature that the configuration is depending on is not implemented yet."
+    template: "Not yet implemented: %s"
+    args:
+      - name: detail
+        type: string
+
+  - name: "ParseError"
+    code: IST0003
+    level: Warning
+    description: "There was a parse error during the parsing of the configuration text"
+    template: "Parse error: %s"
+    args:
+      - name: detail
+        type: string
+
+  - name: "Deprecated"
+    code: IST0004
+    level: Warning
+    description: "A feature that the configuration is depending on is now deprecated."
+    template: "Deprecated: %s"
+    args:
+      - name: detail
+        type: string
+
+  - name: "ReferencedResourceNotFound"
+    code: IST0101
+    level: Error
+    description: "A resource being referenced does not exist."
+    template: "Referenced %s not found: %q"
+    args:
+      - name: reftype
+        type: string
+      - name: refval
+        type: string
+
+  - name: "NamespaceNotInjected"
+    code: IST0102
+    level: Warning
+    description: "A namespace is not enabled for Istio injection."
+    template: "The namespace is not enabled for Istio injection. Run 'kubectl label namespace %s istio-injection=enabled' to enable it, or 'kubectl label namespace %s istio-injection=disabled' to explicitly mark it as not needing injection"
+    args:
+      - name: namespace
+        type: string
+      - name: namespace2
+        type: string
+
+  - name: "PodMissingProxy"
+    code: IST0103
+    level: Warning
+    description: "A pod is missing the Istio proxy."
+    template: "The pod is missing its Istio proxy. Run 'kubectl delete pod %s -n %s' to restart it"
+    args:
+      - name: pod
+        type: string
+      - name: namespace
+        type: string
+
+  - name: "GatewayPortNotOnWorkload"
+    code: IST0104
+    level: Warning
+    description: "Unhandled gateway port"
+    template: "The gateway refers to a port that is not exposed on the workload (pod selector %s; port %d)"
+    args:
+      - name: selector
+        type: string
+      - name: port
+        type: int

i18n/en.toml

@@ -193,5 +193,14 @@ other = "-"
 [syntax_coloring]
 other = "Color Examples"
 
-[announcement_relnotes]
-other = "%s RELEASE NOTES"
+[analysis_name]
+other = "Message Name"
+
+[analysis_code]
+other = "Message Code"
+
+[analysis_description]
+other = "Description"
+
+[analysis_level]
+other = "Level"

layouts/_default/analysis-landing.html

@@ -0,0 +1,29 @@
+{{ define "main" }}
+
+    {{ .Scratch.Set "skipSeeAlso" true }}
+
+    {{ partial "primary_top.html" . }}
+
+    {{ .Content }}
+
+    {{ $current := . }}
+    <div class="section-index">
+
+        {{ range $msg := .Site.Data.analysis.messages }}
+            <div class="entry">
+                {{ $page_title := printf "%s/index.md" (lower $msg.code) }}
+                {{ $page := $current.GetPage $page_title }}
+
+                {{ if $page }}
+                    <h5><a href="{{ $page.Permalink }}">{{- $msg.code -}}: {{ $msg.name }}</a></h5>
+                {{ else }}
+                    <h5>{{- $msg.code -}}: {{ $msg.name }}</h5>
+                {{ end }}
+                <p>{{ $msg.description }}</p>
+            </div>
+        {{ end }}
+    </div>
+
+    {{ partial "primary_bottom.html" . }}
+
+{{ end }}

layouts/_default/analysis-message.html

@@ -0,0 +1,44 @@
+{{ define "main" }}
+    {{ partial "primary_top.html" . }}
+
+    {{ $found := false }}
+    {{ $current := .}}
+    {{ range $msg := .Site.Data.analysis.messages }}
+        {{ if eq $msg.name $current.Page.Title }}
+            {{ $found = true}}
+
+                <div class="analysis-message-metadata">
+                <table>
+                    <tbody>
+                        <tr>
+                            <td>{{ i18n "analysis_name" }}</td>
+                            <td>{{ $msg.name}}</td>
+                        </tr>
+
+                        <tr>
+                            <td>{{ i18n "analysis_code" }}</td>
+                            <td>{{ $msg.code}}</td>
+                        </tr>
+
+                        <tr>
+                            <td>{{ i18n "analysis_description" }}</td>
+                            <td>{{ $msg.description}}</td>
+                        </tr>
+
+                        <tr>
+                            <td>{{ i18n "analysis_level" }}</td>
+                            <td>{{ $msg.level}}</td>
+                        </tr>
+                    </tbody>
+                </table>
+            </div>
+        {{ end }}
+    {{ end }}
+
+    {{ if not $found }}
+        {{ errorf "Could not find analysis message for %s" .Page.Title }}
+    {{ end }}
+
+    {{ .Content }}
+    {{ partial "primary_bottom.html" . }}
+{{ end }}

scripts/grab_reference_docs.sh

@@ -49,6 +49,9 @@ COMPONENTS=(
     https://github.com/istio/operator.git@master@cmd/manager@operator
 )
 
+# The repo to fetch config analysis message data from
+CONFIG_ANALYSIS_MESSAGE_REPO="https://github.com/istio/istio.git@master@galley/pkg/config/analysis/msg/messages.yaml"
+
 SCRIPTPATH="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 ROOTDIR=$(dirname "${SCRIPTPATH}")
 
@@ -146,6 +149,21 @@ handle_components() {
     done
 }
 
+handle_config_analysis_messages() {
+    REPO_URL=$(echo "${CONFIG_ANALYSIS_MESSAGE_REPO}" | cut -d @ -f 1)
+    REPO_BRANCH=$(echo "${CONFIG_ANALYSIS_MESSAGE_REPO}" | cut -d @ -f 2)
+    REPO_NAME=$(echo "${REPO_URL}" | cut -d / -f 5 | cut -d . -f 1)
+    FILE_PATH=$(echo "${CONFIG_ANALYSIS_MESSAGE_REPO}" | cut -d @ -f 3)
+
+    git clone --depth=1 -q -b "${REPO_BRANCH}" "${REPO_URL}"
+
+    pushd "${REPO_NAME}" >/dev/null || exit
+    cp "${FILE_PATH}" "${ROOTDIR}/data/analysis.yaml"
+    popd >/dev/null || exit
+
+    rm -fr "${REPO_NAME}"
+}
+
 # delete all the existing generated files so that any stale files are removed
 find "${ROOTDIR}/content/en/docs/reference" -name '*.html' -type f -print0 | xargs -0 rm 2>/dev/null
 
@@ -153,8 +171,11 @@ find "${ROOTDIR}/content/en/docs/reference" -name '*.html' -type f -print0 | xar
 mkdir -p "${WORK_DIR}"
 pushd "${WORK_DIR}" >/dev/null || exit
 
-#echo "Handling doc scraping"
+echo "Handling doc scraping"
 handle_doc_scraping
 
 echo "Handling component docs"
 handle_components
+
+echo "Fetching config analysis data"
+handle_config_analysis_messages

src/sass/_all.scss

@@ -9,6 +9,7 @@
 @import "base/reset";
 @import "base/base";
 
+@import "misc/analysis-message";
 @import "misc/blog";
 @import "misc/breadcrumbs";
 @import "misc/button";

src/sass/misc/_analysis-message.scss

@@ -0,0 +1,34 @@
+.analysis-message-metadata {
+    display: block;
+    margin: 1em 0 1em 2em;
+
+    @media (min-width: $bp-md) {
+        margin: 1em 3em;
+    }
+
+    padding-left: 1em;
+    padding-right: 1em;
+    border-radius: $border-radius;
+
+    table td:first-of-type {
+        color: $textBrandColor;
+        background-color: $mainBrandColor;
+        font-weight: $tableHeaderWeight;
+    }
+
+    table td:last-of-type {
+        background-color: $backgroundColor;
+    }
+
+    table tr:last-of-type td {
+        border-bottom-color: $boxBorderColor;
+    }
+
+    table.with-logo td:first-of-type {
+        opacity: .9;
+    }
+
+    table.with-logo td:last-of-type {
+        opacity: .9;
+    }
+}

src/sass/misc/_partner-component.scss

@@ -8,7 +8,6 @@
 
     padding-left: 1em;
     padding-right: 1em;
-    background-color: $quoteCalloutBackgroundColor;
     border-radius: $border-radius;
 
     table td:first-of-type {