diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 0000000..7601ea6 --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,4 @@ +# Table of contents + +* [Sandbox](README.md) +* [Requirements for building blocks](guidelines-for-bbs.md) \ No newline at end of file diff --git a/docs/guidelines-for-bbs.md b/docs/guidelines-for-bbs.md new file mode 100644 index 0000000..8ba4541 --- /dev/null +++ b/docs/guidelines-for-bbs.md @@ -0,0 +1,57 @@ +# Guidelines for building block Sandbox deployment + +> 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. + +## Examples +These examples are candidate building blocks and work in progress. + +* [Information mediator BB](https://github.com/GovStackWorkingGroup/sandbox-bb-information-mediator) +* [Payment BB](https://github.com/GovStackWorkingGroup/sandbox-bb-payments) +* [Registration BB](https://github.com/GovStackWorkingGroup/sandbox-bb-registration) \ No newline at end of file