Greenhouse API

• 1: Organizations
• 2: PluginDefinitions
• 3: PluginPresets
• 4: Plugins

1 - Organizations

An Organization is the top-level entity within Greenhouse. Each Organization represents a different tenant within Greenhouse and is provided with a dedicated Namespace in the Greenhouse cluster.

Example Organization Spec

apiVersion: greenhouse.sap/v1alpha1
kind: Organization
metadata:
  name: example-organization
spec:
  authentication:
    oidc:
      issuer: https://accounts.example.com
      clientId: example-client-id

Writing an Organization Spec

DisplayName

.spec.displayName is a human-friendly name for the Organization. This field is optional; if not provided, it defaults to the value of metadata.name.

Authentication

OIDC

.spec.authentication.oidc is used to configure how members of the Organization will authenticate to Greenhouse. Greenhouse IDProxy is using Dex to provide the OIDC authentication for multiple Organizations. Each Organization receives their own Dex connector.

The config requires issuer, the URL of the identity provider, and clientIDReference and clientSecretReference, which reference Kubernetes Secrets containing the OIDC client ID and client secret, respectively.

spec:
  authentication:
    oidc:
      issuer: https://accounts.example.com
      clientIdReference:
        name: oidc-client-id-secret
        key: client-id
      clientSecretReference:
        name: oidc-client-secret
        key: client-secret

.authentication.oidc.redirectURI is an optional field to specify a custom redirect URI for OIDC authentication. If not provided, it defaults to the Greenhouse ID Proxy (auth.<greenhouse domain name>).

.authentication.oidc.oauth2ClientRedirectURIs is an optional list of URIs that are added to the Dex connector as allowed redirect URIs for OAuth2 clients.

SCIM

.spec.authentication.scim is used by Greenhouse to retrieve the members of a Team from the Organization’s identity provider. This field is optional; if not provided, Greenhouse will not attempt to sync users via SCIM.

The configuration requires baseURL, the URL of the SCIM endpoint, and authType, which specifies the authentication method to use when connecting to the SCIM endpoint. Supported methods are basic and token.

spec:
  authentication:
    scim:
      baseURL: https://scim.example.com
      authType: token
      bearerToken:
        secret:
          name: scim-bearer-token-secret
          key: bearer-token
      bearerPrefix: Bearer
      bearerHeader: Authorization

.authentication.scim.bearerPrefix is an optional field to specify a custom prefix for the bearer token in the authorization header. If not provided, it defaults to Bearer.

.authentication.scim.bearerHeader is an optional field to specify a custom header name for the bearer token. If not provided, it defaults to Authorization.

MappedOrgAdminIdPGroup

.spec.mappedOrgAdminIdPGroup is an optional field that specifies the name of an identity provider group whose members will be granted Organization Admin privileges within Greenhouse. If this field is not provided, no users will be granted Organization Admin privileges.

Working with Organizations

Role-Based Access Control within the Organization namespace

Greenhouse provisions a set of default Roles and RoleBindings within each Organization’s Namespace to facilitate Role-Based Access Control (RBAC). These roles can be used by the Organization Admins as a starting point to manage access to resources within their Organization.

The following roles are seeded for each Organization:

Next Steps

• Creating an Organization

2 - PluginDefinitions

A PluginDefinition brings either a UI application, a Helm chart deployment, or both, to the Greenhouse platform. The Helm chart for a PluginDefinition can be used to deploy infrastructure components to a Kubernetes cluster managed with Greenhouse. The PluginDefinition provides an opinionated way to configure, integrate and deploy these components with Greenhouse.

Example PluginDefinition Spec

apiVersion: greenhouse.sap/v1alpha1
kind: PluginDefinition
metadata:
  name: alerts
  namespace: example-organization
spec:
  description: The Alerts Plugin consists of both Prometheus Alertmanager and Supernova,
    the holistic alert management UI
  displayName: Alerts
  docMarkDownUrl: https://raw.githubusercontent.com/cloudoperators/greenhouse-extensions/main/alerts/README.md
  helmChart:
    name: alerts
    repository: oci://ghcr.io/cloudoperators/greenhouse-extensions/charts
    version: 4.0.3
  icon: https://raw.githubusercontent.com/cloudoperators/greenhouse-extensions/main/alerts/logo.png
  uiApplication:
    name: supernova
    version: latest
  version: 5.0.3
  weight: 0

Writing a PluginDefinition Spec

