Minor doc fixes. (istio#1594)

Merging because this is just doc changes in markdown files.
WillardHu · Nov 8, 2017 · 692278d · 692278d
1 parent 689bc64
commit 692278d
Show file tree

Hide file tree

Showing 8 changed files with 16 additions and 50 deletions.
diff --git a/.github/issue_template.md b/.github/issue_template.md
@@ -1,6 +1,4 @@
 <!--
-Please see https://istio.io/troubleshooting/ and if you are a user of Istio, please file issues in
-https://github.com/istio/issues/issues instead of here
-
+Please see https://istio.io/troubleshooting for potential workarounds.
 Please add the correct labels and epics (and priority and milestones if you have that information)
 -->
diff --git a/DEV-GUIDE.md b/DEV-GUIDE.md
@@ -34,7 +34,6 @@ so we can improve the doc.
   - [Adding dependencies](#adding-dependencies)
   - [About testing](#about-testing)
 - [Local development scripts](#collection-of-scripts-and-notes-for-developing-for-istio)
-- [MacOS tips](#macos-tips)
 
 This document is intended to be relative to the branch in which it is found.
 It is guaranteed that requirements will change over time for the development
@@ -390,8 +389,6 @@ Assuming you did (once):
    ```bash
    mkdir github
    cd github/
-   git clone https://github.com/istio/proxy.git
-   git clone https://github.com/istio/mixer.git
    git clone https://github.com/istio/istio.git
    ```
 4. You can then use
@@ -416,14 +413,3 @@ Assuming you did (once):
    cd mixer/
    source bin/use_bazel_go.sh
    ```
-
-
-## MacOs tips
-
-Get GitHub desktop https://desktop.github.com/
-
-If you want to make changes to the [website](https://github.com/istio/istio.github.io), and want to run jekyll locally and natively, without docker):
-
-You will need a newer ruby than the default: get and install rvm https://rvm.io/
-
-Then rvm install ruby-2.1 (or later) rvm use ruby-2.1  then `gem install jekyll bundler` then `bundle install` and then finally you can run successfully `bundle exec jekyll serve` in the directory you cloned the iostio doc repo. To avoid `GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data.` errors you need to set a public repo access token at https://github.com/settings/tokens and export it in `JEKYLL_GITHUB_TOKEN` env var (in your `.bash_profile`) - then http://127.0.0.1:4000/docs/ will work and auto update when pulling.
diff --git a/DEV-PERF.md b/DEV-PERF.md
@@ -1,7 +1,7 @@
 # Creating Fast and Lean Code
 
-Mixer is a high-performance component. It's imperative to keep its
-latency and memory consumption low.
+It's imperative to keep latency and memory consumption of Istio components low.
+To that end, we present here a few general guidelines and pointers.
 
 - [Memory usage](#memory-usage)
   - [Reuse and object pools](#reuse-and-object-pools)
@@ -42,15 +42,15 @@ abound. But Go does have good value semantics, so we use them.
 
 So prefer:
 
-```
+```go
 type MyContainer struct {
   inlineStruct OtherStuff
 }
 ```
 
 When possible as opposed to:
 
-```
+```go
 type MyContainer struct {
   outoflineStruct *OtherStruct
 }

diff --git a/README.md b/README.md
@@ -19,8 +19,8 @@ In addition, here are some other docs you may wish to read:
 - [Contribution Guidelines](CONTRIBUTING.md) - explains the process for contributing to the Istio code base
 - [Reviewing and Merging Pull Requests](REVIEWING.md) - explains the process we use to review code changes
 - [Istio Developer's Guide](DEV-GUIDE.md) - explains how to setup and use an Istio development environment
-- [Project conventions](DEV-CONVENTIONS.md) - describes the conventions we use within the code base
-- [Creating fast and lean code](DEV-PERF.md) - performance-oriented advice and guidelines for the code base
+- [Project Conventions](DEV-CONVENTIONS.md) - describes the conventions we use within the code base
+- [Creating Fast and Lean Code](DEV-PERF.md) - performance-oriented advice and guidelines for the code base
 
 ## Introduction
 
@@ -56,8 +56,8 @@ Istio is composed of these components:
 
 * **Broker** - A component implementing the open service broker API for Istio-based services. (Under development)
 
-Istio currently supports Kubernetes, Consul, qne Eureka-based environments. We plan support for additional platforms such as
-Cloud Foundry, and Mesos in the  near future.
+Istio currently supports Kubernetes, Consul, and Eureka-based environments. We plan support for additional platforms such as
+Cloud Foundry, and Mesos in the near future.
 
 ## Istio authors
 
@@ -93,12 +93,12 @@ contains code for Istio's implementation of the Open Service Broker API.
 component-level APIs and common configuration formats for the Istio platform.
 
 - [istio/mixerclient](https://github.com/istio/mixerclient). Client libraries
-for the mixer API.
+for Mixer's API.
 
 - [istio/proxy](https://github.com/istio/proxy). The Istio proxy contains
 extensions to the [Envoy proxy](https://github.com/lyft/envoy) (in the form of
 Envoy filters), that allow the proxy to delegate policy enforcement
-decisions to the mixer.
+decisions to Mixer.
 
 ## Issue management
 

diff --git a/broker/README.md b/broker/README.md
@@ -1,19 +1,6 @@
 # Broker
 
-[![GoDoc](https://godoc.org/github.com/istio/broker?status.svg)](https://godoc.org/github.com/istio/broker)
-[![Build Status](https://testing.istio.io/buildStatus/icon?job=broker/postsubmit)](https://testing.istio.io/job/broker/)
-[![Go Report Card](https://goreportcard.com/badge/github.com/istio/broker)](https://goreportcard.com/report/github.com/istio/broker)
-[![codecov.io](https://codecov.io/github/istio/broker/coverage.svg?branch=master)](https://codecov.io/github/istio/broker?branch=master)
-
 The Istio Service Broker provides an implementation of the [Open Service Broker API](https://docs.cloudfoundry.org/services/api.html) for Istio.
 This API enables external service consumers to automatically provision and access Istio services. 
 
-This repository is currently under development.
-
-Please see [istio.io](https://istio.io)
-to learn about the overall Istio project and how to get in touch with us. To learn how you can
-contribute to any of the Istio components, including Broker, please
-see the Istio [contribution guidelines](https://github.com/istio/istio/blob/master/CONTRIBUTING.md).
-
-Istio's [development guide](https://github.com/istio/istio/blob/master/devel/README.md)
-presents everything you need to know to create, build, and test code for Broker.
+The broker is currently under early development.
diff --git a/pilot/doc/build.md b/pilot/doc/build.md
diff --git a/pilot/doc/design.md b/pilot/doc/design.md
@@ -19,6 +19,6 @@ Istio configuration is backed by a distributed key-value store. Istio Pilot comp
 The overview of the proxy controllers in Istio Pilot is [here](proxy-controller.md).
 Istio Pilot supervises a mesh of proxies co-located with service instances as sidecar container. A proxy agent generates fresh configuration adapted to the local proxy instances from the services and configuration models, and triggers proxy re-configuration.
 
-![architecture](https://cdn.rawgit.com/istio/pilot/master/doc/pilot.svg)
+![architecture](https://cdn.rawgit.com/istio/istio/master/pilot/doc/pilot.svg)
 
 The diagram uses _black_ arrows for the data path and _red_ arrows for the control path. Proxies capture traffic from services and route them internally and externally using control information from the discovery services and agent-generated configurations. This control information is stored in the API server in Kubernetes and is managed by the operator using `kubectl` or `istioctl`.
diff --git a/security/README.md b/security/README.md
@@ -16,7 +16,7 @@ The diagram below shows Istio Security's architecture, which includes three prim
 This diagram describes how Istio Security is used to secure the service-to-service communication between service 'frontend' running as the service account 'frontend-team' and service 'backend' running as the service account 'backend-team'.
 Istio supports services running on both Kubernetes containers and VM/bare-metal machines.
 
-![overview](https://cdn.rawgit.com/istio/auth/master/overview.svg)
+![overview](https://cdn.rawgit.com/istio/istio/master/security/overview.svg)
 
 As illustrated in the diagram, Istio Security leverages secret volume mount to deliver keys/certs from Istio CA to Kubernetes containers.
 For services running on VM/bare-metal machines, we introduce a node agent, which is a process running on each VM/bare-metal machine.
@@ -78,7 +78,7 @@ Once the key and certificate are deployed, the runtime phase is the same for the
 
 1.  When a pod is created, API Server mounts the key and certificate pair according to the service account using [Kubernetes secrets](https://kubernetes.io/docs/concepts/configuration/secret/).
 
-1.  [Pilot]({{home}}/docs/concepts/traffic-management/pilot.html) generates the config with proper key and certificate and secure naming information,
+1.  [Pilot](https://istio.io/docs/concepts/traffic-management/pilot.html) generates the config with proper key and certificate and secure naming information,
 which
  defines what service account(s) can run a certain service, and passes it to Envoy.
 
@@ -122,6 +122,6 @@ Let's consider a 3-tier application with three services: photo-frontend, photo-b
 In this scenario, a cluster admin creates 3 namespaces: istio-ca-ns, photo-ns, and datastore-ns. Admin has access to all namespaces, and each team only has
 access to its own namespace. The photo SRE team creates 2 service accounts to run photo-frontend and photo-backend respectively in namespace photo-ns. The
 datastore SRE team creates 1 service account to run the datastore service in namespace datastore-ns. Moreover, we need to enforce the service access control
-in [Istio Mixer]({{home}}/docs/concepts/policy-and-control/mixer.html) such that photo-frontend cannot access datastore.
+in [Istio Mixer](https://istio.io/docs/concepts/policy-and-control/mixer.html) such that photo-frontend cannot access datastore.
 
 In this setup, Istio CA is able to provide keys and certificates management for all namespaces, and isolate microservice deployments from each other.