Update reference docs.

- Update to latest version of protoc-gen-docs - Add sorting of debug scopes in pkg/log so that generated docs are consistent. - Update pkg/collateral to generate description: front-matter instead of overview: as per the latest changes in istio.github.io - Update protos to use $description instead of $overview: - Move template examples from appearing on the template message to appearing on the package. This ends up giving a better flow in the generated docs. - Move the location of adapter & template docs into a subdirectory on istio.io for better organization. - Document which template each adapter supports.
istio · May 16, 2018 · bf56229 · bf56229
1 parent c646a10
commit bf56229
Show file tree

Hide file tree

Showing 125 changed files with 1,155 additions and 705 deletions.
diff --git a/Gopkg.lock b/Gopkg.lock
diff --git a/mixer/adapter/circonus/config/adapter.circonus.config.pb.html b/mixer/adapter/circonus/config/adapter.circonus.config.pb.html
@@ -1,13 +1,16 @@
 ---
 title: Circonus
-overview: Adapter for circonus.com's monitoring solution.
-location: https://istio.io/docs/reference/config/adapters/circonus.html
+description: Adapter for circonus.com's monitoring solution.
+location: https://istio.io/docs/reference/config/policy-and-telemetry/adapters/circonus.html
 layout: protoc-gen-docs
+redirect_from: /docs/reference/config/adapters/circonus.html
 number_of_entries: 3
 ---
 <p>The <code>circonus</code> adapter enables Istio to deliver metric data to the
 <a href="https://www.circonus.com">Circonus</a> monitoring backend.</p>
 
+<p>This adapter supports the <a href="https://istio.io/docs/reference/config/policy-and-telemetry/templates/metric.html">metric template</a>.</p>
+
 <h2 id="Params">Params</h2>
 <section>
 <p>Configuration format for the Circonus adapter.</p>

diff --git a/mixer/adapter/circonus/config/config.pb.go b/mixer/adapter/circonus/config/config.pb.go
diff --git a/mixer/adapter/circonus/config/config.proto b/mixer/adapter/circonus/config/config.proto
@@ -15,11 +15,14 @@
 syntax = "proto3";
 
 // $title: Circonus
-// $overview: Adapter for circonus.com's monitoring solution.
-// $location: https://istio.io/docs/reference/config/adapters/circonus.html
+// $description: Adapter for circonus.com's monitoring solution.
+// $location: https://istio.io/docs/reference/config/policy-and-telemetry/adapters/circonus.html
+// $front_matter: redirect_from: /docs/reference/config/adapters/circonus.html
 
 // The `circonus` adapter enables Istio to deliver metric data to the
 // [Circonus](https://www.circonus.com) monitoring backend.
+//
+// This adapter supports the [metric template](https://istio.io/docs/reference/config/policy-and-telemetry/templates/metric.html).
 package adapter.circonus.config;
 
 import "gogoproto/gogo.proto";

diff --git a/mixer/adapter/cloudwatch/config/adapter.cloudwatch.config.pb.html b/mixer/adapter/cloudwatch/config/adapter.cloudwatch.config.pb.html
@@ -1,8 +1,9 @@
 ---
 title: CloudWatch
-overview: Adapter for cloudwatch metrics.
-location: https://istio.io/docs/reference/config/adapters/cloudwatch.html
+description: Adapter for cloudwatch metrics.
+location: https://istio.io/docs/reference/config/policy-and-telemetry/adapters/cloudwatch.html
 layout: protoc-gen-docs
+redirect_from: /docs/reference/config/adapters/cloudwatch.html
 number_of_entries: 3
 ---
 <p>The CloudWatch adapter enables Istio to deliver metrics to
@@ -17,6 +18,8 @@
 <p>The handler configuration must contain the same metrics as the instance configuration.
 The metrics specified in both instance and handler configurations will be sent to CloudWatch.</p>
 
+<p>This adapter supports the <a href="https://istio.io/docs/reference/config/policy-and-telemetry/templates/metric.html">metric template</a>.</p>
+
 <h2 id="Params">Params</h2>
 <section>
 <p>Configuration for the <code>cloudwatch</code> adapter.</p>

diff --git a/mixer/adapter/cloudwatch/config/config.pb.go b/mixer/adapter/cloudwatch/config/config.pb.go
diff --git a/mixer/adapter/cloudwatch/config/config.proto b/mixer/adapter/cloudwatch/config/config.proto
@@ -15,8 +15,9 @@
 syntax = "proto3";
 
 // $title: CloudWatch
