Basic guidelines for building block Sandbox deployment

Owned by jarkkohyoty
Last updated: Dec 22, 2023
2 min read

GovStack Sandbox aims to be an isolated, safe environment simulating a small governmental e-service system (reference implementation of the GovStack approach). The Sandbox is not intended to be a production environment, and it does not contain sensitive data. It is a demonstration environment to learn and a technical environment to test and develop digital government services.

Two approaches for deployment:

  1. The building block deployment is self-contained and deployed inside the Sandbox (preferred).

  2. The building block implementation provides a gateway component that is deployed inside the Sandbox. The gateway provides s GovStack-compliant API and transparently accesses the externally deployed application (details out of scope of this document, defined case by case).

At the core, the Sandbox deployment environment for building blocks is a basic Kubernetes cluster. Building blocks deployed inside the Sandbox are not directly exposed to the public Internet.

General guidelines

  • Building block applications should be provided as one or more OCI compliant container images (“Docker images”) and packaged using a Helm (version 3) chart that defines the resources required by the application.

    • For example, if the application uses a database, the deployment should define one.

  • The chart should define a minimal, small scale deployment for exploration and development, covering only the essential components and functionality.

  • The deployment should only depend on basic Kubernetes concepts and abstractions (e.g. deployments, pods, config maps, secrets, services, persistent volume claims).

  • The application should be isolated into a Kubernetes namespace. The namespace name should be configurable during the chart install time.

  • An application can not expect control of the cluster, and should not depend on advanced features like custom Kubernetes controllers.

  • The application should not expose any interfaces (e.g. ingresses should be opt-in or disabled).

  • The application should not, in general, require access to external resources in the Internet, but it can use other building blocks deployed in the same Sandbox.

  • Configurable: The deployment should include means for providing initial configuration for the application. For example, the application can provide additional configuration APIs, read configuration provided via a ConfigMap at deployment time, or the configuration can be (partially) baked in to the container images. The exact mechanism is implementation specific, but should be scriptable (not require manual steps or using an UI).

  • Automatic deployment: The deployment should be fully automated so that the deployment can be triggered e.g. from a CI/CD pipeline. Installing the chart with possible additional deployment-time configuration should start the application in a known, working state.

    • Preferably, the deployment should include basic tests that can be used to verify a successful deployment, and it should be possible to integrate the tests to the pipeline.