Server

Converge comes with a server that can:

• run plan and apply 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:

1. Start a local RPC server
2. Perform the requested action against the RPC server
3. 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

Address

Converge has been assigned port 4774 by the Internet Assigned Numbers Authority.