Control Plane

The Control Plane is the top level in the Konfig hierarchy. It orchestrates and manages everything within Konfig, including Platforms, Domains, Workloads, and infrastructure resources. The Control Plane constantly reconciles the desired state, as specified in YAML configurations, with the actual state of the world and corrects any drift. This works by building on top of and extending GCP's Config Connector, which is an open source Kubernetes add-on that lets you manage Google Cloud resources through Kubernetes.

The Control Plane is provided to customers as a dedicated managed SaaS which securely connects to a customer's cloud environment and GitLab. The Control Plane is driven purely through GitOps by committing YAML definitions to the Control Plane repository. Read-only interactions, such as viewing information about Platforms, Domains, or Workloads, can be done using either the Konfig UI or Konfig CLI.

Control Plane Repository

All operations that mutate a control plane, such as creating Platforms, Domains, Workloads, or resources, are done via GitOps. When a control plane is created, it sets up a group in GitLab which initially contains a single repository called "konfig-control-plane". This repository contains the YAML definitions for your Platforms and Domains. It's automatically configured with a CI/CD pipeline that applies these definitions to the control plane.

GitOps and Platform as Code

GitOps is a DevOps practice that uses Git as the single source of truth for infrastructure and application deployment, allowing teams to manage and automate system configurations and updates through merge requests and version control. By leveraging Git, it ensures consistency, transparency, and traceability across the entire deployment process.

Konfig leverages this not just for Workloads, but for everything, including Platforms and Domains. This allows you to apply the same SDLC you use for application code to your entire platform. This model is something we call "Platform as Code".

Security Model

Because the Control Plane is responsible for managing resources in both GCP and GitLab, it's important to discuss the Control Plane's security model.

For GCP, Konfig does not rely on any keys, credentials, or secrets. Instead, it leverages service accounts to perform operations in GCP, both within the control plane and within customer environments. These service accounts do not have keys associated with them. In fact, we encourage customers disable service account key creation. Service accounts are managed in a fine-grained manner to minimize blast radius. Similarly, GitLab CI/CD pipelines do not rely on any keys to authenticate with the Control Plane. Rather, they leverage Workload Identity Federation which relies on OpenID Connect to securely authenticate with GCP using on-demand, short-lived credentials that do not require any stored secrets.

For GitLab, the Control Plane leverages a group access token with API access that is scoped to the Control Plane group. This token can be rotated regularly and on demand.

The diagram below shows a high-level illustration of the Control Plane model and interactions.

GCP

Access within GCP is compartmentalized to minimize risk, both within the Konfig GCP organization (referred to as the Konfig Tenant GCP Organization) and the customer GCP organization. The Control Plane itself is also compartmentalized into different controllers which handle different responsibilities. Below we describe in detail Konfig's security model as it relates to GCP.

Platform Service Account

Customer-owned and managed

The Platform Service Account can be disabled by the customer to revoke Konfig's access to create and manage Platforms and Domains.

The Control Plane does not have full access to the customer GCP organization. Instead, its access is scoped to a customer-specified folder within GCP in which they want Konfig to operate within (this is referred to as the Control Plane Folder). This is managed by the Platform Controller which uses a service account that has the following IAM roles granted on it for the Control Plane folder:

• Compute Shared VPC Admin: Allows the Control Plane to manage VPCs used by Platforms, Domains, and Workloads.
• Folder Admin: Allows the Control Plane to create and manage folders for Platforms and Domains.
• Folder IAM Admin: Allows the Control Plane to manage access to Platform and Domain folders.
• Project Creator: Allows the Control Plane to create Environment projects within a Domain folder.

This service account is called the Platform Service Account. Because these roles are granted only on the Control Plane Folder, Platform Controller cannot manage these resources outside of this folder. Platform Controller is responsible for managing Platforms and Domains (but not the resources contained within Domains such as Workloads). That is to say, it only controls foundational components like folders and projects in the Control Plane Folder within GCP.

The Platform Service Account is owned and managed by the customer. This allows the customer to revoke Platform Controller's ability to create and manage Platforms and Domains at any time.

Platform CI/CD Service Account

Konfig-owned and managed

The Platform CI/CD Service Account allows the customer's GitLab Control Plane repository to authenticate with the Konfig Control Plane. It has no access to the customer GCP environment.

The Control Plane repository in GitLab authenticates with the Control Plane using Workload Identity Federation. This works by allowing the repository's CI/CD pipeline to assume another service account called the Platform CI/CD Service Account. This service account is owned and managed by Konfig and is scoped to a customer's Control Plane. It has a very narrow set of permissions which only allow the Control Plane repository to apply Platform and Domain definitions to the Control Plane. These definitions are then acted upon by the Platform Controller. This service account has no permissions or access to the customer GCP organization.

Domain CI/CD Service Accounts

Konfig-owned and managed

The Domain CI/CD Service Accounts allow the customer's GitLab Workload repositories to authenticate with the Konfig Control Plane and push container images to Artifact Registry repositories in the customer GCP Domain projects.

