Refresh the glossary and attribute vocabulary based on current reality. (#2142)

content/docs/reference/config/policy-and-telemetry/attribute-vocabulary/index.md

@@ -23,7 +23,7 @@ deployments will have agents (Envoy or Mixer adapters) that produce these attrib
 | `source.labels`             | map[string, string] | A map of key-value pairs attached to the source instance. | version => v1 |
 | `source.name`               | string | Source workload instance name. | `redis-master-2353460263-1ecey` |
 | `source.namespace`          | string | Source workload instance namespace. | `my-namespace` |
-| `source.principal`          | string | The identity of the source workload. | `service-account-foo` |
+| `source.principal`          | string | Authority under which the source workload instance is running. | `service-account-foo` |
 | `source.owner`              | string | Reference to the workload controlling the source workload instance. | `kubernetes://apis/extensions/v1beta1/namespaces/istio-system/deployments/istio-policy` |
 | `source.workload.uid`       | string | Unique identifier of the source workload. | `istio://istio-system/workloads/istio-policy` |
 | `source.workload.name`      | string | Source workload name. | `istio-policy` |
@@ -34,13 +34,13 @@ deployments will have agents (Envoy or Mixer adapters) that produce these attrib
 | `destination.labels`            | map[string, string] | A map of key-value pairs attached to the server instance. | version => v2 |
 | `destination.name`              | string | Destination workload instance name. | `istio-telemetry-2359333` |
 | `destination.namespace`         | string | Destination workload instance namespace. | `istio-system` |
-| `destination.principal`         | string | The identity of the destination workload. | `service-account` |
+| `destination.principal`         | string | Authority under which the destination workload instance is running. | `service-account` |
 | `destination.owner`             | string | Reference to the workload controlling the destination workload instance.| `kubernetes://apis/extensions/v1beta1/namespaces/istio-system/deployments/istio-telemetry` |
 | `destination.workload.uid`      | string | Unique identifier of the destination workload. | `istio://istio-system/workloads/istio-telemetry` |
 | `destination.workload.name`     | string | Destination workload name. | `istio-telemetry` |
 | `destination.workload.namespace`| string | Destination workload namespace. | `istio-system` |
-| `destination.container.name`    | string | Container name of the server workload instance. | `mixer` |
-| `destination.container.image`   | string | Image source for the destination container. | `gcr.io/istio-testing/mixer:0.8.0` |
+| `destination.container.name`    | string | Name of the destination workload instance's container. | `mixer` |
+| `destination.container.image`   | string | Image of the destination workload instance's container. | `gcr.io/istio-testing/mixer:0.8.0` |
 | `destination.service.host`      | string | Destination host address. | `istio-telemetry.istio-system.svc.cluster.local` |
 | `destination.service.uid`       | string | Unique identifier of the destination service. | `istio://istio-system/services/istio-telemetry` |
 | `destination.service.name`      | string | Destination service name. | `istio-telemetry` |

content/help/glossary/adapters.md

@@ -2,8 +2,8 @@
 title: Adapters
 ---
 
-Adapters are plug-ins to Mixer to enable Mixer to interface with an open-ended
-set of infrastructure backends that deliver core functionality, such as logging,
+Adapters are plug-ins to Mixer, Istio's [policy and telemetry](/docs/concepts/policies-and-telemetry/) component, which enable it to interface
+with an open-ended set of infrastructure backends that deliver core functionality, such as logging,
 monitoring, quotas, ACL checking, and more.
 The exact set of adapters used at runtime is determined through configuration and can easily be
 extended to target new or custom infrastructure backends.

content/help/glossary/attribute.md

@@ -13,5 +13,7 @@ request.path: xyz/abc
 request.size: 234
 request.time: 12:34:56.789 04/17/2017
 source.ip: 192.168.0.1
-destination.service: example
+destination.workload.name: example
 {{< /text >}}
+
+Attributes are used by Istio's [policy and telemetry](/docs/concepts/policies-and-telemetry/) features.

content/help/glossary/secure-naming.md

@@ -1,5 +1,5 @@
 ---
 title: Secure Naming
 ---
-Provides a mapping between a [service name](#service-name) and the [workload principals](#workload-principal) that are authorized to
-run the [workloads](#workload) implementing a [service](#service).
+Provides a mapping between a [service name](#service-name) and the [workload instance principals](#workload-instance-principal) that are authorized to
+run the [workload instances](#workload-instance) implementing a [service](#service).

content/help/glossary/service-endpoint.md

@@ -2,4 +2,5 @@
 title: Service Endpoint
 ---
 The network-reachable manifestation of a [service](#service).
-Service endpoints are exposed by [workloads](#workload). Not all services have service endpoints.
+Service endpoints are exposed by [workload instances](#workload-instance).
+Not all services have service endpoints.

content/help/glossary/service-mesh.md

@@ -2,4 +2,4 @@
 title: Service Mesh
 ---
 A shared set of names and identities that allows for common policy enforcement and telemetry collection.
-[Service names](#service-name) and [workload principals](#workload-principal) are unique within a service mesh.
+[Service names](#service-name) and [workload instance principals](#workload-instance-principal) are unique within a service mesh.

content/help/glossary/workload-id.md

@@ -1,7 +0,0 @@
----
-title: Workload ID
----
-A unique identifier for an individual instance of a [workload](#workload).
-Like [workload name](#workload-name), the workload ID is not a strongly verified property and should not be used
-when enforcing ACLs. The workload IDs are accessible in Istio configuration as the
-`source.uid` and `destination.uid` [attributes](#attribute).

content/help/glossary/workload-instance-principal.md

@@ -0,0 +1,9 @@
+---
+title: Workload Instance Principal
+---
+The verifiable authority under which a [workload instance](#workload-instance) runs.
+Istio's service-to-service authentication is used to produce the workload principal.
+By default workload principals are compliant with the SPIFFE ID format.
+
+Workload instance principals are available in policy and telemetry configuration
+using the `source.principal` and `destination.principal` [attributes](#attribute).

content/help/glossary/workload-instance.md

@@ -0,0 +1,17 @@
+---
+title: Workload Instance
+---
+A single instantiation of a workload's binary.
+A workload instance can expose zero or more [service endpoints](#service-endpoint),
+and can consume zero or more [services](#service).
+
+Workload instances have a number of properties:
+
+- Name and namespace
+- Unique ID
+- IP Address
+- Labels
+- Principal
+
+These properties are available in policy and telemetry configuration
+using the many [`source.*` and `destination.*` attributes](/docs/reference/config/policy-and-telemetry/attribute-vocabulary/).

content/help/glossary/workload-name.md

@@ -1,8 +0,0 @@
----
-title: Workload Name
----
-A unique name for a [workload](#workload), identifying it within the [service mesh](#service-mesh).
-Unlike the [service name](#service-name) and the [workload principal], the workload name is not a
-strongly verified property and should not be used when enforcing ACLs.
-The workload names is accessible in Istio configuration as the `source.name` and `destination.name`
-[attributes](#attribute).

content/help/glossary/workload-principal.md

@@ -1,11 +0,0 @@
----
-title: Workload Principal
----
-Identifies the verifiable authority under which a [workload](#workload) runs.
-Istio's service-to-service authentication is used to produce the workload principal.
-By default workload principals are compliant with the SPIFFE ID format.
-
-- Multiple [workloads](#workload) may share the same workload principal, but each workload has a single canonical workload
-  principal
-
-- Workload principals are accessible in Istio configuration as the `source.user` and `destination.user` [attributes](#attribute).

content/help/glossary/workload.md

@@ -1,9 +1,11 @@
 ---
 title: Workload
 ---
-A process/binary deployed by operators in Istio, typically represented by entities such as containers, pods, or VMs.
+A binary deployed by operators to deliver some function in Istio. Workloads have names, namespaces, and unique ids. These properties are available in policy and telemetry configuration
+using the following [attributes](#attribute):
 
-* A workload can expose zero or more [service endpoints](#service-endpoint).
-* A workload can consume zero or more [services](#service).
-* Each workload has a single canonical [service name](#service-name) associated with it, but
-may also represent additional service names.
+* `source.workload.name`, `source.workload.namespace`, `source.workload.uid`
+* `destination.workload.name`, `destination.workload.namespace`, `destination.workload.uid`
+
+In Kubernetes, a workload typically corresponds to a Kubernetes deployment, while a workload instance corresponds to an individual pod managed
+by the deployment.

src/sass/base/_common.scss

@@ -2,7 +2,7 @@
     // This is a hack such that when we link to a fragment on a page, the page
     // scrolls correctly in relation to the fixed header. Without this hack, the
     // page scrolls with the fragment at the top of the page, below the header!
-    h2[id]:before, h3[id]:before, h4[id]:before, h5[id]:before, h6[id]:before {
+    h2[id]:before, h3[id]:before, h4[id]:before, h5[id]:before, h6[id]:before, dt[id]:before {
           display: block;
           content: ' ';
           margin-top: -1.8em;
@@ -17,6 +17,11 @@
         visibility: visible;
     }
 
+    dt[id]:before {
+        margin-top: -2.8em;
+        height: 2.8em;
+    }
+
     html {
         overflow-y: scroll;
         position: relative;