Converge comes with a server that can:
applyand stream the results (using gRPC)
- serve modules from a given root
- serve the Converge binary itself, for bootstrapping new systems inside your network
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 188.8.131.52:4774 your.hcl
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
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
apply, in order to trust your new CA (or put it in the system roots.)
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 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
rpc/client.go are your friends.
When using the RPC interface, the JWT token should be sent in the request
authorization field with the prefix
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
querystring var, or send it in the
Standalone Server For The Command-Line
The main Converge commands (like
apply) will take a
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
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
--key-file, and optionally
connect over HTTPS.
Converge has been assigned port 4774 by the Internet Assigned Numbers Authority.