Server
Converge comes with a server that can:
- run
plan
andapply
and stream the results (using gRPC) - serve modules from a given root
- serve the Converge binary itself, for bootstrapping new systems inside your network
Basic Usage
To run converge in server mode with easy configuration, you just need
the binary installed on your device, and a token to use for authenticating over
RPC. In this example, we’ll use the uuid
utility to generate this token.
TOKEN=`uuid`
converge server --rpc-token $TOKEN
This will spin up a gRPC server on port 4774, with $token
set as the RPC
token. You should see messages streaming from the server.
If you run the server command without --rpc-token
, then the output will
include the generated token. While this token is valid during the whole
session, a new one is generated each time you start a new session. If you want
to use the same token across sessions, you will need to pass it in.
The next step is to run the converge binary in client mode. This can be on
the same machine, or a different machine in your network. This example assumes
that you have a HCL file called your.hcl
that you wish to configure the
server or device with.
TOKEN="the pasted contents of that token from earlier"
converge plan --rpc-token $TOKEN --rpc-addr 1.2.3.4:4774 your.hcl
HTTPS
You can run the server over HTTPS. If you don’t have your own certificates, you can use certstrap to get some with the following commands:
$ certstrap init --common-name your-company
$ certstrap request-cert --ip 127.0.0.1
$ certstrap sign 127.0.0.1 --CA your-company
Of course, replace your-company
and 127.0.0.1
with your company’s name and
the your server’s IP address, respectively (but those defaults will work fine
for trying it out locally.) The certificates will be placed in out
in the
directory you run the command from.
Afterwards, reference these files like so:
converge server --cert-file out/127.0.0.1.crt \
--key-file out/127.0.0.1.crt \
--ca-file out/your-company.crt \
--use-ssl \
--rpc-token your-token
You’ll also need to pass the --ca-file
flag to commands like plan
and
apply
, in order to trust your new CA (or put it in the system roots.)
APIs
Using the Converge command-line interface is good enough for most cases. If you want to integrate Converge into your system in novel ways, however, an API is available.
Authentication
Authentication happens with JSON Web Tokens. The only
currently supported algorithm is HS512, and issued tokens must have a 30 second
expiration. Tokens are set using the --rpc-token
configuration flag to all subcommands that use the API.
HTTP/2.0 And gRPC
If you want to create your own client for Converge, you’ll probably want to use
gRPC. You can get instructions for your chosen langauge in
the gRPC docs, and the protobuf file is
rpc/pb/root.proto
in the Converge source. If you’re using Go, the client
implementations in rpc/client.go
are your friends.
When using the RPC interface, the JWT token should be sent in the request
metadata’s authorization
field with the prefix BEARER
.
HTTP/1.1 And JSON
A pseudo-RESTful interface is available to do the same things the gRPC interface can do. See the protobuf file for the most up-to-date endpoints and payload information.
When using the HTTP/1.1 interface, the JWT token should be sent in the
Authorization
header with the prefix BEARER
. You can also set the jwt
querystring var, or send it in the jwt
cookie.
Standalone Server For The Command-Line
The main Converge commands (like plan
and apply
) will take a --local
argument (or set CONVERGE_LOCAL=1
.) This will:
- Start a local RPC server
- Perform the requested action against the RPC server
- Shut down the RPC server
During this process, a port (localhost:47740
) will be opened and RPC will be
running on it. This interface will be protected with an randomly-generated
token, unless you specify --no-token
Don't Disable Tokens
Please don’t disable token generation with --no-token
. I know we just said you
can, but don’t do it. This will open up remote execution of arbitrary
instructions to whoever can reach that port. You can make this process more
secure by specifying --cert-file
, --key-file
, and optionally --ca-file
to
connect over HTTPS.
Address
Converge has been assigned port 4774 by the Internet Assigned Numbers Authority.