AD Cloud is a collection of projects that will provide common configurations and functions simplifying implementation.
Reading articles about Spring Boot andSpring Cloud is an important first step. It gives us a sense of what is available and what the various components do. For some, this is enough to get started. For people like me, we don't feel comfortable about a concept until we fully understand it. The only way to gain that understanding is through doing. So lets get started.
Ensure you don't have any existing adcloud docker images and containers.
MySql client such as command line tool or MySql Workbench
If you are using a VM, don't forget to forward any ports you might want to access and open the ports on the firewall.
Base This will start up the monitoring (discovery and hystrix dashboard), config server, and the database server (mysql).
Copy the properties files from config/src/main/resources/repo to /tmp/config-repo. By default, the config server will look for files in /tmp/config-repo. This can be changed inside of the yml file.
cd to adcloud-docker/<network-type>, if you are not sure of the network-type, choose host.
type: docker-compose -f docker-compose-host-base.yml up
NOTE: If you are running a VM and want to be able to access the config server from your local dev environment, you can use docker-compose-dev-use.yml which will force the config server to register as localhost instead of the internal ip.
Eureka Dashboard Once docker-compose up is complete, you should be able to access the dashboard: http://localhost:8761
It's important to note that the config server may not register with the discovery service initially and you will see this.
Not to worry though as the discovery client in the config server will automatically retry. After some time, you should be able to refresh the page and see something like this.
Now our services will be able to register with the discovery service and get their configurations from the config server.
Services This will start up the gateway, aclservice, and mockidm. In a new terminal window:
cd to adcloud-docker/host, ensure the network type is the same that you used for the base.
type: docker-compose -f docker-compose-host-services.yml up
Eureka Dashboard Once docker-compose up is complete, you should refresh the dashboard: http://localhost:8761
That's it. AD Cloud is up and running.
ADCloud Before we go too much further, I really want to re-iterate that all of this is possible because of Spring Cloud and Netflix OSS. ADCloud is just tying everything together and adding functionality. With that out of the way, lets look at the ACL Service. Aside from the fact it is used to retrieve permissions for a user, it's really just a normal REST microservice. It exposes endpoints that performs CRUD operations on users, groups, roles, and permissions. It could have just been run as a standalone application. So aside from a fancy dashboard with a list of services registered, what have we gained?
Configuration and Discovery By running ACL Service within this environment, it was able to find the config server using the discovery service and retrieve its application.properties files. This means that changing its configuration can be done by simply updating the properties file in the config-repo. While this doesn't seem like a big deal with one service, it can really simplify configuration when dealing with multiple services.
Gateway The ACL Service can be accessed directly through http://localhost:9001/acl/v1.0. In fact there are JMeter tests that can be run using services/aclservice/aclservice_tests.jmx. The problem with this is that it is difficult to apply common functionality to services if each one is accessed individually.
In a typical production environment, you would want to protect your services where they would only be accessible through a gateway. This gateway provides an entry point into the services and can apply filters before and after requests are executed. This is useful for things like:
Security and RBAC
Governance and more
In addition, the gateway provides hystrix circuit breakers in order to allow services to fail fast and fallback to a helpful response. It can also use client side load balancing through the use of Ribbon. To access the ACL Service through the gateway, we use: http://localhost:8080/gateway/acl-service/acl/v1.0
There are JMeter tests that can be run that will log into the mockidm to obtain a JWT and then call all of the endpoint on the ACL Service.
Security and RBAC With the default settings, the gateway requires every request to have a valid JWT and the appropriate authorization through RBAC. Here are some scenarios:
If we try to access the ACL Service through the gateway without a JWT (http://localhost:8080/gateway/acl-service/acl/v1.0/groups), we will receive a 401 Authentication error.
If we do pass in a valid token (http://localhost:8080/gateway/acl-service/acl/v1.0/groups?access_toke=<token>) then the RBACFilter will use the ACL Service to look up the permissions available to the user. If the user does not have permission, a 403 Unauthorized error will be returned.
NOTE: In order to get a JWT, a call needs to be made to the MockIDM. curl mock:secret@localhost:8080/mockauth/oauth/token -d grant_type=password -d username=ben -d password=benspassword
Hystrix Dashboard With all of the services up and running, we can now see the circuit breaker metrics through the dashboard by accessing: