:files

1. Introduction

Nowadays many microservice applications are deployed in the form of containers in a Kubernetes Cluster. There are multiple ways to configure these containers. The configuration can be …

  1. shipped within the image itself

  2. passed on a mounted volume

  3. passed as environment variables

    1. sourced from a configmap

    2. sourced from a secret

  4. retrieved from an external service

If you are using ConfigSeeder to manage your configuration data, you can either fetch the required configuration data with an init-container (Scenario 2, OS Connector or SimpleConfigDownloader) or retrieve it directly with a ConfigSeeder Client (Scenario 4). In either case, an API Key is required to retrieve configuration data from ConfigSeeder.

These API Keys can be managed (created and replaced before expiration) manually or automatically by Kubernetes Connector. The Kubernetes Connector reads Assemblies of type Secret: API Key from ConfigSeeder and manages API Keys within Kubernetes Secrets.

At the moment, the Kubernetes Connector is limited to manage API Keys. Soon (planned for the end of September) the Kubernetes Connector will have the ability to provision configuration data stored in ConfigMaps and Secrets (Scenario 3a/b).

1.1. Use cases

The kubernetes-connector can be used for the following scenarios:

  • Provide API Keys with access to configured Configuration Groups within Secrets.

  • Provide ConfigMaps containing key/value pairs

  • Provide Secrets of type opaque containing key/value pairs

1.2. Online/Offline Mode