-// $overview: Adapter for cloudwatch metrics.
-// $location: https://istio.io/docs/reference/config/adapters/cloudwatch.html
+// $description: Adapter for cloudwatch metrics.
+// $location: https://istio.io/docs/reference/config/policy-and-telemetry/adapters/cloudwatch.html
+// $front_matter: redirect_from: /docs/reference/config/adapters/cloudwatch.html
 
 // The CloudWatch adapter enables Istio to deliver metrics to
 // [Amazon CloudWatch](https://aws.amazon.com/cloudwatch/).
@@ -29,6 +30,8 @@ syntax = "proto3";
 //
 // The handler configuration must contain the same metrics as the instance configuration.
 // The metrics specified in both instance and handler configurations will be sent to CloudWatch.
+//
+// This adapter supports the [metric template](https://istio.io/docs/reference/config/policy-and-telemetry/templates/metric.html).
 package adapter.cloudwatch.config;
 
 option go_package="config";

diff --git a/mixer/adapter/denier/config/adapter.denier.config.pb.html b/mixer/adapter/denier/config/adapter.denier.config.pb.html
@@ -1,13 +1,18 @@
 ---
 title: Denier
-overview: Adapter that always returns a precondition denial.
-location: https://istio.io/docs/reference/config/adapters/denier.html
+description: Adapter that always returns a precondition denial.
+location: https://istio.io/docs/reference/config/policy-and-telemetry/adapters/denier.html
 layout: protoc-gen-docs
+redirect_from: /docs/reference/config/adapters/denier.html
 number_of_entries: 2
 ---
 <p>The <code>denier</code> adapter is designed to always return a denial to precondition
 checks. You can specify the exact error to return for these denials.</p>
 
+<p>This adapter supports the <a href="https://istio.io/docs/reference/config/policy-and-telemetry/templates/checknothing.html">checknothing template</a>,
+the <a href="https://istio.io/docs/reference/config/policy-and-telemetry/templates/listentry.html">listentry template</a>,
+and the <a href="https://istio.io/docs/reference/config/policy-and-telemetry/templates/quota.html">quota template</a>.</p>
+
 <h2 id="Params">Params</h2>
 <section>
 <p>Configuration format for the Denier adapter.</p>

diff --git a/mixer/adapter/denier/config/config.pb.go b/mixer/adapter/denier/config/config.pb.go
diff --git a/mixer/adapter/denier/config/config.proto b/mixer/adapter/denier/config/config.proto
@@ -15,11 +15,16 @@
 syntax = "proto3";
 
 // $title: Denier
-// $overview: Adapter that always returns a precondition denial.
-// $location: https://istio.io/docs/reference/config/adapters/denier.html
+// $description: Adapter that always returns a precondition denial.
+// $location: https://istio.io/docs/reference/config/policy-and-telemetry/adapters/denier.html
+// $front_matter: redirect_from: /docs/reference/config/adapters/denier.html
 
 // The `denier` adapter is designed to always return a denial to precondition
 // checks. You can specify the exact error to return for these denials.
+//
+// This adapter supports the [checknothing template](https://istio.io/docs/reference/config/policy-and-telemetry/templates/checknothing.html),
+// the [listentry template](https://istio.io/docs/reference/config/policy-and-telemetry/templates/listentry.html),
+// and the [quota template](https://istio.io/docs/reference/config/policy-and-telemetry/templates/quota.html).
 package adapter.denier.config;
 
 import "gogoproto/gogo.proto";

diff --git a/mixer/adapter/dogstatsd/config/adapter.dogstatsd.config.pb.html b/mixer/adapter/dogstatsd/config/adapter.dogstatsd.config.pb.html
@@ -1,13 +1,16 @@
 ---
 title: Datadog
-overview: Adapter to deliver metrics to a dogstatsd agent for delivery to DataDog
-location: https://istio.io/docs/reference/config/adapters/datadog.html
+description: Adapter to deliver metrics to a dogstatsd agent for delivery to DataDog
+location: https://istio.io/docs/reference/config/policy-and-telemetry/adapters/datadog.html
 layout: protoc-gen-docs
+redirect_from: /docs/reference/config/adapters/datadog.html
 number_of_entries: 3
 ---
 <p>The <code>dogstatsd</code> adapter is designed to deliver Istio metric instances to a
 listening <a href="https://www.datadoghq.com/">DataDog</a> agent.</p>
 
+<p>This adapter supports the <a href="https://istio.io/docs/reference/config/policy-and-telemetry/templates/metric.html">metric template</a>.</p>
+
 <h2 id="Params">Params</h2>
 <section>
 <p>Configuration parameter for the DataDog adapter. These params control how Mixer telemetry is transformed and sent to a dogstatsd agent.</p>

