1. Introduction

ConfigSeeder® provides the capability to manage configuration data centrally. However, in the kubernetes world, the gitops methodology is beginning to gain momentum.

The Git-Connector is a ConfigSeeder that combines these two worlds:

  • Manage your configuration data centralized in ConfigSeeder

  • Let the Git-Connector distribute your configuration data to the git repositories

  • Your devops tools requiring a git repository as single point of truth will work with configuration data managed by ConfigSeeder

The following types of files can be provided to a git repository:

  • Files

    • with static content

    • with templated content

  • ConfiMaps

    • containing key/value pairs

    • containing templates

  • Secrets of type Opaque

    • containing key/value pairs

    • containing a key- or truststore

  • ImagePullSecrets (Secrets of type kubernetes.io/dockerconfigjson)

1.1. Use cases

  1. Periodic synchronization

    • Install the Git-Connector as a cronjob

    • Every some minutes it will synchronize the configuration data stored in ConfigSeeder to the configured git repositories

    • Depending on the configuration (of your connected gitops tools), your tools will either directly execute some actions or wait until you create a tag, merge a branch, …​

  2. Manual synchronization

    • Run the Git-Connector manually / integrated in a pipeline at specific events (e.g. before an application installation)

    • It will synchronize the configuration data stored in ConfigSeeder to the configured git repositories

    • Let your gitops tools execute their actions

2. Quickstart

2.1. Introduction

2.1.1. Content of the quickstart manual

The Git Connector is able to connect ConfigSeeder® to one or many Git repositories and push configuration data to Git. This quickstart guide gives an introduction to the use of the Git Connector.

You will understand, how

  • the Git-Connector can be configured

  • data to be pushed to Git can be defined in ConfigSeeder

This quickstart guide also offers links to more detailed information.

