AddOns

Info

Add-ons are optional components of a Cluster Blueprint. Click to learn about add-ons.

Create/Update Add-On¶

A declarative approach to lifecycle management of add-ons is strongly recommended backed by the add-on payloads version controlled in your SCM/Git repository.

Use the below command to create/update an add-on in the controller based on a version controlled add-on spec that you can store in a Git repository. This enables users to develop automation for reproducible infrastructure.

./rctl apply -f addon-spec.yml

Helm Type¶

Example specification for the Helm type with the Upload files manually artifact sync option:

apiVersion: infra.k8smgmt.io/v3
kind: Addon
metadata:
  name: sample-addon
  project: sample-project
spec:
  artifact:
    artifact:
      chartPath:
        name: file://artifacts/sample-chart.tgz
      valuesPaths:
      - name: file://artifacts/values.yaml
    options:
      maxHistory: 10
      timeout: 5m0s
    type: Helm
  namespace: sample-namespace
  sharing: {}
  version: v1

Example specification for the Helm type with the Pull files from repository artifact sync option:

apiVersion: infra.k8smgmt.io/v3
kind: Addon
metadata:
  name: sample-addon
  project: sample-project
spec:
  artifact:
    artifact:
      chartPath:
        name: sample-chart.tgz
      repository: sample-repo
      revision: main
    type: Helm
  namespace: sample-namespace
  sharing:
    enabled: false
  version: v1

An example config file to create an add-on with Helm Chart and values from different repositories

apiVersion: infra.k8smgmt.io/v3
kind: AddonVersion
metadata:
  name: v1
  project: project1
  description: description for v1
spec:
  addon: demorctladdon-new4
  namespace: rctl
  template:
    type: Helm3
    repository_ref: default-bitnami
    repo_artifact_meta:
      helm:
        chartName: apache
        tag: 8.5.4
    value_repository_ref: testrepo1
    additional_reference:
      git:
        revision: main
        repoArtifactFiles:
        - name: apache-values
          relPath: apache-values.yaml
          fileType: HelmValuesFile

K8s Yaml Type¶

Example specification for the K8s YAML type with the Upload files manually artifact sync option:

apiVersion: infra.k8smgmt.io/v3
kind: Addon
metadata:
  name: sample-addon
  project: sample-project
spec:
  artifact:
    artifact:
      paths:
      - name: file://artifacts/sample-manifest.yaml
    type: Yaml
  namespace: sample-namespace
  sharing: {}
  version: v1

Example specification for the K8s YAML type with the Pull files from repository artifact sync option:

apiVersion: infra.k8smgmt.io/v3
kind: Addon
metadata:
  name: sample-addon
  project: sample-project
spec:
  artifact:
    artifact:
      paths:
      - name: sample-path/sample-manifest.yaml
      repository: sample-repo
      revision: main
    type: Yaml
  namespace: sample-namespace
  sharing: {}
  version: v1

Example specification for the K8s YAML type with the Pull files from URL artifact sync option:

apiVersion: infra.k8smgmt.io/v3
kind: Addon
metadata:
  name: sample-addon
  project: defaultproject
spec:
  artifact:
    artifact:
      url: ["https://raw.githubusercontent.com/user1/testnetworkpolicy/refs/heads/main/test/nginx-app.yaml"]
    type: Yaml
  namespace: sample-namespace
  sharing:
    enabled: false
  version: v1

Kustomize Add-Ons¶

Upload Files Manually¶

Create a Kustomize-based add-on by manually uploading a zipped or tarred folder containing the customized base files.

Below is an example YAML configuration for creating an add-on using an uploaded file:

apiVersion: infra.k8smgmt.io/v3
kind: Addon
metadata:
  name: addon-upload
  project: defaultproject
spec:
  artifact:
    artifact:
      file:
        name: file://multibases.zip
      path: dev
    type: Kustomize
  namespace: default
  sharing: {}
  version: draft-version
  versionState: draft

Pull Files From Repository¶

Below is an example YAML configuration for creating a Kustomize-based add-on that pulls files directly from a Git repository. This method allows users to deploy Kubernetes-native add-ons by referencing Kustomize manifests stored and versioned in source control.

apiVersion: infra.k8smgmt.io/v3
kind: Addon
metadata:
  name: repo-addon
  project: defaultproject
spec:
  artifact:
    artifact:
      directory: examples/multibases
      path: staging
      repository: kustomize-repo
      revision: master
    type: Kustomize
  namespace: default
  version: staging
  versionState: active

Catalog¶

Example specification using Catalog:

apiVersion: infra.k8smgmt.io/v3
kind: Addon
metadata:
  name: sample-addon
  project: defaultproject