The Kubernetes Connector can run in the following modes:

  1. Online Mode (default)

    In the Kubernetes Access Mode Online, the Kubernetes Connector manages Kubernetes Objects directly in the cluster by accessing the Kubernetes Master API (see https://kubernetes.io/docs/tasks/administer-cluster/access-cluster-api/#directly-accessing-the-rest-api)

    Limitations:

    The Kubernetes Connector requires RBAC-permissions to manage the Kubernetes Objects, see Required RBAC Permissions

  2. Offline Mode

    In the Kubernetes Access Mode Offline, the Kubernetes Connector doesn’t access a Kubernetes Cluster via API, but instead creates json-files describing the configured ConfigMaps and Secrets.

    The Offline Mode can be activated via setting the configuration option kubernetesAccessMode to Offline.

    Limitations:

    • In Offline Mode, it isn’t possible to check if an Assembly containes a change or not. A json file is created for every Assembly which is managed by Kubernetes Connector. The Kubernetes API Server is responsible for validating, if a change is required when the json files are applied.

    • Because reading the existing objects is not possible, for Assemblies of type API Key Secret, the Kubernetes Connector will create a new API Key for every run.

    • It is only possible to create new object or modify existing objects. However it is not possible to delete existing objects.

2. Quickstart

2.1. Introduction

2.1.1. Content of the quickstart manual

The kubernetes-connector can to provide ConfigMaps and Secrets to a Kubernetes Cluster. This quickstart guide gives an introduction to the use of the kubernetes-connector.

You will understand, how

  • configuration objects to be deployed to Kubernetes are defined in ConfigSeeder®

  • multiple environments/namespaces are supported

  • labels and annotations can be set

This quickstart guide also offers links to more detailed information.

2.1.2. Preconditions

  • ConfigSeeder up and running

  • Licence which supports the use of the kubernetes-connector

  • Connectivity from the machine or cluster running kubernetes-connector to the ConfigSeeder

  • Access to a Kubernetes cluster and permission to manage kubernetes objects like namespaces, service accounts, secrets and rbac roles & bindings.

2.2. Prepare ConfigSeeder Management

  1. Create the Environments TEST and PROD

  2. Create the Configuration Group kubernetes-connector-quickstart

2.3. Setup Kubernetes Connector

The following actions are required to set up Kubernetes Connector:

  1. Create Namespace in which the Connector should be running.

    ns.yaml
    apiVersion: v1
kind: Namespace
metadata:
  name: cs-demo-k8s-connector

    kubectl apply -f ns.yaml

  2. Create the Serviceaccount with which the Connector will connect to the Kubernetes Master.

    sa.yaml
    apiVersion: v1
kind: ServiceAccount
metadata:
  name: cs-demo-k8s-connector
  namespace: cs-demo-k8s-connector

    kubectl apply -f sa.yaml

  3. Give the ServiceAccount permission to store state-information (in this quickstart guide it is expected that the state will be stored in the same Namespace in which the Kubernetes Connector(s) are running). Also, prepare a ClusterRole with access to the Kubernetes Object Types which will be managed by Kubernetes Connector.

    rbac.yaml
    kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: cs-demo-k8s-connector-state
  namespace: cs-demo-k8s-connector
rules:
  - apiGroups: [""]
    resources: ["configmaps"]
    verbs: ["create", "get", "update", "delete"]
---
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: cs-demo-k8s-connector-state
  namespace: cs-demo-k8s-connector
subjects:
  - kind: ServiceAccount
    name: cs-demo-k8s-connector
    namespace: cs-demo-k8s-connector
roleRef:
  kind: Role
  name: cs-demo-k8s-connector-state
  apiGroup: rbac.authorization.k8s.io
---
kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: cs-demo-k8s-connector
rules:
  - apiGroups: [""]
    resources: ["configmaps", "secrets"]
    verbs: ["create", "get", "patch", "update", "delete"]

    kubectl apply -f rbac.yaml

  4. Create the Namespaces in which the Kubernetes Connector shall manage Kubernetes objects and give the ServiceAccount permission to manage the objects. In this quickstart guide, the namespaces cs-demo-application-test and cs-demo-application-prod are used.

    ns-example.yaml
    apiVersion: v1
kind: Namespace
metadata:
  name: cs-demo-application-test
---
apiVersion: v1
kind: Namespace
metadata:
  name: cs-demo-application-prod
---
apiVersion: v1
kind: Namespace
metadata:
  name: cs-demo-ansible-prod
---
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: cs-demo-k8s-connector
  namespace: cs-demo-application-test
subjects:
  - kind: ServiceAccount
    name: cs-demo-k8s-connector
    namespace: cs-demo-k8s-connector
roleRef:
  kind: ClusterRole
  name: cs-demo-k8s-connector
  apiGroup: rbac.authorization.k8s.io
---
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: cs-demo-k8s-connector
  namespace: cs-demo-application-prod
subjects:
  - kind: ServiceAccount
    name: cs-demo-k8s-connector
    namespace: cs-demo-k8s-connector
roleRef:
  kind: ClusterRole
  name: cs-demo-k8s-connector
  apiGroup: rbac.authorization.k8s.io
---
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: cs-demo-k8s-connector
  namespace: cs-demo-ansible-prod
subjects:
  - kind: ServiceAccount
    name: cs-demo-k8s-connector
    namespace: cs-demo-k8s-connector
roleRef:
  kind: ClusterRole
  name: cs-demo-k8s-connector
  apiGroup: rbac.authorization.k8s.io

    kubectl apply -f ns-example.yaml

  5. Create API Key used by the Kubernetes Connector to access ConfigSeeder:

    1. Create API Key of Type Kubernetes Connector with access to the relevant Configuration Groups and Environments:

      Create API Key in ConfigSeeder

    2. Store generated API Key in file apikey.txt

    3. Create Secret:

      kubectl create secret generic -n cs-demo-k8s-connector cs-demo-k8s-connector-apikey \
        --from-file=apikey=apikey.txt

  6. Store configuration used by Kubernetes Connector in a ConfigMap:

    cs-demo-k8s-connector-config.yaml
    apiVersion: v1
kind: ConfigMap
metadata:
  name: cs-demo-k8s-connector-config
  namespace: cs-demo-k8s-connector
data:
  CONNECTOR_APIKEY_LIFETIMEINDAYS: "2"
  CONNECTOR_APIKEY_RECREATEDAYSBEFOREEXPIRATION: "1"
  CONNECTOR_CONFIGSEEDER_SERVERURL: https://develop.postgresql.configseeder.com
  CONNECTOR_CONFIGSEEDER_TENANTKEY: userdocumentation
  CONNECTOR_CONFIGSEEDER_CONFIGURATIONGROUPKEYS: kubernetes-connector-quickstart
  CONNECTOR_CONFIGSEEDER_CONNECTIONTIMEOUT: "5000"
  CONNECTOR_CONFIGSEEDER_READTIMEOUT: "5000"
  CONNECTOR_LOG_LEVEL: "INFO"
  CONNECTOR_STARTUPRETRYWAITTIME: "10000"
  CONNECTOR_STATEMANAGER_NAMESPACE: "cs-demo-k8s-connector"

    Be sure to set the following options to the correct values:

    CONNECTOR_CONFIGSEEDER_SERVERURL
CONNECTOR_CONFIGSEEDER_TENANTKEY
CONNECTOR_CONFIGSEEDER_CONFIGURATIONGROUPKEYS

    kubectl apply -f cs-demo-k8s-connector-config.yaml

2.4. Execute the Kubernetes Connector

2.4.1. Periodically execute Kubernetes Connector with a CronJob

Starting Kubernetes Connector with a CronJob is usually done if exact timing of a configuration Change is not really relevant and configuration changes should be applied to kubernetes as soon as possible (e.g. for dev or test environments).

  1. Create CronJob Template

    cs-demo-k8s-connector-cronjob-test.yaml
    apiVersion: batch/v1beta1
kind: CronJob
metadata:
  name: cs-demo-k8s-connector-cronjob-test
  namespace: cs-demo-k8s-connector
spec:
  schedule: "*/5 * * * *"
  # Don't execute Job more than once at the same time
  concurrencyPolicy: Forbid
  failedJobsHistoryLimit: 5
  successfulJobsHistoryLimit: 1
  jobTemplate:
    spec:
      # Don't do any retries
      backoffLimit: 0
      template:
        spec:
          # Don't restart if an error occurs
          restartPolicy: Never
          containers:
            - name: kubernetes-connector
              image: configseeder/kubernetes-connector:1.5.1-alpine
              imagePullPolicy: Always
              envFrom:
                - configMapRef:
                    name: cs-demo-k8s-connector-config
              env:
                - name: CONNECTOR_CONFIGSEEDER_ENVIRONMENTKEY
                  value: "TEST"
                - name: CONNECTOR_STATEMANAGER_NAME
                  value: "cs-demo-k8s-connector-state-test"
                - name: CONNECTOR_CONFIGSEEDER_APIKEY
                  valueFrom:
                    secretKeyRef:
                      name: cs-demo-k8s-connector-apikey
                      key: apikey
          serviceAccountName: cs-demo-k8s-connector

  2. Start CronJob

    startCronJobTest.sh
    #!/bin/bash

kubectl apply -f cs-demo-k8s-connector-cronjob-test.yaml

    ./startCronJobTest.sh

  3. Stop / Delete CronJob

    stopCronJobTest.sh
    #!/bin/bash

kubectl delete -f cs-demo-k8s-connector-cronjob-test.yaml

    ./startCronJobTest.sh

2.4.1.1. Results

As long as no Value Assembly of with a kubernetes type is created in Configuration Group kubernetes-connector-quickstart the Kubernetes Connector won’t do anything.

  1. No secret should have been created:

    kubectl get secret -n cs-demo-application-test

  2. No error should be logged:

    kubectl logs -n cs-demo-k8s-connector cs-demo-k8s-connector-cronjob-test-<…​>

  3. No Object should be managed by Kubernetes Connector:

    kubectl get cm -n cs-demo-k8s-connector cs-demo-k8s-connector-state-test -o yaml

If a Value Assembly of for a Kubernetes type has been created or changed, re-executing the shell script is not required. The CronJob will re-execute Kubernetes Connector after the defined time and the changes will be applied automatically.

2.4.2. Start Kubernetes Connector as a Job

Starting Kubernetes Connector with a CronJob is usually done if exact timing of a configuration Change is relevant (e.g. for production level or similar environments).

  1. Create Job Template

    cs-demo-k8s-connector-job-prod.yaml
    apiVersion: batch/v1
kind: Job
metadata:
  name: cs-demo-k8s-connector-job
  namespace: cs-demo-k8s-connector
spec:
  # Don't do any retries
  backoffLimit: 0
  # Automatically clean up after 7 days
  ttlSecondsAfterFinished: 604800
  template:
    spec:
      # Don't restart if an error occurs
      restartPolicy: Never
      containers:
        - name: kubernetes-connector
          image: configseeder/kubernetes-connector:1.5.1-alpine
          imagePullPolicy: Always
          envFrom:
            - configMapRef:
                name: cs-demo-k8s-connector-config
          env:
            - name: CONNECTOR_CONFIGSEEDER_ENVIRONMENTKEY
              value: "PROD"
            - name: CONNECTOR_STATEMANAGER_NAME
              value: "k8s-connector-state-prod"
            - name: CONNECTOR_CONFIGSEEDER_APIKEY
              valueFrom:
                secretKeyRef:
                  name: cs-demo-k8s-connector-apikey
                  key: apikey
      serviceAccountName: cs-demo-k8s-connector

  2. Execute Job

    startJobProd.sh
    #!/bin/bash

timestamp=`date +%F-%H.%M.%S`
jobYaml=`sed -e "s/k8s-connector-job/k8s-connector-job-${timestamp}/g" cs-demo-k8s-connector-job-prod.yaml`

echo "$jobYaml" | kubectl apply -f -

    ./startJobProd.sh

2.4.2.1. Results

As long as no Value Assembly with a Kubernetes type is created in Configuration Group kubernetes-connector-quickstart the Kubernetes Connector won’t do anything.

  1. No secret should have been created:

    kubectl get secret -n cs-demo-application-prod

  2. No error should be logged:

    kubectl logs -n cs-demo-k8s-connector cs-demo-k8s-connector-job-<…​>

  3. No Object should be managed by Kubernetes Connector:

    kubectl get cm -n cs-demo-k8s-connector cs-demo-k8s-connector-state-prod -o yaml

If startJobProd.sh is (re)executed after a Value Assembly of Type Secret: Key/Value has been created, the given commands should show details of the created secret.

2.5. Manage a Secret containing key/value data

Create a Value Assembly of Type Secret: Key/Value in Configuration Group Kubernetes Connector Quickstart:

Create Key Value Secret in ConfigSeeder

Reexecute Job or wait until CronJob has run again, check results.

2.6. Set a label or annotation

Either modify the previously created secret or create a new one:

Secret: API Key with label and annotation

Execute the Job again or wait until CronJob has run again, check results.

3. Kubernetes Connector Configuration

3.1. Ways to configure the Connector

This section describes every available configuration option available for Kubernetes 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: DEBUG
  apiKey:
    lifetimeInDays: 2
    recreateDaysBeforeExpiration: 1
  configSeeder:
    tenantKey: "configseeder"
    environmentKey: "TEST"
    configurationGroupKeys: "kubernetes-connector-integrationtest"
    serverUrl: "https://develop.postgresql.configseeder.com"

  2. Configuration by environment variables

    Example:

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

  3. Configuration by startup parameter (highest priority)

    Example:

    kubernetes-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

3.2. Configuration Options

The Kubernetes 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.

apiKey.disabled

no

Can be set to true if the Api Key Management - Module should be disabled

apiKey.lifetimeInDays

yes

Defines how many days an API Key created by Kubernetes Connector will be valid.

This parameter can be overriden in the Secret: API Key assembly with the apikey.lifetimeInDays parameter.

apiKey.recreateDaysBeforeExpiration

yes

Defines how many days before reaching the expiration date an API Key managed by Kubernetes Connector should be replaced. The replaced API Key won’t be invalidated.

This configuration option

configMap.disabled

yes

Must be set to false if the ConfigMap Management - Module should be enabled

Defaults to connector.yaml.

configseeder.apiKey

yes

API Key used by Connector to access ConfigSeeder.

The API Key must be of Type Kubernetes 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.configurationGroupKeys

yes

Defines which configuration groups should be read by the Connector.

configseeder.context

no

Optional for filtering configuration values by context. Either context or labels can be used, not both at the same time. Context is deprecated and will be removed in favor of labels.

configseeder.connectionTimeout

no

Connection Timeout, defaults to 1000 (ms).

configseeder.dateTime

no

Optional for filtering configuration values by validFrom & validTo.

configseeder.labels

no

Optional for filtering configuration values by labels. Either context or labels can be used, not both at the same time.

Defaults to now.

configseeder.environmentKey

yes

Environment for which the Connector is running.

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.

configseeder.version

no

Optional for filtering configuration values by versionFrom & versionTo

generatorOutputDirectory

no

Defines the directory, in which json files are stored in Offline mode.

Defaults to ./generated

Directory must not exist or be empty. Otherwiese, the Kubernetes Connector will abort with an error message.

kubeconfig

no

Name (and path) of the kubernetes config file used by Kubernetes Connector to connecto to the cluster. Only used if the Kubernetes Connector runs outside of a Kubernetes Cluster.

kubernetesAccessMode

no

Defines if the kubernetes connector should access a kubernetes cluster or if the connector runs in offline mode. In offline mode, objects aren’t managed but created as json files. Valid modes are Online and Offline.

Defaults to Online

log.filename

no

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

Defaults to kubernetes-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.

secret.disabled

yes

Must be set to false if the Secret Management - Module should be enabled

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)