2.1.2. Preconditions

  • ConfigSeeder up and running

  • Git Server up and running (We recommend https://gogs.io/ for testing)

  • Connectivity to the Git Server and ConfigSeeder

  • Licence which supports the use of the Git Connector

2.2. Prepare ConfigSeeder®

2.2.1. Setup configuration groups and api key

  1. Create a Configuration Group git-connector-quickstart (the name of the Configuration Group can be chosen as desired)

    Create _Configuration Group_ Git Connector Quickstart

    When creating the Configuration Group, just enable the filter column Environment and leave the security options on their default values.

  2. Create the two environments TEST and PROD (the name of the Environments can be chosen as desired)

  3. Create an api key with permission to access the Configuration Group git-connector-quickstart and both environments.

    Create API Key

    Copy the generated api key and store it in the file git-connector-apikey.

At the moment, there is not api key of type Git Connector. Just select type Kubernetes Connector.

2.2.2. Setup configuration data

  1. Open the Configuration Group git-connector-quickstart, switch to the Value Assemblies-Tab

  2. Create an assembly of type `ConfigMap: Key/Value (Git):

    ConfigMap Key/Value

  3. Create an assembly of type `Secret: Key/Value (Git):

    Secret Key/Value

2.3. Prepare Git Repository

2.3.1. Create Git Repository

  1. Create the git repository git-connector-quickstart

  2. Create an user git-connector with access permission to the previously created repository

The following assumptions are made in this Quickstart Guide:

2.3.2. Create synchronization configuration

Every Git Repository that will be a target of the Git Connector must hold at least one configseeder-gitsync.yaml. In this example, the two environments TEST and PROD will be synchronized, therefore, two of these configuration files have to be created.

  1. Create the file configseeder-gitsync-test.yaml in the root of the Git Repository with the following content

    configuration-group-keys: [git-connector-quickstart]
environment-key: TEST

  2. Create the file configseeder-gitsync-prod.yaml in the root of the Git Repository with the following content

    configuration-group-keys: [git-connector-quickstart]
environment-key: PROD

2.4. Execute Git Connector

2.4.1. Simple configuration

In this example, the git connector is configured in a very simple way. Goal is to create a json formatted file per Assembly in the Git Repository.

  1. Download the helm chart of the Git Connector from https://configseeder.com/download/

    curl https://download.configseeder.com/helmcharts-release/git-connector/0.9.3+000/configseeder-git-connector-0.9.4+000.tar.gz

  2. Create a git-connector-value.yaml file with the following content:

    gitConnector:
  configseeder:
    url: "https://staging-postgresql-config-seeder.oneo.cloud"

configmap:
  create: true
  content: |-
    connector:
      synchronizations:
      - application: Git Connector Quickstart
        environments: [test,prod]
        git-repository: http://gogs.git-server:3000/gitadmin/git-connector-quickstart
        branch-detection-pattern: ^master$
        configuration-location: configseeder-gitsync-<environment>.yaml
        output-prefix: /configseeder/

secret:
  create: true
  basicAuthRequired: true
  basicAuthUsername: "git-connector"
  basicAuthPassword: "git-connector"

psp:
  create: true

  3. Install the Git Connector

    kubectl create ns git-connector-quickstart --dry-run=client -o yaml | kubectl apply -f -
kubectl -n git-connector-quickstart create secret generic "git-connector-apikey"  --from-file=apiKey=git-connector-apikey --dry-run=client -o yaml | kubectl -n git-connector-quickstart apply -f -
helm -n git-connector-quickstart upgrade -i "git-connector" configseeder-git-connector-0.9.4+000.tar.gz --values git-connector-helm-value.yaml

When the Git-Connector has run for the first time, the following files will have been created in the Git Repository:

  • configseeder/configmap-prod.json

  • configseeder/configmap-test.json

  • configseeder/secret-prod.json

  • configseeder/secret-test.json

For example file TODO will have the following content:

{
  "kind": "Secret",
  "apiVersion": "v1",
  "metadata": {
    "name": "secret",
    "namespace": "application-prod",
    "creationTimestamp": null,
    "annotations": {
      "configseeder.com/dataHash": "72fcef6049eece721c76c329f01e674c32f026de56246074e0b0baac68353241",
      "configseeder.com/managed": "true",
      "configseeder.com/module": "SecretKeyValueFileModule"
    }
  },
  "stringData": {
    "DOWNSTREAM_SYSTEM_APIKEY": "api-key-for-prod"
  },
  "type": "Opaque"
}

2.4.2. Adding a pre- and postfix to generated files

In this example, some files created by the Git Connector require a specific pre- and postfix (e.g. because they will be processed by Helm and should only be used if a given namespace matches).

This example builds on the previous example. It is expected that the namespace etc is already set up.

  1. Adapt the git-connector-value.yaml file / add the following default-file-modifications:

      ...
  content: |-
    connector:
      default-file-modifications:
        K8S_ALL:
          prefix: '{{- if eq .Release.Namespace "assembly.metadata.namespace" }}'
          postfix: '{{- end }}'

      synchronizations:
  ...

  2. Delete the files previously created by the Git Connector

    (A prefix and postfix is not calculated into the hashcode of kubernetes object. Therefore, adding or changing a prefix and postfix doesn’t always lead to recreation of a file.)

  3. Update the Git Connector

    helm -n git-connector-quickstart upgrade -i "git-connector" configseeder-git-connector-0.9.4+000.tar.gz --values git-connector-helm-value.yaml

After the Git-Connector has run, the same files as before will be created. However, the files will have the following content:

{{- if eq .Release.Namespace "application-prod" }}
{
  "kind": "Secret",
  "apiVersion": "v1",
  ...
}
{{- end }}

2.4.3. Convert Kubernetes Secrets to Sealed Secrets

In this example, the secrets should be converted to sealed secrets.

This example requires that the certificates used by sealed secrets are either injected in the pod or can be downloaded from an external location. (We recommend to retrieve the certificates from an external rotation. In this scenario, rotating the certificates used for encryption can easily be achieved.)

This example builds on the previous example. It is expected that the namespace etc is already set up.

  1. Adapt the git-connector-value.yaml file / add the following default-file-modifications:

      ...
  content: |-
    connector:
      sealedsecret:
        active: true
        certificates:
          test: http://gogs.git-server:3000/gitadmin/sealed-secret-certificates/src/master/sealed-secret-test.crt
          prod: http://gogs.git-server:3000/gitadmin/sealed-secret-certificates/src/master/sealed-secret-prod.crt
    ...
secret
  ...
  remoteCertificateCredentialsRequired: true
  remoteCertificateUsername: "git-connector"
  remoteCertificatePassword: "git-connector"

sealedSecretModule:
  active: true
...

  2. Delete the files previously created by the Git Connector

    (A prefix and postfix is not calculated into the hashcode of kubernetes object. Therefore, adding or changing a prefix and postfix doesn’t always lead to recreation of a file.)

  3. Update the Git Connector

    helm -n git-connector-quickstart upgrade -i "git-connector" configseeder-git-connector-0.9.4+000.tar.gz --values git-connector-helm-value.yaml

After the Git-Connector has run, the same files as before will be created. However, the files will have the following content:

{
  "kind": "SealedSecret",
  "apiVersion": "bitnami.com/v1alpha1",
  "metadata": {
    "name": "secret",
    "namespace": "application-prod",
    "creationTimestamp": null
  },
  "spec": {
    "template": {
      "metadata": {
        "name": "secret",
        "namespace": "application-prod",
        "creationTimestamp": null,
        "annotations": {
          "configseeder.com/dataHash": "72fcef6049eece721c76c329f01e674c32f026de56246074e0b0baac68353241",
          "configseeder.com/managed": "true",
          "configseeder.com/module": "SecretKeyValueFileModule"
        }
      },
      "type": "Opaque",
      "data": null
    },
    "encryptedData": {
      "DOWNSTREAM_SYSTEM_APIKEY": "AgB84JjwteROvUKTfrp8ZfLBiQotPYM84Pjm6tPUClBZS2f/5ZSU+lcAZO0id9GpaA5aio2CBrHNWfSqoVTyYf7pCyRjIYTCvkutsQTlcMlMgQ2L5D7SyPU1EU7dAbk3JmRH/LOrZxJFRQzarbWKZuEuN2CmEq3wuBDvSOniL60ZCyMNOCzZ1pO3I5bN0T7iYZGgRVvL45MT0tGzTi7BTWYdSs/x57E4ChPxvJrI6EtjTuSbWNWJZRV+meRCyxnHBKx1XKfu/jHohg5YbFB4lrGMn16klKmUWijSmQHSv5WN/PW8XaT9qZ69Fyp8UzTS1Y2KdoVIiei/IBrk7NpOamZPC2PoZklQeOP+PtLMODtoZs0xsGYfhSs6ndtim3pmC6JeHCGvaXzx5i2aaNsFFUw7xyu4Y3NqhS0aEj2NoB7XTKDDfFEb6jzdB26XVQFGSjb/oIlIlhXrEt0bS9uj5MQiQqAJmIMhAG8Sg16wg87pjh7msEXJi+khUuvBxKGgC2RWfgkW1Bedc2HefbuhnAOveBeHZ2e1UmulmI77UgKGiWmbN5BGUKWaBjgcg9X0DhpCO15pnPWX2drS9iqtdJC1RgkQ/DsLcRAVR+Nkh3SDmDehPO83MmuAghGpij5p4tTU0lQxiiyEcP9tzu5ioIMz42mv9dB/z3E2sxuQ1t82Z5tkkZ6l0jZP333sykDFXvl2oO7LuM6eGhA2dSxCCbVO"
    }
  }
}

In combination with the previous example (prefix and postfix) the generated file looks as follows:

{{- if eq .Release.Namespace "application-prod" }}
{
  "kind": "SealedSecret",
  "apiVersion": "bitnami.com/v1alpha1",
...
}
{{- end }}

3. Configuration Options

3.1. Ways to configure the Connector

This section describes every available configuration option available for Git Connector and it’s modules.

There are three ways to configure the connector:

  1. Configuration by file (lowest priority)

    Default filename is connector.yaml, the connector looks for the file in the directoy it is started from. The filename can be overwritten, see Configuration Options.

    Example:

    connector:
  log:
    level: info
    target: console
  startupRetryWaitTime: 10000
  startupMaxWaitTime: 5000
  configSeeder:
    tenantKey: "default"
    serverUrl: "https://staging-postgres-config-seeder.oneo.cloud"
  synchronizations:
    - application: application1
      environments: [dev,test]
      git-repository: gitRepository1
      branch-detection-pattern: ^development$
      configuration-location: values-<environment>/configseeder-gitsync.yaml
      output-prefix: values-<environment>/

  2. Configuration by environment variables

    Example:

    export CONNECTOR_LOG_LEVEL=DEBUG
export CONNECTOR_CONFIGSEEDER_APIKEY=xxxx
...
git-connector

  3. Configuration by startup parameter (highest priority)

    Example:

    git-connector -connector.log.level=DEBUG -connector.configseeder.apikey=xxx ...

It is possible to mix the different ways to configure the connector. You probably want to configure the connector by file and provide the API Key with an environment variable so it isn’t readable by anyone (You don’t want to provide the API Key as a startup parameter because the values of startup parameters can be retrieved by anyone using ps awx).

Priorities of ways to configure the connector

  • A parameter configured by file can be overwritten by environment variable or startup parameter

  • A parameter configured by environment variable can be overwritten by startup parameter

It is currently not possible to configure the synchronizations by env variable or flag.

3.2. Details

3.2.1. SealedSecret

The Git-Connector can automatically convert secrets to sealed secrets. This behavior can be configured via the following options:

connector:
  ...
  sealedsecret:
    active: true
    ...
  ...
3.2.1.1. Locally available certificates

If the certificates are (from the Git-Connectors point of view) locally available, the creation of sealed secrets can be configured as follows:

connector:
  ...
  sealedSecret:
    active: true
    certificates:
      dev: examples/sealedsecret/test.crt
      test: examples/sealedsecret/test.crt
      prod: examples/sealedsecret/prod.crt
  ...
3.2.1.2. Certificates retrieved from a remote location

If the certificates have to be fetched from a remote location via http(s), the creation of sealed secrets can be configured as follows:

The authentication information (username & password used for basic auth) is optional and must only be provided if anonymous access is not allowed.

connector:
  ...
  sealedsecret:
    active: true
    authentication:
      username: git-connector
      password: git-connector
    certificates:
      dev: https://server:port/path/sealed-secret-certificates/raw/master/test.crt
      test: https://server:port/path/sealed-secret-certificates/raw/master/test.crt
      prod: https://server:port/path/sealed-secret-certificates/raw/master/prod.crt
  ...

3.2.2. Access to git

The git repositories can be accessed over ssh or http(s) protocol. Per Git-Connector, only one protocol can be configured. If you need to synchronize to some git repositories with ssh and some other with http(s), at least two Git-Connectors must be set up (one with ssh, one with http(s)).

3.2.2.1. Authentication with Basic Auth

Basic Auth can be used for the protocols ssh and http(s) and is set up with the following configuration options:

connector:
  ...
  git:
    basic-auth-username: <username>
    basic-auth-password: <password>
  ...
3.2.2.2. Authentication with SSH Keys

Authentication with SSH Keys can only be used when accessing the git repositories with the ssh protocol. The following configuration settings can be used:

connector:
  ...
  git:
    private-key-filename: /path/to/keys/privateKey
    private-key-password: <optional-password-for-the-private-key>
  ...

3.2.3. Adding a prefix and/or postfix to generated files

Normally, it is required that the git connector creates the files as specified in ConfigSeeder. There are cases however, where a prefix and or postfix should be added to all or some of the files created by git connector.

Example: Create a file containing a ConfigMap or other kubernetes object that is directly used by Helm and should only be considered if certain conditions are met:

{{- if eq .Release.Namespace "application-test" }}    <-- added prefix
{
  "kind": "ConfigMap",
  "apiVersion": "v1",
  "metadata": {
    "name": "application",
...
{{- end }}                                           <-- added postfix
3.2.3.1. Define file modification

Prefixes and or postfixes are defined by so-called file modifications. It is possible to define multiple file modifications.

File modifications can impact all assembly types, a group of assembly types or a single assembly type. Examples

  • ALL: This file modification impacts all assembly types if no more specific file modification is defined

  • K8S_ALL: This file modification impacts all assembly types that describe a kubernetes object

  • FILE_ALL: This file modification impacts all assembly types that describe a file

  • GIT_CONFIGMAP_KEY_VALUE: This file modification impacts the assembly type ConfigMap KeyValue for Git

  • If no file modification could be found for an assembly type, the content is used as is / no modification is done

File modification can be placed at different parts in the configuration:

  • file modifications used by all synchronizations

  • file modifications used by a single synchronizations

  • file modifications defined for a single synchronization overwrite globally defined file modifications

  • if no file modification could be found for the synchronization, the globally defined file modifications are used

3.2.3.2. Example

In the following example, the following file modifications would be done:

  • For all synchronizations, the kubernetes objects will be

    • Prefixed with prefix K8S_ALL

    • Postfixed with postfix K8S_ALL

  • KeyValue ConfigMaps for the synchronization for application 1 will be

    • Prefixed with prefix GIT_CONFIGMAP_KEY_VALUE

    • Postfixed with postfix GIT_CONFIGMAP_KEY_VALUE

connector:
  ...
  default-file-modifications:
    K8S_ALL:
      prefix: 'prefix K8S_ALL'
      postfix: 'postfix K8S_ALL'
  ...
  synchronizations:
    - application: application1
      ...
      file-modifications:
        GIT_CONFIGMAP_KEY_VALUE:
          prefix: 'prefix GIT_CONFIGMAP_KEY_VALUE'
          postfix: 'postfix GIT_CONFIGMAP_KEY_VALUE'
3.2.3.3. Variable replacing (Namespace)

In some cases (like the mentioned example with modifying a file to be used by Helm), it is required to replace a variable int the prefix or postfix.

At the moment, the only variable that can be replaced in the prefix and/or postfix is the namespace.

The string assembly.metadata.namespace will be replaced by the effective namespace.

Configure the git connector as follows:

  default-file-modifications:
    K8S_ALL:
      prefix: '{{- if eq .Release.Namespace "assembly.metadata.namespace" }}'
      postfix: '{{- end }}'

Assuming that the namespace is set to application-test in the assembly, the result will look like this:

{{- if eq .Release.Namespace "application-test" }}
...
{{- end }}

3.3. Configuration Options

The Git-Connector can be configured by the following options:

All keys are prefixed with connector.. This prefix is neglected in the table to save space.
Key Mandatory Value

configfile

no

Location and name of the configfile containing the connector configuration.

Defaults to connector.yaml.

configseeder.apiKey

yes

API Key used by Connector to access ConfigSeeder.

The API Key must be of Type OS connector

configseeder.certificateFilename

no

Allows to specify a file containing additional (PEM-formatted) certificates that are used for tls verification when connecting to configseeder. If this configuration option is not set, tls verification is done with the system certificate pool.

configseeder.connectionTimeout

no

Connection Timeout, defaults to 1000 (ms).

configseeder.maxRetries

no

Defines, how many times the connector should try to connect to ConfigSeeder

Defaults to 3.

configseeder.readTimeout

no

Read Timeout, defaults to 2000 (ms).

configseeder.retryWaitTime

no

Time in Milliseconds between failed tries to connect to ConfigSeeder.

Defaults to 500 (ms).

configseeder.serverUrl

yes

URL under which ConfigSeeder can be reached.

configseeder.tenantKey

no

Defaults to Tenant default.

default-file-modifications.[assembly-type-or-group].prefix

no

Prefix that will be added for the assembly type or group of assembly types of all synchronizations.

Globally defined file modifications can be overwritten by file-modifications defined for a single synchronization.

default-file-modifications.[assembly-type-or-group].postfix

no

Postfix that will be added for the assembly type or group of assembly types of all synchronizations.

Globally defined file modifications can be overwritten by file-modifications defined for a single synchronization.

git.basic-auth-password

no

Password if basic auth is required to connect to git (can be used with protocols http(s) as well as with ssh).

Must be used in concert with git.basic-auth-username.

Defaults to no password.

git.basic-auth-username

no

Username if basic auth is required to connect to git (can be used with protocols http(s) as well as with ssh).

Must be used in concert with git.basic-auth-password.

Defaults to no username.

git.private-key-filename

no

Points to the file containing an ssh private key if public key auth is required to connect to git (can only be used with protocol ssh).

Defaults to no filename.

git.private-key-password

no

Optional passwort to unlock an ssh private key.

Must be used in concert with git.private-key-filename.

Defaults to no password.

log.filename

no

Name of the Logfile if logging to a file is configured.

Defaults to os-connector-<YYYY-MM-DD>.log.

log.level

no

ogLevel for the connector, valid levels are: trace, debug, info, warning, error, fatal, panic.

Defaults to info

log.target

no

Target for the connector logging, valid targets are CONSOLE, CONSOLE_AND_FILE and FILE.

Defaults to CONSOLE.

sealedsecret.active

no

Controls if the sealedsecret module is active or not. If set to true, the Git-Connector converts all secrets to sealed secrets using the certificates configured with sealedsecret.certificates.<env>: <certificate-location>.

Defaults to false.

sealedsecret.authentication.password

no

Password used to retrieve a certificate from a remote location (if authentication is required to retrieve certificates).

Must be used in concert with sealedsecret.authentication.username.

Defaults to no password.

sealedsecret.authentication.username

no

Username used to retrieve a certificate from a remote location (if authentication is required to retrieve certificates).

Must be used in concert with sealedsecret.authentication.password.

Defaults to no username.

sealedsecret.certificates.<env>

(yes)

Location of the certificate that should be used to convert secrets to sealed secrets for the environment <env>.

Certificates must be configured if the sealed secret module is active.

Defaults to no certificates.

Examples:

  • locally available certificates: dev: path/to/cert/test.crt

  • certificates from remote location: dev: http(s)://server:port/path/test.crt

startupMaxWaitTime

no

Maximum duration in milliseconds which is waited if there is a problem connecting to the ConfigSeeder at startup time. Not setting startupMaxWaitTime means endless retries

Defaults to endless retries (not default set).

startupRetryWaitTime

no

Duration in milliseconds which is waited between retries if there is a problem connecting to the ConfigSeeder at startup time.

Defaults to 15000 (ms)

synchronizations

yes

A synchronization defines a connection between some ConfigSeeder filter criteria and a Git Repository.

A Git-Connector can synchronize multiple sets of filter criterias to different branches of a git repository or to different git repositories.

synchronizations.[x].application

yes

Defines the application for which a synchronization is set up

synchronizations.[x].environments

yes

Defines the environments for which a synchronization is done

synchronizations.[x].git-repository

yes

Defines the target git repository of a synchronization

synchronizations.[x].branch-detection-pattern

yes

The synchronization is executed for all branches matching this pattern

synchronizations.[x].configuration-location

yes

Defines the location inside the git repository, that holds the ConfigSeeder filter criteria file configseeder-gitsync.yaml

synchronizations.[x].output-prefix

no

The prefix that is added to all filenames before the files are written to the git repository

synchronizations.[x].file-modifications.[assembly-type-or-group].prefix

no

Prefix that will be added for the assembly type or group of assembly types of this synchronization.

file-modifications defined for a single synchronization overwrite globally defined file modifications.

synchronizations.[x].file-modifications.[assembly-type-or-group].postfix

no

Postfix that will be added for the assembly type or group of assembly types of this synchronization.

file-modifications defined for a single synchronization overwrite globally defined file modifications.

The specified keys can be easily translated to environment variable names:

  • Take the specified key

  • Replace . with _

  • Only use UPPERCASE Characters

connector.configseeder.apiKey becomes CONNECTOR_CONFIGSEEDER_APIKEY

3.4. Configuration file configseeder-gitsync.yaml

The configuration file configseeder-gitsync.yaml is stored inside the target git repository and defines, how the Git-Connector should access data stored in the ConfigSeeder.

All keys are prefixed with connector.. This prefix is neglected in the table to save space.
Key Mandatory Value

configuration-group-keys

yes

Configuration groups to read the assemblies from

`context `

yes

Filter criteria context

date-time

yes

Filter criteria date time

environment-key

yes

Filter criteria environment key

version

yes

Filter criteria version

4. Modules

4.1. Introduction

Different modules are responsible for managing different kind of configuration data. The following table gives an overview of the available modules.

Table 1. Git-Connector Modules
Module Assembly Description

File Module

File: Static (Git)

Create and manage files with static content.

File: Template (Git)

Create and manage files with templated content.

ConfigMap Module)

ConfigMap: Key/Value (Git)

Create and manage ConfigMaps containing key / value pairs.

ConfigMap: Template (Git)

Create and manage ConfigMaps where the configuration data is created with templating.

Secret Module)

Secret: ImagePull (Git)

Create and manage Image Pull Secrets

Secret: Key/Value (Git)

Create and manage Secrets containing key / value pairs.

Secret: Keystore (Git)

Create and manage Secrets containing Key-/Truststores based on PEM Certificates and Private Keys

All modules can be configured with different options. The following table shows the configuration options which are valid for all available modules:

Table 2. Common configuration options
Key Mandatory Value

assembly.active

yes

With this flag, an assembly can be activated or deactivated for different scenarios.

To enable an assembly for just environment TEST:

  • Set assembly.active to false

  • Copy assembly.active, set environment to TEST and value to true

To disable an assembly for context Cluster-DEV:

  • Set assembly.active to true

  • Copy assembly.active, set context to Cluster-DEV and value to false

file.name

yes

Name of the file

file.name can have different kind of values:

  • filename.txt if only the filename is specified

  • path/filename.txt if the file should be put in a specific path

Be aware that for every synchronization, an output path prefix can be defined with the output-prefix option. For more details, see output-prefix

The following table shows the configuration options that can be used for all kubernetes objects:

Table 3. Common configuration options for kubernetes objects
Key Mandatory Value

metadata.annotatations.xxx

no

Used to set one or more annotations (replace xxx with name of annotation)

metadata.labels.xxx

no

Used to set one or more label (replace xxx with name of label)

metadata.name

yes

Name of the Kubernetes Object (Secret, ConfigMap) that will be created because of this Value Assembly.

If more than one Environment is used, there could be

  • a name <application-apikey>-test with environment TEST and

  • a name <application-apikey>-prod with environment PROD

However, we recommend having a dedicated namespace for each application and environment.

metadata.namespace

yes

Namespace in which the kubernetes object will be created.

If more than one Environment is used, there could be

  • a namespace <application>-test with environment TEST and

  • a namespace <application>-prod with environment PROD

4.2. Static Files (File Module)

4.2.1. Introduction

This module is responsible for creating configuration files with static content.

Static Files are configured with Value Assemblies of type File: Static (Git)

The content can be defined per filter criteria, for example the environment:

File: Static (git) in ConfigSeeder

4.2.2. Configuration Values within Value Assemblies

Key Mandatory Value

file.static-content

yes

Static content of the file.

If a different file content is required for different environments (or other filter criteria), there could be

  • a file with content Content for Test with environment TEST

  • a file with content Content for Production with environment PROD

4.3. Template Files (File Module)

4.3.1. Introduction

This module is responsible for creating configuration files with a templating mechanism. The configuration values used for templating are stored in one or more referenced configuration groups.

Template Files are configured with Value Assemblies of type File: Template (Git):

ConfigMap: Template) in ConfigSeeder