spec:
  artifact:
    artifact:
      chartName: nginx
      chartVersion: 15.1.3
      repository: default-bitnami
      valuesPaths:
      - name: file://values.yaml
    options:
      maxHistory: 1
      timeout: 1m0s
    type: Helm
  namespace: sample-namespace
  sharing:
    enabled: false
  version: v2

List Add-ons¶

Use this command to retrieve the list of add-ons. The name of the add-ons, the type of payload and publish status are returned. An illustrative example is shown below where RCTL retrieves the list of add-ons

./rctl get addon --v3

./rctl get addon --v3
+--------------------------------------------+--------------+---------------------------+-------------------------+
| ADDON NAME                                 | TYPE         | NAMESPACE                 | ADDON VERSION           |
+--------------------------------------------+--------------+---------------------------+-------------------------+
| acr-new-addon-helm3                        | Helm         | namespace-12              | v2                      |
+--------------------------------------------+--------------+---------------------------+-------------------------+
| acr-new-addon-yaml                         | Yaml         | namespace-12              | v3                      |
+--------------------------------------------+--------------+---------------------------+-------------------------+
| addon1                                     | Yaml         | nov-ns                    |                         |
+--------------------------------------------+--------------+---------------------------+-------------------------+
| addon2                                     | Yaml         | nov-ns                    |                         |
+--------------------------------------------+--------------+---------------------------+-------------------------+
| arm-only                                   | Yaml         | new-namespce              | v1                      |
+--------------------------------------------+--------------+---------------------------+-------------------------+

List By Add-On Label¶

You can also retrieve a list of add-ons filtered by label(s)

./rctl get addon -L key1:value1,key2:

where the labels in this case are key1:value1 (a key value pair label) and key2 (a key only label).

Important

When multiple labels are specified, the list that is returned is add-ons containing all the labels specified (i.e. it is an AND operation, NOT an OR).

Bulk Association of Add-Ons With Label(s)¶

For an existing set of add-ons, you may want to tag all of them with a specific set of label(s). To accomplish this you can specify the names of all the add-ons you want to update and then call a bulk update command.

1) Specify the name of your add-ons in a file in .txt format

Example:

addon1
addon2

2) Use the following command to add the specified label(s) (-L) to all the addons specified in the text file. For example, in the command below, labels key1:value1 and key2 will be added to addon1 and addon2, the add-ons specified in my file.

./rctl update addon -t path/file-name.txt -L key1:value1,key2: --v3

Labels can be specified in the following manner:

Key Value Pair: in the format key:value (e.g. fruit:pear)
Key Only: in the format key: (e.g. fruit:)

Multiple labels are separated by a comma. In the example command above, key1:value1 is one label that is of type key:value pair and key2: is another label with type key only.

Bulk Disassociation of Add-Ons With Label(s)¶

For an existing set of add-ons, you may have tagged them with a specific label and now want to delete that label from all the add-ons at once. To accomplish this, you can use this command.

1) Specify the name of your add-ons in a file in .txt format

Example:

addon1
addon2

2) Use the following command to delete the specified label(s) (-L) from all the addons specified in the text file. For example, in the command below, labels key1:value1 and key2 will be deleted from addon1 and addon2, the add-ons specified in my file.

./rctl update addon -t path/file-name.txt -L key1:value1,key2: --delete --v3

Labels can be specified in the following manner:

Key Value Pair: in the format key:value (ex. fruit:pear)
Key Only: in the format key: (ex. fruit:)

Multiple labels are separated by a comma. In the example command above key1:value1 is one label that is of type key:value pair and key2: is another label with type key only.

Get Specific Add-on Info¶

Use this command to retrieve a specific add-on's details in the configured project.

./rctl get addon <addon-name> --v3

Below is the illustrative example for the add-on called "datadog-helm3"

./rctl get addon datadog-helm3 --v3

+--------------+------------------------------+
| VERSION NAME | CREATED AT                   |
+--------------+------------------------------+
| v1           | Mon Jun 29 04:41:11 UTC 2020 |
+--------------+------------------------------+

Or you can use below command to get more information of the add-on in json or yaml format

./rctl get addon <addon-name> -o json

./rctl get addon <addon-name> -o yaml

Example:

./rctl get addon acr-new-addon-helm3 -o yaml --v3
apiVersion: infra.k8smgmt.io/v3
kind: Addon
metadata:
  name: acr-new-addon-helm3
  project: prod-test