When Platform Controller creates a new Domain, it creates a GCP folder within the Platform's folder to house the Domain's projects. Within this Domain folder, it also creates a project per Environment. These resources live within the customer GCP organization, in particular, within the Control Plane Folder. Domain-Environment projects have Artifact Registry enabled to store Workload container images.

The Control Plane is segmented into namespaces based on Domain-Environment pairs. Namespaces are a virtual isolation mechanism which allow Konfig to further compartmentalize the Control Plane such that access boundaries can be enforced around Domains and Environments. For example, if we have two Domains, Fulfillment and Payment, we can ensure that the Fulfillment team cannot mutate the Payment Domain and vice versa.

This is done by creating a service account for each Domain used by Workload repositories in GitLab. These service accounts are called the Domain CI/CD Service Accounts. Like the Platform CI/CD Service Account, these service accounts have limited permissions to only allow them to apply Workload definitions to to their respective Domain namespaces in the Control Plane. These definitions are acted upon by another controller called the Workload Controller, which runs in each Domain-Environment namespace (e.g. fulfillment-dev, fulfillment-stage, and fulfillment-prod). For the customer GCP organization, Domain CI/CD Service Accounts only have the Artifact Registry Create-on-Push Writer role on each Domain-Environment project to allow CI/CD pipelines to push Workload container images.

Domain CI/CD Service Accounts are owned and managed by Konfig and are scoped to Domain namespaces within a customer's Control Plane.

Domain-Environment Service Accounts

Konfig-owned and managed

Domain-Environment Service Accounts allow Konfig to manage Workloads and resources in customer Domain-Environment projects. These are currently owned and managed by Konfig, but in the future will be managed by Konfig but owned by the customer. In combination with the Platform Service Account, this will allow customers to fully revoke Konfig's access to their GCP organization.

Each Domain-Environment namespace in the Control Plane contains a Workload Controller. The Workload Controller is responsible for managing Workloads and their infrastructure resources in the customer GCP organization for the respective Domain-Environment combination. Recall that in the customer GCP organization is a Control Plane Folder that Konfig operates within, and within the Control Plane Folder is a folder for each Platform. Inside each Platform folder is a folder for each of the Platform's Domains which then contain a project for each of the Domain's Environments. An example of this hierarchy in GCP is shown below.

Konfig manages a service account for each Domain-Environment namespace which allows it to scope access to the specific Environment project in the customer GCP organization. These are called the Domain-Environment Service Accounts. By segmenting these by Environment, we can further reduce risk by ensuring cross-environment misconfigurations are prevented.

These service accounts have IAM roles which enable them to create GCP resources on behalf of a customer. In Konfig, Workloads are assigned their own service account such that access can be configured for only the resources they require. This means the Domain-Environment Service Accounts also need the ability to create Workload service accounts. The exact set of IAM roles granted on the Domain-Environment projects for these service accounts can vary based on which services are enabled, but a non-exhaustive list of roles is the following:

• Logs Writer: Allows Workload Controller to emit logs to Cloud Logging.
• Service Account Admin: Allows Workload Controller to create Workload service accounts.
• Project IAM Admin: Allows Workload Controller to manage IAM permissions on Workload service accounts.
• Service Account User: Allows Workload Controller to attach service accounts to Workloads.
• Artifact Registry Administrator: Allows Workload Controller to create and manage Workload repositories and artifacts.
• Cloud Datastore Owner: Allows Workload Controller to create and manage Cloud Datastore and Firestore databases.
• Cloud Memorystore Redis Admin: Allows Workload Controller to create and manage Cloud Memorystore Redis instances.
• Cloud Run Admin: Allows Workload Controller to create and manage Cloud Run services.
• Cloud SQL Admin: Allows Workload Controller to create and manage Cloud SQL databases.
• Compute Load Balancer Admin: Allows Workload Controller to create and manage load balancers.
• Dataflow Admin: Allows Workload Controller to create and manage Cloud Dataflow resources.
• Pub/Sub Admin: Allows Workload Controller to create and manage Cloud Pub/Sub topics and subscriptions.
• Secret Manager Admin: Allows Workload Controller to create and manage secrets.
• Storage Admin: Allows Workload Controller to create and manage Cloud Storage buckets.

Domain-Environment Service Accounts are owned and managed by Konfig and are scoped to the specific Domain-Environment namespace within a customer's Control Plane.

GitLab

Customer-owned and managed

The CI/CD Token can be disabled by the customer to revoke Konfig's access to the customer's GitLab.

Both Platform Controller and the Konfig UI interact with the customer's GitLab. Platform Controller creates Platform and Domain subgroups, SAML group links, and group CI/CD variables. The Konfig UI creates merge requests as well as various read-only operations on Konfig repositories. Platform Controller and Konfig UI rely on a group access token, called the CI/CD Token, which is scoped to the Control Plane group. This token requires api scope with Owner role. Group access tokens have an expiration that is configured by the customer. Konfig allows this token to be rotated regularly or on demand.

The GitLab token is the only secret Konfig uses. At this time, GitLab does not support an OpenID Connect solution which would allow the Control Plane to authenticate with GitLab without the use of a token. This token is stored as an encrypted value in the Control Plane and is not accessible by anything outside of the Control Plane itself.