With the Template looking like this:

ConfigMap: Template in ConfigSeeder

Define the following Configuration Values:

Referenced Values

4.3.2. Configuration Values within Value Assemblies

Key Mandatory Value

file.template

yes

Content/Template of the file. This content isn’t written directly to a VM, but first sent to the templating service of ConfigSeeder. See Supported templating engines.

file.configuration-groups.source

yes

This value specifies which Configuration Groups are used for the templating. Defaults to the Configuration Group in which the Value Assembly is defined.

4.4. ConfigMap: Key/Value (Module ConfigMap)

4.4.1. Introduction

This module is responsible for creating and managing ConfigMaps containing key / value pairs. The ConfigMaps are defined in Value Assemblies of type ConfigMap: Key/Value (Git):

  • The key / value pairs can either be configured

    • directly in the Value Assembly

    • or be contained in a single or multiple referenced configuration groups.

  • Key / value pairs defined directly in the assembly overwrite key / value pairs defined in a referenced configuration group.

ConfigMap: Key/Value in ConfigSeeder

With the configuration group containing the following values:

Referenced Values

Check the preview:

ConfigMap: Key/Value Preview

The example above would create a ConfigMap named keyvalue

  • in the namespace myapplication-test containing the following data:

    • log.level: INFO (on DEV it would be DEBUG)

    • server.port: 8080

    • ssl.key-store.location: keystore-test.jks

  • in the namespace myapplication-prod containing the following data:

    • log.level: INFO

    • server.port: 8080

    • ssl.key-store.location: keystore.jks

