Add-Ons CLI

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

An illustrative example of the add-on spec YAML file is shown below. Add-On Labels can be specified as well with either just a key or key value pair.

apiVersion: infra.k8smgmt.io/v3
kind: AddonVersion
metadata:
  # version name
  name: v1.0.7
  # labels. optional
  labels:
    # example label with key value pair
    ram16: label-v16
    # example label with just a key and no value
    ram17:
  # project name. optional
  project: defaultproject
spec:
  # add-on name
  addon: kubeless
  # template for different add-on types
  template:
    # type of add-on
    type: yaml
    # path of yaml manifest
    yamlFile: ./kubeless.yaml

Helm Add-Ons from Different Repos¶

Below is 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

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

Add-Ons CLI

Create/Update Add-On¶

Helm Add-Ons from Different Repos¶

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¶