stateManager.name

no

Name of the ConfigMap containing the state

Defaults to kubernetes-connector-state

If more than one Kubernetes Connector is used, it must be ensured that every Connector has its own combination of namespace and name.

stateManager.namespace

no

Namespace in which the ConfigMap containing the state is created.

Defaults to configseeder.

If more than one Kubernetes Connector is used, it must be ensured that every Connector has its own combination of namespace and name.

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

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. Kubernetes Connector Modules
Module Assembly Description

AKM (Api Key Management)

Secret: API Key

Create and manage secrets which contain API Keys which grant access to ConfigSeeder.

CMM (ConfigMap Management Module)

ConfigMap: Generated

Create and manage ConfigMaps where the configuration data is generated out of the available configuration values.

ConfigMap: Key/Value

Create and manage ConfigMaps containing key / value pairs.

ConfigMap: Template

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

SMM (Secret Management Module)

Secret: ImagePull

Create and manage Image Pull Secrets

Secret: Key/Value

Create and manage Secrets containing key / value pairs.

All modules can by configured with different options. The following table shows the configuration options which are valid for all the 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 label Cluster-DEV:

  • Set assembly.active to true

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

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. Api Key Management (Module AKM)

4.2.1. Introduction

The AKM Module is responsible for creating API Keys that are stored in Kubernetes Secrets.