The key ssl.key-store.password is marked as secured and is therefore ignored when creating the ConfigMap.

The created kubernetes object will look like this:

kubectl get cm -n myapplication-test keyvalue -o json

{
  "kind": "ConfigMap",
  "apiVersion": "v1",
  "metadata": {
    "name": "keyvalue",
    "namespace": "myapplication-test",
    "annotations": {
      "configseeder.com/dataHash": "f6e0a03c2502663b1acc22fc4926534609ccc37c15706d5664eb550f59209e77",
      "configseeder.com/managed": "true",
      "configseeder.com/module": "CMM_KV"
    }
  },
  "data": {
    "log.level": "8080",
    "server.port": "8080"
    "ssl.key-store.location": "keystore-test.jks"
  }
}

4.4.2. Usage of Configuration Values within Value Assembly

Key Mandatory Value

data.configuration-groups.source

no

Reference to one ore more configuration groups. The ConfigMap created by this module will contain all key / value pairs.

data.configuration-groups.filter-regex

no

If configured, only keys matching the pattern will be included in the ConfigMap.

To include all keys:

  • Don’t use data.configuration-groups.filter-regex

To include all keys with prefix / infix / postfix:

  • Add data.configuration-groups.filter-regex

    • for filtering Prefix: prefix.*

    • for filtering Infix: .*infix.*

    • for filtering Prefix: .*postfix

