Building containerized RESTful microservices from scratch

Here at Open Data Group, we’re big proponents of delivering
software and models as containerized microservices. In fact,
it’s a core part of our value proposition! Because we find ourselves
doing this a lot, our team has standardized around a
systematic approach using existing tooling to allow us to
rapidly prototype and develop production-grade containerized
applications. In this blog post, I’ll talk about three parts
to this approach, specifically focusing on applications
implemented in Go.

Why Go?

In this post, I’m going to specifically focus on the most
common subset of containerized microservices: lightweight,
restricted-functionality webservers implementing a RESTful
API. From Python to
Erlang, just about
every language has a great framework for easily building out
a server. Go, however, has a couple of features that make it
a particularly appealing choice of language for a
production-grade containerized microservice:

• A very strong standard library as well as a rich ecosystem
  of community packages
• Highly performant, simple to use concurrency abstractions
• The ability to easily generate statically linked binaries

The last point is especially valuable when targeting Docker
as the code deployment mechanism.

A Step-By-Step guide to building a RESTful microservice

In contrast to some traditional development patterns,
when building out a RESTful microservice at Open Data Group,
we like to take an “outside in” approach. By this I mean that
we start by designing the REST API of the service we’re
building, then generate a server stub, and finally start
filling out the “inside” (i.e. implementing the underlying
functionality). There’s two reasons for this approach:

1. Most RESTful microservices do not exist in isolation:
   by beginning with an interface definition, development
   of and integration with other components can be done in parallel. And, because
   the server stub can be rapidly generated from that
   interface definition, we can naturally apply a test-driven
   development methodology to guide and check the ultimate
   implementation of the underlying functionality.
2. In general, interfaces tend to be longer-lived than
   the innards of the service: other services or client
   applications may depend on functionality defined in
   that particular interface, so by starting with the
   interface design we ensure that we’re focusing our
   attention first on what is generally the most critical
   part of the application.

Additionally, we leverage a standard, language-neutral
format for defining our API specifications: OpenAPI (formerly known as Swagger).
OpenAPI is designed and guided by Swagger,
who also publishes a number of tools for working with these API
specs.
The OpenAPI
specification is sufficiently general to capture most of the
functionality we’ve ever been interested in implementing. In
my experience, it is particularly well-suited to describing
API calls where the request or response are encoded as JSON
objects; it can be a little more cumbersome for edge cases
where the request encoding doesn’t map to JSON or YAML.

Here’s an example OpenAPI specification for a very simple
microservice (stolen from [one of our tutorials](/Knowledge Center/Tutorials/A Simple Microservice/)):

swagger: "2.0"
info:
    description: "An example FastScore microservice."
    version: "0.1"
    title: "My FastScore Microservice"

paths:
    /:
        get:
            produces:
                - text/html
            operationId: get_index
            responses:
                200:
                    description: Returns the Dashboard homepage.
                    schema: { type: string }
    /{engine}/model:
        get:
            parameters:
                - name: engine
                  description: The name of the engine instance
                  type: string
                  in: path
                  required: true
            produces:
                - application/json
            operationId: get_model
            responses:
                200:
                    description: Returns a description of the currently running model.
                    schema: { type: object }

Generating a server stub

Swagger provides a number of tools for working with OpenAPI
specifications, including one called swagger-codegen, which
can take in an API specification and generate client and
server stubs. However, the official swagger-codegen has a few issues
with its Go support, so instead we use
the Go package go-swagger.

To generate a server stub with go-swagger, just run

swagger generate server -f api.yaml

This will spit out a few different directories:

• cmd, whose subdirectory contains the main entrypoint
• models, which contains definitions for all of the types
  used in your API
• restapi, which contains the actual API implementation.

For convenience, let’s assume that the name of our microservice
is myservice. Of these, at a minimum the two files we need to
edit are main.go, located in cmd/myservice-server, and
configure_myservice.go, located in restapi.

The latter of these files we need to edit to implement the actual
functionality of our service. This consists of filling out the various
API functions defined in this file (the functions named api.NameOfOperation)
and replacing the middleware.NotImplemented(...) return values to appropriate
returns for the outcomes of the functions. A typical “filled out” API function
will look something like:

