Resources

Resources comprise the infrastructure that a Workload depends on, such as databases, caches, queues, storage buckets, etc. They are managed declaratively within the Workload YAML. Konfigurate handles provisioning Resources for a Workload and configuring IAM on the Workload's service account such that it can access its Resources securely and in a least-privilege manner. Resources can be shared between Workloads or Workloads can have exclusive ownership. Resource Templates provide a means to abstract infrastructure configuration from developers and enforce organizational standards.

Supported Resource Types

Konfigurate leverages Config Connector to manage infrastructure resources in GCP. Config Connector supports a broad set of GCP resource types. These Resources will have an API group of cnrm.cloud.google.com. For select GCP resources that are not supported in Config Connector, Konfigurate provides a "shim" to allow the Control Plane to manage them. Konfigurate also provides Composite Resources, which can comprise multiple underlying Resources that are stitched together. These Konfigurate-provided Resource types have an API group of konfig.realkinetic.com.

GCP Resources

Refer to the Config Connector documentation for the complete set of supported GCP resources and their definitions.

Shimmed GCP Resources

These are GCP Resources that are not currently supported in Config Connector but supported through a Konfigurate-provided "shim". This shim allows you to use these Resources the same way you would use Config Connector Resources. It's possible for these Resources to be supported by a future version of Config Connector, in which case shims would no longer be required. Konfigurate-shimmed GCP Resources have an API group of gcp.konfig.realkinetic.com. Below is the list of shimmed GCP Resource types.

Google Cloud Product	Resource Name
Firestore	FirestoreDatabase
Dataflow	DataflowFlexTemplate

Composite Resources

Composite Resources are a way to assemble multiple Resources together in order to build more complex pieces of infrastructure.

Coming Soon

Creating Resources

Resources are created by specifying the Resource in the resources portion of the Workload YAML. An example of this is shown below.

apiVersion: konfig.realkinetic.com/v1alpha8
kind: Workload
metadata:
  name: WORKLOAD_NAME
spec:
  runtime:
    ... # Removed for brevity
  resources:
    - apiVersion: storage.cnrm.cloud.google.com/v1beta1
      kind: StorageBucket
      metadata:
        name: [RESOURCE NAME]

This is called a Resource claim. In this example, we are making a Resource claim for a Cloud Storage bucket. The apiVersion corresponds to either the Config Connector or Konfigurate Resource API (see supported Resource types for more on this). The kind refers to the actual Resource type provided through the apiVersion. Lastly, the metadata specifies a name, which is simply the name to assign the Resource.

Configuration

Resource claims typically have minimal configuration as illustrated in the example above. This is possible because the bulk of Resource configuration is abstracted by Resource Templates. Resource Templates are designed to allow an organization to centrally manage standard Resource configurations, hiding complexity from developers and making it easier to ensure organizational requirements are enforced, such as encryption standards, high availability, or data sovereignty.

Resource Templates can be as rigid or as flexible as an organization desires. A template may specify default values for a Resource while allowing developers to override them. Alternatively, a template may specify default values and prohibit developers from changing them. Often, however, templates are somewhere in the middle—specifying sane defaults for some fields which can be overridden when necessary and enforcing organization requirements for others. A Resource Template is specified by setting the konfig.realkinetic.com/template annotation on the Resource claim. If this is not set, default will be used.

apiVersion: konfig.realkinetic.com/v1alpha8
kind: Workload
metadata:
  name: WORKLOAD_NAME
spec:
  runtime:
    ... # Removed for brevity
  resources:
    - apiVersion: sql.cnrm.cloud.google.com/v1beta1
      kind: SQLInstance
      metadata:
        name: [RESOURCE NAME]
        annotations:
          konfig.realkinetic.com/template: my-template

Resource configuration is set as part of the Resource claim by providing a spec for the corresponding apiVersion and kind. This spec should contain the fields you want to set or override, assuming the Resource Template allows the fields to be set. You will need to refer to the respective Resource definitions to know what the spec for a given Resource type looks like. The example below shows configuring a Cloud Storage bucket by setting a lifecycle rule and enabling object versioning.

apiVersion: konfig.realkinetic.com/v1alpha8
kind: Workload
metadata:
  name: WORKLOAD_NAME
spec:
  runtime:
    ... # Removed for brevity
  resources:
    - apiVersion: storage.cnrm.cloud.google.com/v1beta1
      kind: StorageBucket
      metadata:
        name: [RESOURCE NAME]
      spec:
        lifecycleRule:
          - action:
              type: Delete
            condition:
              age: 7
              withState: ANY
        versioning:
          enabled: true

Ownership

Resources created by one Workload can be used, or leased, by another Workload by creating a Resource claim with the same apiVersion, kind, and name and then adding the konfig.realkinetic.com/ownership_role annotation and setting it to user. The default value for this annotation is owner. When setting the ownership role annotation, the spec field of the Resource claim is ignored and the Workload will wait for the Resource to exist and be healthy prior to continuing its own rollout.

apiVersion: konfig.realkinetic.com/v1alpha8
kind: Workload
metadata:
  name: WORKLOAD_NAME
spec:
  runtime:
    ... # Removed for brevity
  resources:
    - apiVersion: storage.cnrm.cloud.google.com/v1beta1
      kind: StorageBucket
      metadata:
        name: [RESOURCE NAME]
        annotations:
          konfig.realkinetic.com/ownership_role: user  # owner (default) | user

Changing Ownership

Changing ownership of a Resource from one Workload to another can be done by simply copying over the Resource claim definition from the owner Workload into the receiving Workload definition and deploying. Once deployed, remove or change the ownership role annotation on the original owner Workload.

warning

Maintaining two or more owners of the same Resource may result in conflict and can cause unexpected behavior. It is best practice to maintain a single owner of a given Resource to avoid unintended configuration changes on the Resource.

Access Management

Konfigurate grants a Workload access to a Resource by binding the Workload's service account to a predefined GCP IAM role. The default role the Workload's service account is given is based on the Resource Template definition. However, that role can be overridden on the Resource itself using the konfig.realkinetic.com/access_role annotation. This role is Resource- and use case- specific. A role will have the form roles/storage.objectAdmin where roles is constant, storage is the GCP API, and objectAdmin is the role itself. See here for the complete list of GCP IAM roles.

Project-Level Roles

In cases where the lowest level you can grant the role is the project, like roles/datastore.owner, you must specify the level in the declaration by prefixing the role with project:. See example below.

apiVersion: konfig.realkinetic.com/v1alpha8
kind: Workload
metadata:
  name: WORKLOAD_NAME
spec:
  runtime:
    ... # Removed for brevity
  resources:
    - apiVersion: storage.cnrm.cloud.google.com/v1beta1
      kind: StorageBucket
      metadata:
        name: [RESOURCE NAME]
        annotations:
          konfig.realkinetic.com/access_role: roles/storage.objectAdmin
    - apiVersion: gcp.konfig.realkinetic.com/v1alpha8
      kind: FirestoreDatabase
      metadata:
        name: [RESOURCE NAME]
        annotations:
          konfig.realkinetic.com/access_role: project:roles/datastore.owner