To include exactly two specified keys:

  • Add data.configuration-groups.filter-regex

  • List required keys: `^(key1

key2)$`

data.entries.xxx

no

When managing a ConfigMap with ConfigSeeder

  • use ConfigMap: Key/Value if you want to create a ConfigMap containing simple key / value pairs to be injected as environment variables.

  • use ConfigMap: Template if you need to inject not just simple environment variables but whole files.

4.5. ConfigMap: Template (Module CMM)

4.5.1. Introduction

This module is responsible for creating and managing ConfigMaps containing key / value pairs. The values are created by templating and normally contain whole files.

The ConfigMap is defined with a Value Assemblies of type ConfigMap: Template (Git). The configuration values used for templating are stored in one or more referenced configuration groups.

Configuration of a ConfigMap: Template Assembly in ConfigSeeder:

ConfigMap: Template) in ConfigSeeder

With the Template looking like this:

ConfigMap: Template in ConfigSeeder

Define the following Configuration Values:

Referenced Values

The example above would create a ConfigMap named template in the namespace myapplication-test (and …​-prod).

The created kubernetes object should look like this:

kubectl get cm -n myapplication-test template -o yaml

apiVersion: v1
data:
  application.yaml: |-
    # Template for application.yaml

    server:
      port: 8080

    ssl:
      keystore:
        location: keystore-test.jks
        password: topsecret_test
    Cancel
