Update glossary with descriptions from Istio Vocabulary doc. #580

smawson · 2017-09-30T18:02:28Z

Also cleaned up a few other items while I was at it.

Update my branch

Also cleaned up a few other items such as the Pilot entry.

istio-testing · 2017-09-30T18:05:47Z

Jenkins job istio.github.io/presubmit passed

geeknoid · 2017-09-30T19:52:23Z

_glossary/istio-auth.md

@@ -2,5 +2,5 @@
 title: Istio-Auth
 type: markdown
 ---
-Istio-Auth provides strong service-to-service and end-user authentication using mutual TLS, with built-in identity and
-credential management. Learn more about Istio-Auth [here](../concepts/network-and-auth/auth.html).
+Provides strong service-to-service authentication using mutual TLS, with built-in identity and credential management.


Instead of "Provides", perhaps "Supports"?

Tried it and it felt wrong. I think we need to rewrite auth here and give a better description, I'll talk to Wencheng. For now will leave as-is.

geeknoid · 2017-09-30T19:56:08Z

_glossary/service-producer.md

@@ -2,4 +2,4 @@
 title: Service Producer
 type: markdown
 ---
-The agent that creates a service by writing source code.
+The agent that creates a **Service** and manages which **Service Consumers** may use it.


The operator is really the one that decides who can use the service, so I'd strike that second part of the sentence.

We're talking about different roles here, it is the same person, but in their provider role that they are deciding who can access, not as operator. Or at least that's what we usually mean by the producer/consumer/operator split. We could maybe just delete producer/consumer from the glossary since they're more about API management than service management?

Yeah, I think removing these for the time being would be good. We'll have a better grip on things for 0.3

geeknoid · 2017-09-30T19:58:31Z

_glossary/service-version.md

-service has a default version consisting of all its instances.
+Distinct variants of a **Service**, typically backed by a different version of a **Workload** binary.
+Common scenarios where multiple **Service Versions** may be used include A/B testing, canary rollouts, etc.
+Each **Service** has a default **Service Version** consisting of all its **Service Endpoints**.


I'm puzzled by what this means. I don't think we can say that a "version consists of endpoints". Maybe just drop the "consisting of all its Service Endpoints" part?

Sure, dropped.

geeknoid · 2017-09-30T19:59:49Z

_glossary/service.md

-use to refer to the functionality being called. Service instances are
-pods/VMs/containers that implement the service.
+A delineated group of related behaviors within a **Service Mesh**. Services are named using a **Service Name**,
+and Istio policies such as load balancing and routing are applied to **Service Names**.


"applied to" isn't right. "applied to services using service names". Or maybe just "applied using service names"

Sure, done.

geeknoid · 2017-09-30T20:00:33Z

_glossary/service.md

-pods/VMs/containers that implement the service.
+A delineated group of related behaviors within a **Service Mesh**. Services are named using a **Service Name**,
+and Istio policies such as load balancing and routing are applied to **Service Names**.
+A **Service** is typically materialized by one or more **Service Endpoints**.


, and may consists of multiple co-existent service versions.

geeknoid · 2017-09-30T20:02:50Z

_glossary/workload-name.md

@@ -0,0 +1,7 @@
+---
+title: Workload


Workload Name

Done, good catch.

geeknoid · 2017-09-30T20:04:13Z

_glossary/workload-principal.md

+Istio service-to-service authentication is used to produce the **Workload Principal**.
+By default **Workload Principals** are compliant with the SPIFFE ID format.
+  * Multiple **Workloads** may share the same **Workload Principal**, but each **Workload** has a single canonical **Workload Principal**.
+  * **Worklooad Principals** are accessible in Istio configuration as the `source.user` and `destination.user` attributes.


Shame we can be consistent here with "user" vs "principal".

Also typo.. Worklooad (double o)

Yeah we want to change this in an upcoming release but didn't want to do it right before 0.2.

Plan is to rename to source.principal and destination.principal, and we'll also have request.auth.principal for auth credentials.

Fixed typo.

geeknoid · 2017-09-30T20:04:40Z

_glossary/workload-name.md

+---
+A unique name for a **Workload**, identifying it within the **Service Mesh**.
+Unlike **Service Name** and **Workload Principal**, **Workload Name** is not a strongly verified property and should not be used when enforcing ACLs.
+  * **Workload Names** are accessible in Istio configuration as the `source.name` and `destination.name` attributes.


Shame this isn't source.workload.name and destination.workload.name.

If it matters, we've been using source.uid and destination.uid to denote the workload IDs.

So what's the relationship between source.name and source.uid? Should we have a glossary entry for Workload Id? Given workload id, why do we need workload name?

Added a glossary entry for Workload ID.

Both are useful, since workload name is a natural grouping of workload IDs and more useful in dashboards.

rshriram

sans typo and fixing links

Maps to source.uid and destination.uid.

istio-testing · 2017-10-02T16:50:34Z

Jenkins job istio.github.io/presubmit passed

smawson added 2 commits September 30, 2017 09:54

Merge pull request #1 from istio/master

3a41b6c

Update my branch

Update glossary with descriptions from Istio Vocabulary doc. (#3)

1d3b8d1

Also cleaned up a few other items such as the Pilot entry.

smawson added this to the Istio 0.2 milestone Sep 30, 2017

smawson self-assigned this Sep 30, 2017

smawson requested review from rshriram and geeknoid September 30, 2017 18:02

geeknoid reviewed Sep 30, 2017

View reviewed changes

rshriram approved these changes Oct 2, 2017

View reviewed changes

smawson added 8 commits October 2, 2017 09:37

Drop default service version

dbb4759

Dropped too much, add back that each service version has a default

a92ecf9

Update service.md

0a2f62f

Add note about service versions to service

a40144b

Update workload-name.md

20650e6

Add a glossary entry for Workload ID

cb36ddf

Maps to source.uid and destination.uid.

Merge branch 'master' into glossary

fb2263e

Fix typo in Workload Principal (worklooad)

a4a2d63

geeknoid approved these changes Oct 2, 2017

View reviewed changes

rshriram merged commit 43e4ba2 into istio:master Oct 2, 2017

Update glossary with descriptions from Istio Vocabulary doc. #580

Update glossary with descriptions from Istio Vocabulary doc. #580

Uh oh!

Conversation

smawson commented Sep 30, 2017

Uh oh!

istio-testing commented Sep 30, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rshriram left a comment

Choose a reason for hiding this comment

Uh oh!

istio-testing commented Oct 2, 2017

Uh oh!

Uh oh!