The required API Keys/secrets are configured with Value Assemblies of type Secret: API Key within ConfigSeeder:

Secret: API Key in ConfigSeeder

The example above would create a secret named apikey

  • in the namespace myapplication-test containing an API Key which grants access on environment TEST and configuration group Kubernetes Connector …​

  • in the namespace myapplication-prod containing an API Key which grants access on environment PROD and configuration group Kubernetes Connector …​

The created kubernetes object should look like this:

kubectl get secret -n myapplication-test apikey -o yaml

apiVersion: v1
data:
  apiKey: ZXlKc.....tYSQ==
kind: Secret
metadata:
  annotations:
    configseeder.com/managed: "true"
    configseeder.com/module: AKM
  name: name: apikey
  namespace: myapplication-test
type: Opaque

4.2.2. Usage of Configuration Values within Value Assembly

Key Mandatory Value

api-key.configuration-groups.accessible

yes

This value specifies to which configurationGroups the created API Key will have access.

api-key.lifetime-in-days

no

With this optional parameter the lifetime of the API Key can be defined. This parameter overrides the API Key lifetime configuration .

api-key.recreate-days-before-expiration

no

With this optional parameter the API Key expiration can be defined. This parameter overrides the API Key Expiration configuration .

api-key.type

yes

The type of API Key, that will be created by the connector for this assembly.