kind: ConfigMap
metadata:
  annotations:
    configseeder.com/dataHash: fbc1e5cf39d8209fa29132595dc0da30409af56c4cb45d18642d04a375e77a85
    configseeder.com/managed: "true"
    configseeder.com/module: CMM_TEMPLATE
  name: template
  namespace: myapplication-test

When managing a ConfigMap with ConfigSeeder

  • use ConfigMap: Key/Value if you want to create a ConfigMap containing simple key / value pairs to be injected as environment variables.

  • use ConfigMap: Template if you need to inject not just simple environment variables but whole files.

4.5.2. Usage of Configuration Values within Value Assembly

Key Mandatory Value

data.configuration-groups.source

yes

Reference to one ore more configuration groups. The ConfigMap created by this module will contain all key / value pairs.

data.templates.xxx

no

Entry of the ConfigMap which is created by templating.

  • xxx: Key of the Entry, can be a filename. Example: application.properties

  • Value:

    Content/Template of the entry. This content isn’t written directly to a VM, but first sent to the templating service of ConfigSeeder. See Supported templating engines.

    Example (for the templating engine HANDLEBARS):

    spring:
  profiles.active: {{profiles.active}}

4.6. Secret: ImagePull (Module SMM)

4.6.1. Introduction

This module is responsible for creating and managing ImagePullSecrets.

