From 8c078c6ec6e41857a39fbf01b0561223a2c5d16d Mon Sep 17 00:00:00 2001 From: Martin Taillefer Date: Mon, 6 Nov 2017 15:24:46 -0800 Subject: [PATCH] Consolidate and organize docs after monorepo merge. (#1558) More work remains, this is a first step. --- devel/conventions.md => DEV-CONVENTIONS.md | 5 + devel/README.md => DEV-GUIDE.md | 118 ++++------ devel/performance.md => DEV-PERF.md | 0 README.md | 27 ++- broker/CONTRIBUTING.md | 8 - broker/LICENSE | 202 ------------------ mixer/CONTRIBUTING.md | 8 - mixer/LICENSE | 202 ------------------ mixer/README.md | 21 +- .../adapter-development-walkthrough.md | 2 +- mixer/doc/{dev => }/adapters.md | 22 +- .../img/example attr to instance.svg | 0 .../img/example instance to type.svg | 0 mixer/doc/{dev => }/img/handler config.svg | 0 mixer/doc/{ => img}/logo.png | Bin .../doc/{dev => }/img/mixer adapter flow.svg | 0 .../doc/{dev => }/img/mixer architecture.svg | 0 mixer/doc/{dev => }/img/mixer start flow.svg | 0 .../{dev => }/img/operator config change.svg | 0 .../img/operator template adapter dev.svg | 0 mixer/doc/{dev => }/img/request time.svg | 0 .../img/template generated artifacts.svg | 0 ...apter and operator config relationship.svg | 0 .../development.md => running-local-mixer.md} | 10 +- mixer/doc/{dev => }/templates.md | 4 +- pilot/CONTRIBUTING.md | 5 - pilot/LICENSE | 201 ----------------- pilot/README.md | 14 +- security/CONTRIBUTING.md | 5 - security/LICENSE | 201 ----------------- security/README.md | 26 --- 31 files changed, 79 insertions(+), 1002 deletions(-) rename devel/conventions.md => DEV-CONVENTIONS.md (96%) rename devel/README.md => DEV-GUIDE.md (80%) rename devel/performance.md => DEV-PERF.md (100%) delete mode 100644 broker/CONTRIBUTING.md delete mode 100644 broker/LICENSE delete mode 100644 mixer/CONTRIBUTING.md delete mode 100644 mixer/LICENSE rename mixer/doc/{dev => }/adapter-development-walkthrough.md (99%) rename mixer/doc/{dev => }/adapters.md (96%) rename mixer/doc/{dev => }/img/example attr to instance.svg (100%) rename mixer/doc/{dev => }/img/example instance to type.svg (100%) rename mixer/doc/{dev => }/img/handler config.svg (100%) rename mixer/doc/{ => img}/logo.png (100%) rename mixer/doc/{dev => }/img/mixer adapter flow.svg (100%) rename mixer/doc/{dev => }/img/mixer architecture.svg (100%) rename mixer/doc/{dev => }/img/mixer start flow.svg (100%) rename mixer/doc/{dev => }/img/operator config change.svg (100%) rename mixer/doc/{dev => }/img/operator template adapter dev.svg (100%) rename mixer/doc/{dev => }/img/request time.svg (100%) rename mixer/doc/{dev => }/img/template generated artifacts.svg (100%) rename mixer/doc/{dev => }/img/template, adapter and operator config relationship.svg (100%) rename mixer/doc/{dev/development.md => running-local-mixer.md} (87%) rename mixer/doc/{dev => }/templates.md (97%) delete mode 100644 pilot/CONTRIBUTING.md delete mode 100644 pilot/LICENSE delete mode 100644 security/CONTRIBUTING.md delete mode 100644 security/LICENSE diff --git a/devel/conventions.md b/DEV-CONVENTIONS.md similarity index 96% rename from devel/conventions.md rename to DEV-CONVENTIONS.md index f984192573ec..60fcccca9d58 100644 --- a/devel/conventions.md +++ b/DEV-CONVENTIONS.md @@ -9,6 +9,11 @@ create, maintain, and use. - [Testing conventions](#testing-conventions) - [Directory and file conventions](#directory-and-file-conventions) +Others docs you should look at: + +- [Go landmines](https://gist.github.com/lavalamp/4bd23295a9f32706a48f) +- [Go style mistakes](https://github.com/golang/go/wiki/CodeReviewComments) + ## Coding conventions - Follow the general guidance from [Effective Go](https://golang.org/doc/effective_go.html) diff --git a/devel/README.md b/DEV-GUIDE.md similarity index 80% rename from devel/README.md rename to DEV-GUIDE.md index a01627270707..c98e65d221f1 100644 --- a/devel/README.md +++ b/DEV-GUIDE.md @@ -1,16 +1,8 @@ # Developing for Istio -This document is intended to be the canonical source of truth for things like -supported toolchain versions for building Istio components like Mixer -(which is used throughout this document as an example when referring to a specific -component repo or directory). -If you find a requirement that this doc does not capture, or if you find other -docs with references to requirements that are not simply links to this doc, -please [submit an issue](https://github.com/istio/istio/issues/new). - -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 -branch, but release branches should not change. +This document helps you get started to develop code for Istio. +If you're following this guide and find some problem, please [submit an issue](https://github.com/istio/istio/issues/new). +so we can improve the doc. - [Prerequisites](#prerequisites) - [Setting up Go](#setting-up-go) @@ -23,7 +15,6 @@ branch, but release branches should not change. - [Fork the main repository](#fork-the-main-repository) - [Clone your fork](#clone-your-fork) - [Enable pre commit hook](#enable-pre-commit-hook) - - [Enable pre push hook](#enable-pre-push-hook) - [Create a branch and make changes](#create-a-branch-and-make-changes) - [Keeping your fork in sync](#keeping-your-fork-in-sync) - [Committing changes to your fork](#committing-changes-to-your-fork) @@ -45,13 +36,9 @@ branch, but release branches should not change. - [Local development scripts](#collection-of-scripts-and-notes-for-developing-for-istio) - [MacOS tips](#macos-tips) -Other docs you should look at: - -- [Project conventions](./conventions.md) -- [Creating fast and lean code](./performance.md) -- Each components additional development docs like [Mixer](https://github.com/istio/mixer/tree/master/doc/dev/development.md)'s -- [Go landmines](https://gist.github.com/lavalamp/4bd23295a9f32706a48f) -- [Go style mistakes](https://github.com/golang/go/wiki/CodeReviewComments) +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 +branch, but release branches should not change. ## Prerequisites @@ -61,11 +48,12 @@ need to setup before being able to build and run the code. ### Setting up Go Many Istio components are written in the [Go](http://golang.org) programming language. -To build, you'll need a Go development environment. Builds for -Mixer require Go version 1.8. If you haven't set up a Go development +To build, you'll need a Go development environment. If you haven't set up a Go development environment, please follow [these instructions](https://golang.org/doc/install) to install the Go tools. +Istio currently builds with Go 1.9 + ### Setting up Bazel Istio components are built using the Bazel build system. See @@ -74,6 +62,8 @@ installation procedures. In addition to Bazel itself, you should install the Bazel buildifier tool from [here](https://github.com/bazelbuild/buildtools). +Istio currently builds with Bazel 0.7.0 + ### Setting up Docker To run some of Istio's examples and tests, you need to set up Docker server. @@ -104,13 +94,13 @@ mkdir -p $ISTIO ### Setting up a personal access token -This is only necessary for core contributors / to push changes to the main repos. +This is only necessary for core contributors in order to push changes to the main repos. You can make pull requests without two-factor authentication but the additional security is recommended for everyone. To be part of the Istio organization, we require two-factor authentication, and -you must setup a personal access token to enable push via HTTPS. Please follow [these -instructions](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) +you must setup a personal access token to enable push via HTTPS. Please follow +[these instructions](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) for how to create a token. Alternatively you can [add your SSH keys](https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/). @@ -121,56 +111,45 @@ Follow the ## Git workflow -Below, we outline one of the more common git workflows that core developers use. -Other git workflows are also valid. +Below, we outline one of the more common Git workflows that core developers use. +Other Git workflows are also valid. ### Fork the main repository -Depending on the component, taking mixer as an example: - -1. Go to https://github.com/istio/mixer +1. Go to https://github.com/istio/istio 2. Click the "Fork" button (at the top right) ### Clone your fork The commands below require that you have $GOPATH set ([$GOPATH docs](https://golang.org/doc/code.html#GOPATH)). We highly recommend you put -Mixer's code into your GOPATH. Note: the commands below will not work if +Istio's code into your GOPATH. Note: the commands below will not work if there is more than one directory in your `$GOPATH`. ```shell cd $ISTIO -git clone https://github.com/$GITHUB_USER/mixer.git -cd mixer -git remote add upstream 'https://github.com/istio/mixer.git' +git clone https://github.com/$GITHUB_USER/istio.git +cd istio +git remote add upstream 'https://github.com/istio/istio.git' git config --global --add http.followRedirects 1 ``` + ### Enable pre-commit hook -Mixer for instance uses a local pre-commit hook to ensure that the code -passes local test. +NOTE: The precommit hook is not functional as of 11/08/2017 following the repo +reorganization. It should come back alive shortly. + +Istio uses a local pre-commit hook to ensure that the code +passes local tests before being committed. Run ```shell -user@host:~/GOHOME/src/istio.io/mixer$ ./bin/pre-commit +user@host:~/GOHOME/src/istio.io/istio$ ./bin/pre-commit Installing pre-commit hook ``` This hook is invoked every time you commit changes locally. The commit is allowed to proceed only if the hook succeeds. -### Enable pre-push hook - -Broker uses a local pre-push hook to ensure that the code -passes local test. - -Run -```shell -user@host:~/GOHOME/src/istio.io/broker$ ./bin/pre-push -Installing pre-push hook -``` -This hook is invoked every time you push changes locally. -The push is allowed to proceed only if the hook succeeds. - ### Create a branch and make changes ```shell @@ -186,7 +165,7 @@ git rebase upstream/master ``` Note: If you have write access to the main repositories -(eg github.com/istio/mixer), you should modify your git configuration so +(e.g. github.com/istio/istio), you should modify your Git configuration so that you can't accidentally push to upstream: ```shell @@ -201,11 +180,10 @@ When you're happy with some changes, you can commit them to your repo: git add . git commit ``` -Then push the change to the fork. When prompted for authentication, using your -github username as usual but the personal access token as your password if you +Then push the change to the fork. When prompted for authentication, use your +GitHub username as usual but the personal access token as your password if you have not setup ssh keys. Please -follow [these -instructions](https://help.github.com/articles/caching-your-github-password-in-git/#platform-linux) +follow [these instructions](https://help.github.com/articles/caching-your-github-password-in-git/#platform-linux) if you want to cache the token. ```shell @@ -214,7 +192,7 @@ git push -f origin my-feature ### Creating a pull request -1. Visit https://github.com/$GITHUB_USER/$COMPONENT +1. Visit https://github.com/$GITHUB_USER/istio 2. Click the "Compare & pull request" button next to your "my-feature" branch. ### Getting a code review @@ -224,12 +202,12 @@ reviewers. Those reviewers will do a thorough code review, looking for correctness, bugs, opportunities for improvement, documentation and comments, and style. -Very small PRs are easy to review. Very large PRs are very difficult to +Very small PRs are easy to review. Very large PRs are very difficult to review. GitHub has a built-in code review tool, which is what most people use. ### When to retain commits and when to squash -Upon merge, all git commits should represent meaningful milestones or units of +Upon merge, all Git commits should represent meaningful milestones or units of work. Use commits to add clarity to the development and review process. Before merging a PR, squash any "fix review feedback", "typo", and "rebased" @@ -243,31 +221,15 @@ reviews much easier. ### Building the code -Using Mixer as an example: +To build the core repo: ```shell -cd $ISTIO/mixer +cd $ISTIO make build ``` This build command figures out what it needs to do and does not need any input from you. -For Pilot, use the command below to set up the initial build: - -```shell -cd $ISTIO/pilot -make setup -``` - -After the initial build, you can simply use the command below to build: - -```shell -cd $ISTIO/pilot -make -``` - -This build command figures out what it needs to do and does not need any input from you. - ### Setup bazel and go links Symlinks bazel artifacts into the standard go structure so standard go @@ -371,10 +333,8 @@ make racetest ### Adding dependencies -It will occasionally be necessary to add a new dependency to Mixer, either in support of a new adapter or to provide -additional core functionality. - -Mixer dependencies are maintained in the [WORKSPACE](https://github.com/istio/mixer/blob/master/WORKSPACE) +It will occasionally be necessary to add a new external dependency to the system +Dependencies are maintained in the [WORKSPACE](https://github.com/istio/istio/blob/master/WORKSPACE) file. To add a new dependency, please append to the bottom on the file. A dependency can be added manually, or via [wtool](https://github.com/bazelbuild/rules_go/blob/master/go/tools/wtool/main.go). diff --git a/devel/performance.md b/DEV-PERF.md similarity index 100% rename from devel/performance.md rename to DEV-PERF.md diff --git a/README.md b/README.md index bb1a060844bf..c8e2b24352ba 100644 --- a/README.md +++ b/README.md @@ -11,9 +11,17 @@ An open platform to connect, manage, and secure microservices. - [Istio authors](#istio-authors) - [Repositories](#repositories) - [Issue management](#issue-management) -- [Contributing to the project](#contributing-to-the-project) - [Community and support](#community-and-support) +In addition, here are some other docs you may wish to read: + +- [Istio Working Groups](GROUPS.md) - how we partition work in the project +- [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 + ## Introduction Istio is an open platform for providing a uniform way to integrate @@ -48,7 +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, Eureka-based environments. We plan support for additional platforms such as Cloud Foundry, and Mesos in the near future. +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 authors @@ -60,7 +69,7 @@ by teams from Google and IBM, in partnership with the Envoy team at Lyft. The Istio project is divided across a few GitHub repositories. - [istio/istio](README.md). This is the main repo that you are -currently looking at. It hosts the core components of Istio and also +currently looking at. It hosts Istio's core components and also the sample programs and the various documents that govern the Istio open source project. It includes: - [security](security/). This directory contains security related code, @@ -108,18 +117,6 @@ milestone cannot be considered achieved if the issue isn't resolved. We don't annotate issues with Releases; Milestones are used instead. We don't use GitHub projects at all, that support is disabled for our organization. -## Contributing to the project - -We promote and encourage a set of [shared values](VALUES.md) to improve our -productivity and inter-personal interactions. - -See the [working groups](GROUPS.md) for a list of working groups to participate in. - -See the [contribution guidelines](CONTRIBUTING.md) for information on how to -participate in the Istio project by submitting pull requests or issues. - -You can then check out how to [setup for development](devel/README.md). - ## Community and support There are several [communication channels](https://istio.io/community/) available to get diff --git a/broker/CONTRIBUTING.md b/broker/CONTRIBUTING.md deleted file mode 100644 index de65d780ea06..000000000000 --- a/broker/CONTRIBUTING.md +++ /dev/null @@ -1,8 +0,0 @@ -# Contribution guidelines - -So, you want to hack on Broker? Yay! Please refer to Istio's overall -[contribution guidelines](https://github.com/istio/istio/blob/master/CONTRIBUTING.md) -to find out how you can help. - -As a developer on Broker be sure to also follow the [development guide](https://github.com/istio/istio/blob/master/devel/README.md) -(including steps that are required before submitting a PR) diff --git a/broker/LICENSE b/broker/LICENSE deleted file mode 100644 index da2dae60a018..000000000000 --- a/broker/LICENSE +++ /dev/null @@ -1,202 +0,0 @@ - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "{}" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright 2017 Istio Authors - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/mixer/CONTRIBUTING.md b/mixer/CONTRIBUTING.md deleted file mode 100644 index 747d96ef4583..000000000000 --- a/mixer/CONTRIBUTING.md +++ /dev/null @@ -1,8 +0,0 @@ -# Contribution guidelines - -So, you want to hack on Mixer? Yay! Please refer to Istio's overall -[contribution guidelines](https://github.com/istio/istio/blob/master/CONTRIBUTING.md) -to find out how you can help. - -As a developer on Mixer be sure to also follow the Mixer-specific [development guide](doc/dev/development.md) -(including steps that are required before submitting a PR) diff --git a/mixer/LICENSE b/mixer/LICENSE deleted file mode 100644 index 2c45691e8839..000000000000 --- a/mixer/LICENSE +++ /dev/null @@ -1,202 +0,0 @@ - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "{}" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright 2016 Istio Authors - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/mixer/README.md b/mixer/README.md index 80a7b263b8e3..f88fb9ce9641 100644 --- a/mixer/README.md +++ b/mixer/README.md @@ -1,10 +1,5 @@ # Mixer -![Mixer](doc/logo.png) - -[![GoDoc](https://godoc.org/github.com/istio/mixer?status.svg)](https://godoc.org/github.com/istio/mixer) -[![Go Report -Card](https://goreportcard.com/badge/github.com/istio/mixer)](https://goreportcard.com/report/github.com/istio/mixer) -[![codecov.io](https://codecov.io/github/istio/mixer/coverage.svg?branch=master)](https://codecov.io/github/istio/mixer?branch=master) +![Mixer](doc/img/logo.png) Mixer enables extensible policy enforcement and control within the Istio service mesh. It is responsible for insulating the proxy (Envoy) from details of the @@ -29,15 +24,11 @@ Mixer provides three distinct features: Learn more about Mixer [here](https://istio.io/docs/concepts/policy-and-control/mixer.html). -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 Mixer, please see the Istio [contribution -guidelines](https://github.com/istio/istio/blob/master/CONTRIBUTING.md). - -Mixer's [developer's guide](doc/dev/development.md) presents everything you need -to know to create, build, and test code for Mixer. - -Mixer's [Adapter Developer's Guide](doc/dev/adapters.md) presents everything you +Mixer's [Adapter Developer's Guide](doc/adapters.md) presents everything you need to know about extending Mixer to provide support for new backends through the development of new [adapters](https://istio.io/docs/concepts/policy-and-control/mixer.html#adapters). + +Mixer's [Template Developer's Guide](doc/templates.md) presents everything you +need to know about you can create new templates to define whole new categories +of adapters. diff --git a/mixer/doc/dev/adapter-development-walkthrough.md b/mixer/doc/adapter-development-walkthrough.md similarity index 99% rename from mixer/doc/dev/adapter-development-walkthrough.md rename to mixer/doc/adapter-development-walkthrough.md index 728ce88f328c..e00cffef779b 100644 --- a/mixer/doc/dev/adapter-development-walkthrough.md +++ b/mixer/doc/adapter-development-walkthrough.md @@ -32,7 +32,7 @@ In this walkthrough you're going to create a simple adapter that: Download a local copy of the Mixer repo ```bash -git clone https://github.com/istio/mixer +git clone https://github.com/istio/istio ``` Install bazel (version 0.5.2 or higher) from [https://bazel.build/](https://bazel.build/) and add it to your PATH diff --git a/mixer/doc/dev/adapters.md b/mixer/doc/adapters.md similarity index 96% rename from mixer/doc/dev/adapters.md rename to mixer/doc/adapters.md index 9b855e87b28b..67ba7ebc4e74 100644 --- a/mixer/doc/dev/adapters.md +++ b/mixer/doc/adapters.md @@ -37,7 +37,7 @@ this template-specific data is constructed and dispatched to adapters. Out of the box, Mixer provides a suite of [default templates](#built-in-templates). We strongly recommend that, when implementing adapters, you use Mixer's default templates. Though if they are not suitable for your particular needs you can also [create your own templates](./templates.md) -along with adapters to consume the relevant data. Mixer also includes some [built-in adapters](https://github.com/istio/mixer/tree/master/adapter) +along with adapters to consume the relevant data. Mixer also includes some [built-in adapters](https://github.com/istio/istio/tree/master/mixer/adapter) by default, but users may need to implement their own to let Mixer send data to their chosen backend. The roles of the template author, adapter author, and the operator can be summarized as: @@ -332,7 +332,7 @@ This is when Mixer is booted and adapters are initialized. Every adapter must im returns an `adapter.Info` object. During initialization, Mixer invokes this function for all known adapters. The `adapter.Info` describes the templates an adapter wants to support as well as how to construct its `builder` object. -`adapter.Info` (Details in [info.go](https://github.com/istio/mixer/blob/master/pkg/adapter/info.go)) contains the +`adapter.Info` (Details in [info.go](https://github.com/istio/istio/blob/master/mixer/pkg/adapter/info.go)) contains the following information: @@ -436,7 +436,7 @@ for a given input set of attributes: The following sample adapters illustrate the basic skeleton of the adapter code and do not provide any functionality. They always return success. For examples of real world adapters, see [implementation of built-in adapters -within Mixer framework](https://github.com/istio/mixer/tree/master/adapter). +within Mixer framework](https://github.com/istio/istio/tree/master/mixer/adapter). * Sample adapter that supports the 'metric' template @@ -619,7 +619,7 @@ start, when operator configuration is loaded/changed and when request is receive # Plug adapter into Mixer For a new adapter to plug into Mixer, you will have to add your adapter's reference into Mixer's inventory -[build file](https://github.com/istio/mixer/blob/master/adapter/BUILD)'s inventory_library rule. In the *deps* section +[build file](https://github.com/istio/istio/blob/master/mixer/adapter/BUILD)'s inventory_library rule. In the *deps* section add a reference to adapter's go_library build rule, and in the *packages* section add the short name and the go import path to the adapter package that implements the `GetInfo `function. These two changes will plug your custom adapter into Mixer. @@ -644,20 +644,20 @@ goroutines are prevented from crashing Mixer as a whole by catching any panics t Mixer ships with a set of built-in templates that are ready to use by adapters: -* [listentry](https://github.com/istio/mixer/tree/master/template/listentry) +* [listentry](https://github.com/istio/istio/tree/master/mixer/template/listentry) -* [logentry](https://github.com/istio/mixer/tree/master/template/logentry) +* [logentry](https://github.com/istio/istio/tree/master/mixer/template/logentry) -* [quota](https://github.com/istio/mixer/tree/master/template/quota) +* [quota](https://github.com/istio/istio/tree/master/mixer/template/quota) -* [metric](https://github.com/istio/mixer/tree/master/template/metric) +* [metric](https://github.com/istio/istio/tree/master/mixer/template/metric) -* [checknothing](https://github.com/istio/mixer/tree/master/template/checknothing) +* [checknothing](https://github.com/istio/istio/tree/master/mixer/template/checknothing) -* [reportnothing](https://github.com/istio/mixer/tree/master/template/reportnothing) +* [reportnothing](https://github.com/istio/istio/tree/master/mixer/template/reportnothing) Using the above templates, the Mixer team has implemented a set of adapters that ships as part of the default Mixer -binary. They are located at [istio/mixer/adapter](https://github.com/istio/mixer/tree/master/adapter). They are good +binary. They are located at [istio/mixer/adapter](https://github.com/istio/istio/tree/master/mixer/adapter). They are good examples for reference when implementing new adapters. # Walkthrough of adapter implementation (30 minutes) diff --git a/mixer/doc/dev/img/example attr to instance.svg b/mixer/doc/img/example attr to instance.svg similarity index 100% rename from mixer/doc/dev/img/example attr to instance.svg rename to mixer/doc/img/example attr to instance.svg diff --git a/mixer/doc/dev/img/example instance to type.svg b/mixer/doc/img/example instance to type.svg similarity index 100% rename from mixer/doc/dev/img/example instance to type.svg rename to mixer/doc/img/example instance to type.svg diff --git a/mixer/doc/dev/img/handler config.svg b/mixer/doc/img/handler config.svg similarity index 100% rename from mixer/doc/dev/img/handler config.svg rename to mixer/doc/img/handler config.svg diff --git a/mixer/doc/logo.png b/mixer/doc/img/logo.png similarity index 100% rename from mixer/doc/logo.png rename to mixer/doc/img/logo.png diff --git a/mixer/doc/dev/img/mixer adapter flow.svg b/mixer/doc/img/mixer adapter flow.svg similarity index 100% rename from mixer/doc/dev/img/mixer adapter flow.svg rename to mixer/doc/img/mixer adapter flow.svg diff --git a/mixer/doc/dev/img/mixer architecture.svg b/mixer/doc/img/mixer architecture.svg similarity index 100% rename from mixer/doc/dev/img/mixer architecture.svg rename to mixer/doc/img/mixer architecture.svg diff --git a/mixer/doc/dev/img/mixer start flow.svg b/mixer/doc/img/mixer start flow.svg similarity index 100% rename from mixer/doc/dev/img/mixer start flow.svg rename to mixer/doc/img/mixer start flow.svg diff --git a/mixer/doc/dev/img/operator config change.svg b/mixer/doc/img/operator config change.svg similarity index 100% rename from mixer/doc/dev/img/operator config change.svg rename to mixer/doc/img/operator config change.svg diff --git a/mixer/doc/dev/img/operator template adapter dev.svg b/mixer/doc/img/operator template adapter dev.svg similarity index 100% rename from mixer/doc/dev/img/operator template adapter dev.svg rename to mixer/doc/img/operator template adapter dev.svg diff --git a/mixer/doc/dev/img/request time.svg b/mixer/doc/img/request time.svg similarity index 100% rename from mixer/doc/dev/img/request time.svg rename to mixer/doc/img/request time.svg diff --git a/mixer/doc/dev/img/template generated artifacts.svg b/mixer/doc/img/template generated artifacts.svg similarity index 100% rename from mixer/doc/dev/img/template generated artifacts.svg rename to mixer/doc/img/template generated artifacts.svg diff --git a/mixer/doc/dev/img/template, adapter and operator config relationship.svg b/mixer/doc/img/template, adapter and operator config relationship.svg similarity index 100% rename from mixer/doc/dev/img/template, adapter and operator config relationship.svg rename to mixer/doc/img/template, adapter and operator config relationship.svg diff --git a/mixer/doc/dev/development.md b/mixer/doc/running-local-mixer.md similarity index 87% rename from mixer/doc/dev/development.md rename to mixer/doc/running-local-mixer.md index ba4f6d64317e..37541eae3467 100644 --- a/mixer/doc/dev/development.md +++ b/mixer/doc/running-local-mixer.md @@ -1,13 +1,5 @@ -# Development Guide +# Running Mixer locally -Please see the [Istio development guide](https://github.com/istio/istio/blob/master/devel/README.md) -for the common Istio-wide development guidelines. - -After which here are other Mixer specific docs you should look at: - -- [Writing Mixer adapters](./adapters.md) - -## Using Mixer locally The following command runs Mixer locally using local configuration. The default configuration contain adapters like `stackdriver` that connect to outside systems. If you do not intend to use the adapter for local testing, you should move `testdata/config/stackdriver.yaml` out of the config directory, otherwise you will see repeated logging of configuration errors. diff --git a/mixer/doc/dev/templates.md b/mixer/doc/templates.md similarity index 97% rename from mixer/doc/dev/templates.md rename to mixer/doc/templates.md index 603233195748..df3a080ab110 100644 --- a/mixer/doc/dev/templates.md +++ b/mixer/doc/templates.md @@ -30,14 +30,14 @@ the data adapters receive, as well as the instances operators must create in ord The [Adapter Developer's Guide](./adapters.md#template-overview) explains how templates are automatically transformed into Go structs and interfaces that can be used by adapter developers, and into config definitions that can be used by operators. -Mixer includes a number of [canonical templates](https://github.com/istio/mixer/tree/master/template) which cover +Mixer includes a number of [canonical templates](https://github.com/istio/istio/tree/master/mixer/template) which cover most of the anticipated workloads that Mixer is expected to be used with. However, the set of supported templates can readily be extended in order to support emerging usage scenarios. Note that it’s preferable to use existing templates when possible as it tends to deliver a better end-to-end story for the ecosystem by making configuration state more portable between adapters. This document describes the simple rules used to create templates for Mixer. -The [Adapter Developer’s Guide](https://github.com/istio/mixer/blob/master/doc/dev/adapters.md) describes how to use templates to +The [Adapter Developer’s Guide](https://github.com/istio/istio/blob/master/mixer/doc/adapters.md) describes how to use templates to create adapters. ## Template format diff --git a/pilot/CONTRIBUTING.md b/pilot/CONTRIBUTING.md deleted file mode 100644 index 76b518433645..000000000000 --- a/pilot/CONTRIBUTING.md +++ /dev/null @@ -1,5 +0,0 @@ -# Contribution guidelines - -So, you want to hack on Istio Pilot? Yay! Please refer to Istio's overall -[contribution guidelines](https://github.com/istio/istio/blob/master/CONTRIBUTING.md) -to find out how you can help. diff --git a/pilot/LICENSE b/pilot/LICENSE deleted file mode 100644 index 8b2be6d61daf..000000000000 --- a/pilot/LICENSE +++ /dev/null @@ -1,201 +0,0 @@ - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "{}" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright 2016 Istio Authors - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/pilot/README.md b/pilot/README.md index 16d8842aced0..c514f712e201 100644 --- a/pilot/README.md +++ b/pilot/README.md @@ -1,11 +1,6 @@ -# Istio Pilot # -[Prow build Status](https://prow.istio.io/?job=pilot-postsubmit) -[![CircleCI](https://circleci.com/gh/istio/pilot/tree/master.svg?style=svg)](https://circleci.com/gh/istio/pilot/tree/master) -[![Go Report Card](https://goreportcard.com/badge/github.com/istio/pilot)](https://goreportcard.com/report/github.com/istio/pilot) -[![GoDoc](https://godoc.org/github.com/istio/pilot?status.svg)](https://godoc.org/github.com/istio/pilot) -[![codecov.io](https://codecov.io/github/istio/pilot/coverage.svg?branch=master)](https://codecov.io/github/istio/pilot?branch=master) +# Istio Pilot -Istio Pilot provides platform-independant service discovery, and exposes an +Istio Pilot provides platform-independent service discovery, and exposes an interface to configure rich L7 routing features such as label based routing across multiple service versions, fault injection, timeouts, retries, circuit breakers. It translates these configurations into sidecar-specific @@ -22,11 +17,6 @@ Istio Pilot [design](doc/design.md) gives an architectural overview of its internal components - cluster platform abstractions, service model, and the proxy controllers. - -To learn how you can contribute to Istio Pilot, please -see the Istio -[contribution guidelines](https://github.com/istio/istio/blob/master/CONTRIBUTING.md). - # Quick start 1. *Install Bazel:* [Bazel 0.6.1](https://github.com/bazelbuild/bazel/releases/tag/0.6.1) or diff --git a/security/CONTRIBUTING.md b/security/CONTRIBUTING.md deleted file mode 100644 index d49ada2b04b0..000000000000 --- a/security/CONTRIBUTING.md +++ /dev/null @@ -1,5 +0,0 @@ -# Contribution guidelines - -So, you want to hack on the Istio auth module? Yay! Please refer to Istio's overall -[contribution guidelines](https://github.com/istio/istio/blob/master/CONTRIBUTING.md) -to find out how you can help. diff --git a/security/LICENSE b/security/LICENSE deleted file mode 100644 index 92494b11e804..000000000000 --- a/security/LICENSE +++ /dev/null @@ -1,201 +0,0 @@ - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "{}" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright 2017 Istio Authors - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/security/README.md b/security/README.md index 7fb97b7cbc2a..c762531c4cb8 100644 --- a/security/README.md +++ b/security/README.md @@ -1,9 +1,5 @@ # Istio Security -[![Go Report Card](https://goreportcard.com/badge/github.com/istio/auth)](https://goreportcard.com/report/github.com/istio/auth) -[![codecov](https://codecov.io/gh/istio/auth/branch/master/graph/badge.svg)](https://codecov.io/gh/istio/auth) - - ## Overview Istio Security's aim is to enhance the security of microservices and their communication without requiring service code changes. It is responsible for: @@ -26,8 +22,6 @@ As illustrated in the diagram, Istio Security leverages secret volume mount to d For services running on VM/bare-metal machines, we introduce a node agent, which is a process running on each VM/bare-metal machine. It generates the private key and CSR (certificate signing request) locally, sends CSR to Istio CA for signing, and delivers the generated certificate together with the private key to Envoy. -## Components - ### Identity Istio Security uses [Kubernetes service accounts](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) to identify who runs the service: @@ -131,23 +125,3 @@ datastore SRE team creates 1 service account to run the datastore service in nam in [Istio Mixer]({{home}}/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. - -## Future work - -* Inter-cluster service-to-service authentication - -* Powerful authorization mechanisms: ABAC, RBAC, etc - -* Per-service auth enablement support - -* Secure Istio components (Mixer, Pilot) - -* End-user to service authentication using JWT/OAuth2/OpenID_Connect. - -* Support GCP service account - -* Unix domain socket for local communication between service and Envoy - -* Layer-7 Middle proxy support - -* Pluggable key management component