From 65045dc4d65a99b43b985773c01e6ab25df789d1 Mon Sep 17 00:00:00 2001 From: oleksiidn Date: Wed, 24 May 2023 12:36:55 +0300 Subject: [PATCH 1/4] Requirements for building blocks --- docs/SUMMARY.md | 4 ++++ docs/requirements-to-bbs.md | 14 ++++++++++++++ 2 files changed, 18 insertions(+) create mode 100644 docs/SUMMARY.md create mode 100644 docs/requirements-to-bbs.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 0000000..4a5998a --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,4 @@ +# Table of contents + +* [Sandbox](README.md) +* [Requirements for building blocks](requirements-to-bbs.md) \ No newline at end of file diff --git a/docs/requirements-to-bbs.md b/docs/requirements-to-bbs.md new file mode 100644 index 0000000..8a18e3c --- /dev/null +++ b/docs/requirements-to-bbs.md @@ -0,0 +1,14 @@ +# Sandbox requirements for building blocks +[Sandbox infrastructure](https://github.com/GovStackWorkingGroup/sandbox-infra) base on [Kubernetes](https://kubernetes.io/). + +## Requirements to building block + +* Package as OCI (Docker) container. +* Designed to operate in a cloud environment. +* Dependencies should be open-source and refrain from soliciting monetary compensation. + +## Examples + +* [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 From 50aa4d499b3178008580a25b4720f275beddc152 Mon Sep 17 00:00:00 2001 From: oleksiidn Date: Wed, 24 May 2023 12:50:39 +0300 Subject: [PATCH 2/4] Update requirements for bbs. --- docs/requirements-to-bbs.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/requirements-to-bbs.md b/docs/requirements-to-bbs.md index 8a18e3c..3150479 100644 --- a/docs/requirements-to-bbs.md +++ b/docs/requirements-to-bbs.md @@ -5,7 +5,6 @@ * Package as OCI (Docker) container. * Designed to operate in a cloud environment. -* Dependencies should be open-source and refrain from soliciting monetary compensation. ## Examples From 724b9a53097e3c9815c5842b915b0a3bdfaf3acb Mon Sep 17 00:00:00 2001 From: oleksiidn Date: Mon, 5 Jun 2023 14:59:54 +0300 Subject: [PATCH 3/4] Updates from confluence. --- docs/SUMMARY.md | 2 +- docs/guidelines-for-bbs.md | 57 +++++++++++++++++++++++++++++++++++++ docs/requirements-to-bbs.md | 13 --------- 3 files changed, 58 insertions(+), 14 deletions(-) create mode 100644 docs/guidelines-for-bbs.md delete mode 100644 docs/requirements-to-bbs.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 4a5998a..7601ea6 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -1,4 +1,4 @@ # Table of contents * [Sandbox](README.md) -* [Requirements for building blocks](requirements-to-bbs.md) \ No newline at end of file +* [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..fa0e419 --- /dev/null +++ b/docs/guidelines-for-bbs.md @@ -0,0 +1,57 @@ +# Guidelines for building block Sandbox deployment + +> :notes: 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 diff --git a/docs/requirements-to-bbs.md b/docs/requirements-to-bbs.md deleted file mode 100644 index 3150479..0000000 --- a/docs/requirements-to-bbs.md +++ /dev/null @@ -1,13 +0,0 @@ -# Sandbox requirements for building blocks -[Sandbox infrastructure](https://github.com/GovStackWorkingGroup/sandbox-infra) base on [Kubernetes](https://kubernetes.io/). - -## Requirements to building block - -* Package as OCI (Docker) container. -* Designed to operate in a cloud environment. - -## Examples - -* [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 From 9c1beb4b927f903b14d9a61d0571d37ee66d8a3f Mon Sep 17 00:00:00 2001 From: oleksiidn Date: Mon, 5 Jun 2023 15:07:18 +0300 Subject: [PATCH 4/4] remove markdown emoji --- docs/guidelines-for-bbs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guidelines-for-bbs.md b/docs/guidelines-for-bbs.md index fa0e419..8ba4541 100644 --- a/docs/guidelines-for-bbs.md +++ b/docs/guidelines-for-bbs.md @@ -1,6 +1,6 @@ # Guidelines for building block Sandbox deployment -> :notes: GovStack Sandbox aims to be an **isolated, safe environment simulating** a small governmental +> 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.