Image pull secrets are defined with Value Assemblies of type Secret: ImagePull (Git) in ConfigSeeder:

Secret: ImagePull in ConfigSeeder

The example above would create a Secret named credentials-dockerhub

  • for the namespace myapplication-test containing the following data:

    {
  "apiVersion": "v1",
  "kind": "Secret",
  "type": "kubernetes.io/dockerconfigjson"
  "metadata": {
    "name": "credentials-dockerhub",
    "namespace": "myapplication-test",
    "creationTimestamp": null,
    "annotations": {
      "configseeder.com/dataHash": "d1e58006dc117b53a9705931ca738d8b403ced0875738f2e65e0483dff65c9eb",
      "configseeder.com/managed": "true",
      "configseeder.com/module": "SecretImagePullFileModule"
    }
  },
  "data": {
    ".dockerconfigjson": "eyJhdXRocyI..."
  }
}

  • for the namespace myapplication-prod, a similar secret is created.

4.6.2. Usage of Configuration Values within Value Assembly

Key Mandatory Value

docker.password

yes

Password required to log into the docker registry

docker.server

yes

Url to the docker registry, defaults to https://index.docker.io/v2/.

docker.username

yes

Username required to log into the docker registry

docker.email

no

Email address for the person responsible for the account connecting to the docker registry.

4.7. Secret: Key/Value (Module SMM)

4.7.1. Introduction

This module is responsible for creating and managing Secrets containing key / value pairs. The ConfigMaps are defined in Value Assemblies of type Secret: Key/Value (Git):

  • The key / value pairs can either be configured

    • directly in the Value Assembly

    • or be contained in a single or multiple referenced configuration groups.

  • Key / value pairs defined directly in the assembly overwrite key / value pairs defined in a referenced configuration group.

Secret: Key/Value in ConfigSeeder

With the configuration group containing the following values:

Referenced Values

Check the preview:

ConfigMap: Key/Value Preview