.spec.displayName is a human-readable name for the PluginDefinition. This field is optional; if not provided, it defaults to the value of metadata.name. This name is used in the Greenhouse UI to display the PluginDefinition in the Catalog of available PluginDefinitions.

.spec.version specifies the semantic version of the PluginDefinition. This versions the combination of Helm chart, UI application and any options provided in the PluginDefinition. The version should be incremented whenever any of these fields are updated.

.spec.uiApplication is an optional field that specifies the UI application associated with the PluginDefinition. The UI application will be made available in the Greenhouse UI when a Plugin is created from this PluginDefinition.

spec:
  uiApplication:
    name: supernova
    version: latest
  weight: 0
  icon: https://raw.githubusercontent.com/cloudoperators/greenhouse-extensions/main/alerts/logo.png
  docMarkDownUrl: https://raw.githubusercontent.com/cloudoperators/greenhouse-extensions/main/alerts/README.md

The fields weight and icon are optional and are used to customize the appearance of the Plugin in the Greenhouse UI sidebar. The optional field docMarkDownUrl can be used to provide a link to documentation for the PluginDefinition, which will be displayed in the entry of available PluginDefinitions in the Greenhouse UI.

.spec.helmChart is an optional field that specifies the Helm chart that is deployed when creating a Plugin from this PluginDefinition.

spec:
  helmChart:
    name: alerts
    repository: oci://ghcr.io/cloudoperators/greenhouse-extensions/charts
    version: 4.0.3

.spec.options is an optional field that specifies default configuration options for the PluginDefinition. These options will be pre-filled when creating a Plugin from this PluginDefinition, but can be overridden by the user.

spec:
  options:
  - description: Alertmanager API Endpoint URL
    name: endpoint
    required: true
    type: string
  - description: FilterLabels are the labels shown in the filter dropdown, enabling
      users to filter alerts based on specific criteria. The format is a list of strings.
    name: filterLabels
    required: false
    type: list
  - default: false
    description: Install Prometheus Operator CRDs if kube-monitoring has not already
      installed them.
    name: alerts.crds.enabled
    required: false
    type: bool

.required indicates whether the option is mandatory when creating a Plugin from this PluginDefinition. .default contains the default value for the option if the Plugin does not provide a value for it. .type is used to enforce validation of the value. The following types are supported: string, bool, int, list, map and secret.

| ℹ️ The type secret requires a secret reference, disallowing clear-text credentials. Vault/OpenBao references will be allowed with 1211|

Next Steps

• Creating a PluginDefinition
• PluginPreset reference
• Plugin reference

3 - PluginPresets

A PluginPreset is used to configure Plugins for a set of Clusters. This allows administrators to define standard configurations for Clusters in the same environment or with similar requirements. Greenhouse will create Plugins based on the PluginPreset for each Cluster that matches the specified selector.

Example PluginPreset Spec

apiVersion: greenhouse.sap/v1alpha1
kind: PluginPreset
metadata:
  name: perses-preset
  namespace: example-organization
spec:
  clusterOptionOverrides:
    - clusterName: example-cluster
      overrides:
      - name: perses.serviceMonitor.selfMonitor
        value: true
      - name: perses.serviceMonitor.labels
        value:
          plugin: kube-monitoring
  clusterSelector:
    matchExpressions:
    - key: cluster-type
      operator: In
      values:
      - observability
  deletionPolicy: Delete
  plugin:
    optionValues:
    - name: perses.sidecar.enabled
      value: true
    pluginDefinitionRef:
      kind: ClusterPluginDefinition
      name: perses
    releaseName: perses
    releaseNamespace: kube-monitoring

Writing a PluginPreset Spec

.spec.plugin is the template for the Plugins that will be created for each matching Cluster. This field has the same structure as the PluginSpec. Only .spec.clusterName is not allowed in the PluginPreset’s Plugin template, as the Cluster name is determined by the matching Clusters.

spec:
  plugin:
    optionValues:
    - name: perses.sidecar.enabled
      value: true
    pluginDefinitionRef:
      kind: ClusterPluginDefinition
      name: perses
    releaseName: perses
    releaseNamespace: kube-monitoring

.spec.clusterSelector is a required field that specifies the label selector used to list the Clusters for which Plugins will be created based on this PluginPreset.

spec:
  clusterSelector:
    matchExpressions:
    - key: cluster-type
      operator: In
      values:
      - observability

| ⚠️ Changing the clusterSelector may result in the creation or deletion of Plugins for Clusters that start or stop matching the selector. |

.spec.clusterOptionOverrides is an optional field that can be used to provide per-Cluster overrides for the Plugin’s OptionValues. This can be used to customize the configuration of the Plugin for specific Clusters.