4.3. ConfigMap: Generated (Module CMM)

4.3.1. Introduction

This module is responsible for creating and managing ConfigMaps containing an entry with a value generated from available configuration values. The ConfigMaps are defined in Value Assemblies of type ConfigMap: Generated:

  • Add some configuration values to a configuration group

  • Setup the assembly

    • Point to the previously definied configuration group

    • Define the name of the data

  • The result will be a configmap

    • Having an entry with the defined name

    • Containing data generated out of the defined configuration values

ConfigMap: Generated in ConfigSeeder

With the configuration group containing the following values:

Referenced Values

Check the preview:

ConfigMap: Generated Preview

4.3.2. Usage of Configuration Values within Value Assembly

Key Mandatory Value

data.configuration-groups.source

yes

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

data.format

yes

Specifies the format of the generated output. Can be one of

  • INI

  • Json

  • Properties

  • Yaml

data.name

yes

The data generated by this assembly will be available with this name in the configmap

4.4. ConfigMap: Key/Value (Module CMM)

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:

  • 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

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.

Click on preview to see how the data will look like:

Preview of key/value data

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 calues are created by templating and normally contain whole files.

The ConfigMap is defined with an Value Assemblies of type ConfigMap: Template. The configuration values used for templating are stored in one ore more referenced confguration 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.5.3. Supported templating engines

