2017-09-22 04:18:21 +02:00
|
|
|
[![Build Status](https://travis-ci.com/pulumi/pulumi.svg?token=cTUUEgrxaTEGyecqJpDn&branch=master)](https://travis-ci.com/pulumi/pulumi)
|
2017-05-24 21:44:36 +02:00
|
|
|
|
2017-09-11 22:05:01 +02:00
|
|
|
# Pulumi Fabric
|
2016-10-09 01:01:25 +02:00
|
|
|
|
2017-09-22 04:18:21 +02:00
|
|
|
The Pulumi Fabric ("Pulumi") is a framework and toolset for creating reusable cloud services.
|
2016-10-09 01:24:26 +02:00
|
|
|
|
2017-09-22 04:18:21 +02:00
|
|
|
If you are learning about Pulumi for the first time, please see [the overview document](docs/overview.md).
|
2017-01-02 00:19:22 +01:00
|
|
|
|
2017-02-25 19:46:26 +01:00
|
|
|
## Installing
|
|
|
|
|
2017-09-22 04:18:21 +02:00
|
|
|
To install Pulumi from source, simply run:
|
2017-02-25 19:46:26 +01:00
|
|
|
|
2017-09-22 04:18:21 +02:00
|
|
|
$ go get -u github.com/pulumi/pulumi
|
2017-02-25 19:46:26 +01:00
|
|
|
|
|
|
|
A `GOPATH` must be set. A good default value is `~/go`. In fact, [this is the default in Go 1.8](
|
|
|
|
https://github.com/golang/go/issues/17262).
|
|
|
|
|
2017-09-22 04:18:21 +02:00
|
|
|
This installs the `pulumi` binary to `$GOPATH/bin`.
|
2017-02-25 19:46:26 +01:00
|
|
|
|
2017-09-22 04:18:21 +02:00
|
|
|
To do anything interesting with Pulumi, you will need an SDK for your language of choice. Please see
|
2017-09-11 22:05:01 +02:00
|
|
|
[sdk/README.md](`sdk/`) for information about how to obtain, install, and use such an SDK.
|
2017-02-25 19:52:01 +01:00
|
|
|
|
2017-02-25 19:46:26 +01:00
|
|
|
## Development
|
|
|
|
|
2017-09-22 04:18:21 +02:00
|
|
|
This section is for Pulumi developers.
|
2017-02-25 19:46:26 +01:00
|
|
|
|
|
|
|
### Prerequisites
|
2017-02-02 20:09:33 +01:00
|
|
|
|
2017-09-22 04:18:21 +02:00
|
|
|
Pulumi is written in Go, uses Dep for dependency management, and GoMetaLinter for linting:
|
2017-02-02 20:09:33 +01:00
|
|
|
|
2017-06-21 23:23:48 +02:00
|
|
|
* [Go](https://golang.org/doc/install): https://golang.org/dl
|
2017-08-02 03:37:06 +02:00
|
|
|
* [Dep](https://github.com/golang/dep): `$ go get -u github.com/golang/dep/cmd/dep`
|
2017-06-21 23:23:48 +02:00
|
|
|
* [GoMetaLinter](https://github.com/alecthomas/gometalinter):
|
2017-08-02 03:37:06 +02:00
|
|
|
- `$ go get -u github.com/alecthomas/gometalinter`
|
2017-06-21 23:23:48 +02:00
|
|
|
- `$ gometalinter --install`
|
2017-02-02 20:09:33 +01:00
|
|
|
|
2017-02-25 19:46:26 +01:00
|
|
|
### Building and Testing
|
2017-02-02 04:33:45 +01:00
|
|
|
|
2017-09-22 04:18:21 +02:00
|
|
|
To build Pulumi, ensure `$GOPATH` is set, and clone into a standard Go workspace:
|
2016-11-23 21:41:30 +01:00
|
|
|
|
2017-09-22 04:18:21 +02:00
|
|
|
$ git clone git@github.com:pulumi/pulumi $GOPATH/src/github.com/pulumi/pulumi
|
|
|
|
$ cd $GOPATH/src/github.com/pulumi/pulumi
|
2016-11-23 21:41:30 +01:00
|
|
|
|
2017-09-12 00:17:11 +02:00
|
|
|
The first time you build, you must `make configure` to install dependencies and perform other machine setup:
|
|
|
|
|
|
|
|
$ make configure
|
|
|
|
|
|
|
|
In the future, you can synch dependencies simply by running `dep ensure` explicitly:
|
2017-05-24 22:25:28 +02:00
|
|
|
|
2017-08-02 03:37:06 +02:00
|
|
|
$ dep ensure
|
2017-05-24 22:25:28 +02:00
|
|
|
|
|
|
|
At this point you can run `make` to build and run tests:
|
2016-11-23 21:41:30 +01:00
|
|
|
|
|
|
|
$ make
|
|
|
|
|
2017-09-22 04:18:21 +02:00
|
|
|
This installs the `pulumi` binary into `$GOPATH/bin`, which may now be run provided `make` exited successfully.
|
2016-11-23 21:41:30 +01:00
|
|
|
|
2017-05-24 22:25:28 +02:00
|
|
|
The Makefile also supports just running tests (`make test`), just running the linter (`make lint`), just running Govet
|
|
|
|
(`make vet`), and so on. Please just refer to the Makefile for the full list of targets.
|
|
|
|
|
2017-02-25 19:52:01 +01:00
|
|
|
### Debugging
|
2017-01-26 22:50:27 +01:00
|
|
|
|
2017-09-22 04:18:21 +02:00
|
|
|
The Pulumi tools have extensive logging built in. In fact, we encourage liberal logging in new code, and adding new
|
2017-01-26 22:50:27 +01:00
|
|
|
logging when debugging problems. This helps to ensure future debugging endeavors benefit from your sleuthing.
|
|
|
|
|
2017-03-13 18:51:21 +01:00
|
|
|
All logging is done using Google's [Glog library](https://github.com/golang/glog). It is relatively bare-bones, and
|
|
|
|
adds basic leveled logging, stack dumping, and other capabilities beyond what Go's built-in logging routines offer.
|
2017-01-26 22:50:27 +01:00
|
|
|
|
2017-09-22 04:18:21 +02:00
|
|
|
The `pulumi` command line has two flags that control this logging and that can come in handy when debugging problems.
|
|
|
|
The `--logtostderr` flag spews directly to stderr, rather than the default of logging to files in your temp directory.
|
|
|
|
And the `--verbose=n` flag (`-v=n` for short) sets the logging level to `n`. Anything greater than 3 is reserved for
|
2017-01-26 22:50:27 +01:00
|
|
|
debug-level logging, greater than 5 is going to be quite verbose, and anything beyond 7 is extremely noisy.
|
|
|
|
|
|
|
|
For example, the command
|
|
|
|
|
2017-09-22 04:18:21 +02:00
|
|
|
$ pulumi eval --logtostderr -v=5
|
2017-01-26 22:50:27 +01:00
|
|
|
|
|
|
|
is a pretty standard starting point during debugging that will show a fairly comprehensive trace log of a compilation.
|
|
|
|
|