api.NameOfOperation = operations.NameOfOperationFunc(func(params operations.NameOfOperationParams) middleware.Responder {

    result := DoSomething(params.Parameter1, params.Parameter2)

    return operations.NewNameOfOperationOK().WithPayload(result)
})

where NameOfOperation is the name of the operation defined in the OpenAPI spec,
Parameter1 and Parameter2 are two of the defined inputs for that function,
result is an appropriate response for this API call, and DoSomething is
the actual “under the hood” function that should be called.

Once this is done, you can build and run your server by navigating to the
cmd/myservice-server directory and running go install, and then running
(for example)

./myservice-server --tls-host=0.0.0.0 --tls-port=8080 --tls-key=keys/key.key --tls-certificate=keys/crt.crt

If all goes well, you’ll see a log message that you’re now serving
your API at port 8080 on your local machine, and you should be able to
connect to it from other machines.

Building a container from scratch

The astute reader will notice that I haven’t described what should be modified
in main.go, nor have I taken advantage of Go’s functionality around statically
linked binaries. Here’s where both of these parts come in. But first, a slight
digression about Docker containers.

Most Docker images use a particular Linux distribution as their base. Among the
most common choices are Ubuntu and Alpine (Ubuntu because it’s easy to add other
dependencies in subsequent layers, and Alpine because it’s much smaller than
most other Linux flavors). So, if you’re interested in getting the smallest
container image possible, your Dockerfile should start with FROM alpine, right?

Wrong! We can do better. There’s a special, completely empty base layer we can
use in Docker called scratch. The advantage of using scratch as a base layer
is that we have complete control over what goes into the container image, which
is especially important for minimizing image sizes and satisfying security
requirements. Note that scratch behaves somewhat differently
from other base layers:

• There’s no tty or terminal or anything that a user can attach to, so you can’t
  get “into” the container with docker exec
• Key filesystem abstractions are missing, so you generally can’t provide
  command-line arguments to applications you start in the container
• And there are other differences.

One important thing that scratch base layers do still allow is setting
environment variables. With this in mind, there are two steps remaining before
we have our containerized microservice:

1. Change main.go to take arguments via environment variables.
2. Compile a statically linked binary of our server and put it in a
   Dockerfile based on scratch.

The first part is straightforward: just add a few lines to main.go to set
the various arguments the microservice needs. For example, to set the TLS
host via environment variable, after the line

server.ConfigureAPI()

in main.go, add the line

host, exists := os.LookupEnv("HOST")
if exists {
    server.TLSHost = host
} else {
    server.TLSHost = "0.0.0.0" // or whatever the default value should be
}

Putting it all together

Finally, we have to build the statically linked binary and put it
in a Dockerfile. A good practice for repeatable builds is to use
a multi-stage build. This essentially creates an intermediate Docker container
which is used to compile any relevant binaries, and then those assets
are copied over to the final output container. This gives a convenient
and transferable encapsulation of the build environment.

Here’s an example of our typical Dockerfile for building a statically
linked Go server:

FROM golang:1.10.3-alpine3.8

RUN apk add git

COPY . /go/src/github.com/myorg/myservice
WORKDIR /go/src/github.com/myorg/myservice/restapi/

WORKDIR /go/src/github.com/myorg/myservice/cmd/myservice-server

RUN go get
RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix nocgo

FROM scratch

COPY --from=0 /go/src/github.com/myorg/myservice/cmd/myservice-server/myservice-server /myservice-server
COPY keys /keys

ENV PORT 8123
ENV TLS_CERT keys/dummy.crt
ENV TLS_KEY keys/dummy.key
ENV TLS_HOST 0.0.0.0

CMD [ "/myservice-server" ]

To build the image, just run

docker build -t myorg/myservice -f Dockerfile

and then we’re done!

Concluding thoughts

By combining a standardized API specification, stub generation tools, and Go,
it’s really easy and quick to build out lightweight, secure containerized
microservices. This has allowed Open Data Group to very quickly generate,
iterate on, and refine prototypes for new microservices, and keeps us close
to the guiding Docker philosophy of light, ephemeral, and portable application
design. Some additional related topics that I didn’t cover here (but might in
a future post) include how to handle stateful containerized microservices,
equivalent practices for other languages such as Python, and building out
client libraries from an API specification. If you want to learn more
about these topics, Swagger and Docker both have a wealth of resources available. Happy coding!