Kustomize ResourceDistribution Generator

Kruise-tools provides a series of generators and Transformers for Kruise features, which is a third party plug-in for Kustomize.

ResourceDistribution Generator

ResourceDistribution Generator Since v1.0.0 (alpha/beta) requires Kustomize version >= 4.3.0. Please refer to the Kustomize for installation.

When using Kustomize to manage applications, the generator provided with Kustomize can directly read files as data content to create Configmap or Secret, avoiding various format errors that are easy to occur during manual replication. The ResourceDistribution Generator is a third-party plug-in for Kustomize that can be used to create a ResourceDistribution by reading files as data content.

Download ResourceDistribution generator

This page provides the path to download binary files for common versions. Currently Linux, Darwin (OS X), Windows provide X86_64 and ARM64 . If you use some other system or architecture, you must download the source code and perform Go Build to build the binary

API Description

ResourceDistributionGenerator is the Exec KRM functions plugin of kusomize. It is mainly composed of resource and targets fields. After the build, it will generate resource and targets content corresponding to ResourceDistribution. The name in metadata is used to set the name of the generated resourceDistribution. The annotation config.kubernetes.io/function needs to write the path of this plugin in the file system. If a relative path is used, it needs to be relative to A kustomization file that references the configuration file.

  1. apiVersion: apps.kruise.io/v1alpha1
  2. kind: ResourceDistributionGenerator
  3. metadata:
  4.   name: rdname
  5.   annotations:
  6.     config.kubernetes.io/function: |
  7.       exec:
  8.         path: ./plugins/resourcedistributiongenerator
  9. resource:
  10.     ... ...
  11. targets:
  12.     ... ...

Resource Field

The contents of the resource field are used to generate the distributed resources. The literals, files, and envs fields are used in the same way as in Configmap or Secret Generator.

  • resourceKind: Specify the resource kind to distribute, Secret or ConfigMap;
  • resourceName: Set the name of the distribution resource, that is, the name of the Secret or ConfigMap;
  • literals: create data content using key/value pairs in the given literals;
  • files: create data content with the given file name and content;
  • envs: create data content using key/value pairs in the file;

A correctly configured resource field is as follows:

  1. apiVersion: apps.kruise.io/v1alpha1
  2. kind: ResourceDistributionGenerator
  3. metadata:
  4.   ... ... 
  5. resource:
  6.   resourceKind: ConfigMap
  7.   resourceName: cmname
  8.   files:
  9.     - file.properties
  10.   literals:
  11.     - JAVA_HOME=/opt/java/jdk
  12. targets:
  13.     ... ...

ResourceDistribution from File

ResourceDistribution Resources may be generated from files - such as a java .propertiesfile.

Example: Generate a ResourceDistribution with a data item containing the contents of a file.

The ResourceDistribution will have data values populated from the file contents. The contents of each file will appear as a single data item in the ResourceDistribution keyed by the filename.

File Input

  1. apiVersion: apps.kruise.io/v1alpha1
  2. kind: ResourceDistributionGenerator
  3. metadata:
  4.   ... ... 
  5. resource:
  6.   resourceKind: ConfigMap
  7.   resourceName: cmname
  8.   files:
  9.     - application.properties
  10. targets:
  11.     ... ...

application.properties

  1. FOO=Bar

Build Output

  1. apiVersion: apps.kruise.io/v1alpha1
  2. kind: ResourceDistribution
  3. metadata:
  4.   ... ...
  5. spec:
  6.   resource:
  7.     apiVersion: v1
  8.     data:
  9.       application.properties: |
  10.         FOO=Bar
  11.     kind: ConfigMap
  12.     metadata:
  13.       name: cmname
  14.   targets:
  15.     ... ...

ResourceDistribution from Literals

ResourceDistribution Resources may be generated from literal key-value pairs - such as JAVA_HOME=/opt/java/jdk.

  • The key/value are separated by a = sign (left side is the key)
  • The value of each literal will appear as a data item in the ResourceDistribution keyed by its key.

Example: Create a ResourceDistribution with 2 data items generated from literals.

