linkerd
/
linkerd2
mirror of https://github.com/linkerd/linkerd2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update top-level docs to reflect repo rename (#1333) 

Signed-off-by: Kevin Lingerfelt <kl@buoyant.io>
This commit is contained in:
Kevin Lingerfelt 2018-07-17 13:42:25 -07:00 committed by GitHub
parent e377cf4214
commit 37f8490edb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 80 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

142
BUILD.md
View File

@ -1,8 +1,8 @@
# Conduit Development Guide
# Linkerd2 Development Guide
:balloon: Welcome to the Conduit development guide! :wave:
:balloon: Welcome to the Linkerd2 development guide! :wave:
This document will help you build and run Conduit from source. More information
This document will help you build and run Linkerd2 from source. More information
about testing from source can be found in the [TEST.md](TEST.md) guide.
# Table of contents
@ -23,13 +23,13 @@ about testing from source can be found in the [TEST.md](TEST.md) guide.
# Repo layout
Conduit is primarily written in Rust, Go, and React. At its core is a
Linkerd2 is primarily written in Rust, Go, and React. At its core is a
high-performance data plane written in Rust. The control plane components are
written in Go. The dashboard UI is a React application.
## Control Plane (Go/React)
- [`cli`](cli): Command-line `conduit` utility, view and drive the control
- [`cli`](cli): Command-line `linkerd` utility, view and drive the control
plane.
- [`controller`](controller)
- [`destination`](controller/destination): Serves service discovery
@ -39,25 +39,27 @@ written in Go. The dashboard UI is a React application.
service.
- [`public-api`](controller/api/public): Accepts requests from API
clients such as `cli` and `web`, provides access to and control of the
conduit service mesh.
Linkerd2 service mesh.
- [`tap`](controller/tap): Provides a live pipeline of requests.
- [`proxy-init`](proxy-init): Adds a Kubernetes pod to join the Conduit
- [`proxy-init`](proxy-init): Adds a Kubernetes pod to join the Linkerd2
Service Mesh.
- [`web`](web): Provides a UI dashboard to view and drive the control plane.
This component is written in Go and React.
## Data Plane (Rust)
- [`proxy`](proxy): High-performance data plane, injected as a sidecar with
every service.
- [`linkerd2-proxy`](https://github.com/linkerd/linkerd2-proxy): Rust source
code for the proxy lives in the linkerd2-proxy repo.
- [`linkerd2-proxy-api`](https://github.com/linkerd/linkerd2-proxy-api): Protobuf
definitions for the data plane APIs live in the linkerd2-proxy-api repo.
# Components
![Conduit Components](https://g.gravizo.com/source/svg/conduit_components?https%3A%2F%2Fraw.githubusercontent.com%2Frunconduit%2Fconduit%2Fmaster%2FBUILD.md)
![Linkerd2 Components](https://g.gravizo.com/source/svg/linkerd2_components?https%3A%2F%2Fraw.githubusercontent.com%2Flinkerd%2Flinkerd2%2Fmaster%2FBUILD.md)
<details>
<summary></summary>
conduit_components
linkerd2_components
digraph G {
rankdir=LR;
@ -94,22 +96,21 @@ conduit_components
"prometheus" -> "kubernetes api";
"prometheus" -> "proxy";
}
conduit_components
linkerd2_components
</details>
# Development configurations
Depending on use case, there are several configurations with which to develop
and run Conduit:
and run Linkerd2:
- [Comprehensive](#comprehensive): Integrated configuration using Minikube, most
closely matches release.
- [Web](#web): Development of the Conduit Dashboard.
- [Rust](#Rust): Standalone development of the Rust `proxy`.
- [Web](#web): Development of the Linkerd2 Dashboard.
## Comprehensive
This configuration builds all Conduit components in Docker images, and deploys
This configuration builds all Linkerd2 components in Docker images, and deploys
them onto Minikube. This setup most closely parallels our recommended production
installation, documented at https://conduit.io/getting-started/.
@ -118,32 +119,32 @@ These commands assume a working
```bash
# build all docker images, using minikube as our docker repo
DOCKER_TRACE=1 bin/mkube bin/docker-build
DOCKER_TRACE=1 bin/mkube bin/fast-build
# install conduit
bin/conduit install | kubectl apply -f -
# install linkerd
bin/linkerd install | kubectl apply -f -
# verify cli and server versions
bin/conduit version
bin/linkerd version
# validate installation
kubectl --namespace=conduit get all
bin/conduit check --expected-version $(bin/root-tag)
kubectl --namespace=linkerd get all
bin/linkerd check --expected-version $(bin/root-tag)
# view conduit dashboard
bin/conduit dashboard
# view linkerd dashboard
bin/linkerd dashboard
# install the demo app
curl https://raw.githubusercontent.com/linkerd/linkerd2-examples/master/emojivoto/emojivoto.yml | bin/conduit inject - | kubectl apply -f -
curl https://raw.githubusercontent.com/runconduit/conduit-examples/master/emojivoto/emojivoto.yml | bin/linkerd inject - | kubectl apply -f -
# view demo app
minikube -n emojivoto service web-svc --url
minikube -n emojivoto service web-svc
# view details per deployment
bin/conduit -n emojivoto stat deployments
bin/linkerd -n emojivoto stat deployments
# view a live pipeline of requests
bin/conduit -n emojivoto tap deploy voting
bin/linkerd -n emojivoto tap deploy voting
```
### A note about Go run
@ -155,31 +156,20 @@ build/run/debug loop faster.
In general, replace commands like this:
```bash
go run cli/main.go
go run cli/main.go check
```
with this:
```bash
bin/go-run cli
```
You may also leverage `go-run` to execute our `conduit` cli command. While in a
release context you may run:
```bash
conduit check
```
In development you can run:
```bash
bin/go-run cli check
```
That is equivalent to running `linkerd check` using the code on your branch.
### Building the CLI for development
When Conduit's CLI is built using `bin/docker-build` it always creates binaries
When Linkerd2's CLI is built using `bin/docker-build` it always creates binaries
for all three platforms. For local development and a faster edit-build-test
cycle you might want to avoid that. For those situations you can use the
`bin/fast-build` script, which builds the CLI using the local Go toolchain
@ -191,7 +181,7 @@ bin/fast-build
### Running the control plane for development
Conduit's control plane is composed of several Go microservices. You can run
Linkerd2's control plane is composed of several Go microservices. You can run
these components in a Kubernetes (or Minikube) cluster, or even locally.
To run an individual component locally, you can use the `go-run` command, and
@ -242,7 +232,7 @@ To develop with a webpack dev server, run:
bin/web dev
```
Note: you'll want to install conduit on a Kubernetes cluster first.
Note: you'll want to install Linkerd2 on a Kubernetes cluster first.
To add a JS dependency:
@ -253,65 +243,23 @@ yarn add [dep]
## Rust
These commands assume a working [Rust](https://www.rust-lang.org)
environment.
Note that we _only_ support the most recent `stable` version of Rust.
To build and run the Rust proxy:
```bash
cargo build -p conduit-proxy
LINKERD2_PROXY_LOG=trace \
LINKERD2_PROXY_PUBLIC_LISTENER=tcp://0.0.0.0:5432 \
LINKERD2_PROXY_PRIVATE_FORWARD=tcp://127.0.0.1:1234 \
LINKERD2_PROXY_CONTROL_URL=tcp://127.0.0.1:8086 \
target/debug/conduit-proxy
```
To connect to a live `proxy-api` at `localhost:8086`:
```bash
bin/go-run controller/cmd/proxy-api
```
All Rust development happens in the
[`linkerd2-proxy`](https://github.com/linkerd/linkerd2-proxy) repo.
### Docker
The `bin/docker-build-proxy` script builds the proxy:
The `bin/docker-build-proxy` script builds the proxy by pulling a pre-published
proxy binary:
```bash
DOCKER_TRACE=1 PROXY_UNOPTIMIZED=1 bin/docker-build-proxy
DOCKER_TRACE=1 bin/docker-build-proxy
```
It supports two environment variables:
- `PROXY_UNOPTIMIZED` -- When set and non-empty, produces unoptimized build artifacts,
which reduces build times at the expense of runtime performance. Changing this will
likely invalidate a substantial portion of Docker's cache.
To run `cargo test` inside of the latest proxy Docker image, run:
```bash
bin/docker-test-proxy
```
This is primarily useful for testing Linux-only proxy features when developing
on another operating system.
# Dependencies
## Updating protobuf dependencies
If you make Protobuf changes, run:
```bash
bin/dep ensure
bin/protoc-go.sh
```
## Updating Docker dependencies
The Rust proxy and Go Docker images rely on base dependency images with
The go Docker images rely on base dependency images with
hard-coded SHA's:
`gcr.io/linkerd-io/go-deps` depends on
@ -322,7 +270,7 @@ hard-coded SHA's:
# Build Architecture
![Build Architecture](https://g.gravizo.com/source/svg/build_architecture?https%3A%2F%2Fraw.githubusercontent.com%2Frunconduit%2Fconduit%2Fmaster%2FBUILD.md)
![Build Architecture](https://g.gravizo.com/source/svg/build_architecture?https%3A%2F%2Fraw.githubusercontent.com%2Flinkerd%2Flinkerd2%2Fmaster%2FBUILD.md)
<details>
<summary></summary>
@ -332,10 +280,10 @@ build_architecture
"Dockerfile-base" [color=lightblue, style=filled, shape=rect];
"Dockerfile-go-deps" [color=lightblue, style=filled, shape=rect];
"Dockerfile-proxy" [color=lightblue, style=filled, shape=rect];
"controller/Dockerfile" [color=lightblue, style=filled, shape=rect];
"cli/Dockerfile-bin" [color=lightblue, style=filled, shape=rect];
"grafana/Dockerfile" [color=lightblue, style=filled, shape=rect];
"proxy/Dockerfile" [color=lightblue, style=filled, shape=rect];
"proxy-init/Dockerfile" [color=lightblue, style=filled, shape=rect];
"proxy-init/integration_test/iptables/Dockerfile-tester" [color=lightblue, style=filled, shape=rect];
"web/Dockerfile" [color=lightblue, style=filled, shape=rect];
@ -348,7 +296,7 @@ build_architecture
"_log.sh";
"_tag.sh";
"conduit" -> "docker-build-cli-bin";
"linkerd" -> "docker-build-cli-bin";
"dep";
@ -384,7 +332,7 @@ build_architecture
"docker-build-proxy" -> "_docker.sh";
"docker-build-proxy" -> "_tag.sh";
"docker-build-proxy" -> "proxy/Dockerfile";
"docker-build-proxy" -> "Dockerfile-proxy";
"docker-build-proxy-init" -> "_docker.sh";
"docker-build-proxy-init" -> "_tag.sh";

9
CONTRIBUTING.md
View File

@ -1,12 +1,12 @@
# Contributing to Conduit #
# Contributing to Linkerd2 #
:balloon: Thanks for your help improving the project!
## Getting Help ##
If you have a question about Conduit or have encountered problems using it,
If you have a question about Linkerd2 or have encountered problems using it,
start by [asking a question in the forums][discourse] or join us in the
[#conduit Slack channel][slack].
(yet-to-be-renamed) [#conduit Slack channel][slack].
## Certificate of Origin ##
@ -35,8 +35,8 @@ Do you have an improvement?
3. Fork this repo, develop and test your code changes. See the project's [README](README.md) for further information about working in this repository.
4. Submit a pull request against this repo's `master` branch.
5. Your branch may be merged once all configured checks pass, including:
- 2 code review approvals, at least 1 of which is from a [runconduit organization member][members].
- The branch has passed tests in CI.
- A review from appropriate maintainers (see [MAINTAINERS.md](MAINTAINERS.md) and [GOVERNANCE.md](GOVERNANCE.md))
## Committing ##
@ -99,5 +99,4 @@ changes should include before- and after- benchmark results.
[discourse]: https://discourse.linkerd.io/c/conduit
[issue]: https://github.com/linkerd/linkerd2/issues/new
[members]: https://github.com/orgs/runconduit/people
[slack]: http://slack.linkerd.io/

79
TEST.md
View File

@ -1,9 +1,9 @@
# Conduit Test Guide
# Linkerd2 Test Guide
This document covers how to run all of the tests that are present in the Conduit
repo. Most of these tests are run in CI, but you can use the instructions here
to run the tests from source. For more information about working in this repo,
see the [BUILD.md](BUILD.md) guide.
This document covers how to run all of the tests that are present in the
Linkerd2 repo. Most of these tests are run in CI, but you can use the
instructions here to run the tests from source. For more information about
working in this repo, see the [BUILD.md](BUILD.md) guide.
Note that all shell commands in this guide are expected to be run from the root
of this repo, unless otherwise indicated by a `cd` command.
@ -11,7 +11,6 @@ of this repo, unless otherwise indicated by a `cd` command.
# Table of contents
- [Unit tests](#unit-tests)
- [Rust](#rust)
- [Go](#go)
- [Javascript](#javascript)
- [Integration tests](#integration-tests)
@ -22,25 +21,6 @@ of this repo, unless otherwise indicated by a `cd` command.
# Unit tests
Conduit is primarily written in Rust, Go, and Javascript, and each entails a
different set of unit tests, described below.
## Rust
Rust dependencies are managed via [cargo](https://github.com/rust-lang/cargo).
To build the Rust code and run tests, run:
```bash
cargo test
```
To analyze the Rust code and report errors, without building object files or
running tests, run:
```bash
cargo check
```
## Go
Go dependencies are managed via [dep](https://github.com/golang/dep). To fetch
@ -74,7 +54,7 @@ NODE_ENV=test yarn karma start --single-run
# Integration tests
The `test/` directory contains a test suite that can be run to validate Conduit
The `test/` directory contains a test suite that can be run to validate Linkerd
functionality via a series of end-to-end tests.
## Prerequisites
@ -82,30 +62,29 @@ functionality via a series of end-to-end tests.
The integration test suite operates on your currently configured Kubernetes
cluster. Prior to running the test suite, verify that:
- The Conduit docker images you're trying to test have been built and are
- The Linkerd docker images you're trying to test have been built and are
accessible to the Kubernetes cluster to which you are deploying
- The `kubectl` CLI has been configured to talk to that Kubernetes cluster
- The Kubernetes cluster automatically provisions external IPs for external load
balanced services (e.g. GKE), or the cluster is running in minikube
- The `conduit` namespace that you're testing does not already exist
- The namespace where the tests will install Linkerd does not already exist;
by default the namespace `linkerd` is used
- The repo's Go dependencies have been downloaded by running `bin/dep ensure`
## Running tests
You can use the `bin/test-run` script to run the full suite of tests.
The `bin/test-run` script requires an absolute path to a Conduit binary to test
as the first argument. You can optionally pass the namespace where Conduit will
be installed as the second argument.
The `bin/test-run` script requires an absolute path to a `linkerd` binary to
test as the first argument. You can optionally pass the namespace where Linkerd
will be installed as the second argument.
```bash
$ bin/test-run
usage: test-run /path/to/conduit [namespace]
usage: test-run /path/to/linkerd [namespace]
```
It's also possible to run tests individually, using the `go test` command. All
of the tests are located in the `test/` directory, either at the root or in
subdirectories. The root `test/install_test.go` test installs Conduit, so that
subdirectories. The root `test/install_test.go` test installs Linkerd, so that
must be run before any of the subdirectory tests (the `bin/test-run` script does
this for you). The subdirectory tests are intended to be run independently of
each other, and in the future they may be run in parallel.
@ -114,18 +93,18 @@ To run an individual test (e.g. the "get" test), first run the root test, and
then run the subdirectory test. For instance:
```bash
$ go test -v ./test -integration-tests -conduit /path/to/conduit
$ go test -v ./test/get -integration-tests -conduit /path/to/conduit
$ go test -v ./test -integration-tests -linkerd /path/to/linkerd
$ go test -v ./test/get -integration-tests -linkerd /path/to/linkerd
```
### Testing against the installed version of the CLI
You can run tests using your installed version of the `conduit` CLI. For
You can run tests using your installed version of the `linkerd` CLI. For
example, to run the full suite of tests using your installed CLI in the
"specialtest" namespace, run:
```bash
$ bin/test-run `which conduit` specialtest
$ bin/test-run `which linkerd` specialtest
```
That will create multiple namespaces in your Kubernetes cluster:
@ -146,43 +125,43 @@ $ bin/test-cleanup specialtest
### Testing against a locally-built version of the CLI
You can also test a locally-built version of the `conduit` CLI. Note, however,
that this requires that you build the corresponding Conduit docker images and
You can also test a locally-built version of the `linkerd` CLI. Note, however,
that this requires that you build the corresponding Linkerd docker images and
publish them to a docker registry that's accessible from the Kubernetes cluster
where you're running the tests. As a result, local testing mostly applies to
[minikube](https://github.com/kubernetes/minikube), since you can build the
images directly into minikube's local docker registry, as described below.
To test your current branch on minikube, first build all of the Conduit images
To test your current branch on minikube, first build all of the Linkerd images
in your minikube environment, by running:
```bash
$ DOCKER_TRACE=1 bin/mkube bin/docker-build
```
That command also copies the corresponding `conduit` binaries into the
`target/cli` directory, and you can use the `bin/conduit` script to load those
That command also copies the corresponding `linkerd` binaries into the
`target/cli` directory, and you can use the `bin/linkerd` script to load those
binaries when running tests. To run tests using your local binary, run:
```bash
$ bin/test-run `pwd`/bin/conduit
$ bin/test-run `pwd`/bin/linkerd
```
That will create multiple namespaces in your Kubernetes cluster:
```bash
$ kubectl get ns | grep conduit
$ kubectl get ns | grep linkerd
NAME STATUS AGE
conduit Active 4m
conduit-egress-test Active 4m
conduit-get-test Active 3m
linkerd Active 4m
linkerd-egress-test Active 4m
linkerd-get-test Active 3m
...
```
To cleanup the namespaces after the test has finished, run:
```bash
$ bin/test-cleanup conduit
$ bin/test-cleanup linkerd
```
## Writing tests

2
bin/fast-build
View File

@ -1,7 +1,6 @@
#!/bin/bash
set -eu
cd "$(pwd -P)"
# Builds CLI binary for current platform only and outside docker to speed up things. Suitable for local development.
@ -20,6 +19,7 @@ fi
(
cd $rootdir
cd "$(pwd -P)"
if [ -z "${LINKERD_SKIP_DEP:-}" ]; then
$bindir/dep ensure -vendor-only -v
fi

1
bin/go-run
View File

@ -1,6 +1,7 @@
#!/bin/bash
set -eu
cd "$(pwd -P)"
bindir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"