diff --git a/mixer/adapter/dogstatsd/config/config.pb.go b/mixer/adapter/dogstatsd/config/config.pb.go
diff --git a/mixer/adapter/dogstatsd/config/config.proto b/mixer/adapter/dogstatsd/config/config.proto
@@ -15,11 +15,14 @@
 syntax = "proto3";
 
 // $title: Datadog
-// $overview: Adapter to deliver metrics to a dogstatsd agent for delivery to DataDog
-// $location: https://istio.io/docs/reference/config/adapters/datadog.html
+// $description: Adapter to deliver metrics to a dogstatsd agent for delivery to DataDog
+// $location: https://istio.io/docs/reference/config/policy-and-telemetry/adapters/datadog.html
+// $front_matter: redirect_from: /docs/reference/config/adapters/datadog.html
 
 // The `dogstatsd` adapter is designed to deliver Istio metric instances to a
 // listening [DataDog](https://www.datadoghq.com/) agent.
+//
+// This adapter supports the [metric template](https://istio.io/docs/reference/config/policy-and-telemetry/templates/metric.html).
 package adapter.dogstatsd.config;
 
 import "gogoproto/gogo.proto";

diff --git a/mixer/adapter/fluentd/config/adapter.fluentd.config.pb.html b/mixer/adapter/fluentd/config/adapter.fluentd.config.pb.html
@@ -1,13 +1,16 @@
 ---
 title: Fluentd
-overview: Adapter that delivers logs to a fluentd daemon.
-location: https://istio.io/docs/reference/config/adapters/fluentd.html
+description: Adapter that delivers logs to a fluentd daemon.
+location: https://istio.io/docs/reference/config/policy-and-telemetry/adapters/fluentd.html
 layout: protoc-gen-docs
+redirect_from: /docs/reference/config/adapters/fluentd.html
 number_of_entries: 1
 ---
 <p>The <code>fluentd</code> adapter is designed to deliver Istio log entries to a
 listening <a href="https://www.fluentd.org">fluentd</a> daemon.</p>
 
+<p>This adapter supports the <a href="https://istio.io/docs/reference/config/policy-and-telemetry/templates/logentry.html">logentry template</a>.</p>
+
 <h2 id="Params">Params</h2>
 <section>
 <p>Configuration parameters for the fluentd adapter.</p>

diff --git a/mixer/adapter/fluentd/config/config.pb.go b/mixer/adapter/fluentd/config/config.pb.go
diff --git a/mixer/adapter/fluentd/config/config.proto b/mixer/adapter/fluentd/config/config.proto
@@ -15,11 +15,14 @@
 syntax = "proto3";
 
 // $title: Fluentd
-// $overview: Adapter that delivers logs to a fluentd daemon.
-// $location: https://istio.io/docs/reference/config/adapters/fluentd.html
+// $description: Adapter that delivers logs to a fluentd daemon.
+// $location: https://istio.io/docs/reference/config/policy-and-telemetry/adapters/fluentd.html
+// $front_matter: redirect_from: /docs/reference/config/adapters/fluentd.html
 
 // The `fluentd` adapter is designed to deliver Istio log entries to a
 // listening [fluentd](https://www.fluentd.org) daemon.
+//
+// This adapter supports the [logentry template](https://istio.io/docs/reference/config/policy-and-telemetry/templates/logentry.html).
 package adapter.fluentd.config;
 
 import "gogoproto/gogo.proto";

diff --git a/mixer/adapter/kubernetesenv/config/adapter.kubernetesenv.config.pb.html b/mixer/adapter/kubernetesenv/config/adapter.kubernetesenv.config.pb.html
@@ -1,13 +1,16 @@
 ---
 title: Kubernetes Env
-overview: Adapter that extracts information from a Kubernetes environment.
-location: https://istio.io/docs/reference/config/adapters/kubernetesenv.html
+description: Adapter that extracts information from a Kubernetes environment.
+location: https://istio.io/docs/reference/config/policy-and-telemetry/adapters/kubernetesenv.html
 layout: protoc-gen-docs
+redirect_from: /docs/reference/config/adapters/kubernetesenv.html
 number_of_entries: 1
 ---
 <p>The <code>kubernetesenv</code> adapter extracts information from a Kubernetes environment
 and produces attribtes that can be used in downstream adapters.</p>
 
+<p>This adapter supports the <a href="https://istio.io/docs/reference/config/policy-and-telemetry/templates/kubernetes.html">kubernetesenv template</a>.</p>
+
 <h2 id="Params">Params</h2>
 <section>
 <p>Configuration parameters for the kubernetes adapter. These params

