From 9a493e3dd64479e654133d16a9b8312f35b22924 Mon Sep 17 00:00:00 2001 From: Bill Robinson Date: Fri, 7 Apr 2017 11:14:08 -0700 Subject: [PATCH] Updated README.md with various corrections/improvements Signed-off-by: Bill Robinson --- README.md | 40 +++++++++++++++++++++-------------- scripts/build.sh | 5 ++--- scripts/build_in_container.sh | 4 ++-- 3 files changed, 28 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 554c9e9c..f18f16ac 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,27 @@ # Auth Proxy -`auth_proxy` provides authentication and authorization via -RBAC before forwarding requests to an upstream `netmaster`. It is TLS-only, +`auth_proxy` provides authentication (local users/LDAP/AD) and authorization +(RBAC) before forwarding requests to an upstream `netmaster`. It is TLS-only, and it will only talk to a non-TLS `netmaster`. Future versions will allow or potentially require TLS-only communication with `netmaster`. -`auth_proxy` also hosts the UI (see the [contiv-ui repo](https://github.com/contiv/contiv-ui)). +`auth_proxy` also hosts the Contiv UI (see the [contiv-ui repo](https://github.com/contiv/contiv-ui)). The UI is baked into the container and lives at the `/ui` directory. It is served from the root of the proxy, e.g., if you run with `--listen-address=localhost:10000`, you can see the UI at https://localhost:10000 A custom version of the UI can be bindmounted over the baked-in version. Note that you need to bind in the `/app` directory under the `contiv-ui` repo, not the base -directory: `-v /your/contiv-ui/repo/app:/ui:ro` +directory (e.g., `-v /your/contiv-ui/repo/app:/ui:ro`) ## Building -Running `make` will generate a `auth_proxy:devbuild` image using the current code -you have checked out and `HEAD` from the `master` branch in the `contiv-ui` repo. +Running `make` will generate a `contiv/auth_proxy:devbuild` image using the current +code you have checked out and `HEAD` from the `master` branch in the `contiv-ui` repo. You can also specify a version, e.g., `BUILD_VERSION=0.1 make`. This will -generate a `auth_proxy:0.1` image using current code you have checked out and -whatever commit is tagged as `0.1` in the `contiv-ui` repo. +generate a `contiv/auth_proxy:0.1` image using current code you have checked out +and whatever commit is tagged as `0.1` in the `contiv-ui` repo. ## Version Checking @@ -34,29 +34,37 @@ version of `1.x.y` where `x` is >= 2 and `y` can be anything. ## Running Tests +Tests currently run against the `contiv/auth_proxy:devbuild` image. Make sure you +have built this image before running tests. + Just run `make test` to run the systemtests and unit tests. The tests are fully -containerized and will spawn anything they require as part of the test run -(note that this does NOT currently include an AD server and we are still using a -hardcoded one). There is also a `MockServer` available in the `systemtests` +containerized and will spawn everything they require as part of the test run +(note that this does NOT currently include an AD server, and we are still using a +hardcoded one). + +There is also a `MockServer` available in the `systemtests` directory which can pretend to be `netmaster` for the purposes of testing. This allows us to mock the parts of `netmaster` we need (mainly that a given endpoint returns some expected JSON response) without the burden of actually compiling and running a full `netmaster` binary and all of its dependencies plus creating the necessary networks, tenants, etc. to get realistic responses from it. -For a complete e2e setup involving auth_proxy + UI + netmaster, please see [contiv/install](https://github.com/contiv/install). +For a complete e2e setup involving auth_proxy + UI + netmaster, please see +[contiv/install](https://github.com/contiv/install). ## Local Development -You will need a local cert and key to start `auth_proxy`. You can run -`make generate-certificate` to generate them if you don't already have them. To test proxy -only functionality, try `make run`. +You will need a certificate and key to start `auth_proxy`. You can run +`make generate-certificate` to generate a self-signed certificate and key under +`./local_certs` if you don't already have them. + +To test auth_proxy in isolation, use `make run` to start it using the compose file. ## Architecture Overview Before anything else, a prospective user must authenticate and get a token. Authentication requires passing a username and password to the -`/api/v1/auth_proxy/login` endpoint: +`/api/v1/auth_proxy/login/` endpoint: ``` login request ---> auth_proxy ---> authentication diff --git a/scripts/build.sh b/scripts/build.sh index 856a72fd..d3d535e2 100755 --- a/scripts/build.sh +++ b/scripts/build.sh @@ -10,7 +10,6 @@ VERSION=${BUILD_VERSION-$DEV_IMAGE_NAME} # # bake in the UI assets # -START_DIR=$(pwd) UI_DIR="$PWD/build/dependencies/contiv-ui" mkdir -p $UI_DIR @@ -24,7 +23,7 @@ if [ ! -d "$UI_DIR/.git" ]; then git clone --depth 1 https://github.com/contiv/contiv-ui.git $UI_DIR fi -cd $UI_DIR +pushd $UI_DIR # this is a fancy way to check if the var is set without tripping the unbound variable check if [ ! -z "${BUILD_VERSION-}" ]; then @@ -42,7 +41,7 @@ fi # # build the final image # -cd $START_DIR +popd # create a local build image docker build -t $BUILD_IMAGE_NAME -f ./build/Dockerfile.build . diff --git a/scripts/build_in_container.sh b/scripts/build_in_container.sh index 3021f1e2..1518baec 100755 --- a/scripts/build_in_container.sh +++ b/scripts/build_in_container.sh @@ -6,8 +6,8 @@ set -euxo pipefail # for our "scratch"-based final image. export CGO_ENABLED=0 -# output the binary under the build/output directory in the code dir so that it's -# available when we issue the `docker build` and COPY it into the final image. +# output the binary under the build/output directory from where it will be +# `docker cp`ed into the final image. go build \ -ldflags "-X main.ProgramVersion=$VERSION" \ -o ./build/output/auth_proxy \