In the current version, the Kubernetes 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 ${…​}.

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 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:
  annotations:
  name: credentials-dockerhub
  namespace: myapplication-test
data:
  .dockerconfigjson: eyJhdXRocyI6eyJyZWdpc3RyeS5n...

  • 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:

  • 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

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 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 Kubernetes 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 Kubernetes 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.add-password-to-secret

no

true/false

If set to true, the password of the keystore will be added to the Secret. The Key of the password will be keystore-password.

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.

private-keys.add-passwords-to-secret

no

true/false

If set to true, the passwords of all private key entries with an individual key-encryption-password will be added to the Secret. The key of the password will be xxx-password (where xxx is the alias of the private key entry).

4.9. Required RBAC Permissions

The modules of the Kubernetes Connector requires the following access the the Kubernetes API to be able to manage the objects configured via the different Value Assemblies:

Table 3. RBAC for Kubernetes Connector Modules
Module Kubernetes Resource Required Verbs

AKM (Api Key Management)

"secrets"

"create", "get", "patch", "update", "delete"

CMM (ConfigMap Management Module)

"configmaps"

"create", "get", "patch", "update", "delete"

SMM (Secret Management Module)

"secrets"

"create", "get", "patch", "update", "delete"

If a Kubernetes Connector should be able to manage all possible objects (Secrets and ConfigMaps), its ServiceAccount should be granted the following permissions:

kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
name: cs-demo-k8s-connector
rules:
- apiGroups: [""]
resources: ["configmaps", "secrets"]
verbs: ["create", "get", "update", "delete"]

5. Status and Metadata

5.1. Status (stored per Kubernetes Connector)

The Kubernetes Connector stores its state in a ConfigMap, normally the name is configseeder/kubernetes-connector-state.

The state contains an overview of all objects managed by the connector, the last action and information if the last action was executed successfully or details to the failure if the action has failed.

Do not modify state-information unless you know what you are doing! There should be no reason to modify the state-information and there is a big chance of destroying the state if tempered with it.

If the Kubernetes Connector is unable to read the state or is otherwise unable to interpret it, the state can be deleted. This leads to a new beginning / recreating of configuration data in the Kubernetes Cluster.

5.2. Metadata (stored per managed object)

The Kubernetes Connector stores Metadata in every managed object. The following annotations are used:

configseeder.com/managed

Boolean flag which defines if an object is managed by Kubernetes Connector, meaning if Kubernetes Connector is allowed to modify or delete the given object. If a ConfigSeeder managed object shouldn’t be modified or deleted by the Kubernetes Connector, this flag can be deleted or set to false.

configseeder.com/module

String value which defines which module of the Kubernetes-Connector is responsible for managing the file.

Manually Read or Modify Metadata

Reading Metadata:

kubectl get secrets -n <namespace> <secret> -o yaml

kind: Secret
metadata:
  annotations:
    configseeder.com/managed: "true"
    configseeder.com/module: AKM
...

Writing Metadata:

Do not modify metadata unless you know what you are doing! There should be no reason to modify the metadata other than perhaps set annotation configseeder.com/managed to false if a file should be removed from ConfigSeeder control 
kubectl edit secrets -n <namespace> <secret>