File Input

  1. apiVersion: apps.kruise.io/v1alpha1
  2. kind: ResourceDistributionGenerator
  3. metadata:
  4.   ... ...
  5. resource:
  6.   resourceKind: ConfigMap
  7.   resourceName: cmname
  8.   literals:
  9.     - JAVA_HOME=/opt/java/jdk
  10.     - JAVA_TOOL_OPTIONS=-agentlib:hprof
  11. targets:
  12.   ... ...

Build Output

  1. apiVersion: apps.kruise.io/v1alpha1
  2. kind: ResourceDistribution
  3. metadata:
  4.   ... ...
  5. spec:
  6.   resource:
  7.     apiVersion: v1
  8.     data:
  9.       JAVA_HOME: /opt/java/jdk
  10.       JAVA_TOOL_OPTIONS: -agentlib:hprof
  11.     kind: ConfigMap
  12.     metadata:
  13.       name: cmname
  14.   targets:
  15.     ... ...

ResourceDistribution from env file

ResourceDistribution Resources may be generated from key-value pairs much the same as using the literals option but taking the key-value pairs from an environment file.

  • The key/value pairs inside of the environment file are separated by a = sign (left side is the key)
  • The value of each line will appear as a data item in the ResourceDistribution keyed by its key.

Example: Create a ResourceDistribution with 3 data items generated from an environment file.

File Input

  1. apiVersion: apps.kruise.io/v1alpha1
  2. kind: ResourceDistributionGenerator
  3. metadata:
  4.   ... ...
  5. resource:
  6.   resourceKind: ConfigMap
  7.   resourceName: cmname
  8.   envs:
  9.     - tracing.env
  10. targets:
  11.   ... ...

tracing.env

  1. ENABLE_TRACING=true
  2. SAMPLER_TYPE=probabilistic
  3. SAMPLER_PARAMETERS=0.1

Build Output

  1. apiVersion: apps.kruise.io/v1alpha1
  2. kind: ResourceDistribution
  3. metadata:
  4.   ... ...
  5. spec:
  6.   resource:
  7.     apiVersion: v1
  8.     data:
  9.       ENABLE_TRACING: "true"
  10.       SAMPLER_TYPE: "probabilistic"
  11.       SAMPLER_PARAMETERS: "0.1"
  12.     kind: ConfigMap
  13.     metadata:
  14.       name: cmname
  15.   targets:
  16.     ... ...

Targets Field

The usage of the targets field is basically the same as that of the targets field in ResourceDistribution. Note that the contents of the includedNamespaces and excludedNamespaces fields are directly the names of the namespaces.

A correctly configured targets field is as follows:

  1. apiVersion: apps.kruise.io/v1alpha1
  2. kind: ResourceDistributionGenerator
  3. metadata:
  4.   ... ... 
  5. resource:
  6.     ... ...
  7. targets:
  8.   allNamespaces: true
  9.   excludedNamespaces:
  10.     - ns-2
  11.   includedNamespaces:
  12.     - ns-1
  13.   namespaceLabelSelector:
  14.     matchLabels:
  15.       group: "test"

Options and ResourceOptions Field

The options and resourceOptions fields are used to set annotations or labels for the generated ResourceDistribution and the Resource (ie ConfigMap or Secret) in it, respectively.

A correctly configured options and resourceOptions fields is as follows:

  1. apiVersion: apps.kruise.io/v1alpha1
  2. kind: ResourceDistributionGenerator
  3. metadata:
  4.   ... ... 
  5. resource:
  6.   ... ...
  7.   resourceOptions:
  8.     annotations:
  9.       dashboard: "1"
  10.     labels:
  11.       environment: "dev"
  12. targets:
  13.     ... ...
  14. options:
  15.   annotations:
  16.     type: "slave"
  17.   labels:
  18.     version: "stable"