diff --git a/mixer/adapter/kubernetesenv/config/config.pb.go b/mixer/adapter/kubernetesenv/config/config.pb.go
diff --git a/mixer/adapter/kubernetesenv/config/config.proto b/mixer/adapter/kubernetesenv/config/config.proto
@@ -15,11 +15,14 @@
 syntax = "proto3";
 
 // $title: Kubernetes Env
-// $overview: Adapter that extracts information from a Kubernetes environment.
-// $location: https://istio.io/docs/reference/config/adapters/kubernetesenv.html
+// $description: Adapter that extracts information from a Kubernetes environment.
+// $location: https://istio.io/docs/reference/config/policy-and-telemetry/adapters/kubernetesenv.html
+// $front_matter: redirect_from: /docs/reference/config/adapters/kubernetesenv.html
 
 // The `kubernetesenv` adapter extracts information from a Kubernetes environment
 // and produces attribtes that can be used in downstream adapters.
+//
+// This adapter supports the [kubernetesenv template](https://istio.io/docs/reference/config/policy-and-telemetry/templates/kubernetes.html).
 package adapter.kubernetesenv.config;
 
 import "gogoproto/gogo.proto";

diff --git a/mixer/adapter/kubernetesenv/template/adapter.template.kubernetes.pb.html b/mixer/adapter/kubernetesenv/template/adapter.template.kubernetes.pb.html
@@ -1,13 +1,41 @@
 ---
 title: Kubernetes
-overview: A template that is used to control the production of Kubernetes-specific attributes.
-location: https://istio.io/docs/reference/config/template/kubernetes.html
+description: A template that is used to control the production of Kubernetes-specific attributes.
+location: https://istio.io/docs/reference/config/policy-and-telemetry/templates/kubernetes.html
 layout: protoc-gen-docs
 number_of_entries: 3
 ---
 <p>The <code>kubernetes</code> template holds data that controls the production of Kubernetes-specific
 attributes.</p>
 
+<p>Example config:</p>
+
+<pre><code class="language-yaml">apiVersion: &quot;config.istio.io/v1alpha2&quot;
+kind: kubernetes
+metadata:
+  name: attributes
+  namespace: istio-system
+spec:
+  # Pass the required attribute data to the adapter
+  source_uid: source.uid | &quot;&quot;
+  source_ip: source.ip | ip(&quot;0.0.0.0&quot;) # default to unspecified ip addr
+  destination_uid: destination.uid | &quot;&quot;
+  destination_ip: destination.ip | ip(&quot;0.0.0.0&quot;) # default to unspecified ip addr
+  attribute_bindings:
+    # Fill the new attributes from the adapter produced output.
+    # $out refers to an instance of OutputTemplate message
+    source.ip: $out.source_pod_ip
+    source.labels: $out.source_labels
+    source.namespace: $out.source_namespace
+    source.service: $out.source_service
+    source.serviceAccount: $out.source_service_account_name
+    destination.ip: $out.destination_pod_ip
+    destination.labels: $out.destination_labels
+    destination.namespace: $out.destination_mamespace
+    destination.service: $out.destination_service
+    destination.serviceAccount: $out.destination_service_account_name
+</code></pre>
+
 <h2 id="OutputTemplate">OutputTemplate</h2>
 <section>
 <p>OutputTemplate refers to the output from the adapter. It is used inside the attribute_binding section of the config
@@ -200,34 +228,6 @@ <h2 id="Template">Template</h2>
 <p>The values provided controls the manner in which the kubernetesenv adapter discovers and
 generates values related to pod information.</p>
 
-<p>Example config:</p>
-
-<pre><code class="language-yaml">apiVersion: &quot;config.istio.io/v1alpha2&quot;
-kind: kubernetes
-metadata:
-  name: attributes
-  namespace: istio-system
-spec:
-  # Pass the required attribute data to the adapter
-  source_uid: source.uid | &quot;&quot;
-  source_ip: source.ip | ip(&quot;0.0.0.0&quot;) # default to unspecified ip addr
-  destination_uid: destination.uid | &quot;&quot;
-  destination_ip: destination.ip | ip(&quot;0.0.0.0&quot;) # default to unspecified ip addr
-  attribute_bindings:
-    # Fill the new attributes from the adapter produced output.
-    # $out refers to an instance of OutputTemplate message
-    source.ip: $out.source_pod_ip
-    source.labels: $out.source_labels
-    source.namespace: $out.source_namespace
-    source.service: $out.source_service
-    source.serviceAccount: $out.source_service_account_name
-    destination.ip: $out.destination_pod_ip
-    destination.labels: $out.destination_labels
-    destination.namespace: $out.destination_mamespace
-    destination.service: $out.destination_service
-    destination.serviceAccount: $out.destination_service_account_name
-</code></pre>
-
 <table class="message-fields">
 <thead>
 <tr>