Core concepts

This article introduces core concepts behind Geopoiesis without going into the full API or configuration details. The implementation is described in the this article.


Backend represents all the backing services that are required for Geopoiesis to run. Currently the only available backend is AWS and it uses the following backend services:

  • S3 to temporarily store manually reviewed plans and their associated workspaces;

  • DynamoDB to permanently store application data;

  • SSM Parameter Store to store environment variables for individual scopes;

  • CloudWatch for telemetry;

  • CloudWatch Logs to write and store logs for individual runs;

  • KMS to encrypt access credentials, S3 artifacts and write-only environment variables;

A single backend is shared by all scopes in a single Geopoiesis installation. If you want to learn more about the API and configuration details, please jump directly to this section. This article on the other hand covers setting up required AWS resource.


A scope refers to a single Terraform workspace. Most importantly, that's where you define which branch of which repository declares your interface (source), and who should have access to it (identity). Each scope has a unique immutable name and a separate domain.

Identity and source each have their own providers, which are entirely independent. Right now the only provider for both is GitHub, with GitLab coming very soon. It will be possible to store your source on GitLab but use GitHub for authentication and authorization, and the other way around.

Geopoiesis is designed to support an arbitrary number of scopes, and you will likely want to use this feature. Large Terraform repositories are undesirable, because the plan/apply cycle is starting to take longer. With more API calls comes more API throttling and more opportunity for errors. You may also want to individual teams within your organization self-service access to their infrastructure, in which case each can have its own infrastructure repository and its associated scope. Even within one repository, you may want to have multiple scopes. Each of those can represent a different stage of your deployment pipeline and be tied to a different branch.

If you're planning to run multiple scopes for one Geopoiesis installation, you will create a separate CNAME DNS record for each of those.


Giving each scope its own domain allows us to separately control access to it using OAuth2 credentials. Identity is where you set up your OAuth2 application client ID and client secret. These are used to authenticate your used with the provider API. The authorization layer is handled by specifying permissions. These can be granted to individual users identified by their username, or entire teams (groups in GitLab parlance).

Geopoiesis allows two levels of permissions - read-only and read-write. This allows you to maintain transparency by giving read view liberally, while still maintaining tight control over changes to the state of infrastructure managed by the individual scope. Read-only users are allowed to trigger runs, but cannot run arbitrary tasks or change the environment.


Source section of the scope declares where infrastructure definitions are stored. You need to point it to a Git repository and (optionally) its branch. This is where you provide access token providing read access to the repository, and webhook secret allowing Geopoiesis to authorize requests coming from your VCS provider.

On-premises installations like GitHub Enterprise are supported by allowing you to supply a custom VCS provider API endpoint.


Admin interface provides visibility into the current state of your installation. From configuration point of view, admin has its own domain name and identity section, so it's pretty much just a scope without source definition. You can read more about the admin interface here.