A Complete Use Case

  1. Create a demo directory as a workspace and enter. Place the downloaded ResourceDistributionGenerator plugin in the current directory and enter the following command to create a configuration file named rdGenerator.yaml.
  1. cat > rdGenerator.yaml <<EOF
  2. #rdGenerator.yaml
  3. apiVersion: apps.kruise.io/v1alpha1
  4. kind: ResourceDistributionGenerator
  5. metadata:
  6.   name: rdname
  7.   annotations:
  8.     config.kubernetes.io/function: |
  9.       exec:
  10.         path: ./resourcedistributiongenerator
  11. resource:
  12.   resourceKind: ConfigMap
  13.   resourceName: cmname
  14.   files:
  15.     - application.properties
  16.   literals:
  17.     - JAVA_HOME=/opt/java/jdk
  18.   resourceOptions:
  19.     annotations:
  20.       dashboard: "1"
  21. options:
  22.   labels:
  23.     app.kubernetes.io/name: "app1"
  24. targets:
  25.   includedNamespaces:
  26.     - ns-1
  27.   namespaceLabelSelector:
  28.     matchLabels:
  29.       group: "test"
  30. EOF
  1. Create the application.properties file using the following command as file input.
  1. cat > application.properties <<EOF
  2. FOO=Bar
  3. FIRST=1
  4. SECOND=2
  5. LAST=3
  6. EOF
  1. Create the kustomization file with the following command.
  1. cat > kustomization.yaml <<EOF
  2. #kustomization.yaml
  3. apiVersion: kustomize.config.k8s.io/v1beta1
  4. kind: Kustomization
  5. generators:
  6. - rdGenerator.yaml
  7. EOF
  1. Use the kustomize build --enable-alpha-plugins --enable-exec . command to build application, the effect is as follows
  1. apiVersion: apps.kruise.io/v1alpha1
  2. kind: ResourceDistribution
  3. metadata:
  4.   labels:
  5.     app.kubernetes.io/name: app1
  6.   name: rdname
  7. spec:
  8.   resource:
  9.     apiVersion: v1
  10.     data:
  11.       JAVA_HOME: /opt/java/jdk
  12.       application.properties: |
  13.         FOO=Bar
  14.         FIRST=1
  15.         SECOND=2
  16.         LAST=3
  17.     kind: ConfigMap
  18.     metadata:
  19.       annotations:
  20.         dashboard: "1"
  21.       name: cmname
  22.   targets:
  23.     includedNamespaces:
  24.       list:
  25.       - name: ns-1
  26.     namespaceLabelSelector:
  27.       matchLabels:
  28.         group: test

Use the ResourceDistribution Generator in ArgoCD

In argocd, the usage of the kustomize plugin is the same as above. In addition to that, add a build option to kustomize that allows third-party plugins. Find the configMap named argocd-cm in the kubernetes cluster and add the following to the data field kustomize.buildOptions : --enable-alpha-plugins --enable-exec to add build options for third-party plugins to the default version of kustomize. See ArgoCD for more information. You can use this sample directly in argocd.

  1. apiVersion: v1
  2. kind: ConfigMap
  3. metadata:
  4.   name: argocd-cm
  5.   namespace: argocd
  6.   labels:
  7.     app.kubernetes.io/name: argocd-cm
  8.     app.kubernetes.io/part-of: argocd
  9. data:
  10.     kustomize.buildOptions: --enable-alpha-plugins --enable-exec

The use of plug-in

Add the resourcedistributiongenerator plugin to argocd’s git repository and fill in the plugin location in the annotation config.kubernetes.io/function

  1. #rdGenerator.yaml
  2. apiVersion: apps.kruise.io/v1alpha1
  3. kind: ResourceDistributionGenerator
  4. metadata:
  5.   ...
  6.   annotations:
  7.     config.kubernetes.io/function: |
  8.       exec:
  9.         path: ./resourcedistributiongenerator

Referenced by the generator field of kustomization.yaml.

  1. #kustomization.yaml
  2. apiVersion: kustomize.config.k8s.io/v1beta1
  3. kind: Kustomization
  4. generators:
  5. - rdGenerator.yaml

After uploading the Git repository, deploy the project by using the argocd app sync myapp command or clicking the Sync button in the UI.

ContainerRecreateRequest