Skip to main content

Platforms

Platforms represent the top-level component of the Konfig hierarchy within a Control Plane. A Platform is a logical collection of Domains that are grouped by business need or structure. In practice, Platforms typically align to coarse-grained organizational units such as a product line, value stream, or business unit.

Platform

Along with Domains, Platforms play a critical role in Konfig's security and governance story. They allow us to assign permissions in a way that cascades down to Domains. For example, if we have an Ecommerce Platform, we may have an Ecommerce group we grant basic permissions to at the Platform level, then specific Ecommerce teams may have ownership or elevated access within their respective Domains. We can also specify which cloud services and APIs are available at the Platform level and further restrict them at the Domain level where necessary.

This hierarchy facilitates a powerful way to enforce enterprise standards for a large organization while allowing for a high degree of flexibility and autonomy for a small organization. Basically, it allows for governance when you need it (and autonomy when you don't). This is particularly valuable for organizations with regulatory or compliance requirements, but it's equally valuable for companies wanting to enforce a "golden path"—that is, an opinionated and supported way of building something within your organization. It supports a DevOps model with significantly more standardization, structure, and efficiency.

Small Organizations

A small organization or startup may only require a single Platform to begin with. Don't worry, you can always add more later!

While Platforms are a singular concept in Konfig, in practice they comprise several different resources which are created and managed by the Control Plane:

  • A Platform GCP folder which houses the folders for the Platform's Domains
  • A Platform GitLab group which houses the subgroups for the Platform's Domains
  • A GCP Workload Identity provider and GitLab CI/CD variables which allow GitLab CI/CD pipelines within the Platform group to securely authenticate with the Platform and its Domains without credentials using OpenID Connect
  • GitLab CI/CD variables set on the Platform group to support Workload Identity Federation
  • GitLab SAML group links which map identity provider groups specified on the Platform to GitLab roles

The state of these items, along with the overall status of the Platform, can be viewed in the Konfig UI, as shown below.

Platform Details

Platforms are an organizational construct

Aside from the Platform folder, Platforms do not result in any resources being created in your GCP organization. The Workload Identity provider is created in the Control Plane which is provided as a managed service. Instead, a Platform is more of a virtual and organizational construct allowing you to apply common governance and access management settings which cascade to Domains contained within the Platform. There is no cost associated with them, so how coarse- or fine-grained your Platforms are is entirely up to you and your organization's needs.

Platforms are managed declaratively using YAML definitions. These definitions live in the Control Plane repository and specify metadata and configuration for the Platform. This configuration includes a number of things:

  • Display name of the Platform
  • GitLab parent group in which the Platform's subgroup should be created
  • GCP billing account to associate with the Platform's Resources
  • GCP parent folder in which the Platform's folder should be created
  • Default environments
  • Cloud services to allow/disallow within Domains
  • Cloud services to enable by default if Domains do not specify services
  • Group access management

Create a Platform​

Platforms are created via GitOps. When a Platform YAML definition is committed to the Control Plane's main branch, Konfig creates the Platform and all of its associated resources. This YAML can be created directly or using either the Konfig UI or Konfig CLI.

Below is an example demonstrating how to create a Platform which has default dev, stage, and prod environments, allows several GCP services with default services set, and sets group permissions.

Refer to the Platform spec for the complete set of Platform configurations.

You can create a Platform by applying the YAML definition to the Control Plane repository.

apiVersion: konfig.realkinetic.com/v1alpha8
kind: Platform
metadata:
  name: [PLATFORM ID]
  namespace: konfig-control-plane
  labels:
    konfig.realkinetic.com/control-plane: konfig-control-plane
spec:
  platformName: [PLATFORM DISPLAY NAME]
  gitlab:
    parentGroupId: [PARENT GROUP ID]
  gcp:
    billingAccountId: [BILLING ACCOUNT ID]
    parentFolderId: [PARENT FOLDER ID]
    defaultEnvs:
      - label: dev
      - label: stage
      - label: prod
    services:
      allowed:
        - cloud-run
        - cloud-sql
        - pubsub
        - redis
        - firestore
      defaults:
        - cloud-run
        - cloud-sql
        - pubsub
        - redis
  groups:
    dev:
      - dev@example.com
    maintainer:
      - maintainer@example.com
    owner:
      - owner@example.com

List Platforms​

The available Platforms within a Control Plane can be viewed either with the Konfig UI or Konfig CLI.

  1. Navigate to the homepage of the Konfig UI.
  2. Platforms will be displayed in both the side navigation and in the main viewport.

Platforms

Get Platform Details​

Metadata for a Platform can be retrieved either with the Konfig UI or Konfig CLI.

  1. Navigate to the homepage of the Konfig UI.
  2. Locate the desired Platform in the main viewport and click the status icon.
  3. This will expand a sidebar containing information about the Platform such as links to the Platform in GitLab and GCP as well as its source definition, the Platform status, and the Platform's YAML applied to the Control Plane.

Platform Details

Platform Custom Resource Definition​

NameTypeDescriptionRequired
apiVersionstringkonfig.realkinetic.com/v1alpha8true
kindstringPlatformtrue
metadataobjectRefer to the Kubernetes API documentation for the fields of the metadata field.true
specobject
false
statusobject
false

Platform.spec​

NameTypeDescriptionRequired
gcpobject
true
gitlabobject
true
platformNamestring

Human readable name for the Platform. This must be unique because the GCP Folder and Gitlab Group will have this name. Default's to metadata.name.


true
groupsobject
false

Platform.spec.gcp​

NameTypeDescriptionRequired
billingAccountIdstring

GCP Billing Account to associate with this Platform's resources.


false
defaultEnvs[]object

The set of enviornments to create for Domains that do not specify enviornments.



Default: [map[label:dev] map[label:stage] map[label:prod]]

false
parentFolderIdstring

GCP Folder where this Platform's Folder will be created.


false
servicesobject
false
workloadIdentityobject

Default: map[]

false

Platform.spec.gcp.defaultEnvs[index]​

NameTypeDescriptionRequired
labelenum

Enum: dev, stage, prod

true
namestring
false
namespacestring
false
subnetNamestring

The name of the subnet to associate with this environment by default.


false

Platform.spec.gcp.services​

NameTypeDescriptionRequired
allowed[]enum

The services Domains may enable. This is an upper-bound restrictive set. If it is an empty list (or unset) then any supported service may be enabled at the domain level. Use this only when the Platform needs to restrict services.


false
defaults[]enum

The services that will be enabled for Domains that do not specify a set of services to enable. Domains may disable specific services when needed.



Default: [cloud-run cloud-sql pubsub redis firestore bigquery]

false

Platform.spec.gcp.workloadIdentity​

NameTypeDescriptionRequired
enabledboolean

Enable Workload Identity Federation for this Platform.



Default: true

false

Platform.spec.gitlab​

NameTypeDescriptionRequired
parentGroupIdinteger

The Gitlab Group that the Platform's Gitlab Group will be created in.


true
workloadIdentityProviderVarstring

Gitlab CI Variable where the Workload Identity Federation Provider will be set.



Default: GCP_IDENTITY_PROVIDER

false

Platform.spec.groups​

NameTypeDescriptionRequired
dev[]string

If set, this group will be added to all Domain dev GCP Projects as 'Editor', and 'Viewer' to non-dev Projects. It will be added to the Platform Gitlab Group as developer.


false
maintainer[]string

If set, this group will be added to all Domain dev GCP Projects as 'Editor', and 'Viewer' to non-dev Projects. It will be added to the Platform Gitlab Group as maintainer.


false
owner[]string

If set, this group will be added to the Platform Folder and all Domain GCP Projects as 'Editor'. It will be added to the Platform Gitlab Group as maintainer.


false

Platform.status​

NameTypeDescriptionRequired
gcpobject
false
gitlabobject
false
lastReconciledobject
false
readyboolean
false

Platform.status.gcp​

NameTypeDescriptionRequired
platformFolderIdstring
false
workloadIdentityobject
false

Platform.status.gcp.workloadIdentity​

NameTypeDescriptionRequired
poolstring
false
providerstring
false

Platform.status.gitlab​

NameTypeDescriptionRequired
groupobject
false

Platform.status.gitlab.group​

NameTypeDescriptionRequired
groupIdstring
false
poolVarSetboolean
false
workloadIdentityProviderVarstring
false

Platform.status.lastReconciled​

NameTypeDescriptionRequired
generationinteger
false
timestampstring
false