The example above would create a Secret named keyvalue

  • in the namespace myapplication-test containing the following data:

    • anotherKey: key-for-test

    • ssl.key-store.password: topsecret_test

  • in the namespace myapplication-prod containing the following data:

    • anotherKey: key-for-prod

    • ssl.key-store.password: topsecret_prod

The other values in the configuration group not marked as secured and are therefore ignored when creating the ConfigMap. This behavior can be overwritten with the Flag data.configuration-groups.include-unprotected.

The created kubernetes object should look like this:

kubectl get secret -n myapplication-test keyvalue -o json

{
  "kind": "Secret",
  "apiVersion": "v1",
  "metadata": {
    "name": "my-application-secret",
    "namespace": "my-application-test",
    "annotations": {
      "configseeder.com/dataHash": "6e2e37c43d6e7cbece978b501a3ee37ab0f9796be0b31280db5b6138efd7588a",
      "configseeder.com/managed": "true",
      "configseeder.com/module": "SMM_KV"
    }
  },
  "data": {
    "anotherKey": "a2V5LWZvci10ZXN0",
    "ssl.key-store.password": "dG9wc2VjcmV0X3Rlc3Q="
  },
  "type": "Opaque"
}

4.7.2. Usage of Configuration Values within Value Assembly

Key Mandatory Value

data.configuration-groups.source

no

Reference to one ore more configuration groups. The Secret created by this module will contain all key / value pairs.

data.configuration-groups.filter-regex

no

If configured, only keys matching the pattern will be included in the Secret.

To include all keys:

  • Don’t use data.configuration-groups.filter-regex

To include all keys with prefix / infix / postfix:

  • Add data.configuration-groups.filter-regex

    • for filtering Prefix: prefix.*

    • for filtering Infix: .*infix.*

    • for filtering Prefix: .*postfix

To include exactly two specified keys:

  • Add data.configuration-groups.filter-regex

  • List required keys: key1|key2

data.entries.xxx

yes

Key-Value Entry which will be contained in the Secret.

Key / Value Pairs defined with this mechanism will always overwrite values retrieved from a referenced configuration group.

data.configuration-groups.include-unprotected

no

Set to true, if unprotected values should be included in the secret.

4.8. Secret: Keystore (Module SMM)

4.8.1. Introduction

This module is responsible for creating PKCS12 files containing only Certificates (Truststore) or also Private Keys (Keystore).

Keystores are configured with Value Assemblies of type Secret: Keystore (Git) in ConfigSeeder:

Secret: Keystore in ConfigSeeder

Add a certificate to your configuration group:

Referenced Values

By hitting the preview Button, the keystore defined the assembly is created on the fly:

Keystore Preview

4.8.2. Configuration Values within Value Assemblies

Key Mandatory Value

keystore.certificates-configuration-groups.source

no

Reference to one or multiple configuration groups containing certificates. All Configuration Values with the type CERTIFICATE will be copied into the key-/truststore by the OS Connector.

  • Referenced Certificates must stored in PEM format

keystore.certificates-configuration-groups.filter-regex

no

Without this attribute, all Certificates contained in the configuration groups referenced by keystore.certificates-configuration-groups.source are copied by the OS Connector into the created key-/truststore.

This attribute enables to filter these certificates.

Examples:

  • certificates\.rootCA: Matches only the certificate with the exact key certificates.rootCA

  • certificates\..*: Matches all certificates with a key starting with certificates.

keystore.password

yes

Password of the Key-/Truststore

Requirements:

  • Length: 6 - 30 characters

  • Must start with [a-zA-Z0-9]

  • Can only contain [a-zA-Z0-9-+$_@#~,.?!%&*]

keystore.type

yes

Type of the Keystore. Supported are

  • JKS

  • PKCS12 (default)

private-keys.xxx.*

The following configuration values have an xxx in their name. xxx specifies the alias of the private key entry and can be changed to another value. If the alias is not required, 1 should be used (this is the default for java keystores) Every private key entry requires at least a key and a certificate. The other configuration options are optional.

private-keys.xxx.encrypted-key-password

no

Password if the private key is stored encrypted in ConfigSeeder®.

It the private key is not stored encrypted, this password will be ignored.

private-keys.1.key

no

PEM encoded Private Key

  • Starts with -----BEGIN RSA PRIVATE KEY-----

  • Ends with -----END RSA PRIVATE KEY-----

private-keys.1.certificate

no

PEM encoded Certificate

  • Mandatory if private-keys.1.key is set.

  • Starts with -----BEGIN CERTIFICATE-----

  • Ends with -----END CERTIFICATE-----

private-keys.1.key-encryption-password

no

Password with which the private key is protected when stored in the key store.

This password can only be set for Keystores with type JKS.

4.9. Supported templating engines

In the current version, the Git Connector supports the following template engines:

Template Engine Description

HANDLEBARS

Templating based on the handlebars templating engine, see https://handlebarsjs.com/

Supports simple variable replacement as well as more complex constructs like if-else conditions or even loops.

SIMPLE

Simple template engine implementation that just replaces variables pre-/postfixed by ${…​}.