spec:
  clusterOptionOverrides:
    - clusterName: example-cluster
      overrides:
      - name: perses.serviceMonitor.selfMonitor
        value: true

.spec.deletionPolicy is an optional field that specifies the behaviour when a PluginPreset is deleted. The possible values are Delete and Retain. If set to Delete (the default), all Plugins created by the PluginPreset will also be deleted when the PluginPreset is deleted. If set to Retain, the Plugins will remain after the PluginPreset is deleted or if the Cluster stops matching the selector.

Next Steps

• Managing Plugins for multiple clusters
• Plugin reference
• PluginDefinition reference

4 - Plugins

A Plugin is an instance of a PluginDefinition and is used to deploy infrastructure components such as observability, compliance or system components to a Kubernetes cluster managed with Greenhouse. A Plugin provides the specific configuration for deploying the Helm chart associated with the referenced PluginDefinition to a specific cluster.

Example Plugin Spec

apiVersion: greenhouse.sap/v1alpha1
kind: Plugin
metadata:
  name: alerts-plugin
  namespace: example-organization
spec:
  clusterName: example-cluster
  displayName: Example Alerts Plugin
  optionValues:
  - name: image.tag
    value: foobar
  pluginDefinitionRef:
    kind: PluginDefinition
    name: alerts
  releaseName: alerts
  releaseNamespace: kube-monitoring

Writing a Plugin Spec

.spec.displayName is an optional human-readable name that is used to display the Plugin in the Greenhouse UI. If not provided, it defaults to the value of metadata.name.

.spec.clusterName is the name of the Cluster resource where the Helm chart associated with the PluginDefinition will be deployed.

.spec.pluginDefinitionRef is the required and immutable reference to a PluginDefinition resource that defines the Helm chart and UI application associated with this Plugin.

spec:
  pluginDefinitionRef:
    kind: PluginDefinition
    name: alerts

.spec.releaseName is the optional and immutable name of the Helm release that will be created when deploying the Plugin to the target cluster. If not provided it defaults to the name of the PluginDefinition’s Helm chart.

.spec.releaseNamespace is the optional and immutable Kubernetes namespace in the target cluster where the Helm release will be deployed. If not provided, it defaults to the name of the Organization.

.spec.optionValues is an optional list of Helm chart values that will be used to customize the deployment of the Helm chart associated with the PluginDefinition. These values are used to set Options required by the PluginDefinition or to override provided default values.

  optionValues:
  - name: image.tag
    value: foobar
  - name: secret
    valueFrom:
      secret:
        name: alerts-secret
        key: secret-key

| ℹ️ A defaulting webhook automatically merges the OptionValues with the defaults set in the PluginDefinition. The defaulting does not update OptionValues when the defaults change and does not remove values when they are removed from the PluginDefinition. |

.spec.waitFor is an optional field that specifies PluginPresets or Plugins which have to be successfully deployed before this Plugin can be deployed. This can be used to express dependencies between Plugins. This can be useful if one Plugin depends on Custom Resource Definitions or other resources created by another Plugin.

spec:
  waitFor:
  - pluginRef:
      pluginPreset: ingress-nginx
  - pluginRef:
      name: cert-manager-example-cluster

| ℹ️ The dependency on a PluginPreset ensures that a Plugin created by this PluginPreset has been deployed to the same cluster. The dependency on a Plugin is fulfilled if the referenced Plugin is deployed to the same cluster. |

Working with Plugins

Choosing the deployment tool

The annotation greenhouse.sap/deployment-tool can be added to a Plugin resource to choose the deployment tool used to deploy the Helm release. Supported values are flux and legacy.

Suspending the Plugin’s reconciliation

The annotation greenhouse.sap/suspend can be added to a Plugin resource to temporarily suspend the reconciliation of the Plugin. This results in no changes on the Plugin or referenced resources being applied until the annotation is removed. This also includes upgrades of the Helm release on the target cluster. This also blocks the deletion of the Plugin resource until the annotation is removed.

Triggering reconciliation of the Plugin’s managed resources

The annotation greenhouse.sap/reconcile can be added to a Plugin resource to trigger a reconciliation of the Plugin and its managed resources. When the Plugin is deployed using FluxCD this annotation is propagated to the Flux HelmRelease resource and triggers a reconciliation of the Helm release on the target cluster. This can be useful to trigger a reconciliation even if no changes were made to the Plugin resource.

Next Steps

• PluginPreset reference
• PluginDefinition reference