spec:
  artifact:
    artifact:
      chartPath:
        name: file://artifacts/acr-new-addon-helm3/nginx-9.5.8.tgz
      valuesPaths:
      - name: file://artifacts/acr-new-addon-helm3/values.yml
    options:
      maxHistory: 10
      timeout: 5m0s
    type: Helm
  namespace: namespace-12
  sharing: {}
  version: v2

Create/Update Add-on Version(s)¶

To create/update a new version of an existing add-on, use the below command. Ensure that you specify the version number for your add-on in the specification file.

./rctl apply -f <addon-spec.yml>

For example, the version for this add-on update is highlighted below.

apiVersion: infra.k8smgmt.io/v3
kind: AddonVersion
metadata:
  # version name
  name: v0.9.1
  # project name. optional
  project: defaultproject
spec:
  # addon name
  addon: vault-server
  # template for different addon types
  template:
    # type of addon
    type: helm3
    chartFile: addon/examples/vault-0.9.1.tgz
    # values file is optional
    valuesFile: addon/examples/vault-values.yaml

Delete Add-on¶

You can delete an add-on in the configured project. Note that add-ons in active use in a cluster blueprint cannot be deleted and the caller will be provided with an error message.

./rctl delete addon -f config.yaml --v3

Templating¶

Users can also create multiple add-on(s) with a set of defined configurations. The template file contains a list of objects that helps to create multiple add-on(s) from a single template.

Below is an example of add-on template file

# Generated: {{now.UTC.Format "2006-01-02T15:04:05UTC"}}
#      With: {{command_line}}
{{ $envName := environment "PWD" | basename}}
{{ $glbCtx := . }}{{ range $i, $project := .ProjectNames }}
apiVersion: infra.k8smgmt.io/v3
kind: Addon
metadata:
  name: apache
  project: {{$envName}}-{{$project}}
  labels:{{$q := $glbCtx}}{{range $k, $label := $glbCtx.Labels}}
    {{ $label.Key }}: {{ $label.Value }}{{end}}
    environment: {{$envName}}
spec:
  artifact:
    artifact:
      chartName: apache
      chartVersion: 8.0.3
      repository: default-bitnami
    options:
      maxHistory: 10
      timeout: 5m0s
    type: Helm
  namespace: common
  sharing:
    enabled: false
  version: {{$glbCtx.Version}}

---
apiVersion: infra.k8smgmt.io/v3
kind: Addon
metadata:
  name: logstash
  project: {{$envName}}-{{$project}}
  labels:{{$q := $glbCtx}}{{range $k, $label := $glbCtx.Labels}}
    {{ $label.Key }}: {{ $label.Value }}{{end}}
    environment: {{$envName}}
spec:
  artifact:
    artifact:
      catalog: default-bitnami
      chartName: logstash
      chartVersion: 5.0.18
    options:
      maxHistory: 10
      timeout: 5m0s
    type: Helm
  namespace: logstash
  sharing:
    enabled: false
  version: {{$glbCtx.Version}}

---
{{end}}

Users can create one or more add-ons with the required configuration defined in the template file. Below is an example of an add-on value file. This file helps to create add-on with version v1.0 along with the specified label key values

Labels:
  - Key: app
    Value: addon
Version: v1.0

Important

Only the objects defined in the template must be present in the value files

Use the command below to create add-on(s) with the specified configuration once the value file(s) are prepared with the necessary objects.

 ./rctl apply -t addon.tmpl -v values.yaml

where, - addon.tmpl: template file - value.yaml: value file

Refer Templating for more details on Templating flags and examples

Use the below command to share an add-on with one or more project(s)

Share with all projects

./rctl share addon addon_name --all-projects --v3

Share with specific project(s)

./rctl share addon addon_name --projects <prj1>,<prj2> --v3

Unshare AddOns¶

Use the below command to unshare an add-on with one or more project(s)

Unshare with all Projects

./rctl share addon addon_name --none --v3

Unshare with specific project(s)

./rctl share addon addon_name --unassign-projects prj1,prj2 --v3

Users can also update the below sharing parameters in the add-on config spec and run the apply command to share/unshare add-ons

sharing:
  enabled: true/false

Important

Refer here for the deprecated RCTL Commands

AddOns

Create/Update Add-On¶

Helm Type¶

K8s Yaml Type¶

Kustomize Add-Ons¶

Upload Files Manually¶

Pull Files From Repository¶

Catalog¶

List Add-ons¶

List By Add-On Label¶

Bulk Association of Add-Ons With Label(s)¶

Bulk Disassociation of Add-Ons With Label(s)¶

Get Specific Add-on Info¶

Create/Update Add-on Version(s)¶

Delete Add-on¶

Templating¶

Share Add-ons¶

Unshare AddOns¶