vSummary is an open source tool for collecting and displaying a summary of your vSphere Environment(s). Visit the demo site or see the screenshots below for a better understanding.
To quickly give vsummary-server a test drive, you can spin up the included
docker-compose test environment.
You will need both docker and docker-compose for this :)
# download the docker-compose.yml (if you haven't already cloned this repo)
wget https://raw.githubusercontent.com/gbolo/vsummary/master/docker-compose.yml
# start it up
docker-compose up
# go to http://127.0.0.1:8080
vSummary requires a credential per vCenter server that it polls. Ideally This credential should be a service user with READ-ONLY privileges to the top level vCenter object
Currently, vsummary-server requires a MYSQL 5.x backend. It can use MySQL, Percona, or MariaDB.
Create a new database and an associated user user for this database.
The database should be empty, as vsummary-server will create the required tables and schema.
The user should be given sufficient privileges to accomplish this:
+--------------------------------------------------------+
| Grants for vsummary@% |
+--------------------------------------------------------+
| GRANT USAGE ON *.* TO 'vsummary'@'%' |
| GRANT ALL PRIVILEGES ON `vsummary`.* TO 'vsummary'@'%' |
+--------------------------------------------------------+
Once the database and credentials are prepared,
you can configure vsummary-server to consume it like:
# data source name (DSN)
# format: <username>:<password>@<host>:<port>/<database>
VSUMMARY_BACKEND_DB_DSN="vsummary:secret@(localhost:3306)/vsummary"
vsummary-server has a built in vCenter poller which is configurable from the web UI. However, if the vsummary-server does not have direct access to all vCenter servers, then you may deploy one or more vsummary-poller to collect from other vCenter(s) and send that information back to your vsummary-server (via the API) for a centralized view of your entire vCenter infrastructure. The docker image has both vsummary-server and vsummary-poller pre-installed. You can also build vsummary-poller for your OS of choice if you would like to avoid using docker for this.
vsummary-poller has two modes:
-
deamonize: in this mode, vCenter destinations are defined in the configuration file and thevsummary-pollerwill keep polling until manually stopped. -
pollendpointin this mode, you must specify a vCenter via command line flags defined below:
Usage:
vsummary-poller pollendpoint [flags]
Flags:
-e, --environment string environment/name of vcenter (friendly name)
-h, --help help for pollendpoint
-p, --password string password for user (will prompt if not specified)
-u, --username string username for vcenter (readonly privilege needed)
-s, --vcenter string fqdn/ip of vcenter server
Global Flags:
--config string config file
--log-level string supported levels: INFO, WARNING, CRITICAL, DEBUG (default "INFO")
--vsummary-url string vsummary-server URL
Contributions are welcomed and appreciated!
Ensure that your changes pass the make lint target.
Full list of make targets:
$ make help
all Build server and poller binaries
server Build server binary
poller Build poller binary
docker Build docker image
fmt Run gofmt on all source files
goimports Run goimports on all source files
lint Run golangci-lint for code issues
unit-test Run go unit tests
integration-test Run integration tests
setup-integration-prereqs Setup integration prerequisites
down-integration-prereqs Shutdown integration prerequisites
vcsim Start local vCenter simulator
clean Cleanup everything
binaries will be placed in ./bin directory.
In addition to passing the make lint target, please also ensure your changes pass
the integration test. This will bring up a local vCenter Simulator and MySQL server
(docker containers) and run tests against them:
# this brings up the required containers
make setup-integration-prereqs
# this runs the actual testing
make integration-test
# this stops and removes the required containers
make down-integration-prereqs
A docker image is automatically created for every commit with the tag latest
and also for every tagged release with the image tag x.x.
It is recommended to use releases,
however the master branch should always be in a working state (hopefully).
To deploy the vsummary-server run the following:
docker run -d --name vsummary-server \
-p 8080:8080 \
-e VSUMMARY_BACKEND_DB_DSN="<CHANGE_ME>" \
gbolo/vsummary:latest
then open your browser to port 8080 on the deployed machine.
This project uses viper which means all values in the configuration file can be overwritten with environment variables. This makes it ideal for docker deployments. For a full list of configuration options see: testdata/testdata/sampleconfig/vsummary-config.yaml
All environment variables must be upper case. Each variable must begin with VSUMMARY_.
Follow the yaml indentation and for each indentation include a _.
For example:
---
# http server settings ---------
server:
# port to listen on
bind_port: 8080
# enable access log on stdout
access_log: trueIn the above sample yaml file, to override the port you would set: VSUMMARY_SERVER_BIND_PORT=443.
If you would like to use only configuration file, then mount the desired config file to /opt/vsummary/vsummary-config.yaml
in the docker image.
v1.0 of vsummary has been completely rewritten in golang. I have been working on this on and off for some time now in small bursts.
This project was meant to be a learning experience for writing a big go app with multiple components (REST API server and client, polling deamon, golang CI best practices, exc). Keep in mind that I am a DevOps guy (not a software engineer). I do this for fun.
MIT
Free Software, Hell Yeah!